NE.Standard

Platforms

The framework is two halves. The core — everything under NE.Standard.UI.* except the Web packages — knows nothing about HTML, HTTP, SignalR or a browser: it compiles views, runs controllers, keeps the two in sync through a stream of updates, and hands a platform a description of what to draw. A platform renders that description, carries the updates to a client and the client's changes back, and implements the handful of services a controller reaches through its context. Web is the full UI platform that ships today — with NE.Standard.UI.Desktop hosting that Web stack in a native Windows WebView2 window over an in-process HTTP/2 loopback server or a remote host — alongside NE.Standard.UI.Client and NE.Standard.UI.Server for in-process and remote C# clients; this page is the contract a platform builds against.

What the core gives a platform

  • A compiled view. IUIHost.ResolveViewAsync answers a UIViewResolution: the route, the navigation request, the session, and a CompiledView — component nodes with their properties, the binding templates and indexes, the events, interactions, validation rules, item templates and dialogs, all addressed by id. A platform walks the nodes and draws each by its TypeKey; ids are stable for the life of the process, so what it drew can be addressed by every later update.
  • A runtime per client. IUIHost.AttachRuntimeAsync creates or finds the IUIRuntime behind a route with a controller, keyed by session, address and window (UIRuntimeKey, UIPersistenceOptions.Lifetime). The runtime answers the initial values (BuildInitialChangeSetAsync, BuildInitialCollectionChangesAsync), takes the client's writes (ProcessChangeSetFromUIAsync; a platform's endpoint calls it through IUIClientEndpoint.ProcessChangeSetAsync), runs commands (ProcessEventAsync), reads item windows (RequestItemWindowAsync), and the core's own scheduler flushes what the controller changed in the meantime (IUIClientEndpoint.FlushAsync for a platform that flushes itself).
  • The page's own life. A live connection resolves through ResolvePresentedViewAsync, which answers null where the session it presented would have to be issued anew — only the request that opens the view can hand one out — and NamesRuntimeOf says whether an attach lands on the runtime the connection already holds. ReportClientState takes what the page says of itself (shown or hidden, its notification permission); a page's own language, theme or colours switch, once stored, goes to ApplySessionChangeAsync (ReachSessionAsync from a page with no runtime), so the session's other pages follow. A platform that renders on the server first lets a kept runtime hear what moved (HearBeforeRenderAsync) and hands out a key a sign-in issued meanwhile (TakeRenderKey) — IUIRenderEndpoint, the part of the host a platform whose client draws the page from the attach never needs.
  • A stream of updates. Everything the client has to change arrives as a ServerChangeSet of ServerUIUpdates — a value, a collection change, a validation message, a full resync — each naming a component address and a property. A platform applies them to whatever it drew.
  • Client effects. A command or an interaction can raise a ClientEffect (focus, scroll, navigate, open a dialog, show a notification, copy to the clipboard, ...). ClientEffectKinds lists the built-in names; a platform runs the ones it implements and ignores the rest with a log line — a kind is a request, not a guarantee. DownloadFileEffect is the one shaped by the web — it names a path the browser fetches — and a platform whose download service saves the file itself never raises it.
  • The words the chrome needs. UIStrings names every word the framework draws that no author property sets — a picker's "Today", a notification's "Close" — with English text; the platform asks the ITranslator for the session's language and draws that.
  • The theme. UITheme is two UIColorPalettes, a UITypography, a UIThemeShape, and the focus-ring and press-ripple switches — values, not CSS. The web turns them into custom properties; another platform turns them into brushes.
  • Client-side rules. Filter and sort rules on a plain or virtualized items host run on the client. UIComparisonEvaluator in the core is the reference for what an operator answers — text comparison unless the operator is numeric, null reading as the empty string, a non-number comparing false under every numeric operator — and a platform's client follows it, or the two halves disagree about which row is visible.

What a platform implements

UIStartupBase refuses to start without these three. The first is the platform's own, which the web registers in WebStartupBase; the other two ship in Core, registered by UIStartupBase unless the platform registered its own first. A dialog needs nothing of the platform: Context.Dialogs sends its effect through the runtime, over IUIUpdateSink.

Service What it does
IUIUpdateSink Pushes a ServerChangeSet to every attached instance of a runtime, and a command's result to the one instance that raised it.
IUIDownloadStager Stages a stream for the client to fetch as a file and answers the DownloadFileEffect that fetches it, which Context.Downloads sends through the runtime — StandardDownloadStager, in Core, does the staging over IUIFileStore; the platform supplies only IUIDownloadAddressProvider.AddressOf(token), turning a staged token into the address the client fetches it from (the web: /_ne/files/{token}). An in-process platform can write the content straight into a save dialog instead, answer no effect, and needs no address at all.
IUIUploadService Answers the files a FileInput selection carries, by selection id and file id, scoped to the session — StandardUploadService, also in Core, over IUIFileStore.

