# Application Facade Surface Reference

This reference summarizes the public Application-layer surface observed in source during the Phase 1 documentation pass. It does not replace generated API documentation and does not mark every type as stable by itself.

## `MASApplication`

Evidence: `MASSystem/Application/Facade/MASApplication.vb`

| Public member | Role |
|---|---|
| `Create()` | Creates a MAS application facade after applying runtime option snapshot. |
| `ConfigureRuntime(...)` | Public SDK-safe runtime diagnostics/startup policy entry point. It exposes reviewed strict/logging/report switches without exposing RootHost or internal diagnostics types. |
| `AttachWindow(...)` | Creates an application and window for one owner form, then disposes the application when the owner form closes. |
| `CreateWindow(...)` | Creates and tracks a `MASApplicationWindow` for a WinForms owner form. |
| `Theme` | Application-owned theme facade. |
| `Sizing` | Application-owned size-profile facade. |
| `Output` | Application-owned Output facade. |
| `Refresh()` | Requests refresh across tracked windows. |
| `Dispose()` | Disposes tracked windows and clears application state. |
| `WindowCount` / `IsDisposed` | Public state inspection. |

Internal evidence: `GetRuntimeOptionsSnapshot`, `OutputGateway`, and `CreateLayeredSceneHost` are Friend/internal in the current source. The internal options object remains Friend; public configuration is through `ConfigureRuntime(...)` only. `ConfigureRuntime(...)` is process-wide and must be called while no MAS windows are alive; live-window calls are rejected to avoid silently changing another host in the same process.

## `MASApplicationWindow`

Evidence: `MASSystem/Application/Facade/MASApplicationWindow.vb`

| Public member | Role |
|---|---|
| `Services` | Service facade: dialogs, context menus, file explorer/picker, toasts, tooltips, progress. |
| `Shell` | Top-bar/menu/shell integration facade. |
| `Geometry` | DPI, surface size, viewport, coordinate conversion, and control bounds queries. |
| `Controls` | Direct control host, factories, retained layout gateways, focus and mutation helpers. |
| `Pages` | Same-window page host. |
| `Input` | Pointer/focus event and native input facade. |
| `Theme` | Window theme facade. |
| `Sizing` | Window size-profile facade. |
| `Chrome` | Native window chrome/shadow facade. |
| `Presentation` | Host-window presentation facade. |
| `SurfaceMaterial` / `WithSurfaceMaterial(...)` | Window application-surface material key access. |
| `SurfaceSizePx`, `Dpi` | Read-only geometry shortcuts. |
| `Setup()`, `Refresh()`, `RefreshNow()`, `Dispose()` | Lifecycle/refresh methods. |

Internal evidence: `AdvancedRootHost`, `OwnerForm`, `Rendering`, `Layout`, `Page`, `Screen`, and `SetContent*` methods are Friend/internal in the current source.


## `MASApplicationWindowInput` event delegate contracts

`MASApplicationWindow.Input` exposes pointer and host-focus notifications. VB generates six public nested delegate types for these parameterized events; applications normally consume them with `AddHandler` rather than constructing the delegate classes directly.

| Event | Public delegate type | Handler parameters |
|---|---|---|
| `PointerMoved` | `MASApplicationWindowInput.PointerMovedEventHandler` | `clientX As Single`, `clientY As Single` |
| `PointerDown` | `MASApplicationWindowInput.PointerDownEventHandler` | `clientX As Single`, `clientY As Single`, `button As MouseButtons` |
| `PointerUp` | `MASApplicationWindowInput.PointerUpEventHandler` | `clientX As Single`, `clientY As Single`, `button As MouseButtons` |
| `PointerWheel` | `MASApplicationWindowInput.PointerWheelEventHandler` | `clientX As Single`, `clientY As Single`, `delta As Integer` |
| `PointerLeft` | `MASApplicationWindowInput.PointerLeftEventHandler` | no parameters |
| `HostFocusLost` | `MASApplicationWindowInput.HostFocusLostEventHandler` | no parameters |

The short CLR type names are `PointerMovedEventHandler`, `PointerDownEventHandler`, `PointerUpEventHandler`, `PointerWheelEventHandler`, `PointerLeftEventHandler`, and `HostFocusLostEventHandler`. They are compiler-generated contracts owned by `MASApplicationWindowInput`, not separately authored SDK services. `AttachNativeInput()`, `DetachNativeInput()`, `ReleasePointerCapture()`, and `SyncPointerFromCursor()` remain the public input-lifecycle operations.

## `MASApplicationWindowShell`

Evidence: `MASSystem/Application/Facade/MASApplicationWindowShell.vb`

