feat(runtime): expose the dev-loader surface as the ns:runtime builtin module

The five dev primitives — configureRuntime, invalidateModules,
getLoadedModuleUrls, setDevBootComplete, terminateAllWorkers — resolve
through the NsBuiltinModules registry: require("ns:runtime"), static
import, and import() all yield the same frozen per-realm module,
materialized lazily from BuildNsRuntimeBinding (HMRSupport.mm). The dev
surface defines no globals.
Membership is realm- and build-scoped: terminateAllWorkers exists only in
the main realm (a worker must not take down its peers) and
canonicalizeHttpUrlKey only in debug builds; missing members are absent,
never present-but-throwing, so feature checks work. Builtin specifiers
resolve only through the registry — an import-map entry can never shadow
them onto HTTP.

Author: NathanWalker

NativeScript/runtime/HMRSupport.h

@@ -96,8 +96,8 @@ void MarkUrlsForCacheBust(const std::vector<std::string>& urls);
 // Flip the dev-boot-complete signal: sets the JS-visible
 // `__NS_HMR_BOOT_COMPLETE__` global and the native atomic that gates the
 // cold-boot-only behaviors (JS-thread runloop pump between synchronous
-// fetches). Exposed to JS as
-// `__NS_DEV__.setDevBootComplete(value?: boolean)`.
+// fetches). Exposed to JS as ns:runtime
+// `setDevBootComplete(value?: boolean)`.
 void SetDevBootComplete(v8::Isolate* isolate, v8::Local<v8::Context> context,
                         bool value);
 
@@ -108,30 +108,27 @@ void SetDevBootComplete(v8::Isolate* isolate, v8::Local<v8::Context> context,
 // still uses).
 void CleanupHMRGlobals();
 
-// Mirror a globally-installed value onto `globalThis.<name>` so
-// `globalThis.<name>` lookups resolve when the runtime installs the
-// canonical value on the realm's global object.
-void MirrorGlobalOnGlobalThis(v8::Isolate* isolate,
-                              v8::Local<v8::Context> context, const char* name);
-
 // ─────────────────────────────────────────────────────────────
-// Dev host namespace installer
+// The `ns:runtime` builtin binding
 //
-// Installs the single `__NS_DEV__` namespace object that carries every
-// JS-callable dev primitive that any tooling can depend on.
-// Idempotent per realm; safe to call from any place that has a fresh
-// context + isolate scope. Installed on the realm's global object AND
-// mirrored on globalThis.
+// Populates the native half of the `ns:runtime` builtin module — the one
+// namespace carrying every JS-callable dev primitive that any tooling can
+// depend on. Called from NsBuiltinModules::BuildBinding the first time a
+// realm resolves `ns:runtime` (via require, static import, or import());
+// ns-runtime.js shapes and freezes the exports.
 //
-// `__NS_DEV__` members:
+// `ns:runtime` members:
 //   - configureRuntime(config)        (import map + volatile patterns +
 //                                      canonicalization vocabulary)
 //   - invalidateModules(urls)         (registry + cache eviction)
 //   - getLoadedModuleUrls()           (registry introspection)
 //   - setDevBootComplete(value?)      (boot-complete signal)
-//   - terminateAllWorkers()           (main isolate only; see Worker.h)
+//   - terminateAllWorkers()           (main realm only; see Worker.h)
 //   - canonicalizeHttpUrlKey(url)     (debug builds only; test diagnostic)
-void InitializeHmrDevGlobals(v8::Isolate* isolate,
-                             v8::Local<v8::Context> context, bool isWorker);
+//
+// Returns false (with an exception pending or a failed Set) when the
+// binding could not be populated.
+bool BuildNsRuntimeBinding(v8::Local<v8::Context> context,
+                           v8::Local<v8::Object> binding);
 
 }  // namespace tns

NativeScript/runtime/HMRSupport.mm

@@ -9,6 +9,7 @@
 #include <mutex>
 #include <string>
 #include <vector>
+#include "Caches.h"
 #include "Helpers.h"
 #include "ModuleInternalCallbacks.h"
 #include "Runtime.h"
@@ -25,22 +26,6 @@ static inline bool StartsWith(const std::string& s, const char* prefix) {
   return s.size() >= n && s.compare(0, n, prefix) == 0;
 }
 
