appplayer_core library

AppPlayer Core — shared library for MCP server connection, bundle handling, and UI runtime orchestration.

This barrel exposes the public stable API (semver-tracked). Internal wiring (ConnectionManager, RuntimeManager, ToolDispatcher, etc.) is available via package:appplayer_core/internals.dart for advanced integrations but is not semver-stable.

Classes

AppDensity
VisualDensity and scrollbar hover policy for the active FormFactor.
AppHandle
AppIconSizes
Icon-size scale. Logical pixels.
AppIconSizesScale
FormFactor-resolved icon sizes. Returned from AppIconSizes.of.
ApplicationDefinition
AppMetadata
Application metadata aggregated from ui://app/info (Online) or the bundle manifest (Local Bundle) — MOD-MODEL-005, FR-META-*.
AppMetadataSink
Host-injected sink for app metadata updates (NFR-EXT-007).
AppNotification
A notification an app (bundle / server) asks the host to display.
AppNotificationPort
Named AppNotificationPort (not NotificationPort) to avoid colliding with mcp_bundle's workflow NotificationPort, a different concept.
AppPlayerCoreService
Top-level entrypoint assembling Connection / Runtime / Session / Dashboard / Tenant layers (MOD-CORE-001, FR-CORE-001~008).
AppSession
Public session handle for a single opened app (MOD-SESSION-001, FR-SESSION-001~004).
AppSpacing
Spacing / padding / gap scale (8-point grid). Logical pixels.
AppSpacingScale
Design-token sets resolved against the active FormFactor.
AppsRegistry<T>
MOD-CORE-REG — single source of truth for the user's registered app list. Reactive surface so shells (Standard / Pro / X / Custom) can listen via ValueListenableBuilder or Provider.watch and rebuild automatically when the list changes (add / remove / update / metadata arrival).
AppTypography
AppTypographyScale
TextTheme resolved against the active FormFactor.
AwaitsReachability
Implemented by a connect error that already knows the endpoint is not there right now, and that something will say when it is back — a lending device that is offline, whose return the account's presence announces.
BackgroundExecutionPort
BackgroundWake
A background wake signal delivered by BackgroundExecutionPort.wakes.
BufferLogger
Logger adapter that pushes every record into a LogBuffer as a LogSource.core entry. Pair with a console adapter inside a CompositeLogger to keep DevTools output intact while also feeding the in-app log viewer for field reports.
BundleEntryPoint
BundleFetcher
Host-injected remote bundle fetcher (NFR-EXT-006).
BundleFileRef
Local filesystem path. Host is expected to pre-resolve file contents into a BundleInlineRef when running in environments where the core must not perform dart:io access (NFR-PORT-004).
BundleInlineRef
Pre-decoded JSON payload.
BundleInstalledRef
Bundle already installed under Core's configured bundle install destination (FR-BUNDLE-009).
BundleRef
Reference to a bundle source (MOD-MODEL-005).
BundleRemoteRef
Remote HTTP(S) URL. Requires a BundleFetcher injection.
CapabilityConsentManager
Gates app (bundle / server) use of a AppCapability: checks the stored grant, prompts on first use, persists the decision, and — for OS-backed capabilities — also requests the platform permission (two-tier gate).
ChainedAppMetadataSink
Forwards metadata to multiple sinks in declaration order. Failures in one sink do not prevent the next from running.
CompositeLogger
Fan-out logger — every record is forwarded to each inner logger. Typical use: CompositeLogger([ConsoleLogger, BufferLogger]) so a single Core diagnostic call lands in DevTools (development) AND the in-app LogBuffer (field report).
ConnectionFailure
ConnectionInfo
Runtime record of an MCP connection attempt and its current state.
ConnectionResult
Result of a ConnectionManager.connect attempt.
ConnectionSuccess
ConsentPrompt
Host-injected consent UI. The core cannot render — the shell shows the prompt and returns the user's decision (FR-CAP-002).
ConsentStore
Persists per-app capability grants (FR-CAP-003). A durable implementation (prefs / secure store) is host-provided; InMemoryConsentStore is the test/default.
ContinuityController
CredentialVault
Host-injected credential store (MOD-STOR-002, NFR-EXT-008).
DashboardBundleRef
Reference used to locate a dashboard bundle (MOD-MODEL-004).
DashboardSession
Public session handle for Dashboard Mode (MOD-SESSION-002, FR-SESSION-005).
DeferredEntry
The result, with the code when there is one.
DeferredEntryResolver
Decides what a launch means. Pure: the platform pieces are the source and the store, and both are injected.
DeferredEntrySource
Reads a code the platform carried across an install, if it can.
EntryChromeLabels
The words the chrome speaks, in the host's language. English defaults so a tier that has not translated still says something true.
EntryContext
How a definition was entered.
EntryDecision
What the host should do next.
EntryFrame
An entry's screen: the issuer on top, then child — the opened target, or a message about why it is not open. Every state of an entry is drawn in this frame, so none of them can forget who is asking.
EntryGrant
The scan's own authority (§5.2). Short-lived, single-medium, scope-limited, and never persisted — it is not an asset credential.
EntryIssuer
Who stands behind the scanned medium.
EntryLeaveScreen
Leaving the application for an external target. The destination is written out and only a tap sends the person there — a replaced sticker cannot move anyone silently.
A link that is an entry, or the reason it is not.
EntryMessage
A message inside an EntryFrame: a title, a body and optional actions, with a way to close.
EntryNotice
A disclosure the host wants rendered before or alongside the document.
EntryOpener
Turns a resolved target into an open session.
EntryPipeline
Applies the resolution rules to a resolver's answer.
EntryResolverPort
Answers an entry code. Implemented per deployment; the platform never assumes where the registry lives, only that something dereferences codes (§2.1 resolver).
EntrySession
Per-runtime holder for entry.* and identity.*.
EntryStateKeys
Reserved state keys the session publishes under. Documents read them through entry.* / identity.* bindings and MUST NOT write them — the state action executor rejects writes to these roots.
EntryStewardRef
The management entry for the medium, present only when the resolved principal may use it (§6.5).
EntrySupport
The issuer operator's contact (platform spec 19 §4.1.3): url (https), phone (E.164), email. Each is optional; a support object carries at least one.
EntryTarget
A resolver's complete answer.
EntryTargetRef
Where an entry points, and where inside it.
ExactNotificationTiming
A port on a platform where on-time delivery of notifications posted for later is a separate grant (Android 12+ "Alarms & reminders"). Elsewhere a later notification is already shown on time and a port has nothing to offer here, so this is a capability a port has or lacks, not a duty of every port. A caller matches for it: if (port case final ExactNotificationTiming t) await t.requestExactTiming();
FirstLaunchStore
Remembers whether this launch is the first after an install.
FormFactorScope
InheritedWidget that pins a FormFactor for a subtree.
HasAppHandle
Trait satisfied by every shell's AppConfig-style entry. Exposes only the handle-resolution surface that AppPlayerCoreServiceActivity needs — keeps core decoupled from the shell's full model shape.
HealthMonitorConfig
Configuration for ConnectionHealthMonitor (NFR-REL-001~003).
HttpEntryResolver
Resolves an entry code against the issuer's own host.
IdentityContext
The principal a session currently acts as.
IdentityPromotion
The result of an PromotionOutcome.promoted attempt and nothing else — identity is set only when the principal actually changed.
InMemoryConsentStore
In-memory grant store (session-scoped). Default for tests; hosts inject a durable store for persistence across restarts.
InMemorySettingsStore
Core default — used when the host does not inject a SettingsStore implementation. Lives in memory and clears on process restart, so production hosts must always supply their own implementation.
InstalledAppBundle
Value object describing a bundle resident under Core's install root (FR-INSTALL-006).
JobScheduler
KvStoragePort
Key-value storage port.
KvStoragePortAdapter
LifecycleCoordinator
LogBuffer
Ring buffer of recent LogEntry records — exposed as a ChangeNotifier so an in-app viewer rebuilds on every push.
LogEntry
Single record stored in LogBuffer. Both AppPlayer Core diagnostics (via BufferLogger) and MCP server logs (via notifications/message) land here so a production user has one place to export when filing an issue. The viewer filters by source / level / scope.
Logger
Host-injected logger interface (NFR-OBS-001).
MCPUIDSLVersion
MCP UI DSL version contract.
MemoryReclaimer
Reclaims re-creatable memory (caches, inactive runtimes) under memory pressure (FR-MEM). Active sessions and persisted data are preserved.
MetricsPort
Observability metrics port (MOD-OBS-002, NFR-EXT-009).
NoOpBackgroundExecutionPort
Default for tests and platforms without background support (desktop/web): nothing runs in the background, foreground behaviour is unaffected.
NoopCredentialVault
No-op implementation used when the host does not configure a vault.
NoopLogger
No-op logger used when the host does not inject one.
NoopMetricsPort
NoOpNotificationPort
Default for tests and platforms without notifications: posts are dropped, permission reads as granted, no taps.
NoOpPlatformPermissionPort
Default for tests and platforms without a permission model (desktop): every permission reads as granted; requests are no-ops.
OpenSourceLicenses
PlatformPermissionPort
RegistryMetadataSink<T>
Default AppMetadataSink that writes metadata back into the shell's AppsRegistry. When AppMetadataProvider.publish fires, the matching registry entry is updated via the shell-supplied merge callback so the launcher tile re-renders with the fresh name / iconUrl / metadataJson without bespoke wiring.
ScheduledJob
ScopedLogger
Logger decorator that injects a fixed scope map into every log call's context. Caller-supplied keys override scope keys on collision. Typical scope: {serverId, handle} so downstream filters can isolate logs per connection / app.
ServerConfig
Server configuration persisted by the host.
ServerStorage
Host-injected storage interface (MOD-STOR-001, FR-STOR-001~006).
ServingAuthorization
What the host answers about credentials for served addresses.
ServingHeaders
Other headers the host sends to a served address — not credentials (an anonymous per-install visitor id that lets a server tell two people on one network apart). Asked before every request on a served connection; return nothing for an address that is not the host's own.
SettingsStore
SlotBindingRule
Rule for binding a slot to a device.
SlotDefinition
Declaration of a single dashboard slot.
TenantContext
Resolved tenant context (MOD-MODEL-003).
TenantSource
Host-injected interface resolving an app code into a TenantContext.
TrustLevelManager
Manages the current trust level and validates permission requirements
ViewModeResolver
Resolves the effective FormFactor by walking the priority chain below:

