winui-svelte 0.0.7 → 0.0.8

package/src/tray/standalone/native.ts

@@ -1,12 +1,14 @@
 import { DynComRawMemory } from "@microsoft/dynwinrt/com/unsafe/raw";
 import { MenuItemKind } from "#src/tray/menu/types.js";
 import type { ResolvedCheck, ResolvedCommand, ResolvedMenuItem, ResolvedRadio } from "#src/tray/menu/types.js";
-import { bindDll, wideMemory } from "#src/win32-calls.js";
+import type { MenuIconCalls } from "#src/tray/tray-extras.js";
+import { bindDll, POINTER_BYTES, wideMemory } from "#src/win32-calls.js";
 
 const MIIM_STATE = 0x1;
 const MIIM_ID = 0x2;
 const MIIM_SUBMENU = 0x4;
 const MIIM_STRING = 0x40;
+const MIIM_BITMAP = 0x80;
 const MIIM_FTYPE = 0x100;
 const MFT_SEPARATOR = 0x800;
 const MFT_RADIOCHECK = 0x200;
@@ -14,13 +16,13 @@ const MFS_GRAYED = 0x3;
 const MFS_CHECKED = 0x8;
 const MFS_DEFAULT = 0x1000;
 const MENU_ITEM_INFO_SIZE = 80;
-const POINTER_BYTES = 8;
 const OFFSET_MASK = 4;
 const OFFSET_TYPE = 8;
 const OFFSET_STATE = 12;
 const OFFSET_ID = 16;
 const OFFSET_SUBMENU = 24;
 const OFFSET_TEXT = 56;
+const OFFSET_BITMAP = 72;
 const BY_POSITION = 1;
 const FIRST_COMMAND_ID = 1;
 const TPM_RIGHTBUTTON = 0x2;
@@ -29,12 +31,19 @@ const TPM_NONOTIFY = 0x80;
 const TPM_RETURNCMD = 0x100;
 const WM_NULL = 0;
 const NO_SUBMENU = 0n;
+const NO_BITMAP = 0n;
 const TAB_CODE = 9;
 const SHORTCUT_SEPARATOR = String.fromCodePoint(TAB_CODE);
 
 /** A line the user can pick in a native menu: a command, a check or a radio. */
 export type NativeChoice = ResolvedCommand | ResolvedCheck | ResolvedRadio;
 
+interface IconTheme {
+  readonly isDark: boolean;
+  readonly size: number;
+  readonly bitmaps: bigint[];
+}
+
 type TextLine = Exclude<ResolvedMenuItem, { readonly kind: typeof MenuItemKind.SEPARATOR }>;
 
 /**
@@ -56,6 +65,9 @@ export interface NativeMenu {
       readonly y: number;
     };
     readonly items: readonly ResolvedMenuItem[];
+
+    /** Whether the menu is dark now, which picks the member of an icon pair and the color of a tinted glyph. */
+    readonly isDark: boolean;
   }): NativeChoice | undefined;
 }
 
@@ -95,8 +107,12 @@ function typeOf(item: ResolvedMenuItem) {
   return (isSeparator ? MFT_SEPARATOR : 0) | (item.kind === MenuItemKind.RADIO ? MFT_RADIOCHECK : 0);
 }
 