-void MirrorGlobalOnGlobalThis(v8::Isolate* isolate, v8::Local<v8::Context> context,
-                              const char* name) {
-  std::string src = "if (typeof globalThis !== 'undefined' && typeof globalThis." +
-                    std::string(name) +
-                    " === 'undefined') {"
-                    "  Object.defineProperty(globalThis, '" +
-                    std::string(name) + "', { value: this." + std::string(name) +
-                    ", writable: true, configurable: true, enumerable: false });"
-                    "}";
-
-  v8::Local<v8::Script> script;
-  if (v8::Script::Compile(context, tns::ToV8String(isolate, src.c_str())).ToLocal(&script)) {
-    script->Run(context).FromMaybe(v8::Local<v8::Value>());
-  }
-}
-
 static void SetBooleanGlobal(v8::Isolate* isolate, v8::Local<v8::Context> context, const char* key,
                              bool value) {
   context->Global()
@@ -54,8 +39,8 @@ static void SetBooleanGlobal(v8::Isolate* isolate, v8::Local<v8::Context> contex
 // Native-side mirror of `__NS_HMR_BOOT_COMPLETE__`. Read by the
 // runloop pump in `MaybePumpJSThreadDuringBoot` so its gate is a
 // single relaxed atomic load on the HMR-time hot path. The JS dev
-// client flips this via the
-// `__NS_DEV__.setDevBootComplete(bool)` global once the real app root view
+// client flips this via ns:runtime
+// `setDevBootComplete(bool)` once the real app root view
 // commits; boot orchestration itself is entirely userland.
 static std::atomic<bool> g_devSessionBootComplete{false};
 
@@ -83,7 +68,7 @@ void SetDevBootComplete(v8::Isolate* isolate, v8::Local<v8::Context> context, bo
 // queries may be normalized, and which paths must keep their query verbatim
 // because the query IS the identity — is server/framework policy, supplied
 // by the dev client via
-// `__NS_DEV__.configureRuntime({ canonicalization: {...} })`.
+// ns:runtime `configureRuntime({ canonicalization: {...} })`.
 //
 // Write-before-read contract: the client configures this once, before the
 // first import wave (session-bootstrap order), so plain statics are
@@ -94,10 +79,6 @@ void SetDevBootComplete(v8::Isolate* isolate, v8::Local<v8::Context> context, bo
 //
 // When unconfigured, a built-in vocabulary matching current
 // `@nativescript/vite` conventions applies.
-// TODO(feat/hmr-dev-sessions follow-up): delete the built-in vocabulary once
-// the paired `@nativescript/vite` release that sends `canonicalization` has
-// been qualified — the runtime should carry zero server/framework URL
-// strings.
 struct CanonicalizationConfig {
   std::vector<std::string> stripParams;            // query param names to drop
   std::vector<std::string> devPathPrefixes;        // path StartsWith → normalize query
@@ -110,7 +91,7 @@ static void SetCanonicalizationConfig(CanonicalizationConfig config) {
   g_canonConfig = std::move(config);
   g_canonConfigured = true;
   if (IsScriptLoadingLogEnabled()) {
-    Log(@"[__NS_DEV__.configureRuntime] canonicalization set (strip=%lu devPrefixes=%lu "
+    Log(@"[ns:runtime configureRuntime] canonicalization set (strip=%lu devPrefixes=%lu "
         @"preserve=%lu)",
         (unsigned long)g_canonConfig.stripParams.size(),
         (unsigned long)g_canonConfig.devPathPrefixes.size(),
@@ -161,7 +142,7 @@ static void ResetCanonicalizationConfig() {
   //
   // The dev server serves every module under ONE canonical URL — module
   // identity IS the URL string. Freshness after an HMR edit is handled by
-  // `__NS_DEV__.invalidateModules` (registry evict) plus the
+  // ns:runtime `invalidateModules` (registry evict) plus the
   // eviction-driven fetch nonce in `PerformHttpFetchOnceSync`, never by URL
   // variation. There is deliberately no path-tag vocabulary to collapse here.
   //
@@ -192,7 +173,8 @@ static void ResetCanonicalizationConfig() {
         return noHash;
       }
     } else {
-      // Built-in fallback vocabulary — see the deletion TODO above.
+      // Unconfigured: built-in vocabulary matching `@nativescript/vite`
+      // conventions.
       if (pathOnly.find("/@ng/component") != std::string::npos) {
         return noHash;
       }
@@ -300,12 +282,10 @@ static void ClearAllCacheBustMarks() {
 //     which fetches the transitive closure concurrently off the JS
 //     thread before instantiation begins.
 //
-// There is deliberately NO body prewarm cache and NO JS-driven prefetch
-// API here. Measurement (see docs/knowledge/hmr-simplification-pass.md)
-// showed the async discovery walk beats server-computed
-// closure/archive seeding on real apps — concurrent fetches overlap
-// with on-device compile, while seeding serializes a full server-side
-// transform pass before the entry can start.
+// These two are the loader's complete fetch surface: the async graph walk
+// owns all body fetching. Concurrent per-module fetches overlap with
+// on-device compile, which measured fastest on real apps
+// (HMR_API_NECESSITY_REVIEW.md §8.3).
 
 // Forward declarations — these helpers are defined below their first use,
 // matching the existing convention in this file.
@@ -754,7 +734,7 @@ void FetchModuleBodyAsync(const std::string& url,
 //     background threads, so they never pump someone else's runloop.
 //   - `IsDevSessionBootComplete()` short-circuits once the dev client
 //     has committed its first stable view (it calls
-//     `__NS_DEV__.setDevBootComplete(true)`) — no placeholder to repaint, and
+//     ns:runtime `setDevBootComplete(true)`) — no placeholder to repaint, and
 //     HMR-time fetches must not pay the pump cost.
 //   - The runloop identity check survives any future change that
 //     decouples the runtime's captured runloop from the current thread.
@@ -814,18 +794,20 @@ void CleanupHMRGlobals() {
 }
 
 // ─────────────────────────────────────────────────────────────
-// Dev-loader JS-callable globals
+// The `ns:runtime` dev surface
 //
 // The runtime's dev surface is deliberately small: it exposes
 // *mechanism* only (resolution config, registry eviction, registry
 // introspection, boot-complete signal). All HMR *policy* — boot
 // orchestration, `import.meta.hot`, full reload, CSS apply, WebSocket
 // protocol — lives in the JS dev client (`@nativescript/vite`).
+// The surface is reachable exclusively through the `ns:runtime` builtin
+// module (require / static import / import()); there is no global.
 
 namespace {
 
 // Sets the function name on the v8 Function for nicer stack traces and
-// attaches it as a method of the `__NS_DEV__` namespace object.
+// attaches it as a member of the `ns:runtime` binding object.
 void InstallDevFunction(v8::Isolate* isolate, v8::Local<v8::Context> context,
                         v8::Local<v8::Object> target, const char* name,
                         v8::FunctionCallback callback) {
@@ -843,7 +825,7 @@ void ConfigureDevRuntimeCallback(const v8::FunctionCallbackInfo<v8::Value>& info
 
   if (info.Length() < 1 || !info[0]->IsObject()) {
     if (logScriptLoading) {
-      Log(@"[__NS_DEV__.configureRuntime] expected config object argument");
+      Log(@"[ns:runtime configureRuntime] expected config object argument");
     }
     return;
   }
@@ -877,7 +859,7 @@ void ConfigureDevRuntimeCallback(const v8::FunctionCallbackInfo<v8::Value>& info
     if (!jsonStr.empty()) {
       SetImportMap(jsonStr);
       if (logScriptLoading) {
-        Log(@"[__NS_DEV__.configureRuntime] import map set (%zu bytes)", jsonStr.size());
+        Log(@"[ns:runtime configureRuntime] import map set (%zu bytes)", jsonStr.size());
       }
     }
   }
@@ -907,7 +889,7 @@ void ConfigureDevRuntimeCallback(const v8::FunctionCallbackInfo<v8::Value>& info
     if (readStringArray(config, "volatilePatterns", patterns) && !patterns.empty()) {
       SetVolatilePatterns(patterns);
       if (logScriptLoading) {
-        Log(@"[__NS_DEV__.configureRuntime] %zu volatile patterns set", patterns.size());
+        Log(@"[ns:runtime configureRuntime] %zu volatile patterns set", patterns.size());
       }
     }
   }
@@ -936,7 +918,7 @@ void InvalidateModulesCallback(const v8::FunctionCallbackInfo<v8::Value>& info)
   v8::Local<v8::Context> ctx = isolate->GetCurrentContext();
 
   if (info.Length() < 1 || !info[0]->IsArray()) {
-    Log(@"[__NS_DEV__.invalidateModules] expected array of URL strings");
+    Log(@"[ns:runtime invalidateModules] expected array of URL strings");
     return;
   }
 
@@ -992,7 +974,7 @@ void GetLoadedModuleUrlsCallback(const v8::FunctionCallbackInfo<v8::Value>& info
   info.GetReturnValue().Set(result);
 }
 
-// `__NS_DEV__.setDevBootComplete(value?: boolean)` — the JS dev client calls
+// ns:runtime `setDevBootComplete(value?: boolean)` — the JS dev client calls
 // this (with `true`, or no argument) once the real app root view has
 // committed. It flips both the JS-visible `__NS_HMR_BOOT_COMPLETE__`
 // global and the native atomic that disarms the cold-boot runloop pump.
@@ -1013,48 +995,48 @@ void SetDevBootCompleteCallback(const v8::FunctionCallbackInfo<v8::Value>& info)
 
 }  // namespace
 
-void InitializeHmrDevGlobals(v8::Isolate* isolate, v8::Local<v8::Context> context, bool isWorker) {
-  // The dev host API lives here: `__NS_DEV__`.
-  v8::Local<v8::Object> dev = v8::Object::New(isolate);
+bool BuildNsRuntimeBinding(v8::Local<v8::Context> context, v8::Local<v8::Object> binding) {
+  v8::Isolate* isolate = v8::Isolate::GetCurrent();
 
-  InstallDevFunction(isolate, context, dev, "configureRuntime", ConfigureDevRuntimeCallback);
-  InstallDevFunction(isolate, context, dev, "invalidateModules", InvalidateModulesCallback);
-  InstallDevFunction(isolate, context, dev, "getLoadedModuleUrls", GetLoadedModuleUrlsCallback);
-  InstallDevFunction(isolate, context, dev, "setDevBootComplete", SetDevBootCompleteCallback);
+  InstallDevFunction(isolate, context, binding, "configureRuntime", ConfigureDevRuntimeCallback);
+  InstallDevFunction(isolate, context, binding, "invalidateModules", InvalidateModulesCallback);
+  InstallDevFunction(isolate, context, binding, "getLoadedModuleUrls", GetLoadedModuleUrlsCallback);
+  InstallDevFunction(isolate, context, binding, "setDevBootComplete", SetDevBootCompleteCallback);
 
-  // Main-isolate only: terminating workers from inside a worker would let
-  // a stuck worker take down its peers (see Worker.h).
-  if (!isWorker) {
-    InstallDevFunction(isolate, context, dev, "terminateAllWorkers",
+  // Main-realm only: terminating workers from inside a worker would let
+  // a stuck worker take down its peers (see Worker.h). A worker realm's
+  // `ns:runtime` simply has no such member, so feature checks work.
+  if (!Caches::Get(isolate)->isWorker) {
+    InstallDevFunction(isolate, context, binding, "terminateAllWorkers",
                        Worker::TerminateAllWorkersCallback);
   }
 
   if (RuntimeConfig.IsDebug) {
-    try {
-      // Debug-only diagnostic: expose the HTTP canonical-key function to JS so
-      // the test harness can pin its identity behavior across cache-busters
-      // and dev-endpoint query normalization.
-      auto canonicalizeCb = [](const v8::FunctionCallbackInfo<v8::Value>& info) {
-        v8::Isolate* iso = info.GetIsolate();
-        if (info.Length() < 1 || !info[0]->IsString()) {
-          info.GetReturnValue().SetEmptyString();
-          return;
-        }
-        v8::String::Utf8Value u(iso, info[0]);
-        std::string key = CanonicalizeHttpUrlKey(*u ? std::string(*u) : std::string());
-        info.GetReturnValue().Set(tns::ToV8String(iso, key.c_str()));
-      };
-      v8::Local<v8::Function> fn = v8::Function::New(context, canonicalizeCb).ToLocalChecked();
+    // Debug-only diagnostic: expose the HTTP canonical-key function to JS so
+    // the test harness can pin its identity behavior across cache-busters
+    // and dev-endpoint query normalization.
+    auto canonicalizeCb = [](const v8::FunctionCallbackInfo<v8::Value>& info) {
+      v8::Isolate* iso = info.GetIsolate();
+      if (info.Length() < 1 || !info[0]->IsString()) {
+        info.GetReturnValue().SetEmptyString();
+        return;
+      }
+      v8::String::Utf8Value u(iso, info[0]);
+      std::string key = CanonicalizeHttpUrlKey(*u ? std::string(*u) : std::string());
+      info.GetReturnValue().Set(tns::ToV8String(iso, key.c_str()));
+    };
+    v8::Local<v8::Function> fn;
+    if (v8::Function::New(context, canonicalizeCb).ToLocal(&fn)) {
       fn->SetName(tns::ToV8String(isolate, "canonicalizeHttpUrlKey"));
-      dev->CreateDataProperty(context, tns::ToV8String(isolate, "canonicalizeHttpUrlKey"), fn)
-          .Check();
-    } catch (...) {
-      // Don't crash if debug-diagnostic setup fails
+      if (!binding
+               ->CreateDataProperty(context, tns::ToV8String(isolate, "canonicalizeHttpUrlKey"), fn)
+               .FromMaybe(false)) {
+        return false;
+      }
     }
   }
 
-  context->Global()->Set(context, tns::ToV8String(isolate, "__NS_DEV__"), dev).FromMaybe(false);
-  MirrorGlobalOnGlobalThis(isolate, context, "__NS_DEV__");
+  return true;
 }
 
 }  // namespace tns

NativeScript/runtime/ModuleInternalCallbacks.mm

@@ -376,15 +376,16 @@ void DestroyModuleStateForIsolate(v8::Isolate* isolate) {
 }
 
 // ────────────────────────────────────────────────────────────────────────────
-// Import map: bare specifier → resolved URL (populated by __NS_DEV__.configureRuntime)
+// Import map: bare specifier → resolved URL (populated by ns:runtime configureRuntime)
 // Instead of rewriting import statements in source code on the Vite side, the runtime
 // resolves bare specifiers through this map to HTTP module URLs. Source code
 // is served as Vite transformed it.
 static robin_hood::unordered_map<std::string, std::string> g_importMap;
 
 // Volatile URL patterns: URLs matching these substrings are always re-fetched
-// (cache is evicted before loading). Configured by Vite at boot instead of
-// being hardcoded. Replaces hardcoded /@ns/sfc/ and __webpack_* checks.
+// (cache is evicted before loading). Configured by Vite at boot — the
+// vocabulary is server/framework policy, so the runtime carries no
+// framework-specific URL strings here.
 static std::vector<std::string> g_volatilePatterns;
 
 static bool ShouldTraceRegistryKey(const std::string& rawKey, const std::string& registryKey) {
@@ -2045,7 +2046,7 @@ static bool IsDocumentsPath(const std::string& path) {
       normalizedSpec;  // use normalized spec for the rest of the resolution logic
 
   // Import map resolution
-  // If the import map is populated (set by __NS_DEV__.configureRuntime), check it
+  // If the import map is populated (set by ns:runtime configureRuntime), check it
   // before any other resolution. This is the highest-leverage change from
   // the HMR architecture review: bare specifiers resolve through the map
   // to either vendor URLs or HTTP module URLs, eliminating the need for
@@ -3515,7 +3516,7 @@ static void FinishHttpDynamicImport(v8::Isolate* isolate, v8::Local<v8::Context>
       // Volatile pattern check: if the URL matches any configured volatile
       // pattern, evict the cached module so we always re-fetch. The pattern
       // list is policy and is supplied exclusively by the dev client via
-      // `__NS_DEV__.configureRuntime({ volatilePatterns })` — the runtime
+      // ns:runtime `configureRuntime({ volatilePatterns })` — the runtime
       // carries no framework or server URL vocabulary of its own. (Framework
       // strategies ship their own endpoints, e.g. Angular's `/@ng/component`
       // whose per-save `t` param would otherwise accumulate one stale

NativeScript/runtime/NsBuiltinModules.cpp

@@ -5,6 +5,7 @@
 #include "BuiltinLoader.h"
 #include "Caches.h"
 #include "Console.h"
+#include "HMRSupport.h"
 #include "Helpers.h"
 
 using namespace v8;
@@ -26,6 +27,7 @@ struct Registration {
 // adapts, so the two module objects stay distinct and the standard module
 // never carries compatibility code.
 constexpr Registration kRegistry[] = {
+    {"ns:runtime", BuiltinId::kNsRuntime},
     {"ns:util", BuiltinId::kNsUtil},
     {"node:util", BuiltinId::kNodeUtil},
 };
@@ -48,6 +50,15 @@ MaybeLocal<Object> BuildBinding(Local<Context> context, BuiltinId builtin) {
   Local<Object> binding = Object::New(isolate);
 
   switch (builtin) {
+    case BuiltinId::kNsRuntime: {
+      // The dev-loader control surface (HMRSupport.mm). The binding builder
+      // decides realm/build-dependent membership; ns-runtime.js only shapes
+      // and freezes whatever arrives.
+      if (!BuildNsRuntimeBinding(context, binding)) {
+        return MaybeLocal<Object>();
+      }
+      break;
+    }
     case BuiltinId::kNsUtil: {
       // The console formatter is built once per realm; ns:util re-exports that
       // instance instead of creating a second one.