Enums

AppCapability
A capability an app (bundle / server) can request.
ApplicationSourceKind
AppLifecyclePhase
App lifecycle phases the core reacts to. Mirrors Flutter's AppLifecycleState plus an explicit memoryPressure signal.
AppSource
BackgroundPolicy
How a connection behaves when the app enters the background.
BackgroundWakeKind
Reason the platform woke the app in the background.
BundleAdaptReason
BundleEntryType
Bundle entry point category (MOD-MODEL-005).
BundleInstallReason
BundleLoadReason
BundleSource
Sources from which a dashboard bundle can be loaded.
ConnectionState
Lifecycle states of an MCP server connection (MOD-MODEL-002).
ConsentDecision
DeferredEntryOutcome
What the host should do at launch.
EntryLinkRejection
Why a link was not accepted as an entry.
EntryRejection
Why an entry could not be opened. Distinct from a resolver saying revoked: these are decisions the host made about an otherwise valid answer.
EntryStatus
Whether an entry may be acted on at all (§4.1).
EntryTargetKind
What kind of thing an entry opens (§4.1).
FormFactor
Device form factor class per Material 3 window-size taxonomy.
IdentityPolicy
How much identity an entry asks for (§4.2).
IdentityState
Who the current session acts as (§8.9.2).
IdentitySubjectKind
The kind of party a principal is.
LogLevel
Log severity levels.
LogSource
Origin of a LogEntry — distinguishes AppPlayer's own diagnostic trace from MCP server-emitted notifications/message payloads so the field-report viewer can separate them. Where a record came from.
McpLogLevel
Log levels for MCP protocol
PermissionStatus
PlatformPermission
OS-level permissions the platform features require.
PromotionOutcome
Why a promotion attempt ended the way it did (§8.9.3).
TransportType
Supported MCP transport types.
TrustLevel
Represents the trust level granted to a UI context
ViewMode
User-selected view-mode pin.

