PrimaFacie Widget SDK

Build a widget.

Create focused WinUI experiences that adapt to the Heads Up dashboard and integrate through a small, purpose-built SDK.

.NET 10 WinUI 3 x64 Preview

FocusWidget.xaml.cs Runtime contract

public sealed partial class FocusWidget
    : UserControl, IWidget
{
    public Task InitializeAsync(
        WidgetContext context,
        CancellationToken cancellationToken);

    public Task RefreshAsync(
        CancellationToken cancellationToken);

    public Task ShutdownAsync(
        CancellationToken cancellationToken);

    public void OnLayoutChanged(
        WidgetLayout layout);

    public void OnViewportChanged(
        WidgetViewport viewport);
}

Overview

Your widget owns the experience. Heads Up supplies the environment.

The widget package references the SDK and implements its widget-facing contracts. Heads Up implements the host services, owns package discovery and activation, preserves live dashboard workspaces, and orchestrates the runtime lifecycle.

PrimaFacie SDK

Explicit boundary Referenced by widgets · hosted by Heads Up

The host

Heads Up

Implements host-provided SDK services
Owns package installation, discovery, and activation
Owns dashboard and runtime orchestration

Independent

Reference the SDK binary without depending on Control Center application, infrastructure, persistence, or Core assemblies.

Responsive

Adapt to effective layout, viewport dimensions, and Small, Compact, or Normal density supplied by the host.

Integrated

Define widget settings, observe host-supplied global settings, report failures, persist private data, request user attention, and release owned resources through explicit SDK boundaries.

Build a Widget

Begin with the supported repository and sample implementation. The SDK binary, build environment, package declaration, and host expectations remain explicit throughout the process.

Start

Use the widget repository.

Clone the supported repository and begin with its pinned SDK binary, build configuration, documentation, and reference widgets.

Repository provides SDK · samples · build environment

Define

Declare the package and behavior.

Define identity, capabilities, size, theme, assembly, and runtime type in manifest.json. Create a WinUI UserControl and implement IWidget for runtime behavior.

Primary boundaries manifest.json · IWidget · WidgetContext

Integrate

Use the host deliberately.

Build behavior with the view-model foundation, define widget settings, persist private data, respond to effective viewport changes, report failures, request user attention when appropriate, and release owned resources during shutdown.

Host boundaries settings · storage · errors · attention · lifecycle

Complete

Build, validate, and submit.

Validate the manifest and runtime widget in the supported Heads Up environment, then submit the source through a pull request. Accepted widgets are reviewed, built, and integrated into Heads Up.

Completion path build · host validation · pull request

SDK

A small contract. A complete widget foundation.

The manifest declares the package. The SDK defines how its runtime widget participates in Heads Up without exposing the host’s internal architecture.

Package manifest

Declare the authoritative widget identity, presentation defaults, runtime entry point, capabilities, and supported size.

manifest.json
WidgetCapabilities
size · theme · logo

Runtime contract

Receive the host context, participate in refresh, release owned resources during shutdown, and respond to effective layout and viewport changes.

IWidget
InitializeAsync · RefreshAsync
ShutdownAsync · layout · viewport

View-model foundation

Property notification, command creation, refresh behavior, cancellation, and protected operation execution.

WidgetViewModelBase
RelayCommand
AsyncRelayCommand

Responsive models

Adapt presentation using the widget’s effective on-screen layout, dimensions, and density supplied by Heads Up.

WidgetLayout
WidgetViewport
WidgetDensity

Settings and storage

Define widget settings and an optional settings surface. Observe host-defined global settings and own the data model persisted within the private data-directory boundary.

WidgetSettings
GlobalWidgetSettings
WidgetContext.DataDirectory

Host services

Route failures consistently and request shell-managed user attention without depending on the shell implementation.

IWidgetErrorReporter
IWidgetAttentionService
WidgetAttentionRequest