Onboarding guide

15. Common UI Framework (MudBlazor components, theme, base pages)

What this chapter covers. MMCA.Common.UI is the Blazor presentation package, and it is one of the two layers (with Grpc) allowed to reference Shared only: its single ProjectReference is MMCA.Common.Shared (MMCA.Common.UI/MMCA.Common.UI.csproj:42), and every other dependency is a NuGet package (MudBlazor, Polly, the SignalR client, Scrutor, QRCoder, FeatureManagement, System.IdentityModel.Tokens.Jwt, MMCA.Common.UI.csproj:19-37). It touches no Application, Domain or Infrastructure type, which is exactly what lets it compile into a Blazor WebAssembly bundle and into a .NET MAUI hybrid head (see primer §1). What it ships is the set of reusable parts every consumer UI assembles pages from: a server-paged data-grid list-page base class, the brand MudBlazor theme, a Result-returning typed HTTP service base for talking to the WebAPI, a client-side read cache, the authentication and token-refresh boundary, list-page state preservation across navigation, vendor-neutral toast and dialog facades, a pluggable UI-module contract, an end-to-end localization pipeline, drop-in role and user administration screens, and a turnkey notification inbox / push / live-channel feature. A second, thinner package MMCA.Common.UI.Web sits above it and holds the pieces that need an ASP.NET pipeline (server-side token storage, the Blazor Content-Security-Policy provider, the trusted-caller header an SSR host stamps on its gateway calls, and the host's own edge rate limiter and ceiling on open circuits, plus an opt-in same-origin API proxy that keeps every token out of script). The per-app and per-module Razor pages in the consumer apps (chapter 21) derive from and consume these primitives, and the same components render across Blazor Server, WebAssembly and MAUI with no per-platform reimplementation. [Rubric §18, UI Architecture & Component Design] assesses component reuse, separation of presentation from data access, and whether there is a coherent composition model; nearly every type in this group exists so a consumer page is composed rather than hand-rolled, which is the shape ADR-067 records.

The data-access boundary: a Result contract over one named HttpClient. A page never touches HttpClient, and it never catches an exception to learn what the server said. It depends on IEntityService<TEntityDTO, TIdentifierType> (MMCA.Common.UI/Common/Interfaces/IEntityService.cs:20), whose seven CRUD members every one return a Result or Result<T> (IEntityService.cs:25-66), and it gets its behavior from the abstract EntityServiceBase<TEntityDTO, TIdentifierType> (MMCA.Common.UI/Services/Api/EntityServiceBase.cs:43), which derives in turn from AuthenticatedServiceBase (MMCA.Common.UI/Services/Api/AuthenticatedServiceBase.cs:16). That base owns the cross-cutting concerns of an outbound call. First, a Polly retry policy: 3 retries with exponential backoff (2s, 4s, 8s) plus up to one second of random jitter so a fleet of clients does not re-converge on the same instant (AuthenticatedServiceBase.cs:20-27, :153-155), over a deliberate retryable set rather than "any 5xx", since 501 and 505 are permanent verdicts and are excluded while 408 and 429 are explicit invitations to come back (AuthenticatedServiceBase.cs:97-122). A POST or PATCH is replayed only when its request carried an Idempotency-Key, because re-sending a write the server cannot dedupe could apply it twice (:115-118, :134-148). The policy's onRetry disposes each superseded response, because Polly hands the caller only the final outcome and an undisposed 5xx leaks its content buffer and holds its connection out of the pool under exactly the sustained failure the retries exist to survive (AuthenticatedServiceBase.cs:163-173). Second, a helper that creates a "APIClient" HttpClient from IHttpClientFactory and stamps the JWT Bearer token onto it from ITokenStorageService, swallowing the InvalidOperationException that JS interop throws during SSR prerender (AuthenticatedServiceBase.cs:53-78); a sibling CreateClientWithToken builds a client around an explicitly supplied token so a request the API answered 401 can be replayed with one acquired straight from ITokenRefresher rather than resending the token the server just rejected (AuthenticatedServiceBase.cs:80-95). The same policy object is reachable without inheritance: IdempotentReadRetry (MMCA.Common.UI/Services/Api/IdempotentReadRetry.cs:18) hands anonymous lookup services the exact instance the base exposes to its subclasses, so the two paths cannot drift, and its only entry point is a GET because re-sending is safe only for an idempotent read (IdempotentReadRetry.cs:9-16, :24, :35-44, AuthenticatedServiceBase.cs:34-38). Its read-side sibling PagedReadAll (MMCA.Common.UI/Services/Api/PagedReadAll.cs:19) exists because a single read truncates silently at the API's page-size maximum: it pages a /paged endpoint in stable id order with a PageSize of 500 until the server's reported total is reached, hands back the first failure unchanged, and stops after 40 pages (20,000 rows) whatever the server claims (PagedReadAll.cs:12-18, :22, :28, :43-46, :57-90).

Retry and idempotency are coupled on purpose: NewIdempotencyKey() (AuthenticatedServiceBase.cs:51) is generated once per logical write and set as a default header on the single client that serves every attempt (EntityServiceBase.cs:168-175, :399-414), so a retried create dedupes on the server instead of producing a duplicate row (the server half is IdempotencyHeaders and IdempotentAttribute, ADR-017). Creates are the only verb that carries a key: updates are full PUTs and deletes are naturally idempotent (EntityServiceBase.cs:168-170). Updates instead carry a precondition: ConcurrencyTagOf renders a DTO's RowVersion as a weak entity tag when the DTO implements IConcurrencyAware, and that tag travels as the If-Match header on the same per-operation client, so every retry states the same precondition instead of a later attempt succeeding against a version the user never saw (EntityServiceBase.cs:193-209, :416-424, ADR-035). Responses come back in the same PagedCollectionResult<T> / CollectionResult<T> envelopes the API returns, and both SendRequestAsync overloads read the response through ProblemDetailsResultReader (EntityServiceBase.cs:351-366, :381-394), so a 404 arrives as an ErrorType.NotFound failure, a rejection as Validation, a 500 as Unexpected, each carrying the server's own text. What the reader cannot convert is the absence of a response, and that is HttpResultExecutor's job (MMCA.Common.UI/Services/Api/HttpResultExecutor.cs:35): it wraps each call, turns a refused connection, a broken stream or an unreadable body into Http.TransportFailure and a client-side timeout into Http.Timeout (HttpResultExecutor.cs:38, :41, :135-136), and rethrows an OperationCanceledException only when the caller's own token asked for it, because a page owns its cancellation and must not have a disposed component reported back as an error to render (HttpResultExecutor.cs:69-75, :104-110). Many-to-many join endpoints, which have POST and DELETE but no standalone reads, get their own thinner base, ChildEntityServiceBase (MMCA.Common.UI/Services/Api/ChildEntityServiceBase.cs:19), whose DeleteByIdAsync reports a missing join row as a NotFound failure so "nothing to remove" stays distinguishable from "the remove failed" (ChildEntityServiceBase.cs:62-79). The page-side half of the same transport is ResultUiExtensions (MMCA.Common.UI/Common/ResultUiExtensions.cs:74): TryGetValue unwraps inside a conditional the way Dictionary.TryGetValue does, branching on IsFailure rather than on a null so a failed (Items, TotalItems) tuple is not read as a success (ResultUiExtensions.cs:86-103), and the rendering helpers look every message up as a resource key with pass-through, de-duplicate ordinally, and order most severe first so a real 403 leads and an incidental validation line never buries it (ResultUiExtensions.cs:18-29). [Rubric §3, Clean Architecture] and [Rubric §9, API & Contract Design]: the UI binds to a DTO contract and an interface, never to server internals, and the wire envelope is uniform across every entity. [Rubric §29, Resilience] is the retry, jitter, idempotency and precondition set. The contract itself is recorded in ADR-094, and the retirement of the old exception-throwing UI deviation in ADR-013.

A third caching tier, on the client. IUiReadCache (MMCA.Common.UI/Services/Caching/IUiReadCache.cs:32) is a read-through cache sitting in front of the API client, so a list re-read twice within a few seconds (a grid re-mounted by navigation, a lookup rendered in two components) costs one round trip. Its operations are TryGetFresh, Set, InvalidatePrefix and Clear (IUiReadCache.cs:50, :59, :78, :85), plus a Generation counter that moves on every invalidation (:35-40), and the key is deliberately the relative URL, path plus the full query string, which is the same key shape the server's authenticated output cache uses, so a filter, page or sort change misses on both tiers rather than being served stale by one of them (IUiReadCache.cs:9-15, ADR-040). UiReadCache (MMCA.Common.UI/Services/Caching/UiReadCache.cs:18) implements it as a lock-guarded ordinal dictionary (UiReadCache.cs:20, :25) with lazy expiry, dropping a stale entry when it is next read instead of running a sweep timer over the few dozen entries a circuit ever holds (UiReadCache.cs:12-14, :68, :76), and TTL resolution picks the longest matching route prefix so a child route can state a different budget than the endpoint it sits under (UiReadCache.cs:157-178). Staleness is configuration, not accident: UiReadCacheOptions (MMCA.Common.UI/Common/Settings/UiReadCacheOptions.cs:13) binds the UiReadCache section with an Enabled escape hatch, a 60-second DefaultTtl and the per-prefix override map (UiReadCacheOptions.cs:16, :24, :32, :41). EntityServiceBase takes the cache as an optional constructor argument, so a service registered without one behaves exactly like a plain GET (EntityServiceBase.cs:47, :58, :253-284), and a bypassCache flag forces a round trip for a read the user explicitly asked to be current (:243-247); only successes are stored, because caching a failure would pin a transient outage in front of the user for the whole TTL and let a 404 survive the create that fixed it (EntityServiceBase.cs:276-281), while the generation captured before the GET drops a late store that a concurrent write has already made stale (:270-273, IUiReadCache.cs:63-70); and every write invalidates its own endpoint prefix unless the server refused it before touching state (a validation, unprocessable, unauthorized, forbidden or rate-limited answer), because a 412, 404 or 409 can be the answer to the retry of a write whose first attempt landed, and a 5xx or transport failure says nothing about whether it did (EntityServiceBase.cs:291-314). The one cross-cutting hazard is scope: the cache is scoped, which is per-circuit on Blazor Server but per app lifetime on WebAssembly and MAUI, so AuthUIService.LogoutAsync clears it explicitly rather than trusting the scope to end with the session (MMCA.Common.UI/Services/Auth/AuthUIService.cs:88, the clear at :190; the registration states why at MMCA.Common.UI/DependencyInjection.cs:73-76); the device-local document cache that backs offline list snapshots is wiped in the same pass, since those snapshots are keyed by surface rather than by user (the optional ILocalCacheStore dependency, AuthUIService.cs:51). [Rubric §12, Performance & Scalability] and [Rubric §19, State Management] both land here, and the tier is recorded in ADR-026.

The list page: DataGridListPageBase<TDto>. This is the most concept-dense type in the group and the centerpiece of the compose-do-not-repeat thesis. Every list screen in every consumer app derives from DataGridListPageBase<TDto> (MMCA.Common.UI/Pages/Common/DataGridListPageBase.cs:22), a ComponentBase that encapsulates what would otherwise be copy-pasted onto each page: server-side paging against MudDataGrid<T>, CancellationTokenSource lifecycle, loading state, filter and sort extraction from MudBlazor's GridState<T>, error surfacing through the toast facade, a LoadFailed flag so a failed fetch renders an inline retry instead of a misleading "no records" empty state (DataGridListPageBase.cs:53, set at :752 and :773), viewport-driven mobile versus desktop rendering (it implements IBrowserViewportObserver and flips IsMobile through BreakpointConstants at the 960 px sidebar-collapse boundary, DataGridListPageBase.cs:22, :322, and MMCA.Common.UI/Common/BreakpointConstants.cs:16-17), a persisted dense-density toggle (DataGridListPageBase.cs:83), and a careful IAsyncDisposable/IDisposable teardown. The fetch path is Result-shaped end to end: a failed page toasts through NotifyOnFailure(Toast, Localizer) and returns an empty grid rather than throwing (DataGridListPageBase.cs:772-773). It also solves a Blazor render-mode problem: grid data captured during SSR prerender is persisted through PersistentComponentState as a private PersistedGridState record (DataGridListPageBase.cs:1132), restored in OnInitialized (:179-189) and re-registered for persisting with an explicit RenderMode.InteractiveAuto, because a page that inherits its render mode from <Routes> gives the framework nothing to associate the callback with (DataGridListPageBase.cs:191-208, ADR-056). A PrerenderFetchTimeoutMs of 5000 caps how long prerender may block on a cold backend before falling back to an empty grid the first interactive fetch refills (DataGridListPageBase.cs:95, applied at :820). That fetch links the timeout to the page's own lifetime token, read through ComponentLifetimeExtensions.LifetimeToken (DataGridListPageBase.cs:816-817, MMCA.Common.UI/Common/ComponentLifetimeExtensions.cs:18, :26): reading Token off a disposed CancellationTokenSource throws ObjectDisposedException, so a load that resumed after the user navigated away would crash the circuit, whereas the extension returns an already-cancelled token and the work stops through its ordinary cancellation path (ComponentLifetimeExtensions.cs:3-11, :28-41). LatestLoadGuard and DetailPageBase read their tokens the same way (LatestLoadGuard.cs:58, DetailPageBase.cs:36), and LifetimeTokenConventionTestsBase pins the rule in each repo (ComponentLifetimeExtensions.cs:13-14). [Rubric §23, Front-End Performance & Rendering] assesses render efficiency and avoided round-trips; this persist-and-restore dance is that concern made concrete. Around the base sit three smaller helpers that are deliberately not members of it, so a page composing its own layout can still use them: ListPageActions (MMCA.Common.UI/Pages/Common/ListPageActions.cs:15) holds the mobile-versus-desktop reload dispatch and the confirm-delete-reload flow every organizer list page repeats (:25-38, :56); LatestLoadGuard (MMCA.Common.UI/Common/LatestLoadGuard.cs:38) gives each load a generation and a token and cancels the previous one, which is what keeps a routed detail component (reused by Blazor across route-parameter changes) from rendering entity 100's late answer after the user has navigated to 101 (LatestLoadGuard.cs:50-59, :67); and OfflineFirstPageSnapshot<TItem> (MMCA.Common.UI/Pages/Common/OfflineFirstPageSnapshot.cs:29) records the first page of a list into ILocalCacheStore as a private CachedPage record (:39) and serves it back only when the device reports itself offline, the store is available and the request is page 1, so the live path is untouched (OfflineFirstPageSnapshot.cs:43, :49, :67). The single-aggregate counterpart of the list base is DetailPageBase (MMCA.Common.UI/Pages/Common/DetailPageBase.cs:26), an abstract ComponentBase that owns what every detail page loaded by route id otherwise repeats: a page-scoped PageToken that cancels in-flight work when the page goes away (:36), a LatestLoadGuard for route-driven reloads (:43), and the inline edit lifecycle, where BeginEdit and EndEdit both reset IsDirty so the flag an unsaved-changes guard reads can never be left set behind a closed editor (:46-49, :68-79, rationale at :15-19). A derived page keeps only its load, its edit-model copy and its save, and releases its own disposables in a Dispose(bool) override that calls the base last (:22-23, :86-101). [Rubric §22, Responsive & Cross-Browser] is named by BreakpointConstants and exercised by MobileInfiniteScrollList<TItem> (MMCA.Common.UI/Components/Lists/MobileInfiniteScrollList.razor.cs:20), the mobile card list whose IntersectionObserver sentinel, 500-item MaxRenderedItems cap (:52) and generation-guarded supersession of in-flight fetches keep a long list bounded; a page that wants infinite scroll without giving up its own card markup renders InfiniteScrollSentinel alone (MMCA.Common.UI/Components/Lists/InfiniteScrollSentinel.razor.cs:21), which owns just the observer and is disposed by the renderer the moment the host stops rendering it (:6-20).

State preservation across navigation. Paging, sort, filters and density live in the URL query string as the source of truth, encoded and decoded by ListPageQueryStateService under deliberately short reserved keys (p, ps, mp, s, sd, d, q, f:<name>) with defaults omitted so a pristine list page has a clean URL (MMCA.Common.UI/Services/ListPageQueryStateService.cs:15-40), so deep links and browser back/forward replay correctly. The noisier scroll offset lives in ListPageStateService (MMCA.Common.UI/Services/ListPageStateService.cs:63), a per-circuit scoped service whose synchronous dictionary is the fast path and whose HydrateFromSessionAsync (ListPageStateService.cs:103) / PersistToSessionAsync (:138) mirror entries through sessionStorage via a nav-interop.js module (:65) so state survives circuit teardown, forceLoad navigation and the SSR to WASM transition. Every JS path there is defensively caught (prerender, disconnected circuit, Safari private mode) so storage can never break the page. The immutable ListPageState record (ListPageStateService.cs:9) carries page, page size, mobile page, scroll, sort, density and a page-specific filter dictionary, and is updated with with expressions. NavigationHistoryService (MMCA.Common.UI/Services/Navigation/NavigationHistoryService.cs:12) bridges Blazor's NavigationManager to the browser history API so a detail page can perform a real history.back() when a previous entry exists and fall back to a fixed path otherwise. [Rubric §19, State Management & Data Flow] assesses a deliberate, scoped state model rather than ambient globals: these are registered Scoped, so each circuit gets its own instance (MMCA.Common.UI/DependencyInjection.cs:175-177). [Rubric §25, Navigation & Information Architecture] covers the route catalogue (RoutePaths (MMCA.Common.UI/Common/RoutePaths.cs:7), NavItem with its role, claim, permission, section and group facets plus resource-key titles resolved per circuit (MMCA.Common.UI/Common/NavItem.cs:20), and the NavSection enum whose declaration order is the sidebar order, MMCA.Common.UI/Common/NavSection.cs:7-17) and the open-redirect guard ReturnUrlProtector, which accepts only same-origin relative paths beginning with a single forward slash and rejects protocol-relative forms, backslashes, control characters and anything that does not parse as a relative URI, replacing each with a fallback (MMCA.Common.UI/Services/Navigation/ReturnUrlProtector.cs:18-60).

Authentication, the host-polymorphic token refresh, and the devices page. Client-side auth is contracted by IAuthUIService (MMCA.Common.UI/Services/Auth/IAuthUIService.cs:18), whose members are Result-returning like the entity services, and implemented by AuthUIService (MMCA.Common.UI/Services/Auth/AuthUIService.cs:44), which calls the WebAPI auth/* endpoints, persists tokens through ITokenStorageService, pushes auth-state changes through JwtAuthenticationStateProvider so AuthorizeView reacts immediately, and coordinates push-registration through the device-capability contract IPushRegistrationService (AuthUIService.cs:49). Two named codes make its local-only failures legible rather than null: Auth.TokenStorageUnavailable when the sign-in succeeded but JS interop could not persist the tokens, and Auth.MissingAccessToken when a 2xx carried no usable token, which means the response shape drifted (AuthUIService.cs:57, :63). The provider round trip is bound to the client that started it: OAuthFlowStateStore (MMCA.Common.UI/Services/Auth/OAuth/OAuthFlowStateStore.cs:20) mints a 32-character random hex value before the challenge and persists it to device-local storage under auth.oauth-flow as a private PendingAttempt record (:23, :53-56, :89), then refuses a completion whose returned state does not match, or whose attempt is older than the 10-minute lifetime, removing the attempt either way so one value is redeemable exactly once (:29, :68-87). The reason that matters is stated on the type: the completion code is a bearer value, so without a binding an attacker can complete the provider flow with their own account and hand the victim the completion link, signing the victim's app in as the attacker (OAuthFlowStateStore.cs:8-16). A host with no durable storage at all reports IsEnforced false and keeps the previous behavior, because nothing can be written across the redirect (:39, :48-51, :70-73). Alongside login, register, OAuth exchange, logout, refresh and change-password, it carries the self-service reset pair (IAuthUIService.cs:60, :67, ADR-091) and the multi-device session pair: GetSessionsAsync lists the caller's live refresh sessions newest first and RevokeSessionAsync ends one of them (IAuthUIService.cs:75, :84, ADR-097). Those two are rendered by the framework-owned Sessions page (MMCA.Common.UI/Pages/Auth/Sessions.razor.cs:27), reachable at /profile/sessions (RoutePaths.cs:16), which deliberately offers two revoke paths: a per-row sign-out that ends one other device's session, and a page-level sign-out-everywhere that also ends the caller's own and is therefore followed by the local logout and a redirect. The current device's row carries no button at all, since revoking it from here would leave the app signed in on a dead session until the access token expired (Sessions.razor.cs:16-24, :110-112). The page-level path is RevokeAllSessionsAsync, which signs out locally only once the server confirmed the revoke (IAuthUIService.cs:94), and one busy flag disables every button while any revoke is in flight, so a second click cannot race the list rebuild (Sessions.razor.cs:52-55). Each row is labelled from UserAgentSummary (MMCA.Common.UI/Services/Auth/UserAgentSummary.cs:18), which extracts a browser and a platform from the raw header with the most specific token winning (every Chromium browser also says "Chrome", and Chrome and Edge both say "Safari", UserAgentSummary.cs:20-38) and returns the two parts separately, because composing "Chrome on Windows" in code would hard-code English word order (UserAgentSummary.cs:13-16).

Email confirmation (ADR-116) ships the same way, as a framework page over a framework client. IEmailConfirmationUIService (MMCA.Common.UI/Services/Auth/IEmailConfirmationUIService.cs:21) is a separate interface rather than two new IAuthUIService members, so a consumer's own IAuthUIService implementation keeps compiling (MMCA.Common.UI/DependencyInjection.cs:164-166). Its two anonymous, Result-returning calls redeem a link's single-use token and ask for a fresh link, the latter answering success on any well-formed request because the endpoint returns 202 whether or not the address holds an account (IEmailConfirmationUIService.cs:28, :30-38). The in-box EmailConfirmationUIService (MMCA.Common.UI/Services/Auth/EmailConfirmationUIService.cs:23) is deliberately not built on the entity-service bases: the token is single-use and the resend spends a per-address request budget, so a retried POST could only spend either one twice. It takes the "APIClient" straight from the factory, posts exactly once and reads the answer through ProblemDetailsResultReader inside HttpResultExecutor (EmailConfirmationUIService.cs:13-21, :35-48). The anonymous ConfirmEmail page (MMCA.Common.UI/Pages/Auth/ConfirmEmail.razor.cs:36, routed at /confirm-email, ConfirmEmail.razor:1) reads the email and token from the URI fragment, which a browser never sends to a server, so the live token stays out of ingress logs, request telemetry and Referer headers; the locationHashTake interop call also scrubs it from the address bar and history, with query-string parameters honored as a fallback (ConfirmEmail.razor.cs:17-22, :139). A link carrying both values is redeemed once on the first interactive render, a link missing either lands on manual entry without posting a request that can only be refused, and a refused token keeps the form with the API's own message and a resend button (:25-30, :108-128). What the page shows is the private three-value ConfirmationState enum, Working, Form and Confirmed (ConfirmEmail.razor.cs:50-60).

The refresh is the interesting part: one ITokenRefresher abstraction (MMCA.Common.UI/Services/Auth/Tokens/ITokenRefresher.cs:17) has two implementations picked per host, SameOriginProxyTokenRefresher for the browser (the refresh token lives in an HttpOnly cookie and rotation happens server-side behind a same-origin /auth/session/token proxy, so JS never sees it) and DirectApiTokenRefresher for MAUI (the refresh token sits in OS SecureStorage and is exchanged directly against auth/refresh). Storage is host-polymorphic in the same way: WasmTokenStorageService holds the access token in memory only and single-flights its re-acquisition behind a lock, since an unguarded ??= lets two callers each start a hydrate and the later one overwrite the other's token (MMCA.Common.UI/Services/Auth/Tokens/WasmTokenStorageService.cs:22, :22-38), while ServerTokenStorageService reads the HttpOnly cookie through CookieTokenReader whenever a live HttpContext exists (SSR prerender) and switches to the in-memory token on the interactive circuit (MMCA.Common.UI.Web/Services/ServerTokenStorageService.cs:30, :30-43, ADR-022). The same AddCommonServerTokenStorage() also puts BrowserOriginHandler (MMCA.Common.UI.Web/Services/BrowserOriginHandler.cs:32) on the server-side "APIClient" (MMCA.Common.UI.Web/DependencyInjection.cs:41, :47-48): a Blazor Server host calls the API on the visitor's behalf, and without it every visitor would share the host's own address and send no user-agent, so the registration rate limit and the session's recorded IP and device would key on the host. It forwards X-Forwarded-For from the request's RemoteIpAddress, which has already been through this host's forwarded-headers middleware rather than copied from whatever the client sent, plus the browser's User-Agent, replacing any value already present and sending nothing when no request is in scope (BrowserOriginHandler.cs:5-29, :47-52, :57-68). A third contract, ISecureTokenStore (MMCA.Common.UI/Services/Auth/Tokens/ISecureTokenStore.cs:16), is raw persistence with no freshness semantics, and it exists to keep the MAUI graph acyclic: storage depends on the refresher, the refresher depends on the raw store, and there is no loop (ISecureTokenStore.cs:5-14). A refresher can also say why it came back empty. ITokenRefresher answers null both for "there is no session" and for a transient failure, so the optional ISessionAwareTokenRefresher (MMCA.Common.UI/Services/Auth/Tokens/ISessionAwareTokenRefresher.cs:12) adds TryAcquireAccessTokenAsync, which returns a TokenAcquisition (MMCA.Common.UI/Services/Auth/Tokens/TokenAcquisition.cs:9): NoSession for the endpoint's 401, Unavailable for a 429 or 5xx, a dropped connection, missing JS interop or a cancelled call, and Acquired(token) otherwise (ISessionAwareTokenRefresher.cs:17, TokenAcquisition.cs:3-8, :18, :21, :35). Storage that remembers a "no session" answer for an anonymous grace period starts the grace only on the definitive kind, so one 429 cannot sign a signed-in user out for the whole window, and a refresher that does not implement the interface keeps the old reading of null as "no session" (ISessionAwareTokenRefresher.cs:3-11). On WebAssembly the first hydration (a JS interop hop for the session cookies plus a same-origin token exchange) would otherwise run inline on whichever API call the user makes first, so a client host may start TokenHydrationWarmup (MMCA.Common.UI/Services/Auth/Tokens/TokenHydrationWarmup.cs:26) after builder.Build() and discard the task, letting it overlap first render instead of delaying it (:11-15). It only reads through ITokenStorageService.GetAccessTokenAsync, which never forces a refresh, so an anonymous visitor gets a no-op, and it swallows and debug-logs every failure because the first real call hydrates again with its own handling (TokenHydrationWarmup.cs:18-22, :36-57); the ADC client wires it that way (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web.Client/Program.cs:92). The ISessionCookieSync / JsFetchSessionCookieSync pair mirrors the in-memory access token into the cookie by firing the fetch from the browser, so the Set-Cookie lands in the user's own jar under both render modes, and both calls report whether the jar was actually updated, false on a non-2xx answer or when JS interop is unavailable (MMCA.Common.UI/Services/Auth/ISessionCookieSync.cs:8-19, JsFetchSessionCookieSync.cs:26-34). All three storage services agree on one 30-second expiry skew read through JwtTokenInfo.IsFresh (MMCA.Common.UI/Services/Auth/Tokens/JwtTokenInfo.cs:16-37, used at WasmTokenStorageService.cs:15,24 and ServerTokenStorageService.cs:41), which parses the token client-side without validating its signature, because the API validates every request. Every outbound call also passes AuthDelegatingHandler, which attaches the stored bearer token to requests that do not go through CreateAuthenticatedClientAsync (MMCA.Common.UI/Services/Auth/AuthDelegatingHandler.cs:14), except one that sets its SkipBearer request option: the token-refresh POST does, because that endpoint is anonymous and reading storage from inside a refresh would re-enter the very acquisition waiting on it (AuthDelegatingHandler.cs:9-19). The lifecycle across render modes is ADR-051; the cross-service JWKS validation these tokens flow into is ADR-004.

An opt-in same-origin API proxy: no token in the page at all. By default a browser client still holds an access token in memory, the one /auth/session/token hands to script. A Blazor Web host can remove even that by calling AddCommonSameOriginApiProxy(configuration) and MapCommonSameOriginApiProxy() from MMCA.Common.UI.Web, a backend-for-frontend in which the browser calls /api/** on the UI host's own origin and the host forwards to the gateway with the bearer taken from the HttpOnly session cookie (SameOriginApiProxyServiceExtensions, MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyServiceExtensions.cs:12-18, :51; SameOriginApiProxyEndpointExtensions, MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpointExtensions.cs:15, :33). SameOriginApiProxySettings (MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxySettings.cs:21) binds SameOriginApiProxy with a default for every value, so a host opts in with no section at all: a /api PathPrefix, a GatewayAddress that falls back to Api:ApiEndpoint so a service-discovery name resolves exactly as it does for the host's own clients, auth/login, auth/register and auth/oauth/exchange as the token-issuing paths, auth/refresh and auth/revoke, and SameSite=Strict session cookies (:31, :38, :46, :52, :59, :66, :74; the gateway fallback at SameOriginApiProxyServiceExtensions.cs:57-64). SameOriginApiProxySettingsValidator (MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxySettingsValidator.cs:14) runs on start and refuses a prefix or path carrying route syntax, a query, a fragment or whitespace, a gateway that is not an absolute address, and any SameSite other than Strict or Lax, because a cookie that authenticates data calls must never ride on a cross-site request (:7-13, :16, :26-49). Opting in also makes the session cookies claims-only toward the browser and has /client-config advertise the proxy, which is what moves the WebAssembly "APIClient" and notification hub onto it (SameOriginApiProxyServiceExtensions.cs:21-28, :69-74).

Each request runs through SameOriginApiProxyEndpoint (MMCA.Common.UI.Web/SameOriginProxy/SameOriginApiProxyEndpoint.cs:29) in a fixed order (:15-28). A foreign Origin or Sec-Fetch-Site is refused with 403 before anything else, and a WebSocket upgrade must carry this host's own Origin, because an upgrade is not CORS-protected and the origin is the only proof of who opened it (:115-131, :232-237); OPTIONS is answered locally with 204 and no CORS grant, so the gateway's CORS policy is never consulted on the proxy's behalf (:241-245); and every unsafe method must carry the X-CSRF: 1 header named by SameOriginProxyHeaders (MMCA.Common.UI/Services/Auth/SameOriginProxyHeaders.cs:11, :14, :17), the one exemption being an HTTP/2 WebSocket, to which a browser cannot add a header (SameOriginApiProxyEndpoint.cs:250-254). The header is defense in depth behind the origin check and carries no secret (SameOriginProxyHeaders.cs:3-9). The session step then validates or refreshes the cookie's access token through the single-flighted ICookieSessionRefresher: a refused refresh token clears the cookies and answers 401, while a refresh that could not be decided keeps them and answers 503 with Retry-After, so a blip at the identity endpoint does not sign the user out (:22-25, :261-284). A browser POST to the refresh path is answered by the proxy itself from the refresh cookie (:351-356), and a safe method the gateway answers 401 gets one forced refresh and one replay, never an unsafe one whose body the upstream could apply twice (:313-328). The per-request YARP transform is SameOriginProxyTransformer (MMCA.Common.UI.Web/SameOriginProxy/SameOriginProxyTransformer.cs:34): it maps {prefix}/rest to {gateway}/rest, replaces whatever Authorization the browser sent with the session's bearer, and keeps the session cookies and the CSRF header off the upstream request (:26-33, :55-62). Its ProxyResponseMode (:14) picks the response treatment: Forward copies, TokenIssuing moves a sign-in's token pair into the cookies and sends the browser the same JSON with a claims-only accessToken and an empty refreshToken under no-store, and Revoke clears the cookies whatever the upstream answered, so a failed revoke cannot strand the user in a session (:16-23, :84-95, :100-145). Forwarding goes through SameOriginProxyInvoker (MMCA.Common.UI.Web/SameOriginProxy/SameOriginProxyInvoker.cs:19), one HttpMessageInvoker built the way YARP requires rather than taken from IHttpClientFactory: no cookie container, which would replay one user's upstream cookies on another user's request, no redirects or decompression, and none of the host's default handlers, since a retry would replay a streamed body and the trusted-caller header would exempt every browser request from the gateway's rate limiter (:9-18, :50-58). On the client, SameOriginProxyRequestHandler (MMCA.Common.UI/Services/Auth/SameOriginProxyRequestHandler.cs:11) is the innermost "APIClient" handler: it strips any Authorization header, since the client only ever holds a claims-only token, and stamps the CSRF header (:3-10, :18-20).

The Blazor Server circuit keeps calling the gateway server-to-server, but its tokens still have to meet the browser's cookie jar, which it can reach only through a script fetch. The proxy therefore replaces the circuit's ITokenRefresher and ISessionCookieSync with HandoffTokenRefresher and HandoffSessionCookieSync (SameOriginApiProxyServiceExtensions.cs:83-84, MMCA.Common.UI.Web/SameOriginProxy/HandoffSessionServices.cs:14, :39), which trade only ciphertext with the page. SessionHandoffProtector (MMCA.Common.UI.Web/SameOriginProxy/SessionHandoffProtector.cs:16) encrypts and signs with the host's data-protection key ring under one purpose each way, so an access-token handoff can never be replayed as a cookie write, and expires a handoff after one minute (:7-15, :19, :23-27); a tampered, expired or wrong-purpose value unprotects to null (:57-72), and the cookie direction serializes the pair as the private TokenPair record (:33-34, :75). SessionHandoffEndpoints (MMCA.Common.UI.Web/SameOriginProxy/SessionHandoffEndpoints.cs:15) maps the two halves, POST /auth/session/handoff (validate-or-refresh from the cookies, answered with a protected access token) and POST /auth/session-cookie/handoff (seed the cookies from a protected pair), both requiring the CSRF header and both exchanging the HandoffBody { "handoff": "..." } record (:17-18, :23-60, :64). Because a registration that lands later would silently put the access token back in the page, MapCommonSameOriginApiProxy resolves both services and fails the boot naming the culprit when either is not the handoff implementation, and it also fails when AddCommonSameOriginApiProxy was never called, which it detects through the internal SameOriginApiProxyMarker (SameOriginApiProxyEndpointExtensions.cs:38-44, :59-92, SameOriginApiProxyServiceExtensions.cs:91-92). [Rubric §26, Front-End Security] is the home category: with the proxy on, no token is readable by script on the page.

Front-end security beyond tokens. [Rubric §26, Front-End Security] assesses token handling, XSS exposure and secret storage, and this group answers it in five places: keeping the refresh token out of JS-reachable storage (above); BlazorCspPolicyProvider, which pins connect-src to 'self' plus the configured API/Gateway origin and its wss form for the SignalR hub (MMCA.Common.UI.Web/Security/BlazorCspPolicyProvider.cs:28, :49-79) and, when the endpoint cannot be parsed, fails closed: connect-src narrows to 'self' and the policy stays enforced, so a misconfiguration surfaces immediately as blocked calls in the console rather than as a Report-Only header that protects nothing and nobody notices (BlazorCspPolicyProvider.cs:16-20, :60-62), feeding the shared SecurityHeadersMiddleware through ICspPolicyProvider; WebApplicationExtensions.UseAuthenticatedNoStore, which emits Cache-Control: no-store on authenticated HTML so a logged-out user pressing Back never sees the previous user's page out of the bfcache while anonymous pages stay bfcache-eligible (MMCA.Common.UI/Extensions/WebApplicationExtensions.cs:24-44); the returnUrl sanitizer already covered; and, on a native head, the app-lock overlay BiometricGate (MMCA.Common.UI/Components/Capabilities/BiometricGate.razor.cs:18), which re-arms once the app has sat in the background longer than its 30-second ReLockAfter parameter, short by design because a device handed to someone else is usually away for longer than a glance at a notification (BiometricGate.razor.cs:19-25). It subscribes to the resume event regardless of the current preference, since app lock can be switched on later in the same session and the handler re-reads the preference every time it fires (:52-55), and it moves focus onto the unlock button once the locked branch has actually rendered, so the panel is a real interaction boundary rather than a picture of one (:31-45).

The CSP has exactly one host-configurable allowance, and it is configured rather than coded. BlazorCspSettings (MMCA.Common.UI.Web/Security/BlazorCspSettings.cs:18) binds the BlazorCsp section and carries a single FrameSources list, the https origins this host's pages may embed in an iframe (:21, :35); with the default empty list the provider emits no frame-src directive at all, so frames fall back to default-src 'self' and the baseline policy stays byte-identical (BlazorCspPolicyProvider.cs:85-90), and when the list is non-empty the origins are canonicalized to scheme://host[:port] and de-duplicated ordinally before being joined into frame-src 'self' ... (BlazorCspPolicyProvider.cs:92-96, BlazorCspSettingsValidator.cs:61-62). frame-ancestors 'none', which governs who may frame this host, is never relaxed by any of it (BlazorCspPolicyProvider.cs:113). Because each entry is spliced verbatim into a security response header, the value is validated at startup rather than at first use: BlazorCspSettingsValidator (MMCA.Common.UI.Web/Security/BlazorCspSettingsValidator.cs:13) is registered with ValidateOnStart and rejects anything that is not a plain https origin, refusing whitespace and the character set *'";,@?# outright (:19, :42-48) and then requiring the https scheme, a non-empty host and a root-only path (:52-54), with a failure message naming the offending entry so the boot log says which one (:26-36). The reasoning is on the type: a quote, semicolon or space could smuggle a keyword or a whole new directive into the policy, and a wildcard or bare scheme would widen frame-src to arbitrary sites (BlazorCspSettingsValidator.cs:6-12). The options registration and the validator are added by the same AddCommonBlazorCsp() that registers the provider, the validator through TryAddEnumerable so calling the method twice does not run the validation twice (MMCA.Common.UI.Web/DependencyInjection.cs:67-77).

The UI host's own edge: a request limiter. The Blazor Web host is an externally reachable origin separate from the Gateway, so the edge limiter of ADR-088 never sees a request to it, while every page load there opens an interactive Server circuit in a container typically sized at 0.25 vCPU and 0.5 GiB (MMCA.Common.UI.Web/Hardening/UiRateLimitingSettings.cs:11-15). MMCA.Common.UI.Web therefore ships a limiter of its own. UiRateLimitingSettings (UiRateLimitingSettings.cs:33) binds the UiRateLimiting section with an Enabled switch that defaults on, a per-IP PermitLimit of 300 over a 60-second WindowSeconds, and a replica-wide GlobalConcurrencyLimit of 200 (:36, :43, :58, :62, :76). The 300 sits well above any single visitor on purpose, because an office or carrier NAT presents many visitors as one address, and a host whose audience shares one egress (a venue's wifi) is told to raise it (:49-55). UiRateLimitingExtensions (MMCA.Common.UI.Web/Hardening/UiRateLimitingExtensions.cs:25) turns that into a chained global limiter, so a request must pass both a fixed window keyed by client IP and one concurrency bucket for the whole process, each with a zero-length queue so excess is rejected with 429 at once rather than queued (:101-108, :126-133, :163, :172-176). The settings are validated on start and then closed over once rather than resolved per request, because the partition callback runs on every request (:150-159). Exemptions are declared rather than inferred from middleware order: /health, /alive, /_framework, /_content and /hubs match on whole segments, and any path whose last segment carries a file extension counts as a static asset, while /_blazor has neither and stays metered because its negotiate is exactly what opens a circuit (:42, :50-56, :62-70). An unresolvable client IP fails open instead of collapsing every such request into one shared bucket (:93-98), and both counts are per replica and in memory, the same trade the Gateway kit makes so the limiter never puts a network round trip in front of the site (UiRateLimitingSettings.cs:27-30). AddUiRateLimiting(configuration) registers it and UseUiRateLimiting() adds the middleware (UiRateLimitingExtensions.cs:145, :187).

And a ceiling on open circuits. A rate still lets a caller who opens circuits slowly enough accumulate them, and CircuitOptions only bounds circuits that have already disconnected, which is what the second bound closes (MMCA.Common.UI.Web/Hardening/BlazorCircuitLimitSettings.cs:10-15). BlazorCircuitLimitSettings (BlazorCircuitLimitSettings.cs:17) binds BlazorCircuitLimits with a MaxActiveCircuits of 200 per replica, derived from that container's memory and stated as an abuse ceiling rather than a capacity plan, plus a tighter disconnected retention of 25 circuits for 60 seconds against the framework's 100 and three minutes (:20, :27-38, :46, :57). BoundedCircuitHandler (MMCA.Common.UI.Web/Hardening/BoundedCircuitHandler.cs:43) keeps the count as a CircuitHandler, the documented extension point that sees a circuit open and close (:14-20). It increments first and rolls back on refusal so two simultaneous opens cannot both take the last slot, floors the close-side decrement at zero so an unpaired close never hands out permits forever, and runs last among the registered handlers (:55, :64-73, :84-88). Refusal is a thrown InvalidOperationException, one of the few places the Result pattern does not apply, because OnCircuitOpenedAsync returns a Task with no refuse value; the client sees Blazor's reconnect UI rather than a crashed page (:23-28, :70-72). BlazorCircuitLimitExtensions (MMCA.Common.UI.Web/Hardening/BlazorCircuitLimitExtensions.cs:19) keeps the two halves as separate calls because they attach to different builders: RetentionFrom(configuration) returns the CircuitOptions callback for AddInteractiveServerComponents, and AddBoundedBlazorCircuits() validates the options on start and registers the handler as a singleton, since circuit handlers resolve from each circuit's own scope and a scoped one would count to one and cap nothing (:13-17, :28-40, :51-60). Both read the same section, so the two numbers cannot drift apart. The ADC Blazor Web host wires all four calls (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:72, :62, :127, :197). [Rubric §12, Performance & Scalability] and [Rubric §29, Resilience]: a public origin sheds load at its own edge instead of letting an unauthenticated loop exhaust its container.

Forms declare their rules once. The shared auth forms (LoginModel, RegisterModel, ForgotPasswordModel, ResetPasswordModel) are plain data-annotation EditForm models, with PasswordComplexityAttribute mirroring the server's rule (at least 8 characters with upper, lower, digit and a non-alphanumeric character) so the form gives the verdict the API would, and deferring empty input to [Required] so a blank field shows one message rather than two (MMCA.Common.UI/Pages/Auth/PasswordComplexityAttribute.cs:15, :21-30). OptionalEmailAttribute (MMCA.Common.UI/Validation/OptionalEmailAttribute.cs:25) covers the optional address the stock [EmailAddress] cannot express: blank passes, and anything else must hold exactly one @ that is neither first nor last, the server's EmailRules check (OptionalEmailAttribute.cs:5-23, :38-41). The auth models resolve their messages through the internal AuthFieldMessages (MMCA.Common.UI/Resources/AuthFieldMessages.cs:19) as an ErrorMessageResourceType, reading SharedResource in the current UI culture with the key itself as fallback, because MudBlazor also runs a For field's attributes on its own and shows the message verbatim, so a bare resource key there reached the screen raw (AuthFieldMessages.cs:11-18, :44). AbsoluteUrlAttribute (MMCA.Common.UI/Validation/AbsoluteUrlAttribute.cs:26) is the same parity argument with sharper stakes: it requires an absolute http/https URL (:39-52) because these values are rendered straight into an image source or a link target, so accepting javascript: or data: on the client and rejecting it on the server would leave a round trip as the only thing between a pasted script URL and the page (AbsoluteUrlAttribute.cs:5-11). Beyond the auth pages, MudBlazor fields bind their Validation parameter to a delegate from ModelValidation.For (MMCA.Common.UI/Validation/ModelValidation.cs:26, :43-49), which hands the model and the member path MudBlazor supplies to an IModelValidator (MMCA.Common.UI/Validation/IModelValidator.cs:13). That indirection is the extension point: the in-box DataAnnotationsModelValidator (MMCA.Common.UI/Validation/DataAnnotationsModelValidator.cs:21) runs the attributes on the model and resolves every produced message as a resource key with pass-through, so a model can declare ErrorMessage = "Validation.AbsoluteUrl" and a plain-English message still renders verbatim (DataAnnotationsModelValidator.cs:13-19, :36-41); an EditForm gets the same localizing path by swapping <DataAnnotationsValidator /> for LocalizedDataAnnotationsValidator (MMCA.Common.UI/Validation/LocalizedDataAnnotationsValidator.cs:21), which writes the results into the form's EditContext, re-validating a field when it changes and the whole model on submit (:9-20); a consumer that keeps its rules in FluentValidation supplies its own implementation and MMCA.Common.UI never references a validation library. That client-side parity is the point of [Rubric §24, Forms, Validation & UX Safety]: the client predicts, the server decides.

Sign-in, registration and terms acceptance ship as framework pages. The /login page's Login code-behind (MMCA.Common.UI/Pages/Auth/Login.razor.cs:8) reads the error query value the OAuth completion endpoint sends a refused external sign-in back with and maps the machine code to words, never showing the raw code, with a dedicated resource for each refusal that carries its own recovery path and a generic refusal for the rest (:15-21, :23-29); when device storage dropped the OAuth attempt it disables the web-redirect provider buttons, since a flow started there would be refused at completion (:10-14). The /register page's Register (MMCA.Common.UI/Pages/Auth/Register.razor.cs:10) validates any address the user did type and blocks the registration on an invalid one instead of dropping it, while an all-blank block sends no address (:15-40); the whole block is switchable through RegistrationSettings.CollectAddress, bound from Registration and defaulting to true so a host that configures nothing keeps the page as it was (MMCA.Common.UI/Common/Settings/RegistrationSettings.cs:8, :11, :18). Legal documents are LegalSettings (MMCA.Common.UI/Common/Settings/LegalSettings.cs:16), bound from Legal: optional absolute URLs for the terms, the privacy policy, the code of conduct and the account-deletion page, where an empty value renders nothing and a set TermsUrl is what makes the register page require "I agree"; the current terms version itself stays server configuration (LegalSettings.cs:5-15, :22, :26, :30, :34, :41). Consent owed after sign-up is TermsAcceptanceGate (MMCA.Common.UI/Components/Legal/TermsAcceptanceGate.razor.cs:29): it reads the signed-in user's standing once per user from OnAfterRenderAsync, because the bearer token is readable only once the renderer is interactive, renders nothing on any failed read so the gate never takes the app down with the API, and otherwise holds a dialog with no close button, backdrop click, Escape or close-on-navigation, since a list page rewriting its own URL right after load would otherwise dismiss it for the rest of the session (:19-28, :31-45). Its client is ILegalAcceptanceUIService (MMCA.Common.UI/Services/Legal/ILegalAcceptanceUIService.cs:16), a Result-returning GetAsync and AcceptAsync against Users/me/legal-acceptance that never throws for a server answer or a transport fault, so a caller treats any failure as "do not block" (:6-15, :21, :27), implemented by LegalAcceptanceUIService (MMCA.Common.UI/Services/Legal/LegalAcceptanceUIService.cs:23) on the authenticated-service shape: the read is retried, the accept POST is sent once (:14-20, :29-40; registered for every host at MMCA.Common.UI/DependencyInjection.cs:168-170). On the profile page, ChangePasswordCard (MMCA.Common.UI/Components/Auth/ChangePasswordCard.razor.cs:18) validates all three fields client-side first (the new password at least MinLength, 8 by default, and the confirmation equal to it) and calls IAuthUIService.ChangePasswordAsync only for a valid form, toasting a success in its own words and a refusal with the server's reason (:9-17, :33-38).

The component library is behind two facades. IToastService (MMCA.Common.UI/Common/Interfaces/IToastService.cs:37) and IAppDialogService (MMCA.Common.UI/Common/Interfaces/IAppDialogService.cs:14) are the only way page code raises a transient notification or asks a yes/no question. The toast contract carries the four named severities plus a runtime-severity Show, a two-line ShowPersistent that stays until dismissed (the push-notification shape: a message that arrived unprompted must not expire before the user looks at the screen, IToastService.cs:64-72) and a ShowAction that renders a button for the undo/view/retry case, with the explicit warning that the callback runs outside any render callback so a caller whose work can fail must guard it (IToastService.cs:74-101); severity itself is the framework's own ToastSeverity enum (IToastService.cs:8). MudToastService (MMCA.Common.UI/Services/MudToastService.cs:19) and MudAppDialogService (MMCA.Common.UI/Services/MudAppDialogService.cs:11) are the only two types in the framework that name MudBlazor's ISnackbar and IDialogService, and even the severity projection is written out as a switch rather than cast, because the two enums agreeing numerically today is not a dependency worth taking silently (MudToastService.cs:92-104). Announcement is deliberately not this service's job: the shared provider block hosts MudBlazor's snackbar inside a role="status" aria-live="polite" element, so the rendered toast already is the live-region content and a second channel would read the same sentence twice (MudToastService.cs:12-17). The dialog facade collapses a dismissal (backdrop click, escape) onto false, so a caller only ever branches on true (MudAppDialogService.cs:14-26). Both are registered by their own AddCommonUiFacades() (MMCA.Common.UI/DependencyInjection.cs:228-233), separate from AddUIShared so a bUnit harness can resolve exactly these two without the rest of the shared-UI surface. [Rubric §1, SOLID] (dependency inversion) and [Rubric §14, Testability]: a component test records toasts instead of driving a rendered snackbar host.

Design system and theming. Visual consistency is centralized in one static MMCATheme MudTheme instance (MMCA.Common.UI/Theme/MMCATheme.cs:9, :11) holding a light palette (:13-55), a full dark palette (:56-111), an Inter-first typography scale (:112-190) and a 6 px default border radius (:191-194). It is applied through the shared MmcaThemeProviders component, which renders the four Mud providers every root layout needs exactly once and takes the theme as a parameter defaulting to MMCATheme.Instance, so an app with its own brand passes a derived MudTheme instead of duplicating the provider block (MMCA.Common.UI/Theme/MmcaThemeProviders.razor:33-36). The palette itself comes from a single C# source of truth, BrandColors (MMCA.Common.UI/Theme/BrandColors.cs:10), whose doc comment states the duplication contract plainly: the CSS custom properties in wwwroot/app.css must mirror these constants because C# cannot read CSS at build time, and BrandColorTokenTests asserts the two stay in sync (BrandColors.cs:3-9). Color choices carry explicit WCAG reasoning: Secondary is Teal 700 #00796B for about 5.3:1 on light surfaces because the Teal 600 it replaced sat at about 4.0:1, under the AA 4.5:1 floor (BrandColors.cs:21-26), and the light Warning is Amber 900 #A85D00 (4.96:1 on Surface, 4.79:1 on Background) rather than the Material amber #F57F17, which measures only about 2.65:1 on white and so fails the 4.5:1 floor everywhere the palette colour is used as text or as a border rather than as a fill, with WarningContrastText moved to white in the same edit because the two values have to move together (MMCATheme.cs:28-36). The dark palette makes the mirror-image choice, keeping rgba(0,0,0,0.87) on #FFA726, where white would be about 2.0:1 and dark text is about 10.8:1 (MMCATheme.cs:83-85). [Rubric §20, Design System, Theming & Consistency] is the home category (one token source, dark mode, consistent typography) and [Rubric §21, Accessibility] is woven into the palette itself and into the chrome, down to the skip-to-content link the shared layout renders first (MMCA.Common.UI/Layout/MainLayout.razor:17).

Dark mode is a service, not a flag. ThemeService (MMCA.Common.UI/Theme/ThemeService.cs:17, registered Scoped at DependencyInjection.cs:180) owns the preference: InitializeAsync reads the stored value through a theme.js module and falls back to the OS prefers-color-scheme only when nothing is stored (ThemeService.cs:35), SetDarkModeAsync persists through the same module and raises OnChange (ThemeService.cs:29, :54), and the JS module handle is held by LazyJsModule (MMCA.Common.UI/Services/LazyJsModule.cs:20), a single-flight importer that caches the in-flight import under a lock so two concurrent callers cannot leak a second module reference, and that drops a failed task so an import attempted during prerender does not poison the module for the rest of the circuit (LazyJsModule.cs:5-19, :22-25). MmcaThemeProviders subscribes to OnChange and re-renders (MMCA.Common.UI/Theme/MmcaThemeProviders.razor:52), and every best-effort theme interop call it makes goes through the internal ThemeInterop.TryAsync (MMCA.Common.UI/Theme/ThemeInterop.cs:9, :19-30), which turns a JSException, a JSDisconnectedException or an InvalidOperationException (a prerender race, a disposed dispatcher) into false, so a JS failure never escapes a component lifecycle and kills the circuit (MmcaThemeProviders.razor:62, :90). Honest caveat: on a web head the no-flash SSR bootstrap is not wired for theme. InitializeAsync runs from OnAfterRenderAsync(firstRender) because JS interop is unavailable during prerender (MmcaThemeProviders.razor:55-62), so the bound mode is corrected just after hydration and a brief wrong-theme first paint is possible (ADR-028). A head that already knows the stored preference without JS closes that gap by registering an IInitialThemeModeSource (MMCA.Common.UI/Theme/IInitialThemeModeSource.cs:14), whose synchronous IsDarkMode (null when unknown) MmcaThemeProviders reads during initialization, with the JS path still running afterwards and staying authoritative; a MAUI hybrid head reading device preferences is the intended implementer, and web heads register nothing (IInitialThemeModeSource.cs:3-13, :21, MmcaThemeProviders.razor:44-47).

Internationalization: one culture decision, carried everywhere. The framework serves en-US and Spanish (es) plus a development-only pseudo locale, and the hard part is not the translations, it is making one culture decision agree across the InteractiveAuto split (SSR prerender, then an InteractiveServer circuit, then an InteractiveWebAssembly client) and across the cross-origin REST services behind the Gateway, with no language flash and no hydration mismatch (ADR-027, which supersedes the single-locale stance of ADR-011). A single non-HttpOnly culture cookie is the source of truth. The WASM client reads it at startup through MmcaCultureBootstrap.SetBrowserCultureAsync, which assigns CultureInfo.DefaultThreadCurrent[UI]Culture before RunAsync() and falls back to SupportedCultures.Default (MMCA.Common.UI/Services/Culture/MmcaCultureBootstrap.cs:22-34). Outbound API calls forward the active culture as an Accept-Language header through CultureDelegatingHandler (MMCA.Common.UI/Services/Culture/CultureDelegatingHandler.cs:13, :20-25), wired into the "APIClient" pipeline at DependencyInjection.cs:146-147, because the cross-origin Gateway does not carry the cookie through to the services and that header is what makes a backend failure come back localized. View strings are externalized to co-located .resx resolved by IStringLocalizer<T> (AddLocalization() at DependencyInjection.cs:88), anchored by two marker types: SharedResource for cross-cutting chrome (MMCA.Common.UI/Resources/SharedResource.cs:9) and MudTranslations for MudBlazor's own component text (pager, filter menus, pickers, MMCA.Common.UI/Resources/MudTranslations.cs:10), served through ResxMudLocalizer, which AddUIShared TryAdds because AddMudServices registers no MudLocalizer of its own (DependencyInjection.cs:97-101) and whose values degrade to MudBlazor's built-in English when a key reports ResourceNotFound (MMCA.Common.UI/Globalization/ResxMudLocalizer.cs:7-19). How MudBlazor reaches that fallback is replaced too: AddUIShared installs InvariantMudLocalizationInterceptor (MMCA.Common.UI/Globalization/InvariantMudLocalizationInterceptor.cs:37) through MudBlazor's AddLocalizationInterceptor, which replaces the default regardless of whether AddMudServices ran first (MMCA.Common.UI/DependencyInjection.cs:110). The resolution order is unchanged (an English UI culture, or no MudLocalizer, reads the built-in strings; any other culture asks the MudLocalizer and falls back on ResourceNotFound, InvariantMudLocalizationInterceptor.cs:49-60), and the English test is the parent language, so en-US counts as English while the neutral en goes through the localizer like every other culture (:46-52). The one difference is how the built-in strings are read. MudBlazor 9.7+ assigns CultureInfo.CurrentUICulture to the invariant culture and then assigns the previous value back, and both writes land in an AsyncLocal, so the "restore" leaves the calling thread's ExecutionContext carrying an explicit culture from then on; on a MAUI hybrid head the renderer dispatches on the process's main thread, which nothing ever resets, so the first MudBlazor chrome string a page renders pins the app to its launch language and a later switch loses to the pinned value even after a WebView reload (:16-27). The private nested BuiltInStrings (InvariantMudLocalizationInterceptor.cs:73) reads the same embedded MudBlazor.Resources.LanguageResource through a ResourceManager with an explicit invariant culture instead, addressing it by manifest name because MudBlazor's generated resource class is internal (:75, :77, :89, :98-102), which is what the culture swap was for (no satellite-assembly probing under a non-English culture) with no culture assignment at all. Count-sensitive messages are handled by a suffix convention rather than by string concatenation: StringLocalizerPluralExtensions.Plural (MMCA.Common.UI/Globalization/StringLocalizerPluralExtensions.cs:20, :40) asks for {key}.One when the count is exactly one and {key}.Other otherwise, falling back to the base key when the plural sibling is missing so a resource set that has not been split yet keeps rendering its single message instead of leaking a raw key name to the reader (:46-51); the send confirmation is the current call site (MMCA.Common.UI/Pages/Notifications/NotificationSend.razor.cs:137). Two categories cover both shipped cultures, and a language with more CLDR categories needs a category selector rather than more suffixes, which would not change the call site (StringLocalizerPluralExtensions.cs:13-19). Applying a switch is host-specific and sits behind ICultureApplier: the web default EndpointCultureApplier force-loads the server /culture/set endpoint so the server re-renders SSR under the new cookie and the WASM runtime re-reads it on startup (MMCA.Common.UI/Services/Culture/EndpointCultureApplier.cs:18-32), while a MAUI hybrid head, having no ASP.NET pipeline, replaces it after AddUIShared with an in-process applier (MauiCultureApplier, chapter 26). The development-only pseudo locale is the group's own i18n test harness: PseudoStringLocalizerFactory decorates IStringLocalizerFactory unconditionally (DependencyInjection.cs:95, MMCA.Common.UI/Globalization/PseudoStringLocalizerFactory.cs:11) so every IStringLocalizer in the host is wrapped in a PseudoStringLocalizer at once, and PseudoLocalizer accents every letter, pads the text and wraps the result in a bracket sentinel while leaving { } placeholders verbatim (MMCA.Common.UI/Globalization/PseudoLocalizer.cs:20-30), which makes hard-coded strings, fixed-width layouts and concatenated fragments all visible in one pass (PseudoLocalizer.cs:12-19). Even the snackbar text is localized: ErrorMessages keeps its static call sites but resolves each message from SharedResource once the root layout hands it a localizer, falling back to the English format string until then (MMCA.Common.UI/Pages/Common/ErrorMessages.cs:24, :33), and it never renders an exception's own Message, because raw exception text is neither localizable nor safe to surface (ErrorMessages.cs:14-22). Time is shown on the viewer's clock rather than the server's: ViewerTimeZone (MMCA.Common.UI/Services/Culture/ViewerTimeZone.cs:18, registered scoped at MMCA.Common.UI/DependencyInjection.cs:190) reads the browser's IANA zone once per scope through time-zone.js, resolves it with TimeZoneInfo, and converts to UTC until then or whenever the zone cannot be read, never to the server's own zone, which on Blazor Server and during prerender is the wrong answer for every viewer elsewhere (ViewerTimeZone.cs:6-17, :32). A page calls EnsureResolvedAsync from its first OnAfterRenderAsync and re-renders when it returns true; during prerender the call is skipped and a later one retries (:49, :62-69). [Rubric §27, Internationalization] is the home category here, and adding a locale is a .es.resx sibling plus one allowlist entry, not new infrastructure.

Per-user preference persistence. A signed-in user's culture and theme follow them across devices via the Identity profile. IUserPreferenceWriter / ApiUserPreferenceWriter PUT to auth/preferences over the shared "APIClient" (MMCA.Common.UI/Services/Preferences/ApiUserPreferenceWriter.cs:22, :62-66) using the private UserPreferencesRequest record (:29), and IUserPreferenceReader / ApiUserPreferenceReader GET the same endpoint at login and return the immutable UserPreferences record, whose null fields mean "leave unchanged" (MMCA.Common.UI/Services/Preferences/UserPreferences.cs:9, MMCA.Common.UI/Services/Preferences/ApiUserPreferenceReader.cs:14, :21-31). The write is strictly best-effort: the cookie is the device-local runtime channel and a failed persist never breaks the in-page switch. Best-effort has a cost, though, and both sides guard it, first by refusing to send when the token is missing, unreadable or within 30 seconds of expiry via JwtTokenInfo.IsFresh (ApiUserPreferenceWriter.cs:27, :47; ApiUserPreferenceReader.cs:21, :31), and second by remembering the exact token the API last answered 401 to, so a revoked session costs one failed request rather than one per toggle (ApiUserPreferenceWriter.cs:31-37, :55-58, :68-71). Comparing the token rather than setting a latch is what lets a fresh sign-in resume writing with no reset step. That is a [Rubric §13, Observability & Operability] detail as much as a [Rubric §19, State Management] one: at low traffic, one 401 per theme toggle is enough on its own to trip a failed-request alert rule.

Pluggable UI modules. The module system that organizes the back end (IModule, chapter 14) has a front-end counterpart in IUIModule (MMCA.Common.UI/Common/Interfaces/IUIModule.cs:11). A module descriptor exposes its navigation entries as NavItem values, the Assembly holding its Razor pages so the host can add it to AdditionalAssemblies for route discovery, and two defaulted collections of component types to render in the app bar and at the root layout (IUIModule.cs:12-22). The registration prologue is shared too: AddUIModule<TModule>() runs one Scrutor scan that picks up every IEntityService<,> implementation in the module's assembly as scoped, then registers the descriptor as a singleton (MMCA.Common.UI/DependencyInjection.cs:320-329), so a module's own Add{Module}UI() no longer carries its own copy of that scan and can still register services that must win afterwards. UIModuleConfiguration lets a host switch a module off through Modules:{name}:Enabled, defaulting to enabled when the section is absent (MMCA.Common.UI/Common/Settings/UIModuleConfiguration.cs:18-22), and IHomePageContent is the per-app landing-page hook behind the shared / route, naming the component type and the page title (MMCA.Common.UI/Common/Interfaces/IHomePageContent.cs:8-15). Adding a feature module therefore wires its pages, its services and its menu entries into the shell with no edit to the shell. [Rubric §18, UI Architecture] and [Rubric §1, SOLID] (open/closed).

A complete vertical slice shipped inside the framework: notifications. Unlike the rest of the package, which is base classes consumers extend, the Notifications area is a finished feature an app switches on with one call. NotificationUIModule (MMCA.Common.UI/Notifications/NotificationUIModule.cs:15) contributes a user-facing inbox nav entry plus a push-notification entry gated on the NotificationPermissions.Manage permission rather than on a role name (:17-21, the permission facet at :20), the app-bar NotificationBell (:23) and a root-layout listener component (:25); NotificationInbox, NotificationList and NotificationSend (with its NotificationSendModel form model) render it; NotificationInboxService and PushNotificationService (behind INotificationInboxUIService and IPushNotificationUIService) call the API; and NotificationHubService (MMCA.Common.UI/Services/Notifications/NotificationHubService.cs:44) holds the SignalR connection to the API's NotificationHub. A dropped connection reconnects for as long as the service is alive: the internal UnboundedReconnectPolicy (MMCA.Common.UI/Services/Notifications/UnboundedReconnectPolicy.cs:21, wired at NotificationHubService.cs:206) walks a 0, 2, 5 and 10 second warm-up and then retries every 30 seconds, where the SignalR default gives up after about 42 seconds and leaves live notifications dead until a page reload (UnboundedReconnectPolicy.cs:6-20, :24-32, :44-46). A connection that still closes with an error is restarted under the same 30-second cap, a deliberate stop or dispose is never restarted, and a 401 or 403 handshake ends both loops, since an expired session cannot recover by retrying (NotificationHubService.cs:32-41, :280). The same connection carries ephemeral live channel events (ADR-039): components join through JoinChannelAsync (NotificationHubService.cs:319), membership is reference-counted per key by ChannelReferenceCounter (MMCA.Common.UI/Services/Notifications/ChannelReferenceCounter.cs:16) so one subscriber leaving does not cut the channel off for the others, handlers are multicast through disposable ChannelSubscription handles (NotificationHubService.cs:771), and every held channel is re-joined on Reconnected because SignalR group membership does not survive a new connection (NotificationHubService.cs:226). On a WebAssembly client whose host runs the same-origin proxy, the hub connects through it and sends the proxy's CSRF header instead of an access token (NotificationHubService.cs:100-109, :540). Which notifications a user sees can be narrowed by INotificationScopeProvider, an app-supplied scope key such as "event:2" that both HTTP services consume so a send and the reads that follow agree, defaulting to the unscoped NullNotificationScopeProvider and contractually forbidden from throwing, with the further instruction to fail closed (return the last known key) rather than degrade to null, since a null silently widens the view to every notification (MMCA.Common.UI/Services/Notifications/INotificationScopeProvider.cs:9-22). Shared unread state lives in NotificationState (MMCA.Common.UI/Services/Notifications/NotificationState.cs:18), which stamps when the count was last established so a subscriber can ask IsStale instead of re-fetching on every trigger (:7-12) and arbitrates a single active-poller slot by owner reference rather than a counter, so a teardown that never unregisters cannot strand the slot for the life of the circuit (:23-29). Both of the badge's timings are configuration rather than compiled-in constants: NotificationBellOptions (MMCA.Common.UI/Common/Settings/NotificationBellOptions.cs:12) binds a 30-second default PollInterval and a 30-second NavigationRefreshMaxAge, so a deployment paying per API call widens the poll and a page change within the window keeps the count it has (:22, :29), read by the bell through IOptions and a TimeProvider (MMCA.Common.UI/Components/Notifications/NotificationBell.razor.cs:30, :36-37). The bell also registers strictly symmetrically, because hosts render it twice inside <AuthorizeView> and a routine token refresh tears both instances down and rebuilds them (NotificationBell.razor.cs:22-29). The whole feature is wired by its own AddNotificationUI() (MMCA.Common.UI/Notifications/DependencyInjection.cs:12, :20-42), kept separate so an app that does not want real-time notifications never pays for the SignalR plumbing. A host that skips it can also set HideNotificationPagesWhenUnregistered (MMCA.Common.UI/Common/Settings/LayoutSettings.cs:49), and NotificationPageGate (MMCA.Common.UI/Notifications/NotificationPageGate.cs:12) then has the router answer the three notification pages with the not-found page whenever no NotificationUIModule is registered (:14-31). The router places the internal NotificationPageNotFoundStatus (MMCA.Common.UI/Notifications/NotificationPageNotFoundStatus.cs:11) beside that not-found page; it renders nothing and calls NavigationManager.NotFound() on initialization, so a server render answers 404 rather than 200 (:5-10, :18). The pages themselves declare the mmca:notification-pages policy instead of a bare [Authorize], because [Authorize] is endpoint metadata and the authorization middleware would challenge a signed-out visitor to sign in before the router's gate ever ran, for a page that does not exist on this host (NotificationPageRequirement, MMCA.Common.UI/Notifications/NotificationPageRequirement.cs:20, :23, rationale at :14-19). NotificationPageAuthorizationHandler (MMCA.Common.UI/Notifications/NotificationPageAuthorizationHandler.cs:14) passes an authenticated caller, and every caller while the host hides the pages, reusing the gate's own predicate so the two cannot disagree (:26-30); AddUIShared registers the policy and the handler for every host (MMCA.Common.UI/DependencyInjection.cs:78-85).

Administration screens ship as components, not pages. Identity administration is the second finished feature in the package (ADR-116), and it is delivered as components an app routes itself: UserAdminList<TUser> (MMCA.Common.UI/Pages/Administration/UserAdminList.razor.cs:47), RoleAdminList (MMCA.Common.UI/Pages/Administration/RoleAdminList.razor.cs:28) and RoleAdminEdit (MMCA.Common.UI/Pages/Administration/RoleAdminEdit.razor.cs:36) carry no @page directive, so the route, the authorization attribute and the links between them stay the app's decision (UserAdminList.razor.cs:17-22, RoleAdminList.razor.cs:12-14, RoleAdminEdit.razor.cs:13-14). The account roster is the one shipped screen that derives from the list-page base itself (MMCA.Common.UI/Pages/Administration/UserAdminList.razor:4) and it is generic over the app's own DTO, constrained only to IUserAdminDTO (UserAdminList.razor.cs:47-48). It has two data paths: by default it reads through IUserAdminUIService<TUserDto> (MMCA.Common.UI/Services/Administration/IUserAdminUIService.cs:18), whose endpoint takes a search term and a role rather than the grid's per-column filter syntax (IUserAdminUIService.cs:11-16, :27-32), while an app whose roster lives on its own filtered endpoint passes a FetchPage delegate instead and the service is never resolved for reads, with the free-text box injected under the SearchFilterKey filter key (UserAdminList.razor.cs:32-39, :50-55). The three account actions always go through IUserAdminActionsUIService (MMCA.Common.UI/Services/Administration/IUserAdminActionsUIService.cs:16), the non-generic half so a component that only acts on an account never names the DTO, and they are hidden on the signed-in operator's own row: an operator who locked or demoted themselves would lose the very capability needed to undo it, and the API has no notion of "the caller" (UserAdminList.razor.cs:40-44). SetRoleAsync is its own member rather than a default interface implementation over SetRolesAsync, because a default implementation is not virtual on the interface a mock proxies, so a test could neither stub nor verify it (IUserAdminActionsUIService.cs:40-54).

Role administration is non-generic throughout, since a role and a permission are both strings the framework already owns (IRoleAdminUIService, MMCA.Common.UI/Services/Administration/IRoleAdminUIService.cs:22, rationale at :11-15). The roster reports the permissions a role's code grants and the permissions stored rows grant as two separate counts, because only the stored half is editable and a single total would hide that removing a compiled permission is a code change (RoleAdminList.razor.cs:16-20). The editor offers only what the server's catalog declares, so nothing it can submit is a permission no endpoint checks, and it locks two kinds of checkbox: one the host compiled in for this role, and ManageRoles itself, which guards this very screen and which the server refuses to store, so offering it would be offering an action guaranteed to fail (RoleAdminEdit.razor.cs:17-29). The rest are grouped by the area before the first colon of an area:capability name through the private PermissionGroup record, with un-prefixed permissions filed under a localized "General" (RoleAdminEdit.razor.cs:37-38, :222, :301-303). Wording stays the app's: every string these three render is looked up in an app-supplied IStringLocalizer first and falls back to the framework's UserAdminListResources, RoleAdminListResources and RoleAdminEditResources markers, so "Deactivate" instead of "Lock" costs no parameter per word (UserAdminList.razor.cs:24-31, MMCA.Common.UI/Pages/Administration/RoleAdminListResources.cs:9-14). Both implementations, UserAdminService<TUserDto> (MMCA.Common.UI/Services/Administration/UserAdminService.cs:26) and RoleAdminService (MMCA.Common.UI/Services/Administration/RoleAdminService.cs:25), derive from AuthenticatedServiceBase rather than the entity-service base, because these endpoints are not CRUD over an entity resource, and they read every answer back through ProblemDetailsResultReader inside HttpResultExecutor so only the caller's own cancellation still propagates (UserAdminService.cs:15-22, RoleAdminService.cs:64-78, :89-101). [Rubric §18, UI Architecture & Component Design] again: the framework ships the screen, the app keeps the route, the vocabulary and the DTO.

How it wires up at startup. A host's Program.cs calls AddUIShared(configuration) once, a C# extension(IServiceCollection) member (see primer §4) on DependencyInjection (MMCA.Common.UI/DependencyInjection.cs:31, :39-209). In order it binds and validates on start ApiSettings, so a missing endpoint fails the host rather than the first request (:42-45; the read-only face of those options is IApiSettings, whose WasmApiEndpoint lets the server call an internal URL while the browser is handed an external one, MMCA.Common.UI/Common/Settings/IApiSettings.cs:11-17); binds LayoutSettings, LegalSettings, RegistrationSettings, UiReadCacheOptions and NotificationBellOptions without validation, deliberately optional so a host that configures none of them keeps the compiled-in defaults (:48-67); TryAdds TimeProvider.System as the clock those staleness policies are measured against and the read cache itself (:71, :76); registers the notification pages' authorization policy and its handler (:81-85); sets up localization, the pseudo/Mud localizer decorators and the MudBlazor localization interceptor (:88-110); registers the auth and culture delegating handlers and the named "APIClient" whose base address comes from ApiSettings and whose timeout is pinned to HttpResilienceDefaults.TotalRequestTimeout rather than the BCL's arbitrary 100s, so the transport never pre-empts the resilience budget (:118-147; when Api:SameOriginApiEndpoint is configured the base address is that proxy endpoint and SameOriginProxyRequestHandler joins as the innermost handler, :120-121, :136, :149-154); calls AddCommonUiFacades() for the toast and dialog pair (:159); then TryAdds AuthUIService, the email-confirmation client (:166), the terms-acceptance client (:170), the OAuthFlowStateStore (:174), the two list-page state services, NavigationHistoryService, ThemeService, EndpointCultureApplier, ViewerTimeZone (:190), NavigationPublicLinkBuilder behind IPublicLinkBuilder (share-sheet and QR links resolved against the browser origin, which a MAUI head replaces because its WebView origin is a virtual host nobody else can open, MMCA.Common.UI/Services/Navigation/IPublicLinkBuilder.cs:9, MMCA.Common.UI/Services/Navigation/NavigationPublicLinkBuilder.cs:11), the preference reader and writer, and a default IOAuthUISettings (DefaultOAuthUISettings) that downstream apps override with ConfigurationOAuthUISettings, which reads provider availability from the OAuth section for a server host and from pre-computed Enabled flags for a WASM client (:161-204, MMCA.Common.UI/Services/Auth/OAuth/ConfigurationOAuthUISettings.cs:13, :24-30); and finally calls AddDeviceCapabilityDefaults() so every capability contract resolves on every head (:208, ADR-042, chapter 26). The TryAdd* discipline is what lets a consumer pre-register its own implementation and win. Browser hosts add AddClientAuthSessionCookieSync() (:240-242) and AddWasmFormFactor() (:252); a Blazor Server head adds AddCommonServerTokenStorage(), AddCommonBlazorCsp() (before AddCommonSecurityHeaders, so it beats the TryAdded static provider) and AddCommonWebFormFactor() from MMCA.Common.UI.Web (MMCA.Common.UI.Web/DependencyInjection.cs:41, :67, :85; the first also registers BrowserOriginHandler, :47-48) plus the UseAuthenticatedNoStore() middleware. The administration screens are opt-in on the same pattern: AddUserAdministrationUI<TUserDto>() registers the generic service and forwards the non-generic actions contract to that same instance, so the roster and the actions it performs go through one object and one substitute in a test (MMCA.Common.UI/DependencyInjection.cs:269-276), and AddRoleAdministrationUI() registers the role client (:295-297); nothing in the framework calls either, so an app serving no administration endpoints registers nothing and the components are simply never rendered. An SSR host behind the gateway also calls AddTrustedCallerHeader(configuration), which composes TrustedCallerHandler (MMCA.Common.UI.Web/Security/TrustedCallerHandler.cs:35) onto every HttpClient the host creates, inserted at index 0 so the origin gate judges the authority the caller wrote rather than one Aspire's service-discovery handler has already rewritten (MMCA.Common.UI.Web/DependencyInjection.cs:121, :143-156), and registers nothing at all when no secret, header name or parseable gateway origin is configured (the early return at :137). The breadth is the point: the call that suffers most from the gateway's per-IP limiter partition, the cookie-session token refresh, is created by the framework under a name a host cannot reach, while the handler itself stays narrow, stamping the secret only on a request whose scheme, host and port match the gateway origin and replacing rather than appending the header, because the gateway compares one single-valued header in constant time (TrustedCallerHandler.cs:9-27, :67-79). UISharedAssemblyReference (MMCA.Common.UI/DependencyInjection.cs:335) is the marker other assemblies scan against.

How a WebAssembly client learns its API address. The WASM bundle is static, so the API base address is fetched at runtime rather than baked in. On the server side, ClientConfigEndpointExtensions (MMCA.Common.UI.Web/ClientConfig/ClientConfigEndpointExtensions.cs:17) adds MapClientConfigEndpoint, an anonymous GET /client-config excluded from the OpenAPI description whose framework-owned Api section carries Api:WasmApiEndpoint (:17, :52-81). It fails closed: with that key missing it throws rather than fall back to Api:ApiEndpoint, which is the server head's service-discovery name a browser cannot resolve, so the client fails to start instead of pointing at the wrong API (:32-38, :53-59). When the host runs the same-origin proxy, the same api section also carries sameOriginApiEndpoint, the proxy prefix with a trailing slash, which is what moves the client's "APIClient" onto it (:84-99). The endpoint declares AllowAnonymous itself, because the client fetches the document before it can hold a session and a host's fallback policy would otherwise gate it (:40-44, :80). A host adds its own sections through a per-request ClientConfigBuilder (MMCA.Common.UI.Web/ClientConfig/ClientConfigBuilder.cs:17), whose Add refuses a blank name, the reserved Api section and a duplicate, and whose remarks warn that everything added is served to every browser before sign-in, so only public values belong there (:12-16, :45-62). The client half is MmcaClientConfigBootstrap (MMCA.Common.UI/Common/Settings/MmcaClientConfigBootstrap.cs:28), whose LoadAsync fetches the document from the app's own origin with a 15-second per-attempt timeout and a single retry after one second (for the cold-start case where the Server host is still warming), then rethrows a second failure on purpose, and returns a buffered stream because browser fetch streams do not support the synchronous reads AddJsonStream performs (:12-22, :30, :33, :44-85). Only the timeout it did not ask for is retried, never the caller's own cancellation (:87-90). ADC wires both halves (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:265, MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web.Client/Program.cs:31).

The small Level-0 supporting cast fills in the rest: NotificationRoutePaths (MMCA.Common.UI/Common/NotificationRoutePaths.cs:8), whose deep-link builder formats invariantly because the route's :int constraint is the validation boundary (:14-20); QrErrorCorrectionLevel, the framework's own enum for QrCodeImage so the component's public API does not pin consumers to QRCoder's ECCLevel (MMCA.Common.UI/Components/Sharing/QrErrorCorrectionLevel.cs:9); RatingStars (MMCA.Common.UI/Components/Ratings/RatingStars.razor.cs:13), five read-only stars out of a MaxValue of 5 rendered as one role="img" element whose required AriaLabel carries the numeric figure, so the stars stay decorative rounding (whole stars fill, a half star shows at .5 and above, :6-11, :16, :31-33, :46-54), which the ADC feedback and speaker dashboards render (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.UI/Pages/Feedback/OrganizerSessionFeedback.razor:67); ApiFileDownloadButton (MMCA.Common.UI/Components/Forms/ApiFileDownloadButton.razor.cs:14), which gives browsers a plain download link and native heads a fetch-stage-share flow, stripping directory segments from the supplied file name so a value built from entity data cannot steer the write out of the temp directory (:21-30); and MauiBackNavigationBridge with its BackNavigationResult for MAUI hardware-back handling, which reports both whether history.back() fired and whether the WebView is at the root of its stack so a host can decide to exit (MMCA.Common.UI/Services/Navigation/MauiBackNavigationBridge.cs:19, :28). Form-factor detection has graduated into its own device-capability layer (IFormFactor and friends, chapter 26). The presentational helper MoneyExtensions formats Money for display, grouping a mixed collection by currency so unrelated amounts never collapse under whichever symbol came first (MMCA.Common.UI/Extensions/MoneyExtensions.cs:14, the single-price form at :29-30 and the collection form at :33), keeping a display concern out of the domain value object, exactly where Clean Architecture wants it.

Read the per-type sections that follow for the mechanics. The consumer-side module UIs live in the ADC module-UI chapter (chapter 21), and the bUnit component tests plus the Playwright/axe-core E2E suite that exercise this package are covered in the testing chapter (chapter 27), which is where [Rubric §28, Front-End Testing] lives.

BreakpointConstants

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/BreakpointConstants.cs:9 · Level 0 · class (static)

• What it is: a one-method static helper that answers "is this viewport a mobile viewport?", so C# viewport detection and the CSS media-query boundary agree on one number.
• Depends on: MudBlazor.Breakpoint (NuGet, imported at BreakpointConstants.cs:1). Nothing first-party.
• Concept introduced, the single authoritative breakpoint. [Rubric §22, Responsive & Cross-Browser] assesses whether a codebase has one definition of "small screen" rather than a magic number re-chosen per component; this class embodies it by making the mobile/desktop split a named predicate. The doc comment (BreakpointConstants.cs:11-15) pins the threshold as "below the sidebar-collapse threshold (MudBlazor Xs or Sm, i.e. < 960 px)", which is the same boundary the shared stylesheet collapses the sidebar at. [Rubric §20, Design System & Theming] applies for the same reason: one threshold keeps the layout, the nav drawer and the list pages switching modes together instead of at three slightly different widths.
• Walkthrough: the type has exactly one member. IsMobileBreakpoint(Breakpoint breakpoint) (BreakpointConstants.cs:16-17) is expression-bodied and returns breakpoint is Breakpoint.Xs or Breakpoint.Sm. That pattern is the whole rule: Md and wider is desktop, and there is no third state.
• Why it's built this way: static and dependency-free, so a component can call it without injecting anything, and moving the mobile threshold is a one-line edit paired with one CSS rule rather than a hunt through component code.
• Where it's used: exactly one production call site, DataGridListPageBase<TDto>'s viewport-change handler NotifyBrowserViewportChangeAsync (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Common/DataGridListPageBase.cs:317), which sets IsMobile from it at line 308 and, on a desktop-to-mobile transition, resets MobileCurrentPage to 1 and re-requests the mobile data (DataGridListPageBase.cs:324-328). That single assignment is what swaps a desktop MudDataGrid for the MobileInfiniteScrollList<TItem> card layout on every list page in both consumer apps.

IAppDialogService

MMCA.Common.UI · MMCA.Common.UI.Common.Interfaces · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Interfaces/IAppDialogService.cs:14 · Level 0 · interface

• What it is: the framework's modal-confirmation contract, one method that asks a yes/no question and resolves once the user answers. It exists so page code never names the component library that draws the dialog.
• Depends on: nothing first-party (the file carries no using directives at all). Implemented by MudAppDialogService over MudBlazor's IDialogService.
• Concept introduced, the vendor-neutral UI facade. [Rubric §32, Dependency & Supply-Chain] assesses whether a third-party dependency is contained behind your own contract or spread across call sites; [Rubric §14, Testability] assesses whether a unit of behavior can be exercised without its infrastructure; [Rubric §1, SOLID] covers the dependency-inversion half of the same idea. The framework applies all three the same way twice: this interface and its sibling IToastService are the only shapes pages depend on, and their two implementations are the only types in the framework that name MudBlazor's IDialogService / ISnackbar (MudAppDialogService at MMCA.Common/Source/Presentation/MMCA.Common.UI/Services/MudAppDialogService.cs:11, doc comment at :6-10). The payoff is concrete: a bUnit test answers a confirmation prompt with a stub instead of rendering, driving and dismissing a real dialog. The doc comment (IAppDialogService.cs:3-13) also states the deliberate scope limit: only the yes/no shape is abstracted, and richer entity-specific dialogs (DeleteConfirmation) stay component-side rather than growing this contract.
• Walkthrough: one member. ConfirmAsync(string title, string message, string confirmText, string cancelText) returns Task<bool> (IAppDialogService.cs:26). Two contract details are stated in the XML doc and honored by the implementation. First, every string parameter is documented as "already-localized" (:21-24): the facade never touches IStringLocalizer, the caller resolves its own copy, which is what keeps the resource key next to the page that owns it (ADR-027). Second, dismissing the dialog without choosing counts as declining (:17-19), so a caller only ever has to branch on true. MudAppDialogService implements exactly that by collapsing MudBlazor's tri-state answer with return confirmed is true; (MudAppDialogService.cs:25), because ShowMessageBoxAsync answers null for a backdrop click or an escape key press (MudAppDialogService.cs:16-18).
• Why it's built this way: a four-string method with a bool answer is the smallest contract that covers every destructive-action prompt in the framework, and keeping it that small is what makes the vendor genuinely swappable: the whole surface an alternative renderer must satisfy is one method. It is registered by AddCommonUiFacades() alongside the toast facade (DependencyInjection, MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:231), scoped to match the MudBlazor services it wraps. See ADR-067, whose 2026-08-29 revision records the vendor choice and these two facades, and whose 2026-08-31 revision records their move into their own registration call.
• Where it's used: injected by the shared framework surfaces that ask before doing something lossy: DataGridListPageBase<TDto>, the notification list, send and inbox pages, ListPageActions, the signed-in-devices page (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/Sessions.razor.cs), and the UnsavedChangesGuard component. Registered for component tests by the shipped bUnit base's Services.AddCommonUiFacades() call (MMCA.Common/Source/Hosting/MMCA.Common.Testing.UI/Infrastructure/BunitComponentTestBase.cs:54), which uses TryAdd semantics so a test that wants a recording double registers one afterwards (BunitComponentTestBase.cs:51-53).

IHomePageContent

MMCA.Common.UI · MMCA.Common.UI.Common.Interfaces · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Interfaces/IHomePageContent.cs:8 · Level 0 · interface

• What it is: the hook that lets each consuming application supply its own landing page at the / route without forking the shared routing or layout.
• Depends on: System.Type (BCL) and, at the consuming end, Microsoft.AspNetCore.Components.DynamicComponent, which the doc comment names as the rendering mechanism (IHomePageContent.cs:3-7).
• Concept introduced, late-bound content injection into a packaged shell. [Rubric §18, UI Architecture & Component Design] assesses whether shared UI infrastructure adapts to per-app content without duplication. The shared package owns the route: Home.razor declares @page "/" once (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Home.razor:1), injects IEnumerable<IHomePageContent> (Home.razor:3), and renders <DynamicComponent Type="_contentType" /> when a provider resolved (Home.razor:8-11). Because the component arrives as a runtime Type rather than a compile-time reference, the framework package renders an app's landing page without referencing the app. When no implementation is registered the page falls back to a localized welcome panel (Home.razor:12-21), so a brand-new host still renders something coherent.
• Walkthrough: two read-only members. ComponentType (IHomePageContent.cs:11) is the System.Type of the Razor component to render as the home-page body. PageTitle (IHomePageContent.cs:14) is the browser-tab title, bound by Home.razor:6.
• Why it's built this way: an inverted dependency (the app registers into the framework, never the reverse) is what lets the whole shell ship as a NuGet package. Compare the sibling mechanism in IUIModule: both hand the framework a Type or an Assembly and let reflection do the binding, and both exist for the same reason (ADR-067).
• Where it's used: implemented once per app and registered once per head. ADC registers ADCHomePageContent as a singleton in all three heads (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:97, MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web.Client/Program.cs:45, MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI/MauiProgram.cs:126), with two separate implementations, one for the web heads (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web.Client/Pages/ADCHomePageContent.cs:11) and one for MAUI (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI/Pages/ADCHomePageContent.cs:8). Store does the same with StoreHomePageContent (MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:101, MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web.Client/Program.cs:41, MMCA.Store/Source/Hosts/UI/MMCA.Store.UI/MauiProgram.cs:76).
• Caveats / not-in-source: the injection point is IEnumerable<IHomePageContent>, so several registrations do not fail; which one wins is decided by Home.razor's selection code (Home.razor:23 onward), not by this interface. Every current host registers exactly one.

ComponentLifetimeExtensions

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/ComponentLifetimeExtensions.cs:18 · Level 0 · class (static, extension methods)

• What it is: one extension method, LifetimeToken(this CancellationTokenSource?), that gives a component a cancellation token it can read at any point of its lifetime without risking an exception.
• Depends on: System.Threading.CancellationTokenSource, CancellationToken and ObjectDisposedException (BCL). Nothing first-party.
• Concept introduced, the always-safe lifetime token. [Rubric §15, Best Practices & Code Quality] assesses whether a recurring hazard has one shared answer. Reading CancellationTokenSource.Token after Dispose() throws ObjectDisposedException, and a Blazor component's async continuation can easily run after the component is gone. The extension converts that failure mode into the correct behavior: a component that has ended gets a token that is already cancelled, so the in-flight call stops instead of throwing out of a dead render tree.
• Walkthrough: LifetimeToken (ComponentLifetimeExtensions.cs:26-42) has three outcomes. A null source, or one whose IsCancellationRequested is already true, returns new CancellationToken(canceled: true) (:28-31). Otherwise it returns source.Token (:35) inside a try; an ObjectDisposedException (a source disposed without being cancelled first) is caught and also returns a cancelled token (:37-41), with the comment that the component is gone all the same.
• Why it's built this way: an extension on the nullable source, rather than a wrapper type, so a component keeps its familiar _cts field and writes _cts.LifetimeToken() where it used to write _cts.Token. null is treated as ended (:28), which covers a component whose source was never created.
• Where it's used: LatestLoadGuard reads its token through it (MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/LatestLoadGuard.cs:58), and the ResultUiExtensions examples show _cts.LifetimeToken() as the call-site shape (MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/ResultUiExtensions.cs:47, :63). The convention is enforced by ArchitectureRules.ComponentsReadTheirTokenThroughLifetimeToken (MMCA.Common/Source/Hosting/MMCA.Common.Testing.Architecture/Rules/Ui/ArchitectureRules.LifetimeTokens.cs:28), which fails the build on a direct _cts.Token read, wrapped for subclassing by LifetimeTokenConventionTestsBase (MMCA.Common/Source/Hosting/MMCA.Common.Testing.Architecture/Bases/Ui/LifetimeTokenConventionTestsBase.cs:13). It is on the shipped public surface (MMCA.Common/Source/Presentation/MMCA.Common.UI/PublicAPI.Shipped.txt:1391).

LatestLoadGuard

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/LatestLoadGuard.cs:38 · Level 0 · class (sealed, IDisposable)

• What it is: a small per-page helper that keeps a routed component showing the load it asked for last, by giving every load a generation number and a cancellation token and cancelling the previous one as the next begins.
• Depends on: System.Threading.CancellationTokenSource and ObjectDisposedException.ThrowIf (BCL), and ComponentLifetimeExtensions for the token it hands out.
• Concept introduced, generation-guarded supersession. [Rubric §19, State Management & Data Flow] assesses the correctness of in-flight asynchronous state, and this is the canonical bug it looks for. The doc comment states it precisely (LatestLoadGuard.cs:5-10): Blazor reuses a routed component instance across route-parameter changes, so a page that opens entity 100 (slow response) and then navigates to entity 101 (fast response) receives 100's late answer after 101 has already rendered. Assigning it unconditionally leaves the URL on 101 while the page holds 100, and any action bound to the loaded entity then fires against the wrong record. Cancellation alone does not fix this, because a fetch that ignores its token still completes; the integer generation is the authoritative check. The same pattern appears at component scope inside MobileInfiniteScrollList<TItem>, which snapshots a generation before awaiting and drops the result if the world moved; LatestLoadGuard is that idea extracted into a reusable object so a detail page gets it in three lines. [Rubric §15, Best Practices & Code Quality] applies: the alternative is every page hand-rolling a token source, a counter and a dispose path.
• Walkthrough: three private fields (LatestLoadGuard.cs:40-42): the current CancellationTokenSource?, the int _generation, and a _disposed flag.
  • Begin() (:50-59) is the entry point. It throws if the guard is disposed (:52), cancels and disposes the previous load through the private CancelAndDisposeCurrent() (:54), publishes a fresh token source (:55), increments the generation (:56), and returns the pair (CancellationToken Token, int Generation) (:58), with the token read as _cts.LifetimeToken() rather than _cts.Token (:58) so it is the always-safe token of ComponentLifetimeExtensions. Returning a tuple rather than exposing two properties is what makes the generation a snapshot: the caller holds the value it started with, so a later Begin() cannot retroactively change what it compares against.
  • IsCurrent(int generation) (:67) is the check after the await: !_disposed && generation == _generation. Disposal counts as not-current, so a component torn down mid-fetch also drops its answer instead of assigning into a dead render tree.
  • Dispose() (:70-79) is idempotent via the _disposed early return (:72-75) and cancels the in-flight load on the way out.
  • CancelAndDisposeCurrent() (:81-91) null-guards, then cancels, disposes and nulls the source, so the guard never double-disposes a token source and never leaks one.
  • The usage shape is spelled out as a <code> block in the doc comment (:15-31): a private readonly LatestLoadGuard _load = new(); field, var (token, generation) = _load.Begin(); at the top of OnParametersSetAsync, an if (!_load.IsCurrent(generation)) { return; } immediately after the await, and public void Dispose() => _load.Dispose();.
• Why it's built this way: deliberately not thread-safe, and the doc comment says so in bold (:32-36). It is built for the renderer's synchronization context, where component lifecycle methods and event callbacks are already serialized, so the fields need no interlocking and the type stays allocation-cheap. That is a contract, not an oversight: sharing one instance across threads is documented as unsupported.
• Where it's used: the framework's DetailPageBase exposes one as protected LatestLoadGuard LoadGuard { get; } = new(); and disposes it (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Common/DetailPageBase.cs:43, :95), so every detail page derived from it inherits the guard. RoleAdminEdit holds its own _load and runs the Begin() / IsCurrent(generation) shape directly (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/RoleAdminEdit.razor.cs:42, :162, :174, :187), and ADC's public event, session and speaker detail pages and SessionCreate also call it (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.UI/Pages/Public/Events/PublicEventDetail.razor.cs, Pages/Public/Sessions/PublicSessionDetail.razor.cs, Pages/Public/Speakers/PublicSpeakerDetail.razor.cs, Pages/Sessions/SessionCreate.razor.cs). It is on the shipped public surface (MMCA.Common/Source/Presentation/MMCA.Common.UI/PublicAPI.Shipped.txt:37-41). It is also exercised by LatestLoadGuardTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Common/LatestLoadGuardTests.cs:11, six test methods covering Begin cancelling the prior token, generation advance, IsCurrent after supersession, and behavior after disposal) [Rubric §28, Front-End Testing]; DetailPageBaseTests covers the base-class wiring (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Common/DetailPageBaseTests.cs).
• Caveats / not-in-source: the guard is not thread-safe by contract, and a page that bypasses it (assigning a fetch result unconditionally) is not caught by any analyzer; adoption is by DetailPageBase inheritance or by hand, as RoleAdminEdit does.

NavSection

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/NavSection.cs:7 · Level 0 · enum

• What it is: classifies a sidebar entry into one of three audience groups: everyone, signed-in users, or administrators.
• Depends on: nothing. Consumed by NavItem and by the shared nav menu.
• Concept introduced, audience as a first-class navigation axis. [Rubric §25, Navigation & Information Architecture] assesses whether the menu structure is declarative and audience-aware rather than a hand-maintained pile of conditionals. [Rubric §11, Security] touches it too, but with an important distinction worth internalizing early: the section is a grouping hint, not an authorization check. What actually hides a link is RequiredRole / RequiredClaim on NavItem, evaluated by the menu (MMCA.Common/Source/Presentation/MMCA.Common.UI/Layout/NavMenu.razor:198-199), and what actually protects the destination is page-level and API-level authorization.
• Walkthrough: three values in declaration order, and the order is itself a contract because the doc comment states sections render in enum declaration order (NavSection.cs:5). General (:10) is for items visible to everyone, anonymous and authenticated alike. User (:13) is for signed-in non-admin items. Admin (:16) is for administrator items.
• Why it's built this way: an enum rather than a string gives the renderer exhaustive, typo-proof matching, which is exactly what NavMenu.razor relies on when it partitions the flattened item list into three collections with i.Section is NavSection.General / User / Admin (NavMenu.razor:202-204). It is a plain C# enum rather than a smart enumeration because no member needs to carry data or behavior, which is the default this codebase commits to (ADR-104).
• Where it's used: the Section parameter of NavItem (NavItem.cs:16, defaulting to General), and the three-way partition at NavMenu.razor:202-204. NotificationUIModule shows both non-default values in one file: its inbox item is Section: NavSection.User (MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationUIModule.cs:19) and its push-management item is Section: NavSection.Admin (:20).

RoutePaths

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/RoutePaths.cs:7 · Level 0 · class (static)

• What it is: the route-path constants owned by the shared UI package itself. Module-specific routes live in their own *RoutePaths classes.
• Depends on: nothing.
• Concept introduced, one source of truth for route strings. [Rubric §25, Navigation & Information Architecture] also covers URL hygiene: a literal "/profile/sessions" typed into four components is four places to get a rename wrong. The class comment (RoutePaths.cs:3-6) states both halves of the convention: centralized paths shared across all UI modules and hosts live here, and module-specific paths live in their own class. That convention is followed consistently across the workspace, by NotificationRoutePaths in this package and by ConferenceRoutePaths, EngagementRoutePaths and IdentityRoutePaths in the consumer modules.
• Walkthrough: two public static readonly string members.
  • Home = "/" (RoutePaths.cs:9).
  • Sessions = "/profile/sessions" (:16), the signed-in-devices page. Its doc comment (:11-15) records why it belongs to the framework rather than to an app: the page is framework-owned (MMCA.Common.UI.Pages.Auth.Sessions), lists the user's live refresh sessions with per-device and account-wide sign-out, and is reachable from the shared nav menu's authenticated section, so a consuming app gets it without doing any routing work.
• Why it's built this way: static readonly rather than const is sufficient because these strings are consumed in navigation and Href expressions, not in attribute arguments. That has one consequence worth knowing: a @page directive still needs its own literal, so Home.razor:1 writes @page "/" directly and this constant covers only the linking and navigating side. Sessions shows the cost of the convention: the route literal appears in the page's own @page directive and again here, and only the tests hold the two together.
• Where it's used: RoutePaths.Home backs the navbar brand link (MMCA.Common/Source/Presentation/MMCA.Common.UI/Layout/NavMenu.razor:18), the Home nav link (NavMenu.razor:58), and the first breadcrumb of the sessions page (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/Sessions.razor.cs:68). RoutePaths.Sessions backs the authenticated-section nav link (NavMenu.razor:142) and is asserted by name in both repos' component tests: MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Layout/NavMenuTests.cs:76 pins that the link renders inside .nav-auth-section, :75 pins its position, :88 pins that it is absent for an anonymous user, and MMCA.Store/Tests/Modules/Identity/MMCA.Store.Identity.UI.Tests/Pages/Users/Profile/ProfileTests.cs:67 pins that the profile page links to it.
• Caveats / not-in-source: Sessions is still listed in PublicAPI.Unshipped.txt (MMCA.Common/Source/Presentation/MMCA.Common.UI/PublicAPI.Unshipped.txt:339) while Home is baselined in PublicAPI.Shipped.txt:916, so the two members sit at different points in the public-API baseline cycle.

ToastSeverity

MMCA.Common.UI · MMCA.Common.UI.Common.Interfaces · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Interfaces/IToastService.cs:8 · Level 0 · enum

• What it is: the framework's own five-level scale for how prominent a toast is, and therefore which color and icon the host renders it with.
• Depends on: nothing. Declared above IToastService in the same file.
• Concept reinforced, keeping the vendor enum out of call sites. The facade idea is taught at IAppDialogService; this enum is the part of it that is easy to skip. A contract that abstracts the snackbar but takes MudBlazor.Severity as a parameter has not abstracted anything, because every caller still references the vendor assembly. The doc comment says exactly that (IToastService.cs:3-7): the five levels mirror what every component library exposes, so a host maps them one-to-one without losing anything, and "naming them here is what keeps the vendor's own severity enum out of page code". [Rubric §32, Dependency & Supply-Chain] and [Rubric §9, API & Contract Design] both apply: the mapping to MudBlazor.Severity lives in one private method inside MudToastService, so swapping renderers is a change to one switch.
• Walkthrough: five explicitly numbered members, each documented by what it means for the user rather than by color. Normal = 0 (IToastService.cs:11), neutral with no color emphasis. Info = 1 (:14), something happened that the user did not ask for. Success = 2 (:17), the action the user asked for completed. Warning = 3 (:20), completed partially or with something worth knowing. Error = 4 (:23), the action failed. The explicit values keep the enum stable if members are ever reordered.
• Why it's built this way: five levels rather than four, because Normal (an uncolored toast) is a distinct affordance from Info, and not more, because there is no shape beyond these that the framework raises. Info is the default parameter value on both ShowPersistent and ShowAction (:72, :100), which is the neutral choice for an unprompted message.
• Where it's used: the severity parameter of IToastService.Show, ShowPersistent and ShowAction; the severity parameter of ResultUiExtensions.NotifyOnFailure, where it defaults to ToastSeverity.Error (MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/ResultUiExtensions.cs:293); and MudToastService, the one type that maps it to MudBlazor.Severity (MMCA.Common/Source/Presentation/MMCA.Common.UI/Services/MudToastService.cs:27).

UISharedAssemblyReference

MMCA.Common.UI · MMCA.Common.UI · MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:335 · Level 0 · class

• What it is: an empty marker class whose only job is to give code a compile-checked typeof(...).Assembly handle on the shared UI assembly.
• Depends on: nothing.
• Concept introduced, the assembly-marker type. Reflection over an assembly needs an Assembly instance, and there are two ways to get one: a string (Assembly.Load("MMCA.Common.UI"), which fails at run time when someone renames the project) or a type reference (typeof(UISharedAssemblyReference).Assembly, which fails at compile time and is carried along by a rename refactoring). Every layer of the framework ships an equivalent marker; this is the UI layer's. [Rubric §15, Best Practices & Code Quality] assesses exactly this kind of refactor-safety over stringly-typed lookups.
• Walkthrough: a single declaration using the semicolon type body, public class UISharedAssemblyReference; (DependencyInjection.cs:335), with its doc comment on line 217. It shares a file with DependencyInjection but is declared at namespace scope beneath it, outside that static class, because a type nested inside a static class could not serve as a public marker the same way. It carries no members, so nothing can accidentally depend on state it does not have.
• Why it's built this way: type-only, public and empty is the whole point. It is the assembly's identity expressed as a symbol the compiler tracks.
• Where it's used: the architecture fitness suite is the real consumer. CommonArchitectureMap registers the assembly as the framework's UI layer with Framework(Layer.Ui, typeof(Common.UI.UISharedAssemblyReference).Assembly) (MMCA.Common/Tests/Architecture/MMCA.Common.Architecture.Tests/CommonArchitectureMap.cs:27), which is what lets the shared layer-dependency rules know which assembly is the UI layer; AnonymousEndpointTests includes it in the assemblies it scans (MMCA.Common/Tests/Architecture/MMCA.Common.Architecture.Tests/Api/AnonymousEndpointTests.cs:19); and NavigationContractTests enumerates its types with typeof(UI.UISharedAssemblyReference).Assembly.GetTypes() (MMCA.Common/Tests/Architecture/MMCA.Common.Architecture.Tests/Ui/NavigationContractTests.cs:105). [Rubric §34, Architecture Governance & Documentation] applies: this one-line type is what makes a layer boundary machine-checkable.
• Caveats / not-in-source: the doc comment (DependencyInjection.cs:334) offers "e.g., for Scrutor scanning" as the motivating case, but no Scrutor registration in this repo takes its scan root from this marker. AddUIModule<TModule>() scans FromAssemblyOf<TModule>() (DependencyInjection.cs:324), taking the root from the module descriptor's own assembly instead. Trust the call sites: the current consumers are the architecture tests.

IToastService

MMCA.Common.UI · MMCA.Common.UI.Common.Interfaces · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Interfaces/IToastService.cs:37 · Level 1 · interface

• What it is: the framework's contract for transient user notifications ("toasts"), covering four named severities, a runtime-chosen severity, a persistent two-line notification, and a toast that carries a clickable action.
• Depends on: ToastSeverity (same file). Implemented by MudToastService over MudBlazor's ISnackbar.
• Concept introduced, fire-and-forget by design. The facade rationale is taught at IAppDialogService; what is specific here is that every method returns void. The doc comment explains why (IToastService.cs:31-35): during server-side prerender there is no toast host at all, so the call is a silent no-op, and a contract that reported whether the message rendered would force every call site to handle a condition it can do nothing about. [Rubric §24, Forms, Validation & UX Safety] assesses whether outcomes surface to the user in a recoverable way; [Rubric §27, Internationalization] applies because every parameter is documented as already localized, which pushes resource resolution out to the page that owns the key. That last rule is enforced, not merely documented: an architecture fitness regex fails the build on a literal first argument to any toast method (Toast\.(?:Success|Info|Warning|Error|Show|ShowPersistent|ShowAction)\(\s*\$?", at MMCA.Common/Source/Hosting/MMCA.Common.Testing.Architecture/Rules/Ui/ArchitectureRules.LocalizedText.cs:14, with the comment at :12-13 recording that it is the same guard that previously watched direct ISnackbar use at :9).
• Walkthrough: seven members, in three tiers.
  • The four named severities, Success (IToastService.cs:41), Info (:45), Warning (:49) and Error (:53), each taking one already-localized message. MudToastService implements each as a one-line snackbar.Add(message, Severity.X) (MudToastService.cs:15-24).
  • Show(string message, ToastSeverity severity) (:62) is the same thing with the level as a parameter, and the doc comment names its motivating caller: ResultUiExtensions.NotifyOnFailure, which carries the severity through as an argument rather than picking one of the four (:55-58).
  • ShowPersistent(string title, string body, ToastSeverity severity = ToastSeverity.Info) (:72) is the push-notification shape: an emphasized title above a body, staying on screen until dismissed. The reasoning (:64-67) is that a message arriving unprompted must not expire before the user has looked at the screen. MudToastService builds it as a render fragment, a <strong> title, a <br>, then the body (MudToastService.cs:41-51).
  • ShowAction(string message, string actionText, Func<Task> onAction, ToastSeverity severity = ToastSeverity.Info, bool requireInteraction = false) (:96-101) is the undo / view-it / retry shape a bare message cannot express. Two contract details are documented rather than enforced. First, the callback runs outside any render callback, so nothing catches what it throws: a caller whose work can fail must guard it and raise its own failure toast (:78-81, restated at :86-88). Second, requireInteraction: true pins the toast open until the user dismisses it or takes the action, and the MudBlazor implementation additionally renders it filled, following the same emphasis convention ShowPersistent uses, "because a toast that waits for the user has to look like it is waiting" (:90-95).
• Why it's built this way: a small, void-returning, already-localized contract is what allows the vendor to appear in exactly one class. It is registered scoped by AddCommonUiFacades() (DependencyInjection, MMCA.Common.UI/DependencyInjection.cs:230) to match the lifetime of the MudBlazor ISnackbar it wraps. See ADR-067.
• Where it's used: essentially everywhere a page reports an outcome. Inside the framework package: DataGridListPageBase<TDto>, MobileInfiniteScrollList<TItem>, ListPageActions, the three notification pages, the sessions page, and the UnsavedChangesGuard, SharePageButton, ApiFileDownloadButton and NotificationListener components. Outside it, every consumer page reaches it indirectly through ResultUiExtensions.NotifyOnFailure. Component tests resolve it from the shipped bUnit base (BunitComponentTestBase.cs:54, whose comment at :50-51 records that without it a consumer's component test fails to resolve IToastService and each repo ends up re-registering the same pair).

NavItem

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/NavItem.cs:20 · Level 1 · record

• What it is: the immutable description of one sidebar entry a UI module contributes: title, href, icon, the resource type its title resolves against, optional role, claim and permission gates, its NavSection, and an optional collapsible group.
• Depends on: NavSection; System.Type (BCL).
• Concept introduced, navigation as data contributed by modules. [Rubric §25, Navigation & Information Architecture] assesses modular, role-aware navigation. The shared menu never knows which modules exist: it injects IEnumerable<IUIModule>, flattens every module's NavItems, filters, partitions and renders (MMCA.Common/Source/Presentation/MMCA.Common.UI/Layout/NavMenu.razor:219-228). That mirrors the server-side IModule contract one layer up (ADR-059 for the server, ADR-067 for this one). [Rubric §27, Internationalization] applies through TitleResource (ADR-027). [Rubric §11, Security] and ADR-020 apply through RequiredPermission.
• Walkthrough: a positional record declared on one line (NavItem.cs:20) with nine parameters, five of them optional:
  • Title, Href, Icon: required, positional.
  • Type TitleResource: required, and the fourth positional parameter. This is the localization contract, and the doc comment states it precisely (NavItem.cs:13-18): Title and Group are resource keys, resolved against TitleResource at render time, per-circuit, so the menu follows the active culture. A key the resource type does not declare renders as the raw string, which is what makes a not-yet-translated entry legible instead of blank. NavMenu.razor implements exactly that, calling LocalizerFactory.Create(item.TitleResource)[item.Title] for an item (NavMenu.razor:166-170) and LocalizerFactory.Create(group.First().TitleResource)[group.Key] for a group heading (NavMenu.razor:172-180), with the ADR-027 rule restated in a code comment at :163-165.
  • string? RequiredRole = null and string? RequiredClaim = null: render gates. The menu applies them as item.RequiredRole is null || _user?.IsInRole(item.RequiredRole) == true and the equivalent claim-type test (NavMenu.razor:221-222).
  • string? RequiredPermission = null: a third, permission-based render gate, layered on top of role and claim. The menu applies it as item.RequiredPermission is null || _user.HasPermissionClaim(item.RequiredPermission) (NavMenu.razor:223), the same permission-claim mechanism ADR-020 uses on the write side, so a nav entry can be hidden by permission instead of only by role.
  • NavSection Section = NavSection.General: which sidebar group the item lands in (NavMenu.razor:226-228).
  • string? Group = null: nests the item inside a collapsible MudNavGroup; the menu groups by it with GroupBy(i => i.Group) in each of the three sections (NavMenu.razor:60, :83, :110).
• Why it's built this way: a positional record gives value semantics and a one-line construction per entry, which is what makes a module's NavItems read as a small declarative list. Making TitleResource a required positional parameter rather than an optional nullable one is the load-bearing design choice: there is no way to register a nav item that bypasses localization, so "all visible text follows the selected language" holds for the menu by construction rather than by review. ADR-067 records the shape at this exact line (NavItem.cs:20). RequiredPermission was added as a third, independent gate rather than folded into RequiredClaim, so a caller can express "hide by permission" without hand-building the permission claim type/value pair itself.
• Where it's used: returned from the NavItems property of every IUIModule implementation and rendered by NavMenu.razor. NotificationUIModule is the framework's own example and shows both the minimal and the maximal form: new("Nav.NotificationInbox", NotificationRoutePaths.NotificationInbox, Icons.Material.Filled.Inbox, typeof(SharedResource), Section: NavSection.User) (MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationUIModule.cs:19) and new("Nav.PushNotifications", NotificationRoutePaths.Notifications, Icons.Material.Filled.NotificationsActive, typeof(SharedResource), RoleNames.Organizer, Section: NavSection.Admin, Group: "Notifications") (:20). Covered by NavMenuTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Layout/NavMenuTests.cs), which drives the menu through a StubUiModule(IReadOnlyList<NavItem> navItems) (:198).
• Caveats / not-in-source: RequiredRole and RequiredClaim control rendering only. They hide a link; they do not authorize the destination. The menu keeps a section-level authentication check alongside the per-item one deliberately (NavMenu.razor:104-105), but page-level and API-level authorization remain the enforcing gates.

IUIModule

MMCA.Common.UI · MMCA.Common.UI.Common.Interfaces · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Interfaces/IUIModule.cs:11 · Level 2 · interface

• What it is: the UI-side counterpart to the server's IModule. A pluggable UI module declares its navigation entries, its Razor assembly for route discovery, and optionally components it injects into the top app bar and the root layout.
• Depends on: NavItem; System.Reflection.Assembly (IUIModule.cs:1).
• Concept introduced, plugging into a packaged application shell. [Rubric §18, UI Architecture & Component Design] assesses whether there is a coherent composition model. ADR-067 states the problem this solves: before it, every Blazor head owned its own App / Routes / layout / nav markup, so adding a module meant editing the host (a new nav link, a new assembly in the router, a new drawer in the layout), and two apps built on the same framework drifted apart in shell behavior even where they agreed. The framework already shipped the shell; what was missing was a contract letting a module contribute into it. Resolution is IEnumerable<IUIModule> from DI, so the shell composes whatever is registered without naming any module. [Rubric §25, Navigation & Information Architecture] applies because nav is contributed rather than hard-coded, and [Rubric §7, Microservices Readiness] applies in the same spirit as the server contract: a module that can be added or removed by one registration line is a module that can move.
• Walkthrough: five members, three of them defaulted.
  • IReadOnlyList<NavItem> NavItems (IUIModule.cs:14): the module's contribution to the shared sidebar. Flattened by NavMenu.razor:256 with .SelectMany(m => m.NavItems).
  • Assembly Assembly (:17): the assembly containing the module's Razor pages. The router consumes it as AdditionalAssemblies="UIModules.Select(m => m.Assembly)" (MMCA.Common/Source/Presentation/MMCA.Common.UI/Routes.razor:13), which is what makes a module's @page routes discoverable at run time with no central route table to edit.
  • IReadOnlyList<Type> AppBarComponentTypes => [] (:20): a default interface member returning an empty collection expression. Components listed here render inside the top app bar (MMCA.Common/Source/Presentation/MMCA.Common.UI/Layout/MainLayout.razor:155, also gathered by NavMenu.razor:216).
  • IReadOnlyList<Type> LayoutComponentTypes => [] (:23): the same idea at the root-layout level, for drawers, overlays and headless listeners (MainLayout.razor:156).
  • IReadOnlyList<Type> ContentHeaderComponentTypes => [] (:29): components rendered at the top of the main content region, above the page body and beside the offline banner, for a banner the user must see before the page itself (:25-28). MainLayout gathers them with UIModules.SelectMany(m => m.ContentHeaderComponentTypes) (MainLayout.razor:157) and renders them in a block documented at MainLayout.razor:77.
• Why it's built this way: the three default interface members are what keep the simple case simple. A module that only contributes navigation implements two properties, not five, and can gain app-bar, layout or content-header contributions later without a breaking change to anything already written. Passing an Assembly rather than a list of page types keeps route discovery reflective, so adding a page is never a framework edit.
• Where it's used: implemented by module descriptors across the workspace: the framework's own NotificationUIModule (MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationUIModule.cs:15), ADC's ConferenceUIModule (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.UI/ConferenceUIModule.cs:14), EngagementUIModule (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.UI/EngagementUIModule.cs:17), IdentityUIModule (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.UI/IdentityUIModule.cs:18) and the MAUI-head-only DeviceUIModule (MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI/DeviceUIModule.cs:18), plus Store's CatalogUIModule (MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.UI/CatalogUIModule.cs:13), SalesUIModule (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.UI/SalesUIModule.cs:16), IdentityUIModule (MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.UI/IdentityUIModule.cs:13) and MauiUIModule (MMCA.Store/Source/Hosts/UI/MMCA.Store.UI/MauiUIModule.cs:14). The optional members earn their keep in practice: NotificationUIModule contributes NotificationBell to the app bar and NotificationListener to the layout (NotificationUIModule.cs:23-25), Store's SalesUIModule contributes CartButton plus CartDrawer and OrphanOrderRecovery (SalesUIModule.cs:30-32), ADC's EngagementUIModule contributes LiveEventListener (EngagementUIModule.cs:31), and ADC's DeviceUIModule contributes five headless native listeners at once (DeviceUIModule.cs:33). Registration goes through AddUIModule<TModule>() (see DependencyInjection), which each module's own one-line Add{Module}UI() delegates to, for example MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.UI/DependencyInjection.cs:19. A stub implementation drives the menu tests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Layout/NavMenuTests.cs:308) and another drives the backend-less component gallery (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Gallery/Stubs/GalleryUIModule.cs:14).

IEntityService<TEntityDTO, TIdentifierType>

MMCA.Common.UI · MMCA.Common.UI.Common.Interfaces · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Interfaces/IEntityService.cs:20 · Level 3 · interface

• What it is: the generic CRUD contract every module page injects to talk to its API endpoints. Seven asynchronous members, every one of them returning a Result.
• Depends on: Result and ErrorType from MMCA.Common.Shared.Abstractions (IEntityService.cs:1); IBaseDTO<TIdentifierType> as the TEntityDTO constraint (:21) and BaseLookup<TIdentifierType> as a return type (:41), both from MMCA.Common.Shared.DTOs (:2). Implemented by EntityServiceBase<TEntityDTO, TIdentifierType>.
• Concept introduced, the Result railway crossing the HTTP boundary intact. [Rubric §18, UI Architecture & Component Design] assesses separation of components from their data access, and [Rubric §9, API & Contract Design] assesses whether the client contract mirrors the server surface. But the teaching point is the second paragraph of the doc comment (IEntityService.cs:10-16): every member returns "the same railway type the server produced, read back from its Problem Details response with the original ErrorType intact". A page therefore branches on the outcome instead of catching an exception. That is what makes a 404 renderable as an empty state and a 401 as a redirect without pattern-matching message text, and it is why the sibling helper ResultUiExtensions exists. ADR-013's 2026-08-27 revision records this as the retirement of the UI-layer deviation, and ADR-094 records the surrounding data-access contract. Note also the layering rule this respects: MMCA.Common.UI may reference MMCA.Common.Shared only, which is why both constraints come from Shared and never from Application or Domain [Rubric §3, Clean Architecture].
• Walkthrough: two generic constraints (:21-22) bind TEntityDTO to IBaseDTO<TIdentifierType> and require TIdentifierType : notnull. Then seven members, every one ending in a defaulted CancellationToken:
  • GetAllAsync(bool includeFKs, bool includeChildren, CancellationToken) (:25-28) returns Result<IReadOnlyList<TEntityDTO>>; the two flags map to API query options.
  • GetPagedAsync(Dictionary<string, (string Operator, string Value)> filters, int pageNumber, int pageSize, string? sortColumn, string? sortDirection, bool includeChildren, CancellationToken) (:31-38) returns Result<(IReadOnlyList<TEntityDTO> Items, int TotalItems)>. The TotalItems half of that tuple is what makes server-side paging work at all: a grid needs the total to size its pager without fetching the rest of the table. The filter dictionary is the client half of the dynamic query contract (ADR-034).
  • GetAllForLookupAsync(string nameProperty, CancellationToken) (:41-43) returns lightweight Id + Name BaseLookup<TIdentifierType> items for dropdowns and autocompletes, so a picker never pulls whole entities.
  • GetByIdAsync(TIdentifierType id, bool includeChildren, CancellationToken) (:50-53) returns Result<TEntityDTO>, and the doc comment (:45-49) pins the contract that used to be ambiguous: a missing entity is an ErrorType.NotFound failure, never a success carrying null. That is what lets a detail page write if (result.IsNotFound()) instead of a null check that cannot distinguish "absent" from "the call failed".
  • AddAsync(TEntityDTO entity, CancellationToken) (:56-58) returns the server-assigned DTO including its generated id.
  • UpdateAsync(TEntityDTO entity, CancellationToken) (:61-63) and DeleteAsync(TIdentifierType id, CancellationToken) (:66-68) return the non-generic Result, because there is no value to carry back, only a verdict.
• Why it's built this way: an interface keeps Blazor components testable (mock the contract, no HTTP) and hides the API URL structure behind a typed surface. The generic-over-DTO shape is the client mirror of the server's generic controller layer (ADR-034), which is why one base class implements it for every entity in the system. The uniform Result return is deliberate rather than convenient: mixing nullable returns for reads with bool for writes forces each call site to invent its own error story, whereas returning Result everywhere means one small set of helpers covers all seven members.
• Where it's used: implemented for every entity by EntityServiceBase<TEntityDTO, TIdentifierType> (MMCA.Common/Source/Presentation/MMCA.Common.UI/Services/Api/EntityServiceBase.cs:43-47, which also composes an optional IUiReadCache) and consumed by every module CRUD page, most of them through DataGridListPageBase<TDto>. Registration is automatic: AddUIModule<TModule>() runs a Scrutor scan over the module's assembly that picks up every class assignable to IEntityService<,> and registers it scoped as its implemented interfaces (DependencyInjection, MMCA.Common.UI/DependencyInjection.cs:323-327). The (Items, TotalItems) shape of GetPagedAsync is also the shape MobileInfiniteScrollList<TItem>'s page-fetch delegate expects.

ResultUiExtensions

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/ResultUiExtensions.cs:74 · Level 4 · class (static, extension methods)

• What it is: the page-side half of the Result transport. It is the four things a Blazor page ever does with a failed Result, written once so no page hand-rolls them again: unwrap the value, push the message into an inline alert, raise it as a toast, or branch on why it failed.

• Depends on: Result, Error, ErrorType and ErrorTypeSeverity from MMCA.Common.Shared.Abstractions (ResultUiExtensions.cs:5); ProblemDetailsResultReader and the synthesized-failure codes of HttpResultExecutor (:6, :9); IToastService and ToastSeverity (:7); the framework's SharedResource resource pair (:8); Microsoft.Extensions.Localization.IStringLocalizer (:4); System.Resources.ResourceManager (:3); System.Diagnostics.CodeAnalysis.NotNullWhenAttribute and SuppressMessageAttribute (:1).

• Concept introduced, localize-with-pass-through, and severity-ordered deduplication. [Rubric §24, Forms, Validation & UX Safety] assesses whether a failure reaches the user as one clear, actionable sentence; [Rubric §27, Internationalization] assesses whether that sentence follows the active culture; [Rubric §15, Best Practices & Code Quality] assesses whether the same five lines get re-typed per page. Two mechanisms carry all three.

  • Pass-through localization (:22-27): every message is looked up as a resource key, and one the localizer does not declare renders verbatim. That is what lets a single call site handle both an API error whose text the server already localized and a client-side error whose Message is a resource key.
  • Code-keyed fallback for synthesized failures (:27-33): a failure the client built itself, with no server-phrased message to pass through (a bodiless HTTP status, a transport failure, a client timeout), is looked up by its error code instead: Http.{status}, then the generic Http.Status format, Http.TransportFailure, Http.Timeout. A code the supplied localizer does not hold resolves from the framework's own SharedResource pair for the current UI culture, so a consumer page passing its own IStringLocalizer<PageType> (which holds no Http.* keys) still shows the translated sentence; the English message is the last resort. The class holds a private ResourceManager SharedResources = new(typeof(SharedResource)) (:84) and the format key HttpStatusFallbackKey = "Http.Status" (:78) for this.
  • Severity-ordered deduplication (:36-39): messages are made distinct with StringComparer.Ordinal and ordered most-severe-first via ErrorTypeSeverity, so a real 403 or 500 leads and an incidental validation message never buries it. The shape this guards against is common once Result.Combine aggregates invariants: the same sentence arriving under several codes now reads as one sentence. This is the client mirror of the server-side status selection recorded in ADR-013, using the very same ranking type hoisted into Shared (MMCA.Common/Source/Core/MMCA.Common.Shared/Abstractions/ErrorTypeSeverity.cs:59) so both edges classify one aggregate identically.

  The class doc even ships a before/after pair (:42-73) contrasting the old try / catch (Exception ex) shape with if (result.TryGetValue(out var dto)) { ... } else { result.NotifyOnFailure(Toast, L); }, both reading the token as _cts.LifetimeToken() (ComponentLifetimeExtensions).

• Walkthrough: eleven public members plus five private helpers, in four tiers.

  • Unwrapping. TryGetValue<T>(this Result<T>, [NotNullWhen(true)] out T? value) (:103-118) reads like Dictionary.TryGetValue so the success and failure branches sit side by side. The implementation carries a subtle correctness note in its comment (:107-109): the failure branch is decided by result.IsFailure, not by whether the value is null, because for a value type (a (Items, TotalItems) tuple, an int count) default is never null and a null test alone would report every failure as a success. The three-argument overload (:137-154) hands the errors back on the failing branch and documents one edge honestly (:123-129): a success carrying a null value also takes the failing branch, and a success has no errors, so errors comes back empty. The framework's own services never produce that shape (a 2xx with no value fails with Http.EmptyResponse), but a caller switching on the error list should not assume it is non-empty.
  • Composing the message. LocalizedErrorMessages(this Result, IStringLocalizer?) (:166-180) returns an empty list for a success, so a caller can bind it without a null or success check, and otherwise orders by ErrorTypeSeverity.Rank descending, localizes each error through the private LocalizeError (:177) rather than its bare message, drops blanks, and takes ordinal-distinct values (:175-179). LocalizedErrorMessage (:190-194) joins that list with a space and returns null for a success. LocalizeDistinct(IEnumerable<string>?, IStringLocalizer?) (:206-218) gives the same treatment to a plain message list, specifically the MudForm.Errors shape whose entries are resource keys produced by the model's DataAnnotations; it preserves original order rather than re-ranking, since those entries carry no ErrorType.
  • Rendering. OnFailureSetError(this Result, Action<string?> setError, IStringLocalizer?) (:248-255) hands the composed message to the page's own error field, the one an inline MudAlert or the PageErrorState component renders (its doc comment names it by its current home, MMCA.Common.UI.Components.PageState.PageErrorState, at :221-222, matching the file at MMCA.Common/Source/Presentation/MMCA.Common.UI/Components/PageState/PageErrorState.razor:1), and clears it on success by passing null (:253), which is why a retry that succeeds does not leave a stale alert on screen. NotifyOnFailure(this Result, IToastService, IStringLocalizer?, ToastSeverity = Error) (:289-305) raises the composed message as one toast, never one per error, calling toast.Show(message, severity) only when the composed message is non-null (:298-302). Both return the same result instance so the call can sit inline, and both have a Result<T> overload that delegates to the non-generic one and returns the typed result (:260-264, :310-318), which is what keeps (await Service.AddAsync(dto, token)).NotifyOnFailure(Toast, L) chainable. All four rendering overloads carry the same [SuppressMessage("ApiDesign", "RS0026...")] (:247, :259, :288, :309): two public overloads with optional parameters is the shape RS0026 forbids, and the justification records them as grandfathered, released after the v1.152 public-API baseline while RS0026/RS0027 were off, so changing the signatures now would be a breaking change.
  • Branching on why. HasErrorType(this Result, ErrorType) (:328-332) is the general predicate; the doc comment (:320-323) notes the category survives the HTTP round trip through ProblemDetailsResultReader, which is what makes this meaningful client-side at all. IsNotFound() (:340) and IsUnauthorized() (:348) are the two named cases, and their doc comments state the intended UI reaction: a 404 becomes a "not found" state rather than an error alert, a 401 becomes a redirect to the login route.
  • The private helpers. LocalizeError(Error, IStringLocalizer?) (:350-373) chooses the lookup per error. With no localizer it returns the message verbatim. For a synthesized HTTP status (ProblemDetailsResultReader.TryGetSynthesizedStatus) it tries the status's own Http.{status} code, then the Http.Status format with the status code as argument, then the message (:360-364). For the executor's own transport or timeout failure it tries the code, then the message (:367-369); IsSynthesizedTransportFailure (:400-405) matches only when the message is still the executor's own English sentence, so a caller that reused one of those codes with a message of its own keeps it. Anything else falls to Localize. LookUpByCode (:377) asks the caller's localizer first and then the framework's SharedResources, and FormatByCode (:386) does the same for a format string. Localize(string message, IStringLocalizer?) (:407-416) is where pass-through actually happens: a null localizer or a blank message returns the input unchanged, otherwise it indexes the localizer and returns localized.ResourceNotFound ? message : localized.Value (:415).

• Why it's built this way: extension methods on Result rather than an injectable service, because there is no state and nothing to resolve, so a page uses them without a constructor parameter and a unit test calls them directly. Every rendering helper returns the result it was given, which is what allows the fluent one-liner style the class doc advertises. The nullable IStringLocalizer? parameter everywhere means the helpers work from a context that has no localizer (they then render verbatim) rather than forcing one in.

• Where it's used: by every page and component that calls an IEntityService<TEntityDTO, TIdentifierType> member, across the framework package and both consumer apps, plus the shared deduplicating error-summary component. Covered by ResultUiExtensionsTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Common/ResultUiExtensionsTests.cs:17) [Rubric §28, Front-End Testing].

• Caveats / not-in-source: the class doc opens with "the Result transport (ADR-030)" (ResultUiExtensions.cs:14), but ADR-030 is 030-startup-sole-migrator.md. The Result-pattern record, including the 2026-08-27 revision that names ResultUiExtensions and its exact member list, is ADR-013; the client data-access half is ADR-094. Trust the ADR index over the comment.

NotificationRoutePaths

MMCA.Common.UI · MMCA.Common.UI.Common · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/NotificationRoutePaths.cs:8 · Level 5 · class (static)

• What it is: the route constants for the framework's own notification feature, three literal paths plus one typed deep-link builder for a single inbox item.
• Depends on: System.Globalization.CultureInfo (NotificationRoutePaths.cs:1) and the UserNotificationIdentifierType alias, which resolves to int (MMCA.Common/Source/Core/MMCA.Common.Shared/GlobalUsings.NotificationIdentifierType.cs:2). That alias dependency is why an otherwise Level 0-looking constants class sits at Level 5.
• Concept introduced, formatting a URL segment invariantly. The "one source of truth for route strings" idea is taught at RoutePaths; what is new here is the builder method and why it pins a culture. [Rubric §27, Internationalization] assesses whether culture-sensitive formatting is applied deliberately rather than by default, and this is the case where the correct answer is to opt out. The doc comment (:14-18) spells it out: the route's :int constraint is the validation boundary, so a culture that renders digit groups (1,234) or non-ASCII digits would produce a URL the constraint rejects. A route segment is machine-readable data, not user-facing text.
• Walkthrough: three public static readonly string members and one method.
  • Notifications = "/notifications" (:10), the admin push-management list.
  • NotificationSend = "/notifications/send" (:11), the admin send page.
  • NotificationInbox = "/notifications/inbox" (:12), the per-user inbox.
  • NotificationInboxItem(UserNotificationIdentifierType id) (:21-22) composes the deep link with string.Create(CultureInfo.InvariantCulture, $"{NotificationInbox}/{id}"). The target route exists: NotificationInbox.razor carries both @page "/notifications/inbox" and @page "/notifications/inbox/{Id:int}" (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Notifications/NotificationInbox.razor:1-2).
• Why it's built this way: kept separate from RoutePaths so an app that never enables the notification module carries no irrelevant constants, and so notification routes evolve on their own. string.Create with an explicit culture, rather than plain string interpolation, is the analyzer-friendly way to state "this formatting is deliberate" in a repo where every analyzer is an error.
• Where it's used: the notification surfaces navigate by these constants rather than by literals: NotificationSend.razor.cs:72 (its breadcrumb back to the list), :117 (post-send navigation) and :136 (the cancel path), NotificationList.razor.cs:106 (navigate to send), and NotificationBell.razor.cs:249 (NavigateToInbox). NotificationUIModule builds its two NavItem entries from NotificationInbox and Notifications (NotificationUIModule.cs:19-20). ADC's AppActionRouteMapTests asserts that a push action resolves to NotificationRoutePaths.NotificationInbox (MMCA.ADC/Tests/Modules/Engagement/MMCA.ADC.Engagement.UI.Tests/Services/AppActionRouteMapTests.cs:39).
• Caveats / not-in-source: NotificationInboxItem has no call site in any of the four repos as of this source; it is listed in PublicAPI.Unshipped.txt (MMCA.Common/Source/Presentation/MMCA.Common.UI/PublicAPI.Unshipped.txt:315, recorded there with its resolved signature NotificationInboxItem(int id)), while the three string constants are baselined in PublicAPI.Shipped.txt:913-915. The {Id:int} route it targets is live; the typed builder for it is shipped but not yet adopted.

DependencyInjection

MMCA.Common.UI · MMCA.Common.UI · MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:31 · Level 10 · class (static, with one extension(IServiceCollection) block)

• What it is: the composition root of the UI layer. One AddUIShared(configuration) call wires the shared UI infrastructure every head needs (Blazor Server, WebAssembly, MAUI), and six smaller methods cover the per-head, per-module and per-opt-in registrations.
• Depends on: nearly the whole group. Settings: ApiSettings, LayoutSettings, LegalSettings, RegistrationSettings, UiReadCacheOptions, NotificationBellOptions. Authorization: NotificationPageRequirement / NotificationPageAuthorizationHandler. Caching: IUiReadCache / UiReadCache. Localization: PseudoStringLocalizerFactory, ResxMudLocalizer, InvariantMudLocalizationInterceptor. HTTP: AuthDelegatingHandler, CultureDelegatingHandler, SameOriginProxyRequestHandler, HttpResilienceDefaults. Facades: IToastService / MudToastService, IAppDialogService / MudAppDialogService. Services: IAuthUIService, IEmailConfirmationUIService / EmailConfirmationUIService, ILegalAcceptanceUIService / LegalAcceptanceUIService, ViewerTimeZone, OAuthFlowStateStore, ListPageStateService, ListPageQueryStateService, NavigationHistoryService, ThemeService, ICultureApplier / EndpointCultureApplier, IPublicLinkBuilder / NavigationPublicLinkBuilder, IUserPreferenceWriter, IUserPreferenceReader, IOAuthUISettings / DefaultOAuthUISettings, ISessionCookieSync / JsFetchSessionCookieSync. Administration opt-ins: IUserAdminUIService<TUserDto> / UserAdminService<TUserDto>, IUserAdminActionsUIService, IRoleAdminUIService / RoleAdminService. Capabilities: IFormFactor / WasmFormFactor. Composition: IUIModule, IEntityService<TEntityDTO, TIdentifierType>. Externals: Scrutor (Decorate, Scan), MudBlazor, and Microsoft.Extensions.{Configuration, DependencyInjection, Localization, Options} (DependencyInjection.cs:2-23).
• Concept introduced, the composition root written as an extension(T) block. The whole registration surface lives inside extension(IServiceCollection services) (DependencyInjection.cs:33) rather than as classic this-parameter extension methods; see primer, C# extension(T) types for the language mechanics, taught once. [Rubric §15, Best Practices & Code Quality] assesses one consistent idiom across layers, and this file matches the other DependencyInjection classes in every layer of the workspace. [Rubric §33, Developer Experience] assesses fail-fast startup and a small number of calls per host. [Rubric §12, Performance & Scalability] assesses whether concerns are wired once, centrally: localization, culture forwarding, authentication, resilience and caching are all configured here rather than per page.
• Walkthrough: seven methods in the extension block.
  • AddUIShared(IConfiguration configuration) (:39-211), in order:
    • Options. ApiSettings binds with .ValidateDataAnnotations().ValidateOnStart() (:42-46), so a missing ApiEndpoint fails the host at startup rather than at the first HTTP call. LayoutSettings binds without validation because empty defaults are acceptable (:48-49), and so do LegalSettings (:53-54, the footer, registration-checkbox and terms-dialog links; an absent section leaves every URL empty, which renders none of them) and RegistrationSettings (:58-59, the optional blocks of the shared register page; an absent section keeps every block). UiReadCacheOptions (:63-64) and NotificationBellOptions (:66-67) bind the client-side staleness policy; the comment (:61-62) records that both sections are optional and an absent section leaves the compiled-in defaults, which is what a host gets without configuring anything.
    • Clock and read cache. TryAddSingleton(TimeProvider.System) (:71), with a comment explaining both directions of the TryAdd (:69-70): a host that already registered one, as AddInfrastructure does, keeps it, and a test substitutes a FakeTimeProvider. TryAddScoped<IUiReadCache, UiReadCache>() (:76) is scoped so it is per-circuit on Blazor Server; the comment (:73-75) records the consequence on the other heads, where the scope is the app lifetime, which is why the sign-out path clears it explicitly, otherwise one account's reads would outlive its session [Rubric §26, Front-End Security].
    • Notification-page policy. AddAuthorizationCore registers a policy named NotificationPageRequirement.PolicyName carrying a NotificationPageRequirement (:81-83), and TryAddEnumerable adds the transient NotificationPageAuthorizationHandler (:84-85). The comment (:78-80) states the intent: [Authorize] semantics, except that a host hiding those pages (Layout:HideNotificationPagesWhenUnregistered) lets the request reach the router, which answers 404 instead of the sign-in challenge.
    • Localization (ADR-027). AddLocalization() (:88) for IStringLocalizer<T>, then Decorate<IStringLocalizerFactory, PseudoStringLocalizerFactory>() (:95), registered unconditionally because the pseudo-locale transform is inert under every other culture and the pseudo locale is only ever activatable in Development (:90-94). TryAddTransient<MudBlazor.MudLocalizer, ResxMudLocalizer>() (:101) localizes MudBlazor's own component text; the comment (:97-100) records why TryAdd is authoritative regardless of host registration order, namely that AddMudServices registers no MudLocalizer of its own and a DI resolution test guards that assumption. AddLocalizationInterceptor<InvariantMudLocalizationInterceptor>() (:110) follows immediately: MudBlazor's own default interceptor reads its built-in English strings by assigning CultureInfo.CurrentUICulture (invariant, then the previous value back), which writes an AsyncLocal culture into the calling context; on a MAUI hybrid head, where that is the main thread, nothing resets it and the app pins to its launch language even after a culture switch reloads the thread defaults. InvariantMudLocalizationInterceptor reads the same resource under an explicit invariant culture instead, and registers with replace semantics so it wins whether AddMudServices ran before or after this call (ADR-027 Decision 10) (:103-109).
    • The one HTTP client. Both delegating handlers register transient (:114-115). Before the client itself, usesSameOriginProxy is computed from the raw configuration (:120-121): it is true only when Api:SameOriginApiEndpoint carries a value, which per the comment (:117-119) happens only on a WebAssembly client whose Server host opted into the same-origin API proxy (ADR-131) and handed that value down through /client-config; every other host (Server, MAUI, a WASM client of a host that did not opt in) keeps the pipeline unchanged. Then the named "APIClient" (:124-147), whose builder is kept in apiClient (:124) so a handler can be appended afterwards. Its factory resolves IOptions<ApiSettings> and sets client.BaseAddress = new Uri(apiSettings.SameOriginApiEndpoint ?? apiSettings.ApiEndpoint!, UriKind.Absolute) (:131-136): the same-origin proxy base, when present, replaces the gateway URL for data calls, and the comment (:134-135) notes the bootstrap has already resolved it to an absolute address. There is deliberately no hand-written endpoint guard, and the comment says why (:126-130): resolving .Value runs the ValidateDataAnnotations rules registered above, so a missing [Required] endpoint already fails as an OptionsValidationException, and a second check would only give the same failure a different, less informative exception. client.Timeout is pinned to HttpResilienceDefaults.TotalRequestTimeout (:142) because the BCL's own 100-second default was chosen with no knowledge of the resilience budget and would cut a call off mid-policy at an arbitrary point (:138-141) [Rubric §29, Resilience & Business Continuity]. Default headers are cleared and Accept: application/json added (:143-144), and the two handlers chain in order (:146-147) so every outgoing call carries both the bearer token and the active UI culture as Accept-Language. When usesSameOriginProxy is true, SameOriginProxyRequestHandler is registered transient and appended as the innermost handler (:149-155); the comment (:151-152) gives the reason for that position: it must see, and strip, every Authorization header the outer handlers or a service's DefaultRequestHeaders attached, and it stamps the proxy's CSRF header [Rubric §26, Front-End Security].
    • Facades. services.AddCommonUiFacades() (:159), factored out so a bUnit harness can register exactly these two without pulling in the whole shared-UI surface (:157-158).
    • Scoped services, all via TryAdd so several composing hosts cannot double-register: IAuthUIService (:162), IEmailConfirmationUIService to EmailConfirmationUIService (:166, the /confirm-email page's client per ADR-116; a separate interface rather than new IAuthUIService members, so a consumer's own IAuthUIService implementation keeps compiling, per the comment at :164-165), ILegalAcceptanceUIService to LegalAcceptanceUIService (:170, the terms-acceptance client behind TermsAcceptanceGate, registered for every host and inert until a host renders the gate, per the comment at :168-169), OAuthFlowStateStore (:174, binding an OAuth completion to the flow this client started so a deep-linked completion code from someone else's provider round trip is dropped instead of exchanged, per its own comment at :172-173), ListPageStateService (:175), ListPageQueryStateService (:176), NavigationHistoryService (:177), ThemeService (:180, ADR-028), ICultureApplier defaulting to EndpointCultureApplier (:186), ViewerTimeZone (:190, the viewer's browser time zone, so UTC instants such as notification and session times render on the clock the person reads), IPublicLinkBuilder defaulting to NavigationPublicLinkBuilder (:196), and the per-user preference writer and reader (:199-200), documented as best-effort and a no-op for an anonymous user (:198). TryAddSingleton<IOAuthUISettings, DefaultOAuthUISettings>() (:204) supplies a no-op default that a downstream app replaces.
    • Capabilities. AddDeviceCapabilityDefaults() (:208, ADR-042) so every capability contract resolves on every head, registered here specifically so MAUI and browser hosts can override afterwards under last-registration-wins (:206-207).
  • AddCommonUiFacades() (:228-233): two TryAddScoped calls, IToastService to MudToastService (:230) and IAppDialogService to MudAppDialogService (:231). Its doc comment (:213-227) is the clearest statement of the facade rule anywhere in the codebase: apart from these two implementations, the only framework type that names MudBlazor's ISnackbar / IDialogService is the DeleteConfirmation component, which injects IDialogService directly to show its typed dialog (pages, other components and the Result helpers depend on the contracts), they are scoped to match the MudBlazor services they wrap, and the method is called both by AddUIShared and by the shipped bUnit base so a component test resolves the facades without the rest of the shared-UI surface.
  • AddClientAuthSessionCookieSync() (:240-244): one TryAddScoped<ISessionCookieSync, JsFetchSessionCookieSync>() (:242), the bridge that mirrors the client's in-memory tokens into the HttpOnly cookie read during server-side SSR prerender. Called from both the Blazor Server host and the WebAssembly client (:235-239).
  • AddWasmFormFactor() (:252-253): registers IFormFactor to WasmFormFactor as a singleton. The doc comment names the two alternatives (:246-251): AddCommonWebFormFactor() from MMCA.Common.UI.Web on the Blazor Server head, AddMauiFormFactor() from MMCA.Common.UI.Maui on the MAUI head.
  • AddUserAdministrationUI<TUserDto>() (:269-279), the ADR-116 UI opt-in for user administration: registers IUserAdminUIService<TUserDto> to UserAdminService<TUserDto> (:271), then forwards IUserAdminActionsUIService to the same instance rather than registering it a second time (:275-276), so the actions the component performs and the page it lists go through one instance (and one substitute, in a test), per the comment at :273-274. The doc comment (:255-266) states the call convention (once per app, after AddUIShared, with the app's own administration DTO) and that an app which serves no administration endpoints registers nothing and the component the service backs is simply never rendered.
  • AddRoleAdministrationUI() (:295-300): the non-generic ADR-116 sibling, registering IRoleAdminUIService to RoleAdminService (:297). Its doc comment (:281-293) explains why it takes no type parameter unlike AddUserAdministrationUI<TUserDto>(): roles and permissions are strings the framework already owns, so there is no app DTO to name.
  • AddUIModule<TModule>() (:320-330), constrained to TModule : class, IUIModule (:321): a Scrutor scan FromAssemblyOf<TModule>() registering every IEntityService<TEntityDTO, TIdentifierType> implementation scoped as its implemented interfaces (:323-327), then AddSingleton<IUIModule, TModule>() (:329). The doc comment (:308-314) records the deliberate boundary: this is the two-step prologue every module's Add{Module}UI() opens with, and module-specific services stay with the caller afterwards, so a module whose service must beat a shared default still controls its own registration order. The type-parameter doc (:316-319) states the constraint that follows from using the descriptor's assembly as the scan root: it must live alongside the module's entity services and Razor pages.
• Why it's built this way: TryAdd throughout is both a safety property (several composing hosts calling AddUIShared cannot double-register) and the override mechanism (a host that registers its own implementation before the call wins). Two ordering choices push in the opposite direction and are called out in comments because they are load-bearing: ICultureApplier's default round-trips a server /culture/set endpoint that a MAUI hybrid head does not have, so hybrids override it after AddUIShared (:182-185), and IPublicLinkBuilder's default resolves against the browser origin, which is wrong for a MAUI WebView whose origin is a virtual host nobody else can open, so that is overridden after as well (:192-195). InvariantMudLocalizationInterceptor follows the same head-dependent pattern one layer down: MudBlazor's own interceptor is correct everywhere except the MAUI hybrid main thread, so the replacement is registered unconditionally here rather than left to the affected head to override, because replace semantics make the registration order irrelevant (:103-110). SameOriginProxyRequestHandler is the one registration decided by configuration rather than by order: it is added only when Api:SameOriginApiEndpoint is present (:120-121, :149-155), so a host that never opts in carries no trace of it in its pipeline. Read together, the file encodes a rule worth carrying into any new registration: a contract whose correct implementation depends on the head is defaulted here and replaced later (or, where replace semantics make order irrelevant, registered outright), while a contract that is the same everywhere is TryAdded and left alone. The two administration opt-ins follow the same principle one level up: nothing else in the framework calls either one, so an app that serves no administration or role-administration endpoints registers nothing and the corresponding component is simply never rendered.
• Where it's used: called once at startup by all six consuming UI hosts (ADC's MMCA.ADC.UI.Web, MMCA.ADC.UI.Web.Client and MAUI MMCA.ADC.UI, plus the three Store equivalents), each followed by the per-module Add{Module}UI() calls, which are usually one-liners over AddUIModule<TModule>(), for example MMCA.Store/Source/Modules/Identity/MMCA.Store.Identity.UI/DependencyInjection.cs:19 and MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.UI/DependencyInjection.cs:24. AddCommonUiFacades() has a second caller outside any host, the shipped bUnit base (MMCA.Common/Source/Hosting/MMCA.Common.Testing.UI/Infrastructure/BunitComponentTestBase.cs:54). AddUserAdministrationUI<TUserDto>() and AddRoleAdministrationUI() are each meant to be called once per app, after AddUIShared, by an app that opts into the corresponding ADR-116 administration surface (:259, :286); nothing inside the framework itself calls either one. The "APIClient" configured here is the client every EntityServiceBase<TEntityDTO, TIdentifierType>-derived service resolves. The assembly this class lives in is also the one UISharedAssemblyReference names for the architecture fitness suite.

ApiFileDownloadButton

MMCA.Common.UI · MMCA.Common.UI.Components.Forms · MMCA.Common/Source/Presentation/MMCA.Common.UI/Components/Forms/ApiFileDownloadButton.razor.cs:14 · Level 0 · class (partial component)

• What it is: a payload-agnostic icon button that hands the user a file produced by an API endpoint. On a browser it is a plain download link to the endpoint; on a native (MAUI) head, where the WebView cannot download, it fetches the bytes over the API client, stages a temp file, and opens the OS share sheet. Callers supply the endpoint, the file name, the MIME type and the labels; the button knows nothing about what the payload is (ApiFileDownloadButton.razor.cs:6-13).
• Depends on: IExternalLinkService and IShareService (the device-capability abstractions), IToastService, ApiSettings through IOptions<ApiSettings>, and IStringLocalizer<ApiFileDownloadButton> over the component's own .resx pair, all injected in the markup file (Components/ApiFileDownloadButton.razor:4-9). Externals: IHttpClientFactory, System.IO.File/Path, and MudBlazor's MudIconButton.
• Concept introduced, one component, two heads, one contract. [Rubric §18, UI Architecture] (assesses whether components have a single clear responsibility and keep host differences out of pages) and [Rubric §26, Front-End Security] (assesses whether the front end treats caller-supplied data as untrusted). The head split is decided by a capability query, not by a compilation symbol: the markup branches on ExternalLink.InterceptsLinks (ApiFileDownloadButton.razor:18), and both branches render the same MudIconButton with the same icon, size and accessible name, so the affordance looks identical while the mechanism differs (ADR-042). The security concept is path containment: a file name built from entity data must not be able to steer a filesystem write, which is what ResolveStagedFileName exists to prevent.
• Walkthrough:
  • Parameters (lines 17-80). Three are [EditorRequired]: RelativeApiPath (line 19), FileName (line 30) and ShareTitle (line 35). ContentType defaults to application/octet-stream (line 43) and is what the share sheet uses to pick target apps. Icon defaults to the generic download glyph (line 47), Size to Size.Small (line 51). AriaLabel, UnavailableMessage and FailureMessage (lines 59, 66, 73) are nullable overrides over localized defaults. HttpClientName defaults to "APIClient" (line 80), the framework's bearer-token plus culture-header client.
  • AccessibleLabel (line 84) resolves AriaLabel ?? L["Button.Download.Aria"].Value, and the markup binds it to BOTH aria-label and title on either branch (ApiFileDownloadButton.razor:22-23, :31-32), so an icon-only control always carries a name. The default key lives in the component's own resource file (Components/ApiFileDownloadButton.resx:15).
  • BrowserDownloadUrl (lines 93-103) is the browser branch's Href. The anchor is a plain top-level navigation, so it carries cookies but never an Authorization header (lines 86-92), and the base is chosen in that light as SameOriginApiEndpoint ?? WasmApiEndpoint ?? ApiEndpoint (line 98). On a WebAssembly client of a host running the same-origin API proxy the link targets the proxy, the same base the "APIClient" uses: the browser sends the HttpOnly session cookie and the proxy attaches the real bearer server-side, so an authenticated download works with no token in script (ADR-131). Everywhere else it prefers WasmApiEndpoint over ApiEndpoint because the browser needs the externally reachable gateway URL: on the Server head ApiEndpoint may be a container-internal name, and on the WASM head ApiEndpoint is already the browser-reachable value fetched from /client-config. With no base URL configured it falls back to the relative path (lines 99-100); otherwise it composes an absolute URI (line 101).
  • ShareDownloadedFileAsync (lines 105-154) is the native branch. It re-entrancy-guards on _isExporting and an empty path (lines 107-110), sanitizes the file name before the fetch so an unusable name costs no download (lines 115-121), creates the named client and pulls the bytes (lines 123-124), stages the file (line 126), and calls Share.ShareFileAsync (line 128), toasting a warning when no share surface accepted it (line 130). Three catch blocks all surface a toast rather than throwing: HttpRequestException (line 133), OperationCanceledException (line 137, which here is the HttpClient timeout, not a disposal, since no token is passed), and a bare Exception (line 143) covering the staging write and the share sheet, because this runs in an OnClick callback where an unhandled exception is fatal to a native host (lines 145-147). The finally clears the guard (line 152).
  • ResolveStagedFileName (lines 167-176) reduces the caller's name to a bare file name with Path.GetFileName and rejects . and .. (lines 169-175), returning null when nothing usable remains. The remarks (lines 160-166) state the exact hazard: Path.Combine discards its first argument outright when the second is rooted, and .. segments walk out of the temp root, so an unsanitized name would decide where the delete and the write land.
  • StageFileAsync (lines 185-197) writes into Path.GetTempPath() under the already-sanitized name (line 187), deleting any leftover first (lines 189-192) so a truncated previous copy is never shared. It deliberately does not delete after sharing: on Android the share intent returns as soon as it launches, so deleting would race the receiving app (lines 179-184).
• Why it's built this way: the download mechanics are the part every consumer would otherwise re-implement per file type, and they are exactly the part that differs per head, so they belong in the framework behind a capability query (ADR-042). Keeping the wording out of the component (labels are parameters with localized fallbacks) is what lets one button serve a calendar file, an export, or a receipt without the framework knowing any of those words.
• Where it's used: ADC wraps it in a thin calendar affordance, MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.UI/Components/AddToCalendarButton.razor:8-17, which supplies ContentType="text/calendar", the calendar glyph, and its own localized aria-label and failure messages while the download and share mechanics stay here. Covered by ApiFileDownloadButtonTests.
• Caveats / not-in-source: the doc comment on AriaLabel (line 54) tags the icon-only accessible-name rule as "ADR-021", but ADR-021 in the current set is 021-consumer-inbox-idempotency; the accessibility contract the rule belongs to is ADR-063. Which apps a native share sheet offers for a given MIME type is OS behavior and not determinable from this source.

IApiSettings

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/IApiSettings.cs:6 · Level 0 · interface

• What it is: a two-property read-only view of the API configuration a UI host needs: the base URL it calls, and the base URL it hands to a browser.
• Depends on: nothing. Two string? getters and no using directives.
• Concept introduced, split-horizon endpoints. [Rubric §7, Microservices Readiness] (assesses whether a component copes with the topology it is deployed into rather than assuming one address space). A Blazor Web host and the browser it serves do not see the gateway the same way. ApiEndpoint (line 9) is what the server calls, which in production is a container-internal or service-discovery name that resolves nowhere in a browser. WasmApiEndpoint (lines 11-17) is the externally reachable URL served to the WebAssembly client through the /client-config endpoint. Splitting them lets the server take the faster internal path while the browser gets a name it can resolve, from one configuration section.
• Walkthrough: string? ApiEndpoint { get; } (line 9) and string? WasmApiEndpoint { get; } (line 17). Both are nullable, because the interface itself imposes no requirement; the [Required] rule lives on the implementation (ApiSettings).
• Why it's built this way: a read-only interface over an options class is the shape that lets a consumer state "I only read configuration" instead of taking a mutable settings object. It also documents the contract in one place while ApiSettings carries the binding and validation attributes.
• Where it's used: implemented by ApiSettings (Common/Settings/ApiSettings.cs:9). The two endpoint values are read through IOptions<ApiSettings> at the /client-config endpoints and in the API client factory, not through this interface.
• Caveats / not-in-source: no injection site resolves IApiSettings today: a repo-wide search finds the interface only at its declaration and on the ApiSettings class. The doc comment (line 15) says WasmApiEndpoint "falls back to ApiEndpoint when null", but neither host's /client-config endpoint actually does that today: both ADC and Store serve it through the shared MapClientConfigEndpoint (MMCA.Common.UI.Web), which throws an InvalidOperationException naming the missing key when WasmApiEndpoint is unset instead of substituting ApiEndpoint (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/ClientConfig/ClientConfigEndpointExtensions.cs:58-60, called from MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:265 and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:247). The fail-closed behavior is now framework policy shared by both hosts, not a per-host divergence, and the doc comment's fallback claim is stale.

InfiniteScrollSentinel

MMCA.Common.UI · MMCA.Common.UI.Components.Lists · MMCA.Common/Source/Presentation/MMCA.Common.UI/Components/Lists/InfiniteScrollSentinel.razor.cs:21 · Level 0 · class (partial component)

• What it is: a bottom-of-list marker that raises OnVisible when it scrolls near the viewport, so the hosting page can fetch and append its next page. It owns the IntersectionObserver and nothing else: the item markup, the fetch, and the accumulated list stay with the page.
• Depends on: IJSRuntime and the shared JS module _content/MMCA.Common.UI/infinite-scroll.js (wwwroot/infinite-scroll.js), DotNetObjectReference, ElementReference, and MudBlazor's MudProgressCircular in the markup. Nothing first-party; it is a sibling of MobileInfiniteScrollList<TItem>, which drives the same JS module.
• Concept introduced, the observer as a child component so disposal is correct. [Rubric §23, Front-End Performance] (assesses render and network cost: paging on demand instead of loading everything, and detaching observers so they stop costing anything), [Rubric §21, Accessibility] (assesses whether dynamic content changes are announced without hijacking focus) and [Rubric §18, UI Architecture]. The design point recorded in the doc comment (lines 14-19) is a lifecycle one: a page deriving from DataGridListPageBase<TDto> cannot hook async disposal because its DisposeAsync is not virtual, whereas a child component is disposed by the renderer the moment the host stops rendering it. Rendering the sentinel only while more pages exist therefore makes "detach the observer" a rendering decision rather than a bookkeeping one, and a filter reset that refills the list gets a fresh instance with a fresh observer.
• Walkthrough:
  • Parameters: OnVisible (line 26), IsLoading (line 29) which renders the inline progress row, and LoadingLabel (line 32), the localized accessible name for that row.
  • State (lines 34-44): a per-instance _observerId (a Guid "N" string, line 34), the _sentinelRef element reference, the imported _module, the _dotNetRef self-reference handed to JS, the _observing flag, _wasLoading (line 43, the previous render's IsLoading), and _disposed.
  • OnSentinelVisible() (lines 50-52) is the [JSInvokable] callback. Its name is fixed by the shared JS module, which calls it by string (lines 46-49). It returns immediately when disposed, otherwise marshals onto the renderer with InvokeAsync before invoking OnVisible.
  • OnAfterRenderAsync (lines 55-66) attaches the observer on the first render, and re-attaches it on the render where a load has just finished: loadJustFinished is _wasLoading && !IsLoading && _observing (line 57), _wasLoading is then updated (line 58), and either condition triggers AttachObserverAsync (line 60). The reason is recorded on the field (lines 40-42): an IntersectionObserver reports threshold crossings only, so a sentinel that is still inside the viewport when the appended page arrives would never fire again and the list would stall until the user scrolled away and back. Re-observing creates a fresh observer, which delivers a fresh initial entry.
  • AttachObserverAsync (lines 106-121) imports the module lazily (lines 110-111), creates the DotNetObjectReference once (line 112), calls observe with the reference, the element and the id (line 113), and sets _observing (line 114). A JSDisconnectedException is swallowed (lines 116-120): during prerendering or circuit teardown there is no JS to talk to, and the list simply stops at the pages already loaded rather than failing the render.
  • DisposeAsync (lines 69-104) suppresses finalization, guards re-entry with _disposed, calls unobserve when it was observing (lines 84-87), disposes the module (line 89), tolerates both JSDisconnectedException and JSException (lines 92-99), and disposes the DotNetObjectReference in a finally (line 102) so the .NET side is released even if the JS side already went away.
  • The markup (Components/InfiniteScrollSentinel.razor:4-13) is a single div carrying the element reference, with the progress row rendered only while IsLoading. That row is role="status" aria-live="polite" aria-busy="true" (line 9), matching PageLoadingState's politeness so a screen reader hears that more items are loading without the announcement interrupting reading.
  • The JS side is deliberately tiny: observe disconnects any prior observer for the id, creates an IntersectionObserver with rootMargin: '200px' and invokes OnSentinelVisible on intersection (wwwroot/infinite-scroll.js:3-14); unobserve disconnects and forgets the id (lines 16-22). The 200px margin is what makes the next page start loading slightly before the sentinel is on screen, and the disconnect-before-create step is what makes the post-load re-attach above safe to call repeatedly with the same id.
• Why it's built this way: extracting just the observer is what lets a page keep its own cards, empty state and error state and still get infinite scroll (lines 10-13). The alternative, folding the behavior into the list component, would force any page that wants infinite scroll to also adopt that component's layout.
• Where it's used: ADC's public speaker list renders it below the card grid while more pages exist, wiring OnVisible to its own loader and passing a localized loading label (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.UI/Pages/Public/Speakers/PublicSpeakerList.razor:144-145, inside PublicSpeakerList). Covered by InfiniteScrollSentinelTests.

LayoutSettings

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/LayoutSettings.cs:9 · Level 0 · class (sealed)

• What it is: the five settings that make the shared shell look and behave like a specific application: the navbar brand text, an optional brand logo URL, the footer text, an optional role gate on the framework-owned "signed-in devices" nav entry, and an opt-in switch that hides the framework's notification pages in a host that never registered the notification UI.
• Depends on: nothing first-party. System.Diagnostics.CodeAnalysis.SuppressMessage (BCL) for one analyzer waiver, and the Microsoft.Extensions.Options binder at registration time.
• Concept introduced, a settings section as a bound options class. [Rubric §17, DevOps & Deployment] (assesses whether configuration is centralized and typed rather than read ad hoc) and [Rubric §20, Design System and Theming] (assesses whether the look of the app is expressed once rather than repeated per page). The shape repeats across every settings class in this namespace: a public static readonly string SectionName naming the configuration section (line 12), init-only properties with compiled-in defaults, and one services.AddOptions<T>().Bind(configuration.GetSection(T.SectionName)) call in AddUIShared (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:48-49). Because every property has a default, an absent section is not an error: the host simply gets the compiled-in values. Components then take IOptions<LayoutSettings> and read .Value, so nothing in the shell parses configuration itself.
• Walkthrough:
  • SectionName = "Layout" (line 12).
  • BrandName (line 15) defaults to "MMCA". NavMenu renders it as the brand link's text and folds it into the link's localized accessible name (Layout/NavMenu.razor:18, :26).
  • FooterText (line 18) defaults to string.Empty, and MainLayout renders the footer block only when it is non-blank (Layout/MainLayout.razor:72-76). An empty default therefore means "no footer", not "an empty footer".
  • BrandLogoUrl (line 30) defaults to empty, which renders the text-only brand. When set, NavMenu emits an img beside the brand text with alt="" and aria-hidden="true" (Layout/NavMenu.razor:22-24): the image is decorative because the brand link already carries its own accessible name, so alt text here would only repeat it to a screen reader (lines 20-24). The property carries a [SuppressMessage] for CA1056 (lines 26-29) whose justification records why it is a string and not a Uri: the value is usually a host-relative path such as /img/logo.svg, which System.Uri cannot represent without RelativeOrAbsolute round-tripping.
  • SessionsNavRequiredRole (line 39) is nullable and unset by default, which shows the "signed-in devices" nav entry to every signed-in user. NavMenu reads it in OnInitializedAsync and computes _showSessionsLink as unset-or-blank OR the current user is in that role (Layout/NavMenu.razor:214-215). The gate covers only the menu entry: /profile/sessions itself stays reachable for any signed-in account whether or not the link is shown (Layout/NavMenu.razor:78-82).
  • HideNotificationPagesWhenUnregistered (line 49) defaults to false, which leaves the routes exactly as they are. When true, the framework's notification pages (/notifications, /notifications/inbox, /notifications/inbox/{Id} and /notifications/send) answer with the not-found page in a host that never called AddNotificationUI(), instead of being reachable by URL with none of the services they need (lines 41-48). The decision is NotificationPageGate.Hides, which requires the flag, a page type in its notification set, and no registered NotificationUIModule (MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationPageGate.cs:22-31), so a host that registers the notification UI is unaffected either way.
• Why it's built this way: the shell ships in the framework package, so the only way a consuming app can brand it, narrow a framework-owned menu entry, or close framework-owned routes it does not use, without forking is configuration. Keeping the branding in appsettings.json also means a deployment can rebrand without a rebuild.
• Where it's used: injected as IOptions<LayoutSettings> by Layout/NavMenu.razor:12 and Layout/MainLayout.razor:11, and read by NotificationPageGate (Notifications/NotificationPageGate.cs:22). Configured by every UI host, for example MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/appsettings.json:15-18. Covered by NavMenuTests and NotificationPageGateTests.

LegalSettings

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/LegalSettings.cs:16 · Level 0 · class (sealed)

• What it is: the four legal-document URLs a host can publish (Terms of Service, Privacy Policy, Code of Conduct, and the page explaining how to delete an account), plus a computed flag saying whether any footer document is configured. Every URL defaults to empty, which means "not configured" and hides the link it drives.
• Depends on: nothing first-party. System.Diagnostics.CodeAnalysis.SuppressMessage (BCL) for the CA1056 waivers, and the Microsoft.Extensions.Options binder at registration time.
• Concept introduced, an empty default as the off switch. [Rubric §17, DevOps & Deployment] (assesses whether configuration is centralized and typed rather than read ad hoc). It follows the same bound-options shape as LayoutSettings: a public static readonly string SectionName = "Legal" (line 22) and init-only properties with compiled-in defaults. Here the default doubles as the feature toggle: an unset URL is string.Empty, and each consumer tests string.IsNullOrWhiteSpace before rendering a link, so a host opts into each document by configuring it and a host that configures nothing sees no legal UI at all. The section is optional for the same reason; ADR-070 (fail-fast configuration contract) is the reference for which settings must be present and which, like this one, may be absent.
• Walkthrough:
  • TermsUrl (line 26), PrivacyUrl (line 30) and CodeOfConductUrl (line 34) are string properties defaulting to string.Empty. The doc comment on TermsUrl states the double effect: empty hides both the footer link and the registration checkbox (line 24).
  • DeleteAccountUrl (line 41) is the page that explains how to delete an account, which app stores require for apps that offer sign-up (lines 36-39). It is deliberately outside the footer group.
  • Each URL carries a [SuppressMessage] for CA1056 (lines 25, 29, 33, 40) sharing one UrlJustification constant (lines 18-19): the value is bound from configuration and emitted straight into an href, and the empty default is not a valid System.Uri, the same precedent as LayoutSettings.BrandLogoUrl.
  • HasFooterLinks (lines 44-47) is true when any of the three footer documents (Terms, Privacy, Code of Conduct) is non-blank. DeleteAccountUrl is not part of it.
• Why it's built this way: the shared shell and the register page ship in the framework package, so the only way an app can publish its own legal documents without forking is configuration. Computing HasFooterLinks once on the settings class keeps the "is there anything to show" decision out of every markup file.
• Where it's used: bound by services.AddOptions<LegalSettings>().Bind(...) in MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:53-54. Layout/MainLayout.razor injects it (line 13), renders the footer when footer text or HasFooterLinks is present (line 87), and emits one ExternalLink per configured document (lines 104-114). Components/Legal/TermsAcceptanceGate.razor.cs reads it through IOptions<LegalSettings> (lines 70, 78) and the gate markup checks Legal.HasFooterLinks (TermsAcceptanceGate.razor:17). Pages/Auth/Register.razor injects it (line 17) and shows the Terms checkbox only when a Terms URL is configured (line 143; Pages/Auth/RegisterModel.cs:46). ADC's LegalAndDataCard.razor.cs on the profile page reads it too. Covered by MainLayoutFooterTests and RegisterTermsTests in MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests.

MmcaClientConfigBootstrap

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/MmcaClientConfigBootstrap.cs:28 · Level 2 · class (static)

• What it is: the WebAssembly client's bootstrap-time fetch of the client-config document (served by ClientConfigEndpointExtensions.MapClientConfigEndpoint) into a stream AddJsonStream can consume, with one automatic retry on failure or timeout, and with a same-origin API proxy path resolved to an absolute address on the way through.
• Depends on: ApiSettings, used only for its SectionName and the SameOriginApiEndpoint property name when rewriting the document; otherwise System.Net.Http.HttpClient, System.Text.Json.Nodes and System.Text.Encoding (BCL). Nothing it touches needs a service provider, which is deliberate, since it runs before builder.Services exists.
• Concept introduced, a bounded retry at the one point in startup where configuration itself is still unknown. [Rubric §29, Resilience, Reliability & Business Continuity] (assesses whether a single transient failure at startup is survivable) and [Rubric §17, DevOps & Deployment]. Every other resilience mechanism in the framework (Polly pipelines, the outbox, internal commands) runs once DI and configuration exist; this runs before both, in Program.cs, fetching the very document that will configure the rest of the client. A Polly-based retry is unavailable at this point (no service provider yet), so the retry is hand-rolled: one attempt, then one retry after a fixed delay, with the caller's own HttpClient and its own Timeout.
• Walkthrough:
  • ClientConfigPath = "client-config" (line 31), the relative path both overloads fetch, matching the endpoint's own route.
  • DefaultTimeout (line 34, 15 seconds) and DefaultRetryDelay (line 37, 1 second) are the defaults the single-argument overload uses.
  • LoadAsync(Uri baseAddress, CancellationToken) (lines 49-60) is the convenience overload: it builds a short-lived HttpClient scoped to baseAddress with DefaultTimeout, then delegates to the caller-owned overload. It carries an RS0027 [SuppressMessage] (line 48) whose justification records it as a grandfathered public overload whose signature cannot change without a breaking change.
  • LoadAsync(HttpClient client, TimeSpan retryDelay, CancellationToken) (lines 72-90) is the real logic: fetch the bytes (line 81), and on HttpRequestException or a caller-uncancelled timeout (IsTimeout, lines 83, 142-143) wait retryDelay then fetch once more (lines 85-86) with no further retry. IsTimeout (lines 142-143) is the detail that makes the retry precise: HttpClient reports its own per-request timeout as TaskCanceledException, the same exception type the caller's own cancellation produces, so the two are told apart by checking whether the caller's token was the one that fired; only a timeout the caller did not ask for is retried.
  • The result passes through ResolveSameOriginApiEndpoint against the client's BaseAddress and is wrapped in a non-writable MemoryStream (line 89), the shape AddJsonStream expects.
  • ResolveSameOriginApiEndpoint(byte[], Uri?) (lines 98-128, internal) exists because a host running the same-origin API proxy serves Api:SameOriginApiEndpoint as an origin-relative path (the server cannot know the public origin a browser used behind ingress) while the "APIClient" needs an absolute base address (lines 92-97). It returns the document byte for byte unless every precondition holds: an absolute base address (line 100), a document that parses (a JsonException is left for configuration binding to report, lines 110-114), an Api object holding a non-blank string SameOriginApiEndpoint that is not already an http(s) URL (lines 116-124). Only then does it replace the value with new Uri(baseAddress, path).AbsoluteUri and re-serialize (lines 126-127). Parsing is case-insensitive on property names (line 108).
  • IsHttpAbsolute(string) (lines 136-138, internal) accepts only an absolute http or https URI. A bare absolute-Uri.TryCreate check is not enough: on Unix-like runtimes, browser WebAssembly included, "/api/" parses as the absolute file:///api/, so the relative path would be left unresolved and every client call would go to file:///api/... (lines 130-135).
• Why it's built this way: a single flaky fetch (a cold container, a brief network blip during a rollout) would otherwise fail the entire WASM client boot before it can render anything, including an error page with any styling. One retry buys resilience against exactly that class of transient failure without turning a genuine outage into a long hang, since both attempts still respect DefaultTimeout. Resolving the proxy path here rather than on the server keeps the server ignorant of the browser-facing origin, and doing it on the raw document means every later consumer of ApiSettings on the client sees an absolute address (ADR-131).
• Where it's used: MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web.Client/Program.cs calls LoadAsync to populate the WASM client's configuration before any service is registered. The endpoint it fetches from is ClientConfigEndpointExtensions (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/ClientConfig/ClientConfigEndpointExtensions.cs). Covered by MmcaClientConfigBootstrapTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Common/Settings/MmcaClientConfigBootstrapTests.cs) and SameOriginProxyClientTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Services/SameOriginProxyClientTests.cs).
• Caveats / not-in-source: only one retry is ever attempted regardless of how the second attempt fails; a second transient failure fails the boot outright.

NotificationBellOptions

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/NotificationBellOptions.cs:12 · Level 0 · class (sealed)

• What it is: the two numbers that define how stale the unread-notification badge is allowed to be: how often it re-reads the API, and how old its count may be before a navigation re-reads it.
• Depends on: nothing first-party. TimeSpan (BCL). Bound with the same options shape LayoutSettings introduces.
• Concept introduced, staleness as a stated policy. [Rubric §19, State Management] (assesses whether client-side state has an explicit freshness contract) and [Rubric §31, Cost and FinOps] (assesses whether the design lets an operator trade money against latency). Both numbers are host decisions rather than compiled constants: a deployment paying per API call widens the poll, one where an unread count must feel instant narrows it (lines 6-10). The framing in the doc comment is important for reading the code: the periodic read is the backstop behind the real-time push, not the primary path, so PollInterval is the budget for "how long a missed push may go unnoticed" (lines 17-22).
• Walkthrough:
  • SectionName = "NotificationBell" (line 15).
  • PollInterval (line 23), default 30 seconds. NotificationBell builds its PeriodicTimer from it (Components/Notifications/NotificationBell.razor.cs:103), against the injected clock rather than the ambient one. Zero or a negative value disables periodic polling while the push refresh and the navigation refresh keep working (lines 20-21): the bell returns before creating the timer when PollInterval <= TimeSpan.Zero (NotificationBell.razor.cs:96-99), because PeriodicTimer rejects such a period and throwing there faulted the circuit (lines 94-95).
  • NavigationRefreshMaxAge (line 30), default 30 seconds. On a page change the bell accepts the count it already holds unless it is older than this window (NotificationBell.razor.cs:166, via State.IsStale(...)). That is what keeps a user clicking through five pages in ten seconds from issuing five reads of a number that has not moved (lines 25-29).
• Why it's built this way: both values are pure policy with no correct universal answer, so they belong in configuration; and because both have defaults, a host that says nothing keeps the framework's chosen 30-second budgets.
• Where it's used: bound in AddUIShared (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:66-67) and injected as IOptions<NotificationBellOptions> by NotificationBell (Components/Notifications/NotificationBell.razor.cs:36). Covered indirectly by NotificationBellTests.

QrErrorCorrectionLevel

MMCA.Common.UI · MMCA.Common.UI.Components.Sharing · MMCA.Common/Source/Presentation/MMCA.Common.UI/Components/Sharing/QrErrorCorrectionLevel.cs:9 · Level 0 · enum

• What it is: the four QR error-correction strengths the framework's QR components expose. Higher levels survive more damage or occlusion but pack fewer characters into the same module count, so the code grows denser (lines 4-5).
• Depends on: nothing. It is a bare enum with no using directives.
• Concept introduced, a framework-owned enum instead of a re-exported vendor type. [Rubric §9, API and Contract Design] (assesses whether a public surface is expressed in types the owner controls) and [Rubric §32, Dependency and Supply-Chain] (assesses whether third-party types leak into contracts consumers must compile against). The doc comment states the decision outright (lines 6-7): declaring this rather than exposing QRCoder's own ECCLevel keeps the component's public API from pinning consumers to the encoder package. The mapping to the vendor type is a private detail of the component, a one-line switch in Components/QrCodeImage.razor:77-82, so replacing the encoder would not be a breaking change for any page that names this enum.
• Walkthrough: four members with explicit values and a stated recovery budget each: Low = 0 (line 12, about 7% recovery, densest code, short payloads on clean screens), Medium = 1 (line 15, about 15%, the usual screen and print trade-off), Quartile = 2 (line 18, about 25%, printed sheets that may get scuffed) and High = 3 (line 21, about 30%, codes overlaid with a logo or scanned in poor light). The explicit values matter because the enum is bound as a component parameter and compared for change detection.
• Why it's built this way: the recovery percentages are properties of the QR standard, not of the encoder, so documenting them on a framework enum keeps the decision (how much damage must this code survive?) at the call site where the physical context is known.
• Where it's used: QrCodeImage takes it as a parameter defaulting to Medium (Components/QrCodeImage.razor:36) and maps it to QRCodeGenerator.ECCLevel before encoding (:77-82); QrCodeButton defaults to Quartile (Components/QrCodeButton.razor:65). ADC passes Medium explicitly on the attendee badge (MMCA.ADC/Source/Modules/Engagement/MMCA.ADC.Engagement.UI/Pages/CheckIns/MyBadge.razor:36) and the speaker QR page (MMCA.ADC/Source/Modules/Conference/MMCA.ADC.Conference.UI/Pages/Speakers/SpeakerQr.razor:29). Covered by QrCodeImageTests.

RatingStars

MMCA.Common.UI · MMCA.Common.UI.Components.Ratings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Components/Ratings/RatingStars.razor.cs:13 · Level 0 · class (partial component)

• What it is: a five-icon star rating display over a double value on a 0-5 scale, rendering full, half, or empty stars per position.
• Depends on: MudBlazor's Size enum and Icons.Material.Filled.{Star,StarHalf,StarBorder}. Nothing first-party.
• Concept introduced, a pure display component with no state of its own. [Rubric §18, UI Architecture] (assesses whether a component's responsibility is genuinely narrow) and [Rubric §21, Accessibility] (assesses whether a visual-only rendering carries an equivalent text alternative). Unlike an editable star-rating input, this component only renders: it has no click handler and no two-way binding, so the same Value always paints the same five icons regardless of interaction history. The single required AriaLabel parameter is what keeps the rating accessible to a screen reader, which otherwise would see five decorative icons and no number.
• Walkthrough:
  • MaxValue = 5 (line 115) is the fixed scale; the markup renders exactly that many icons regardless of Value.
  • Value (line 127) is a double on the 0-MaxValue scale. The doc comment (lines 121-125) states the intended caller pattern explicitly: a caller holding a decimal average casts it to double, because the half-star threshold this component applies needs no decimal precision.
  • AriaLabel (lines 130-132) is [EditorRequired], so the compiler enforces that every usage supplies the accessible name for the whole rating; there is no per-star label.
  • Size (line 136) defaults to Size.Small.
  • FillFor(int star) (lines 145-153) is the per-position logic: a star index at or below Value is FullStar; otherwise it is HalfStar when Value is within half a star of that position (Value >= star - 0.5), else EmptyStar. IconFor(string fill) (lines 138-143) maps those three string constants to the three MudBlazor icon glyphs through a switch, defaulting to the empty-star border icon for any other value.
• Why it's built this way: three private string constants (FullStar/HalfStar/EmptyStar) rather than an enum keep the fill/icon mapping a two-function, easily-read pair; the component stays a pure function of Value with no fields to maintain across renders.
• Where it's used: exercised directly by RatingStarsTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Components/Ratings/RatingStarsTests.cs) and by 4 further call sites in Store's Catalog UI rendering Product.RatingSummary on catalog and product-detail pages.
• Caveats / not-in-source: the exact call sites beyond the test project were not opened for this section (the brief lists "5" and "and 4 more"); which pages render it is not itemized here.

RegistrationSettings

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/RegistrationSettings.cs:8 · Level 0 · class (sealed)

• What it is: a one-property settings class that lets a host turn the register page's optional postal-address block on or off.
• Depends on: nothing first-party. The Microsoft.Extensions.Options binder at registration time.
• Concept introduced, a feature switch that defaults to the framework's existing behavior. [Rubric §17, DevOps & Deployment] (assesses whether configuration is centralized and typed rather than read ad hoc). CollectAddress defaults to true (line 18), so a host that never configures the Registration section (SectionName, line 11) keeps the address block it always had; only a host that sets false changes anything. ADR-070 (fail-fast configuration contract) covers why an absent optional section is not an error.
• Walkthrough: CollectAddress (line 18, get; set;) is the only member. true shows the optional address block; false hides it and the registration request carries no address (lines 13-17).
• Why it's built this way: not every deployment wants to ask for a postal address at sign-up, and the register page is framework-owned, so configuration is the only way a consuming app can drop the block without forking the page.
• Where it's used: bound in MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:58-59. Pages/Auth/Register.razor injects IOptions<RegistrationSettings> (line 18) and wraps the address block in @if (CollectAddress) (line 107); Pages/Auth/Register.razor.cs exposes CollectAddress from the options (line 13) and branches on it at line 24. Covered by RegisterAddressOptionTests in MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Auth.

UIModuleConfiguration

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/UIModuleConfiguration.cs:10 · Level 0 · class (static)

• What it is: a one-method helper that answers "is this UI module enabled in this host?" by reading Modules:{moduleName}:Enabled from configuration, defaulting to enabled when nothing is configured.
• Depends on: Microsoft.Extensions.Configuration.IConfiguration (GetSection, Exists, GetValue). Nothing first-party, which is what lets a host call it before any DI registration has happened.
• Concept introduced, composing a UI host from configuration. [Rubric §7, Microservices Readiness] (assesses whether the same codebase can be deployed as different subsets) and [Rubric §17, DevOps & Deployment]. The server-side module system registers IModule implementations in topological order; the UI side has its own analogue, IUIModule, registered by each module's AddXUI() extension (ADR-067). This helper is the gate in front of those calls: a host that switches a module off never calls AddXUI(), so no IUIModule descriptor is registered, and the shell composes without that module's routes, nav entries or services. The default-on behavior (lines 7-8) is a compatibility choice: a host with no Modules section behaves exactly as it did before the section existed.
• Walkthrough: ModulesSectionName = "Modules" (line 12) and IsModuleEnabled(IConfiguration configuration, string moduleName) (lines 18-22). It walks two section levels, Modules then the module name (line 20), and returns !section.Exists() || section.GetValue("Enabled", true) (line 21). Read carefully, that is two independent defaults: an absent module entry is enabled, and a present entry missing the Enabled key is also enabled. Only an explicit false turns a module off.
• Why it's built this way: a static helper over IConfiguration (rather than a bound options class) is what makes it usable at the exact point it is needed, inside Program.cs/MauiProgram.cs before the service provider exists. Keeping the check in the framework rather than hand-rolling builder.Configuration["Modules:X:Enabled"] per host is what keeps the default-on semantics identical across all six heads.
• Where it's used: all six UI hosts gate their module registrations with it. ADC: MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:167-177, MMCA.ADC.UI.Web.Client/Program.cs:55-64, MMCA.ADC.UI/MauiProgram.cs:129-138 (Identity, Conference, Engagement, Notification). Store: MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:120-126, MMCA.Store.UI.Web.Client/Program.cs:51-57, MMCA.Store.UI/MauiProgram.cs:83-89 (Catalog, Sales, Identity). The corresponding configuration block is MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/appsettings.json:9-14.

UiReadCacheOptions

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/UiReadCacheOptions.cs:13 · Level 0 · class (sealed)

• What it is: the client-side staleness policy for IUiReadCache: a master on/off switch, a default freshness budget, and per-route-prefix overrides.
• Depends on: nothing first-party. TimeSpan and Dictionary<string, TimeSpan> (BCL), plus the options binder at registration.
• Concept introduced, client-side freshness as a recorded decision. [Rubric §19, State Management] (assesses whether cached client state has an explicit lifetime), [Rubric §12, Performance and Scalability] and [Rubric §31, Cost and FinOps]. The doc comment states the intent precisely (lines 6-11): the point of writing staleness into configuration is that it becomes a decision a host records, rather than an accident of how often a component happens to re-render. This is the client-side analogue of the server caching strategy (ADR-026) applied to the entity data-access contract (ADR-094).
• Walkthrough:
  • SectionName = "UiReadCache" (line 16).
  • Enabled (line 24), default true. Setting it false turns every lookup into a miss and every store into a no-op (lines 19-22), so the services behave exactly as they would with no cache registered. The cache honors it on both paths (Services/Caching/UiReadCache.cs:36, :74), which is the framework's escape hatch for a host that wants no client-side staleness at all.
  • DefaultTtl (line 32), default 60 seconds, applied to any read whose URL matches no configured prefix. The comment records the reasoning for the number (lines 27-31): short enough that a stale list corrects itself within one user's attention span, long enough to collapse the burst of identical reads a page issues while it mounts.
  • RoutePrefixTtls (line 41), a getter-only Dictionary<string, TimeSpan> keyed by the leading part of a relative URL (for example countries). Getter-only is deliberate: the configuration binder populates the instance the defaults created, which is how bindable collections are shaped across this namespace (lines 37-39). The longest matching prefix wins, so a specific child route can state a stricter budget than the endpoint above it whatever order configuration enumerates in; that resolution is implemented in UiReadCache.ResolveTtl (Services/Caching/UiReadCache.cs:120-135).
• Why it's built this way: a single global TTL would force one budget on reference data that changes hourly and on lists that change constantly, so the per-prefix table is what makes one cache usable for both. Longest-match rather than first-match removes any dependence on configuration ordering, which JSON does not guarantee.
• Where it's used: bound in AddUIShared (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:63-64) and injected into UiReadCache (Services/Caching/UiReadCache.cs:18, snapshotted to a field at :27). Covered by UiReadCacheTests.

WebApplicationExtensions

MMCA.Common.UI · MMCA.Common.UI.Extensions · MMCA.Common/Source/Presentation/MMCA.Common.UI/Extensions/WebApplicationExtensions.cs:8 · Level 0 · class (static)

• What it is: a one-method middleware extension for Blazor Server / WASM hybrid hosts. UseAuthenticatedNoStore() emits Cache-Control: no-store on HTML responses to authenticated users, so a logged-out user pressing Back never sees the previous logged-in HTML.
• Depends on: Microsoft.AspNetCore.Builder.IApplicationBuilder, HttpContext.User, and HttpResponse.OnStarting (ASP.NET Core). Nothing first-party.
• Concept introduced, the browser back-forward cache (bfcache) as an auth-leak boundary. [Rubric §26, Front-End Security] (assesses whether the front end avoids leaking authenticated content and treats the browser as hostile storage) and [Rubric §23, Front-End Performance] (assesses render and navigation cost; bfcache is a performance feature this deliberately gives up, but only where it is unsafe). A browser's bfcache restores a full DOM snapshot of a previous page on Back without issuing a request, so no server authorization check runs. Emitting no-store on a response makes that page bfcache-ineligible: Back re-requests it and the server re-renders under the current (possibly signed-out) identity. The scoping is the interesting part: anonymous pages keep their bfcache eligibility because the guard is context.User.Identity?.IsAuthenticated is true (line 30), and non-HTML responses (JSON, static assets, the Blazor framework files) are skipped by the text/html content-type check (lines 31-32), so nothing but authenticated pages pays the cost.
• Walkthrough: a static class holding a single C# extension(IApplicationBuilder app) block (line 10), the same extension(T) preview syntax the framework uses for DI registration (see primer).
  • UseAuthenticatedNoStore() (lines 24-44) registers an inline app.Use((context, next) => ...) middleware (line 26).
  • It does not inspect the response at request time: it hooks context.Response.OnStarting (line 28), the callback the server invokes just before the first byte of the response is written. That is what makes reading context.User and context.Response.ContentType meaningful, both are populated by then even though this middleware sits ahead of the authentication middleware in the pipeline.
  • When both conditions hold it sets Cache-Control: no-store, no-cache, must-revalidate, max-age=0 plus the HTTP/1.0-era Pragma: no-cache (lines 34-35), then returns Task.CompletedTask (line 37).
  • The middleware returns next() immediately (line 40), and the extension returns app (line 43) so it chains in the usual app.UseX().UseY() shape.
• Why it's built this way: an IApplicationBuilder extension is the idiomatic ASP.NET Core registration shape, and the OnStarting hook is what allows a single narrow registration to make an after-the-fact decision (was this response authenticated? was it HTML?) instead of duplicating the check at every page. The remarks (lines 19-23) state the one ordering constraint: register it before MapRazorComponents so it wraps every page response.
• Where it's used: both Blazor Web hosts call it once: MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:245 and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:171.
• Caveats / not-in-source: whether a given browser honors no-store as bfcache-ineligibility is browser behavior, not code, and cannot be verified from this source. This type is distinct from the same-named WebApplicationExtensions in the API layer; they share a name across assemblies, not an implementation.

ApiSettings

MMCA.Common.UI · MMCA.Common.UI.Common.Settings · MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/ApiSettings.cs:9 · Level 1 · class (sealed)

• What it is: the bound implementation of IApiSettings: the "Api" configuration section, validated at startup so a host with no API endpoint fails immediately instead of at the first request.
• Depends on: IApiSettings (the read-only contract it implements) and System.ComponentModel.DataAnnotations.RequiredAttribute (BCL).
• Concept introduced, fail-fast configuration. [Rubric §29, Resilience, Reliability & Business Continuity] and [Rubric §15, Best Practices and Code Quality]. The class is three properties of data, but the behavior lives in how it is registered: AddOptions<ApiSettings>().Bind(...).ValidateDataAnnotations().ValidateOnStart() (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:42-45). ValidateDataAnnotations turns the [Required] attribute into an options validator, and ValidateOnStart runs that validator during host startup rather than lazily on first resolution, so a missing Api:ApiEndpoint surfaces as an OptionsValidationException naming the key before the host accepts traffic (ADR-070). That is what licenses the null-forgiving apiSettings.ApiEndpoint! in the client factory (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:133-136): the validator, not a local check, is the guarantee.
• Walkthrough:
  • SectionName = "Api" (line 12), the same convention every settings class here uses.
  • [Required] public string? ApiEndpoint { get; init; } (lines 15-16). Nullable so the binder can leave it unset, [Required] so leaving it unset fails validation. init-only, so a bound instance is immutable after construction.
  • WasmApiEndpoint { get; init; } (line 19) carries <inheritdoc /> and no [Required]: it is optional at the contract level, and each host decides whether an absent value is acceptable.
  • SameOriginApiEndpoint { get; init; } (line 33) is declared on the class only, not on IApiSettings, and is null everywhere except on a WebAssembly client whose Server host opted in with AddCommonSameOriginApiProxy (lines 21-32). The host serves it as an origin-relative path in /client-config and MmcaClientConfigBootstrap.LoadAsync resolves it to an absolute address. When it is set, the "APIClient" and the notification hub target it instead of ApiEndpoint, send no Authorization header (the proxy attaches the bearer from the HttpOnly session cookie server-side) and add the proxy's CSRF header; ApiEndpoint keeps the gateway URL for full-page navigations that must reach the gateway itself, such as the external sign-in challenge (ADR-131). In the client factory the switch is client.BaseAddress = new Uri(apiSettings.SameOriginApiEndpoint ?? apiSettings.ApiEndpoint!, ...) (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:136), and the same configuration key decides at registration time whether the proxy pipeline is wired at all (DependencyInjection.cs:117-121).
• Why it's built this way: sealed plus init gives an immutable snapshot of configuration that cannot drift while the app runs. Putting the validation attribute on the options class rather than writing a guard in the HttpClient factory keeps one failure mode with one message: the comment at MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:126-130 records that a second hand-written check would only give the same failure a different, less informative exception.
• Where it's used: bound in AddUIShared (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:42-45); read by the named "APIClient" HttpClient factory to set BaseAddress (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:124-136, alongside the 90-second total-request timeout at :120); read by ApiFileDownloadButton for its browser download URL (Components/Forms/ApiFileDownloadButton.razor.cs:98); read by NotificationHubService and BlazorCspPolicyProvider; and served to the WebAssembly client by each Server head's /client-config endpoint, both routed through the shared MapClientConfigEndpoint (MMCA.Common/Source/Presentation/MMCA.Common.UI.Web/ClientConfig/ClientConfigEndpointExtensions.cs:52-61; called at MMCA.ADC/Source/Hosts/UI/MMCA.ADC.UI.Web/Program.cs:265-281 and MMCA.Store/Source/Hosts/UI/MMCA.Store.UI.Web/Program.cs:247).

MobileInfiniteScrollList<TItem>

MMCA.Common.UI · MMCA.Common.UI.Components.Lists · MMCA.Common/Source/Presentation/MMCA.Common.UI/Components/Lists/MobileInfiniteScrollList.razor.cs:20 · Level 3 · class (generic partial component)

• What it is: the mobile card list every list page falls back to on a narrow viewport. It owns the whole loop: an IntersectionObserver sentinel that asks for the next page, an accumulated item list rendered through a caller-supplied card template, a rendered-item cap that bounds DOM growth, generation-guarded supersession of in-flight fetches, and localized load-failure handling with a Retry button.
• Depends on: Result and its generic form (the fetch delegate's return type), SharedResource through IStringLocalizer<SharedResource>, ResultUiExtensions.LocalizedErrorMessage, the EmptyState component, the ClickableCard component each row's card is wrapped in, and the shared _content/MMCA.Common.UI/infinite-scroll.js module it shares with InfiniteScrollSentinel. Externals: IJSRuntime, DotNetObjectReference, CancellationTokenSource, MudBlazor primitives.
• Concept introduced, generation-guarded supersession. [Rubric §19, State Management] (assesses whether concurrent updates to client state have a defined winner) and [Rubric §23, Front-End Performance]. The hard problem in an infinite list is not fetching, it is what happens when the user changes the filter while a fetch is in flight. Cancellation alone is not enough: the fetch delegate is consumer-supplied and may ignore its CancellationToken entirely, so a superseded call can still complete successfully and try to append rows to a list that was cleared. The answer here is a monotonically increasing _generation counter (line 62). A load snapshots it before awaiting and discards its results if the value moved while it waited (lines 181-183, 199). The token cancellation is still issued (it stops work that does honor it), but the generation, not the token, is authoritative (lines 196-198). The second half of the pattern is that the page counter is computed, not committed: targetPage = _currentPage + 1 (line 190) and _currentPage only advances on a successful, non-superseded completion (line 214), so a cancelled, failed or superseded fetch leaves nothing to compensate back and no page is ever re-requested (lines 187-189).
• Walkthrough:
  • Injected services (lines 22-23: IJSRuntime and the localizer, no toast service) and parameters (lines 25-52). CardTemplate is an [EditorRequired] RenderFragment<TItem> (line 27). FetchPageResult (line 37), also [EditorRequired], is the fetch delegate in the shape every Result-returning UI service already has, (page, pageSize, cancellationToken) returning Result<(IReadOnlyList<TItem> Items, int TotalItems)>, which is IEntityService<TEntityDTO, TIdentifierType>.GetPagedAsync minus the filter and sort arguments. PageSize defaults to 10 (line 39), MaxRenderedItems to 500 (line 52).
  • State (lines 54-87): _items, _totalCount, _currentPage, _generation, the four render flags (_isInitialLoad, _isLoadingMore, _hasMore, _loadError), _loadErrorMessage, the interop handles (_sentinelRef, _jsModule, _dotNetRef, _observerId, _cts, _observerAttached), _reobservePending (line 86) and _disposed.
  • OnInitializedAsync (lines 89-95) validates the delegate then loads page 1. ValidateFetchParameter (lines 102-109) throws an InvalidOperationException when FetchPageResult is null, deliberately before the load, so a misconfigured call site fails loudly instead of rendering as a load failure with a Retry button that can never succeed (lines 97-101).
  • OnAfterRenderAsync (lines 111-120) consumes and clears _reobservePending (lines 113-114), then attaches the observer only while more pages exist, there are items to scroll past and the initial load is done, either when none is attached yet or when a re-observe was queued (line 116). AttachObserverAsync (lines 122-136) and DetachObserverAsync (lines 138-153) import and call the same observe/unobserve module functions the sentinel component uses, tolerating JSDisconnectedException on both paths.
  • OnSentinelVisible() (lines 155-168), the [JSInvokable] entry point, early-returns when already loading, exhausted or disposed (lines 158-161), then loads on the renderer's context and re-renders.
  • LoadNextPageAsync(bool isInitial) (lines 170-252) is the core. It guards re-entry (lines 172-175), clears the error state (lines 178-179), snapshots the generation and publishes a fresh CancellationTokenSource (lines 183-185), computes targetPage (line 190), and awaits the delegate (line 194). After the await it checks disposal and generation (line 199), unwraps the Result with TryGetValue and routes a failure to SetLoadFailed (lines 204-210), and only then commits: advance the page (line 214), append the items through AppendNew and keep the count of new rows (line 216), record the total (line 217), set _hasMore from HasMoreAfter(appended) (line 218), which is where the DOM cap and the empty-append guard stop the loop, and call MarkReobserveAfterAppend(isInitial) (line 220). OperationCanceledException is swallowed as a normal supersession (lines 222-225); any other exception raises the generic failure, again only for the current generation (lines 226-234). The finally (lines 235-251) is careful about ownership: only the current generation may clear _isLoadingMore (a superseding reset already cleared it and may have set it again), and only the still-current CancellationTokenSource is disposed here (ReferenceEquals, line 244), because a resetter that took one over already cancelled and disposed it.
  • AppendNew(IEnumerable<TItem> items) (lines 260-268) appends only the rows not already shown and returns how many were new. Offset paging plus an insert ahead of the window can repeat a row across pages, and rows are keyed by value (@key="item"), so a repeat would be two siblings with one key and a render error (lines 254-259). It filters lazily with _items.Contains while adding (lines 264-265), so a row repeated inside the same page is caught too; records compare by value, the same equality @key uses. HasMoreAfter(int appended) (lines 276-277) is appended > 0 && _items.Count < _totalCount && _items.Count < MaxRenderedItems: besides the rendered-item cap it stops when a page added nothing new (an empty page, or a window shifted by a whole page), so the re-observed sentinel cannot re-request the same page forever; ResetAsync starts over (lines 270-275).
  • MarkReobserveAfterAppend(bool isInitial) (lines 283-289) sets _reobservePending after a non-initial append that left more pages. The IntersectionObserver reports threshold crossings only, so a sentinel still inside the viewport after the append would never fire again; re-observing creates a fresh observer, which delivers an initial entry with the current state (lines 83-85). This is the same stall InfiniteScrollSentinel guards against with its post-load re-attach.
  • SetLoadFailed(Result? failure) (lines 301-305) sets the inline error state and nothing else: no toast is raised, because the inline alert is announced on its own, rendered in place of the list for a failed first page or below it for a later page (lines 291-294). The message comes from failure?.LocalizedErrorMessage(L) (line 304); a raw exception passes null, because exception text is neither translatable nor safe to surface (lines 295-299), and the generic resource string is used instead.
  • CardCallback(TItem item) (lines 314-317), declared between SetLoadFailed and RetryAsync, binds one row's click behavior for the markup below. When OnCardClick has a delegate it returns an EventCallback.Factory.Create wrapping the invoke; when it does not, it returns default, deliberately not EventCallback.Empty, because EventCallback.Empty wraps a no-op Action so its HasDelegate is still true and every card would present as interactive. default is the only value ClickableCard reads as "no handler wired", which is what lets it render a plain, non-focusable card instead of a keyboard control that does nothing (lines 307-313).
  • ResetAsync() (lines 329-365) is the public API a page calls when filters change. Order matters and is commented: bump the generation first so any in-flight fetch is already superseded (line 333), then cancel and dispose the stale token source (lines 335-342), then clear _isLoadingMore explicitly (lines 344-347, because the superseded load will not clear it), then reset the list and every flag (lines 349-355), detach the observer (lines 357-358), and reload from page 1 (lines 360-364).
  • DisposeAsync (lines 367-399) guards re-entry, cancels and disposes the token source, detaches the observer, disposes the JS module tolerating JSDisconnectedException, and disposes the DotNetObjectReference.
  • The markup (Components/Lists/MobileInfiniteScrollList.razor:1-64) renders one of four shapes: an indeterminate progress bar inside a role="status" live region on the initial load (lines 5-14), the load-failure alert when the first page itself failed (lines 15-20, because a failed first page is not an empty list), EmptyState when the list came back empty (lines 21-24), or a MudStack of ClickableCard wrappers around the caller's template, each keyed by item and wired to CardCallback(item) (lines 27-34). Below the cards it renders the sentinel div only while _hasMore, with a polite live-region spinner while a page loads (lines 36-49), and the same alert when a later page failed (lines 51-54). That alert is one RenderFragment, LoadFailedAlert, carrying role="alert" with the message and a Retry button (lines 58-63).
• Why it's built this way: the component encapsulates the part of infinite scroll that is genuinely hard to get right (supersession, cancellation ownership, disposal, the DOM cap) and leaves the part that is app-specific (what a card looks like, where the data comes from) to parameters. The Result-returning delegate rather than a raw Task<List<T>> is what makes a localized failure message reachable without the component knowing any error catalogue.
• Where it's used: the mobile branch of nearly every list page. ADC: SessionList.razor:56, SpeakerList.razor:41, SponsorList.razor:41, RoomList.razor:41, EventList.razor:31, ActivityList.razor:41, QuestionList.razor:27, ConferenceCategoryList.razor:27, the public views PublicSessionListView.razor:6 and PublicEventList.razor:23, the check-in AttendeeSearchPanel.razor:27, and MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.UI/Pages/Users/UserList.razor:27. Store: MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.UI/Pages/Orders/OrderList.razor:26 and Pages/ShoppingCart/ShoppingCartList.razor:19. It is also exercised in the component gallery (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Gallery/Pages/ComponentsGallery.razor:57) and covered by MobileInfiniteScrollListTests.
• Caveats / not-in-source: MaxRenderedItems bounds the DOM but there is no virtualization, so 500 rendered cards remain in the DOM; whether that is acceptable on a given device is not determinable from source. A consumer fetch delegate that ignores its CancellationToken still runs to completion after a reset: the generation guard discards its results, but the request itself is not stopped.

MoneyExtensions

MMCA.Common.UI · MMCA.Common.UI.Extensions · MMCA.Common/Source/Presentation/MMCA.Common.UI/Extensions/MoneyExtensions.cs:14 · Level 5 · class (static)

• What it is: the presentation-layer formatter for money, turning a Money value object into $12.50 USD and a collection of them into a per-currency range such as $10.00 - $25.00 USD, formatted under a caller-chosen or ambient culture.
• Depends on: Money and its Currency (both MMCA.Common.Shared.ValueObjects), plus CultureInfo.CurrentCulture and StringComparer.Ordinal (BCL).
• Concept introduced, formatting lives in the UI layer, not the value object. [Rubric section 3, Clean Architecture] (assesses whether presentation concerns stay out of the inner layers: Money knows amounts and currencies, it does not know what a price looks like) and [Rubric section 20, Design System and Theming] (assesses consistent presentation of a recurring data shape; one formatter means every price on every page reads the same). It also shows the C# extension(T) preview syntax used for something other than DI: two blocks, one on Money and one on IReadOnlyCollection<Money>, sit in a single static class so both spellings (price.ToDisplayString() and prices.ToDisplayRange()) are available from one using.
• Walkthrough:
  • The class carries a file-level [SuppressMessage("Naming", "CA1708")] (lines 10-13): with two or more extension(T) blocks in one static class, CA1708 flags the compiler-generated grouping members as case-colliding. The justification records that no user-visible identifier differs only by case, a known analyzer trap of the preview syntax.
  • extension(Money price) (lines 16-31) exposes ToDisplayString(CultureInfo? culture = null) (lines 29-30), which delegates to FormatGroup(price.Amount, price.Amount, price.Currency.Code, culture): passing the same value as both bounds is what makes the shared helper render a single price rather than a degenerate range. Left unset, culture resolves inside FormatGroup to CultureInfo.CurrentCulture, the request's culture as already set by its culture provider; a caller passes one explicitly only when rendering off the reader's thread (a background job, an export, a test).
  • extension(IReadOnlyCollection<Money> prices) (lines 33-64) exposes ToDisplayRange(CultureInfo? culture = null) (lines 47-63): returns string.Empty for an empty collection (lines 49-52), resolves culture ?? CultureInfo.CurrentCulture once into resolved (line 54, ahead of the grouping), then groups by Currency.Code with StringComparer.Ordinal and formats each group from its own min and max under resolved (lines 58-60), joining the groups with ", " (line 62). Grouping is the load-bearing detail: a mixed-currency collection renders one range per currency, each with its own symbol, instead of collapsing unrelated amounts under whichever currency appeared first. The inline comment notes GroupBy preserves first-appearance order, so the single-currency case (every collection in practice today) is unchanged. Resolving the culture once outside the Select and passing it into every FormatGroup call is what keeps a one-element range and the single price it holds reading identically: the two paths must not drift.
  • Symbol(string code) (lines 71-76), a private switch mapping "USD" to $ and "EUR" to the escaped euro sign (line 74, escaped to keep the source file ASCII-only). Every other code, including the empty code of the Currency.None sentinel behind Money.Zero() (MMCA.Common/Source/Core/MMCA.Common.Shared/ValueObjects/Financial/Currency.cs:25, Money.cs:160), renders with no symbol rather than falsely claiming dollars.
  • FormatGroup(decimal min, decimal max, string code, CultureInfo? culture) (lines 88-97), the single formatting path: resolves culture ?? CultureInfo.CurrentCulture (line 90), then renders a single price when min == max and a hyphen-separated range otherwise, each bound through FormatAmount (lines 92-94), and appends the trailing code only when it is non-empty (line 96). Only the digit grouping and decimal separator follow the culture; the currency symbol and the trailing ISO code always come from the money itself, so a USD price stays USD in every locale.
  • FormatAmount(decimal amount, string symbol, CultureInfo culture) (lines 103-106) formats one amount with "N2" under the resolved culture, so an English reader gets $1,234.56 and a Spanish reader gets $1.234,56. A negative amount puts the sign before the symbol (-$5.00, not $-5.00) by formatting Math.Abs(amount) behind a leading -, which keeps the culture's digit grouping intact (lines 99-102).
• Why it's built this way: presentational formatting belongs above the domain, so Money stays display-agnostic and the same value can be rendered differently by a different head. The move from a hardcoded CultureInfo.InvariantCulture to a caller-optional, request-defaulted CultureInfo.CurrentCulture lets the number format follow the reader's culture (a Spanish reader's thousands and decimal separators) while the currency symbol and ISO code stay tied to the money's own currency, so the price never implies a currency the data does not carry. The optional parameter keeps every existing call site source-compatible while opening a path for a background job, an export, or a test to format under an explicit culture instead of the ambient one.
• Where it's used: Store's Sales and Catalog UIs. ToDisplayString() renders order totals and line amounts (MMCA.Store/Source/Modules/Sales/MMCA.Store.Sales.UI/Pages/Orders/OrderLinesPanel.razor:63, :39, :51; Pages/Order/OrderSummaryPanel.razor:54; Pages/Order/OrderList.razor:36, :102) and the cart's order-created snackbar (Pages/ShoppingCart/ShoppingCartDetail.razor.cs:354); ToDisplayRange() renders the price span across a product's variants in catalog browse (MMCA.Store/Source/Modules/Catalog/MMCA.Store.Catalog.UI/Pages/Catalog/CatalogBrowse.CardFormatting.razor.cs:38, with the single-price helper alongside it at :41) and on the catalog product detail page (Pages/Catalog/CatalogProductDetail.razor.cs:266, :269). None of these call sites pass a culture argument, so all of them format under the ambient CultureInfo.CurrentCulture. Covered by MoneyExtensionsTests.
• Caveats / not-in-source: only USD and EUR have symbols; adding a currency means editing Symbol, there is no configuration-driven table. The "N2" format assumes a two-minor-unit currency, so a zero-decimal currency (JPY) would render two spurious decimals; no code guards that today.

BuiltInStrings

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/InvariantMudLocalizationInterceptor.cs:73 · Level 0 · class (private, sealed, nested, implements IStringLocalizer)

• What it is: a private class nested inside InvariantMudLocalizationInterceptor that resolves MudBlazor's own built-in English strings straight from its embedded resource file, instead of MudBlazor's generated LanguageResource class, which is internal to the MudBlazor assembly and therefore unreachable directly.
• Depends on: System.Resources.ResourceManager and System.Globalization.CultureInfo (BCL); reads the manifest resource named "MudBlazor.Resources.LanguageResource" off typeof(MudLocalizer).Assembly (MudBlazor, NuGet). Nothing first-party beyond its owner.
• Concept: no new pattern; addressing an internal library resource by its manifest name, plus a minimal singleton (a private constructor and a static Instance property, lines 79-83).
• Walkthrough: this[string name] (85-92) calls Resources.GetString(name, CultureInfo.InvariantCulture) (89) and returns a LocalizedString whose resourceNotFound flag is set when that lookup returns null. this[string name, params object[] arguments] (94-104) does the same lookup, then formats the resolved string with CultureInfo.CurrentCulture when it was found, or falls back to the bare name when it was not (98-101). GetAllStrings(bool includeParentCultures) (106-122) enumerates the invariant-culture ResourceSet (108) and yields a LocalizedString per entry, or nothing if the set cannot be created (109-112).
• Why it's built this way: private and sealed, nested inside its only consumer, because it exists solely to give InvariantMudLocalizationInterceptor an IStringLocalizer it can pass as the English fallback to the base AbstractLocalizationInterceptor constructor; reading the manifest resource by string name is the only way to reach MudBlazor's built-in strings since the generated resource class itself is internal to MudBlazor.
• Where it's used: constructed once via Instance and passed as the built-in localizer argument to InvariantMudLocalizationInterceptor's base constructor call (line 38); not referenced outside the file that defines it.

NotificationPageNotFoundStatus

MMCA.Common.UI · MMCA.Common.UI.Notifications · MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationPageNotFoundStatus.cs:11 · Level 0 · class (internal, sealed)

• What it is: a render-nothing ComponentBase whose only job is to tell the host the response is a 404 when the router answers a notification route with the not-found page.
• Depends on: externals only: Microsoft.AspNetCore.Components (ComponentBase, [Inject], NavigationManager). No first-party types.
• Concept introduced, a not-found that is a real status. [Rubric §25, Navigation, Routing & Information Architecture] assesses whether the routing answer matches what the host composed. Rendering the not-found page alone would still return HTTP 200 on a server render; calling NavigationManager.NotFound() is the framework signal that sets the 404 status.
• Walkthrough
  • Navigation (lines 14-15) is an [Inject]ed private NavigationManager.
  • OnInitialized() (line 18) is the whole behavior: Navigation.NotFound().
• Why it's built this way: the call has to run inside a component lifecycle, so the signal is a tiny component rather than code in Routes.razor; internal because only the router uses it.
• Where it's used: mounted through <DynamicComponent Type="typeof(NotificationPageNotFoundStatus)" /> in the hidden branch of the router (MMCA.Common/Source/Presentation/MMCA.Common.UI/Routes.razor:25), next to the not-found page rendered by NotificationPageGate's decision.

NotificationPageRequirement

MMCA.Common.UI · MMCA.Common.UI.Notifications · MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationPageRequirement.cs:20 · Level 0 · class (internal, sealed)

• What it is: the IAuthorizationRequirement behind the mmca:notification-pages policy that the notification pages declare instead of a bare [Authorize]. It is a marker with one constant, PolicyName (line 23).
• Depends on: externals only: Microsoft.AspNetCore.Authorization (IAuthorizationRequirement). The class doc references LayoutSettings and NotificationPageGate.
• Concept introduced, a policy that can defer to the router. [Rubric §11, Security] and [Rubric §25, Navigation, Routing & Information Architecture]. A bare [Authorize] becomes endpoint metadata, so on a Blazor Web host the authorization middleware challenged a signed-out request (a sign-in redirect) before the router's gate ran, and a page that does not exist for this host asked the visitor to sign in (class remarks, lines 14-19). The requirement carries no data; the decision is made by NotificationPageAuthorizationHandler.
• Walkthrough: PolicyName is "mmca:notification-pages" (line 23). The type has no other members.
• Why it's built this way: a named policy with its own requirement lets the pass condition be "authenticated, or the pages are hidden" while still reading as [Authorize] semantics on the page.
• Where it's used: the policy is added in AddUIShared with NotificationPageRequirement.PolicyName and new NotificationPageRequirement() (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:81-83); evaluated by the handler (NotificationPageAuthorizationHandler.cs, 3 references).

PseudoLocalizer

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/PseudoLocalizer.cs:20 · Level 0 · class (static)

• What it is: a pure string transform that "pseudo-localizes" text. It accents every letter, pads the result by roughly 40% to simulate real-translation expansion, and wraps it in [!! ... !!] bracket sentinels, while leaving composite-format placeholders ({0}, {name}) byte-identical so the string can still be formatted with arguments (ADR-027 §8).
• Depends on: System.Text.StringBuilder and char.IsLetter (BCL). Nothing first-party. It is consumed by PseudoStringLocalizer.
• Concept introduced, pseudo-localization as an i18n fitness test. [Rubric §27, Internationalization] (assesses whether the app is genuinely translation-ready, not just wired for one extra language) and [Rubric §28, Front-End Testing] (assesses whether i18n defects are caught automatically). Pseudo-localization is a development-time technique that surfaces three classes of bug in a single visual pass, without needing a real second translation, and the <remarks> block (PseudoLocalizer.cs:12-19) enumerates exactly those three: (1) any string that stays plain ASCII was hard-coded rather than pulled from a resource, and stands out beside the accented text; (2) any UI that truncates the padded text has a fixed-width layout that a real (longer) translation would break; (3) any label built by concatenating fragments shows one sentinel per fragment, exposing the joins that translate badly.
• Walkthrough:
  • Three constants (lines 22-24): OpenSentinel = "[!! ", CloseSentinel = " !!]", and CombiningAcute (the combining acute accent code point) appended after each base glyph so the letter stays readable while visibly altered.
  • Transform(string value) (lines 30-74): returns null/empty input unchanged (lines 32-35); pre-sizes a StringBuilder with slack for the padding (line 37) and appends the open sentinel (line 38); then walks each character in a switch (lines 42-66) tracking an insidePlaceholder flag toggled by { and } (lines 46-53) so placeholder bodies are copied verbatim, and for every letter outside a placeholder appends the combining accent and increments a letters counter (lines 54-64); finally computes the pad length as Math.Max(1, letters * 2 / 5) (about 40%, line 69), appends a separating space (line 70), that many ~ characters (line 71) and the close sentinel (line 72), and returns the string (line 73).
• Why it's built this way: keeping the transform pure and static (input string to output string, no culture check inside) makes it trivially unit-testable and lets the culture gating live one layer up in PseudoStringLocalizer. Preserving {...} placeholders is essential: transforming them would corrupt string.Format, so pseudo-loc must accent the template and only then substitute arguments (see the two-step in PseudoStringLocalizer).
• Where it's used: called by PseudoStringLocalizer on every resolved string when the current UI culture is the pseudo locale (SupportedCultures.PseudoLocale, referenced in the doc comment at line 10); inert otherwise. Covered by PseudoLocalizationTests.

StringLocalizerPluralExtensions

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/StringLocalizerPluralExtensions.cs:20 · Level 0 · class (static)

• What it is: a static extension class that adds a Plural(key, count, args) method to IStringLocalizer, resolving the count-appropriate resource key (a .One suffix for a count of exactly one, .Other for every other count, zero included) with a fallback to the base key when the plural-specific entry is missing.
• Depends on: Microsoft.Extensions.Localization.IStringLocalizer/LocalizedString (NuGet). No first-party dependency.
• Concept introduced, plural-form resolution via key suffixing. [Rubric §27, Internationalization] assesses whether the app handles languages whose plural rules diverge from a naive singular-versus-plural split; this extension implements the simpler English-style two-category split (one, other) as a suffix convention on top of the standard IStringLocalizer indexer, rather than pulling in a full CLDR plural-rules library. OneSuffix (".One", line 23) and OtherSuffix (".Other", line 26) are the two constants callers key their resx entries against. The C# extension(IStringLocalizer localizer) block (line 28) is the new extension-member syntax the workspace's LangVersion: preview setting enables, in place of a classic this IStringLocalizer localizer first parameter.
• Walkthrough: Plural(string key, int count, params object[] args) (lines 40-52) validates its arguments (42-44), picks pluralKey as key + OneSuffix when count == 1 or key + OtherSuffix otherwise (46), resolves it through the localizer's indexer (47), and if that lookup's ResourceNotFound is true, falls back to the base key itself (51): the comment at 49-50 records why the fallback matters, ResourceNotFound is how a ResourceManager-backed localizer reports a missing key, by handing back the key name itself, which must never reach the screen.
• Why it's built this way: the fallback to the unsuffixed key means a resx file that has not yet been split into .One/.Other entries still renders something legible instead of a raw resource-key string; the suffix convention keeps plural-aware resources in the same flat resx format every other string uses, no separate plural-rules resource format.
• Where it's used: not referenced outside the file that defines it.

InvariantMudLocalizationInterceptor

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/InvariantMudLocalizationInterceptor.cs:37 · Level 1 · class (internal, sealed)

• What it is: MudBlazor's interception point for resolving its own chrome text, tuned so the neutral "en" culture (whose parent is the invariant culture) still routes through the app's MudLocalizer like every other non-English culture, and only "en-US" (and other cultures whose parent is literally English) short-circuits straight to MudBlazor's built-in strings (ADR-027).
• Depends on: BuiltInStrings (its own nested Level 0 type, passed as the built-in localizer), an optional MudLocalizer constructor parameter (MudBlazor, NuGet), and the base class the constructor chains into, AbstractLocalizationInterceptor(BuiltInStrings.Instance, mudLocalizer) (line 38).
• Concept introduced, matching a library's own "is this English" test rather than assuming one. [Rubric §27, Internationalization]. The comment at lines 46-48 records the design constraint directly: this interceptor deliberately reproduces MudBlazor's own definition of "is this culture English", the culture's parent's two-letter ISO name equals "en" so a specific culture like "en-US" counts as English, but the neutral "en" culture itself (whose parent is the invariant culture, not English) does not, and instead flows through MudLocalizer like any other culture, falling back to the built-in string only if that lookup reports ResourceNotFound.
• Walkthrough: the primary constructor (line 37) takes an optional MudLocalizer? mudLocalizer and passes it, alongside BuiltInStrings.Instance, to the base AbstractLocalizationInterceptor. Handle(string key, params object[] arguments) (lines 41-61) validates its arguments (43-44), computes isEnglish by comparing CultureInfo.CurrentUICulture.Parent.TwoLetterISOLanguageName to "en" with OrdinalIgnoreCase (49-52), and returns straight from BuiltIn(key, arguments) (56) when MudLocalizer is null or the culture is English (54-57); otherwise it tries MudLocalizer[key, arguments] (59) and falls back to BuiltIn when that translation reports ResourceNotFound (60). The private BuiltIn(string key, object[] arguments) helper (65-66) is a no-argument-indexer call when arguments is empty, the comment at 63-64 notes that formatting a value containing literal braces with an empty argument list would throw, and MudBlazor's own strings are looked up the same way.
• Why it's built this way: reusing MudBlazor's own English-detection rule, rather than a simpler "does the culture name start with en" check, keeps this interceptor's fallback behavior identical to MudBlazor's default DefaultLocalizationInterceptor for the one case (the neutral "en" culture) where a naive check would diverge from it.
• Where it's used: MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs (1 reference, its registration). Tested by MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Globalization/InvariantMudLocalizationInterceptorTests.cs.

PseudoStringLocalizer

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/PseudoStringLocalizer.cs:13 · Level 1 · class (sealed)

• What it is: an IStringLocalizer decorator that pseudo-localizes every resolved string, but only when the current UI culture is the pseudo locale; under every other culture it delegates unchanged to the wrapped localizer, so it is inert in production (ADR-027 §8).
• Depends on: PseudoLocalizer (the transform, Level 0), SupportedCultures (its IsPseudoLocale from MMCA.Common.Shared.Globalization), and IStringLocalizer/LocalizedString/CultureInfo (BCL and NuGet). Constructed with an inner IStringLocalizer via a primary constructor (line 13).
• Concept introduced, the decorator that gates on culture. [Rubric §2, Design Patterns] (assesses idiomatic use of patterns; this is a textbook Decorator, same interface in and out, wrapping behavior around a delegate) and [Rubric §27, Internationalization]. The key design move is that pseudo-localization is a cross-cutting transform applied to the localizer, not to any call site: because it implements IStringLocalizer and forwards to inner, it can be slid underneath every IStringLocalizer<T> in the app at once by decorating the factory (PseudoStringLocalizerFactory), with zero changes to consumers.
• Walkthrough:
  • IsPseudoActive (lines 16-17), a private static bool that returns SupportedCultures.IsPseudoLocale(CultureInfo.CurrentUICulture.Name), the single gate every member checks.
  • this[string name] (lines 20-29): resolves inner[name] (line 24), then, if pseudo is active, returns a new LocalizedString whose value is PseudoLocalizer.Transform(localized.Value) while preserving ResourceNotFound/SearchedLocation (line 26); otherwise returns the inner value untouched (line 27).
  • this[string name, params object[] arguments] (lines 32-48): when pseudo is inactive, delegates straight to inner[name, arguments] (lines 36-39); when active it does the two-step that makes placeholders survive, transform the raw template first (lines 43-44), then string.Format the accented template with the arguments (line 45), so the substituted values are never accented or padded.
  • GetAllStrings(bool includeParentCultures) (lines 51-57): maps the transform over every string when active (line 55), passes them through otherwise (line 56).
• Why it's built this way: gating inside the decorator (rather than conditionally registering it) keeps DI wiring unconditional and simple, the decorator is always present and simply does nothing outside the pseudo locale, which per the doc comment (lines 10-11) is never an activatable request culture in production. Splitting the pure transform (PseudoLocalizer) from the culture-aware decorator keeps each single-responsibility and independently testable ([Rubric §1, SOLID]).
• Where it's used: produced by PseudoStringLocalizerFactory around every localizer the inner factory creates, so it transparently wraps IStringLocalizer<SharedResource>, IStringLocalizer<MudTranslations>, and every other localizer in the host.

ResxMudLocalizer

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/ResxMudLocalizer.cs:17 · Level 1 · class (sealed, internal)

• What it is: MudBlazor's MudLocalizer implementation that resolves the library's built-in component text from the MudTranslations resource pair, so MudBlazor chrome (pager, filter menus, pickers, close buttons) follows the active UI culture (ADR-027).
• Depends on: MudBlazor.MudLocalizer (the abstract base, NuGet), IStringLocalizer<MudTranslations> (injected via primary constructor, line 17), and MudTranslations (Level 0). Nothing else first-party.
• Concept introduced, adapting a third-party localization hook. [Rubric §2, Design Patterns] (this is an Adapter, bridging MudBlazor's MudLocalizer contract to the ASP.NET Core IStringLocalizer world) and [Rubric §27, Internationalization]. MudBlazor exposes exactly one extension point for translating its built-in strings: subclass MudLocalizer and override its indexer. This adapter routes that indexer straight to IStringLocalizer<MudTranslations>. MudBlazor's own DefaultLocalizationInterceptor consults this localizer only for non-English cultures and falls back to its built-in English whenever the returned LocalizedString.ResourceNotFound is true (per the doc comment, ResxMudLocalizer.cs:9-12), so any untranslated key degrades gracefully.
• Walkthrough: a one-member class. internal sealed class ResxMudLocalizer(IStringLocalizer<MudTranslations> localizer) : MudLocalizer (line 17) with a single public override LocalizedString this[string key] => localizer[key]; (line 19). The doc comment (lines 13-15) also notes that because resolution flows through the DI IStringLocalizerFactory, the PseudoStringLocalizerFactory decorator applies here too, so under the development-only qps-Ploc culture MudBlazor's chrome pseudo-localizes alongside the application text.
• Why it's built this way: internal because it is pure host wiring no consumer needs to name; delegating to the injected IStringLocalizer<MudTranslations> reuses the exact same .resx/factory pipeline as app strings (one localization mechanism, not two), which is what lets pseudo-loc reach MudBlazor for free.
• Where it's used: registered as MudBlazor's MudLocalizer in AddUIShared via services.TryAddTransient<MudBlazor.MudLocalizer, ResxMudLocalizer>() (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:101). TryAdd is authoritative because AddMudServices does not register a MudLocalizer of its own (guarded by a DI-resolution test, per the comment at DependencyInjection.cs:97-100), regardless of host registration order. Covered by ResxMudLocalizerTests.

PseudoStringLocalizerFactory

MMCA.Common.UI · MMCA.Common.UI.Globalization · MMCA.Common/Source/Presentation/MMCA.Common.UI/Globalization/PseudoStringLocalizerFactory.cs:11 · Level 2 · class (sealed)

• What it is: an IStringLocalizerFactory decorator that wraps every localizer the inner factory produces in a PseudoStringLocalizer, so decorating this one factory pseudo-localizes every IStringLocalizer<T> and IStringLocalizer in the host at once (ADR-027 §8).
• Depends on: PseudoStringLocalizer (Level 1) and IStringLocalizerFactory/IStringLocalizer (Microsoft.Extensions.Localization, NuGet). Constructed with the inner factory via a primary constructor (line 11).
• Concept introduced, decorate the factory to reach every product. [Rubric §2, Design Patterns] (Decorator applied at the factory level) and [Rubric §6, CQRS & Event-Driven Design] (assesses whether cross-cutting behavior is injected in one place rather than scattered). Because StringLocalizer<T> resolves its backing localizer through the IStringLocalizerFactory, wrapping the factory means every localizer the DI container ever hands out is already pseudo-aware: no per-type registration, no consumer change. This is the same "decorate the boundary, not the callers" idea the CQRS pipeline uses (see primer §2), applied to localization.
• Walkthrough: two forwarding overrides, each wrapping the inner factory's product:
  • Create(Type resourceSource) (lines 14-15): new PseudoStringLocalizer(inner.Create(resourceSource)), the path used by IStringLocalizer<T>.
  • Create(string baseName, string location) (lines 18-19): new PseudoStringLocalizer(inner.Create(baseName, location)), the path used by name-based localizers.
• Why it's built this way: registering the wrapper on the factory is the minimal, DI-idiomatic way to make pseudo-loc universal; combined with the culture gate inside PseudoStringLocalizer, it can be registered unconditionally because it is inert under every non-pseudo culture, so production wiring is not conditional on environment (the registration comment, DependencyInjection.cs:90-94, says exactly that: the pseudo locale is only ever activatable in Development).
• Where it's used: registered via services.Decorate<IStringLocalizerFactory, PseudoStringLocalizerFactory>() (Scrutor) in AddUIShared (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:95), after services.AddLocalization() (line 60). Its reach includes MudBlazor chrome through ResxMudLocalizer, which resolves its IStringLocalizer<MudTranslations> through this same factory.

NotificationUIModule

MMCA.Common.UI · MMCA.Common.UI.Notifications · MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationUIModule.cs:15 · Level 7 · class (sealed)

• What it is: the notification feature's IUIModule descriptor. It declares the two nav entries (user inbox, admin push notifications), the app-bar component, the layout component, and the assembly to scan for routable pages.
• Depends on: first-party: IUIModule (the contract, line 15), NavItem and NavSection (the nav item shape and its placement enum), NotificationRoutePaths (the two routes), SharedResource (the resx type each nav label resolves against), NotificationPermissions (the Manage gate), plus the NotificationBell and NotificationListener components in the same package (lines 23, 25). Externals: MudBlazor (Icons.Material.Filled.*), System.Reflection (Assembly).
• Concept introduced, the UI module pattern (the client-side counterpart to IModule). [Rubric §25, Navigation, Routing & Information Architecture] assesses how navigation is composed and how routes are discovered. Server modules declare their registrations and dependencies through IModule; UI features do the same for the shell. Nothing here calls into a layout: the module declares nav items and component types as data, and the host discovers every registered IUIModule and assembles the menu, app bar, and layout from those declarations. Adding a feature therefore never edits a shared MainLayout.razor or a central menu file.
  • [Rubric §18, UI Architecture & Component Design] applies to the two component collections: AppBarComponentTypes and LayoutComponentTypes are Type handles, so the shell renders them dynamically without a compile-time reference to the feature.
  • [Rubric §11, Security] applies to the permission gate: the admin entry carries RequiredPermission: NotificationPermissions.Manage (line 20) on the nav item itself, so the authorization fact lives next to the thing it protects rather than in a layout if.
  • [Rubric §27, Internationalization & Localization]: the nav labels are resource keys plus a resource type, "Nav.NotificationInbox" and "Nav.PushNotifications" with typeof(SharedResource) (lines 19-20), not literal English. A descriptor is a singleton built once at startup, so it cannot hold a localized string; carrying the key and the resx anchor instead is what lets the shell resolve the label per circuit under the active culture.
• Walkthrough
  • NavItems (lines 17-21) is an immutable IReadOnlyList<NavItem> with two entries: the inbox key Nav.NotificationInbox to NotificationRoutePaths.NotificationInbox with the Inbox icon in NavSection.User (line 19, no role, so any authenticated user sees it), and Nav.PushNotifications to NotificationRoutePaths.Notifications with the NotificationsActive icon, gated on NotificationPermissions.Manage, in NavSection.Admin and grouped under the resource key "Nav.Group.Notifications" (line 20), so the group heading is localized like the labels.
  • AppBarComponentTypes (line 23) is [typeof(NotificationBell)], the badge the shell injects into the top bar.
  • LayoutComponentTypes (line 25) is [typeof(NotificationListener)], mounted once per layout so the SignalR callback wiring has exactly one owner.
  • Assembly (line 27) returns typeof(NotificationUIModule).Assembly, which the host adds to the Blazor router's additional assemblies so the pages in this package become routable in the consumer app.
• Why it's built this way: expressing contributions as data (collections of records and Types) keeps the shell open for extension and closed for modification, and it is what allows a package to ship a complete feature (routes, nav, app-bar widget, background listener) that a host enables with one DI call. The class is sealed and every member is a get-only auto-property initialized inline, so the descriptor is safely shared as a singleton.
• Where it's used: registered as a singleton IUIModule by AddNotificationUI() in the notifications DependencyInjection (Notifications/DependencyInjection.cs:39); enumerated by the host shell at startup to build navigation and to discover this package's routable components.

NotificationPageGate

MMCA.Common.UI · MMCA.Common.UI.Notifications · MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationPageGate.cs:12 · Level 8 · class (internal, static)

• What it is: the two-method predicate (Hides and HidesNotificationPages) the framework router consults to decide whether a matched notification page should be answered with the not-found page instead, because the host opted in and never registered the notification UI (class doc, lines 7-11).
• Depends on: first-party: LayoutSettings (the HideNotificationPagesWhenUnregistered opt-in, MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/Settings/LayoutSettings.cs:49), IUIModule (the registered modules it scans), NotificationUIModule (the module whose presence means "registered"), and the three routable pages it guards, NotificationList, NotificationInbox and NotificationSend. Externals: BCL System.Type and LINQ (Contains, Any).
• Concept introduced, a feature's routes follow its registration. [Rubric §25, Navigation, Routing & Information Architecture] assesses whether what is reachable by URL matches what the host actually composed. The notification pages ship in the MMCA.Common.UI assembly itself, so they are routable in every host whether or not it called AddNotificationUI(); a host that never registered the feature would serve pages whose services it never registered, which fail at render. The UI module pattern (ADR-067) already makes the NotificationUIModule singleton the evidence of registration, so the gate reads that rather than probing for individual services.
  • Opt-in, not a behavior change. HideNotificationPagesWhenUnregistered defaults to false, which leaves the routes exactly as they are, and a host that registers the notification UI is unaffected either way (LayoutSettings.cs:38-49). Only a host that sets the flag and lacks the module gets the not-found answer.
• Walkthrough
  • NotificationPages (line 15) is a private static Type[] of typeof(NotificationList), typeof(NotificationInbox) and typeof(NotificationSend), the routable pages that need the services AddNotificationUI() registers.
  • Hides(Type pageType, LayoutSettings settings, IEnumerable<IUIModule> modules) (lines 22-23) is NotificationPages.Contains(pageType) && HidesNotificationPages(settings, modules): the matched page must be one of the three before the host-level question is asked.
  • HidesNotificationPages(LayoutSettings settings, IEnumerable<IUIModule> modules) (lines 29-31) is the page-independent half: the flag is on (line 30) and no registered module is NotificationUIModule (line 31). It is public so NotificationPageAuthorizationHandler can ask the same question without a page type.
• Why it's built this way: keeping the decision in a small internal static predicate, with the page type, settings and module list passed in, keeps Routes.razor to a one-line branch and lets a unit test cover every combination without rendering a router. Answering with the framework's own not-found page inside the main layout gives the user the same experience as any unknown URL instead of a render failure.
• Where it's used: called once per route match from the <Found> branch of the framework router, NotificationPageGate.Hides(routeData.PageType, LayoutOptions.Value, UIModules) (MMCA.Common/Source/Presentation/MMCA.Common.UI/Routes.razor:16), which renders Pages.NotFound inside MainLayout when it returns true; pinned by NotificationPageGateTests (MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Notifications/NotificationPageGateTests.cs, 4 references).
• Caveats / not-in-source: the LayoutSettings doc lists four routes (/notifications, /notifications/inbox, /notifications/inbox/{Id}, /notifications/send) while the gate matches three page types, so the inbox detail route is presumably served by one of those three pages; which page carries it is not visible from these files.

NotificationPageAuthorizationHandler

MMCA.Common.UI · MMCA.Common.UI.Notifications · MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/NotificationPageAuthorizationHandler.cs:14 · Level 9 · class (internal, sealed)

• What it is: the AuthorizationHandler<NotificationPageRequirement> that evaluates the mmca:notification-pages policy: it succeeds for any authenticated caller, and also for every caller when the host hides the notification pages.
• Depends on: first-party: NotificationPageRequirement (the requirement it handles), NotificationPageGate (HidesNotificationPages), LayoutSettings (via IOptions<LayoutSettings>), IUIModule (the registered modules). Externals: Microsoft.AspNetCore.Authorization, Microsoft.Extensions.Options.
• Concept introduced, authorization that steps aside for a 404. [Rubric §11, Security] assesses that access rules are explicit and centrally evaluated. The handler keeps [Authorize] semantics but lets a hidden page reach the router, so a signed-out visitor to a route the host does not serve gets a not-found answer instead of a sign-in challenge (requirement doc, NotificationPageRequirement.cs:6-13). Nothing is ever failed explicitly: the handler only calls Succeed, so an unauthenticated caller on a host that shows the pages falls through to the default denial.
• Walkthrough
  • Primary constructor (lines 14-16) takes IOptions<LayoutSettings> layoutOptions and IEnumerable<IUIModule> modules.
  • HandleRequirementAsync (lines 20-33) guards context with ArgumentNullException.ThrowIfNull (line 24), then calls context.Succeed(requirement) (line 29) when any identity IsAuthenticated (line 26) or NotificationPageGate.HidesNotificationPages(layoutOptions.Value, modules) is true (line 27), and returns Task.CompletedTask (line 32).
• Why it's built this way: delegating the "hidden" question to NotificationPageGate.HidesNotificationPages means the router and the policy cannot disagree about when the pages are hidden. The handler is synchronous work wrapped in a completed task because no I/O is needed.
• Where it's used: registered as a transient IAuthorizationHandler with TryAddEnumerable in AddUIShared (MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs:84-85), alongside the policy registration at lines 81-83.

DependencyInjection

MMCA.Common.UI · MMCA.Common.UI.Notifications · MMCA.Common/Source/Presentation/MMCA.Common.UI/Notifications/DependencyInjection.cs:12 · Level 8 · class (static)

• What it is: the notification-UI registration entry point, a single AddNotificationUI() extension on IServiceCollection that wires the two typed HTTP services, the shared per-circuit state, the SignalR client, the scope provider, and the IUIModule descriptor.
• Depends on: first-party: INotificationScopeProvider + NullNotificationScopeProvider, IPushNotificationUIService + PushNotificationService, INotificationInboxUIService + NotificationInboxService, NotificationState, NotificationHubService, and IUIModule + NotificationUIModule. Externals: Microsoft.Extensions.DependencyInjection (IServiceCollection, AddScoped, AddSingleton) and Microsoft.Extensions.DependencyInjection.Extensions (TryAddScoped).
• Concept: the C# extension(IServiceCollection services) registration idiom used package-wide (see primer); the block opens at line 14 and the method inside it is an ordinary extension method in the new form. Note this is one of several DependencyInjection classes in the UI packages: this one is specifically the Notifications registrar, the sibling of the MMCA.Common.UI.Web host registrar above.
  • [Rubric §33, Developer Experience & Inner Loop] assesses how much a consumer must know to switch a feature on; the answer here is one call.
  • [Rubric §3, Clean Architecture] assesses where composition lives; the feature owns its own DI, so nothing about notifications leaks into a host's Program.cs beyond the single line.
  • TryAdd versus Add is a deliberate signal. The scope provider is registered with TryAddScoped (line 24) precisely so an app that registers its own INotificationScopeProvider wins regardless of the order the two registration calls run in (the comment on lines 22-23 says so); everything else uses plain AddScoped/AddSingleton because this package owns those contracts.
• Walkthrough: inside the extension block (line 14), AddNotificationUI() (line 20) registers, in order, INotificationScopeProvider to NullNotificationScopeProvider via TryAddScoped (line 24, the default no-op scope consumed by both HTTP services and read for the caption on NotificationSend), IPushNotificationUIService to PushNotificationService (scoped, line 27), INotificationInboxUIService to NotificationInboxService (scoped, line 30), NotificationState as a concrete scoped type (line 33, one unread-count owner per Blazor circuit), NotificationHubService (scoped SignalR client, line 36), and finally NotificationUIModule as a singleton IUIModule (line 39), because the descriptor is immutable shell metadata rather than per-circuit state. It returns services for chaining (line 41).
• Why it's built this way: the scoped-versus-singleton split is the load-bearing part. HTTP services, state, and the hub connection are per-circuit (a Blazor circuit is a DI scope, and the unread count belongs to one user's session), while the nav and shell descriptor is process-wide and immutable. Bundling all six behind one extension keeps host startup honest and makes the feature's dependency surface reviewable in one screen.
• Where it's used: called from the Program.cs of each consuming host (Blazor Web and MAUI) that opts into the notification UI; it complements the main MMCA.Common.UI registration rather than replacing it.
• Caveats / not-in-source: this method does not register NotificationBellOptions. The bell injects IOptions<NotificationBellOptions> (NotificationBell.razor.cs:36) and the options type supplies its own defaults (NotificationBellOptions.cs:23,30), so the unconfigured case works, but where a host binds the NotificationBell configuration section is not visible from this file.

PermissionGroup

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/RoleAdminEdit.razor.cs:328 · Level 0 · record (private, sealed, nested)

• What it is: a private record nested inside RoleAdminEdit that groups the permissions filed under one area:capability prefix, the shape the edit form renders one checkbox section per.
• Depends on: nothing first-party beyond its own owner; an IReadOnlyList<string> for the member permissions.
• Concept: no new pattern; a compact in-memory grouping record with two positional properties.
• Walkthrough: Area (the text before the first colon, or the localized "General") and Permissions (that area's permissions, ordered). Built by RoleAdminEdit.Group(IEnumerable<string>) (RoleAdminEdit.razor.cs:308-317), which groups the catalog's permissions by RoleAdminEdit.AreaOf and orders both the groups and each group's members with StringComparer.Ordinal, so the checkbox layout is stable across loads.
• Why it's built this way: private and sealed because it exists only to shape one component's markup loop; nothing outside RoleAdminEdit needs it.
• Where it's used: the _groups field of RoleAdminEdit (RoleAdminEdit.razor.cs:131), populated by Group(...) and iterated by the permission checkbox markup.

RoleAdminEditResources

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/RoleAdminEditResources.cs:14 · Level 0 · class (sealed, empty)

• What it is: an empty marker class, public sealed class RoleAdminEditResources;, whose only job is to be the generic argument of an IStringLocalizer<RoleAdminEditResources>.
• Depends on: nothing; it carries no members.
• Concept introduced, a fallback-resource marker for an app-first localization pattern. [Rubric §27, Internationalization] assesses whether an app can supply its own wording without forking framework code. RoleAdminEdit injects IStringLocalizer<RoleAdminEditResources> as L (RoleAdminEdit.razor.cs:160) and its private T(key, args) helper (:205-217) checks the caller-supplied Localizer parameter first, falling through to L (this marker's resx) only when the app's localizer does not carry the key. The marker class itself defines no strings; it exists purely so .NET's resource-file convention (RoleAdminEditResources.resx beside the class) has something to key against.
• Walkthrough: no members.
• Why it's built this way: sealed because nothing subclasses a resource marker; kept as a distinct class per component (paired with RoleAdminListResources, UserAdminListResources) rather than one shared marker, so each component's resx file, and its "app localizer not consulted for this key" fallback, is scoped independently.
• Where it's used: RoleAdminEdit.razor.cs (3 references: the injected L property, the T fallback call, and the DI registration type argument) and 2 more, including MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs.

RoleAdminListResources

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/RoleAdminListResources.cs:14 · Level 0 · class (sealed, empty)

• What it is: the same empty resx-marker shape as RoleAdminEditResources, scoped to RoleAdminList instead.
• Depends on: nothing; no members.
• Concept reinforced: the app-localizer-first fallback RoleAdminEditResources introduces. [Rubric §27, Internationalization].
• Walkthrough: no members.
• Why it's built this way: kept distinct from RoleAdminEditResources so the two components' resx files, and their independent "app localizer missing this key" fallbacks, do not share one namespace.
• Where it's used: RoleAdminList.razor.cs (3 references) and 2 more, including MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs.

UserAdminListResources

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/UserAdminListResources.cs:14 · Level 0 · class (sealed, empty)

• What it is: the same empty resx-marker shape, scoped to UserAdminList<TUser>.
• Depends on: nothing; no members.
• Concept reinforced: the app-localizer-first fallback RoleAdminEditResources introduces. [Rubric §27, Internationalization].
• Walkthrough: no members.
• Why it's built this way: same rationale as its two siblings, one marker per component so each keeps its own resx and fallback scope.
• Where it's used: UserAdminList.razor.cs (3 references) and 2 more, including MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs.

RoleAdminEdit

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/RoleAdminEdit.razor.cs:36 · Level 4 · class (partial, ComponentBase, IDisposable)

• What it is: the UI half of ADR-116 role administration: an editable, grouped checkbox matrix of every permission the catalog knows about for one Role, with code-compiled permissions shown locked and only the operator's extra grants persisted.
• Depends on: IRoleAdminUIService (injected as Roles, line 80), IToastService (Toast, 82), IStringLocalizer<RoleAdminEditResources> (L, 84, see RoleAdminEditResources), LatestLoadGuard (MMCA.Common/Source/Presentation/MMCA.Common.UI/Common/LatestLoadGuard.cs:38, held as _load, line 42), its own nested PermissionGroup record, and AdministrationPermissions.ManageRoles (MMCA.Common.Shared.Auth.Administration). Externals: Microsoft.Extensions.Localization.IStringLocalizer, Blazor's ComponentBase.
• Concept introduced, a compiled/stored permission split rendered as locked vs. editable checkboxes. [Rubric §11, Security] assesses whether a role's code-granted authority stays visible and non-revocable from the UI; [Rubric §18, UI Architecture & Component Design] assesses whether that split is legible to the operator. _compiled (line 47) is the set of permissions the role's code already grants (the registry, unconditionally locked); _stored (48) is the operator-editable overlay persisted to the PermissionGrant table. A permission is ticked when either set contains it (IsChecked, line 253) but is read-only, and therefore excluded from a save, when it is compiled OR is AdministrationPermissions.ManageRoles itself (IsReadOnly, 258-260): the second clause is a deliberate lockout guard, an operator can never uncheck the one permission that lets a role reach this very page.
• Concept introduced (2), an app-localizer-first fallback with per-call override args. [Rubric §27, Internationalization]. The private T(key, args) helper (141-153) checks the caller-supplied Localizer parameter first via its indexer (overridden.ResourceNotFound), falling back to L (an IStringLocalizer<RoleAdminEditResources>) only when the app's localizer does not carry the key; the same shape repeats verbatim in RoleAdminList and UserAdminList<TUser>.
• Walkthrough:
  • State (39-59): GeneralAreaKey const "Group.General" (39, the resource key for an ungrouped permission), a component-scoped CancellationTokenSource (41), the LatestLoadGuard _load (42, supersedes an in-flight load), _compiled/_stored as HashSet<string>(StringComparer.Ordinal) (47-48, IDE0028 suppressed because a collection expression cannot carry the comparer), _groups (51, the display-ready PermissionGroup list), _loadResult/_saveResult (52-53, the last load/save outcome for inline rendering), _loadedRole (54, guards a redundant reload), _isDirty (58, whether _stored has diverged from what was last loaded or saved, the whole unsaved state a navigation guard protects), _disposed (59).
  • Parameters: Role (62-64, [EditorRequired]), ListHref (67-69, [EditorRequired], the route back to the roster), Heading (72, optional override of the default "Permissions for {role}" title), Localizer (78).
  • OnParametersSetAsync (108): reloads only when Role actually changed (string.Equals(_loadedRole, Role, Ordinal)), so a parent re-render does not throw away an operator's half-made edits. A Role change also supersedes the load still in flight (the doc comment at 103-105), so a late answer for the previous role can never become what Save posts for the current one.
  • Dispose(bool) (116-): cancels and disposes _cts and also disposes _load (127).
  • LoadAsync (160-217): opens a generation with _load.Begin() (162), capturing (token, generation), and snapshots Role into requestedRole (163). It loads the role with that token, then the catalog; after each await it returns silently unless _load.IsCurrent(generation) still holds (174, 187), so a superseded load never touches the form. Either failure sets _loadResult and calls Reset() (219) and returns early. It clears _isDirty (169) up front, since a fresh load has nothing unsaved yet. On success it repopulates _compiled from role.Value.RegisteredPermissions and _stored from role.Value.StoredPermissions, then builds _groups from catalog.Value.Permissions via Group(...). An OperationCanceledException is swallowed only when the load is no longer current (206), and finally clears IsLoading only for the current generation (212), so the newer load owns the spinner.
  • Group(permissions) (233): groups by AreaOf (243, the text before the first : or the localized GeneralAreaKey), orders groups and, within each, members, both with StringComparer.Ordinal, so the rendered layout is deterministic across loads.
  • ReadOnlyHint(permission) (265): the reason text beside a locked checkbox, Hint.Compiled when the code grants it, Hint.ManageRoles for the self-lockout case, empty otherwise.
  • Toggle(permission, granted) (277-289): adds or removes the permission from _stored only, a compiled permission is never touched because it is not a member of _stored to begin with, and sets _isDirty = true (288) unconditionally, since either direction of a toggle is an edit worth protecting.
  • SaveAsync (291-323): posts _stored, ordered, via Roles.SetStoredPermissionsAsync(Role, permissions, _cts.LifetimeToken()) (300). On success it does not trust what it submitted: it re-seeds _compiled and _stored from the server's response (the comment at 308-310 records that the two lists the server reports are disjoint, so a permission the host compiles in moves to the locked half even if the operator's own submission still carried it as stored), and it clears _isDirty (315) now that the form matches what the server holds.
  • The nested PermissionGroup record (328) closes the file.
• Why it's built this way: reseeding from the server's answer rather than the submitted payload is the same "server is the authority, reload rather than assume" principle Sessions applies after a revoke; locking ManageRoles unconditionally is a UI-level backstop for a lockout the server-side authorization gate would otherwise only catch after the fact.
• Where it's used: wrapped by MMCA.ADC's RoleEdit.razor.cs (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.UI/Pages/Roles/RoleEdit.razor.cs), registered in MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs. Tested by MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Administration/RoleAdminEditTests.cs (5 tests), MMCA.ADC/Tests/Modules/Identity/MMCA.ADC.Identity.UI.Tests/Pages/Roles/RoleEditTests.cs, and the e2e page object MMCA.ADC/Tests/E2E/MMCA.ADC.E2E.Tests/PageObjects/Identity/RoleAdminPage.cs. See ADR-116.

RoleAdminList

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/RoleAdminList.razor.cs:28 · Level 4 · class (partial, ComponentBase, IDisposable)

• What it is: the ADR-116 role roster: every declared role with a link into RoleAdminEdit for each, loaded whole in one call rather than through a paged grid.
• Depends on: IRoleAdminUIService (Roles, 49), IStringLocalizer<RoleAdminListResources> (L, 51, see RoleAdminListResources). Externals: same ComponentBase/IStringLocalizer shape as its sibling.
• Concept reinforced: the app-localizer-first T(key, args) fallback RoleAdminEdit introduces (100-112 here, identical shape). [Rubric §27, Internationalization].
• Walkthrough:
  • State (30-33): _cts, _roles as IReadOnlyList<RolePermissionsResponse> (33, defaulting empty), _disposed.
  • Parameters: Heading (36, optional), EditHref (39-41, [EditorRequired] Func<string, string> that builds the route to one role's editor), Localizer (47).
  • OnInitializedAsync (69) calls LoadRolesAsync once.
  • LoadRolesAsync (114): calls Roles.GetAllAsync(_cts.LifetimeToken()) (121), stores the whole Result in _loadResult (59, private field) for inline failure rendering, and sets _roles to the result's value on success or empty on failure.
  • Dispose pattern (Dispose(bool), 76): the same idempotent cancel-and-dispose shape as RoleAdminEdit and Sessions.
• Why it's built this way: unlike UserAdminList<TUser>, which pages through MudDataGrid's server-data contract, this component loads the entire roster in one GetAllAsync call: the declared-role set is small and bounded by the app's own role list, so a paging protocol would add ceremony without solving a real scale problem.
• Where it's used: wrapped by MMCA.ADC's RoleList.razor.cs (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.UI/Pages/Roles/RoleList.razor.cs), registered in MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs. Tested by MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Administration/RoleAdminListTests.cs (4 tests), MMCA.ADC/Tests/Modules/Identity/MMCA.ADC.Identity.UI.Tests/Pages/Roles/RoleListTests.cs, and the e2e page object MMCA.ADC/Tests/E2E/MMCA.ADC.E2E.Tests/PageObjects/Identity/RoleAdminPage.cs. See ADR-116.

UserAdminList<TUser>

MMCA.Common.UI · MMCA.Common.UI.Pages.Administration · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Administration/UserAdminList.razor.cs:47 · Level 5 · class (partial, generic, constrained where TUser : IUserAdminDTO)

• What it is: a drop-in, generic account roster component covering the ADR-116 user-administration operator actions (lock, unlock, change role, optional delete), built as a component rather than a page so the app supplies the route, the authorization attribute, and the detail link.
• Depends on: IUserAdminActionsUIService (Actions, 131, the three account actions, always used regardless of data source), IAppDialogService (Dialogs, 133, confirmation dialogs), AuthenticationStateProvider (135, to find the signed-in operator's own id), IServiceProvider (137, to resolve IUserAdminUIService<TUser> on demand), IStringLocalizer<UserAdminListResources> (L, 139, see UserAdminListResources), MudDataGrid<TUser>/MobileInfiniteScrollList<TUser> (143-144), DeleteConfirmation (145), ListPageActions.ReloadActiveLayoutAsync (215), and IUserAdminDTO as the TUser bound. Its class declaration (UserAdminList.razor.cs:47-49) shows no explicit base in this partial; the overridden members (Title, GridRef, OnInitializedAsync, SaveFilters, RestoreFilters, all protected override) match DataGridListPageBase<TDto>'s shape, so the base is declared on the paired .razor file, not visible in this .cs half.
• Concept introduced, two swappable data paths behind one component. [Rubric §18, UI Architecture & Component Design] assesses whether a reusable component adapts to an app's own backend without a fork. By default LoadServerData (227-243) and FetchMobilePage (245) read through Users, a property that resolves IUserAdminUIService<TUser> from ServiceProvider on demand (158-162) and throws a directive InvalidOperationException naming the missing registration call if it is absent; when the app supplies FetchPage (96-, a delegate taking the grid's filter bag, paging, sort column/direction and a token) that delegate is used instead and the reading service is never resolved. The three account actions (lock/unlock/role-change) always go through IUserAdminActionsUIService regardless of which reading path is active, because both the framework's own endpoint and an app's custom listing endpoint sit in front of the same administration API.
• Concept introduced (2), hiding an operator's destructive power over their own row. [Rubric §11, Security]. CanAdminister(user) (204) is false when _currentUserId (set from AuthenticationStateProvider in OnInitializedAsync, 165) equals the row's UserId, and every administration affordance (lock, role, delete) checks it: an operator who locked, demoted or deleted themselves would lose the very capability needed to undo it (self-service deletion stays on the profile page), and the API itself has no notion of "the caller", so the guard is UI-only and deliberately placed here.
• Walkthrough:
  • SearchFilterKey const "Search" (55, the filter-bag key the search box is injected under when FetchPage owns the fetch).
  • Parameters: Heading (58), DetailHref (61-63, [EditorRequired]), AssignableRoles (70, ordered least to most privileged, offered as "Set role to X" menu items, empty offers only lock/unlock), RoleLabel (78, maps a stored role value to a display label; raw value shown when null), Columns/TrailingColumns/CardContent (81-87, extension render fragments), FetchPage (96-, the custom-endpoint override described above), Sortable (112, defaults false because the framework's own administration endpoint ignores sort and a sortable header would lie), ShowSearch (115, default true), OnDelete (122, null means no Delete affordance at all: account erasure has its own authorization rule the framework does not assume exists), Localizer (129).
  • State: _currentUserId (141), _dataGrid/_infiniteList (143-144, the two render-mode grid handles), _deleteConfirm (145), _searchString (146).
  • RoleText(role) (196): RoleLabel?.Invoke(role) ?? role.
  • SaveFilters/RestoreFilters (208-213): persist and restore _searchString under the "search" key, the list-page filter-persistence contract DataGridListPageBase<TDto> defines.
  • LoadServerData (227-243): routes to FetchPage via InjectSearchFilter when supplied, otherwise to Users.GetPagedAsync with the search term and the Role column's filter value.
  • InjectSearchFilter (264): adds the free-text box to the filter bag under SearchFilterKey, but only when non-blank, so the delegate never has to distinguish "empty" from "absent".
  • SearchTermFrom (278-281): prefers the free-text box; falls back to the Email column's own filter, so both affordances reach the one search parameter the administration endpoint takes.
  • FilterValue (290): reads one column filter's value out of the grid's filter bag, ignoring its operator, since the endpoint takes a value only.
  • ToggleLockAsync (296-322): confirms via IAppDialogService, then calls Actions.LockAsync/UnlockAsync, toasts, and reloads the active layout on success.
  • ChangeRoleAsync (325-348): confirms, calls Actions.SetRoleAsync(user.UserId, role), toasts, and reloads.
  • DeleteUserAsync (352): routes through ListPageActions.DeleteWithConfirmationAsync, the shared delete-confirm-toast-reload sequence, calling OnDelete!(user) (the null-forgiving operator is safe here because the Delete button only renders when OnDelete is non-null).
• Why it's built this way: making Users a computed property resolved from ServiceProvider rather than an [Inject] field is what lets an app that supplies FetchPage skip registering IUserAdminUIService<TUser> at all; a required inject would force every consumer to register a service some of them never call.
• Where it's used: wrapped by MMCA.ADC's UserList.razor.cs (MMCA.ADC/Source/Modules/Identity/MMCA.ADC.Identity.UI/Pages/Users/UserList.razor.cs, 3 references), registered in MMCA.Common/Source/Presentation/MMCA.Common.UI/DependencyInjection.cs, and referenced from RoleAdminEdit.razor.cs and RoleAdminList.razor.cs (shared AdministrationPermissions usage). Tested by MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Administration/UserAdminListTests.cs (8 tests) and MMCA.ADC/Tests/Modules/Identity/MMCA.ADC.Identity.UI.Tests/Pages/Users/UserListTests.cs.
• Caveats / not-in-source: the base class (DataGridListPageBase<TDto>, inferred from the protected override members) is declared in the paired .razor file, which this brief's source excerpt does not include; the inference is from member shape, not a visible @inherits or base-list clause.

ConfirmationState

MMCA.Common.UI · MMCA.Common.UI.Pages.Auth · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/ConfirmEmail.razor.cs:50 · Level 0 · enum (private, nested)

• What it is: the three states ConfirmEmail cycles through while redeeming an email-confirmation link: Working, Form, Confirmed (:50-60).
• Depends on: nothing; a private nested enum with no other type references.
• Concept: a private nested enum used purely as component render-state, the same shape used throughout the UI layer to drive conditional markup without a separate view-model class.
• Walkthrough: Working is the initial field value (:40) and stays current through the automatic redeem attempt in OnAfterRenderAsync (:108-128); Form covers manual entry together with any resend notice or error message above it, and is the state chosen both up front, when neither an email nor a token is available to redeem (:122), and after a failed redeem (:181, :201); Confirmed marks a successful redeem (:193).
• Why it's built this way: a private enum keeps the state vocabulary scoped to the one component that interprets it, rather than promoting it to a shared UI-layer type nothing else needs. The vocabulary is three values, not four: a missing token, a failed redeem, and a completed resend all land the visitor back on the same manual-entry form, with only the _errorMessage / _linkSent fields (not the enum) distinguishing which of those happened.
• Where it's used: only inside ConfirmEmail, which stores it in _state and switches its markup on the value.

Login

MMCA.Common.UI · MMCA.Common.UI.Pages.Auth · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/Login.razor.cs:8 · Level 0 · class (partial, page code-behind)

• What it is: the code-behind half of the shared Login page. The markup half (Login.razor) owns the form; this file owns the two behaviors around external sign-in: turning a refused OAuth round trip into words, and writing the per-attempt OAuth state before a provider redirect.
• Depends on: OAuthFlowStateStore (the OAuthFlowState injection, MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/Login.razor:14), IStringLocalizer<SharedResource> as L (see SharedResource); externals: [SupplyParameterFromQuery] (Microsoft.AspNetCore.Components), BCL InvalidOperationException.
• Concept introduced, a refusal code is a machine value that is mapped to words and never displayed. [Rubric §27, Internationalization] assesses whether user-facing text translates; [Rubric §26, Front-End Security] assesses whether the front end leaks internals. The OAuth completion endpoint sends every refusal back to /login?error={code}, and Error (Login.razor.cs:20-21, bound by [SupplyParameterFromQuery(Name = "error")]) receives it. ExternalSignInErrorMessage (:32-38) maps null or empty to no message, oauth_failed and missing_claims to their own resources, and any other code to RefusalMessage (:40-44). That helper looks up Auth.Login.ExternalError.{code} and, when the resource is missing (ResourceNotFound), falls back to the generic Auth.Login.ExternalError.Refused text. The doc comment (:24-29) explains the split: a code with a recovery path of its own (a locked account, an email already linked to another sign-in, an unverified provider email) gets its own resource, and every other domain code (for example an invalid name) shows the generic refusal. The raw code is never rendered.
• Walkthrough:
  • _externalSignInUnavailable (:14): set when device storage dropped the OAuth attempt; the web-redirect provider buttons are then disabled, because a flow started there would be refused at completion (comment, :11-13).
  • BeginOAuthAttemptAsync() (:52-70): awaits OAuthFlowState.BeginAsync() (:56) and keeps the returned state in _oauthState. If the store throws InvalidOperationException (:58), because storage accepted the write without keeping it (storage full, site data blocked, private mode), it sets _externalSignInUnavailable, shows Auth.Login.ExternalSignInStorageUnavailable, calls StateHasChanged, and returns (:60-64). Otherwise, when a state was written, it re-renders (:66-69).
• Why it's built this way: the completion page refuses a flow whose state it cannot find one redirect later, with no explanation; failing at the click, with the buttons disabled and a reason on screen, turns a silent dead end into an actionable message (doc comment, :46-51). The fallback-to-generic rule means a new domain error code never surfaces as a raw key.
• Where it's used: the Login.razor markup calls BeginOAuthAttemptAsync after first render when external providers exist (Login.razor:193, :180 for _oauthState), and appends the state to the provider redirect query (Login.razor:211-213). Error mapping is covered by MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Auth/LoginErrorQueryTests.cs, and the form models by LoginModel. The OAuth design is ADR-036 and the native callback is ADR-043.
• Caveats / not-in-source: the markup half was read only for the cited lines; the form submit path and provider buttons live there, not here.

PasswordComplexityAttribute

MMCA.Common.UI · MMCA.Common.UI.Pages.Auth · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/PasswordComplexityAttribute.cs:15 · Level 1 · class (sealed attribute)

• What it is: a custom ValidationAttribute that enforces the framework's password-strength rule on any form that sets a new password: at least 8 characters including an uppercase, a lowercase, a digit, and a special (non-alphanumeric) character.
• Depends on: System.ComponentModel.DataAnnotations (ValidationAttribute, ValidationResult, ValidationContext, BCL) and the first-party PasswordComplexity rule in MMCA.Common.Shared.Auth (MMCA.Common/Source/Core/MMCA.Common.Shared/Auth/PasswordComplexity.cs:18).
• Concept introduced, extending DataAnnotations with a domain rule defined once for both sides. [Rubric §24, Forms, Validation & UX Safety] assesses client-side validation parity with the server. Beyond the built-in [Required] and [EmailAddress], a bespoke rule subclasses ValidationAttribute and overrides IsValid, which plugs it straight into the same validator that drives the rest of the form. Parity is structural rather than copied: the attribute does not encode the character rules itself, it calls PasswordComplexity.Evaluate (PasswordComplexity.cs:52), the single Unicode-aware definition the server's StrongPasswordRules also uses (doc comment, lines 6-13; PasswordComplexity.cs:5-17). That definition counts any \p{Lu} as uppercase, any \p{Ll} as lowercase, any \p{Nd} as a digit, and anything that is neither a letter nor a decimal digit as special (PasswordComplexity.cs:27-43), so an accented or CJK letter is a letter, never the special character. What happens to an accepted password server-side (PBKDF2-HMAC-SHA512 hashing with legacy-hash compatibility) is ADR-032; this attribute is only the client-side gate, never the security boundary.
• Walkthrough:
  • [AttributeUsage(AttributeTargets.Property, AllowMultiple = false)] (line 14), so it is applied as [PasswordComplexity] on a single property.
  • The constructor (lines 17-20) seeds the base ErrorMessage with the full English rule, so a usage that does not override the message still shows something actionable. The framework's own forms override it with an ErrorMessageResourceType / ErrorMessageResourceName pair that points at AuthFieldMessages.PasswordComplexity (see RegisterModel).
  • IsValid(object?, ValidationContext) (lines 22-36): one guard (line 24) returns ValidationResult.Success for a non-string, a null/empty input, or a password for which PasswordComplexity.Evaluate is true. Deferring the empty case to RequiredAttribute keeps the field to one message rather than two. On failure it returns a ValidationResult scoped to the member name (lines 34-35) so the message attaches to the right input; the member lookup is null-conditional (validationContext?.MemberName, line 34) because the base class routes the context-free IsValid(object) overload here with no context (comment, lines 29-30), and there is then no member to attach the error to.
  • The message is built with FormatErrorMessage(validationContext?.DisplayName ?? string.Empty) (line 35), not the raw ErrorMessage property (comment, lines 31-33): FormatErrorMessage also resolves an ErrorMessageResourceType / ErrorMessageResourceName pair, which is how the auth models localize inside the attribute, and it returns a plain ErrorMessage or the default message unchanged.
• Why it's built this way: because the rule is an attribute rather than page code, a second form that sets a password gets identical behavior by adding one line, which is exactly how the reset vertical picked it up. Delegating the predicate to a type in the Shared project, the one project both client and server may reference, is what makes the two verdicts identical by construction rather than by review. Delegating emptiness to [Required] keeps one field from stacking two errors. The length cap is deliberately not part of this attribute: PasswordComplexity.MaximumLength is a separate rule with its own message on both sides (PasswordComplexity.cs:24, :45-49).
• Where it's used: applied to RegisterModel.Password (RegisterModel, RegisterModel.cs:28) and to ResetPasswordModel.NewPassword (ResetPasswordModel, ResetPasswordModel.cs:26); evaluated by the LocalizedDataAnnotationsValidator in Register.razor (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/Register.razor:33) and ResetPassword.razor (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/ResetPassword.razor:43). Unit-tested in MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Auth/PasswordComplexityAttributeTests.cs:12; its agreement with the server rule is pinned by the architecture test MMCA.Common/Tests/Architecture/MMCA.Common.Architecture.Tests/Ui/PasswordRuleParityTests.cs:21.
• Caveats / not-in-source: the doc comment (line 7) still describes the attribute as the rule "for the Register form" although the reset form carries it too; the code is the wider truth.

ForgotPasswordModel

MMCA.Common.UI · MMCA.Common.UI.Pages.Auth · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/ForgotPasswordModel.cs:15 · Level 2 · class (sealed)

• What it is: the EditForm backing model for the Forgot Password page: one Email string carrying DataAnnotations for shape validation. Nothing else is collected, because nothing else is needed to start a reset.
• Depends on: System.ComponentModel.DataAnnotations (BCL): [Required], [EmailAddress], and the first-party AuthFieldMessages resource type that supplies both messages.
• Concept introduced, validation deliberately capped at "shape" because of an anti-enumeration contract. [Rubric §24, Forms, Validation & UX Safety] assesses whether a form gives a clear per-field verdict before submit; [Rubric §26, Front-End Security] assesses whether the front end avoids leaking information the back end withholds. Every other form in this group validates as much as it can client-side. This one stops at "is this a syntactically valid address", because the interesting question, does an account exist for it, is one the server refuses to answer: ADR-091 Decision 3 has the reset request succeed on every path (malformed address, no account, throttled, failed send), so a distinguishable client-side outcome would reintroduce exactly the account-enumeration oracle the endpoint exists to avoid. The doc comment (ForgotPasswordModel.cs:7-8) states that trade-off directly.
• Walkthrough: one get; set; property. Email (line 19) carries [Required] and [EmailAddress] (lines 17-18), each naming ErrorMessageResourceType = typeof(AuthFieldMessages) with ErrorMessageResourceName = nameof(AuthFieldMessages.EmailRequired) / nameof(AuthFieldMessages.EmailInvalid), and defaults to string.Empty. The message is read from the shared resources inside the attribute (AuthFieldMessages, MMCA.Common/Source/Presentation/MMCA.Common.UI/Resources/AuthFieldMessages.cs:19, ADR-027), so the form's validator and MudBlazor's own field-level pass (which runs the For property's attributes when a field is touched) both show localized text, never a raw key (AuthFieldMessages.cs:11-17; model doc comment, ForgotPasswordModel.cs:10-12).
• Why it's built this way: sealed and mutable (set, not init) because EditForm two-way-binds the input to the model; keeping the model to one field is what makes the page's anti-enumeration behavior easy to reason about, since there is no second field whose validation could betray a lookup.
• Where it's used: instantiated as _model by ForgotPassword.razor (MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/ForgotPassword.razor:71) and bound by its <EditForm Model="_model" OnValidSubmit="HandleRequestAsync"> plus <LocalizedDataAnnotationsValidator /> (lines 38-39), with the field wired For="@(() => _model.Email)" (line 41) so the message attaches to that input. On valid submit HandleRequestAsync (lines 80-97) calls IAuthUIService.RequestPasswordResetAsync(_model.Email) (line 86, contract at MMCA.Common/Source/Presentation/MMCA.Common.UI/Services/Auth/IAuthUIService.cs:60) inside a try whose catch is empty on purpose (lines 88-91) and whose finally sets _isSubmitted = true unconditionally (line 95), so the confirmation renders for every submitted address whether the call succeeded, failed, or threw.
• Caveats / not-in-source: RequestPasswordResetAsync returns a Result and the call site never inspects it (line 86); the comment block above the method (lines 75-79) records that this is the anti-enumeration rule rather than a dropped result. The gallery E2E suite pins the behavior by asserting the confirmation appears with no backend at all (MMCA.Common/Tests/Presentation/MMCA.Common.UI.E2E.Tests/Auth/ForgotPasswordPageE2ETests.cs:28), with WCAG 2.1 AA scans on both the form and the confirmation state (:41, :50).

LoginModel

MMCA.Common.UI · MMCA.Common.UI.Pages.Auth · MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/LoginModel.cs:15 · Level 2 · class (sealed)

• What it is: the EditForm backing model for the Login page: two string properties (Email, Password) carrying DataAnnotations for field-level validation.
• Depends on: System.ComponentModel.DataAnnotations (BCL): [Required], [EmailAddress]. The only first-party reference is AuthFieldMessages, the resource type its attributes read their messages from.
• Concept introduced, the form-backing model plus a localizing DataAnnotations validator. [Rubric §24, Forms, Validation & UX Safety] assesses whether forms validate at the field level with clear inline messages before submit; [Rubric §26, Front-End Security] assesses that client-side checks are a UX convenience, not the trust boundary; [Rubric §27, Internationalization] assesses whether validation messages translate. A Blazor EditForm binds to a plain model, a <LocalizedDataAnnotationsValidator /> reads the attributes and surfaces a per-field message as the user types, and the submit handler only fires on a valid form. Each message is read from the shared resources through AuthFieldMessages inside the attribute (doc comment, LoginModel.cs:10-12, ADR-027), so the model carries no English text and the localized text shows whether the form's validator or MudBlazor's own field-level pass runs the attribute. The doc comment (LoginModel.cs:7-8) is also explicit that the server remains the authority on whether the credentials are actually valid: the form only prevents an obviously malformed request.
• Walkthrough: two get; set; properties.
  • Email (line 19), [Required] plus [EmailAddress] (lines 17-18), each with ErrorMessageResourceType = typeof(AuthFieldMessages) and the name EmailRequired / EmailInvalid, defaulting to string.Empty.
  • Password (line 22), [Required] with the name PasswordRequired (line 21). There is deliberately no complexity rule here: login validates an existing credential, not a new one, and rejecting a legacy password client-side would lock a user out of their own account.
• Why it's built this way: sealed and mutable because EditForm two-way-binds each input; each attribute names one AuthFieldMessages entry so each field shows exactly one verdict, in the reader's language.
• Where it's used: instantiated as _model and bound by Login.razor (<EditForm Model="_model" OnValidSubmit="HandleLoginAsync"> plus <LocalizedDataAnnotationsValidator />, MMCA.Common/Source/Presentation/MMCA.Common.UI/Pages/Auth/Login.razor:39-40, field at line 172 (not re-verified), inputs bound For="@(() => _model.Email)" and For="@(() => _model.Password)" at lines 48 and 54 so each MudTextField shows its own message). On valid submit the page hands the credentials to IAuthUIService as a LoginRequest (Login.razor:241). Sibling of RegisterModel; its shape rules are unit-tested alongside the other auth models in MMCA.Common/Tests/Presentation/MMCA.Common.UI.Tests/Pages/Auth/AuthModelValidationTests.cs:11.