@geastack/compiler 1.0.15 → 1.0.17

package/dist/targets/cpp/translation-unit.js

@@ -17,7 +17,7 @@ import { createCppDocumentBuilder, emptyCppFacts, render, spliceRendered } from
 import { beginUnionAliasing, endUnionAliasing } from './types.js';
 import { cppConstructedThunkName, cppConstructThunkName, cppFormalName, cppReceiverName, cppThunkName, emitBody, isCppEmitBlockedError } from './emit.js';
 import { cppCaptureFieldName, cppCaptureReceiverFieldName, cppEnvironmentLocalName, cppEnvironmentParamName, cppEnvironmentSlotName, cppEnvironmentStructName, effectiveAbiOf, symbolKeyDefinitions, templateObjectDefinitions } from './emit-context.js';
-import { censusClassStaticFieldStorage, censusLazyArrowFields, classBoxable, cppFieldInitializerStatements, publishBoxableClasses, publishClassStaticFieldStorage, publishLazyArrowFieldPlans } from './class-layout.js';
+import { censusClassStaticFieldStorage, censusConstantFieldInitializers, censusLazyArrowFields, classBoxable, cppFieldInitializerStatements, publishBoxableClasses, publishClassStaticFieldStorage, publishConstantFieldInitializers, publishLazyArrowFieldPlans } from './class-layout.js';
 import { classStaticFieldStorageRows, cppRecordDeclarations, cppStructNameOf, declaredFieldRepresentationOf, declaredRecordFieldOf, recordAccessorBodiesOf, representationNamesMintedStruct, withUnreadParametersUnnamed } from './records.js';
 import { prototypeReadHooks, virtualMethodEmission, virtualMethodFamiliesOf } from './virtual-methods.js';
 import { virtualDispatchVerdictOf } from '../../projection/dispatch.js';
@@ -27,7 +27,7 @@ import { classesConstructedUnobservably, functionsIgnoringTheirReceiver } from '
 import { renderJsonStructDeclarations } from './emit-json.js';
 import { alignedValueText } from './emit-narrowing.js';
 import { recordLayoutPolicyOf } from '../../projection/fields.js';
