@bun-win32/dwrite 1.0.0

package/AI.md

@@ -0,0 +1,71 @@
+# AI Guide for @bun-win32/dwrite
+
+How to use this package, not what the Win32 API does.
+
+## Usage
+
+```ts
+import Dwrite, { SomeFlag } from '@bun-win32/dwrite';
+
+// Methods bind lazily on first call
+const result = Dwrite.SomeFunctionW(arg1, arg2);
+
+// Preload: array, single string, or no args (all symbols)
+Dwrite.Preload(['SomeFunctionW', 'AnotherFunction']);
+Dwrite.Preload('SomeFunctionW');
+Dwrite.Preload();
+```
+
+## Where To Look
+
+| Need                              | Read                 |
+| --------------------------------- | -------------------- |
+| Find a method or its MS Docs link | `structs/Dwrite.ts` |
+| Find types, enums, constants      | `types/Dwrite.ts`   |
+| Quick examples                    | `README.md`          |
+
+`index.ts` re-exports the class and all types — import from `@bun-win32/dwrite` directly.
+
+## Calling Convention
+
+All documented `dwrite.dll` exports are bound. Each method maps 1:1 to its DLL export. Names, parameter names, and order match Microsoft Docs.
+
+### Strings
+
+`W` methods take UTF-16LE NUL-terminated buffers. `A` methods take ANSI strings.
+
+```ts
+const wide = Buffer.from('Hello\0', 'utf16le');  // LPCWSTR
+Dwrite.SomeFunctionW(wide.ptr);
+
+// Reading a wide string back from a buffer:
+const text = new TextDecoder('utf-16').decode(buf).replace(/\0.*$/, '');
+```
+
+### Return types
+
+- `HANDLE`, `HWND`, etc. → `bigint`
+- `DWORD`, `UINT`, `BOOL`, `INT`, `LONG` → `number`
+- `LPVOID`, `LPWSTR`, etc. → `Pointer`
+- Win32 `BOOL` is `number` (0 or non-zero), **not** JS `boolean`. Do not compare with `=== true`.
+
+### Pointers, handles, out-parameters
+
+- **Pointer** params (`LP*`, `P*`, `Pointer`): pass `buffer.ptr` from a caller-allocated `Buffer`.
+- **Handle** params (`HANDLE`, `HWND`, etc.): pass a `bigint` value.
+- **Out-parameters**: allocate a `Buffer`, pass `.ptr`, read the result after the call.
+
+```ts
+const out = Buffer.alloc(4);
+Dwrite.SomeFunction(out.ptr);
+const value = out.readUInt32LE(0);
+```
+
+### Nullability
+
+- `| NULL` in a signature → pass `null` (optional pointer).
+- `| 0n` in a signature → pass `0n` (optional handle).
+
+## Errors and Cleanup
+
+Return values are raw. If the Win32 function uses last-error semantics, read via `GetLastError()`. Resource cleanup is your responsibility — same as raw Win32.

package/README.md

