App Adapter Model
An App is a capability module. It is not inherently part of a Desktop, a
Principle
An App is a capability module. It is not inherently part of a Desktop, a folder, or one Studio. A Studio decides how to mount an App through adapter, presentation, placement, permissions, and runtime context.
Adapter Types
| Adapter | Meaning |
|---|---|
| Local App | A React module bundled with the shell or a workspace package. |
| Route App | An app with a first-class route that can be hosted as a page or shell route. |
| Frame App | An iframe-hosted app. The frame is the implementation detail. |
| Proxied App | An external app wrapped by a Prox OS bridge, proxy, permission, and sandbox layer. |
| Remote App | A future app loaded from a remote bundle or external runtime. |
Internal technical terms should stay clear: do not rename Proxied App to Portal App. User-facing copy may say Connected Web App or External Web App when that is clearer.
Presentation And Placement
The app contract now has optional fields for describing how an app can mount into Studios:
type AppAdapter = 'local' | 'route' | 'frame' | 'proxied' | 'remote'
type AppPresentation =
| 'window'
| 'page'
| 'panel'
| 'widget'
| 'card'
| 'frame'
| 'device-screen'
| 'admin-section'
type StudioAppPlacement = {
studioType: string
presentation: AppPresentation
defaultSize?: unknown
defaultRegion?: unknown
permissions?: string[]
}Examples:
- Pricing is a Local App that can present as a Desktop Runtime window or a route page.
- Hola is a Local App that can welcome users in a Desktop window or at
/hola. - A future docs tool may be a Frame App in the local-only Webview Studio.
- A future mobile preview can mount the same capability as
device-screenunder the local-only Device Studio.
Runtime Ownership
apps/os-shell composes manifests, opens windows, owns routing, and passes app
runtime context. App packages own app interiors and must not deep-import shell
stores. Studio Engines consume app projections and commands through contracts
or registry adapters.