Extensions

AppPlayerCoreServiceActivity on AppPlayerCoreService
FR-CORE-ACTIVE-001 — single API for "is this app currently active?". Every shell launcher tile should call this rather than build its own per-tier aggregator.
EntryTargetCodec on EntryTarget
Wire parsing for a resolver's answer.
TransportTypeName on TransportType

Constants

kEntryLeavableSchemes → const Set<String>
Schemes an entry may hand to the operating system. Anything else would let a printed code launch whatever else is installed.

Functions

entryLeaveDestination(EntryTargetRef target) → Uri?
Where an external target leaves to, or null when it must not leave: not external, unparsable, or a scheme outside kEntryLeavableSchemes.
osPermissionFor(AppCapability capability) → PlatformPermission?
Maps a capability to the OS permission it also requires, if any (FR-CAP-006 two-tier gate). Capabilities with no OS-permission backing return null — app consent alone gates them.

Typedefs

EntryFetch = Future<String> Function(Uri url, {Map<String, String> headers})
Performs the request. Returns the response body, or throws.
EntryLeaveOpener = Future<bool> Function(Uri destination)
Opens an address outside the application; answers whether something took it.
IdentityPromoter = Future<IdentityPromotion> Function()
Asks the host to identify the current viewer, or to let go of that identity.
LocalNodeResolver = Future<String> Function(String discoveryRef)
Resolves a local node's discovery identity to a registered server id.
McpLogMessageHandler = void Function(String serverId, Map<String, dynamic> params)
PageLoaderFn = Future<Map<String, dynamic>> Function(String uri)
Runtime-ready application definition common to Online and Local Bundle sources (MOD-MODEL-005, FR-APP-002).
ServerReGrant = Future<ServerConfig?> Function(ServerConfig stale)
Host-provided token re-grant for durable reconnect.