App Registry

Source Files

• Composed registry: apps/os-shell/src/apps/registry.ts
• Platform iframe templates: packages/app-registry (esmadrider-me, /app-dev localhost iframes; see packages/app-registry/README.md)
• App runtime host: apps/os-shell/src/apps/AppRuntime.tsx
• Local app component map: apps/os-shell/src/apps/localAppComponents.tsx
• Types: apps/os-shell/src/apps/types.ts
• Routes: apps/os-shell/src/router.tsx

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.

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.

Route Groups

The router defines normal OS app routes plus /website variants for /app, /app-user, /app-dev, /app-iframe, and /app-os. ViewMode maps normal routes to OS mode and /website routes to single-app website mode. True fullscreen app Spaces are addressed through /spaces/:spaceId instead of website-mode suffixes.

True OS fullscreen is no longer represented by those app-route suffixes. A fullscreen app lives in a dedicated Space and uses /spaces/:spaceId as the shell-level route. Refreshing a stale Space URL gracefully falls back to the default desktop when the in-memory Space no longer exists.

Current Apps

Most non-core apps now use runtime.kind: "os-package" and are imported from @prox-os/os-apps. The /app-dev localhost iframe apps use runtime.kind: "iframe" with templates in @prox-os/app-registry (devOnly: true; omitted from the composed registry in production builds). esmadrider-me is the first production-oriented external iframe under /app-iframe (template packages/app-registry/src/manifests/esmadrider-me.ts). Dev Tools consumes development diagnostics through AppRuntimeContext. Keyboard shortcuts and Display options remain runtime.kind: "local-module" shell control apps.

App ids should use kebab-case without dots or other punctuation.

Future Manifest Shape

The current ShellAppManifest already includes:

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

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
• navigation for app-internal routes
• lifecycle hooks for mount, suspend, resume, and close
• security metadata for sandboxing and external links

The first external package target is packages/os-apps, exposed through runtime.kind: "os-package". New reusable official apps should export a manifest from @prox-os/os-apps first, then be imported into the shell registry.

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.