Provides the immutable Web document for the configured default AppSurface theme.
AppSurfaceThemeDocument GetDocument()
Gets the current safe document snapshot.
A renderable document, or AppSurfaceThemeDocument.Empty
when it is unsafe.
Builds and retains the immutable Web document from the neutral default-theme resolver.
Configures the browser-local System/Light/Dark preference enhancement for Web theme documents.
The enhancement stores only an explicit Light or Dark selection in browser local storage for the current origin; selecting System removes that value and returns to the operating-system preference. It neither reads nor writes cookies, server-side preference state, or additional document URLs.
AppSurfaceThemePreferenceOptions Snapshot()
Validates and copies this configuration for service registration.
A validated snapshot detached from the caller's mutable options instance.
ArgumentException
StorageKey
is blank, unsafe for an HTML data attribute, or longer than 64 characters.string StorageKey { get; set; }
Source
Gets or sets the origin-scoped local-storage key used for explicit Light or Dark selection.
The default is as_theme
. Keys must contain 1 to 64 non-whitespace characters and cannot include quote or control characters because the value is emitted as an encoded HTML data attribute.
Renders the deterministic browser bootstrap for local theme preferences.
The bootstrap reads the configured origin-scoped local-storage key before the critical theme style renders, applies a System/Light/Dark selection to the document root, and synchronizes every rendered preference control. Storage access is best-effort: blocked or malformed browser storage falls back to the System mode without affecting server rendering, HTTP state, or the canonical document URL. Keep Script
deterministic because CspHash
is the public Content Security Policy source expression for its exact contents.
string Render(string? nonce)
Renders the bootstrap script with an optional encoded CSP nonce.
nonce
A script element that supplies the configured storage key by data attribute.
string StorageKey { get; }
Source
Gets the encoded-data-attribute-safe key read and written by the browser bootstrap.
string CspHash { get; }
Source
Gets the stable sha256-
source expression for Script
.
Provides the stable CSP source hash for the opt-in theme-preference bootstrap.
The hash covers only the deterministic inline script emitted by <appsurface-theme-head>
after AppSurfaceWebThemingServiceCollectionExtensions.AddAppSurfaceWebThemePreferences(Microsoft.Extensions.DependencyInjection.IServiceCollection, Action{AppSurfaceThemePreferenceOptions}?)
. The configured storage key is supplied by an encoded data attribute, so it does not change this value. A dynamic host can instead supply its request nonce through the TagHelper. Static hosts remain responsible for separately hashing their generated critical styles.
string ScriptHash { get; }
Source
Gets the sha256-
source expression for the deterministic bootstrap script.
Represents the deterministic HTML fragments required to apply one AppSurface theme resolution.
The document contains no request-specific values. In particular, HeadContent
never contains a CSP nonce; the live head TagHelper adds one only to its inline style
element. Only the package serializer can create a renderable instance, so adapters cannot accidentally bypass the validated neutral-theme boundary.
string RootAttributes { get; }
Source
Gets serialized attributes placed on the theme root.
string RootThemeId { get; }
Source
Gets the theme identifier for the root metadata.
string RootThemeMode { get; }
Source
Gets the rendered theme mode for the root metadata.
string RootSchemaVersion { get; }
Source
Gets the rendered payload schema version for the root metadata.
string RootStyle { get; }
Source
Gets the safe color-scheme
declaration for the theme root.
string HeadContent { get; }
Source
Gets serialized head metadata and critical CSS without a nonce.
AppSurfaceThemeDocument Empty { get; }
Source
Gets an empty document used when a resolver cannot produce a safe renderable snapshot.
bool IsRenderable { get; }
Source
Gets a value indicating whether the document contains renderable theme fragments.
Provides the documented request-item key for a host-generated AppSurface theme CSP nonce.
string? Get(HttpContext httpContext)
Gets the host-generated nonce from the current request, when one is available.
httpContext
The nonce supplied by the host, or null
when the host does not use a nonce-based CSP.
Selects one registered AppSurface theme pair from already-authorized host context.
Implement this scoped policy in the Web host when the rendered pair depends on application-owned request context, such as an authorized tenant. The policy is a presentation seam only: it does not establish tenancy, authenticate callers, authorize access, read a cache, or validate a theme identifier supplied by untrusted input.
Return false
when the host intentionally wants the configured default pair. Return true
only with a registered pair identifier. The Web adapter validates that result against the sealed neutral registry before rendering; an empty or unknown id fails closed. A host that wants a missing or unauthorized context to fail owns that decision before this policy returns.
bool TrySelect(out AppSurfaceThemeId themeId)
Attempts to select a registered theme pair for the current host context.
themeId
true
; otherwise ignored.
true
to render themeId
, or false
to render the configured default pair.
Provides one host-selected, prevalidated theme document for a Web request scope.
Provides a cached System-first document for browser-local theme preferences.
The neutral resolver is evaluated exactly once during construction. The resulting document is cached for every request and is empty when the resolved pair cannot safely be serialized. This provider does not inspect HTTP state or browser storage; the deterministic bootstrap performs browser-local selection after rendering.
AppSurfaceThemeDocument GetDocument()
Gets the cached document without re-resolving the configured theme pair.
The cached renderable document, or an empty document when the resolved pair was unsafe.
Rejects a document-provider replacement that bypasses the selection adapter.
Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
Validates the resolved document-provider contract after host pipeline composition.
void Validate()
Validates that no later registration replaced the opt-in selection provider.
Marks the browser-preference adapter so conflicting registrations fail predictably.
Marks the selection adapter so duplicate registration fails predictably.
Retains the mutable registration collection until startup can validate its final selection contract.
void ValidatePolicyLifetime()
Rejects a later policy registration that changes the effective service lifetime.
void ValidateNeutralServiceLifetimes()
Rejects a later neutral-service registration that violates the cache lifetime contract.
void ValidateDocumentProviderRegistration()
Rejects a later document-provider registration that violates the scoped selection contract.
Serializes validated neutral theme resolutions into deterministic Web document fragments.
AppSurfaceThemeDocument Serialize(AppSurfaceThemeResolution resolution)
Creates a deterministic, nonce-free document for a neutral theme resolution.
resolution
A renderable document, or AppSurfaceThemeDocument.Empty
when the snapshot is unsafe.
AppSurfaceThemeDocument SerializePreference(AppSurfaceThemeResolution resolution)
Creates the System-first document used by the browser-local preference enhancement.
resolution
A document with System, Light, and Dark selectors, or AppSurfaceThemeDocument.Empty
when the resolution is unsafe to render.
This method deliberately replaces the configured startup mode with System while retaining the same Light and Dark pair. The browser bootstrap can then select an explicit branch without changing the URL or duplicating the HTML document. Safety validation is repeated before serialization so an invalid resolution fails closed instead of emitting partially trusted markup.
bool TrySerialize(AppSurfaceThemeResolution? resolution, out AppSurfaceThemeDocument document)
Attempts to create a deterministic document from a neutral theme resolution.
resolution
document
true
when all values are safe to emit; otherwise false
.
string SerializeHeadContent(AppSurfaceThemeDocument document, string? nonce = null)
Adds an encoded nonce to the live inline style in a previously serialized head fragment.
document
nonce
Head content with the nonce applied only to the inline style element.
Builds immutable Web documents for every pair in the sealed neutral registry.
The cache is keyed only by registered pair id because its values contain package-owned CSS and HTML derived from immutable pairs. A pair id is never a host response-cache key: applications remain responsible for partitioning or disabling any cache that contains tenant-specific content, authorization, or other host-owned state.
bool TryGet(AppSurfaceThemeId themeId, out AppSurfaceThemeDocument document)
Attempts to get the prevalidated document for a selected registered pair.
AppSurfaceThemeDocument DefaultDocument { get; }
Source
Gets the ordinary configured-default document used when a policy has no selection.