Optional, and worth having:

  • IUserSessionResolver — the shipped resolver loads the session the client presented and issues a new id when it presented none; a platform only replaces it to source identity differently. What the platform does own is carrying the id: the web puts it in an HttpOnly cookie named by UISessionOptions.ClientKey (under __Host- over HTTPS); an in-process platform holds it in memory.
  • IUIContentAddressResolver — where the platform serves content an IUIContentProvider answers by key (an avatar, a chat background); UIContentAddress is the default implementation, a fixed prefix the platform's startup constructs once at registration (new UIContentAddress(WebContentEndpoint.Prefix) on the web) and registers as the singleton. Reachable as UIApplication.Content and, for a controller, Context.Content.
  • A theme-persistence helper — SetThemeEffect both puts the client into a theme and reports the choice back to the session, so the next render agrees; the session write is UserSessionStoreExtensions.SetThemeModeAsync, a Core helper over IUserSessionStore a platform's theme-switch handler calls (the web: WebUIHub.SetThemeAsync).
  • IUISessionKeyHandover — hands a page the key of the session its sign-in moved to a new id (the web: a one-time token the page trades for its cookie, WebSessionKeys). With none registered, a sign-in still moves the session and its client is left without the key.
  • UIPlatformDefaults — what the platform decides for an option the application left unset: whether missing words are reported, and whether an author's mistake found as a page runs is told to the page's console (the web: both in Development).

And the glue that has no interface, because it is the platform's own shape:

  1. A connection is a UIInstance — a transport id, a WindowId and the navigation request — wrapped with the session into a UIHandle. A window is one top-level surface showing one address (a browser tab, a desktop window); one handle per attached client, and the runtime keeps every attached instance and the update sink sends to all of them.
  2. Resolve, then attach. A page load calls ResolveViewAsync (which runs the view filters and the route authorization) and then AttachRuntimeAsync; the runtime's IsInitialized says whether the controller's OnInitializeAsync has run. DetachRuntime when the connection goes; the core keeps the runtime for DisconnectedRetention so a reconnect finds it.
  3. The phase. ResolveViewAsync takes a UIViewRequestPhase: Open for the request that opens the view and can hand the client a new session id, Attach for a live connection attaching to it. The web calls both, once each per page load; a platform with one step passes Open — that is the phase in which a pending session-id rotation (a host principal's sign-in) is carried out, so a platform that never passes it never rotates. SignInAsync moves the session at once and hands the new key to the platform's IUISessionKeyHandover (above).
  4. Two-way values. A platform decides which of its controls write back and sends a ClientChangeSet of ClientValueUIUpdates; the core accepts a value only for a property declared writable (UIBindingCapabilities.TargetToSource) and coerces it to the property's type (RecursiveValueCoercion).
  5. Items. A static list is rendered by the platform from the compiled template; a bound list arrives as collection inserts and is rendered from the same template on the client. Every item is keyed by its Id, and an address inside a template carries the keys of the enclosing rows as dynamic parameters — the walk that resolves a template against an item is ItemContext in the core (NE.Standard.UI.Compiled), which the web's renderers call and its client mirrors in binding-template-evaluator.ts, held to one shared corpus of cases so the two cannot drift.
  6. A dialog's own dismissal is a client-raised event. UIDialog.OnClose registers a command on the dialog's content component under the reserved event name close; a platform raises it only when the viewer dismisses the dialog (Escape, the backdrop) and never when the server closes it itself, or a controller cannot tell the two apart.
  7. A bound value written as a URL must be checked before it reaches the client. An href, an image src or a background url() built from a bound value is a javascript:/non-image-data: injection surface on both the render path and the live-patch path; the web checks both through one shared helper (WebUrlSafety) rather than trusting the render path and forgetting the patch path or vice versa, and judges an address as the browser's URL parser will read it — /\host, or //host behind a control character or a tab, is another site. A second platform needs the equivalent check on whatever it treats as "safe to write as a link or an image source."
  8. Chrome a component's picker enforces is advisory only. FileInput.MaxFileSize (the web writes data-ui-file-max-size) and any similar picker-side limit are the client refusing early for a better experience; the real limit is still enforced wherever the bytes are received, since a client can simply not send the attribute a picker chrome reads.
  9. UITheme.PressRipple and UITheme.OverlayScrollbars are looks a theme may switch off, not mechanisms a platform must implement. The web reads it at render (data-ui-press-ripple on the root) and answers it with a client engine; a platform that draws presses another way is free to ignore the flag.

Where the seam is drawn

  • Contracts/ and Core/ reference nothing above them and no web package; Web.Abstractions references Shell, never Core, so a render add-on does not drag the engine in.
  • A platform reaches the host through IUIHost and the application through UIApplication, both public; UIHost itself is internal on purpose. Nothing a platform needs is internal: the web slice builds on the core with no InternalsVisibleTo, through the seams a second platform uses — the members above, and the helpers that keep two platforms counting alike: UIAllowanceCharge (what an upload or a staged value counts against the session's allowance, reserved before its bytes are taken), StoredUserSessionResolver.ApplyClaims (the host's principal over a session a side endpoint reads under UIIdentitySource.Claims) and UIApplicationStorage (the application's own folder under the temp folder, for a platform's caches).
  • The wire is JSON only where a wire exists. The converters on UIComponentId, UIProperty, ServerUIUpdate and ClientEffect live with the types so every channel agrees; an in-process platform never serializes and never touches them.