API Reference

API Reference

This page summarizes the public runtime surface. It is not a replacement for source-level API documentation, but it is the fastest way to find the right type and understand where it fits.

Public Surface Map

flowchart LR
    Runtime["ForsettiRuntime"] --> Manager["ModuleManager"]
    Manager --> Loader["ManifestLoader"]
    Manager --> Registry["ModuleRegistry"]
    Manager --> Registration["ModuleRegistrationStore"]
    Manager --> Activation["ActivationStore"]
    Manager --> Surface["UISurfaceManager"]
    Runtime --> Context["ForsettiContext"]
    Context --> Services["ForsettiServiceProviding"]
    Context --> Events["ForsettiEventBus"]
    Context --> Logger["ForsettiLogger"]
    Host["ForsettiHostTemplate"] --> Runtime
    Platform["ForsettiPlatform"] --> Runtime

Loading

Core Runtime

Type	Purpose
ForsettiRuntime	Top-level runtime facade for boot, shutdown, routing, event bus, UI surface manager, and module manager access.
ModuleManager	Discovers, registers, activates, deactivates, restores, persists, and manages the active UI module.
ManifestLoader	Loads and validates bundled manifest JSON files.
CompatibilityChecker	Produces compatibility reports from manifest schema/template, platform, version, and capability policy.
ModuleRegistry	Registers entryPoint factories and creates module instances.
UISurfaceManager	Publishes merged toolbar items, view injections, overlay schema, and theme mask state.

Module Contracts

Type	Purpose
ForsettiModule	Base lifecycle protocol for all modules.
ForsettiUIModule	UI module protocol with uiContributions.
ForsettiAppModule	Specialized UI module for complete single-app modules.
ModuleDescriptor	Runtime identity snapshot for a module.
ModuleManifest	JSON-backed activation contract.
ModuleType	service, ui, or app.
Platform	Supported runtime platforms: iOS and macOS.
SemVer	Semantic version model used by framework and module compatibility checks.

Manifest and Runtime Requirement Model

Type	Purpose
ManifestTemplateVersion	Template contract version, currently 1.0 and 1.1, with 1.1 as current.
Capability	Permission-like capability enum for services, UI contributions, routing, and provider roles.
DefaultModuleRole	Declares default provider roles such as ui, shared_database, authentication, diagnostics, api, or security.
ModuleRuntimeRequirements	Container for I/O, UI, and data isolation requirements.
ModuleIORequirement	Declares a service-facing runtime need with ID, kind, access mode, required flag, and description.
ModuleIOKind	Service family required by an I/O requirement.
ModuleIOAccess	Intended access: read, write, read_write, execute, emit, or consume.
ModuleUIRequirements	Declares accepted UI contribution IDs for template 1.1 modules.
ModuleDataIsolation	Declares data isolation mode, owned store IDs, and required default roles.
ModuleDataIsolationMode	private_to_module or framework_mediated_shared.

Registration and Activation Stores

Type	Purpose
ModuleRegistrationRecord	Persisted manifest identity, hash, capabilities, default role, runtime requirements, and registration time.
ModuleRegistrationStore	Registration record persistence protocol.
InMemoryModuleRegistrationStore	Test and local-memory implementation.
UserDefaultsModuleRegistrationStore	UserDefaults-backed registration record store.
ActivationState	Persisted desired activation state for service and UI modules.
ActivationStore	Activation state persistence protocol.
InMemoryActivationStore	Test and local-memory implementation.
UserDefaultsActivationStore	UserDefaults-backed activation store.

Policy and Entitlements

Type	Purpose
CapabilityPolicy	Evaluates requested capabilities.
AllowAllCapabilityPolicy	Allows requested capabilities.
FixedCapabilityPolicy	Allows only configured capabilities.
CapabilityScopedServiceProvider	Wraps host services so modules can resolve only services covered by granted capabilities.
ForsettiEntitlementProvider	Asynchronous unlock, refresh, restore, and change-stream contract.
AllowAllEntitlementProvider	Unlocks all modules.
StaticEntitlementProvider	Unlocks configured module or product IDs.
StoreKit2EntitlementProvider	StoreKit-backed entitlement provider where StoreKit is available.

