OS Apps

Current Runtime

Reusable app implementations now live primarily in packages/os-apps and are imported by apps/os-shell through the existing registry and renderer bridge.

apps/os-shell still owns shell runtime behavior: routing, desktop grouping, iframe hosting, window manager state, shell settings, and control apps that directly affect the OS surface. Display options and Keyboard shortcuts remain local shell apps for now.

Package Ownership

• apps/os-shell: shell chrome, desktop, OS-level routing, local window manager, shell settings, iframe host, renderer adapter, and shell-coupled control apps.
• packages/os-apps: reusable official OS apps that can run from public app contracts, @prox-os/os-ui, and package-local code. Each app owns internal navigation; the shell must not assume how a window’s UI switches pages.
• packages/app-registry: static iframe manifest templates for esmadrider-me and /app-dev localhost tools (see packages/app-registry/README.md). Consumed by the shell when composing registry.ts; must not import shell or os-apps implementations.
• packages/app-contract: implementation-neutral manifest, window, permission, settings, keyboard, and runtime context types. Router-agnostic: no imports from @tanstack/react-router, react-router, next/router, or other concrete routers. Optional navigation hints on AppRuntimeContext describe generic intent only (navigationMode, initialPath, onNavigate, etc.), not router instances.

In-app routing (first-party vs third-party)

• Shell owns browser URL, window open/focus/close, and route groups (/app, /app-user, /app-os, …).
• First-party os-apps default to TanStack Router for in-window structure, with a separate router instance per app (not the shell router). Prefer createMemoryHistory so in-app paths and search params do not collide with the shell’s Register typings or the browser location.
• Third-party or migrated apps may use React Router, Wouter, Next.js navigation, a small state machine, or no router. Prefer an adapter / wrapper to mount them behind the same manifest + runtime contract; do not force an internal rewrite just to land in Próx OS.
• Remote micro-frontends may share a React singleton when the integration model allows it; do not share a single Router instance across apps—history, base path, loaders, and URL state must stay scoped per app or host contract.

Future adapter folders (incremental; not required for every stack):

packages/os-apps/src/adapters/   # optional; add per integration as needed
  react-router/
  iframe/
  ...

Route split:

• /app/*: personal work, data, and creative apps.
• /app-user/*: user/profile/visitor/preference apps.
• /app-shell/*: target group for shell-coupled apps that remain inside apps/os-shell.
• /app-dev/*: developer-only local tools, docs, project graphs, and API explorers.
• /app-iframe/*: external and standalone iframe apps grouped under Framed Apps.
• /app-os/*: reusable OS, official team, community, developer, and platform operations apps.

/app-shell is still a target split. Current registered routes use /app, /app-user, /app-dev, /app-iframe, and /app-os.

Migrated Apps

These apps now export their React component and manifest from @prox-os/os-apps:

The migrated app implementation files have been removed from apps/os-shell/src/apps. New imports should use @prox-os/os-apps or an app subpath. The shell keeps only runtime adapter files and the local shell control apps listed below.

Local Shell Apps

These apps stay inside apps/os-shell because they are tightly coupled to shell control behavior:

The shell also keeps packages/app-registry (iframe manifest data), iframe/IframeAppHost.tsx, AppRuntime.tsx, registry.ts, types.ts, and localAppComponents.tsx as runtime adapter code.

Package Structure

packages/os-apps/
  package.json
  tsconfig.json
  src/
    index.ts
    shared/
      AppPrimitives.tsx
      defineOsAppManifest.ts
      mock-data.ts
    apps/
      <app>/
        index.ts
        manifest.ts
        <AppName>App.tsx          # often wraps RouterProvider + app-local router
        <app>Router.tsx            # optional: createRoute tree + createRouter factory
        <app>Layout.tsx            # optional: nav + Outlet
        README.md optional

Every app owns its manifest next to the component. defineOsAppManifest stamps the standard runtime.kind: "os-package" metadata and sourcePackage: "@prox-os/os-apps". Apps with multi-section UIs should express sections as routes (and optional search params), not useState switching whole “pages”. Simple single-page apps can stay flat until they grow.

The App Store is the exception where package-local catalog data can include roadmap and concept entries. That catalog must remain separate from the shell runtime registry so concept cards cannot imply that unregistered apps are launchable.

Styling Source Graph

The shell stylesheet must include packages/os-apps/src in its Tailwind source graph. Reusable app interiors rely on package-local utility classes, including arbitrary grid templates for split panes, dense tables, and piano-key style controls. If apps/os-shell/src/App.css stops scanning this package, the components still render but their generated CSS disappears, so many apps collapse into single-column fallback layouts at once.

Boundaries

packages/os-apps may depend on:

• @prox-os/app-contract
• @prox-os/os-ui
• React peer dependencies
• package-local components, data, hooks, and utilities

It must not import:

• apps/os-shell/src/apps/*
• apps/os-shell/src/shell/*
• apps/os-shell/src/window-manager/*
• shell-private Zustand stores, settings implementations, shortcut handlers, or window-manager adapters

If an app needs shell facts, expose a readonly runtime snapshot or a narrow app-contract action first. Do not deep-import shell internals to make a migration pass.

API And State

Current app data is still local mock data or app-local arrays. No app in packages/os-apps performs direct remote fetching yet.

Remote server data should move through app-local API modules and TanStack Query. Zustand remains for browser OS local state only. Shell runtime snapshots are intentionally readonly from the package app perspective.