@@ -0,0 +1,66 @@
+# @bun-win32/dwrite
+
+Zero-dependency, zero-overhead Win32 DirectWrite bindings for [Bun](https://bun.sh) on Windows.
+
+## Overview
+
+`@bun-win32/dwrite` exposes the `dwrite.dll` export using [Bun](https://bun.sh)'s FFI. It provides a single class, `Dwrite`, which lazily binds the native symbol on first use. You can optionally preload it up-front via `Preload()`.
+
+`dwrite.dll` exports exactly **one** flat function — `DWriteCreateFactory`. It hands back an `IDWriteFactory`, and the entire DirectWrite surface (font enumeration, text layout, glyph metrics, ClearType/grayscale rasterization, typography, shaping) lives behind that object's COM vtable. This package binds the factory entry point; the included examples demonstrate the hand-driven COM vtable pattern (`read.u64` + `CFunction`) for everything beyond it — the same proven approach used by `@bun-win32/dxgi` and `@bun-win32/combase`.
+
+The bindings are strongly typed for a smooth DX in TypeScript.
+
+## Features
+
+- [Bun](https://bun.sh)-first ergonomics on Windows 10/11.
+- Direct FFI to `dwrite.dll` (DirectWrite font and text layout/typography engine).
+- In-source docs in `structs/Dwrite.ts` with links to Microsoft Docs.
+- Lazy binding on first call; optional eager preload (`Dwrite.Preload()`).
+- No wrapper overhead; calls map 1:1 to native APIs.
+- Strongly-typed Win32 aliases (see `types/Dwrite.ts`).
+
+## Requirements
+
+- [Bun](https://bun.sh) runtime
+- Windows 10 or later
+
+## Installation
+
+```sh
+bun add @bun-win32/dwrite
+```
+
+## Quick Start
+
+```ts
+import Dwrite, { DWRITE_FACTORY_TYPE } from '@bun-win32/dwrite';
+
+// __uuidof(IDWriteFactory) = b859ee5a-d838-4b5b-a2e8-1adc7d93db48
+const iid = Buffer.from([0x5a, 0xee, 0x59, 0xb8, 0x38, 0xd8, 0x5b, 0x4b, 0xa2, 0xe8, 0x1a, 0xdc, 0x7d, 0x93, 0xdb, 0x48]);
+
+const factory = Buffer.alloc(8);
+const hr = Dwrite.DWriteCreateFactory(DWRITE_FACTORY_TYPE.DWRITE_FACTORY_TYPE_SHARED, iid.ptr!, factory.ptr!);
+console.log(`DWriteCreateFactory → 0x${(hr >>> 0).toString(16)}`);
+
+// factory.readBigUInt64LE(0) is now an IDWriteFactory*; walk its COM vtable
+// with `read.u64` + `CFunction` (see example/font-observatory.ts).
+```
+
+> [!NOTE]
+> AI agents: see `AI.md` for the package binding contract and source-navigation guidance. It explains how to use the package without scanning the entire implementation.
+
+## Examples
+
+Run the included examples:
+
+```sh
+bun run example/glyph-forge.ts
+bun run example/font-observatory.ts
+```
+
+## Notes
+
+- Either rely on lazy binding or call `Dwrite.Preload()`.
+- `iid` is a caller-allocated 16-byte GUID buffer (`Pointer`); `factory` is a caller-allocated 8-byte slot (`Pointer`) that receives an `IUnknown*`/`IDWriteFactory*` interface pointer, read back as a `bigint`.
+- All DirectWrite objects are COM interfaces — invoke their methods through the vtable and `Release` them when finished.
+- Windows only. Bun runtime required.

package/index.ts

@@ -0,0 +1,4 @@
+import Dwrite from './structs/Dwrite';
+
+export * from './types/Dwrite';
+export default Dwrite;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "author": "Stev Peifer <stev@bell.net>",
+  "bugs": {
+    "url": "https://github.com/ObscuritySRL/bun-win32/issues"
+  },
+  "dependencies": {
+    "@bun-win32/core": "1.1.2"
+  },
+  "description": "Zero-dependency, zero-overhead Win32 DWRITE bindings for Bun (FFI) on Windows.",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "exports": {
+    ".": "./index.ts"
+  },
+  "license": "MIT",
+  "module": "index.ts",
+  "name": "@bun-win32/dwrite",
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "private": false,
+  "homepage": "https://github.com/ObscuritySRL/bun-win32#readme",
+  "repository": {
+    "type": "git",
+    "url": "git://github.com/ObscuritySRL/bun-win32.git",
+    "directory": "packages/dwrite"
+  },
+  "type": "module",
+  "version": "1.0.0",
+  "main": "./index.ts",
+  "keywords": [
+    "bun",
+    "ffi",
+    "win32",
+    "windows",
+    "dwrite",
+    "directwrite",
+    "fonts",
+    "typography",
+    "text",
+    "bindings",
+    "typescript",
+    "dll"
+  ],
+  "files": [
+    "AI.md",
+    "README.md",
+    "index.ts",
+    "structs/*.ts",
+    "types/*.ts"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "scripts": {
+    "example:font-observatory": "bun ./example/font-observatory.ts",
+    "example:glyph-forge": "bun ./example/glyph-forge.ts"
+  }
+}

package/structs/Dwrite.ts

@@ -0,0 +1,49 @@
+import { type FFIFunction, FFIType } from 'bun:ffi';
+
+import { Win32 } from '@bun-win32/core';
+
+import type { DWRITE_FACTORY_TYPE, HRESULT, LPLPVOID, REFIID } from '../types/Dwrite';
+
+/**
+ * Thin, lazy-loaded FFI bindings for `dwrite.dll`.
+ *
+ * Each static method corresponds one-to-one with a Win32 export declared in `Symbols`.
+ * The first call to a method binds the underlying native symbol via `bun:ffi` and
+ * memoizes it on the class for subsequent calls. For bulk, up-front binding, use `Preload`.
+ *
+ * Symbols are defined with explicit `FFIType` signatures and kept alphabetized.
+ * You normally do not access `Symbols` directly; call the static methods or preload
+ * a subset for hot paths.
+ *
+ * `dwrite.dll` exports exactly one flat function, `DWriteCreateFactory`. Every other
+ * DirectWrite capability is reached through the COM vtable of the `IDWriteFactory`
+ * it returns (see the package examples for the vtable-walk pattern).
+ *
+ * @example
+ * ```ts
+ * import Dwrite, { DWRITE_FACTORY_TYPE } from './structs/Dwrite';
+ *
+ * // Lazy: bind on first call
+ * const iid = Buffer.alloc(16); // __uuidof(IDWriteFactory)
+ * const factory = Buffer.alloc(8);
+ * const hr = Dwrite.DWriteCreateFactory(DWRITE_FACTORY_TYPE.DWRITE_FACTORY_TYPE_SHARED, iid.ptr, factory.ptr);
+ *
+ * // Or preload to avoid per-symbol lazy binding cost
+ * Dwrite.Preload('DWriteCreateFactory');
+ * ```
+ */
+class Dwrite extends Win32 {
+  protected static override name = 'dwrite.dll';
+
+  /** @inheritdoc */
+  protected static override readonly Symbols = {
+    DWriteCreateFactory: { args: [FFIType.u32, FFIType.ptr, FFIType.ptr], returns: FFIType.i32 },
+  } as const satisfies Record<string, FFIFunction>;
+
+  // https://learn.microsoft.com/en-us/windows/win32/api/dwrite/nf-dwrite-dwritecreatefactory
+  public static DWriteCreateFactory(factoryType: DWRITE_FACTORY_TYPE, iid: REFIID, factory: LPLPVOID): HRESULT {
+    return Dwrite.Load('DWriteCreateFactory')(factoryType, iid, factory);
+  }
+}
+
+export default Dwrite;

package/types/Dwrite.ts

@@ -0,0 +1,12 @@
+import type { Pointer } from 'bun:ffi';
+
+export type { HRESULT } from '@bun-win32/core';
+
+export enum DWRITE_FACTORY_TYPE {
+  DWRITE_FACTORY_TYPE_ISOLATED = 1,
+  DWRITE_FACTORY_TYPE_SHARED = 0,
+}
+
+export type IUnknown = Pointer;
+export type LPLPVOID = Pointer;
+export type REFIID = Pointer;