# Nexamas UI

Nexamas UI is a premium SkiaSharp-based .NET Framework 4.8 UI SDK for modern Windows Forms desktop applications.

Nexamas UI is the product and package identity. The public developer-facing API intentionally uses the `MAS` family prefix for controls and application surfaces such as `MASApplication`, `MASApplicationWindow`, `MASButton`, `MASLabel`, `MASDataGrid`, `MASApplicationTheme`, `IMASAppTheme`, and `MASSize`. These identifiers are stable Nexamas UI API names, part of the official Nexamas UI naming model.

This repository is packaged for commercial delivery. It intentionally keeps only the product source, build/package assets, essential legal/package notices, the official quality runner, and minimal samples.

## What you can build with it

Nexamas UI gives a WinForms application a MAS-owned application/window layer, SkiaSharp rendering, themed controls, page layout helpers, data presentation controls, localization/RTL foundations, motion infrastructure, output/export capabilities, and quality proof tooling.

The recommended consumer path is simple:

1. Install the `Nexamas.UI` NuGet package.
2. Create a normal .NET Framework 4.8 WinForms app.
3. Attach a `MASApplicationWindow` to your form.
4. Add controls through `window.Controls`.
5. Layout the page through the official MAS layout builders.

## Requirements

- Windows desktop application
- .NET Framework 4.8
- Visual Studio / MSBuild capable of building classic WinForms projects
- NuGet package restore enabled

## Install

For a local package produced by this repository:

```powershell
Install-Package Nexamas.UI -Version 1.0.0-rc.1 -Source .\.artifacts\nuget
```

This source snapshot is prepared for the first release candidate package: `1.0.0-rc.1`. Promote to `1.0.0` only after the release-candidate proof passes.

## Quick start: first Nexamas window

Create a .NET Framework 4.8 WinForms application and replace the startup form code with this minimal pattern:

```vb
Option Strict On
Option Explicit On

Imports System
Imports System.Windows.Forms
Imports Nexamas.UI.Application
Imports Nexamas.UI.Controls
Imports Nexamas.UI.Layout

Public NotInheritable Class MainForm
    Inherits Form

    Private ReadOnly _window As MASApplicationWindow

    Public Sub New()
        Text = "Nexamas UI Quickstart"
        Width = 1000
        Height = 700
        StartPosition = FormStartPosition.CenterScreen

        _window = MASApplication.AttachWindow(
            owner:=Me,
            configure:=Sub(window As MASApplicationWindow)
                           Dim title As MASTitle = window.Controls.AddTitle("Nexamas UI")
                           Dim message As MASLabel = window.Controls.AddLabel("Hello from Nexamas UI.")
                           Dim action As MASButton = window.Controls.AddButton("Click me")

                           AddHandler action.Click,
                               Sub(sender As Object, e As EventArgs)
                                   window.Services.Toasts.Success("The MAS window is alive.", "Quickstart")
                               End Sub

                           window.Controls.LayoutPage(
                               Sub(page As MASApplicationLayoutPageBuilder)
                                   page.Padding(MASLayoutSpacing.Spacious)
                                   page.Spacing(MASLayoutSpacing.Medium)
                                   page.FullWidth(title, MASSize.FillWidth)
                                   page.FullWidth(message, MASSize.FillWidth)
                                   page.ActionGroup(
                                       Sub(actions As MASApplicationActionGroupLayoutBuilder)
                                           actions.AlignCenter().EqualItemWidth().Add(action, MASSize.Default)
                                       End Sub)
                               End Sub)
                       End Sub)
    End Sub
End Class
```

Use the normal WinForms entry point:

```vb
Friend Module Program
    <STAThread>
    Public Sub Main()
        Global.System.Windows.Forms.Application.EnableVisualStyles()
        Global.System.Windows.Forms.Application.SetCompatibleTextRenderingDefault(False)
        Global.System.Windows.Forms.Application.Run(New MainForm())
    End Sub
End Module
```

## Explicit application lifetime

Use `MASApplication.AttachWindow(...)` for one-form applications. Use explicit lifetime when one application instance should own more than one MAS window:

```vb
Private ReadOnly _application As MASApplication
Private ReadOnly _window As MASApplicationWindow

Public Sub New()
    _application = MASApplication.Create()
    _window = _application.CreateWindow(owner:=Me)
End Sub

Protected Overrides Sub OnFormClosed(e As FormClosedEventArgs)
    If _window IsNot Nothing Then _window.Dispose()
    If _application IsNot Nothing Then _application.Dispose()
    MyBase.OnFormClosed(e)
End Sub
```

## Core public concepts

| Concept | Consumer entry point |
|---|---|
| Application lifetime | `MASApplication.Create()` or `MASApplication.AttachWindow(...)` |
| Window facade | `MASApplicationWindow` |
| Controls | `window.Controls.AddButton(...)`, `AddLabel(...)`, `AddDataGrid(...)`, and other typed factories |
| Layout | `window.Controls.LayoutPage(...)`, `MASSize`, `MASLayoutSpacing` |
| Theme and surfaces | `application.Theme`, `window.Theme`, public surface-material helpers |
| DataGrid/DataView | `MASDataGrid`, `MASDataView`, data factories |
| Localization / RTL | official localization/RTL public gateways documented under `docs/developer/` |
| Output | `MASApplication.Output` capability catalog and supported export routes |
| Quality proof | `tools/quality/Run-NexamasUIQuality.ps1` and source-contract gates |

## Brand and API identity

Use this naming model consistently:

```text
Nexamas UI      Product / SDK name
Nexamas.UI      NuGet package, assembly, and namespace root
MAS*            Stable API/control family exposed by Nexamas UI
```

