winui-svelte 0.0.7 → 0.0.8

package/src/window/dpi-awareness.ts

@@ -0,0 +1,162 @@
+import { bindDll } from "#src/win32-calls.js";
+
+// The process's DPI awareness, apart from the window runtime: it imports no
+// WinRT, so it runs on a host's main thread before anything else. Bound when
+// called, never when the module loads.
+
+/** How a process is told the pixels of a display: from not at all to per monitor. */
+export const DpiAwareness = {
+  unaware: "unaware",
+  system: "system",
+  perMonitor: "per-monitor",
+  perMonitorV2: "per-monitor-v2"
+} as const;
+
+/** One of the `DpiAwareness` values. */
+export type DpiAwareness = (typeof DpiAwareness)[keyof typeof DpiAwareness];
+
+/** From the lowest awareness to the highest: a later one satisfies an earlier request. */
+const AWARENESS_ORDER = [
+  DpiAwareness.unaware,
+  DpiAwareness.system,
+  DpiAwareness.perMonitor,
+  DpiAwareness.perMonitorV2
+] as const;
+
+/** The pseudo handles of `DPI_AWARENESS_CONTEXT`, signed as Windows defines them; the one table. */
+export const DPI_CONTEXT_HANDLES = {
+  [DpiAwareness.unaware]: -1n,
+  [DpiAwareness.system]: -2n,
+  [DpiAwareness.perMonitor]: -3n,
+  [DpiAwareness.perMonitorV2]: -4n
+} as const;
+
+const UNAWARE_GDI_SCALED_HANDLE = -5n;
+const POINTER_BITS = 64;
+
+/**
+ * The awareness a pseudo handle stands for.
+ *
+ * @param handle - A `DPI_AWARENESS_CONTEXT` pseudo handle, signed or as a 64-bit address.
+ * @returns The awareness; undefined for a handle that is not one of the pseudo values.
+ */
+export function awarenessOfHandle(handle: bigint) {
+  const signed = BigInt.asIntN(POINTER_BITS, handle);
+  const isGdiScaled = signed === UNAWARE_GDI_SCALED_HANDLE;
+  if (isGdiScaled) {
+    return DpiAwareness.unaware;
+  }
+
+  return AWARENESS_ORDER.find(awareness => DPI_CONTEXT_HANDLES[awareness] === signed);
+}
+
+/**
+ * The awareness the process asked for was refused and what it has is lower;
+ * a manifest or an earlier call set it, or a window already exists.
+ */
+export class DpiAwarenessTooLow extends Error {
+  /** What the process asked for. */
+  readonly requested: DpiAwareness;
+
+  /** What the process has. */
+  readonly current: DpiAwareness;
+
+  constructor({ requested, current }: {
+    readonly requested: DpiAwareness;
+    readonly current: DpiAwareness;
+  }) {
+    super(`The process is ${current} DPI aware and cannot become ${requested}: set the awareness before the first window exists, or in the application manifest`);
+    this.requested = requested;
+    this.current = current;
+  }
+}
+
+/** The two native steps `ensureDpiAwareness` takes, so a test can stand in for them. */
+export interface DpiAwarenessCalls {
+  /** Asks Windows to make the process this aware; true when it did. */
+  readonly setProcess: (awareness: DpiAwareness) => boolean;
+
+  /** What the process is now. */
+  readonly current: () => DpiAwareness;
+}
+
+function rankOf(awareness: DpiAwareness) {
+  return AWARENESS_ORDER.indexOf(awareness);
+}
+
+/**
+ * Asks for an awareness; refusal is success when the process already has at
+ * least that (a manifest or an earlier call set it).
+ *
+ * @param options - `requested`, and the native `calls`.
+ * @throws {DpiAwarenessTooLow} when refused and the process has less
+ */
+export function ensureDpiAwareness({ requested, calls }: {
+  readonly requested: DpiAwareness;
+  readonly calls: DpiAwarenessCalls;
+}) {
+  const isSet = calls.setProcess(requested);
+  if (isSet) {
+    return;
+  }
+
+  const current = calls.current();
+  const isSufficient = rankOf(current) >= rankOf(requested);
+  if (!isSufficient) {
+    throw new DpiAwarenessTooLow({
+      requested,
+      current
+    });
+  }
+}
+
+function bindUser32() {
+  return bindDll({
+    dll: "user32.dll",
+    functions: {
+      setProcess: ["SetProcessDpiAwarenessContext", ["pointer"], "i32"],
+      thread: ["GetThreadDpiAwarenessContext", [], "pointer"],
+      areEqual: ["AreDpiAwarenessContextsEqual", ["pointer", "pointer"], "i32"]
+    }
+  });
+}
+
+function handleArgument(awareness: DpiAwareness) {
+  return BigInt.asUintN(POINTER_BITS, DPI_CONTEXT_HANDLES[awareness]);
+}
+
+/**
+ * What this process is now, from `GetThreadDpiAwarenessContext`.
+ *
+ * @returns The awareness; `unaware` for the GDI-scaled flavour of it.
+ */
+export function processDpiAwareness() {
+  const user32 = bindUser32();
+  const context = user32.thread();
+  function isEqual(awareness: DpiAwareness) {
+    return user32.areEqual(context, handleArgument(awareness)) !== 0;
+  }
+
+  return [...AWARENESS_ORDER].reverse().find(isEqual) ?? DpiAwareness.unaware;
+}
+
+/**
+ * Asks Windows for a process-wide awareness. Call it on the main thread
+ * before any window exists: user32 allows it once, and a library that created
+ * a window first keeps an unaware process.
+ *
+ * @param requested - The awareness to ask for.
+ * @throws {DpiAwarenessTooLow} when refused and the process has less
+ */
+export function requestDpiAwareness(requested: DpiAwareness) {
+  const user32 = bindUser32();
+  ensureDpiAwareness({
+    requested,
+    calls: {
+      setProcess(awareness) {
+        return user32.setProcess(handleArgument(awareness)) !== 0;
+      },
+      current: processDpiAwareness
+    }
+  });
+}

