App Registry

Source Files

The composed shell registry is the runtime source of truth for route group, window defaults, ownership, permissions, runtime kind, and desktop placement. Pure iframe registration data for non–os-apps bundles lives in @prox-os/app-registry and is merged in registry.ts.

Package ownership is no longer concentrated in @prox-os/os-apps. system-apps is reserved for OS-level apps, while category packages own personal, connector, developer, admin, game, founder, community, and hub apps. The Shell registry imports manifests from the category package roots and should not deep-import app internals. localAppComponents.tsx remains the host-side renderer map that connects app ids to package-exported React components.

The App Store catalog is intentionally broader than the runtime registry. It may display available apps, incubating apps, concepts, templates, Spaces, data source ideas, and AI workflows. Only entries with a real registered runtimeAppId should open through the shell. Roadmap entries must stay visibly labeled as prototype, incubating, coming soon, concept, experimental, or roadmap.

The Studio Engine Model reads the composed registry through apps/os-shell/src/surfaces/surfaceManifestAdapter.ts. That adapter creates WorkspaceSurfaceManifest records from app manifests, uses manifest-level surfaceCapabilities when present, falls back to curated overrides in @prox-os/os-surface, and finally provides conservative window/icon defaults. This keeps Studio Engine modes registry-driven without making the app registry depend on shell renderer internals.

Launch Modes

The composed Shell registry can add launch surface metadata on top of package manifests:

type ShellAppLaunchMode = 'globalWindow' | 'studio' | 'fullscreen' | 'popover'

launchModes states where an app may appear, and defaultLaunchMode states the preferred user-initiated opening behavior. This is shell-level metadata for now, not a new backend contract.

Current rules:

The singleton app window is intentionally MVP-limited to one floating app at a time outside Desktop Runtime. It renders through AppRuntime, so local modules and iframes still use the same manifest and renderer paths as normal windows.

App Adapter And Studio Placement

Apps are capability modules. They do not inherently belong to Desktop Runtime, a route page, or any single folder in the Shell. Desktop Runtime is the strongest multi-window host for apps; a Studio decides how to mount an App through adapter, presentation, and placement metadata.

The shared app contract now exposes:

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[]
}

Adapter meanings:

Presentation examples:

Route Groups

The router defines normal OS app routes plus /website variants for /app, /app-track, /app-data, /app-connectors, /app-edu, /app-health, /app-user, /app-spaces, /app-sports, /app-admin, /app-dev, /app-iframe, /app-os, and /app-hub. ViewMode maps normal routes to OS mode and /website routes to single-app website mode. /app-data/* remains a deprecated compatibility alias that parses to /app-track/*. /app-user-connectors/* remains a deprecated compatibility alias that parses to /app-connectors/*. /app-spaces itself is a root/folder entry that normalizes to /app-spaces/home; the complex Spaces implementation lives at /app-spaces/home, Slidepad lives at /app-spaces/slidepad, and Deployment Spaces lives at /app-spaces/deployments. /app/dreams remains a compatibility alias for /app-health/dreams. Fullscreen app sessions still use the historical /spaces/:spaceId runtime route instead of website-mode suffixes.

True OS fullscreen is no longer represented by those app-route suffixes. A fullscreen app lives in a dedicated runtime Space and uses /spaces/:spaceId as the shell-level runtime route. Refreshing a stale Space URL gracefully falls back to the default desktop when the in-memory Space no longer exists. This route is preserved as current runtime behavior only; new Studio resources should use the Studio URL model, not /spaces/:spaceId.

Current Apps And Entry References

The route and window facts below remain useful when checking the runtime registry. Package ownership should be read through the category package table above and the imports in apps/os-shell/src/apps/registry.ts; older entry references may still point at the original @prox-os/os-apps migration path.

Track apps:

Connector routes now use /app-connectors/*; old /app-user-connectors/* paths are compatibility aliases. New connector routes include /app-connectors/books, /app-connectors/music, /app-connectors/movies, and /app-connectors/airtable, /app-connectors/sports, /app-connectors/events, /app-connectors/tickets, /app-connectors/deployments, and /app-connectors/social, alongside migrated Game, Files, Calendar, Contacts, Wallet, and existing connector surfaces.

New scene app routes:

Sports memory routes live under /app-sports/*, with Football as the richest v0 app for matchdays, World Cup, Champions League, teams, players, stadiums, Fan Passport, jerseys, costs, and memories.

Most package apps use runtime.kind: "os-package" and declare their sourcePackage from the category package that owns the implementation. The /app-dev iframe apps use runtime.kind: "iframe" with templates in @prox-os/app-registry and are exposed by the shell registry in all builds; production URLs still need appropriate Access boundaries. esmadrider-me is the first production-oriented external iframe under /app-iframe (template packages/runtime/app-registry/src/manifests/esmadrider-me.ts). Developer Tools consumes development diagnostics through AppRuntimeContext. Keyboard shortcuts and Display options remain runtime.kind: "local-module" shell control apps.

Alma is intentionally not listed as a normal app manifest. It is a Shell Surface that lives beside the workspace and can open registered apps through structured OS actions. ChatOS remains the registered app-mode archive and text surface for sidecar conversations and logs.

App ids should use kebab-case without dots or other punctuation. The manifest routing.routeBase is the canonical launch base and may use a shorter product slug when the stable user-facing route should differ from the internal app id, for example airtable-viewer at /app/airtable.

Future Manifest Shape

The current ShellAppManifest already includes:

• id, title, shortTitle, icon, description
• category, accent, status, ownership
• desktopPlacement, routeGroup, routing.routeBase
• runtime.kind, runtime.module
• window.defaultWidth, window.defaultHeight, window.resizable, optional window.maximizable
• optional window.minWidth, window.minHeight
• permissions

routing also declares route ownership and bridge preferences through mode, owner, defaultPath, supportsDeepLink, and preferredUrlMode. See app-routing.md for the app-level contract.

Future OsAppManifest should add (see also app-namespace-and-domain-strategy.md):

• namespace / owner handle and mutable slug with aliases and redirect metadata
• version
• sourcePackage or sourceUrl
• dataScopes
• apiDependencies
• capabilities
• featureFlags
• i18nNamespace
• richer navigation metadata for app-internal routes
• lifecycle hooks for mount, suspend, resume, and close
• security metadata for sandboxing and external links

The first-party package target is now the appropriate category package under packages/apps/*-apps, exposed through runtime.kind: "os-package". New apps should choose a category package first, export a manifest from that package's root barrel, and then be imported into the shell registry. Only OS-level apps belong in packages/apps/system-apps.

Relationship To Window Manager

The registry describes what can be opened. The window manager decides what is open now.

Flow:

1. Shell receives an app open request.
2. appRegistry validates the app and provides title, icon, route, permissions, and default window size.
3. useShellStore.openApp creates or focuses a WindowInstance.
4. WindowLayer renders AppWindow.
5. AppRuntime reads the manifest, builds AppRuntimeContext, and delegates local component lookup to the app renderer map.

The window manager should not hardcode app UI. It should only use registry metadata needed for window creation and presentation.

Local app renderers are centralized in apps/os-shell/src/apps/localAppComponents.tsx as a static renderer map. Package apps are imported there as a bridge while AppRuntime.tsx stays focused on runtime context and iframe hosting.