# Theme / Surface Public Surface Reference

This page lists the source-verified public Theme and Surface Visual surface found during the static documentation pass.

## Public theme types

| Type | Kind | Role | Evidence |
|---|---|---|---|
| `MASApplicationTheme` | Class | Application-level theme facade. | `MASSystem/Application/Facade/MASApplicationTheme.vb` |
| `MASApplicationWindowTheme` | Class | Window-owned convenience facade over global theme selection. | `MASSystem/Application/Facade/MASApplicationWindowTheme.vb` |
| `MASApplicationThemeScope` | Enum | Publicly states current theme scope. | `MASSystem/Application/Facade/MASApplicationThemeScope.vb` |
| `NexamasUIChangedEventArgs` | Class | Theme change event data with old/new theme. | `MASSystem/Application/Facade/MASApplicationTheme.vb` |
| `IMASAppTheme` | Interface | Public theme identity contract. | `MASSystem/Visual/ThemeSystem/App/IMASAppTheme.vb` |
| `MASAppThemeBase` | MustInherit class | Advanced base for immutable app themes. | `MASSystem/Visual/ThemeSystem/App/MASAppThemeBase.vb` |
| `MASPremiumOfficeApp` | Class | Built-in theme. | `MASSystem/Visual/ThemeSystem/ReadyThemes/MASSignature/App/MASPremiumOfficeApp.vb` |
| `MASGreenOceanApp` | Class | Built-in theme. | `MASSystem/Visual/ThemeSystem/ReadyThemes/MASSignature/App/MASGreenOceanApp.vb` |
| `MASDarkBlueNightSkyApp` | Class | Built-in theme. | `MASSystem/Visual/ThemeSystem/ReadyThemes/MASSignature/App/MASDarkBlueNightSkyApp.vb` |

## Theme facade members

| Owner | Member | Public behavior |
|---|---|---|
| `MASApplicationTheme` | `Current` | Returns current `IMASAppTheme`. |
| `MASApplicationTheme` | `CurrentId` | Returns current theme id. |
| `MASApplicationTheme` | `CurrentDisplayName` | Returns current display name. |
| `MASApplicationTheme` | `GetAll()` | Returns registered themes. |
| `MASApplicationTheme` | `GetById(id)` | Returns a theme by id or `Nothing`. |
| `MASApplicationTheme` | `TryUse(id)` | Attempts to apply a registered theme. |
| `MASApplicationTheme` | `Use(id)` | Applies a theme or throws when invalid/unregistered. |
| `MASApplicationTheme` | `Register(theme)` | Registers a full `IMASAppTheme`. |
| `MASApplicationTheme` | `CurrentChanged` | Event forwarding the new current theme. |
| `MASApplicationTheme` | `CurrentThemeChanged` | Event forwarding old/new theme data. |
| `MASApplicationTheme` | `ThemeRegistered` | Event raised after registration. |
| `MASApplicationWindowTheme` | `Scope` | Returns `MASApplicationThemeScope.GlobalApplication`. |
| `MASApplicationWindowTheme` | `IsGlobalApplicationTheme` | Returns `True`. |
| `MASApplicationWindowTheme` | `TryUseGlobally(id)` | Explicit alias for global theme application. |
| `MASApplicationWindowTheme` | `UseGlobally(id)` | Explicit alias for global theme application with throwing behavior. |
| `MASApplicationWindowTheme` | `Refresh()` | Invalidates the window theme host and requests repaint. |

## Public surface-material types

| Type | Kind | Role | Evidence |
|---|---|---|---|
| `MASApplicationSurfaceMaterialGateway` | Class | Public shared gateway for selectable surface materials and scope creation. | `MASSystem/Application/Facade/SurfaceMaterials/MASApplicationSurfaceMaterialGateway.vb` |
| `MASApplicationSurfaceMaterialOption` | Class | Public immutable option with `Key` and `DisplayName`. | `MASSystem/Application/Facade/SurfaceMaterials/MASApplicationSurfaceMaterialOption.vb` |
| `MASApplicationSurfaceMaterialScope` | Class | Public application-scope material switch helper. | `MASSystem/Application/Facade/SurfaceMaterials/MASApplicationSurfaceMaterialScope.vb` |
| `MASApplicationWindow.SurfaceMaterial` | Property | Public application chrome material key. | `MASSystem/Application/Facade/MASApplicationWindow.vb` |
| `MASApplicationWindow.WithSurfaceMaterial(key)` | Function | Fluent application chrome material key setter. | `MASSystem/Application/Facade/MASApplicationWindow.vb` |
| `MASApplicationSurfaceLayoutBuilder.WithCommandBackgroundSurfaceMaterial(key)` | Function | Public command background material request. | `MASSystem/Application/Facade/MASApplicationSurfaceLayoutBuilder.Chrome.vb` |
| `MASApplicationSurfaceLayoutBuilder.WithRegionBackgroundSurfaceMaterial(key)` | Function | Public region background material request. | `MASSystem/Application/Facade/MASApplicationSurfaceLayoutBuilder.Chrome.vb` |

## Gateway methods