-/** The Win32 calls that make a menu from resolved lines, bound when this is called, never when the module loads. */
-export function createMenuBuilder() {
+/**
+ * The Win32 calls that make a menu from resolved lines, bound when this is called, never when the module loads.
+ *
+ * @param options - `icons`: the calls of the `menuIcons` extra; without them no line has an icon.
+ */
+export function createMenuBuilder({ icons }: { readonly icons?: MenuIconCalls | undefined } = {}) {
   const { createPopup, destroyMenu, insertItem } = bindDll({
     dll: "user32.dll",
     functions: {
@@ -106,10 +122,11 @@ export function createMenuBuilder() {
     }
   });
 
-  function fill({ menu, items, choices }: {
+  function fill({ menu, items, choices, theme }: {
     readonly menu: bigint;
     readonly items: readonly ResolvedMenuItem[];
     readonly choices: Map<number, NativeChoice>;
+    readonly theme: IconTheme;
   }) {
     for (const [position, item] of items.entries()) {
       const isSubmenu = item.kind === MenuItemKind.SUBMENU;
@@ -118,7 +135,8 @@ export function createMenuBuilder() {
         fill({
           menu: submenu,
           items: item.items,
-          choices
+          choices,
+          theme
         });
       }
 
@@ -128,11 +146,21 @@ export function createMenuBuilder() {
         choices.set(id, item);
       }
 
+      const bitmap = bitmapOfItem({
+        item,
+        theme
+      });
+      const hasBitmap = bitmap !== NO_BITMAP;
+      if (hasBitmap) {
+        theme.bitmaps.push(bitmap);
+      }
+
       const text = wideMemory(item.kind === MenuItemKind.SEPARATOR ? "" : menuTextOf(item));
       const info = DynComRawMemory.allocate(MENU_ITEM_INFO_SIZE, POINTER_BYTES);
       try {
         info.writeU32(0, MENU_ITEM_INFO_SIZE);
-        info.writeU32(OFFSET_MASK, MIIM_FTYPE | MIIM_STATE | MIIM_ID | MIIM_SUBMENU | MIIM_STRING);
+        info.writeU32(OFFSET_MASK, MIIM_FTYPE | MIIM_STATE | MIIM_ID | MIIM_SUBMENU | MIIM_STRING | MIIM_BITMAP);
+        info.writeU64(OFFSET_BITMAP, bitmap);
         info.writeU32(OFFSET_TYPE, typeOf(item));
         info.writeU32(OFFSET_STATE, stateOf(item));
         info.writeU32(OFFSET_ID, id);
@@ -146,25 +174,57 @@ export function createMenuBuilder() {
     }
   }
 
+  function bitmapOfItem({ item, theme }: {
+    readonly item: ResolvedMenuItem;
+    readonly theme: IconTheme;
+  }) {
+    const icon = "icon" in item ? item.icon : undefined;
+    const hasIcon = icon !== undefined && icons !== undefined;
+    if (!hasIcon) {
+      return NO_BITMAP;
+    }
+
+    return icons.bitmapOf({
+      icon,
+      isDark: theme.isDark,
+      isEnabled: "isEnabled" in item && item.isEnabled,
+      isChecked: "isChecked" in item && item.isChecked,
+      size: theme.size
+    });
+  }
+
   return {
     /**
-     * Makes a popup menu, with a submenu for each submenu line to any depth.
+     * Makes a popup menu, with a submenu for each submenu line to any depth. A line with an `icon` gets
+     * a bitmap beside its label, sized for the screen scale and dimmed when the line is disabled.
      *
      * @returns The menu handle, the table from command number to line, and `destroy`, which
-     * frees the menu and its submenus.
+     * frees the menu, its submenus and the bitmaps.
      */
-    build({ items }: { readonly items: readonly ResolvedMenuItem[] }) {
+    build({ items, isDark }: {
+      readonly items: readonly ResolvedMenuItem[];
+      readonly isDark: boolean;
+    }) {
       const menu = createPopup();
       const choices = new Map<number, NativeChoice>();
+      const theme: IconTheme = {
+        isDark,
+        size: icons?.size() ?? 0,
+        bitmaps: []
+      };
       function destroy() {
         destroyMenu(menu);
+        for (const bitmap of theme.bitmaps) {
+          icons?.free(bitmap);
+        }
       }
 
       try {
         fill({
           menu,
           items,
-          choices
+          choices,
+          theme
         });
       } catch (error) {
         destroy();
@@ -185,8 +245,8 @@ export function createMenuBuilder() {
  * loads. It does not theme itself: the menu follows the process's preferred app mode, which the
  * caller sets before `choose` (see `createMenuTheme`).
  */
-export function createNativeMenu() {
-  const builder = createMenuBuilder();
+export function createNativeMenu({ icons }: { readonly icons?: MenuIconCalls | undefined } = {}) {
+  const builder = createMenuBuilder({ icons });
   const { trackPopup, postMessage } = bindDll({
     dll: "user32.dll",
     functions: {
@@ -196,8 +256,11 @@ export function createNativeMenu() {
   });
 
   const native: NativeMenu = {
-    choose({ owner, point, items }) {
-      const built = builder.build({ items });
+    choose({ owner, point, items, isDark }) {
+      const built = builder.build({
+        items,
+        isDark
+      });
       try {
         const chosen = trackPopup(
           built.menu,

package/src/tray/standalone/standalone-tray.ts

@@ -10,7 +10,14 @@ import { createTrayNative } from "#src/tray/native.js";
 import type { TrayNative } from "#src/tray/native.js";
 import { createTrayCore } from "#src/tray/tray-core.js";
 import type { TrayIconOptions, TrayScheduler } from "#src/tray/tray-core.js";
-import type { BalloonsExtra, ImageOf, TrayExtra, TrayHandle } from "#src/tray/tray-extras.js";
+import type {
+  BalloonsExtra,
+  ImageOf,
+  MenuIconCalls,
+  MenuIconsExtra,
+  TrayExtra,
+  TrayHandle
+} from "#src/tray/tray-extras.js";
 
 /** The menu of `createStandaloneTray`; `ItemId` is the union of the ids of `menu`. */
 interface StandaloneMenuOptions<ItemId extends string, Extras extends readonly TrayExtra[]>
@@ -20,7 +27,8 @@ interface StandaloneMenuOptions<ItemId extends string, Extras extends readonly T
 
   /**
    * The optional parts of the icon, each one import: `balloons` adds `notify`, `bounds` adds `bounds`,
-   * `themedIcon` lets `icon` follow the taskbar theme. None of their code is in the bundle unless passed.
+   * `themedIcon` lets `icon` follow the taskbar theme, `menuIcons` draws the icons of the menu's lines.
+   * None of their code is in the bundle unless passed.
    */
   readonly extras?: Extras;
 
@@ -28,7 +36,8 @@ interface StandaloneMenuOptions<ItemId extends string, Extras extends readonly T
    * The menu a right click opens, in the model of `winui-svelte/tray/menu`: commands, checks, radios,
    * submenus to any depth, separators and headers. A separator needs an `id` like every line. On this
    * renderer a submenu's own `onselect` and `autoExpand` do nothing (Windows opens a submenu row and
-   * reports no pick) and an `icon` is not drawn. None means a right click does nothing. A function makes
+   * reports no pick) and an `icon` is drawn only with the `menuIcons` extra in `extras`. None means a right
+   * click does nothing. A function makes
    * the lines each time the menu opens, which is how a tray written as markup keeps its variables current.
    */
   readonly menu?: ReadonlyArray<MenuItem<ItemId>> | (() => ReadonlyArray<MenuItem<ItemId>>) | undefined;
@@ -76,6 +85,10 @@ function isBalloons(extra: TrayExtra): extra is BalloonsExtra {
   return extra.kind === "balloons";
 }
 
+function isMenuIcons(extra: TrayExtra): extra is MenuIconsExtra {
+  return extra.kind === "menuIcons";
+}
+
 // The menu runs a message loop of its own on the only thread there is, and ends only when the user
 // picks a line or a click lands elsewhere; a click elsewhere is seen only when the owner is in front.
 const FOCUS_ATTEMPTS = 3;
@@ -137,6 +150,7 @@ export function createStandaloneTray<
   const { menu: source } = options;
   let menu = options.nativeMenu;
   let theme = options.menuTheme;
+  let icons: MenuIconCalls | undefined;
 
   function resolved() {
     const { profile } = options;
@@ -151,7 +165,8 @@ export function createStandaloneTray<
     readonly x: number;
     readonly y: number;
   }) {
-    menu ??= createNativeMenu();
+    icons ??= extras.find(isMenuIcons)?.createCalls();
+    menu ??= createNativeMenu({ icons });
     theme ??= createMenuTheme();
     const owner = native.createOwnerWindow();
     let choice: NativeChoice | undefined;
@@ -165,10 +180,12 @@ export function createStandaloneTray<
       }
 
       do {
-        theme.apply(options.colorScheme ?? MenuColorScheme.SYSTEM);
+        const colorScheme = options.colorScheme ?? MenuColorScheme.SYSTEM;
+        theme.apply(colorScheme);
         choice = menu.choose({
           owner,
           point,
+          isDark: icons?.isDark(colorScheme) ?? false,
           items: resolved()
         });
 
@@ -176,6 +193,10 @@ export function createStandaloneTray<
           choice.select();
         }
       } while (choice?.staysOpen);
+
+      if (choice) {
+        native.allowForeground();
+      }
     } finally {
       native.destroyWindow(owner);
     }

package/src/tray/themed-icon.ts

@@ -1,11 +1,5 @@
+import { createLightReader, PersonalizeValue } from "./personalize.ts";
 import type { ThemedIconExtra } from "./tray-extras.ts";
-import { bindDll, wideMemory, withMemory } from "#src/win32-calls.js";
-
-const DWORD_BYTES = 4;
-const HKEY_CURRENT_USER = 0x80000001n;
-const REG_DWORD_ONLY = 0x10;
-const PERSONALIZE_KEY = String.raw`Software\Microsoft\Windows\CurrentVersion\Themes\Personalize`;
-const LIGHT_THEME_VALUE = "SystemUsesLightTheme";
 
 /**
  * The extra that lets a tray icon's `icon` be `{ forLightTaskbar, forDarkTaskbar }`: pass it in `extras`
@@ -14,35 +8,9 @@ const LIGHT_THEME_VALUE = "SystemUsesLightTheme";
 export const themedIcon: ThemedIconExtra = {
   kind: "themedIcon",
   createReader() {
-    const { registryValue } = bindDll({
-      dll: "advapi32.dll",
-      functions: {
-        registryValue: ["RegGetValueW", ["pointer", "pointer", "pointer", "u32", "pointer", "pointer", "pointer"], "i32"]
-      }
-    });
-    return () => withMemory({
-      size: 2 * DWORD_BYTES,
-      alignment: DWORD_BYTES,
-      use(buffer) {
-        buffer.writeU32(DWORD_BYTES, DWORD_BYTES);
-        const subKey = wideMemory(PERSONALIZE_KEY);
-        const valueName = wideMemory(LIGHT_THEME_VALUE);
-        try {
-          const result = registryValue(
-            HKEY_CURRENT_USER,
-            subKey,
-            valueName,
-            REG_DWORD_ONLY,
-            null,
-            buffer,
-            buffer.pointer(DWORD_BYTES).address
-          );
-          return result === 0 && buffer.readU32(0) !== 0;
-        } finally {
-          subKey.release();
-          valueName.release();
-        }
-      }
+    return createLightReader({
+      value: PersonalizeValue.TASKBAR_IS_LIGHT,
+      isLightWhenMissing: false
     });
   }
 };

package/src/tray/tray-core.ts

@@ -1,4 +1,4 @@
-import { createClickDetector } from "./click-detector.ts";
+import { createClickDetector, TrayGesture } from "./click-detector.ts";
 import type { TrayPointerEvent } from "./click-detector.ts";
 import { NotifyOperation } from "./native.ts";
 import type {
@@ -182,6 +182,11 @@ export function createTrayCore<const Extras extends readonly TrayExtra[]>(option
         contextMenu: options.oncontextmenu,
         middleClick: options.onmiddleclick
       };
+      const isMenu = event.gesture === TrayGesture.contextMenu;
+      if (!isMenu) {
+        native.allowForeground();
+      }
+
       handlers[event.gesture]?.(event);
     }
   });

package/src/tray/tray-extras.ts

@@ -1,4 +1,6 @@
+import type { MenuIcon } from "./menu/types.ts";
 import type { Balloon, BalloonWriter, NotifyOperation, ScreenRect } from "./native.ts";
+import type { MenuColorScheme } from "./standalone/menu-theme.ts";
 import type { BalloonOptions, TrayIconImage } from "./tray-core.ts";
 
 /** What an extra may use of a live tray icon. */
@@ -37,8 +39,35 @@ export interface ThemedIconExtra {
   createReader(): () => boolean;
 }
 
-/** One of the three optional parts of a tray icon. */
-export type TrayExtra = BalloonsExtra | BoundsExtra | ThemedIconExtra;
+/** What the popup menu calls to draw the icon of a line. */
+export interface MenuIconCalls {
+  /** The side of a menu bitmap, in pixels, at the screen's scale. */
+  size(): number;
+
+  /** Whether a menu of this color scheme is dark now, read fresh on each call. */
+  isDark(colorScheme: MenuColorScheme): boolean;
+
+  /** Makes the premultiplied bitmap of an icon for the theme; 0n when the picture cannot be read. */
+  bitmapOf(options: {
+    readonly icon: MenuIcon;
+    readonly isDark: boolean;
+    readonly isEnabled: boolean;
+    readonly isChecked: boolean;
+    readonly size: number;
+  }): bigint;
+
+  /** Frees a bitmap `bitmapOf` made. */
+  free(bitmap: bigint): void;
+}
+
+/** The extra that draws the `icon` of the lines of a standalone tray's menu. Import `menuIcons`. */
+export interface MenuIconsExtra {
+  readonly kind: "menuIcons";
+  createCalls(): MenuIconCalls;
+}
+
+/** One of the four optional parts of a tray icon. */
+export type TrayExtra = BalloonsExtra | BoundsExtra | ThemedIconExtra | MenuIconsExtra;
 
 type HasExtra<Extras extends readonly TrayExtra[], Kind extends TrayExtra["kind"]> =
   [Extract<Extras[number], { readonly kind: Kind }>] extends [never] ? false : true;

package/src/web-apis/eye-dropper.ts

@@ -1,10 +1,10 @@
 import { DomErrorName, domException } from "./dom-exception.ts";
 import { defineProperty } from "./install.ts";
 import { createCursorReader } from "#src/tray/native.js";
-import { createKeyStateReader, createScreenPixelReader } from "#src/web-apis/native.js";
+import { createScreenPixelReader } from "#src/web-apis/native.js";
+import { createKeyStateReader, PointerButtonKey } from "#src/win32-key-state.js";
 
 const POLL_MILLISECONDS = 16;
-const VIRTUAL_KEY_LEFT_BUTTON = 0x01;
 const VIRTUAL_KEY_ESCAPE = 0x1b;
 const HEX_RADIX = 16;
 const HEX_DIGITS = 2;
@@ -69,11 +69,15 @@ function delay(milliseconds: number) {
 export function windowsScreenPicker() {
   const readCursor = createCursorReader();
   const readPixel = createScreenPixelReader();
-  const isDown = createKeyStateReader();
+  const readKey = createKeyStateReader();
+
+  function isDown(virtualKey: number) {
+    return readKey(virtualKey).isDown;
+  }
 
   return {
     async pick({ signal }) {
-      let isHeld = isDown(VIRTUAL_KEY_LEFT_BUTTON);
+      let isHeld = isDown(PointerButtonKey.left);
       for (;;) {
         signal?.throwIfAborted();
         const isCancelled = isDown(VIRTUAL_KEY_ESCAPE);
@@ -81,7 +85,7 @@ export function windowsScreenPicker() {
           return undefined;
         }
 
-        const isPressed = isDown(VIRTUAL_KEY_LEFT_BUTTON);
+        const isPressed = isDown(PointerButtonKey.left);
         const isNewPress = isPressed && !isHeld;
         isHeld = isPressed;
 

package/src/web-apis/native.ts

@@ -1,7 +1,6 @@
 import { DynWin32, DynWin32Unsafe } from "@microsoft/dynwinrt/win32/unsafe";
 import { addressOf, bind, numberOf, pointerOf } from "#src/win32-calls.js";
 
-const KEY_DOWN_BIT = 0x8000;
 const INVALID_COLOR = 0xffffffff;
 const BYTE_MASK = 0xff;
 const GREEN_SHIFT = 8;
@@ -54,22 +53,3 @@ export function createScreenPixelReader() {
     }
   };
 }
-
-/**
- * Reads whether a key or mouse button is held down, by virtual key code. It
- * only reads; nothing is sent.
- *
- * @returns A function from a virtual key code to whether it is down now.
- */
-export function createKeyStateReader() {
-  const keyState = bind({
-    dll: "user32.dll",
-    entryPoint: "GetAsyncKeyState",
-    parameters: ["i32"],
-    returnType: "i32"
-  });
-  return (virtualKey: number) => {
-    const state = numberOf(keyState.invoke([DynWin32.i32(virtualKey)]).returnValue);
-    return (state & KEY_DOWN_BIT) !== 0;
-  };
-}

package/src/win2d/activation-failure.ts

@@ -0,0 +1,35 @@
+import { hasPackageIdentity } from "#src/window/package-identity.js";
+
+// A Win2D class that a packaged process cannot activate is almost always the
+// manifest's doing, and the error says only which class, once per class:
+// this words it once for the process, naming the fix.
+
+const NOT_REGISTERED = "0x80040154";
+const WIN2D_CLASS = "Microsoft.Graphics.Canvas.";
+const PACKAGED_HINT = "Win2D is not registered in this package: add win2dActivatableClasses() of winui-svelte/win2d/manifest to the package's <Extensions> in AppxManifest.xml, with Microsoft.Graphics.Canvas.dll in the package (API.md, Win2D, Packaged apps)";
+
+let isHinted = false;
+
+/**
+ * What to write for a failure of a Win2D effect or drawing: in a packaged
+ * process, a Win2D class that is not registered is one message that names the
+ * manifest fragment, written once; anything else is the error's own message.
+ *
+ * @param error - What was thrown.
+ * @returns The line to write, or null when it was already written.
+ */
+export function win2dFailureMessage(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  const isUnregistered = message.includes(NOT_REGISTERED) && message.includes(WIN2D_CLASS);
+  const isPackagedUnregistered = isUnregistered && hasPackageIdentity();
+  if (!isPackagedUnregistered) {
+    return message;
+  }
+
+  if (isHinted) {
+    return null;
+  }
+
+  isHinted = true;
+  return PACKAGED_HINT;
+}

package/src/win2d/element-lifecycle.ts

@@ -1,3 +1,4 @@
+import { win2dFailureMessage } from "./activation-failure.ts";
 import type { FrameworkElement } from "#winui/microsoft/ui/xaml/FrameworkElement";
 
 // What the controllers that draw on an element's Composition visual have in
@@ -74,7 +75,11 @@ export class ElementFollower {
         height
       });
     } catch (error) {
-      process.stderr.write(`winui-svelte css: ${error instanceof Error ? error.message : String(error)}${NEWLINE}`);
+      const message = win2dFailureMessage(error);
+      const isWritten = message !== null;
+      if (isWritten) {
+        process.stderr.write(`winui-svelte css: ${message}${NEWLINE}`);
+      }
     }
   }
 }

package/src/win2d/manifest.ts

@@ -0,0 +1,78 @@
+import { readdirSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+// What a packaged app's manifest must say for Win2D to activate: a package's
+// registration catalogue holds only the classes its manifest declares (and
+// those of its framework packages), and Win2D ships no framework package, so
+// every Win2D class the app uses is an `ActivatableClass` of an
+// `InProcessServer` that names Microsoft.Graphics.Canvas.dll inside the
+// package. Unpackaged, `initWindowsAppSdk` puts the library's folder on PATH
+// and the class is found without any of this.
+
+const WIN2D_NAMESPACE = "Microsoft.Graphics.Canvas";
+const ANCHOR_CLASS = "microsoft/graphics/canvas/CanvasDevice";
+const ACTIVATION_PATTERN = /activationFactory\('(Microsoft\.Graphics\.Canvas\.[^']+)'/g;
+const THREADING_MODEL = "both";
+
+const IN_PROCESS_SERVER_CATEGORY = "windows.activatableClass.inProcessServer";
+
+function bindingsFolder() {
+  const anchor = fileURLToPath(import.meta.resolve(`#winui/${ANCHOR_CLASS}`));
+  return path.resolve(path.dirname(anchor), "..", "..", "..");
+}
+
+function bindingFiles(folder: string) {
+  return readdirSync(folder, {
+    withFileTypes: true,
+    recursive: true
+  }).filter(entry => entry.isFile() && entry.name.endsWith(".js")).map(entry => path.join(entry.parentPath, entry.name));
+}
+
+/**
+ * Every Win2D class the bindings activate by name, sorted.
+ *
+ * @param options - `bindings`: the folder the `#winui` bindings are generated
+ *     into; the library's own by default.
+ * @returns Full class names such as `Microsoft.Graphics.Canvas.Effects.GaussianBlurEffect`.
+ */
+export function win2dClassNames({ bindings = bindingsFolder() }: { bindings?: string } = {}) {
+  const names = new Set<string>();
+  for (const file of bindingFiles(path.join(bindings, ...WIN2D_NAMESPACE.toLowerCase().split(".")))) {
+    for (const match of readFileSync(file, "utf8").matchAll(ACTIVATION_PATTERN)) {
+      names.add(match[1] ?? "");
+    }
+  }
+
+  return [...names].sort();
+}
+
+/**
+ * The manifest fragment that lets a packaged app activate Win2D: one
+ * `InProcessServer` with an `ActivatableClass` per class. Put it in the
+ * package's own `<Extensions>` (a child of `<Package>`, after
+ * `<Capabilities>`), not the application's, and ship
+ * `Microsoft.Graphics.Canvas.dll` at `libraryPath` (`bin\x64\...`, which
+ * `buildApp` writes); an x64 and an arm64 package each need their own path.
+ *
+ * @param options - `libraryPath`: where the DLL is inside the package,
+ *     relative to its root. `classes`: the classes to list, every Win2D class
+ *     the bindings hold by default. `bindings`: where those bindings are.
+ * @returns The `<Extension>` element.
+ */
+export function win2dActivatableClasses({ libraryPath, classes, bindings }: {
+  libraryPath: string;
+  classes?: readonly string[];
+  bindings?: string;
+}) {
+  const listed = classes ?? win2dClassNames(bindings === undefined ? {} : { bindings });
+  const entries = listed.map(name => `    <ActivatableClass ActivatableClassId="${name}" ThreadingModel="${THREADING_MODEL}" />`);
+  return [
+    `<Extension Category="${IN_PROCESS_SERVER_CATEGORY}">`,
+    "  <InProcessServer>",
+    `    <Path>${libraryPath.replaceAll("/", "\\")}</Path>`,
+    ...entries,
+    "  </InProcessServer>",
+    "</Extension>"
+  ].join("\n");
+}

package/src/win32/index.ts

@@ -0,0 +1,19 @@
+// The Win32 seam: the few pieces a consumer needs to call a function of a
+// DLL that WinRT has no equivalent for, over the same binder the package uses.
+// An escape hatch, not a stable API: parameter and return types are strings,
+// the caller owns the lifetime of memory it allocates, and
+// `@microsoft/dynwinrt` is a preview, so this surface may change with it.
+// `bind` takes values that `DynWin32` makes; `bindDll` takes plain numbers,
+// bigints, strings and memory and gives back plain numbers and addresses.
+// The registry has its own typed entry (`winui-svelte/app/activation`).
+export {
+  addressOf,
+  bind,
+  bindDll,
+  numberOf,
+  pointerOf,
+  WIDE_CHAR_BYTES,
+  wideMemory,
+  withMemory
+} from "#src/win32-calls.js";
+export { hasPackageIdentity } from "#src/window/package-identity.js";

package/src/win32-calls.ts

@@ -8,7 +8,14 @@ import type { DynWin32Value } from "@microsoft/dynwinrt/win32/unsafe";
 
 /** The size of a UTF-16 code unit, in bytes. */
 export const WIDE_CHAR_BYTES = 2;
-const NO_ADDRESS = 0n;
+/** The size of a pointer, in bytes. */
+export const POINTER_BYTES = 8;
+
+/** The size of a DWORD or a 32-bit integer, in bytes. */
+export const DWORD_BYTES = 4;
+
+/** The address of a null pointer. */
+export const NO_ADDRESS = 0n;
 
 /** A Win32 function to bind: its DLL, name, parameter types and return type (`pointer`, `i32`, `u32`, `i64`). */
 interface BindOptions {