basalt-win32 0.2.7 → 0.2.8

package/README.md

@@ -0,0 +1,60 @@
+# basalt-win32
+
+The Windows half of [Basalt](https://basaltjs.dev): a Win32 and Direct2D view
+layer, a Fabric mounting manager, and a host that runs your React Native app
+as a native application.
+
+```bash
+npx basalt-core init      # adds this package when app.json asks for windows
+npm run windows -- --build
+```
+
+You rarely install this by hand. `basalt init` reads
+[`basalt.desktops`](https://basaltjs.dev/docs/reference/app-json#basaltdesktops)
+and adds the host packages the app asked for.
+
+## What it gives you
+
+Win32 windows, Direct2D for everything drawn, and DirectWrite for every line
+of text. Screen readers are answered through UI Automation. The caption
+buttons stay the system's, and an app that draws its own header answers
+`HTCAPTION` for the parts of it that should move the window.
+
+A toast needs an AppUserModelID and a Start Menu shortcut carrying it, and the
+host registers both itself at startup rather than from Node, because a `.lnk`
+with that property set means `IPropertyStore`, which means COM.
+
+It registers the `react-native run-windows` command.
+
+**Windows is the least finished of the three desktops**, and
+[the support table](https://basaltjs.dev/docs/support) says exactly where
+rather than leaving you to find out: 124 of 137 props at the time of writing,
+against 126 on Linux and 130 on macOS, with a reason beside every gap.
+
+## What you need to build it
+
+CMake, Ninja, [vcpkg](https://vcpkg.io) with `VCPKG_INSTALLATION_ROOT`
+pointing at it, and **`clang-cl`**, not just `cl`: Hermes uses
+`__builtin_expect`, which MSVC's compiler does not have.
+
+`npx basalt-core doctor` checks all of that in seconds. Worth doing before a
+first build that compiles Hermes and React Native's C++ from source and takes
+tens of minutes.
+
+Ninja is what development and CI use. The Visual Studio generator works too,
+and CI builds it on every release so that opening the project in Visual Studio
+keeps working.
+
+## What it is not
+
+Not a renderer and not a runtime. Everything behind the views is in
+[`basalt-core`](https://www.npmjs.com/package/basalt-core): React Native's own
+Hermes, Yoga, Fabric and shadow tree, the same C++ that runs on a phone. This
+package is the part ReactCommon declares and leaves for a platform to define.
+
+The host binary is `basalt_win32`, which is what shows in Task Manager and in
+a crash report rather than your app's name.
+
+## Licence
+
+MIT.

package/native/win32/Win32Snapshot.cpp

@@ -9,6 +9,7 @@
 #include <wrl/client.h>
 
 #include <cmath>
+#include <cstdlib>
 #include <string>
 
 using Microsoft::WRL::ComPtr;
@@ -43,6 +44,77 @@ std::wstring widen(const std::string &text) {
   return wide;
 }
 
+// How many device pixels to a density-independent one, from
+// BASALT_SNAPSHOT_SCALE.
+//
+// One by default, which is what every test wants: a pixel assertion is
+// written against the frames, and a snapshot that changed size with the
+// machine would compare as a difference against the other two hosts.
+//
+// Two is for a picture somebody is going to look at. macOS and Linux are
+// photographed on retina displays and in a scaled Xvfb, so a Windows shot
+// beside them at 96 dpi is visibly the soft one. Anything outside [1, 4] is
+// ignored rather than argued with.
+float snapshotScale() {
+  const char *requested = std::getenv("BASALT_SNAPSHOT_SCALE");
+  if (requested == nullptr) {
+    return 1.0f;
+  }
+  const float scale = std::strtof(requested, nullptr);
+  if (!(scale >= 1.0f) || scale > 4.0f) {
+    return 1.0f;
+  }
+  return scale;
+}
+
+// One PNG writer for both the render and the photograph, so the two cannot
+// drift into writing different files. `format` is what the frame is told to
+// hold: premultiplied BGRA for a render, which carries transparency, and BGR
+// for a window capture, where GDI leaves the alpha byte at zero and reading
+// it as alpha produces a picture of nothing.
+bool encodePng(IWICImagingFactory *wic,
+               IWICBitmapSource *source,
+               UINT width,
+               UINT height,
+               const std::string &path,
+               WICPixelFormatGUID format) {
+  const std::wstring widePath = widen(path);
+  if (widePath.empty()) {
+    return false;
+  }
+
+  ComPtr<IWICStream> stream;
+  if (FAILED(wic->CreateStream(stream.GetAddressOf())) ||
+      FAILED(stream->InitializeFromFilename(widePath.c_str(), GENERIC_WRITE))) {
+    return false;
+  }
+
+  ComPtr<IWICBitmapEncoder> encoder;
+  if (FAILED(wic->CreateEncoder(GUID_ContainerFormatPng, nullptr, encoder.GetAddressOf())) ||
+      FAILED(encoder->Initialize(stream.Get(), WICBitmapEncoderNoCache))) {
+    return false;
+  }
+
+  ComPtr<IWICBitmapFrameEncode> frameEncode;
+  if (FAILED(encoder->CreateNewFrame(frameEncode.GetAddressOf(), nullptr)) ||
+      FAILED(frameEncode->Initialize(nullptr)) || FAILED(frameEncode->SetSize(width, height))) {
+    return false;
+  }
+
+  // The encoder is allowed to answer with a format it prefers; PNG takes
+  // these, and asking is the documented way rather than an optimisation.
+  if (FAILED(frameEncode->SetPixelFormat(&format))) {
+    return false;
+  }
+
+  if (FAILED(frameEncode->WriteSource(source, nullptr)) || FAILED(frameEncode->Commit()) ||
+      FAILED(encoder->Commit())) {
+    return false;
+  }
+
+  return true;
+}
+
 // Renders the tree into a WIC bitmap. The one place the render is described, so
 // the pixels a test reads and the pixels a PNG carries cannot come out
 // different -- the same reason the text layout is built in one place and shared
@@ -53,8 +125,9 @@ bool renderToBitmap(const RnWin32View &root,
                     UINT &width,
                     UINT &height) {
   const RnRect frame = root.frame();
-  width = static_cast<UINT>(std::lround(frame.width));
-  height = static_cast<UINT>(std::lround(frame.height));
+  const float scale = snapshotScale();
+  width = static_cast<UINT>(std::lround(frame.width * scale));
+  height = static_cast<UINT>(std::lround(frame.height * scale));
   if (width == 0 || height == 0) {
     return false;
   }
@@ -80,16 +153,17 @@ bool renderToBitmap(const RnWin32View &root,
     return false;
   }
 
-  // 96 dpi explicitly, so a render is the size the frames say regardless of
-  // what the machine taking it is set to. Every coordinate in this project is
-  // in React Native's density-independent pixels, and a snapshot that silently
-  // came out at 150% on one developer's laptop would compare as a difference
-  // against every other host.
+  // 96 dpi times the scale, so a render is the size the frames say regardless
+  // of what the machine taking it is set to. Every coordinate in this project
+  // is in React Native's density-independent pixels, and a snapshot that
+  // silently came out at 150% on one developer's laptop would compare as a
+  // difference against every other host. The scale is one unless somebody
+  // asks, so every existing caller gets exactly the pixels it got before.
   const D2D1_RENDER_TARGET_PROPERTIES properties = D2D1::RenderTargetProperties(
       D2D1_RENDER_TARGET_TYPE_DEFAULT,
       D2D1::PixelFormat(DXGI_FORMAT_B8G8R8A8_UNORM, D2D1_ALPHA_MODE_PREMULTIPLIED),
-      96.0f,
-      96.0f);
+      96.0f * scale,
+      96.0f * scale);
 
   ComPtr<ID2D1RenderTarget> target;
   if (FAILED(d2d->CreateWicBitmapRenderTarget(bitmap.Get(), properties, target.GetAddressOf()))) {
@@ -159,43 +233,93 @@ bool writeSnapshot(const RnWin32View &root, const std::string &path) {
   if (!renderToBitmap(root, wic, bitmap, width, height)) {
     return false;
   }
+  return encodePng(wic.Get(), bitmap.Get(), width, height, path, GUID_WICPixelFormat32bppPBGRA);
+}
 
-  const std::wstring widePath = widen(path);
-  if (widePath.empty()) {
+bool captureWindow(void *windowHandle, const std::string &path) {
+  HWND window = static_cast<HWND>(windowHandle);
+  if (window == nullptr || IsWindow(window) == FALSE) {
     return false;
   }
 
-  ComPtr<IWICStream> stream;
-  if (FAILED(wic->CreateStream(stream.GetAddressOf())) ||
-      FAILED(stream->InitializeFromFilename(widePath.c_str(), GENERIC_WRITE))) {
+  RECT rect{};
+  if (GetWindowRect(window, &rect) == FALSE) {
     return false;
   }
-
-  ComPtr<IWICBitmapEncoder> encoder;
-  if (FAILED(wic->CreateEncoder(GUID_ContainerFormatPng, nullptr, encoder.GetAddressOf())) ||
-      FAILED(encoder->Initialize(stream.Get(), WICBitmapEncoderNoCache))) {
+  const LONG width = rect.right - rect.left;
+  const LONG height = rect.bottom - rect.top;
+  if (width <= 0 || height <= 0) {
     return false;
   }
 
-  ComPtr<IWICBitmapFrameEncode> frameEncode;
-  if (FAILED(encoder->CreateNewFrame(frameEncode.GetAddressOf(), nullptr)) ||
-      FAILED(frameEncode->Initialize(nullptr)) || FAILED(frameEncode->SetSize(width, height))) {
+  HDC screen = GetDC(nullptr);
+  if (screen == nullptr) {
     return false;
   }
-
-  // The encoder is allowed to answer with a format it prefers; PNG takes this
-  // one, and asking is the documented way rather than an optimisation.
-  WICPixelFormatGUID format = GUID_WICPixelFormat32bppPBGRA;
-  if (FAILED(frameEncode->SetPixelFormat(&format))) {
+  HDC memory = CreateCompatibleDC(screen);
+  if (memory == nullptr) {
+    ReleaseDC(nullptr, screen);
     return false;
   }
 
-  if (FAILED(frameEncode->WriteSource(bitmap.Get(), nullptr)) || FAILED(frameEncode->Commit()) ||
-      FAILED(encoder->Commit())) {
-    return false;
+  // Top-down, 32 bits, so the rows come out in the order the encoder wants
+  // and there is no flip to get wrong. A negative height is how a DIB says
+  // top-down.
+  BITMAPINFO info{};
+  info.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
+  info.bmiHeader.biWidth = width;
+  info.bmiHeader.biHeight = -height;
+  info.bmiHeader.biPlanes = 1;
+  info.bmiHeader.biBitCount = 32;
+  info.bmiHeader.biCompression = BI_RGB;
+
+  void *bits = nullptr;
+  HBITMAP dib = CreateDIBSection(memory, &info, DIB_RGB_COLORS, &bits, nullptr, 0);
+  bool wrote = false;
+  if (dib != nullptr && bits != nullptr) {
+    HGDIOBJ previous = SelectObject(memory, dib);
+    // PW_RENDERFULLCONTENT (2) is the flag that asks DWM for the composited
+    // window rather than asking the app to paint itself, which is what gets
+    // Direct2D content, child windows and the caption buttons.
+    const BOOL printed = PrintWindow(window, memory, 2);
+    SelectObject(memory, previous);
+
+    if (printed != FALSE) {
+      ComPtr<IWICImagingFactory> wic;
+      if (ensureCom() &&
+          SUCCEEDED(CoCreateInstance(
+              CLSID_WICImagingFactory, nullptr, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&wic)))) {
+        const UINT stride = static_cast<UINT>(width) * 4;
+        const UINT size = stride * static_cast<UINT>(height);
+        ComPtr<IWICBitmap> bitmap;
+        // 32bppBGR rather than BGRA: GDI leaves the alpha byte at zero, and
+        // read as alpha that is a fully transparent picture of nothing.
+        if (SUCCEEDED(wic->CreateBitmapFromMemory(
+                static_cast<UINT>(width),
+                static_cast<UINT>(height),
+                GUID_WICPixelFormat32bppBGR,
+                stride,
+                size,
+                static_cast<BYTE *>(bits),
+                bitmap.GetAddressOf()))) {
+          wrote = encodePng(
+              wic.Get(),
+              bitmap.Get(),
+              static_cast<UINT>(width),
+              static_cast<UINT>(height),
+              path,
+              GUID_WICPixelFormat32bppBGR);
+        }
+      }
+    }
   }
 
-  return true;
+  if (dib != nullptr) {
+    DeleteObject(dib);
+  }
+  DeleteDC(memory);
+  ReleaseDC(nullptr, screen);
+  return wrote;
 }
 
 } // namespace basalt::win32

package/native/win32/Win32Snapshot.h

@@ -63,4 +63,28 @@ RnPixels renderToPixels(const RnWin32View &root);
 // not be rendered or the file could not be written.
 bool writeSnapshot(const RnWin32View &root, const std::string &path);
 
+// A photograph of the live window instead of a render of the tree, through
+// `PrintWindow` with PW_RENDERFULLCONTENT, which asks DWM for what it
+// composited.
+//
+// Everything above renders `RnWin32View`s and is the right answer for a test:
+// no window has to exist, nothing has to be visible, and the result is the
+// size the frames say. Two things are not in that tree, and backlog entry 3
+// in docs/backlog/platform-windows.md has named both since 2026-10-13. A
+// `<TextInput>`'s peer is a child window, so a field renders as its
+// background with no text, no placeholder and no caret. A `<Canvas>` shows
+// the last frame delivered to the live window, which an offscreen pass never
+// had. The caption buttons are a third: DWM draws them over the app's header
+// and no view knows about them.
+//
+// So this is for a picture of the application as a person sees it, and the
+// render above stays what the tests read. It needs a real window, and the
+// pixels are the window's own, which means the machine's DPI rather than
+// BASALT_SNAPSHOT_SCALE.
+//
+// `window` is an HWND, as `void *` so this header stays free of windows.h.
+// Returns false if there is no window, if PrintWindow refused, or if the
+// file could not be written.
+bool captureWindow(void *window, const std::string &path);
+
 } // namespace basalt::win32

package/native/win32/main_win32.cpp

@@ -865,6 +865,35 @@ void writeSnapshotOf(RnWin32View *root, const std::string &path) {
   }
 }
 
+// BASALT_WINDOW_CAPTURE: photograph the live window on the way out.
+//
+// The snapshot below renders the view tree, which is what a test should read
+// and is not what a person sees: a <TextInput>'s peer is a child window, a
+// <Canvas> holds the last frame delivered to the real window, and the caption
+// buttons belong to DWM. None of those are in the tree. This asks DWM for the
+// window it composited instead, so a picture for a README has the field, the
+// canvas and the buttons in it.
+//
+// Taken before teardown, like everything else here, because it needs a window
+// that still exists. A failure is reported and otherwise ignored: a picture
+// nobody took is not a reason for an application to exit non-zero.
+void captureWindowIfRequested() {
+  const char *path = std::getenv("BASALT_WINDOW_CAPTURE");
+  if (path == nullptr) {
+    return;
+  }
+  HWND window = gHost.windows.empty() ? nullptr : gHost.main().window;
+  if (window == nullptr) {
+    std::fprintf(stderr, "no window to capture\n");
+    return;
+  }
+  if (basalt::win32::captureWindow(window, path)) {
+    std::fprintf(stderr, "captured the window to %s\n", path);
+  } else {
+    std::fprintf(stderr, "could not capture the window to %s\n", path);
+  }
+}
+
 void snapshotIfRequested() {
   const char *path = std::getenv("BASALT_SNAPSHOT");
   if (path == nullptr) {
@@ -1295,6 +1324,7 @@ void captureBeforeTeardown() {
   gQuitting = true;
   dumpTreeIfRequested();
   dumpMenuIfRequested();
+  captureWindowIfRequested();
   snapshotIfRequested();
 }
 

package/package.json

@@ -1,7 +1,17 @@
 {
   "name": "basalt-win32",
-  "version": "0.2.7",
-  "description": "The Windows view layer for basalt-core: a Win32 and Direct2D view layer, a Fabric mounting manager, and a host. Everything behind them is in basalt-core.",
+  "version": "0.2.8",
+  "description": "React Native on Windows, over Win32 and Direct2D: the view layer, the Fabric mounting manager and the host. The desktop half of Basalt; everything behind it is basalt-core.",
+  "keywords": [
+    "react-native",
+    "desktop",
+    "windows",
+    "win32",
+    "direct2d",
+    "directwrite",
+    "basalt",
+    "cross-platform"
+  ],
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -22,6 +32,6 @@
     "react-native": "*"
   },
   "dependencies": {
-    "basalt-core": "0.2.7"
+    "basalt-core": "0.2.8"
   }
 }