internals library

AppPlayer Core — advanced integration barrel.

Exposes internal wiring components (connection/runtime/bundle/dashboard managers and dispatchers) so advanced hosts can construct custom flows that the public AppSession abstraction does not cover.

No semver guarantee. Anything exported here may change or be removed across minor versions. Prefer package:appplayer_core/appplayer_core.dart whenever possible.

Classes

AgentAtom

ApplicationLoader

Discovers and loads application definitions from an MCP server (MOD-RUNTIME-002, FR-APP-001003, FR-APP-ONLINE-001005).

AppMetadataProvider

Fetches and publishes AppMetadata from Online / Local Bundle sources.

AtomCategory

AtomVerb

One verb declared by an AtomCategory. The bridge turns each verb into a JS function on the atom's host.<key> object.

BundleApplicationAdapter

Converts McpBundle into a runtime-ready ApplicationDefinition (MOD-BUNDLE-004, FR-APP-LOCAL-004~008).

BundleAtom

BundleLoaderAdapter

Loads McpBundle objects from inline / remote / installed sources and validates schema and manifest (MOD-BUNDLE-001, FR-BUNDLE-001/004~010).

BundleResolver

Parses BundleManifest.entryPoint and validates type/entry compatibility (MOD-BUNDLE-002, FR-BUNDLE-002 / FR-APP-LOCAL-002~003).

BundleUriResolver

Resolves bundle:// URIs into runtime-consumable URIs.

ConnectionManager

Manages MCP server connections: create, reuse, disconnect, reconnect, and notify listeners on state changes (MOD-CONN-001, FR-CONN-001~010).

DashboardBundleLoader

Loads dashboard bundles from market URL, inline, Aggregator server, or synthesizes a grid fallback (MOD-DASH-002, FR-DASH-001~003).

DashboardOrchestrator

Composes Dashboard Mode: loads a bundle, binds slots to devices, mounts each device's summary view (MOD-DASH-001, FR-DASH-001, 007~008).

DebugMcpHost

Serves the DebugSurface over a localhost MCP endpoint. One instance per AppPlayerCoreService when the Debug MCP setting is enabled on a desktop platform.

DebugSurface

Owns the capture GlobalKey and the pure-Flutter capture / input primitives. One instance per active Debug MCP host.

HttpBundleFetcher

Host-injected fetcher for market/URL bundles.

JsEvalResult

Result of an evaluate / evaluateAsync call — wraps the JSON-serialized return value from the worker. Mirrors the subset of flutter_js.JsEvalResult callers actually consume.

JsIsolateEvalResult

Result of an evaluate / evaluateAsync call, as returned by a platform branch. Mirrors the subset of a JS engine's eval result callers consume.

JsToolRuntime

McpAtom

NotificationRouter

Routes MCP server-initiated notifications into the runtime / host:

ReattachResult

What a ResourceSubscriber.reattach actually achieved.

ResolvedBundleUri

Resolved target for a bundle:// URI (MOD-BUNDLE-003).

ResourceSubscriber

Handles MCP resource subscribe / unsubscribe, initial read, and runtime binding registration (MOD-RUNTIME-004, FR-RES-001~004).

RuntimeManager

Owns the lifecycle of per-AppHandle MCPUIRuntime instances (MOD-RUNTIME-001, FR-RUNTIME-001~004).

SlotBinder

Matches SlotDefinitions to concrete device IDs using their binding rules (MOD-DASH-003, FR-DASH-004).

SummaryViewResolver

Locates and parses a device's summary view definition (MOD-DASH-004, FR-DASH-005~006).

TenantResolver

Resolves app codes into TenantContext and guards allowlists (MOD-TENANT-001, FR-TENANT-001~006).

ToolDispatcher

Dispatches MCP tool calls and returns the parsed JSON response so the runtime can apply auto-merge against its own state. Host responsibilities here are limited to MCP forwarding, listTools-based existence checks (for clearer error messaging), and exception modelling (MOD-RUNTIME-003, FR-TOOL-001~005).

TransportFactory

Translates ServerConfig into an mcp_client.TransportConfig (MOD-CONN-002, FR-CONN-009).

Functions

atomSurfaceJsLine(String key, List<String> verbs) → String

Emits the host.<key>.<verb> surface for one atom.

hostBridgeBootstrapJs(String sendInvoke) → String

Builds the bootstrap installed into the JS engine.

Typedefs

ClientConnector = Future<Client> Function(TransportConfig transport)

Abstraction over McpClient.createAndConnect to allow injection in tests.

HostAtomDispatcher = Future<Object?> Function(String atomKey, String verb, List<Object?> args)

Dispatcher signature — given an atom key + verb + args list, the host computes the atom's return value (JSON-serializable). Errors thrown from the dispatcher are forwarded to the JS side as __hostReject with the exception's string form.

InProcessToolHandler = Future Function(Map<String, dynamic> params)

In-process tool handler. Returns the parsed JSON value (or null) that the runtime applies auto-merge against — exactly the shape an MCP callTool text response would decode to.

McpLogMessageHandler = void Function(String serverId, Map<String, dynamic> params)

PageLoader = Future<Map<String, dynamic>> Function(String uri)

Page-loader closure accepted by MCPUIRuntime.initialize.

RuntimeLogHandler = void Function(MCPLogRecord record)

Callback invoked when a notifications/message (MCP logging spec) arrives. Hosts typically push the payload into a LogBuffer for the in-app log viewer. Receives one record from the UI DSL runtime's own logger.

ServerReGrant = Future<ServerConfig?> Function(ServerConfig stale)

Host-provided token re-grant for durable reconnect.