# Nexamas Suite Cohesion Pass

Date: 2026-07-07

## Scope

This pass stabilizes the relationship between the current Nexamas deliverables:

- `Nexamas.UI` as the framework/SDK and package project.
- `NexamasUIShowcase` as the external public-consumer demo.
- `IconStudio.Desktop` as an independent real application that consumes `Nexamas.UI`.

The goal is not to add another visual feature. The goal is to make the projects move as one commercial product surface without weakening architecture boundaries.

## Decisions

1. `Nexamas.UI` remains the owner of internals: rendering, layout, virtualization, diagnostics, render verification, product dashboards, and readiness gates.
2. `NexamasUIShowcase` remains an external consumer: it must prove value through public controls and public product gateways only.
3. `IconStudio.Desktop` keeps its own application identity while referencing the current `Nexamas.UI` project.
4. Suite-level verification belongs outside the projects so no project needs to become responsible for another project's internals.
5. Consumer projects must reference `Nexamas.UI` by project reference, not by copied DLL, stale package, or duplicated source.
6. Existing public API names such as `MASButton` or `MASListView public API` may remain because they are API contracts, not the old product identity.

## Added/renamed assets

- `Nexamas.sln` at suite root.
- `README.md` at suite root.
- `eng/Invoke-NexamasSuiteGate.ps1` at suite root.

## What the suite gate protects

- Expected project roots exist in the sibling layout.
- Project files have no missing, extra, or duplicate Compile Include entries.
- Showcase references `Nexamas.UI` through `..\Nexamas.UI\Nexamas.UI.vbproj`.
- Showcase does not reference a copied `Nexamas.UI.dll`.
- IconStudio.Desktop references `Nexamas.UI` through `..\Nexamas.UI\Nexamas.UI.vbproj` when the desktop project is present.
- Consumer source does not consume forbidden internal/weak tokens such as Virtualization internals, Render Verification snapshots, `OverlayManager`, native file dialogs, `MessageBox.Show`, manual `SetBounds`, or `BoundsLogical`.
- Showcase keeps user-facing Virtualization proof tokens such as `MASListView public API`, `Benchmark scenarios`, `Heavy consumers`, `Live proof surface`, and `Expected result:`.

## How to run

Static suite gate:

```powershell
.\eng\Invoke-NexamasSuiteGate.ps1
```

Full local verification:

```powershell
.\eng\Invoke-NexamasSuiteGate.ps1 -RunInnerGates
```

The full mode delegates to the project-owned gates instead of duplicating their logic.

## Non-goals

- No new framework feature was opened.
- No Showcase page was converted into a framework-internal diagnostic tool.
- No wrappers, adapters, bridges, copied DLLs, or parallel verification systems were introduced.
- No public API was expanded.