| Public member | Role |
|---|---|
| `TopBar` | Returns the attached standard/custom top bar. |
| `MainMenuBar` | Returns the attached standard application menu bar. |
| `HasStandardMenuBar` | Indicates whether the shell-owned standard menu slot is active. |
| `AttachStandardTopBar(...)` | Creates and attaches the standard MAS TopBar using MASSize chrome metrics. |
| `StandardTopBarHeightLogical` | Active-profile TopBar height from MASSize contracts. |
| `StandardMenuBarHeightLogical` | Active-profile MainMenuBar height from MASSize contracts. |
| `StandardTopBarContentTopLogical` | Content start for TopBar-only windows. |
| `StandardContentTopLogical` | Content start below standard application chrome: TopBar + optional MainMenuBar + MAS chrome gap. |
| `CreateStandardTopBarLogicalRect()` | Standard TopBar host rectangle. |
| `CreateStandardMenuBarLogicalRect()` | Standard full-width MainMenuBar host rectangle. |
| `CreateMenuButton(...)` / `BindMenuButton(...)` | Menu-button integration through the shell-owned dropdown route. |
| `ShowDropDownMenuForControl(...)` | Public dropdown hook anchored to a MAS control's layout-owned float anchor. |

`MASApplicationWindowControls.AddMenuBar(...)` is the public application-wide MainMenuBar route. It delegates to a Friend shell implementation so the menu is hosted as standard application chrome below the TopBar. `MASMenuBar` is not a page/content control: direct hosting through `Controls.Add`/`AddControl` is rejected, and the returned MainMenuBar must not be passed to `LayoutPage` / `LayoutApplicationSurface` builders such as `page.FullWidth(...)`, `Section(...)`, `Grid(...).Add(...)`, `SplitPane().AddSurface(...)`, or region content.

## `MASApplicationWindowControls`

Evidence: `MASSystem/Application/Facade/MASApplicationWindowControls.vb`, `MASSystem/Application/Facade/MASApplicationWindowControls.LayoutPage.vb`, and `docs/_inventory/component-factory-inventory.md`

| Public member group | Role |
|---|---|
| `Add*` factory methods | Public creation/hosting helpers for controls; detailed control documentation is deferred to the Component phase. `AddMenuBar(...)` is the public MainMenuBar gateway and attaches the shell-owned chrome slot rather than page content; the returned `MASMenuBar` is for configuration/command registration, not for page layout admission. |
| `LayoutPage(...)` | Public retained page-layout gateway. |
| `LayoutApplicationSurface(...)` | Public semantic application-surface layout gateway. |
| `Remove`, `Clear`, `BringToFront` | Direct detach/reorder mutation methods. `Remove` and `Clear` are intentionally detach-only and do not dispose controls. |
| `RemoveAndDispose`, `ClearAndDisposeCreatedControls` | Explicit destructive lifecycle methods. `RemoveAndDispose` removes and disposes a specified control; `ClearAndDisposeCreatedControls` disposes only controls created and hosted through `Add*` factory helpers while leaving manually added controls consumer-owned. |
| `PerformUpdate(...)` | Batch direct updates through one visual update block. |
| Direct controls scalability policy | `ControlsLayer` is a retained direct-control layer. It is appropriate for bounded page controls and can be stress-proved at 1k retained direct controls, but it is not a 10k/100k repeated-item virtualization surface. Use MASDataGrid, MASListView, MASListBox, or another Nexamas UI owner backed by MASVirtualizedItemsSystem for large repeated data. |
| `Focus`, `RequestFocus`, `Contains`, `Count` | Focus/state helpers. |

Internal evidence: `LayoutRegions(...)`, retained layout sessions, layout-hosted control reconciliation, `GetSnapshot`, and advanced layer access are Friend/internal or obsolete compatibility paths.

## `MASApplicationPageHost`

Evidence: `MASSystem/Application/Facade/MASApplicationPageHost.vb`

| Public member | Role |
|---|---|
| `RegisterPage(...)` | Registers a logical same-window page by id/title/build action. |
| `NavigateTo(...)` | Switches current page by id. |
| `Show()` | Shows/applies the page host surface. |
| `Refresh()` | Reapplies current page when shown. |
| `ClearPages()` | Clears page registrations and cached pages. |
| `ContainsPage(...)` | Checks registration by normalized id. |
| `WithNavigationVisible(...)` | Controls navigation visibility. |
| `WithRegionBackgrounds(...)` | Controls region background visibility. |
| `WithRhythm(...)` | Applies application-surface rhythm. |
| `WithNavigationSize(...)` | Applies navigation size. |
| `BindNavigationRail(...)` | Binds a `MASNavigationRail` to registered pages. |
| `CurrentPageChanged` | Public event raised on page changes. |

## `MASApplicationWindowPresentation`

Evidence: `MASSystem/Application/Presentation/MASApplicationWindowPresentation.vb`

| Public member | Role |
|---|---|
| `GetAllProfileKinds()` | Returns the public presentation profile vocabulary. |
| `UseUtility`, `UseCompact`, `UseStandard`, `UseSpacious`, `UseProductive`, `UseImmersive` | Applies one-shot presentation profiles. |
| `UseUserPreferences(...)` | Applies a user-preference presentation flow with persistence key. |
| `Apply(...)`, `ApplyAndSave(...)`, `SaveCurrent(...)` | Apply/persist presentation state. |
| `CurrentProfileKind` | Exposes current profile kind. |

## Public presentation profile kinds

Evidence: `MASSystem/Application/Presentation/MASWindowPresentationProfileKind.vb`

- `Compact`
- `Standard`
- `Spacious`
- `Productive`
- `Immersive`
- `Utility`