package/src/window/foreground-native.ts

@@ -1,11 +1,11 @@
 import type { ForegroundSource } from "./foreground-filter.ts";
 import { DynComRawMemory } from "@microsoft/dynwinrt/com/unsafe/raw";
-import { bindDll, WIDE_CHAR_BYTES, wideMemory } from "#src/win32-calls.js";
+import { bindDll, DWORD_BYTES, WIDE_CHAR_BYTES, wideMemory } from "#src/win32-calls.js";
+import { FOREGROUND_QUERY_CALLS } from "#src/win32-foreground.js";
 
 // The Win32 calls behind foreground tracking. Bound when a function is called, never when the module loads.
 
 const CLASS_NAME_CHARS = 256;
-const DWORD_BYTES = 4;
 const WS_POPUP = 0x80000000;
 const NO_WINDOW = 0n;
 const SHELL_HOOK_MESSAGE = "SHELLHOOK";
@@ -15,10 +15,8 @@ function bindUser32() {
   return bindDll({
     dll: "user32.dll",
     functions: {
-      foreground: ["GetForegroundWindow", [], "pointer"],
+      ...FOREGROUND_QUERY_CALLS,
       className: ["GetClassNameW", ["pointer", "pointer", "i32"], "i32"],
-      threadOf: ["GetWindowThreadProcessId", ["pointer", "pointer"], "u32"],
-      isWindow: ["IsWindow", ["pointer"], "i32"],
       createWindow: [
         "CreateWindowExW",
         ["u32", "pointer", "pointer", "u32", "i32", "i32", "i32", "i32", "pointer", "pointer", "pointer", "pointer"],

package/src/window/index.ts

@@ -4,6 +4,8 @@ export type { AppWindow, WindowOptions } from "./create-window.ts";
 export { Backdrop } from "./backdrop.ts";
 export type { WindowBounds, WindowSize } from "./anchor.ts";
 export { SizeToContent, WindowAnchor } from "./anchor.ts";
+export type { CoverOptions } from "./cover.ts";
+export { coverWindow } from "./cover.ts";
 export type { DockOptions } from "./dock.ts";
 export { displayAreaOf, DockDisplay, dockWindow } from "./dock.ts";
 export type { CaptionButtonColors, WindowRegion } from "./chrome.ts";

package/src/window/native.ts

@@ -9,6 +9,7 @@ import {
   addressOf,
   bind,
   numberOf,
+  POINTER_BYTES,
   pointerOf,
   wideMemory,
   withMemory
@@ -598,7 +599,6 @@ export function requestFineTimerResolution() {
 
 const LOOP_OFFSET = 8;
 const IOCP_OFFSET = 56;
-const POINTER_BYTES = 8;
 const POINTER_ALIGNMENT = 8;
 const OBJECT_TYPE_BUFFER_BYTES = 256;
 const OBJECT_TYPE_NAME_LENGTH_OFFSET = 0;

package/src/window/package-identity.ts

@@ -0,0 +1,112 @@
+import type { DynComRawMemory } from "@microsoft/dynwinrt/com/unsafe/raw";
+import { bindDll, DWORD_BYTES, POINTER_BYTES, withMemory } from "#src/win32-calls.js";
+
+// Two questions of the process's package identity, answered with kernel32 calls
+// only, no WinRT: this module is on the path of `winui-svelte/bootstrap`, which
+// promises to import nothing of WinRT. GetCurrentPackageFullName (appmodel.h)
+// is the cheap check: called with a zero length it answers
+// APPMODEL_ERROR_NO_PACKAGE outside a package and ERROR_INSUFFICIENT_BUFFER
+// inside one. GetCurrentPackageInfo lists the package graph, whose framework
+// packages tell whether the Windows App SDK is already loaded for the process.
+
+const NO_PACKAGE_ERROR = 15_700;
+const INSUFFICIENT_BUFFER_ERROR = 122;
+const SUCCESS = 0;
+const PACKAGE_FILTER_HEAD = 0x10;
+const PACKAGE_FILTER_DIRECT = 0x20;
+const FRAMEWORK_PREFIX = "Microsoft.WindowsAppRuntime";
+// PACKAGE_INFO on 64-bit Windows: reserved, flags, path, full name, family name,
+// then the PACKAGE_ID (reserved, architecture, version, name, publisher, ...).
+const PACKAGE_INFO_BYTES = 80;
+const NAME_OFFSET = 48;
+const COUNT_OFFSET = DWORD_BYTES;
+
+const appModel = bindDll({
+  dll: "kernel32.dll",
+  functions: {
+    currentPackageFullName: ["GetCurrentPackageFullName", ["pointer", "pointer"], "i32"],
+    currentPackageInfo: ["GetCurrentPackageInfo", ["u32", "pointer", "pointer", "pointer"], "i32"]
+  }
+});
+
+/**
+ * Whether this process has a package identity (MSIX, or a sparse package).
+ *
+ * @returns False for plain Node.js, Electron and `pnpm dev`.
+ */
+export function hasPackageIdentity() {
+  return withMemory({
+    size: DWORD_BYTES,
+    alignment: DWORD_BYTES,
+    use(length) {
+      length.writeU32(0, 0);
+      return appModel.currentPackageFullName(length, null) !== NO_PACKAGE_ERROR;
+    }
+  });
+}
+
+function nameAt({ buffer, address }: {
+  buffer: DynComRawMemory;
+  address: bigint;
+}) {
+  const start = Number(address - buffer.pointer().address);
+  const remaining = Number(buffer.size) - start;
+  const [name = ""] = buffer.readBytes(start, remaining).toString("utf16le").split("\0");
+  return name;
+}
+
+function packageNames({ buffer, count }: {
+  buffer: DynComRawMemory;
+  count: number;
+}) {
+  return Array.from({ length: count }, (_, iPackage) => {
+    const address = buffer.readU64(iPackage * PACKAGE_INFO_BYTES + NAME_OFFSET);
+    return nameAt({
+      buffer,
+      address
+    });
+  });
+}
+
+// The two-call pattern: the first call, given no buffer, reports the size.
+function packageGraphNames() {
+  const flags = PACKAGE_FILTER_HEAD | PACKAGE_FILTER_DIRECT;
+  return withMemory({
+    size: DWORD_BYTES * 2,
+    alignment: DWORD_BYTES,
+    use(sizes) {
+      const count = sizes.pointer(COUNT_OFFSET).address;
+      sizes.writeU32(0, 0);
+      const isSized = appModel.currentPackageInfo(flags, sizes, null, count) === INSUFFICIENT_BUFFER_ERROR;
+      if (!isSized) {
+        return [];
+      }
+
+      return withMemory({
+        size: sizes.readU32(0),
+        alignment: POINTER_BYTES,
+        use(buffer) {
+          const isFilled = appModel.currentPackageInfo(flags, sizes, buffer, count) === SUCCESS;
+          return isFilled ? packageNames({
+            buffer,
+            count: sizes.readU32(COUNT_OFFSET)
+          }) : [];
+        }
+      });
+    }
+  });
+}
+
+/**
+ * Whether a Windows App SDK framework package is in this process's package
+ * graph, which is the case when the manifest declares the `PackageDependency`:
+ * WinRT and WinUI then activate with no bootstrapper, and the bootstrapper
+ * refuses to run. A sparse package has an identity and may have no such
+ * dependency.
+ *
+ * @returns False outside a package and in a package without the framework.
+ */
+export function hasWindowsAppRuntimeDependency() {
+  const isPackaged = hasPackageIdentity();
+  return isPackaged && packageGraphNames().some(name => name.startsWith(FRAMEWORK_PREFIX));
+}

package/src/window/system-dispatcher-queue.ts

@@ -1,4 +1,10 @@
-import { bind, numberOf, pointerOf, withMemory } from "#src/win32-calls.js";
+import {
+  bind,
+  numberOf,
+  POINTER_BYTES,
+  pointerOf,
+  withMemory
+} from "#src/win32-calls.js";
 
 // Windows.UI.Composition.Compositor (the system's, which the transparent
 // backdrop needs) refuses to be created on a thread with no
@@ -9,7 +15,6 @@ import { bind, numberOf, pointerOf, withMemory } from "#src/win32-calls.js";
 // makes it, as Microsoft's own MicaController samples do.
 
 const OPTIONS_BYTES = 12;
-const POINTER_BYTES = 8;
 const ALIGNMENT = 8;
 const THREAD_CURRENT = 2;
 const APARTMENT_NONE = 0;

package/src/window/taskbar-native.ts

@@ -2,7 +2,7 @@ import type { TaskbarBackend } from "./taskbar.ts";
 import { DynWinRtValue, WinGuid } from "@microsoft/dynwinrt";
 import { DynCom, DynComMethodSig, DynComUnsafe } from "@microsoft/dynwinrt/com/unsafe";
 import { DynComRawMemory } from "@microsoft/dynwinrt/com/unsafe/raw";
-import { bind, pointerOf } from "#src/win32-calls.js";
+import { bind, POINTER_BYTES, pointerOf } from "#src/win32-calls.js";
 import { createIconFileCalls, createPixelIconCalls } from "#src/win32-icons.js";
 
 // ITaskbarList3 (shobjidl_core.h) has no WinRT form, so its methods are
@@ -25,7 +25,6 @@ const OFFSET_TOP = 4;
 const OFFSET_RIGHT = 8;
 const OFFSET_BOTTOM = 12;
 const FLASH_INFO_SIZE = 32;
-const POINTER_BYTES = 8;
 const NO_ICON = 0n;
 const OFFSET_SIZE = 0;
 const OFFSET_HWND = 8;

package/src/window/window-handle.ts

@@ -1,4 +1,6 @@
 import { applyShownInSwitchers } from "./apply-chrome.ts";
+import type { CoverOptions } from "./cover.ts";
+import { coverWindow } from "./cover.ts";
 import type { DockOptions } from "./dock.ts";
 import { dockWindow } from "./dock.ts";
 import { scaleOf } from "./native.ts";
@@ -8,6 +10,7 @@ import { createTaskbarButton } from "./taskbar.ts";
 import type { TaskbarButton } from "./taskbar.ts";
 import { WindowControlsOverlay, windowTitleBarSource } from "#src/web-apis/window-controls-overlay.js";
 import { WindowGeometry } from "#src/web-apis/window-geometry.js";
+import { bringWindowToFront } from "#src/win32-foreground.js";
 import type { Window } from "#src/winui.js";
 import {
   FileOpenPicker,
@@ -121,6 +124,24 @@ export class WindowHandle {
     });
   }
 
+  /**
+   * Covers a whole display, or a rectangle of one, in physical pixels, and
+   * returns the bounds it applied. A covering window needs `isBorderless` and
+   * `isResizable={false}`; `cover` leaves those props to you. `dock` is a
+   * corner of the work area at the window's own size, `cover` is the whole
+   * display at the display's size, and `geometry` is in CSS pixels and can do
+   * neither exactly.
+   *
+   * @param options - The display (the active one by default) and the region of
+   * it, from its top left (the whole display by default).
+   */
+  cover(options: CoverOptions = {}) {
+    return coverWindow({
+      appWindow: this.appWindow,
+      ...options
+    });
+  }
+
   /** Shows the window and gives it focus. */
   activate() {
     this.window.activate();
@@ -141,10 +162,17 @@ export class WindowHandle {
     this.presenter.restore();
   }
 
-  /** Restored, shown and focused: what launching an app again does. */
+  /**
+   * Restored, shown and focused: what launching an app again does. WinUI's
+   * activation alone is refused by Windows' foreground lock when this process
+   * was not just given the foreground (a tray menu in another process asked
+   * for the window), and the window then only flashes on the taskbar, so the
+   * window is also brought to the front the way `bringWindowToFront` does.
+   */
   bringToFront() {
     this.restore();
     this.activate();
+    bringWindowToFront(this.appWindow.id.value);
   }
 
   /**

package/src/window/window-host.svelte.ts

@@ -184,6 +184,16 @@ export interface WindowProps {
    */
   isActivatable?: boolean | undefined;
 
+  /**
+   * The window is shown, so its page runs at full speed, and never seen: a
+   * tool window that is not activatable, opens without taking focus and sits
+   * clear of every display (left of the virtual screen). `placement` and
+   * `width`/`height` give only the size. Dropped again, the window goes back
+   * where it was. Not the same as `isHidden`: a hidden window is a hidden
+   * page, and Chromium slows it down.
+   */
+  isParked?: boolean | undefined;
+
   /** Clicks go to whatever is behind the window. */
   isClickThrough?: boolean | undefined;
 
@@ -216,7 +226,7 @@ export interface WindowProps {
    * again when the window goes back to it.
    */
   presentation?: WindowPresentation | undefined;
-  isResizable?: boolean;
+  isResizable?: boolean | undefined;
   isMaximizable?: boolean;
   isMinimizable?: boolean;
 
@@ -355,6 +365,12 @@ class WindowHost {
   private isBorderApplied = false;
   private isCaptureApplied = false;
   private isSwitcherApplied = false;
+  private unparkedBounds: {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+  } | null = null;
   private isClipApplied = false;
   private isTopApplied = false;
   private hasShown = false;
@@ -392,7 +408,7 @@ class WindowHost {
       file: windowStateFile(stateKey)
     }) : null;
 
-    const isNewBackgroundWindow = isBackgroundRun() && !this.isTakenOver;
+    const isNewBackgroundWindow = this.isKeptInBackground && !this.isTakenOver;
     if (isNewBackgroundWindow) {
       keepInBackground(this.handle.appWindow.id.value);
     }
@@ -409,6 +425,7 @@ class WindowHost {
     this.keepInLine(() => this.syncPresentation());
     this.keepInLine(() => this.syncLimits());
     this.keepInLine(() => this.syncFrame());
+    $effect(() => this.syncParked());
     this.keepInLine(() => this.syncShape());
 
     if (!this.isTakenOver) {
@@ -630,6 +647,10 @@ class WindowHost {
     }
   }
 
+  private get isKeptInBackground() {
+    return isBackgroundRun() || this.props.isParked === true;
+  }
+
   private get isWindowed() {
     const presentation = this.props.presentation ?? WindowPresentation.windowed;
     return presentation === WindowPresentation.windowed;
@@ -650,7 +671,7 @@ class WindowHost {
       presentation: presentation ?? WindowPresentation.windowed
     });
 
-    if (isBackgroundRun()) {
+    if (this.isKeptInBackground) {
       // A presenter (full screen, compact overlay) puts the window on a display.
       this.handle.appWindow.moveAndResize(backgroundPlacement(this.handle.appWindow.size));
     }
@@ -711,6 +732,37 @@ class WindowHost {
     }
   }
 
+  // Parking after the window is open moves it off every display; dropping the
+  // prop moves it back. The first placement is placeFirst's.
+  private syncParked() {
+    const isParked = this.props.isParked === true && !isBackgroundRun();
+    const { appWindow } = this.handle;
+    if (!this.hasShown) {
+      return;
+    }
+
+    const isToPark = isParked && this.unparkedBounds === null;
+    if (isToPark) {
+      const { x, y } = appWindow.position;
+      const { width, height } = appWindow.size;
+      this.unparkedBounds = {
+        x,
+        y,
+        width,
+        height
+      };
+      appWindow.moveAndResize(backgroundPlacement(appWindow.size));
+      return;
+    }
+
+    const { unparkedBounds } = this;
+    const isToUnpark = !isParked && unparkedBounds !== null;
+    if (isToUnpark) {
+      appWindow.moveAndResize(unparkedBounds);
+      this.unparkedBounds = null;
+    }
+  }
+
   // The window styles, the borderless presenter and the capture affinity: all
   // left alone until the app names them.
   private syncFrame() {
@@ -745,6 +797,7 @@ class WindowHost {
         hwnd,
         style,
         isOn,
+        isParked: this.isKeptInBackground,
         applied: this.appliedStyles
       });
     }
@@ -893,7 +946,7 @@ class WindowHost {
         scale
       })
     };
-    if (isBackgroundRun()) {
+    if (this.isKeptInBackground) {
       appWindow.moveAndResize(
         backgroundPlacement({
           width: props.placement?.width ?? size.width,
@@ -1142,7 +1195,7 @@ class WindowHost {
 
   private showWindow() {
     const { window } = this.handle;
-    const isBackground = this.props.activate === false || isBackgroundRun();
+    const isBackground = this.props.activate === false || this.isKeptInBackground;
     if (isBackground) {
       window.appWindow.showWithActivation(false);
     } else {

package/web-types.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/web-types",
   "name": "winui-svelte",
-  "version": "0.0.6",
+  "version": "0.0.7",
   "framework": "svelte",
   "description-markup": "markdown",
   "contributions": {
@@ -26666,6 +26666,14 @@
                 "type": "boolean"
               }
             },
+            {
+              "name": "isParked",
+              "description": "The window is shown, so its page runs at full speed, and never seen: a tool window that is not activatable, opens without taking focus and sits clear of every display (left of the virtual screen). `placement` and `width`/`height` give only the size. Dropped again, the window goes back where it was. Not the same as `isHidden`: a hidden window is a hidden page, and Chromium slows it down.",
+              "value": {
+                "kind": "expression",
+                "type": "boolean"
+              }
+            },
             {
               "name": "isClickThrough",
               "description": "Clicks go to whatever is behind the window.",
@@ -26933,7 +26941,7 @@
             },
             {
               "name": "icon",
-              "description": "A path to an `.ico` or `.png`, a glyph string, or square BGRA pixels (`IconPixels`); each renderer decides what it can draw."
+              "description": "The picture beside the label; each renderer decides what it can draw."
             },
             {
               "name": "badge",
@@ -27023,7 +27031,7 @@
             },
             {
               "name": "icon",
-              "description": "A path to an `.ico` or `.png`, a glyph string, or square BGRA pixels (`IconPixels`); each renderer decides what it can draw."
+              "description": "The picture beside the label; each renderer decides what it can draw."
             },
             {
               "name": "badge",