perf(hir): class captures live in the class environment, not on instances

changelog.d/11297-class-capture-environment.md

@@ -0,0 +1,14 @@
+Classes nested in a function no longer store their captured outer variables
+on every instance. A class whose definition runs once, or a class expression
+evaluated to a fresh class object (every class in a CommonJS module body),
+keeps its captures in a per-class environment read with one compare and one
+load; a second evaluation (a re-run module body) is resolved per receiver,
+so each instance still sees its own evaluation's values. TypeScript's AST
+nodes lose their 3-10 hidden `__perry_cap_*` keys (25% fewer bytes per node),
+`pos`/`end`/`kind` no longer shift with a class's capture count, and
+`ts.transpileModule` runs about 11% fewer instructions.
+
+A class expression in env mode that closes over a `for (let …)` head binding
+keeps #11250's expired-head rewrite: the refresh re-reads that evaluation's
+own capture array, which the runtime republishes into the environment slots
+only for the owning evaluation (`test_gap_11297_env_class_for_let_capture`).

crates/perry-codegen/src/codegen/helpers.rs

@@ -1368,6 +1368,8 @@ pub(super) fn register_module_globals_as_gc_roots(
         ctx.block()
             .call_void("js_gc_register_global_root", &[(I64, &addr)]);
     }
+    // Guarded class environments: hand the runtime their state and slots.
+    crate::expr::class_env::register_class_envs(ctx);
 }
 
 /// Issue #100: emit the IR that populates this module's

crates/perry-codegen/src/codegen/module_globals_emit.rs

@@ -620,6 +620,48 @@ pub(crate) fn emit_module_globals(
             static_field_globals.insert((c.name.clone(), sf.name.clone()), name);
         }
     }
+    // Class capture environments (`Expr::ClassEnvGet`/`ClassEnvSet`): one
+    // module-state global per published slot, filed under a key no static
+    // field can spell so the GC-root registration and every lowering context
+    // pick them up with the static fields. Starts `undefined`; the class
+    // evaluation (`RegisterClassCaptures` / `ClassExprFresh`) and the
+    // constructor fill it.
+    for c in &hir.classes {
+        let (slots, guarded) = crate::expr::class_env::class_env_layout(c);
+        if guarded {
+            // 0.0 = one evaluation so far; the runtime writes 1.0 on a second.
+            let name = format!(
+                "perry_classenv_{}__{}__state",
+                module_prefix,
+                sanitize_member(&c.name),
+            );
+            if external_globals_emitted.insert(name.clone()) {
+                llmod.add_module_state_global(&name, DOUBLE, "0.0");
+            }
+            static_field_globals.insert(
+                (c.name.clone(), perry_hir::cap_fields::class_env_state_key()),
+                name,
+            );
+        }
+        for index in 0..slots {
+            let name = format!(
+                "perry_classenv_{}__{}__{}",
+                module_prefix,
+                sanitize_member(&c.name),
+                index,
+            );
+            if external_globals_emitted.insert(name.clone()) {
+                llmod.add_module_state_global(&name, DOUBLE, "0x7FFC000000000001");
+            }
+            static_field_globals.insert(
+                (
+                    c.name.clone(),
+                    perry_hir::cap_fields::class_env_slot_key(index),
+                ),
+                name,
+            );
+        }
+    }
     // Register foreign static-field globals from imported classes. The source
     // module emits the defining external global (above); the consumer just
     // declares a reference and adds it to its own `static_field_globals` map