-import { cppAbiParameterType, cppAbiType, cppStringLiteral, cppStringViewLiteral, cppBodyName, cppCallableDeclarationTagName, cppCommonJsModuleName, cppCommonJsRecordName, cppNarrowedIntegerType, cppRefcountedReceiver, cppBoxedType, cppClassName, cppConstructName, cppGlobalName, cppInitializeName, cppRecordFieldName, cppRecordStructName, cppResultTypeOf, cppTypeOf, sanitizeForCppIdentifier } from './types.js';
+import { cppAbiParameterType, cppAbiType, cppStringLiteral, cppBodyName, cppCallableDeclarationTagName, cppCommonJsModuleName, cppCommonJsRecordName, cppNarrowedIntegerType, cppRefcountedReceiver, cppBoxedType, cppClassName, cppConstructName, cppGlobalName, cppInitializeName, cppRecordFieldName, cppRecordStructName, cppResultTypeOf, cppTypeOf, sanitizeForCppIdentifier } from './types.js';
 import { buildHostMethodAliasIndex } from './host/host-method-aliases.js';
 import { cppRecursiveContainerDeclarations, cppRecursiveContainerTraceEdges } from './recursive-containers.js';
 /**
@@ -562,7 +562,7 @@ const signatureOf = (body, captures, narrowed = new Set(), narrowedResult = fals
     const formals = bodyFormalsOf(body.sourceOwner, effectiveAbi, admission, narrowed, borrowsReceiver(body), borrowed);
     return `${result} ${name}(${formals.join(', ')})`;
 };
-const thunkOf = (body, captures, narrowed, narrowedResult, linkage, preserveFunctionFacts) => {
+const thunkOf = (body, captures, narrowed, narrowedResult, linkage) => {
     if (!body.abi)
         return null;
     const abi = body.abi;
@@ -601,17 +601,11 @@ const thunkOf = (body, captures, narrowed, narrowedResult, linkage, preserveFunc
     const construct = constructThunkOf(body, abi, hasEnvironment, linkage);
     return {
         prototype: [`${signature};`, ...(construct === null ? [] : [construct.prototype])].join('\n'),
-        definition: [
-            `${signature} { ${statement} }`,
-            ...(!preserveFunctionFacts || body.functionSource === undefined
-                ? []
-                : [
-                    `[[maybe_unused]] static const bool ${cppThunkName(body.sourceOwner)}_source = ` +
-                        `gea::CallableObject<${cppAbiType(abi)}>::registerSource<&${cppThunkName(body.sourceOwner)}>(` +
-                        `${cppStringViewLiteral(body.functionName ?? '')}, ${body.functionLength ?? 0}, ${cppStringViewLiteral(body.functionSource)});`
-                ]),
-            ...(construct === null ? [] : [construct.definition])
-        ].join('\n')
+        // No `registerSource` beside the thunk any more: the function's
+        // `name`/`length`/source text register at the sites that mint a function
+        // object from it (`emit-context.ts`'s `cppThunkEntryText`), so a function
+        // nothing reaches is not pinned into the binary by its own registration.
+        definition: [`${signature} { ${statement} }`, ...(construct === null ? [] : [construct.definition])].join('\n')
     };
 };
 /**
@@ -1395,6 +1389,13 @@ export const renderTranslationUnit = (input) => {
     // actual reader in this same function -- `cppRecordDeclarations` itself --
     // so it cannot be published after, the way that one is.
     publishLazyArrowFieldPlans(input.classes, censusLazyArrowFields(input.bodies, input.classes, captures));
+    // Published alongside it, and read by the same constructor emission: which
+    // field initializers are a single constant, so a store that writes what
+    // value-initialization already wrote can be dropped. Passed the plugin's own
+    // `reactive.fields` rather than the settled `celledFields`, which
+    // `cppRecordDeclarations` has not produced yet -- see the census's own
+    // comment for why that is the right superset to refuse.
+    publishConstantFieldInitializers(input.classes, censusConstantFieldInitializers(input.bodies, input.classes, input.hosts.reactive.fields));
     const structs = cppRecordDeclarations(input.plan, deriver, input.classes, input.hosts.reactive, boundRecordFields, structMembers, narrowedStorage.slots, input.wellKnownSymbols, perFile, input.reflection, emissionRepresentations, input.physicalClasses ?? input.classes, (body) => captures.of(body).kind === 'ok', fixedFieldStateConstant, singleEvaluationClasses);
     const recursiveContainers = cppRecursiveContainerDeclarations(input.plan, emissionRepresentations);
     // Real storage for every `ClassName.KEY = value` site the whole program
@@ -1632,9 +1633,24 @@ export const renderTranslationUnit = (input) => {
             }
         return false;
     });
+    // The facts every mint site of a function registers (`cppThunkEntryText`),
+    // spelled once per body here rather than looked up through the thunk. Empty
+    // when the census above found no reader, so `&thunk` alone is stored.
+    const functionFacts = new Map();
+    if (preserveFunctionFacts)
+        for (const body of input.bodies) {
+            if (isRegionId(body.sourceOwner) || body.abi === null || body.functionSource === undefined)
+                continue;
+            functionFacts.set(body.sourceOwner, {
+                abiType: cppAbiType(body.abi),
+                name: body.functionName ?? '',
+                length: body.functionLength ?? 0,
+                source: body.functionSource
+            });
+        }
     const thunks = new Map();
     for (const body of input.bodies) {
-        const thunk = thunkOf(body, captures, formalsNarrowedIn(body.sourceOwner), resultNarrowedIn(body.sourceOwner), linkage, preserveFunctionFacts);
+        const thunk = thunkOf(body, captures, formalsNarrowedIn(body.sourceOwner), resultNarrowedIn(body.sourceOwner), linkage);
         if (thunk)
             thunks.set(body, thunk);
     }
@@ -1706,7 +1722,7 @@ export const renderTranslationUnit = (input) => {
             continue;
         }
         try {
-            const sections = emitBody(body, input.placements, input.classes, hosts, deriver, input.wellKnownSymbols, captures, symbolKeys, templateObjects, directCallables, virtuals.dispatched, narrowedStorage.factsOf(body.sourceOwner), formalsNarrowedIn(body.sourceOwner), repeatedConstructors, dyingArguments, instantiation, (callable) => abiByBody.get(String(callable)) ?? null, hostMethodAliases, callableMemberCandidates, borrowableMemberBodies, stableBorrowEntries, printerDrift, input.conversions, selectionHelpers, callableIdentityDemand, nativeIntegrityRestricted, fixedFieldStateConstant);
+            const sections = emitBody(body, input.placements, input.classes, hosts, deriver, input.wellKnownSymbols, captures, symbolKeys, templateObjects, directCallables, virtuals.dispatched, narrowedStorage.factsOf(body.sourceOwner), formalsNarrowedIn(body.sourceOwner), repeatedConstructors, dyingArguments, instantiation, (callable) => abiByBody.get(String(callable)) ?? null, functionFacts, hostMethodAliases, callableMemberCandidates, borrowableMemberBodies, stableBorrowEntries, printerDrift, input.conversions, selectionHelpers, callableIdentityDemand, nativeIntegrityRestricted, fixedFieldStateConstant);
             const stableEntry = stableBorrowEntries.get(cppBodyName(body.sourceOwner));
             const commonJsScope = commonJsOwner === null || commonJsOwner.nativeRecord
                 ? []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geastack/compiler",
-  "version": "1.0.15",
+  "version": "1.0.17",
   "description": "The geastack TypeScript-to-C++ compiler: one semantic spine, no source-shaped authority, no boxing of statically typed values.",
   "license": "Apache-2.0",
   "repository": {
@@ -67,7 +67,7 @@
     "check:contracts": "npm run build && node test/contracts.mjs"
   },
   "dependencies": {
-    "@geastack/node-compat": "^1.0.7",
+    "@geastack/node-compat": "^1.0.12",
     "typescript": "^5.9.3"
   },
   "devDependencies": {
@@ -77,9 +77,9 @@
     "prettier": "^3.8.3"
   },
   "peerDependencies": {
-    "@geastack/apple": ">=0.1.0",
-    "@geastack/geatsc-plugin-apple-native": ">=0.1.0",
-    "@geastack/geatsc-plugin-gea": ">=0.1.0"
+    "@geastack/apple": ">=0.2.8",
+    "@geastack/geatsc-plugin-apple-native": ">=0.1.3",
+    "@geastack/geatsc-plugin-gea": ">=0.1.6"
   },
   "peerDependenciesMeta": {
     "@geastack/apple": {

package/src/targets/cpp/runtime/gea_dynamic_proxy.h

@@ -89,8 +89,46 @@ inline Value ordinaryToPrimitive(const Value& value, ToPrimitiveHint hint) {
   host::throwRuntimeError("TypeError", "Cannot convert object to primitive value");
 }
 
+/**
+ * ToPrimitive of a boxed typed array, which is always its ToString.
+ *
+ * A typed array is a native carrier with no dynamic property surface: it has no
+ * `@@toPrimitive`, its `valueOf` is Object's and returns the object, and
+ * nothing a program can do installs either on it. So 7.1.1 lands on
+ * `%TypedArray%.prototype.toString` for every hint, and that is knowable from
+ * the payload type alone -- without it the generic path below asks the box for
+ * `@@toPrimitive` and the box, having no field table, refuses by name. A view
+ * whose host brand states its own ToString (Node's Buffer) answers with that.
+ */
+template <typename Element>
+inline bool boxedTypedArrayToStringAs(const Value& value, std::string& out) {
+  using Handle = gea::Ref<TypedArray<Element>>;
+  if (value.payloadType() != detail::payloadTypeTagFor<Handle>()) return false;
+  const Handle& view = value.as<Handle>();
+  if constexpr (std::is_same_v<Element, std::uint8_t>) {
+    if (view) {
+      if (const detail::HostViewToString render = detail::hostViewToStringFor(view->hostBrand())) {
+        out = render(*view);
+        return true;
+      }
+    }
+  }
+  out = runtime::array::join(view);
+  return true;
+}
+
+inline bool boxedTypedArrayToString(const Value& value, std::string& out) {
+  if (value.tag() != Value::Tag::Object || value.isProxy()) return false;
+  return boxedTypedArrayToStringAs<std::uint8_t>(value, out) || boxedTypedArrayToStringAs<std::int8_t>(value, out) ||
+         boxedTypedArrayToStringAs<ClampedUint8>(value, out) || boxedTypedArrayToStringAs<std::int16_t>(value, out) ||
+         boxedTypedArrayToStringAs<std::uint16_t>(value, out) || boxedTypedArrayToStringAs<std::int32_t>(value, out) ||
+         boxedTypedArrayToStringAs<std::uint32_t>(value, out) || boxedTypedArrayToStringAs<float>(value, out) ||
+         boxedTypedArrayToStringAs<double>(value, out);
+}
+
 inline Value dynamicToPrimitive(const Value& value, ToPrimitiveHint hint = ToPrimitiveHint::Default) {
   if (!isObjectValue(value)) return value;
+  if (std::string text; boxedTypedArrayToString(value, text)) return Value::box(Value::Tag::String, std::move(text));
   const Value exotic = value.getProperty(PropertyKey::symbol(wellKnownSymbol(detail::WellKnownSymbol::ToPrimitive)));
   if (exotic.tag() != Value::Tag::Undefined && exotic.tag() != Value::Tag::Null) {
     if (exotic.tag() != Value::Tag::Function) host::throwRuntimeError("TypeError", "@@toPrimitive is not callable");

package/src/targets/cpp/runtime/gea_runtime.h

@@ -3170,6 +3170,25 @@ struct CallableObject<Result(Arguments...)> {
     return true;
   }
 
+  // The same registration, performed where a function OBJECT is minted from
+  // the thunk rather than by a namespace-scope initializer beside the thunk.
+  // A namespace-scope registration is a static initializer that takes the
+  // thunk's address, and a static initializer with a side effect is a GC
+  // root: neither `--gc-sections` nor LTO may drop it, so it kept every
+  // emitted function -- and its source text -- in the binary whether or not
+  // anything reached it. One `EventEmitter` boxing a listener turned the
+  // registry on for a whole program, and that pinned all 384 functions of a
+  // raw HTTP server. Here the registration is reachable only from a site
+  // that creates the function object, which is the only site that can later
+  // observe its `name`/`length`/source. The function-local static is one
+  // per `Entry`, so several minting sites of one declaration share a single
+  // registration, and a site costs one guard-variable load per mint.
+  template <Invoke Entry>
+  static Invoke entryWithFacts(std::string_view name, std::size_t length, std::string_view text) {
+    static const SourceRegistration registration{Entry, name, length, text, nullptr};
+    return Entry;
+  }
+
   // An adapter (`dropArguments` and its siblings below) shares ONE thunk
   // pointer across every closure it wraps, so the facts it reports cannot
   // live in this registration -- they belong to whichever `Source` closure
@@ -5649,6 +5668,7 @@ class TypedArray {
    */
   void setHostBrand(const void* brand) { hostBrand_ = brand; }
   bool hasHostBrand(const void* brand) const { return brand != nullptr && hostBrand_ == brand; }
+  const void* hostBrand() const { return hostBrand_; }
 
   /**
    * ECMA-262 23.2.3.26 `%TypedArray%.prototype.set`, over a source view of any
@@ -5833,6 +5853,41 @@ class TypedArray {
   const void* hostBrand_ = nullptr;
 };
 
+/**
+ * What a host brand's views answer to ToString.
+ *
+ * A brand is identity only (see `setHostBrand`), which is enough while the
+ * view's type is known: `buffer.toString()` lowers to the host's own function.
+ * Behind a box it is not. `body + chunk` in a `'data'` listener -- where Node
+ * declares `chunk` as `any` and hands out a Buffer -- is ToPrimitive over an
+ * erased byte view, and the generic answer for a byte view (23.2.3.32, the
+ * comma-joined elements) is not Buffer's, which decodes the bytes as UTF-8.
+ * The host that minted the brand is the only party that knows that, so it
+ * states it here once, keyed by the same opaque address.
+ *
+ * `GEA_HOST_VIEW_TO_STRING` lets a host header register only when this runtime
+ * has the table, so it still builds against a runtime that predates it.
+ */
+#define GEA_HOST_VIEW_TO_STRING 1
+namespace detail {
+using HostViewToString = std::string (*)(const TypedArray<std::uint8_t>&);
+inline std::vector<std::pair<const void*, HostViewToString>>& hostViewToStrings() {
+  static std::vector<std::pair<const void*, HostViewToString>> table;
+  return table;
+}
+inline bool registerHostViewToString(const void* brand, HostViewToString render) {
+  hostViewToStrings().emplace_back(brand, render);
+  return true;
+}
+inline HostViewToString hostViewToStringFor(const void* brand) {
+  if (brand == nullptr) return nullptr;
+  for (const auto& [known, render] : hostViewToStrings()) {
+    if (known == brand) return render;
+  }
+  return nullptr;
+}
+}  // namespace detail
+
 namespace runtime::atomics {
 
 template <typename T>
@@ -6544,6 +6599,32 @@ struct MaxAlignOf<T, Rest...> {
   static constexpr std::size_t value = alignof(T) > MaxAlignOf<Rest...>::value ? alignof(T) : MaxAlignOf<Rest...>::value;
 };
 
+/**
+ * Whether an arm may be the one a default-constructed union holds.
+ *
+ * A default-constructed `TaggedUnion` has to hold SOMETHING, and which arm it
+ * picks is arbitrary -- the emitter only ever produces one to declare an SSA
+ * slot that is assigned before it is read. Arm 0 is not always a legal choice:
+ * `FunctionValue` deliberately has no default (a Function arm holding a
+ * non-function is the bug its constructors exist to catch), so picking it
+ * aborts a program that has done nothing wrong. Arms opt out here and the
+ * default walks past them.
+ */
+template <typename Arm>
+struct UnionDefaultArm : std::true_type {};
+
+/** The first arm that may be default-constructed; 0 when none opts in. */
+template <typename... Arms>
+struct DefaultUnionArmIndex {
+  static constexpr std::size_t value = [] {
+    constexpr bool allowed[] = {UnionDefaultArm<Arms>::value...};
+    for (std::size_t index = 0; index < sizeof...(Arms); ++index) {
+      if (allowed[index]) return index;
+    }
+    return static_cast<std::size_t>(0);
+  }();
+};
+
 /** Lifetime dispatch over a closed arm set, by index: a raw byte buffer holds whichever arm is live, so construct/copy/move/destroy need a hand-written vtable-by-recursion in place of what the language generates for a real union of non-trivial arms. */
 template <typename... Arms>
 struct TaggedUnionOps;
@@ -6588,7 +6669,9 @@ class TaggedUnion {
     }(std::index_sequence_for<Arms...>{});
   }
 
-  TaggedUnion() : index_(0) { detail::TaggedUnionOps<Arms...>::defaultConstruct(0, &storage_); }
+  TaggedUnion() : index_(detail::DefaultUnionArmIndex<Arms...>::value) {
+    detail::TaggedUnionOps<Arms...>::defaultConstruct(index_, &storage_);
+  }
 
   TaggedUnion(const TaggedUnion& other) : index_(other.index_) {
     detail::TaggedUnionOps<Arms...>::copyConstruct(index_, &storage_, &other.storage_);
@@ -10021,6 +10104,19 @@ class FunctionValue : public Value {
   }
 };
 
+namespace detail {
+/**
+ * Never the arm a default-constructed union holds.
+ *
+ * `FunctionValue()` aborts on purpose, so a union with a Function arm first
+ * could not be declared at all: `gea_union_N v1;` -- the ordinary way the
+ * emitter opens an SSA slot it assigns further down -- killed the process
+ * before the assignment ran. `node:net`'s `Socket.pipe` is one such union.
+ */
+template <>
+struct UnionDefaultArm<FunctionValue> : std::false_type {};
+}
+
 namespace runtime {
 namespace string {
 inline std::size_t utf16Length(const std::string& value);
@@ -14682,6 +14778,50 @@ inline const Ref<DynamicObject>& Value::functionProperties() const {
 
 Value dynamicFunctionPrototypeGet(const PropertyKey& key);
 
+namespace detail {
+/**
+ * The own, non-method surface of a boxed typed array: `length`, `byteLength`,
+ * `byteOffset` and the element at a canonical numeric index (ECMA-262 10.4.5,
+ * 23.2.3).
+ *
+ * A typed array reaches a box wherever a library types it `any` -- Node's
+ * `'data'` chunk is the measured case, and `total += chunk.length` is what a
+ * byte-counting handler does with it. The payload type names the element type
+ * exactly, so these four are answerable from the box with no table. Every other
+ * key keeps the refusal below: a method (`slice`, `toString`) needs a callable
+ * this runtime does not mint for an erased view, and answering `undefined`
+ * would be the plausible wrong answer.
+ */
+template <typename Element>
+inline bool boxedTypedArrayOwnAs(const Value& value, const PropertyKey& key, Value& out) {
+  using Handle = gea::Ref<TypedArray<Element>>;
+  if (value.payloadType() != payloadTypeTagFor<Handle>()) return false;
+  const Handle& view = value.as<Handle>();
+  if (!view || key.isSymbol()) return false;
+  std::size_t index = 0;
+  if (arrayIndexOfKey(key, index)) {
+    // 10.4.5.15: an index past the end reads `undefined`, never the prototype.
+    out = index < view->size() ? Value::box(Value::Tag::Number, static_cast<double>((*view)[index])) : Value();
+    return true;
+  }
+  if (key.isNumericSource()) return false;
+  const std::string& name = key.text();
+  if (name == "length") out = Value::box(Value::Tag::Number, static_cast<double>(view->size()));
+  else if (name == "byteLength") out = Value::box(Value::Tag::Number, view->byteLength());
+  else if (name == "byteOffset") out = Value::box(Value::Tag::Number, view->byteOffset());
+  else return false;
+  return true;
+}
+
+inline bool boxedTypedArrayOwn(const Value& value, const PropertyKey& key, Value& out) {
+  return boxedTypedArrayOwnAs<std::uint8_t>(value, key, out) || boxedTypedArrayOwnAs<std::int8_t>(value, key, out) ||
+         boxedTypedArrayOwnAs<ClampedUint8>(value, key, out) || boxedTypedArrayOwnAs<std::int16_t>(value, key, out) ||
+         boxedTypedArrayOwnAs<std::uint16_t>(value, key, out) || boxedTypedArrayOwnAs<std::int32_t>(value, key, out) ||
+         boxedTypedArrayOwnAs<std::uint32_t>(value, key, out) || boxedTypedArrayOwnAs<float>(value, key, out) ||
+         boxedTypedArrayOwnAs<double>(value, key, out);
+}
+}  // namespace detail
+
 inline Value Value::getProperty(const PropertyKey& key) const {
   return getProperty(key, *this);
 }
@@ -14739,6 +14879,8 @@ inline Value Value::getProperty(const PropertyKey& key, const Value& receiver) c
   if (tag_ == Tag::Object) {
     Value method;
     if (detail::boxedPromiseMethod(*this, key, method)) return method;
+    Value own;
+    if (detail::boxedTypedArrayOwn(*this, key, own)) return own;
   }
   if (tag_ == Tag::Object || tag_ == Tag::Function) detail::refuseOpaquePropertyAccess("a property read", key);
   // Every remaining box is a primitive, whose properties all live on a
@@ -18207,6 +18349,31 @@ template <typename T>
   throw gea::Value::box(gea::Value::Tag::String, std::string("InternalError: entered a branch the compiler proved unreachable"));
 }
 
+/**
+ * The exact-arm projection of a tagged union (`conversion/nodes.ts`'s
+ * `exactArmFor`): the payload of arm `Index`, or a `TypeError` when the value
+ * holds another arm.
+ *
+ * Emitted inside a body whose declaration states `@gea-exact-arms`, and at a
+ * value the program's own `as T` states the arm of where the census has no
+ * sound per-arm answer (`lower-operands.ts`'s `assertedArmEntry`). The
+ * alternative the compiler would otherwise render is a per-arm dispatch that
+ * CONVERTS every arm into the target -- for a callable target, an adapter that
+ * boxes the typed arm's parameters to feed a generic listener -- and the tag
+ * is the author stating that the guard around the cast already excluded those
+ * arms. A `TypeError` rather than an abort because a wrong arm here is the
+ * program's contract violated (`server.on('request', genericHandler)`), not
+ * the compiler's, and the program may want to catch it.
+ */
+template <std::size_t Index, typename... Arms>
+typename gea::TaggedUnion<Arms...>::template ArmType<Index> exactArm(const gea::TaggedUnion<Arms...>& value) {
+  if (!value.template is<Index>()) {
+    throwRuntimeError("TypeError", "Value is not the union arm this operation requires (arm " + std::to_string(Index) +
+                                       " expected, arm " + std::to_string(value.index()) + " held)");
+  }
+  return value.template get<Index>();
+}
+
 }  // namespace gea::host
 
 namespace gea::runtime::string {
@@ -24927,6 +25094,77 @@ inline void recordNodeSubscription(int nodeId, std::function<void()> release);
 template <typename Node>
 gea::Ref<bool> nodeLiveToken(const Node& node);
 
+/**
+ * Whether the engine dispatches `name` off-tree. `rotary` (the encoder dial)
+ * always: it has no element target, the runtime hands each detent to the one
+ * document-level listener chain (`dispatchDocumentRotary`), and
+ * `Tree::setEventListener` drops "rotary" as a type it never walks the tree
+ * for -- so an `onRotary` delegated to the body was registered nowhere and the
+ * dial did nothing, silently. `keydown` is off-tree on anything but an
+ * `<input>`: the runtime hands a key to the focused input's own listener (which
+ * bubbles to the body) and then to the document-level chain. The same rule the
+ * gea plugin's `cpp-mounted-lowering.ts` applies to its direct-root listeners.
+ */
+template <typename Node>
+bool isDocumentLevelEvent(const Node& node, const std::string& name) {
+  if (name == "rotary") return true;
+  if (name != "keydown") return false;
+  const char* tag = node.tagName();
+  if (!tag) return true;
+  std::string lowered(tag);
+  for (char& character : lowered) character = static_cast<char>(std::tolower(static_cast<unsigned char>(character)));
+  return lowered != "input";
+}
+
+/**
+ * Register `invoke` for `name` on behalf of `node`: the one place both engine
+ * `addNodeListener` overloads bind through.
+ *
+ * A document-level event goes straight to `Document::addEventListener`, which
+ * chains it onto the off-tree singleton: no `containsNode` gate, since there is
+ * no target to contain. The chain has no per-listener removal, so the handler
+ * is gated on the node's live token instead -- a rebuilt subtree leaves an
+ * inert closure behind rather than a second generation of the handler.
+ *
+ * Everything else is delegated to the BODY and gated by `containsNode`; see
+ * the no-argument `addNodeListener` for why, and `recordNodeSubscription` for
+ * how it is released with the node.
+ */
+template <typename Node, typename Invoke>
+void bindNodeListener(Node& node, const std::string& name, Invoke invoke) {
+  const auto target = node;
+  auto run = [target, invoke](gea::framework::events::PointerEvent& event) mutable {
+    const auto previousTarget = event.currentTarget;
+    const auto previousTargetId = event.currentTargetId;
+    const auto previousPhase = event.eventPhase;
+    event.currentTarget = gea::framework::events::EventTarget(target.id());
+    event.currentTargetId = target.id();
+    event.eventPhase = event.targetId == target.id() ? gea::framework::events::EventPhase::AtTarget
+                                                     : gea::framework::events::EventPhase::Bubbling;
+    invoke(event);
+    event.currentTarget = previousTarget;
+    event.currentTargetId = previousTargetId;
+    event.eventPhase = previousPhase;
+  };
+  if (isDocumentLevelEvent(node, name)) {
+    auto alive = nodeLiveToken(node);
+    gea::embedded::ui::Document::instance().addEventListener(
+      name.c_str(), [alive, run](gea::framework::events::PointerEvent& event) mutable {
+        if (!*alive) return;
+        run(event);
+      });
+    return;
+  }
+  const auto listenerId = gea::embedded::ui::Document::instance().body().addEventListener(
+    name.c_str(), [target, run](gea::framework::events::PointerEvent& event) mutable {
+      if (!gea::embedded::ui::Tree::instance().containsNode(target.id(), event.targetId)) return;
+      run(event);
+    });
+  recordNodeSubscription(target.id(), [name, listenerId]() {
+    gea::embedded::ui::Document::instance().body().removeEventListener(name.c_str(), listenerId);
+  });
+}
+
 /**
  * `onClick={() => ...}` on the real engine: the handler is copied into the
  * listener the engine holds, and the event it hands back is dropped -- a
@@ -24969,26 +25207,7 @@ void addNodeListener(Node& node, const std::string& type, const gea::CallableObj
   // flipped the unit twice and the whole UI stayed in Celsius, with nothing
   // logged and every node still rendering correctly.
   const gea::CallableObject<Result()> held = handler;
-  const auto target = node;
-  const std::string name = eventTypeOf(type);
-  const auto listenerId = gea::embedded::ui::Document::instance().body().addEventListener(
-    name.c_str(), [held, target](gea::framework::events::PointerEvent& event) mutable {
-      if (!gea::embedded::ui::Tree::instance().containsNode(target.id(), event.targetId)) return;
-      const auto previousTarget = event.currentTarget;
-      const auto previousTargetId = event.currentTargetId;
-      const auto previousPhase = event.eventPhase;
-      event.currentTarget = gea::framework::events::EventTarget(target.id());
-      event.currentTargetId = target.id();
-      event.eventPhase = event.targetId == target.id() ? gea::framework::events::EventPhase::AtTarget
-                                                       : gea::framework::events::EventPhase::Bubbling;
-      held.call();
-      event.currentTarget = previousTarget;
-      event.currentTargetId = previousTargetId;
-      event.eventPhase = previousPhase;
-    });
-  recordNodeSubscription(target.id(), [name, listenerId]() {
-    gea::embedded::ui::Document::instance().body().removeEventListener(name.c_str(), listenerId);
-  });
+  bindNodeListener(node, eventTypeOf(type), [held](gea::framework::events::PointerEvent&) mutable { held.call(); });
 }
 
 /**
@@ -25018,31 +25237,14 @@ void addNodeListener(Node& node, const std::string& type, const gea::CallableObj
 template <typename Node, typename Result, typename Argument>
 void addNodeListener(Node& node, const std::string& type, const gea::CallableObject<Result(Argument)>& handler) {
   const gea::CallableObject<Result(Argument)> held = handler;
-  const auto target = node;
   const std::string name = eventTypeOf(type);
-  const auto listenerId = gea::embedded::ui::Document::instance().body().addEventListener(
-    name.c_str(), [held, target, name](gea::framework::events::PointerEvent& event) mutable {
-      if (!gea::embedded::ui::Tree::instance().containsNode(target.id(), event.targetId)) return;
-      const auto previousTarget = event.currentTarget;
-      const auto previousTargetId = event.currentTargetId;
-      const auto previousPhase = event.eventPhase;
-      event.currentTarget = gea::framework::events::EventTarget(target.id());
-      event.currentTargetId = target.id();
-      event.eventPhase = event.targetId == target.id() ? gea::framework::events::EventPhase::AtTarget
-                                                       : gea::framework::events::EventPhase::Bubbling;
-      if constexpr (std::is_constructible_v<std::decay_t<Argument>, const gea::framework::events::PointerEvent&>) {
-        held.call(static_cast<std::decay_t<Argument>>(event));
-      } else {
-        std::fprintf(stderr, "gea: the handler for \"%s\" declares an event parameter, which no host table states a carrier for\n", name.c_str());
-        gea::detail::abortAfterFlush();
-      }
-      event.currentTarget = previousTarget;
-      event.currentTargetId = previousTargetId;
-      event.eventPhase = previousPhase;
-    });
-  // Owned by `node`, for the reason the no-argument overload above states.
-  recordNodeSubscription(target.id(), [name, listenerId]() {
-    gea::embedded::ui::Document::instance().body().removeEventListener(name.c_str(), listenerId);
+  bindNodeListener(node, name, [held, name](gea::framework::events::PointerEvent& event) mutable {
+    if constexpr (std::is_constructible_v<std::decay_t<Argument>, const gea::framework::events::PointerEvent&>) {
+      held.call(static_cast<std::decay_t<Argument>>(event));
+    } else {
+      std::fprintf(stderr, "gea: the handler for \"%s\" declares an event parameter, which no host table states a carrier for\n", name.c_str());
+      gea::detail::abortAfterFlush();
+    }
   });
 }