@nativescript/windows-hermes 0.1.0-alpha.0

package/README.md

@@ -0,0 +1,27 @@
+# @nativescript/windows-hermes
+
+NativeScript Windows runtime on **Microsoft's prebuilt Hermes** (`hermes.dll`, which exports both
+`napi_*` and the JSR C API), with no Node/Bun/Deno host. The engine-neutral
+`runtime::napi_engine` WinRT interop runs unchanged over Hermes's `napi_env`.
+
+## As an app runtime (drop-in for `@nativescript/windows`)
+Publishes as `@nativescript/windows-hermes`, the **same** WinUI 3 framework as
+`@nativescript/windows` with the Hermes runtime DLL — swap the dependency and an app runs
+unchanged. Build the framework with the engine flag:
+```sh
+pwsh -File ../../template/build.ps1 -Engine hermes   # or: npm run build
+```
+The engine → runtime-DLL adapter (the C ABI the WinUI 3 host P/Invokes) follows the reference
+implementation in `../windows-quickjs/src/abi.rs`. See `../README.md` for the full contract.
+
+## Standalone host (dev/bench)
+```sh
+cargo build --release --manifest-path packages/windows-hermes/Cargo.toml
+target/release/nativescript-windows.exe   # runs the WinRT demo, exit 0
+```
+build.rs links `vendor/x64/hermes.lib`, forward-exports Hermes's `napi_*` from the exe (so napi-sys
+resolves them), and copies `hermes.dll`/`hermes-icu.dll` next to the binary.
+
+## Notes
+- Prebuilt engine binaries are committed under `vendor/` — see `vendor/README.md` for provenance
+  (Microsoft.JavaScript.Hermes NuGet) and the refresh recipe.

package/framework/__PROJECT_NAME__/App.xaml

@@ -0,0 +1,13 @@
+<Application
+    x:Class="__PROJECT_NAME__.App"
+    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
+    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
+    xmlns:local="using:__PROJECT_NAME__">
+    <Application.Resources>
+        <ResourceDictionary>
+            <ResourceDictionary.MergedDictionaries>
+                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
+            </ResourceDictionary.MergedDictionaries>
+        </ResourceDictionary>
+    </Application.Resources>
+</Application>

package/framework/__PROJECT_NAME__/App.xaml.cs