| Owner | Member | Role |
|---|---|---|
| `MASApplicationSurfaceMaterialGateway` | `GetSelectableMaterials()` | Returns `MASApplicationSurfaceMaterialOption()` for public selection. |
| `MASApplicationSurfaceMaterialGateway` | `NormalizeMaterialKey(materialKey)` | Normalizes keys using platform policy. |
| `MASApplicationSurfaceMaterialGateway` | `IsAutoMaterialKey(materialKey)` | Checks default/auto key. |
| `MASApplicationSurfaceMaterialGateway` | `CreateScope(window)` | Creates `MASApplicationSurfaceMaterialScope`. |

`ResetRuntimeSwitch` is intentionally Friend-only after Phase-12; public hosts select/apply materials through `CreateScope(window).Apply(key)` and do not own runtime-switch cleanup.
| `MASApplicationSurfaceMaterialScope` | `RegisterTopBar(topBar)` | Registers `MASTopBarComponent`. |
| `MASApplicationSurfaceMaterialScope` | `RegisterToolbar(toolbar)` | Registers `MASToolbar`. |
| `MASApplicationSurfaceMaterialScope` | `RegisterGroupBox(groupBox)` | Registers `MASGroupBox`. |
| `MASApplicationSurfaceMaterialScope` | `RegisterProgressBar(progressBar)` | Registers `MASProgressBar`. |
| `MASApplicationSurfaceMaterialScope` | `RegisterOperationProgressBox(progressBox)` | Registers `MASOperationProgressBox`. |
| `MASApplicationSurfaceMaterialScope` | `RegisterCard(card)` | Registers `MASCard`. |
| `MASApplicationSurfaceMaterialScope` | `Apply(materialKey)` | Applies current material through registered owners and refreshes the window. |
| `MASApplicationSurfaceMaterialScope` | `CreateToastOptions(message, title)` | Creates toast options using the current material key. |

## Built-in themes

| Id | Display name | Class |
|---|---|---|
| `premium-office-mas-signature` | `Premium Office MASSignature` | `MASPremiumOfficeApp` |
| `green-ocean-mas-signature` | `Green Ocean MASSignature` | `MASGreenOceanApp` |
| `dark-blue-night-sky-mas-signature` | `Dark Blue Night Sky MASSignature` | `MASDarkBlueNightSkyApp` |

Default id in `ThemeManager`: `premium-office-mas-signature`.

## Public-selectable materials observed in source

The source registry marks 14 definitions as public-selectable. `GetSelectableMaterials()` returns `Auto / current default` plus public definitions except `Platform Default`.

| Display name | Internal id constant |
|---|---|
| Platform Default | `PlatformDefault` |
| Soft Mist | `SoftMist` |
| Frosted Glass | `FrostedGlass` |
| Crystal Ice | `CrystalIce` |
| Crystal Ice Native | `CrystalIceNative` |
| Warm Paper | `WarmPaper` |
| Warm Paper Native | `WarmPaperNative` |
| Graphite Metal | `GraphiteMetal` |
| Media Shell | `MediaShell` |
| Media Chrome | `MediaChrome` |
| Media Toolbar Glass | `MediaToolbarGlass` |
| Media Command Rail | `MediaCommandRail` |
| Media Footer Chrome | `MediaFooterChrome` |
| Media Stage | `MediaStage` |

Consumer docs should tell users to use returned option keys rather than internal constants.

## Advanced rendering and typography supporting types

These public types are lower-level supporting contracts. They do not replace the application-owned `MASApplication.Theme` / `MASApplicationWindow.Theme` selection route.

| Type | Classification | Public role |
|---|---|---|
| `MASCardVisualStyle` | Advanced | Selects `Default` or `Secondary` card presentation. |
| `MASThemeContext` | Advanced | Read-only render context exposing `Theme`, `Typography`, and `Dpi`. |
| `MASTypography` | Advanced | Disposable typography helper constructed with a scale; exposes `GetPaint(...)`, `CreatePaint(...)`, `BaselineY(...)`, and `Scale`. |
| `MASTypography.MASTextStyle` | Advanced | Nested text-style vocabulary: `Body`, `Small`, `Micro`, `Title`, `Button`, `FieldText`, `FieldPlaceholder`, `TopBarTitle`, and `SelectionText`. The CLR short name is `MASTextStyle`. |
| `MASSurfaceStrength` | Evidence | Surface-evidence strength vocabulary: `ThemeDefault` and levels `Level1` through `Level6`. It is not a beginner theme-selection API. |

`MASTypography.GetPaint(...)` and `CreatePaint(...)` each return a caller-owned `SKPaint` clone; callers may mutate and dispose that paint without affecting the internal cache. Consumers that construct `MASTypography` own its `Dispose()` lifecycle. `MASThemeContext` itself has no public constructor and is supplied by Nexamas UI rendering. The context and text-style enum describe rendering inputs; they do not register fonts, load application resources, or choose the current application theme.

## Explicit exclusions

The following are source-visible but not public consumer API:

- `ThemeManager`
- `ThemeHost`
- `ThemeAssembly`
- `ThemeValidator`
- `IMASThemeFoundation`
- `IMASThemeFamilies`
- component recipe factories
- `MASAppThemeContracts`
- `MASThemeStudio`
- `MASSurfaceDesigner`
- `MASSurfaceMaterialRegistry`
- material painter/frame painter/runtime routing classes
- visual governance/audit report classes

## Validation note

This page is based on static source/project inspection. No Windows/MSBuild build or visual governance gate was executed here.