xbintsc 0.3.81 → 0.5.6

package/src/codegen/generator/module.ts

@@ -29,12 +29,18 @@ function isParameterProperty(parameter: Parameter): boolean {
   );
 }
 
+/** A readable, IR-symbol-safe suffix for a function name. */
+function symbolSuffix(name: string): string {
+  if (name.length === 0 || name.startsWith("<")) return "";
+  return name.replace(/[^A-Za-z0-9_]/g, "_").replace(/^_+/, "").slice(0, 32);
+}
+
 export interface ModuleMethods {
   run(this: Generator): string;
   emitFunction(this: Generator, fn: FunctionInfo): void;
+  emitFunctionReturn(this: Generator, value: string): void;
   emitMain(this: Generator): void;
   functionName(this: Generator, fn: FunctionInfo): string;
-  wrapAsync(this: Generator, value: string): string;
   classGlobal(this: Generator, classInfo: ClassInfo): string;
   emitClassReference(this: Generator, classInfo: ClassInfo): string;
   emitClassSetup(this: Generator, classInfo: ClassInfo): void;
@@ -77,13 +83,32 @@ export const moduleMethods: ModuleMethods = {
     ];
     const runtimeDeclarations = new Set(RUNTIME_DECLARATIONS);
     const extraDeclarations = [...this.extraDeclarations].filter((line) => !runtimeDeclarations.has(line));
-    return [...header, ...RUNTIME_DECLARATIONS, ...extraDeclarations, "", ...this.globals, "", ...this.functions, ""].join("\n");
+    return [
+      ...header,
+      ...RUNTIME_DECLARATIONS,
+      ...extraDeclarations,
+      "",
+      ...this.globals,
+      "",
+      ...this.functions,
+      "",
+      ...this.debugMetadataLines(),
+    ].join("\n");
   },
 
   // -- module level --------------------------------------------------------
 
   emitFunction(fn: FunctionInfo): void {
+    this.unsupportedCount = 0;
+    // `async function*` would need an async iterator and a promise-returning
+    // `.next()`; the generator/async lowering below would silently produce a
+    // synchronous generator instead, so reject it rather than miscompile.
+    if (fn.isAsync && fn.isGenerator) {
+      this.unsupported(fn.node, "async generator function");
+      return;
+    }
     const name = this.functionName(fn);
+    const debugSubprogram = this.debugSubprogramFor(fn);
     const state: FunctionState = {
       fn,
       buffer: [],
@@ -98,10 +123,18 @@ export const moduleMethods: ModuleMethods = {
       finallyStack: [],
       escapePointers: [],
       usesTry: false,
+      /* Generator and async bodies run on a private coroutine stack that can be
+       * suspended in the middle of a call. Their shadow frame would then sit on
+       * the shadow stack while the caller unwinds its own, so leave them out of
+       * `Error.stack` frames (nesting calls inside them are still recorded). */
+      trackFrames: !fn.isGenerator && !fn.isAsync,
+      ...(debugSubprogram ? { debugSubprogram } : {}),
     };
     this.current = state;
+    if (debugSubprogram) this.setDebugLocation(fn.node);
 
-    const header = `define i64 @${name}(i64 %this, i64 %env, i32 %argc, i64* %argv) {`;
+    const debugSuffix = debugSubprogram ? ` !dbg ${debugSubprogram}` : "";
+    const header = `define i64 @${name}(i64 %this, i64 %env, i32 %argc, i64* %argv)${debugSuffix} {`;
     this.emit(`%saved.env = alloca i64`);
     this.emit(`store i64 %env, i64* %saved.env`);
     this.emit(`%saved.this = alloca i64`);
@@ -112,6 +145,23 @@ export const moduleMethods: ModuleMethods = {
     this.emit(`%saved.argv = alloca i64*`);
     this.emit(`store i64* %argv, i64** %saved.argv`);
 
+    // Shadow-stack frame: `Error.stack` and fatal-signal dumps walk this.
+    if (state.trackFrames) {
+      const displayName = fn.isModule
+        ? "module"
+        : fn.isConstructor && fn.classInfo
+          ? `new ${this.displayNameOf(fn.classInfo.name)}`
+          : this.displayNameOf(fn.name.length > 0 ? fn.name : "anonymous");
+      const namePointer = this.internStatic(displayName);
+      /* Normalise separators like `source_filename`: the compiler may run under
+       * Node (`\`) or as a self-hosted binary (`/`), and the IR must stay
+       * byte-identical across the two. */
+      const filePointer = this.internStatic(this.fileNameOf(fn.node).split("\\").join("/"));
+      this.emit(
+        `  call void @xt_stack_push(i8* ${namePointer}, i8* ${filePointer}, i32 ${this.lineOf(fn.node)})`,
+      );
+    }
+
     // Parameters.
     const parameterNodes = (fn.node as { parameters?: Parameter[] }).parameters ?? [];
     for (let index = 0; index < fn.params.length; index++) {
@@ -207,15 +257,17 @@ export const moduleMethods: ModuleMethods = {
       this.emitStatements(this.sourceFile.statements);
     } else if (fn.node.kind === SyntaxKind.ArrowFunction && (fn.node as ArrowFunction).body.kind !== SyntaxKind.Block) {
       const value = this.emitExpression((fn.node as ArrowFunction).body as Expression);
-      this.terminate(`ret i64 ${fn.isAsync ? this.wrapAsync(value) : value}`);
+      this.emitFunctionReturn(value);
     } else {
       const body = (fn.node as { body: Block }).body;
       if (body) this.emitStatements(body.statements);
     }
 
     if (!this.current.terminated) {
-      const fallback = fn.isAsync ? this.wrapAsync(i64(XT_UNDEFINED)) : i64(XT_UNDEFINED);
-      this.terminate(`ret i64 ${fallback}`);
+      /* An `async` body returns its value plainly: the runtime's async
+       * coroutine settles the returned promise (and adopts a returned
+       * promise), so wrapping here would add a redundant promise. */
+      this.emitFunctionReturn(i64(XT_UNDEFINED));
     }
 
     const escapes = state.usesTry
@@ -229,8 +281,22 @@ export const moduleMethods: ModuleMethods = {
     const moduleName = this.functionName(this.binding.moduleFunction);
     // Module bindings and class constructors live in globals; register them as
     // GC roots before the module body runs so a collection cannot free them.
-    const roots = [...this.classGlobals.values(), ...this.moduleGlobals.values()];
+    const stringEntries = [...this.strings.values()];
+    const roots = [
+      ...this.classGlobals.values(),
+      ...this.moduleGlobals.values(),
+      ...stringEntries.map((entry) => entry.slot),
+    ];
     const rootLines = roots.map((name) => `  call void @xt_gc_add_root(i64* ${name})`);
+    // Every interned string literal is materialised once here and shared by all
+    // uses, so property names and other literals stop allocating per access.
+    const stringInit = stringEntries.flatMap((entry) => {
+      const register = `%strv.${entry.slot.replace("@.strv.", "")}`;
+      return [
+        `  ${register} = call i64 @xt_string_new(i8* ${entry.label}, i64 ${entry.length})`,
+        `  store i64 ${register}, i64* ${entry.slot}`,
+      ];
+    });
     this.functions.push(
       [
         "define i32 @main(i32 %argc, i8** %argv) {",
@@ -239,6 +305,7 @@ export const moduleMethods: ModuleMethods = {
         "  call void @xt_gc_set_stack_base(i8* %stackbase.ptr)",
         "  call void @xt_gc_init()",
         ...rootLines,
+        ...stringInit,
         "  call void @xt_gc_arm()",
         "  call void @xt_set_program_args(i32 %argc, i8** %argv)",
         `  %result = call i64 @${moduleName}(i64 ${i64(XT_UNDEFINED)}, i64 ${i64(XT_UNDEFINED)}, i32 0, i64* null)`,
@@ -252,14 +319,17 @@ export const moduleMethods: ModuleMethods = {
   },
 
   functionName(fn: FunctionInfo): string {
-    return fn.isModule ? "xt_module" : `xt_fn_${fn.id}`;
+    if (fn.isModule) return "xt_module";
+    /* Keep the original name in the symbol so native debuggers, crash
+     * backtraces and `--emit ir` are readable (`xt_fn_3_sum`). */
+    const suffix = symbolSuffix(this.displayNameOf(fn.name));
+    return suffix.length > 0 ? `xt_fn_${fn.id}_${suffix}` : `xt_fn_${fn.id}`;
   },
 
-  /** Wrap a returned value in a resolved promise (for `async` functions). */
-  wrapAsync(value: string): string {
-    const result = this.reg();
-    this.emit(`  ${result} = call i64 @xt_promise_resolve(i64 ${value})`);
-    return result;
+  /** Emit the function's return, dropping its shadow-stack frame first. */
+  emitFunctionReturn(value: string): void {
+    if (this.current.trackFrames) this.emit("  call void @xt_stack_pop()");
+    this.terminate(`ret i64 ${value}`);
   },
 
   classGlobal(classInfo: ClassInfo): string {

package/src/codegen/generator/numeric.ts

@@ -0,0 +1,158 @@
+/**
+ * Inline fast paths for numeric operators.
+ *
+ * Every JavaScript operator used to be a runtime call (`xt_add`, `xt_lt`, …).
+ * That is correct but expensive in numeric code: a `for` loop paid three calls
+ * per iteration, and clang cannot inline across the generated IR / C runtime
+ * boundary. For two unboxed doubles the operation is just a hardware
+ * instruction, so emit that inline and keep the runtime call as the cold path
+ * for every other combination (strings, BigInt, coercion, …).
+ *
+ * Doubles are stored bit-for-bit in `xt_value`, so the tag check is an integer
+ * mask and the operation is `bitcast` → `fadd`/`fcmp` → `bitcast`.
+ */
+
+import { i64, XT_FALSE, XT_NUMBER_MASK, XT_TRUE } from "../values.js";
+import type { Generator } from "./generator.js";
+
+export interface NumericMethods {
+  /**
+   * Emit `left <operator> right`, using an inline double fast path when both
+   * operands turn out to be numbers and {@link allowFastPath} is set.
+   */
+  emitBinaryOperation(
+    this: Generator,
+    left: string,
+    right: string,
+    operator: string,
+    runtime: string,
+    allowFastPath?: boolean,
+  ): string;
+  emitNumericBinary(this: Generator, left: string, right: string, instruction: string, runtime: string): string;
+  emitNumericComparison(this: Generator, left: string, right: string, predicate: string, runtime: string): string;
+  /** Emit an i1 SSA value that is true when `value` is an unboxed double. */
+  isNumberValue(this: Generator, value: string): string;
+}
+
+/** Canonical quiet NaN; the runtime uses the same pattern in `xt_from_double`. */
+const CANONICAL_NAN = 0x7ff8000000000000n;
+
+const NUMERIC_ARITHMETIC: Record<string, string | undefined> = {
+  "+": "fadd",
+  "-": "fsub",
+  "*": "fmul",
+  "/": "fdiv",
+  "%": "frem",
+};
+
+const NUMERIC_COMPARISON: Record<string, string | undefined> = {
+  "<": "olt",
+  "<=": "ole",
+  ">": "ogt",
+  ">=": "oge",
+  "==": "oeq",
+  "!=": "une",
+  "===": "oeq",
+  "!==": "une",
+};
+
+export const numericMethods: NumericMethods = {
+  emitBinaryOperation(left, right, operator, runtime, allowFastPath = true) {
+    if (allowFastPath) {
+      const instruction = NUMERIC_ARITHMETIC[operator];
+      if (instruction) return this.emitNumericBinary(left, right, instruction, runtime);
+      const predicate = NUMERIC_COMPARISON[operator];
+      if (predicate) return this.emitNumericComparison(left, right, predicate, runtime);
+    }
+    const result = this.reg();
+    this.emit(`  ${result} = call i64 @${runtime}(i64 ${left}, i64 ${right})`);
+    return result;
+  },
+
+  /** Emit an i1 SSA value that is true when `value` is an unboxed double. */
+  isNumberValue(value: string): string {
+    const masked = this.reg();
+    this.emit(`  ${masked} = and i64 ${value}, ${i64(XT_NUMBER_MASK)}`);
+    const result = this.reg();
+    this.emit(`  ${result} = icmp ne i64 ${masked}, ${i64(XT_NUMBER_MASK)}`);
+    return result;
+  },
+
+  emitNumericBinary(left, right, instruction, runtime) {
+    const result = this.alloca();
+    const leftIsNumber = this.isNumberValue(left);
+    const rightIsNumber = this.isNumberValue(right);
+    const bothNumbers = this.reg();
+    this.emit(`  ${bothNumbers} = and i1 ${leftIsNumber}, ${rightIsNumber}`);
+    const fast = this.label("num.fast");
+    const slow = this.label("num.slow");
+    const end = this.label("num.end");
+    this.terminate(`br i1 ${bothNumbers}, label %${fast}, label %${slow}`);
+
+    this.startBlock(fast);
+    const leftDouble = this.reg();
+    this.emit(`  ${leftDouble} = bitcast i64 ${left} to double`);
+    const rightDouble = this.reg();
+    this.emit(`  ${rightDouble} = bitcast i64 ${right} to double`);
+    const computed = this.reg();
+    this.emit(`  ${computed} = ${instruction} double ${leftDouble}, ${rightDouble}`);
+    // Hardware NaNs carry many payloads; the value model only reserves the
+    // canonical quiet NaN, and `-NaN` would otherwise collide with XT_UNDEFINED.
+    const bits = this.reg();
+    this.emit(`  ${bits} = bitcast double ${computed} to i64`);
+    const unordered = this.reg();
+    this.emit(`  ${unordered} = fcmp uno double ${computed}, ${computed}`);
+    const canonical = this.reg();
+    this.emit(`  ${canonical} = select i1 ${unordered}, i64 ${i64(CANONICAL_NAN)}, i64 ${bits}`);
+    this.emit(`  store i64 ${canonical}, i64* ${result}`);
+    this.terminate(`br label %${end}`);
+
+    this.startBlock(slow);
+    const called = this.reg();
+    this.emit(`  ${called} = call i64 @${runtime}(i64 ${left}, i64 ${right})`);
+    this.emit(`  store i64 ${called}, i64* ${result}`);
+    this.terminate(`br label %${end}`);
+
+    this.startBlock(end);
+    const value = this.reg();
+    this.emit(`  ${value} = load i64, i64* ${result}`);
+    return value;
+  },
+
+  emitNumericComparison(left, right, predicate, runtime) {
+    const result = this.alloca();
+    const leftIsNumber = this.isNumberValue(left);
+    const rightIsNumber = this.isNumberValue(right);
+    const bothNumbers = this.reg();
+    this.emit(`  ${bothNumbers} = and i1 ${leftIsNumber}, ${rightIsNumber}`);
+    const fast = this.label("cmp.fast");
+    const slow = this.label("cmp.slow");
+    const end = this.label("cmp.end");
+    this.terminate(`br i1 ${bothNumbers}, label %${fast}, label %${slow}`);
+
+    this.startBlock(fast);
+    const leftDouble = this.reg();
+    this.emit(`  ${leftDouble} = bitcast i64 ${left} to double`);
+    const rightDouble = this.reg();
+    this.emit(`  ${rightDouble} = bitcast i64 ${right} to double`);
+    // Ordered comparisons are false for NaN and unordered `!=` is true, which
+    // is exactly ECMAScript's behaviour for two numbers.
+    const compared = this.reg();
+    this.emit(`  ${compared} = fcmp ${predicate} double ${leftDouble}, ${rightDouble}`);
+    const value = this.reg();
+    this.emit(`  ${value} = select i1 ${compared}, i64 ${i64(XT_TRUE)}, i64 ${i64(XT_FALSE)}`);
+    this.emit(`  store i64 ${value}, i64* ${result}`);
+    this.terminate(`br label %${end}`);
+
+    this.startBlock(slow);
+    const called = this.reg();
+    this.emit(`  ${called} = call i64 @${runtime}(i64 ${left}, i64 ${right})`);
+    this.emit(`  store i64 ${called}, i64* ${result}`);
+    this.terminate(`br label %${end}`);
+
+    this.startBlock(end);
+    const merged = this.reg();
+    this.emit(`  ${merged} = load i64, i64* ${result}`);
+    return merged;
+  },
+};

package/src/codegen/generator/state.ts

@@ -50,6 +50,16 @@ export interface FunctionState {
   thisPtr?: string;
   /** Set when the function contains a `try`, forcing locals to live in memory. */
   usesTry: boolean;
+  /**
+   * True when the function pushes/pops a shadow-stack frame. Generator bodies
+   * are excluded: they switch stacks and can be suspended, so a global shadow
+   * stack would attribute their frames to the wrong caller.
+   */
+  trackFrames: boolean;
+  /** `!DISubprogram` for this function when DWARF emission is enabled. */
+  debugSubprogram?: string;
+  /** Current `!DILocation` attached to every emitted instruction. */
+  debugLocation?: string;
 }
 
 export interface CodegenResult {
@@ -74,6 +84,13 @@ export interface CodegenOptions {
    * defaults to the running process; it is overridable for tests.
    */
   readonly target?: { readonly platform: string; readonly arch: string };
+  /**
+   * Emit LLVM debug metadata (`!DICompileUnit`, `!DISubprogram`,
+   * `!DILocation`) so `clang -g` produces DWARF/CodeView for the generated
+   * program. Off by default: the metadata is large and only useful when
+   * debugging; `xbintsc build --debug` turns it on.
+   */
+  readonly debug?: boolean;
 }
 
 export const RUNTIME_DECLARATIONS: readonly string[] = [
@@ -87,12 +104,17 @@ export const RUNTIME_DECLARATIONS: readonly string[] = [
   "declare i64 @xt_closure_new(i8*, i32, i64*)",
   "declare i64 @xt_function_set_metadata(i64, i64, i32)",
   "declare i64 @xt_function_set_generator(i64)",
+  "declare i64 @xt_function_set_async(i64)",
   "declare i64 @xt_closure_call(i64, i32, i64*)",
   "declare i64 @xt_closure_env(i64, i32)",
   "declare i64 @xt_call_with_this(i64, i64, i32, i64*)",
   "declare i64 @xt_this()",
   "declare i64 @xt_new(i64, i32, i64*)",
   "declare i64 @xt_instance_of(i64, i64)",
+  "declare i64 @xt_instance_of_builtin(i64, i32)",
+  "declare i64 @xt_builtin_constructor(i64)",
+  "declare i64 @xt_array_ctor(i32, i64*)",
+  "declare i64 @xt_object_ctor(i32, i64*)",
   "declare i64 @xt_function_set_prototype(i64, i64)",
   "declare i64 @xt_function_get_prototype(i64)",
   "declare i64 @xt_object_new_with_proto(i64)",
@@ -225,6 +247,7 @@ export const RUNTIME_DECLARATIONS: readonly string[] = [
   "declare i64 @xt_object_entries(i64)",
   "declare i64 @xt_object_assign(i32, i64*)",
   "declare i64 @xt_object_spread(i64, i64)",
+  "declare i64 @xt_object_rest(i64, i32, i64*)",
   "declare i64 @xt_call_method(i64, i64, i32, i64*)",
   "declare i64 @xt_math_call(i64, i32, i64*)",
   "declare i64 @xt_parse_int(i32, i64*)",
@@ -298,6 +321,9 @@ export const RUNTIME_DECLARATIONS: readonly string[] = [
   "declare i8* @xt_try_enter()",
   "declare i64 @xt_try_exception(i8*)",
   "declare void @xt_try_leave(i8*)",
+  "declare void @xt_stack_push(i8*, i8*, i32)",
+  "declare void @xt_stack_pop()",
+  "declare void @xt_stack_set_line(i32)",
   "declare void @xt_console_log(i32, i64*)",
   "declare void @xt_console_info(i32, i64*)",
   "declare void @xt_console_warn(i32, i64*)",

package/src/codegen/generator/statements/control-flow.ts

@@ -250,12 +250,11 @@ export const controlFlowStatementMethods: ControlFlowStatementMethods = {
   },
 
   emitReturn(statement: ReturnStatement): void {
-    let value = statement.expression ? this.emitExpression(statement.expression) : i64(XT_UNDEFINED);
-    if (this.current.fn.isAsync) value = this.wrapAsync(value);
+    const value = statement.expression ? this.emitExpression(statement.expression) : i64(XT_UNDEFINED);
     this.runFinallysBeforeExit(0);
     if (this.current.terminated) return;
     this.popTryFramesTo(0);
-    this.terminate(`ret i64 ${value}`);
+    this.emitFunctionReturn(value);
   },
 
   /** Emit `xt_try_leave` for every active frame above `depth` (innermost first). */

package/src/codegen/generator/statements/dispatch.ts

@@ -41,6 +41,9 @@ export const statementDispatchMethods: StatementDispatchMethods = {
   },
 
   emitStatement(statement: Statement): void {
+    /* Every instruction emitted while lowering this statement (including
+     * nested expressions) points at its source position when DWARF is on. */
+    this.setDebugLocation(statement);
     switch (statement.kind) {
       case SyntaxKind.ExpressionStatement:
         this.emitExpression((statement as { expression: Expression }).expression);

package/src/codegen/generator/statements/variables.ts

@@ -87,13 +87,19 @@ export const variableStatementMethods: VariableStatementMethods = {
       return;
     }
     const pattern = name as ObjectBindingPattern;
+    /* Keys named by the pattern are excluded from `...rest`. */
+    const excludedKeys: string[] = [];
     for (const element of pattern.elements) {
-      const key = element.propertyName ?? (element.name.kind === SyntaxKind.Identifier ? element.name : undefined);
       if (element.dotDotDotToken) {
-        this.unsupported(element, "object rest destructuring");
+        const rest = this.reg();
+        const keys = this.emitValueArguments(excludedKeys);
+        this.emit(`  ${rest} = call i64 @xt_object_rest(i64 ${value}, i32 ${keys.argc}, i64* ${keys.ptr})`);
+        this.emitBindingPattern(element.name, rest);
         continue;
       }
+      const key = element.propertyName ?? (element.name.kind === SyntaxKind.Identifier ? element.name : undefined);
       const keyValue = this.stringValue(key ? propertyNameText(key) : "undefined");
+      excludedKeys.push(keyValue);
       let elementValue = this.reg();
       this.emit(`  ${elementValue} = call i64 @xt_get(i64 ${value}, i64 ${keyValue})`);
       if (element.initializer) elementValue = this.emitBindingDefault(elementValue, element.initializer);

package/src/codegen/generator/tables.ts

@@ -22,6 +22,32 @@ export function requiresSetjmpex(platform: string, arch: string): boolean {
   return platform === "win32" && arch === "arm64";
 }
 
+/**
+ * Built-in constructors usable on the right of `instanceof`, mapped to the id
+ * `xt_instance_of_builtin` expects. Keep in sync with the `XT_INSTANCE_*` enum
+ * in `runtime/xt_builtins.c`; the typed-array ids follow the runtime's
+ * `XT_TA_*` order (Uint8Array first).
+ */
+export const BUILTIN_INSTANCEOF: Readonly<Record<string, number>> = {
+  Array: 0,
+  Object: 1,
+  Function: 2,
+  Map: 3,
+  Set: 4,
+  Date: 5,
+  RegExp: 6,
+  Promise: 7,
+  Uint8Array: 16,
+  Int8Array: 17,
+  Uint8ClampedArray: 18,
+  Uint16Array: 19,
+  Int16Array: 20,
+  Uint32Array: 21,
+  Int32Array: 22,
+  Float32Array: 23,
+  Float64Array: 24,
+};
+
 export const BINARY_RUNTIME: Record<string, string | undefined> = {
   [BinaryOperator.Add]: "xt_add",
   [BinaryOperator.Subtract]: "xt_sub",
@@ -227,6 +253,23 @@ export const NAMESPACE_STATICS: Record<string, string> = {
   ...TYPED_ARRAY_STATICS,
 };
 
+/** The well-known symbols exposed as properties of the `Symbol` namespace. */
+export const SYMBOL_WELL_KNOWN = new Set<string>([
+  "asyncIterator",
+  "hasInstance",
+  "isConcatSpreadable",
+  "iterator",
+  "match",
+  "matchAll",
+  "replace",
+  "search",
+  "species",
+  "split",
+  "toPrimitive",
+  "toStringTag",
+  "unscopables",
+]);
+
 /** Namespace identifiers whose property access maps to a runtime getter. */
 export const NAMESPACE_PROPERTIES: Record<string, string> = {
   process: "xt_process_get",
@@ -236,7 +279,7 @@ export const NAMESPACE_PROPERTIES: Record<string, string> = {
 
 /** Global constructors called as `new X(...)` (all have signature `(i32, i64*)`). */
 export const CTOR_FUNCTIONS: Record<string, string> = {
-  Array: "xt_array_new",
+  Array: "xt_array_ctor",
   Map: "xt_map_ctor",
   Set: "xt_set_ctor",
   Date: "xt_date_ctor",
@@ -255,6 +298,30 @@ export const CTOR_FUNCTIONS: Record<string, string> = {
   ...TYPED_ARRAY_CTORS,
 };
 
+/**
+ * Built-in constructors that are also ordinary first-class values. The codegen
+ * lowers a bare reference (`const A = Array`) to `xt_builtin_constructor`, which
+ * returns a cached function with `name`/`length`, a `prototype` and the
+ * constructor's statics (`A.isArray`, `A.from`, ...).
+ */
+export const FIRST_CLASS_CONSTRUCTORS = new Set<string>([
+  "Array",
+  "Object",
+  "Function",
+  "Map",
+  "Set",
+  "Date",
+  "RegExp",
+  "Promise",
+  ...Object.keys(TYPED_ARRAYS),
+  ...Object.keys(ERROR_CONSTRUCTORS),
+  "Number",
+  "String",
+  "Boolean",
+  "BigInt",
+  "Symbol",
+]);
+
 export const BUILTIN_METHODS = new Set<string>([
   "push", "pop", "shift", "unshift", "join", "slice", "indexOf", "includes", "map", "forEach", "filter",
   "reduce", "concat", "reverse", "charAt", "charCodeAt", "substring", "substr", "split", "toUpperCase",
@@ -368,7 +435,7 @@ export function utf8Bytes(text: string): number[] {
   if (!hasMultiByteUnit(text)) {
     const bytes: number[] = [];
     for (let index = 0; index < text.length; index++) bytes.push(text.charCodeAt(index) & 0xff);
-    return bytes;
+    return combineSurrogateBytes(bytes);
   }
   const bytes: number[] = [];
   const length = text.length;
@@ -394,6 +461,47 @@ function hasMultiByteUnit(text: string): boolean {
   return false;
 }
 
+/**
+ * Join adjacent WTF-8 surrogate halves into one four-byte sequence.
+ *
+ * A literal such as `"\uD83D\uDE00"` scans to two separate three-byte
+ * escapes. JavaScript's string value is one code point, so the emitted bytes
+ * must be the four-byte UTF-8 form (and a lone escape must stay three bytes,
+ * which is why this runs after scanning rather than per escape).
+ */
+function combineSurrogateBytes(bytes: number[]): number[] {
+  const out: number[] = [];
+  for (let index = 0; index < bytes.length; index++) {
+    if (
+      index + 5 < bytes.length &&
+      bytes[index] === 0xed &&
+      bytes[index + 1]! >= 0xa0 &&
+      bytes[index + 1]! <= 0xaf &&
+      bytes[index + 2]! >= 0x80 &&
+      bytes[index + 2]! <= 0xbf &&
+      bytes[index + 3] === 0xed &&
+      bytes[index + 4]! >= 0xb0 &&
+      bytes[index + 4]! <= 0xbf &&
+      bytes[index + 5]! >= 0x80 &&
+      bytes[index + 5]! <= 0xbf
+    ) {
+      const high = ((bytes[index]! & 0x0f) << 12) | ((bytes[index + 1]! & 0x3f) << 6) | (bytes[index + 2]! & 0x3f);
+      const low = ((bytes[index + 3]! & 0x0f) << 12) | ((bytes[index + 4]! & 0x3f) << 6) | (bytes[index + 5]! & 0x3f);
+      const code = 0x10000 + ((high - 0xd800) << 10) + (low - 0xdc00);
+      out.push(
+        0xf0 | (code >> 18),
+        0x80 | ((code >> 12) & 0x3f),
+        0x80 | ((code >> 6) & 0x3f),
+        0x80 | (code & 0x3f),
+      );
+      index += 5;
+      continue;
+    }
+    out.push(bytes[index]!);
+  }
+  return out;
+}
+
 export function escapeBytes(bytes: readonly number[]): string {
   return bytes
     .map((byte) => {