@@ -0,0 +1,240 @@
+using System;
+using System.Text.Json;
+using Windows.ApplicationModel;
+using Microsoft.UI.Dispatching;
+using Microsoft.UI.Xaml;
+using Microsoft.UI.Xaml.Controls;
+using Microsoft.UI.Xaml.Media;
+using Windows.Storage;
+
+namespace __PROJECT_NAME__
+{
+    public interface INativeScriptApp
+    {
+        Microsoft.UI.Xaml.Window MainWindow { get; }
+        Microsoft.UI.Xaml.Window Window { get; }
+    }
+
+    sealed partial class App : Application, INativeScriptApp
+    {
+        private const string LastLaunchArgsKey = "LastLaunchArgs";
+        private readonly RuntimeHost _runtimeHost = new RuntimeHost();
+
+        internal static Window CurrentWindow { get; private set; }
+        public Window MainWindow => CurrentWindow;
+        public Window Window => CurrentWindow;
+
+         enum AppEventKind
+        {
+            Activated = 1,
+            Deactivated = 2,
+            Shown = 3,
+            Hidden = 4,
+            UncaughtError = 5,
+            Exit = 6
+        }
+
+        public App()
+        {
+			this.InitializeComponent();
+			CurrentWindow ??= new Window();
+
+            CrashDiagnostics.InstallGlobalHandlers();
+            CurrentWindow.Closed += OnWindowClosed;
+            CurrentWindow.Activated += OnWindowActivated;
+            CurrentWindow.VisibilityChanged += OnWindowVisibilityChanged;
+            this.UnhandledException += OnUnhandledException;
+        }
+
+        protected override async void OnLaunched(LaunchActivatedEventArgs e)
+        {
+            _runtimeHost.Initialize();
+
+            // Capture before any await — continuations may resume on a thread pool thread.
+            var dispatcherQueue = DispatcherQueue.GetForCurrentThread();
+
+            // Show crash report from the previous run if one exists.
+            try
+            {
+                var panicLogPath = System.IO.Path.Combine(
+                    ApplicationData.Current.LocalFolder.Path, "nativescript-panic.log");
+                if (System.IO.File.Exists(panicLogPath))
+                {
+                    var content = System.IO.File.ReadAllText(panicLogPath);
+                    System.IO.File.Delete(panicLogPath);
+                    if (!string.IsNullOrWhiteSpace(content))
+                        await CrashDiagnostics.ShowCrashDialogAsync("Crash from previous run", content);
+                }
+            }
+            catch { }
+
+            string jsError = null;
+            try
+            {
+                _runtimeHost.RunMainScript();
+                jsError = _runtimeHost.GetLastJsError();
+                if (!string.IsNullOrEmpty(jsError))
+                {
+                    CrashDiagnostics.WriteMessage("JS Error", jsError);
+                    var report = CrashDiagnostics.BuildErrorReport(null, jsError);
+                    CrashDiagnostics.WriteToTraceLog(report);
+                    await CrashDiagnostics.ShowCrashDialogAsync("JavaScript Error", report);
+                }
+            }
+            catch (Exception scriptEx)
+            {
+                jsError = _runtimeHost.GetLastJsError();
+                System.Diagnostics.Debug.WriteLine($"[NativeScript] Script exception: {scriptEx.Message}");
+                CrashDiagnostics.WriteExceptionReport("RunMainScript", scriptEx, null);
+                var report = CrashDiagnostics.BuildErrorReport(scriptEx, jsError);
+                CrashDiagnostics.WriteToTraceLog(report);
+                await CrashDiagnostics.ShowCrashDialogAsync("Script Execution Error", report);
+            }
+
+            void ShowMainWindow()
+            {
+                StartPump();
+
+                try
+                {
+                    if (CurrentWindow?.Content != null)
+                    {
+                        CurrentWindow.Activate();
+                    }
+                }
+                catch { }
+            }
+
+            // After any await, the continuation may run on a thread pool thread.
+            // Schedule all UI-thread-required operations through the dispatcher queue.
+            if (dispatcherQueue?.HasThreadAccess == true)
+            {
+                ShowMainWindow();
+            }
+            else if (!(dispatcherQueue?.TryEnqueue(ShowMainWindow) ?? false))
+            {
+                ShowMainWindow();
+            }
+        }
+
+        private void OnWindowClosed(object sender, WindowEventArgs e)
+        {
+            StopPump();
+            _runtimeHost.NotifyAppEvent((int)AppEventKind.Exit, null);
+            ApplicationData.Current.LocalSettings.Values[LastLaunchArgsKey] = string.Empty;
+            _runtimeHost.Dispose();
+        }
+
+        private void OnWindowActivated(object sender, WindowActivatedEventArgs e)
+        {
+             var kind = e.WindowActivationState == WindowActivationState.Deactivated ? AppEventKind.Deactivated : AppEventKind.Activated;
+            _runtimeHost.NotifyAppEvent((int)kind, null);
+        }
+
+        private void OnWindowVisibilityChanged(object sender, WindowVisibilityChangedEventArgs e)
+        {
+            var kind = e.Visible ? AppEventKind.Shown : AppEventKind.Hidden;
+            _runtimeHost.NotifyAppEvent((int)kind, null);
+        }
+
+        private void OnUnhandledException(object sender, Microsoft.UI.Xaml.UnhandledExceptionEventArgs e)
+        {
+            e.Handled = true;
+            var jsError = _runtimeHost.GetLastJsError();
+
+             var message = e.Message ?? jsError ?? "Unhandled exception";
+            _runtimeHost.NotifyAppEvent((int)AppEventKind.UncaughtError, message);
+
+            CrashDiagnostics.WriteExceptionReport(
+                "Xaml.UnhandledException",
+                e.Exception,
+                "JsError=" + (jsError ?? "<none>"));
+
+            var report = CrashDiagnostics.BuildErrorReport(e.Exception, jsError);
+            CrashDiagnostics.WriteToTraceLog(report);
+            var _ = CrashDiagnostics.ShowCrashDialogAsync(
+                e.Message ?? "Unhandled exception", report);
+        }
+
+        // The V8 runtime pump (JS timers + microtask/promise continuations) must NOT run *inside*
+        // CompositionTarget.Rendering: that callback executes within XAML's render walk, and the JS it
+        // pumps frequently mutates the live XAML tree (e.g. setting Image.Source when an async image
+        // load completes, or layout-invalidating writes from JS-driven animations). Mutating the tree
+        // during the render walk re-enters the XAML core illegally and trips its re-entrancy guard,
+        // which RoFailFastWithErrorContext's with E_UNEXPECTED (0x8000FFFF): a stowed exception
+        // (0xC000027B) that faults in Microsoft.UI.Xaml.dll and bypasses every managed/native handler
+        // (so it leaves no crash/panic log).
+        //
+        // Pump cadence comes from two sources, both routed through the guarded SchedulePump():
+        //   1. CompositionTarget.Rendering — fires at the display's true refresh rate (120/144/240Hz,
+        //      NOT capped at 60) while the compositor is producing frames, so JS-driven animations stay
+        //      smooth on high-refresh displays.
+        //   2. A low-frequency DispatcherQueueTimer heartbeat — keeps timers/promise continuations
+        //      running even when Rendering stops firing (e.g. the window is minimised or fully occluded,
+        //      so the compositor idles and stops raising Rendering).
+        // Either way the actual pump runs as an ordinary dispatcher work item OUTSIDE the render walk,
+        // where mutating the tree is legal. _pumpQueued keeps at most one pump in flight, so the two
+        // sources never double-pump and work items can't pile up. All fields are touched only on the UI
+        // thread, so no synchronization is needed.
+        private DispatcherQueue _dispatcherQueue;
+        private DispatcherQueueTimer _pumpHeartbeat;
+        private bool _pumpQueued;
+
+        private void StartPump()
+        {
+            _dispatcherQueue = DispatcherQueue.GetForCurrentThread();
+
+            CompositionTarget.Rendering -= OnRenderFrame;
+            CompositionTarget.Rendering += OnRenderFrame;
+
+            if (_pumpHeartbeat == null && _dispatcherQueue != null)
+            {
+                _pumpHeartbeat = _dispatcherQueue.CreateTimer();
+                _pumpHeartbeat.Interval = TimeSpan.FromMilliseconds(100);
+                _pumpHeartbeat.IsRepeating = true;
+                _pumpHeartbeat.Tick += OnPumpHeartbeat;
+                _pumpHeartbeat.Start();
+            }
+        }
+
+        private void StopPump()
+        {
+            CompositionTarget.Rendering -= OnRenderFrame;
+            if (_pumpHeartbeat != null)
+            {
+                _pumpHeartbeat.Stop();
+                _pumpHeartbeat.Tick -= OnPumpHeartbeat;
+                _pumpHeartbeat = null;
+            }
+        }
+
+        // Inside XAML's render walk — only schedule; never pump or touch the tree here.
+        private void OnRenderFrame(object sender, object e) => SchedulePump();
+
+        private void OnPumpHeartbeat(DispatcherQueueTimer sender, object args) => SchedulePump();
+
+        private void SchedulePump()
+        {
+            if (_pumpQueued)
+            {
+                return;
+            }
+
+            var dispatcherQueue = _dispatcherQueue;
+            if (dispatcherQueue == null)
+            {
+                return;
+            }
+
+            _pumpQueued = true;
+            dispatcherQueue.TryEnqueue(() =>
+            {
+                _pumpQueued = false;
+                _runtimeHost.PumpTimers();
+#if DEBUG
+                _runtimeHost.PumpDevtools();
+#endif
+            });
+        }
+    }
+}

