App Window

FluereAppWindow provides the chrome of a window: corner radius, border and shadow, the title bar (icon, title, subtitle, left header, center content, right header, back and pane-toggle buttons), the caption buttons in the top-right corner, and a content area that only owns the visible region.

It maps to WinUI 3 / Windows App SDK's Microsoft.UI.Xaml.Controls.TitleBar (microsoft-ui-xaml) — a composite control — so the template, states and metrics follow it item by item:

• 12-column template: 2 | Auto(back) | Auto(pane toggle) | Auto(left header) | 14(left header spacing) | Auto(icon) | Auto(title) | Auto(subtitle) | *(content) | Auto(right header) | 48(min drag region) | Auto(caption area).
• Two heights: 32 only when Content / LeftHeader / RightHeader are all empty (TitleBarCompactHeight); otherwise 48 (TitleBarExpandedHeight, TitleBar.cpp#UpdateHeight).
• Zero-duration state changes: the source calls GoToState(..., false) and has no Storyboard / VisualTransition at all, so title-bar internals never animate.
• Dragging = non-client area plus punched holes: the whole title bar is non-client, interactive elements become NonClientRegionKind::Passthrough holes, and the Icon uses its own Icon region — it is not in the passthrough list, so the icon area stays draggable.

Version and evidence baseline

perf2026 is not adopted: TitleBar_themeresources_perf2026.xaml (new in 2.5.1) contains two real bugs (a renamed resource key whose reference was not updated, and the pane-toggle Disabled state painting the background onto the 16×16 icon instead of the button). This component follows the base file.

Title bar: six slots and three buttons

Any of the latter four pushes the title bar to 48. When exactly one of back / pane-toggle is visible, the left-header spacing drops from 14 to 2 (NegativeInsetSpacing).

<FluereAppWindow
  title="Header slots"
  :is-back-button-visible="true"
  :is-pane-toggle-button-visible="true"
  @back-requested="…"
  @pane-toggle-requested="…"
>
  <template #titlebar-content>
    <FluereInput placeholder="Find a setting" aria-label="Find a setting" class="w-[220px]" />
  </template>
  <template #right-header>
    <FluereButton appearance="subtle" icon-only :icon="FluentIconPerson24Regular" aria-label="Account" />
  </template>
  <template #content>…</template>
</FluereAppWindow>

Inputs and buttons placed in the title bar are not drag regions — pressing them never starts a window drag (the equivalent of WinUI punching that area into the passthrough list).

Content area: viewport only

The content area is "window height minus title-bar height" with overflow: clip and min-block-size: 0: it only defines the visible boundary; scrolling is up to the consumer (put a FluereScrollView, or your own scroller, inside). Sizing is up to the consumer too — the component never writes position / inset / transform.

<FluereAppWindow class="h-[300px] w-full max-w-[560px]" title="Settings" subtitle="21RU0000CD">
  <template #icon>
    <FluentIconCloudArrowUp24Regular :size="16" />
  </template>
  <template #content>…</template>
</FluereAppWindow>

Caption buttons: pure logic proxying

FluereCaptionButtons renders three native <button>s (minimize, maximize/restore, close) and only emits: minimize / maximize / restore / close, plus v-model:maximized to hand the "maximize ⇄ restore" intent back. The component itself never changes any window state — that is exactly the 0.5.2 "logic proxy" contract.

<FluereCaptionButtons
  v-model:maximized="maximized"
  :is-minimizable="isMinimizable"
  :is-maximizable="isMaximizable"
  :is-closable="isClosable"
  @minimize="…"
  @maximize="…"
  @restore="…"
  @close="…"
/>

Caption-button evidence gaps

WinUI 3's TitleBar has no caption buttons in its template (all 12 columns read; no minimize / maximize / close). They are drawn by the system (DWM) and have no XAML implementation in microsoft-ui-xaml:

• CWindowChrome.cpp only makes the button background fully transparent and maintains the caption-region hit-test rectangles — no drawing code; enum class CaptionButtonState in CWindowChrome.h has no usage anywhere.
• Microsoft's own specs/TitleBar/titlebar-functional-spec.md:47-48 states "WinUI TitleBar does not handle Caption Buttons … handled by the AppWindow TitleBar".
• The only caption visual in the tree is the legacy system-chrome x:Key="WindowCaptionButton" style (src/dxaml/xcp/dxaml/themes/generic.xaml:15697-15786, a 40×28 button, a 9×9 stroked Path, and the two WindowStateNormal/Maximized Path.Data strings). This component only reuses its glyph geometry.

Everything below is therefore a system metric, cross-checked against 1:1 Windows 11 screenshots and exposed as overridable component-local variables:

Glyph calibration (1:1 frozen frames vs. the Windows 11 reference screenshot, scored by per-pixel mean absolute ink difference Δ, lower = closer; scripts temp/glyph-lab.mjs + temp/glyph-lab-compare.py stay in temp/, the conclusions live in packages/ui/src/app-window/constants.ts and the component comments):

Two systematic fixes (the root cause of the former "clunky / broken" look): ① dropping shape-rendering: crispEdges — it disables anti-aliasing, turning 45° strokes into hard stair-steps and quantizing the rounded corners into blocks (Δ15.7 vs Δ3.2); ② moving line width and line cap onto the per-glyph path presentation attributes (minimize / maximize 1px + butt, close 1.1px + round) — CSS rules outrank presentation attributes, so keeping them in <style scoped> would silently override the per-glyph values.

To match a real machine exactly, override these local variables:

.my-caption-buttons {
  --fui-caption-buttons-button-width: 46px;
  --fui-caption-buttons-glyph-size: 10px;
  --fui-caption-buttons-glyph-color: #000000; /* #ffffff in dark */
  --fui-caption-buttons-close-hover: #c42b1c;
  --fui-caption-buttons-close-pressed: #b22b26;
}

Glyph line width / line cap / path are deliberately not local variables: they interlock with the path geometry (endpoint = width ÷ 2) and differ per glyph, so overriding one of them breaks the box alignment — use the minimize-icon / maximize-icon / restore-icon / close-icon slots to swap glyphs instead.

Dragging: events only

With draggable (default true), pressing the title bar outside interactive regions emits:

• Per-event deltas (deltaX/deltaY) suit incremental updates; totals (totalDeltaX/totalDeltaY) can be applied straight to the drag origin.
• Esc / pointercancel / losing pointer capture ⇒ dragEnd.canceled = true.
• Pressing inside left header / center / right header / back / pane toggle / caption buttons / any native interactive element, or inside an element carrying data-fui-app-window-drag-exempt ⇒ no drag starts.
• Title-bar text is not selectable while dragging (it is a non-client area in WinUI).
• With roundToInteger (default false), dragMove / dragEnd totals round to whole numbers and delta is the difference between two consecutive rounded totals — so an outer CSS translate stays integer (no sub-pixel blur) with no accumulated rounding error.

<FluereAppWindow
  class="absolute h-[200px] w-[380px] transition-[translate,border-radius] duration-150"
  :style="{ translate: `${x}px ${y}px` }"
  :maximized="maximized"
  :round-to-integer="true"
  @drag-start="onDragStart"
  @drag-move="onDragMove"
  @titlebar-double-click="maximized = !maximized"
/>

Why translate instead of left / top: translate runs on the compositor and does not trigger reflow / repaint, keeping the drag smooth; with :round-to-integer="true" the offset stays a whole number, so there is no blur or jitter from sub-pixel values.

States and integrated styling

<FluereAppWindow :active="active" :maximized="maximized" title="Active / inactive" />
<FluereAppWindow
  motion="none"
  title="Zero-duration states + focus"
  :is-back-button-visible="true"
/>

Stacking stays outside: the component writes no z-index at all. The window layer is the shell's decision (existing docs tiers: ContentDialog / Combobox popups 1000, Tooltip 1100).

Maximize / minimize animation: DWM's window open, minimize and maximize animations have no readable keyframes (they are not in microsoft-ui-xaml), so this library makes no frame-accurate claim. The component only offers controllable hooks: with motion="auto" the window frame transitions radius / shadow / background with design tokens (--durationNormal + --curveDecelerateMid, honoring prefers-reduced-motion); geometry animation is up to the shell using the same tokens (see the drag demo above).

API

FluereAppWindow

FluereCaptionButtons

Measured in a real browser (reproducible)

Computed styles measured with Playwright + system Chrome (1280×900 / DPR 1) on this very page (the script and screenshots are process artifacts under temp/; the conclusions are below):

Implementation notes

• Height logic mirrors UpdateHeight(): only LeftHeader / Content / RightHeader count; Title / Subtitle do not affect the height tier.
• Three deliberate departures from the legacy system chrome for the caption glyphs (calibrated 2026-10-16): ① dropping shape-rendering: crispEdges (it disables anti-aliasing, turning 45° strokes into hard stair-steps); ② moving line width / line cap onto the per-glyph path presentation attributes (CSS outranks presentation attributes, so keeping them in the style block would silently override the per-glyph values); ③ switching the ink to the local variable light-dark(#000000, #ffffff) (= WindowCaptionForeground → SystemBaseHighColor; no token matches it). The geometry candidate scan is in "Caption buttons: the evidence gap" above.
• Compact folding is "last declared group wins": both TitleTextGroup and DisplayModeGroup write PART_TitleText.Visibility, and the latter is declared later ⇒ Compact hides title / subtitle and moves the center content from centered to left with a 16 end margin. The criterion is not a breakpoint but "desired width of the center ≥ its available width" (contentArea.DesiredSize().Width >= contentAreaGrid.ActualWidth()), with the threshold remembered from the moment folding started; the Web side measures desired width through a hidden mirror (visibility: hidden + aria-hidden + inert).
• Web equivalent of punching passthrough holes: pointerdown does not start a drag when it lands in [data-fui-app-window-nodrag], a native interactive element, or [data-fui-app-window-drag-exempt]. Esc cancels; pointercancel and lost capture end as canceled=true.
• Back / pane-toggle buttons skip the AnimatedIcon animation for now: WinUI uses AnimatedBackVisualSource / AnimatedGlobalNavigationButtonVisualSource (LottieGen output, c_durationTicks = 13333333 ≈ 1.3333 s, 48×48 canvas, 12 markers, Foreground theme property). This library ships static glyphs for now; the animation lands with 0.5.4 NavigationView (the slots are already in place).
• Known gaps: high-contrast is not implemented (WinUI HC switches the title bar to SystemControl* / SystemColor*); the material tokens landed in 0.4.4 (micaBackgroundFillColorBase / acrylicInAppFillColorDefault / layerFillColorDefault and friends — see sources.materials in packages/designs/data/repo-tokens.json), but material composition (gradient + translucent layers + noise) belongs to 0.9.1 / 0.9.2, so the window surface still uses colorNeutralBackground2 (reusing the existing SolidBackgroundFillColorBase mapping) and no backdrop-filter is written.
• Title never writes document.title: WinUI really renames the window and restores the default title when cleared; the Web side leaves the document title alone (no docs-site or SSR pollution).