Internals

Kernel contract

Public API surface of @owdproject/core for themes, apps, and extension modules.

This page summarizes the stable contract between @owdproject/core and themes/apps. Internal implementation under runtime/internal/ is not part of the contract and may change in minor releases.

Source of truth in the repo: packages/core/DESKTOP_KERNEL.md.

Bootstrap order

Load desktop.config.ts (or legacy owd.config.ts).
Validate and split: theme / apps / modules → installModule; other keys → runtimeConfig.public.desktop / appConfig.desktop only.
Install Pinia, then theme → modules → apps.
Client plugin flushes queued defineDesktopApp calls after Pinia is active.

Configuration API

Export	Use
`defineDesktopConfig({ theme, apps, modules, … })`	Root desktop config file
`runtimeConfig.public.desktop`	Shell flags (`workspaces`, `systemBar`, `explorer`, …)
`useDesktopManager().setConfig()`	Runtime shell overrides (defu: new props win)

Allowed shell keys include: name, defaultApps, features, systemBar, dockBar, workspaces, explorer, docs. Unknown keys: dev warning. Nuxt-like keys: rejected with hint.

Applications

Export	Use
`defineDesktopApp(config)`	App register plugin (`owd-*-register`, client-only, `import.meta.server` guard)
`useApplicationManager()`	Launch, list running apps, resolve windows

Kernel Vue components

Component	Role
`DesktopCore`	Shell wrapper
`DesktopApplicationRender`	Running app windows
`DesktopWindow` / `DesktopWindowNav` / `DesktopWindowContent`	Window primitives
`DesktopBackground` / `DesktopTime`	Optional utilities

Themes expose Desktop.vue → app.vue uses <Desktop />.

Stores and composables

Symbol	Role
`useDesktopStore`	Shell state, personalization, default apps
`useDesktopWorkspaceStore`	Active workspace, overview mode
`useDesktopWindowStore`	Global z-index
`useWorkspaceManager`	Overview keyboard + HTML5 workspace drops
`useApplicationManager`	App registry and launch
`useDesktopManager`	Shell config merge

Explorer: useExplorerStore from @owdproject/module-fs (alias useDesktopExplorerStore deprecated).

Window lifecycle (internal contract)

WindowController guarantees:

focus() / bringToFront() — exclusive focus + monotonic z-index
minimize() / unminimize() — toggles state.active
setWorkspace(id) — assigns workspace

Contract tests: windowController.contract.test.ts, useWorkspaceManager.contract.test.ts.

Extension packages

Package	Layer
core shell composables	Shell identity, edge drop, overview — Shell identity
core `runtime/explorer/`	Explorer store, DnD, menu model
`@owdproject/kit-primevue`	PrimeVue dialogs + PV explorer UI
`@owdproject/module-fs`	ZenFS VFS
`@owdproject/module-persistence`	Optional persistence

Versioning

Breaking contract changes require semver coordination with themes (separate repos). Current kernel release line: 3.4.x (Desktop* rename, explorer eviction from core, full public.desktop merge, extension defineDesktopModule + composables — see DESKTOP_KERNEL.md in @owdproject/core).

Package authors: Migrate themes, apps, and modules (3.4). Stack changes (PrimeVue, shell in core): see migration guide.

Edit this pageorReport an issue

Dialog provider

Shared alert, confirm, and prompt API in core; PrimeVue implementation in kit-primevue.

Shell identity

Shared session user for shell UI and per-user VFS paths (useDesktopShellIdentity).