UI Contribution Types

Type	Purpose
UIContributions	Container for theme mask, toolbar items, view injections, and overlay schema.
ToolbarItemDescriptor	Toolbar item title/icon/action.
ToolbarAction	Navigate, open overlay, or publish event.
ViewInjectionDescriptor	Slot, view ID, and priority for injected UI.
ThemeMask	Theme declaration model; default manager currently sanitizes it before surface publication.
ThemeToken	Theme key/value pair.
OverlaySchema	Pointer and route collection.
NavigationPointer	Named pointer to a base destination.
OverlayRoute	Route path and destination.
OverlayDestination	Base destination or module overlay destination.

Services, Events, and Diagnostics

Type	Purpose
ForsettiContext	Runtime context with services, events, logging, routing, and scoped module identity.
ForsettiModuleContext	Module-facing context protocol.
ForsettiModuleLogger	Module-bound logging facade.
ForsettiServiceProviding	Service resolver protocol.
ForsettiServiceContainer	Type-keyed service registry.
NetworkingService	Host networking service protocol.
StorageService	Host non-sensitive storage protocol.
SecureStorageService	Host sensitive storage protocol.
FileExportService	Host file export protocol.
TelemetryService	Host telemetry protocol.
SharedDatabaseService	Shared database provider marker protocol.
AuthenticationService	Authentication provider marker protocol.
DiagnosticsService	Diagnostics provider marker protocol.
APIService	API provider marker protocol.
SecurityService	Security provider marker protocol.
ForsettiEventBus	Publish/subscribe event contract.
InMemoryEventBus	In-memory event implementation.
ForsettiEvent	Event type, payload, source module ID, and timestamp.
SubscriptionToken	Event subscription cancellation token.
ModuleCommunicationGuard	Policy gate for module-to-module messaging.
DefaultModuleCommunicationGuard	Default guard for module messages and reserved namespaces.
ForsettiLogger	Logging abstraction.
ConsoleForsettiLogger	Debug console logger.
OSLogForsettiLogger	Platform logger backed by OSLog where available.
KeychainSecureStorageService	Platform secure storage default backed by Keychain where available.
LocalFileExportService	Local export service that sanitizes suggested filenames and writes inside its configured directory.

Host Template Types

Type	Purpose
ForsettiHostController	Observable controller for boot, module lists, activation, selection, purchase restore, toolbar actions, and errors.
ForsettiLaunchActivationStrategy	Explicit launch policy: restore only, activate all eligible for development, or activate specific module IDs.
ForsettiHostRootView	Reusable SwiftUI host shell.
ForsettiHostTemplateBootstrap	Factory helpers for host controller/runtime wiring.
ForsettiHostOverlayRouter	Overlay route and pointer resolver for host template surfaces.
ForsettiViewInjectionRegistry	Maps viewID strings to SwiftUI AnyView builders.

Activation Call Graph

flowchart TD
    Runtime["ForsettiRuntime.boot"] --> Loader["ManifestLoader"]
    Runtime --> Manager["ModuleManager"]
    Manager --> Registration["ModuleRegistrationStore"]
    Manager --> Checker["CompatibilityChecker"]
    Manager --> Entitlements["ForsettiEntitlementProvider"]
    Manager --> Registry["ModuleRegistry"]
    Registry --> Module["ForsettiModule"]
    Module --> Context["ForsettiContext"]
    Context --> Scoped["CapabilityScopedServiceProvider"]
    Manager --> Surface["UISurfaceManager"]

Loading

Error Types to Recognize

Error	Meaning
moduleNotDiscovered	Activation requested for a module ID that was not loaded from manifests.
moduleLocked	Entitlement provider did not unlock the module.
incompatible(report:)	Compatibility report contains an error.
notUIModule	Manifest says ui or app, but factory returned a non-UI module.
moduleIdentityMismatch	Descriptor or module manifest does not match discovered manifest.
missingCapability	UI contribution requires a capability not requested in the manifest.
registrationMissing	Registration store has no record for the discovered manifest.
registrationMismatch	Registration record no longer matches the current manifest.
unsatisfiedRuntimeRequirement	Required provider, capability, data isolation role, or UI declaration is missing.