package/framework/__PROJECT_NAME__/CrashDiagnostics.cs

@@ -0,0 +1,281 @@
+using System;
+using System.IO;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+using WinRT.Interop;
+using Windows.ApplicationModel.Core;
+using Windows.ApplicationModel.DataTransfer;
+using Windows.Storage;
+using Windows.System;
+using Windows.UI.Popups;
+
+namespace __PROJECT_NAME__
+{
+    internal static class CrashDiagnostics
+    {
+        private static bool _installed;
+
+        public static void InstallGlobalHandlers()
+        {
+            if (_installed) return;
+            _installed = true;
+
+            AppDomain.CurrentDomain.UnhandledException += (_, args) =>
+            {
+                var ex = args.ExceptionObject as Exception;
+                WriteExceptionReport("AppDomain.UnhandledException", ex, "IsTerminating=" + args.IsTerminating);
+            };
+
+            TaskScheduler.UnobservedTaskException += (_, args) =>
+            {
+                // Always mark the exception as observed to prevent the finalizer
+                // from rethrowing it on the finalizer thread.
+                try { args.SetObserved(); } catch { }
+
+                // Log the exception but never allow logging failures to propagate
+                // (this handler runs on the finalizer thread in some cases).
+                try
+                {
+                    WriteExceptionReport("TaskScheduler.UnobservedTaskException", args.Exception, null);
+                }
+                catch (Exception logEx)
+                {
+                    try { WriteToTraceLog("[CrashDiagnostics] Failed to write unobserved exception: " + logEx); } catch { }
+                }
+            };
+        }
+
+        public static void WriteExceptionReport(string source, Exception ex, string details)
+        {
+            var sb = new StringBuilder();
+            sb.AppendLine("============================================================");
+            sb.AppendLine("Timestamp: " + DateTimeOffset.UtcNow.ToString("o"));
+            sb.AppendLine("Source: " + source);
+            if (!string.IsNullOrWhiteSpace(details)) sb.AppendLine("Details: " + details);
+            if (ex != null) { sb.AppendLine("Exception:"); sb.AppendLine(ex.ToString()); }
+            else sb.AppendLine("Exception: <null>");
+            sb.AppendLine("Managed stack snapshot:");
+            sb.AppendLine(Environment.StackTrace);
+            sb.AppendLine();
+            AppendToLog(sb.ToString());
+        }
+
+        public static void WriteMessage(string source, string message)
+        {
+            var sb = new StringBuilder();
+            sb.AppendLine("============================================================");
+            sb.AppendLine("Timestamp: " + DateTimeOffset.UtcNow.ToString("o"));
+            sb.AppendLine("Source: " + source);
+            sb.AppendLine("Message: " + message);
+            sb.AppendLine();
+            AppendToLog(sb.ToString());
+        }
+
+        public static string BuildErrorReport(Exception ex, string jsError = null, string extraDetails = null)
+        {
+            var sb = new StringBuilder();
+
+            if (!string.IsNullOrWhiteSpace(jsError))
+            {
+                sb.AppendLine("── JavaScript Error ──────────────────────────────────────");
+                sb.AppendLine(jsError.Trim());
+                sb.AppendLine();
+            }
+
+            if (ex != null)
+            {
+                sb.AppendLine("── Native Exception ──────────────────────────────────────");
+                sb.AppendLine(ex.GetType().Name + ": " + ex.Message);
+                if (ex.StackTrace != null) sb.AppendLine(ex.StackTrace);
+                var inner = ex.InnerException;
+                while (inner != null)
+                {
+                    sb.AppendLine("Caused by: " + inner.GetType().Name + ": " + inner.Message);
+                    if (inner.StackTrace != null) sb.AppendLine(inner.StackTrace);
+                    inner = inner.InnerException;
+                }
+                sb.AppendLine();
+            }
+
+            // Include panic log from previous or current run
+            try
+            {
+                var panicLog = Path.Combine(ApplicationData.Current.LocalFolder.Path, "nativescript-panic.log");
+                if (File.Exists(panicLog))
+                {
+                    var content = File.ReadAllText(panicLog, Encoding.UTF8).Trim();
+                    if (!string.IsNullOrEmpty(content))
+                    {
+                        sb.AppendLine("── Rust Panic Log ────────────────────────────────────────");
+                        sb.AppendLine(content);
+                        sb.AppendLine();
+                    }
+                }
+            }
+            catch { }
+
+            if (!string.IsNullOrWhiteSpace(extraDetails))
+            {
+                sb.AppendLine("── Additional Info ───────────────────────────────────────");
+                sb.AppendLine(extraDetails);
+                sb.AppendLine();
+            }
+
+            sb.AppendLine("──────────────────────────────────────────────────────────");
+            sb.AppendLine("Timestamp: " + DateTimeOffset.UtcNow.ToString("o"));
+
+            return sb.ToString();
+        }
+
+        public static string CrashLogPath()
+        {
+            try { return Path.Combine(ApplicationData.Current.LocalFolder.Path, "nativescript-crash.log"); }
+            catch { return null; }
+        }
+
+        /// Parses the first "path:line:col" source location from a JS stack trace.
+        /// Returns null if none found. Handles Windows drive-letter paths (C:\...).
+        public static (string file, int line, int col)? TryExtractSourceLocation(string errorReport)
+        {
+            if (string.IsNullOrEmpty(errorReport)) return null;
+
+            // Match the contents of the first (path:line:col) group in the stack trace.
+            var m = Regex.Match(errorReport, @"\(([^)]+)\)");
+            if (!m.Success) return null;
+
+            var inner = m.Groups[1].Value; // e.g. "C:\app\bundle.js:42:13"
+
+            // Parse col from the right (last :digits).
+            var lastColon = inner.LastIndexOf(':');
+            if (lastColon < 0 || !int.TryParse(inner.Substring(lastColon + 1), out int col)) return null;
+            inner = inner.Substring(0, lastColon);
+
+            // Parse line from the right (second-to-last :digits).
+            lastColon = inner.LastIndexOf(':');
+            if (lastColon < 0 || !int.TryParse(inner.Substring(lastColon + 1), out int line)) return null;
+            var file = inner.Substring(0, lastColon);
+
+            return string.IsNullOrEmpty(file) ? null : (file, line, col);
+        }
+
+        public static async Task ShowCrashDialogAsync(string heading, string errorReport)
+        {
+            try
+            {
+                // Write full details to log so developer can access them even if the
+                // dialog summary is truncated.
+                var logPath = CrashLogPath();
+                if (logPath != null)
+                    File.WriteAllText(logPath, errorReport, Encoding.UTF8);
+
+                // Truncate for the dialog (MessageDialog has practical limits).
+                const int MaxLen = 800;
+                var summary = errorReport.Length > MaxLen
+                    ? errorReport.Substring(0, MaxLen) + "\n\n[truncated — see log for full details]"
+                    : errorReport;
+
+                if (logPath != null)
+                    summary += "\n\nFull log: " + logPath;
+
+                var dialog = new MessageDialog(summary, "NativeScript Runtime Error");
+                try
+                {
+                    var window = App.CurrentWindow;
+                    if (window != null)
+                    {
+                        InitializeWithWindow.Initialize(dialog, WindowNative.GetWindowHandle(window));
+                    }
+                }
+                catch { }
+
+                // MessageDialog supports at most 3 commands. When a source location is
+                // available, swap "Copy Details" for "Open in VS Code" so the user can
+                // choose between jumping to the error or restarting. Full details are
+                // always written to the log file shown in the dialog text.
+                var srcLocation = TryExtractSourceLocation(errorReport);
+                if (srcLocation.HasValue)
+                {
+                    var (srcFile, srcLine, srcCol) = srcLocation.Value;
+                    dialog.Commands.Add(new UICommand("Open Source File", async _ =>
+                    {
+                        try
+                        {
+                            var normalizedPath = srcFile.Replace('\\', '/');
+                            var uriStr = $"file:///{normalizedPath}";
+                            if (Uri.TryCreate(uriStr, UriKind.Absolute, out var fileUri))
+                                await Launcher.LaunchUriAsync(fileUri,
+                                    new LauncherOptions { DisplayApplicationPicker = true });
+                        }
+                        catch { }
+                    }));
+                }
+                else
+                {
+                    dialog.Commands.Add(new UICommand("Copy Details", _ =>
+                    {
+                        try
+                        {
+                            var dp = new DataPackage();
+                            dp.SetText(errorReport);
+                            Clipboard.SetContent(dp);
+                        }
+                        catch { }
+                    }));
+                }
+
+                dialog.Commands.Add(new UICommand("Restart App", async _ =>
+                {
+                    try { await CoreApplication.RequestRestartAsync("crash-restart"); }
+                    catch { }
+                }));
+
+                dialog.Commands.Add(new UICommand("Dismiss"));
+                dialog.DefaultCommandIndex = 0;
+                dialog.CancelCommandIndex = 2;
+
+                await dialog.ShowAsync();
+            }
+            catch (Exception ex)
+            {
+                System.Diagnostics.Debug.WriteLine("[NativeScript] Failed to show crash dialog: " + ex.Message);
+            }
+        }
+
+        /// <summary>
+        /// Appends <paramref name="message"/> to the runtime trace file in the Win32 temp path.
+        /// Prefer `console.log`; fall back to `ns_trace.log` for CLI/legacy compatibility.
+        /// In a packaged Windows app, GetTempPath() resolves inside the app container temp area,
+        /// matching Rust's std::env::temp_dir() so the CLI still sees the same log stream.
+        /// </summary>
+        public static void WriteToTraceLog(string message)
+        {
+            try
+            {
+            // System.IO.Path.GetTempPath() calls Win32 GetTempPathW() which for a packaged
+            // desktop app resolves into the container temp folder, matching Rust.
+                var temp = System.IO.Path.GetTempPath();
+                var consolePath = Path.Combine(temp, "console.log");
+                File.AppendAllText(consolePath, message, Encoding.UTF8);
+
+                // Maintain legacy compatibility: also append to ns_trace.log if it already exists
+                var legacyPath = Path.Combine(temp, "ns_trace.log");
+                if (File.Exists(legacyPath))
+                {
+                    File.AppendAllText(legacyPath, message, Encoding.UTF8);
+                }
+            }
+            catch { }
+        }
+
+        private static void AppendToLog(string content)
+        {
+            try
+            {
+                var logPath = Path.Combine(ApplicationData.Current.LocalFolder.Path, "nativescript-crash.log");
+                File.AppendAllText(logPath, content, Encoding.UTF8);
+            }
+            catch { }
+        }
+    }
+}