Correct consumer code uses `Nexamas.UI.*` namespaces with `MAS*` types:

```vb
Imports Nexamas.UI.Application
Imports Nexamas.UI.Controls
Imports Nexamas.UI.Layout

Dim app As MASApplication = MASApplication.Create()
Dim window As MASApplicationWindow = app.CreateWindow(owner:=Me)
Dim button As MASButton = window.Controls.AddButton("Save")
```

Do not reintroduce former platform-era product identity names.

## Documentation map

Start here when evaluating or adopting the SDK:

- `docs/index.md` — main documentation center.
- `docs/customer-guide.md` — customer-facing explanation of what is included and what is not included.
- `docs/company-adoption-guide.md` — safe company evaluation path.
- `docs/commercial/pricing-and-evaluation.md` — seven-day evaluation and commercial offer boundary.
- `docs/developer-guide.md` — developer entry point for public consumer APIs.
- `docs/developer/quickstart-copy-paste.md` — shortest copy-paste examples.
- `docs/examples/README.md` — example catalog.
- `docs/quality-proof-guide.md` — quality proof wording and execution boundaries.
- `release-docs/README.md` — curated commercial reading pack.

## Repository layout

```text
Component/                  Public controls and component internals
MASSystem/                  Nexamas UI domains: Application, Layout, Visual, Interaction, Data, Commands, Quality, Output, Localization, Extensibility
buildTransitive/            NuGet build integration
eng/ci/                     Release, pack, and external consumer proof scripts
eng/tests/                  Source-contract, sample proof, and SDK runtime harness
eng/benchmarks/             Startup probe and optional baseline performance capture
samples/MinimalConsumerApp  Minimal raw-code consumer sample
docs/                       Code-first documentation center
release-docs/               Curated commercial documentation pack
tools/quality/              Single official quality entry point
tools/validation/           Windows validation pack runner
NuGet.Config                Product-local NuGet restore configuration
Nexamas.UI.nuspec           Binary package contract
```

## Source build and package proof

The main quality command is:

```powershell
.\tools\quality\Run-NexamasUIQuality.ps1 -Configuration Release -Platform x64
```

Direct package lane after a successful `Release|x64` build:

```powershell
.\eng\ci\Pack-Nexamas.UI.ps1 -Configuration Release -Platform x64
.\eng\ci\Test-NexamasUIPackedConsumer.ps1 -Configuration Release -Platform x64
```

The packed consumer proof must pass from the `.nupkg`, not from a project reference.

Expected local package output for the current release-candidate line:

```text
.artifacts\nuget\Nexamas.UI.1.0.0-rc.1.nupkg
.artifacts\nuget\Nexamas.UI.1.0.0-rc.1.snupkg
```

Commercial release lane:

```text
Release candidate: 1.0.0-rc.1
First stable release: 1.0.0
```

## Quality and release discipline

A build is not releaseable only because it compiles. Before release, validate:

- clean source-contract tests,
- public API freeze gates,
- approved V1 public surface gate,
- package proof,
- packed external consumer proof,
- source-distribution cleanliness,
- license and third-party notices.

Useful commands:

```powershell
.\eng\tests\Run-NexamasUITestSuite.ps1 -Configuration Release -Platform x64
.\eng\ci\Test-NexamasUIPackedConsumer.ps1 -Configuration Release -Platform x64
```

## Package contents

The binary NuGet package is intentionally small and consumer-clean. It contains the product assembly, XML documentation, buildTransitive target, README, license, and third-party notices. The companion symbol package carries the PDB. The binary package does not ship `docs/`, `eng/`, `samples/`, `tools/`, local build output, historical audit reports, or machine-specific artifacts.

## Advanced notes

### Surface material routing

Surface materials are owned by `MASSystem/Visual/Surface/Material`. Canonical material identities use `surface.material.*`; reusable material distributions use `surface.material-profile.*`; complex elements should request materials through generic surface slots such as Root, Header, Body, Footer, Toolbar, Viewport, Overlay, and SelectedItem. The material registry remains element-agnostic: no material id should contain component names such as button, grid, avatar, preview, date, time, menu, toast, tooltip, progressbar, or imageviewer.

### TileBox bitmap ownership

`MASTileBox` keeps the existing safe default: bitmaps passed directly or returned by providers are borrowed and are not disposed by the control. When a consumer creates fresh bitmaps that are not owned by an external cache, use the explicit TileBox ownership overloads with `takeOwnership:=True` or an `Action(Of SKBitmap)` disposer. The renderer still reads prepared snapshots only; ownership is held by `MASTileItem` and released when owned item resources are cleared/replaced or when the tile item/control is disposed.

### Motion frame-clock lifecycle

Nexamas UI Motion uses a host-scoped `MASMotionFrameClock` owned by each `MASSkiaFrameScheduler`, together with `MASMotionTimelineRunner`, instead of consumer-local timers or background loops. Controls resolve their owning clock through `MASControlRuntimeServices`; non-control runtime owners such as Float transitions receive the clock explicitly from the host runtime. Motion consumers that keep active runners or frame-clock registrations must unregister at their dispose lifecycle boundary.

## License, evaluation, and third-party notices

Nexamas UI is proprietary commercial software distributed under the terms in `LICENSE.md`. The default evaluation path is a seven-day, non-production evaluation license. Commercial use, customer delivery, paid client work, and redistribution require a valid commercial license.

Pricing and evaluation policy are documented in `docs/commercial/pricing-and-evaluation.md`. Third-party notices are listed in `THIRD_PARTY_NOTICES.md`.
