Core, themes, and apps

Open Web Desktop (OWD) is intentionally split into layers. Keeping them separate is what makes “GNOME vs Windows 95 vs Nova” a theme problem, not a rewrite of your apps.

flowchart TB
  subgraph consumer [Your desktop project]
    config[desktop.config.ts]
    nuxt[nuxt.config.ts]
  end
  subgraph engine [Engine]
    core["@owdproject/core"]
  end
  subgraph kits [Optional kits]
    kitPrimeVue["@owdproject/kit-primevue"]
  end
  subgraph external [External modules]
    modFs["@owdproject/module-fs"]
    modPersist["@owdproject/module-persistence"]
  end
  subgraph presentation [Presentation]
    theme[Theme module]
    apps[App modules]
  end
  config --> core
  core --> theme
  core --> modFs
  core --> modPersist
  theme --> kitPrimeVue
  theme --> modFs
  kitPrimeVue --> modFs
  core --> apps

The engine: @owdproject/core

• Loads desktop.config.ts (legacy owd.config.ts), validates and splits config: theme / modules / apps drive installModule; shell keys merge into runtimeConfig.public.desktop only.
• Bootstrap order: Pinia → theme → modules → apps.
• Owns window/application lifecycle, workspace overview, z-order, and composables such as useApplicationManager, useDesktopManager, useWorkspaceManager.
• Ships Core Vue components (DesktopCore, DesktopWindow, DesktopApplicationRender, …): behaviour and slots, not pixel-perfect OS chrome.
• Does not ship filesystem explorer UI or ZenFS — those live in module-fs and kit-primevue.

If config is missing or invalid, core fails fast with an explicit error.

Public contract: Kernel contract (also DESKTOP_KERNEL.md in the core package).

Kits (shared, optional)

Themes that want a PrimeVue-based look depend on kit-primevue.

Extension modules (external npm)

Not vendored under packages/ in the client repo — install with desktop add. See Package linking.

Themes (pluggable desktop environment)

• Nuxt module: components, styles, boot flow, runtimeConfig.public.desktop defaults via defu.
• Exposes Desktop.vue as the theme entry; wraps DesktopCore and core window primitives with OS-specific chrome.
• Conditionally loads explorer UI when @owdproject/module-fs is in the Nuxt module list.

Apps (Nuxt modules per program)

• Published packages (dist/module.mjs via @nuxt/module-builder).
• Register with defineDesktopApp (entries, commands, window models).
• Must depend only on @owdproject/core (peer) and public kit APIs — never on a specific theme.

Repository map (client monorepo)