package/framework/__PROJECT_NAME__/Directory.Build.props

@@ -0,0 +1,15 @@
+<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
+  <!-- Default property values for manifest overrides.
+       Override these in Directory.Build.props or via /p: properties. -->
+  <PropertyGroup>
+  <AppDisplayName Condition=" '$(AppDisplayName)' == '' ">$(MSBuildProjectName)</AppDisplayName>
+    <AppDescription Condition=" '$(AppDescription)' == '' ">A NativeScript Windows application</AppDescription>
+    <Square150x150Logo Condition=" '$(Square150x150Logo)' == '' ">Assets\Square150x150Logo.png</Square150x150Logo>
+    <Square44x44Logo Condition=" '$(Square44x44Logo)' == '' ">Assets\Square44x44Logo.png</Square44x44Logo>
+    <Wide310x150Logo Condition=" '$(Wide310x150Logo)' == '' ">Assets\Wide310x150Logo.png</Wide310x150Logo>
+    <StoreLogo Condition=" '$(StoreLogo)' == '' ">Assets\StoreLogo.png</StoreLogo>
+    <LockScreenLogo Condition=" '$(LockScreenLogo)' == '' ">Assets\LockScreenLogo.png</LockScreenLogo>
+    <SplashBackgroundColor Condition=" '$(SplashBackgroundColor)' == '' ">#65ADF1</SplashBackgroundColor>
+    <SplashImage Condition=" '$(SplashImage)' == '' ">Assets\SplashScreen.png</SplashImage>
+  </PropertyGroup>
+</Project>