From 1879b7eeca221ac7c1e51a9c1d7a3f608d555ee0 Mon Sep 17 00:00:00 2001
From: freya <freya@nix.place>
Date: Fri, 9 Jan 2026 16:04:14 -0600
Subject: [PATCH] Note that Windows API handles should be u64, not ptr (#25886)

### What does this PR do?

Update FFI documentation with a note on Windows API handle values, as
pointer encoding to double causes intermittent failures with some
classes of handles.

Putting it in this accordion feels less than ideal but it's also a very
specific use case.

The specific issue I experienced: HDCs and HBITMAPs are basically 32
bits, although they are typedef'd in the headers to HANDLE. They are
returned from and passed to the GDI APIs as sign-extended versions of
the underlying 32-bit value, and so when going through the ptr <->
double pathway of bun FFI, the bottom 11 bits of those values are lost
if the original value had bit 31 set, and subsequent calls will fail.
Probably this is fixable by correctly encoding 'negative' pointers in
the double representation, and I might tackle that if I find time.
---
 docs/runtime/ffi.mdx | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/docs/runtime/ffi.mdx b/docs/runtime/ffi.mdx
index 002765a7b2..d64e3e7dbe 100644
--- a/docs/runtime/ffi.mdx
+++ b/docs/runtime/ffi.mdx
@@ -358,6 +358,8 @@ Bun represents [pointers](<https://en.wikipedia.org/wiki/Pointer_(computer_progr
 
 **Why not `BigInt`?** `BigInt` is slower. JavaScript engines allocate a separate `BigInt` which means they can't fit into a regular JavaScript value. If you pass a `BigInt` to a function, it will be converted to a `number`
 
+**Windows Note**: The Windows API type HANDLE does not represent a virtual address, and using `ptr` for it will *not* work as expected. Use `u64` to safely represent HANDLE values.
+
 </Accordion>
 
 To convert from a `TypedArray` to a pointer: