@owdproject/core 3.4.0 → 4.0.0-alpha.3

package/DESKTOP_KERNEL.md

@@ -1,232 +0,0 @@
-# Desktop kernel contract
-
-Public surface of `@owdproject/core` for themes, apps, and modules. Internal implementation lives under `runtime/internal/` and is not part of this contract.
-
-## Bootstrap order
-
-1. Load `desktop.config.ts` (or legacy `owd.config.ts`) from the Nuxt root.
-2. Validate config; warn only on keys that look like Nuxt options (`ssr`, `vite`, …).
-3. Merge the **full** export into `runtimeConfig.public.desktop` (plus `coreVersion`). Same object is assigned to `appConfig.desktop`. Never spread onto `_nuxt.options`.
-4. Install **Pinia**, then **theme → modules → apps** via `installDesktopPackage` (passes `desktop[configKey]` when a package declares `meta.configKey`).
-5. Client plugin **`desktop-shell-init`** binds Pinia, sets up workspaces, loads default apps, and merges shell keys onto `appConfig.desktop` (before `<Desktop />` renders).
-6. Client plugin **`desktop-register-desktop-apps`** flushes queued `defineDesktopApp` calls (`app:created`; legacy apps may still queue until flush).
-
-## Desktop subsystems
-
-Conceptual map of every desktop area **owned by core**. Use this when sculpting a theme: kernel provides state, contracts, and primitives; the theme renders chrome and wires DOM measurement. This section complements the API tables below — it does not replace them.
-
-```mermaid
-flowchart TB
-  subgraph core [core_kernel]
-    Config[Config_and_extensions]
-    Bootstrap[Shell_bootstrap]
-    Apps[Application_registry]
-    Windows[Window_lifecycle]
-    Layout[Layout_snap_workArea]
-    Workspaces[Workspace_state_API]
-    Overview[Overview_interaction]
-    Dialogs[Dialog_contract]
-    ShellServices[Volume_defaults_terminal]
-  end
-
-  subgraph theme [theme_layer]
-    DesktopEntry[Desktop.vue]
-    Chrome[Taskbar_dock_launcher]
-    WindowChrome[Window_visual_chrome]
-    WorkspaceUI[Workspace_stack_cards]
-  end
-
-  subgraph modules [extension_modules]
-    ModuleFs[module_fs_VFS]
-    KitPV[kit_primevue_explorer_dialogs]
-  end
-
-  Config --> Bootstrap
-  Bootstrap --> Apps
-  Apps --> Windows
-  Windows --> Layout
-  Windows --> Workspaces
-  Workspaces --> Overview
-  Bootstrap --> DesktopEntry
-  DesktopEntry --> Chrome
-  DesktopEntry --> WindowChrome
-  DesktopEntry --> WorkspaceUI
-  Dialogs --> KitPV
-  ModuleFs --> KitPV
-```
-
-### Subsystem catalog
-
-| # | Area | Kernel (core) | Theme / external modules | Key paths |
-|---|------|---------------|--------------------------|-----------|
-| 1 | **Bootstrap & shell init** | Pinia bind, workspace bootstrap, default-app load, shell key merge on `appConfig.desktop`. Plugins: `desktop-shell-init`, `desktop-register-desktop-apps`, `resize.client`. | Theme `Desktop.vue` mounts after `$desktopShellReady`. | `runtime/utils/initDesktopShell.ts`, `runtime/plugins/01.desktop-shell-init.client.ts`, `runtime/plugins/02.desktop-register-desktop-apps.client.ts` |
-| 2 | **Desktop configuration** | `defineDesktopConfig`, merge into `runtimeConfig.public.desktop` / `appConfig.desktop`, `useDesktopConfig`, `useDesktopExtension`, runtime overrides via `useDesktopManager().setConfig()`, config validation/warnings. | Theme defaults via `defineDesktopTheme` + `defu`. | `kit/authoring.ts`, `runtime/composables/useDesktopManager.ts`, `runtime/composables/useDesktopConfig.ts` |
-| 3 | **Package installation** | `defineDesktopTheme` / `defineDesktopModule`, `installDesktopPackage`, install order theme → modules → apps, per-package `configKey` namespace merge. | Each theme/app/module is its own Nuxt package. | `kit/authoring.ts` |
-| 4 | **Shell readiness & options** | `useDesktopShellReady` (`$desktopShellReady` after init). `useDesktopShellOptions` reads `systemBar` flags (`enabled`, `position`, `startButton`) — **config only**, no UI. | Theme renders taskbar/start button from those flags. | `runtime/composables/useDesktopShellReady.ts`, `runtime/composables/useDesktopShellOptions.ts` |
-| 5 | **Shell identity & session** | `useDesktopShellIdentity` (guest default, `userHome`, `setShellIdentity` for auth). `useDesktopSession` (`initiateShutdownToStart` → `/start`). | `/start`, `/boot` pages, shutdown/boot animations and styling. | `runtime/composables/useDesktopShellIdentity.ts`, `runtime/composables/useDesktopSession.ts` |
-| 6 | **Application registry** | `defineDesktopApp`, `flushPendingDesktopApps`, `useApplicationManager` (launch, running apps, open windows), `useApplicationEntries` (sorted/filtered launcher list), per-app meta store. | Theme launcher/grid consumes `useApplicationEntries`. | `kit/defineDesktopApp.ts`, `runtime/composables/useApplicationManager.ts`, `runtime/composables/useApplicationEntries.ts`, `runtime/stores/storeApplicationMeta.ts` |
-| 7 | **Window lifecycle** | Internal `WindowController` / `ApplicationController`: focus, z-index, minimize, `setWorkspace`. Global z-index counter and work-area rect in `useDesktopWindowStore`. Per-app window map in `storeApplicationWindows`. | Theme `Window*.vue` wraps kernel primitives; `provide/inject` for `windowController`. See **Window lifecycle** below. | `runtime/stores/storeDesktopWindow.ts`, `runtime/stores/storeApplicationWindows.ts` |
-| 8 | **Layout, maximize, work area** | `useToggleWindowMaximize`, `utilWindowMaximizeLayout`, `utilWindowLayout` (snap rects, bounds restore), `useDesktopWorkArea` writes measured stage rect to store. | Theme measures shell stage DOM and calls `useDesktopWorkArea`. | `runtime/composables/useToggleWindowMaximize.ts`, `runtime/utils/utilWindowMaximizeLayout.ts`, `runtime/utils/utilWindowLayout.ts`, `runtime/composables/useDesktopWorkArea.ts` |
-| 9 | **Drag, Aero snap, edge drop** | `useWindowDragHandlers`, `useWindowSnapDrop`, `utilDetectSnapZone`, `useWorkspaceEdgeDrop`, hint bases `DesktopWindowSnapHintsBase` / `DesktopWorkspaceEdgeHintsBase`. | Theme wires drag in `Window.vue`; styles snap/edge hints. | `runtime/composables/useWindowDragHandlers.ts`, `runtime/composables/useWindowSnapDrop.ts`, `runtime/utils/utilDetectSnapZone.ts`, `runtime/composables/useWorkspaceEdgeDrop.ts` |
-| 10 | **Workspaces — state & API** | `useDesktopStore` (overview flag, z-index seed, default-apps map). `useDesktopWorkspaceStore`: `list`, `active`, `overview`, `createWorkspace`, `removeWorkspace`, `resolveWorkspaceFallback`. `utilWorkspaceWindows` / `countWindowsOnWorkspace`. | Theme reads workspace list for tray, indicators, overview entry. | `runtime/stores/storeDesktop.ts`, `runtime/stores/storeDesktopWorkspace.ts`, `runtime/utils/utilWorkspaceWindows.ts` |
-| 11 | **Workspaces — interaction** | `useWorkspaceManager` (overview keyboard, HTML5 drop between desktops, `removeWorkspace` with window migration). `useWorkspaceOverviewLiveScale`, `useWorkspaceOverviewCapture`, `utilCaptureElementToCanvas`. | Theme overview UI (cards, wallpaper preview, remove button, scale shell). Workspace removal rules: see **Window lifecycle** below. | `runtime/composables/useWorkspaceManager.ts`, `runtime/composables/useWorkspaceOverviewLiveScale.ts`, `runtime/composables/useWorkspaceOverviewCapture.ts` |
-| 12 | **Kernel Vue components** | `DesktopCore`, `DesktopApplicationRender`, `DesktopApplicationWindowsRender`, `DesktopWindow` / `DesktopWindowNav` / `DesktopWindowContent`, `DesktopBackground`, `DesktopTime`, snap/edge hint bases. | `Desktop.vue` wraps `DesktopCore`; theme chrome around window primitives. | `runtime/components/` (`prefix: 'Desktop'` in core `module.ts`; source files e.g. `window/Window.vue`) |
-| 13 | **Dialogs** | Contract `desktopDialogProvider`, `useDesktopDialogs` (theme inject or browser fallback). Inject key: `runtime/constants/desktopShellKeys.ts`. | PV implementation: `@owdproject/kit-primevue` (`createDesktopDialogs`). | `runtime/dialogs/desktopDialogProvider.ts`, `runtime/composables/useDesktopDialogs.ts` |
-| 14 | **Secondary shell services** | `useDesktopDefaultAppsStore` + `useDesktopManager` default-app routing. `useDesktopVolumeStore` (master volume). `useTerminalManager` (command registry; `app-terminal` registers commands). | Theme volume control, terminal UI, “open with” flows. | `runtime/stores/storeDesktopDefaultApps.ts`, `runtime/stores/storeDesktopVolume.ts`, `runtime/composables/useTerminalManager.ts` |
-| 15 | **Global shell behaviour** | `useBlockNonInputContextMenu` (desktop-style context menu policy). `useDesktopStore` persistence when `@owdproject/module-persistence` is installed. Pinia ids: `desktop`, `desktop/workspace`, `desktop/window`, `desktop/volume`, `desktop/defaultApps`, `desktop/application/${appId}/windows`, `desktop/application/${appId}/meta`. Legacy `owd/*` keys are migrated once on client boot via `migratePersistedStoreIds`. | Theme chooses where to call context-menu blocking; boot/shutdown pages. | `runtime/composables/useBlockNonInputContextMenu.ts`, `runtime/stores/storeDesktop.ts`, `runtime/stores/storeIds.ts`, `runtime/utils/migratePersistedStoreIds.ts` |
-
-### Out of core (by user-facing area)
-
-| User-facing area | Not in core |
-|------------------|-------------|
-| Launcher / Start menu | Theme (e.g. `NovaLauncherOverlay`) — uses `useApplicationEntries` |
-| Taskbar / Dock / System tray | Theme UI; core exposes `systemBar` / `dockBar` config keys only |
-| Workspace overview cards, wallpaper preview, remove button | Theme layout/CSS; core provides state, scale/capture helpers, `removeWorkspace` API |
-| Explorer file UI (`DesktopExplorer*`) | `@owdproject/kit-primevue` |
-| VFS, paths, headless explorer APIs | `@owdproject/module-fs` |
-| Window titlebar, chrome buttons, shadows | Theme wrappers around `DesktopWindow*` |
-
-## Package layout
-
-| Path | Role | Auto-imported in apps? |
-|------|------|------------------------|
-| `kit/` | Module-time authoring (`defineDesktop*`, `installDesktopPackage`, validation) | No — import `@owdproject/core/kit/*` or root barrel |
-| `runtime/` | Client kernel (composables, stores, utils, components, plugins) | Composables, stores, utils only (via `addImportsDir`) |
-| `runtime/internal/` | Window/application controllers | No |
-| `runtime/constants/` | Shell layout bands, inject keys | No |
-
-## Public API
-
-### Configuration
-
-| Export | Use |
-|--------|-----|
-| `defineDesktopConfig({ theme, apps, modules, ... })` | Root `desktop.config.ts` — `@owdproject/core/kit/authoring` |
-| `defineDesktopModule` / `defineDesktopTheme` | Authoring extension modules and themes (`@owdproject/core/kit/*`); Tailwind v3 + `tailwindcss-primeui` live in `@owdproject/kit-primevue` — themes call `registerThemeTailwindPath` / `registerTailwindPath` from `@owdproject/kit-primevue/kit/registerTailwindPath` after `installModule('@owdproject/kit-primevue')` |
-| `runtimeConfig.public.desktop` | Full merged config (manifest + shell + extension namespaces) |
-| `useDesktopConfig()` | Reactive access to `public.desktop` |
-| `useDesktopExtension(key)` | One extension namespace (`fs`, `terminal`, …) |
-| `hasDesktopModule` / `hasDesktopApp` / `hasDesktopExtension` | Manifest and extension checks (`runtime/composables/useDesktopManifest.ts`) |
-| `useDesktopManager().setConfig()` | Runtime shell overrides on `appConfig.desktop` |
-
-Shell keys in core types: `name`, `defaultApps`, `features`, `systemBar`, `dockBar`, `workspaces`, `explorer`, `docs`. Extension keys (`fs`, `terminal`, …) are typed via **module augmentation** in each package (`types/desktop.d.ts`), not an allowlist in core.
-
-### Applications
-
-| Export | Use |
-|--------|-----|
-| `defineDesktopApp(config)` | App plugin (`app:created` recommended; legacy sync `setup` still queues until flush) |
-| `useApplicationManager()` | Launch entries, list running apps, resolve open windows |
-
-Apps register via Nuxt modules listed in `desktop.config.ts` → `apps`.
-
-### Kernel Vue components (global)
-
-Registered from `runtime/components` with `pathPrefix: false`:
-
-| Component | Role |
-|-----------|------|
-| `DesktopCore` | Kernel shell wrapper (props, workspace init, default slot) |
-| `DesktopApplicationRender` | Iterates running apps; delegates per-app window lists |
-| `DesktopApplicationWindowsRender` | Renders one app's open windows (workspace filter, slot for theme `Window`) |
-| `DesktopWindow` / `DesktopWindowNav` / `DesktopWindowContent` | Window chrome primitives |
-| `DesktopBackground` / `DesktopTime` | Optional shell utilities |
-| `DesktopWindowSnapHintsBase` / `DesktopWorkspaceEdgeHintsBase` | Unstyled snap and workspace-edge drop hints |
-
-Themes expose **`Desktop.vue`** or **`Desktop.client.vue`** as the theme entry point (`app.vue` → `<Desktop />`). Prefer **`Desktop.client.vue`** when the theme uses Pinia in shell chrome so the whole tree stays client-only. Themes wrap `DesktopCore` and kernel window components with theme-specific chrome.
-
-### Stores & composables (auto-imported)
-
-| Symbol | Role |
-|--------|------|
-| `useDesktopStore` | Shell state (workspace overview flag, z-index counter, default-apps map); Pinia id `desktop`; persisted with `module-persistence` |
-| `useDesktopWorkspaceStore` | Active workspace, overview mode, `createWorkspace` / `removeWorkspace`, `resolveWorkspaceFallback` |
-| `useDesktopWindowStore` | Global z-index increment + measured work area (`workArea`, `setWorkArea`) |
-| `useDesktopDefaultAppsStore` | Feature → default app/entry mapping (`getDefaultApp`, `setDefaultApp`) |
-| `useDesktopVolumeStore` | Master volume level |
-| `useWorkspaceManager` | Overview keyboard, HTML5 drop between workspaces, `removeWorkspace` (migrates windows) |
-| `useApplicationManager` | Launch app entries, track running apps and open windows |
-| `useApplicationEntries` | Sorted/filtered app entry list for launchers |
-| `useDesktopDialogs` | Confirm/alert/prompt via theme inject or browser fallback |
-| `useToggleWindowMaximize` | Maximize/restore; work-area-aware via `useDesktopWindowStore.workArea` |
-| `useDesktopShellIdentity` | Shell user (`userId`, `displayName`, `avatarUrl`, `userHome`); Guest default; auth calls `setShellIdentity` |
-| `useDesktopSession` | Shutdown flow (`shuttingDown`, `initiateShutdownToStart` → `/start`) |
-| `useDesktopShellReady` | `true` after `desktop-shell-init` has bound Pinia and bootstrapped workspaces |
-| `useDesktopShellOptions` | Reactive `systemBar` flags from `appConfig.desktop` |
-| `useWindowSnapDrop` / `useWorkspaceEdgeDrop` | Aero snap zones and workspace edge drop while dragging windows |
-| `useWindowDragHandlers` | Theme `Window.vue` drag wiring (snap + edge drop; work area from store) |
-| `useWorkspaceOverviewLiveScale` / `useWorkspaceOverviewCapture` | Overview live fit and optional DOM snapshot capture |
-| `useDesktopWorkArea` | Measure shell stage DOM rect → writes `useDesktopWindowStore.workArea` |
-| `useTerminalManager` | Register and resolve shell terminal commands (used by `app-terminal`) |
-| `useBlockNonInputContextMenu` | Block browser context menu on non-input elements (skipped in debug mode) |
-
-Explorer headless APIs live in **`@owdproject/module-fs`**. PrimeVue explorer UI (`DesktopExplorer*`) is in `@owdproject/kit-primevue`.
-
-### Window lifecycle (internal contract)
-
-`WindowController` (internal) guarantees:
-
-- `focus()` / `actions.bringToFront()` — exclusive focus + monotonic z-index via `useDesktopWindowStore`
-- `minimize()` / `unminimize()` — toggles `state.active`
-- `setWorkspace(id)` — assigns window to a workspace
-
-**Removing a workspace:** `useWorkspaceManager.removeWorkspace(id)` requires at least three desktops (minimum two after removal). Open windows on the removed desktop are **migrated** (not closed) to `resolveWorkspaceFallback(id)` — the last workspace in `list` excluding the removed id. Windows without an explicit `workspace` belong to the active desktop for this purpose. If the active desktop is removed, `active` becomes the fallback target.
-
-Contract tests: `packages/core/test/windowController.contract.test.ts`, `useWorkspaceManager.contract.test.ts`.
-
-## Theme obligations
-
-1. Provide `Desktop.vue` (theme entry) registered as a global component by the theme module.
-2. Wrap kernel components; do not reimplement window manager logic in the theme.
-3. Use `provide/inject` for `windowController` only inside theme `Window*.vue` wrappers.
-4. Install `@owdproject/module-fs` when needed for VFS and headless explorer APIs. PV explorer UI: `@owdproject/kit-primevue`.
-5. Prefer `defineDesktopTheme` so shell defaults merge with `defu(public.desktop, themeDefaults)`.
-
-## Extension packages
-
-Keep these packages **separate** — do not merge explorer UI kits into `module-fs` or core.
-
-| Package | Layer |
-|---------|--------|
-| `@owdproject/core` | Kernel + shell composables/utils/components (flat `runtime/`) |
-| `@owdproject/kit-primevue` | PrimeVue Nuxt module, `createDesktopDialogs`, PV explorer chrome |
-| `@owdproject/module-fs` | ZenFS virtual filesystem + headless explorer (`defineDesktopModule`, `configKey: 'fs'`). Only package that imports `@zenfs/*`. |
-| `@owdproject/module-persistence` | Pinia persistence (optional) |
-| `@owdproject/app-terminal` | Terminal app (`configKey: 'terminal'`) |
-
-Deprecated (empty modules only): `@owdproject/kit-theme`, `@owdproject/kit-fs`, `@owdproject/kit-explorer`. Do not import `@owdproject/kit-*/runtime/*` — use `@owdproject/core`, `@owdproject/module-fs`, or `@owdproject/kit-primevue` directly.
-
-**Stacks** (see also `MIGRATION_3.4.md`):
-
-| Stack | Needs `module-fs`? |
-|-------|-------------------|
-| Core + theme (windows, apps) | No |
-| `kit-primevue` with `{ explorer: false }` (dialogs only) | No |
-| `DesktopExplorer*` (default `kit-primevue`) | Yes — list in `desktop.config.ts` `modules` |
-
-Themed file explorer: `module-fs` in `desktop.config.ts` → `@owdproject/kit-primevue` in theme → theme-specific explorer shell.
-
-Dialog and maximize contracts live in core (`runtime/dialogs/desktopDialogProvider.ts`, `useDesktopDialogs`, `useToggleWindowMaximize`, `useDesktopWindowStore.workArea`). PV dialog **implementation**: `@owdproject/kit-primevue`.
-
-## Migrating packages (3.3.2)
-
-Themes, apps, and extension modules should adopt `defineDesktopTheme` / `defineDesktopModule`, module augmentation for `configKey`, and runtime composables. See **[MIGRATION_3.3.2.md](./MIGRATION_3.3.2.md)** and the full guide in `docs/content/6.setup/5.migrate-packages-3.3.2.md`.
-
-## Package exports (semver-stable)
-
-Supported deep imports from `@owdproject/core`:
-
-- `@owdproject/core/kit/*` — authoring helpers (`defineDesktopConfig`, `defineDesktopModule`, …)
-- `@owdproject/core/runtime/composables/*`
-- `@owdproject/core/runtime/constants/*`
-- `@owdproject/core/runtime/dialogs/*`
-- `@owdproject/core/runtime/utils/*`
-- `@owdproject/core/runtime/stores/*`
-- `@owdproject/core/runtime/components/*`
-- `@owdproject/core/runtime/types/*`
-
-**Not supported:** `@owdproject/core/runtime/internal/*` (controllers and other implementation details). Importing internal paths is not part of the public contract and may break without a major release.
-
-## Versioning
-
-Breaking changes to this contract require a semver major (or minor with explicit `BREAKING CHANGE` in changelog) and coordinated theme updates in separate repos.

package/MIGRATION_3.3.2.md

@@ -1,23 +0,0 @@
-# Migrate to @owdproject/core 3.3.2
-
-**Audience:** maintainers and coding agents updating themes, apps, or extension modules.
-
-Full guide (checklists, before/after, pitfalls): **[docs/content/6.setup/5.migrate-packages-3.3.2.md](../../docs/content/6.setup/5.migrate-packages-3.3.2.md)** (published as `/setup/migrate-packages-3.3.2` on the docs site).
-
-## Agent one-liner
-
-Extension/app `module.ts` → `defineDesktopModule` + `types/desktop.d.ts`; theme `module.ts` → `defineDesktopTheme(definition)` + `installModule('@owdproject/kit-primevue')` + `registerThemeTailwindPath` from kit-primevue (see MIGRATION_3.4.md — the second `import.meta.url` argument was removed in 3.4); keep `defineDesktopApp` in `plugin.ts`; read config via `public.desktop.<configKey>` or `useDesktopExtension`; import authoring helpers from `@owdproject/core/kit/*` (e.g. `defineDesktopModule`), not the root barrel.
-
-## Reference packages (monorepo)
-
-| Package | Pattern |
-|---------|---------|
-| `packages/module-fs` | `defineDesktopModule`, `configKey: 'fs'`, augmentation |
-| `apps/app-terminal` | `defineDesktopModule`, `configKey: 'terminal'`, `defineDesktopApp` in plugin |
-
-## Do not
-
-- Whitelist extension keys in core
-- Export composables from `index.ts`
-- Use `appConfig.terminal` / manual `public.desktop[key] = options` in extension setup
-- Reintroduce `splitDesktopUserConfig`

package/MIGRATION_3.4.md

@@ -1,126 +0,0 @@
-# Migration 3.4 — PrimeVue out of core
-
-## Summary
-
-- **@owdproject/core** no longer installs PrimeVue. Module-time authoring lives in `kit/` (not auto-imported). Shell composables, utils, and hint components use `runtime/` (`composables`, `utils`, `constants`, `components/Desktop/`).
-- **@owdproject/module-fs** — ZenFS virtual filesystem + headless explorer (composables, stores, utils; no `.vue`).
-- **@owdproject/kit-primevue** — Nuxt PrimeVue module, `tailwindcss-primeui`, `createDesktopDialogs`, optional explorer UI (`DesktopExplorer*`; `{ explorer: false }` for dialogs only). Installs Tailwind today (duplicate of kit-tailwind; target: depend on `@owdproject/kit-tailwind`).
-- **@owdproject/kit-tailwind** — optional kit for Tailwind content registration (`registerTailwindPath`, `@nuxtjs/tailwindcss`). Canonical import for apps/themes with utility classes. Used alone on Nuxt UI stacks; PV themes should layer PrimeVue on top.
-- **Tailwind** — no longer installed by core. Register globs from `@owdproject/kit-tailwind/kit/registerTailwindPath`; PV themes also run `installModule('@owdproject/kit-primevue')` which installs Tailwind + PrimeUI preset.
-- **@owdproject/kit-theme**, **kit-fs**, **kit-explorer** — deprecated (empty Nuxt modules). **No Vite import shims** — update sources to explicit paths below.
-
-## Stacks (what is optional)
-
-| Stack | `desktop.config` `modules` | Theme |
-|-------|---------------------------|--------|
-| Desktop only | — (no `module-fs`) | theme only |
-| PV dialogs | — | `installModule('@owdproject/kit-primevue', { explorer: false })` |
-| PV file explorer | `['@owdproject/module-fs', …]` | `installModule('@owdproject/kit-primevue')` |
-
-`module-fs` is optional at the **app** level (omit from `desktop.config` if you do not need a VFS). It is **required** when you mount `DesktopExplorer*` (default `kit-primevue`).
-
-## Themes (demo PV)
-
-```ts
-await installModule('@owdproject/kit-primevue')
-```
-
-Dialogs only (no explorer components, no `module-fs`):
-
-```ts
-await installModule('@owdproject/kit-primevue', { explorer: false })
-```
-
-Remove `kit-theme`, `kit-explorer` from `package.json` / `installModule`. Keep mounting theme `<ConfirmDialog />` groups.
-
-Dialog plugin example (core inject key):
-
-```ts
-import { DESKTOP_DIALOG_PROVIDER_KEY } from '@owdproject/core/runtime/constants/desktopShellKeys'
-import { createDesktopDialogs } from '@owdproject/kit-primevue/runtime/dialogs/createDesktopDialogs'
-```
-
-Or rely on kit-primevue client plugin (no theme plugin needed).
-
-## Imports
-
-| Old | New |
-|-----|-----|
-| `@owdproject/kit-theme/runtime/composables/*` | `@owdproject/core/runtime/composables/*` |
-| `@owdproject/kit-fs/runtime/*` (headless) | `@owdproject/module-fs/runtime/*` |
-| `@owdproject/kit-explorer/runtime/composables/*` | `@owdproject/module-fs/runtime/composables/*` |
-| `@owdproject/kit-explorer/runtime/components/*` | `@owdproject/kit-primevue/runtime/components/explorer/*` |
-| `@owdproject/kit-fs/runtime/components/*` | `@owdproject/kit-primevue/runtime/components/explorer/*` |
-| `createDesktopDialogs` from kit-theme | `@owdproject/kit-primevue/runtime/dialogs/createDesktopDialogs` |
-| PV explorer UI (Workspace, FileEntry, Frame, …) | `@owdproject/kit-primevue` (`DesktopExplorer*`) |
-| Shell snap/edge hints | `@owdproject/core` (`DesktopWindowSnapHintsBase`, `DesktopWorkspaceEdgeHintsBase`) |
-| `provideDesktopWorkArea` / `desktopWorkAreaKey` | `useDesktopWorkArea(shellStageRef)` → `useDesktopWindowStore.workArea` |
-| `useDesktopWindowDragHandlers` / `*Injected` | `useWindowDragHandlers` |
-| `useFileSystemExplorer` | `useExplorerWindow` |
-| `@owdproject/core/runtime/utils/defineDesktop*` | `@owdproject/core/kit/authoring` |
-| `@owdproject/core/runtime/utils/utilDesktop` (`defineDesktopApp`) | `@owdproject/core/kit/defineDesktopApp` |
-| `registerTailwindPath` from core | `@owdproject/kit-tailwind/kit/registerTailwindPath` (canonical; also re-exported from kit-primevue during transition) |
-| `defineDesktopTheme(definition, import.meta.url)` (auto Tailwind) | `defineDesktopTheme(definition)` + `registerThemeTailwindPath(nuxt, import.meta.url)` from kit-tailwind after theme installs its UI kit |
-| `runtime/utils/utilHasDesktop` | `runtime/composables/useDesktopManifest` (`hasDesktop*`) |
-| `runtime/utils/windowMaximizeLayout` | `runtime/utils/utilWindowMaximizeLayout` |
-| `runtime/utils/utilWindow` | `runtime/utils/utilWindowControllerAdapter` |
-
-### Tailwind content registration
-
-`@nuxtjs/tailwindcss` is installed by `kit-tailwind` or `kit-primevue` during kit `setup` (not by core). Register globs during each module's `setup`; the active kit merges them on `tailwindcss:config`.
-
-| Caller | API |
-|--------|-----|
-| Theme `module.ts` (after installing its UI kit) | `registerThemeTailwindPath(nuxt, import.meta.url)` from `@owdproject/kit-tailwind/kit/registerTailwindPath` |
-| Apps / extension modules with utility classes | `registerTailwindPath(nuxt, resolve('./path/to/glob'))` from `@owdproject/kit-tailwind/kit/registerTailwindPath` + `"@owdproject/kit-tailwind"` in app `dependencies` |
-
-Registered paths merge into `content.files` (not a plain array — that breaks the generated PostCSS template). Duplicate globs are deduplicated.
-
-## module-fs
-
-Use `useDesktopShellIdentity` from `@owdproject/core/runtime/composables/useDesktopShellIdentity`.
-
-**ZenFS boundary:** `@zenfs/core` (and `@zenfs/dom`, `@zenfs/archives`) are imported only inside `@owdproject/module-fs`. Do not import `@zenfs/*` from `kit-primevue`, themes, or core — use module-fs runtime APIs (e.g. `fetchExplorerEntryMetadata`, `useExplorerWindow`).
-
-Headless explorer: `useExplorerTabs`, `createExplorerWindowMenuItems`, `useExplorerStore`, DnD composables — all from `@owdproject/module-fs/runtime/...`. `useExplorerWindow(window, t)` defaults to `createExplorerFsOperations`.
-
-## Shell identity
-
-See `DESKTOP_KERNEL.md` (`useDesktopShellIdentity`).
-
-## Module naming (3.4)
-
-Runtime identifiers use the `desktop-` prefix. The npm scope `@owdproject/*` and CSS classes/tokens (`.owd-*`, `--owd-*`) are unchanged.
-
-| Surface | 3.4 convention | Legacy (warn only) |
-|---------|----------------|-------------------|
-| Core Nuxt module `configKey` | `desktop` | `owd` (nuxt.config module options) |
-| App `plugin.ts` `name` | `desktop-<slug>-register` | `owd-<slug>-register` |
-| App/module `meta.name` | `desktop-app-<slug>` / `desktop-module-<slug>` | `owd-app-*` / `owd-module-*` |
-| Theme `meta.name` | `desktop-theme-<slug>` | `owd-theme-*` |
-| Desktop manifest file | `desktop.config.ts` | `owd.config.ts` |
-| Kernel Vue source files | `runtime/components/<area>/<Name>.vue` + `prefix: 'Desktop'` | `runtime/components/Desktop/<area>/Desktop<Name>.vue` |
-
-Global component names (`DesktopWindow`, `DesktopCore`, …) are unchanged. Deep imports of hint bases: `runtime/components/workspace/WorkspaceEdgeHintsBase.vue`, `runtime/components/window/WindowSnapHintsBase.vue`.
-
-## Pinia store ids (3.4.1)
-
-Pinia store ids were renamed to match the `desktop-*` runtime naming. CSS classes (`.owd-*`) and npm scope (`@owdproject/*`) are unchanged.
-
-| Legacy id | New id |
-|-----------|--------|
-| `owd/desktop` | `desktop` |
-| `owd/desktop/workspace` | `desktop/workspace` |
-| `owd/desktop/window` | `desktop/window` |
-| `owd/desktop/volume` | `desktop/volume` |
-| `owd/desktop/defaultApps` | `desktop/defaultApps` |
-| `owd/application/${appId}/windows` | `desktop/application/${appId}/windows` |
-| `owd/application/${appId}/meta` | `desktop/application/${appId}/meta` |
-
-When `@owdproject/module-persistence` is installed, persisted state is migrated automatically on the first client boot (`desktop-shell-init` runs `migratePersistedStoreIds` before Pinia hydration). No app or theme code changes are required.
-
-**Breaking only for tools that read raw localStorage keys** (e.g. custom debug scripts expecting `owd/desktop`). In-browser state is preserved via migration.
-
-`pnpm validate:modules` (or `desktop validate`) warns when a package still uses legacy `meta.name: "owd-*"` or Pinia `defineStore` ids containing `owd/`.
-
-Extension modules with their own persisted stores should use the `desktop/<module>/…` id pattern (e.g. `@owdproject/module-fs` explorer: `desktop/module-fs/explorer`). Core migrates only kernel ids (`owd/desktop`, `owd/application/*`); extension packages may omit a localStorage migration — users who already had legacy keys may see a one-time reset of that module's persisted prefs.

package/PLAYGROUND.md

@@ -1,91 +0,0 @@
-# App and theme module playground
-
-Checklist for `@owdproject/app-*`, `@owdproject/theme-*`, and `@owdproject/module-*` packages.
-
-## Layout
-
-```
-package/
-  src/
-    module.ts          # Nuxt module (defineNuxtModule / defineDesktopModule / defineDesktopTheme)
-    runtime/
-      plugin.ts        # apps: defineDesktopApp + name: desktop-<slug>-register
-      components/      # optional Vue UI
-  playground/
-    desktop.config.ts  # defineDesktopConfig({ theme, apps, modules, ... })
-    nuxt.config.ts     # ssr: false, modules: ['@owdproject/core']
-    package.json
-  dist/module.mjs      # after dev:prepare / prepack
-```
-
-## Apps (`@owdproject/app-*`)
-
-- `src/runtime/plugin.ts` calls `defineDesktopApp` from `@owdproject/core/kit/defineDesktopApp`
-- Plugin `name`: `desktop-<slug>-register` (required for `dependsOn` ordering)
-- `src/module.ts` `meta.name`: `desktop-app-<slug>`
-- Tailwind utilities in Vue: `registerTailwindPath` from `@owdproject/kit-tailwind/kit/registerTailwindPath`
-- `"@owdproject/kit-tailwind": "workspace:*"` in app **`dependencies`** (build-time; not replaced by the playground theme)
-- Playground lists the app in `desktop.config.ts` `apps: ['@owdproject/app-<slug>']`
-
-### Theme UI stack vs app Tailwind
-
-| Concern | Package | Who declares it |
-|---------|---------|-----------------|
-| Tailwind content globs (`registerTailwindPath`) | `kit-tailwind` | **App** (and theme) `module.ts` + app `dependencies` |
-| PrimeVue auto-import (`InputText`, `Button`, …) | `kit-primevue` | **PV theme** via `installModule('@owdproject/kit-primevue')` — not all themes |
-| Nuxt UI components | `kit-nuxt-ui` | **`theme-nuxt`** — no PrimeVue |
-
-PrimeVue markup in an app requires a PV theme at runtime. `@owdproject/theme-nuxt` does not install `kit-primevue`.
-
-## Themes (`@owdproject/theme-*`)
-
-- `defineDesktopTheme` from `@owdproject/core`
-- **PrimeVue themes:** `installModule('@owdproject/kit-primevue')` then `registerThemeTailwindPath(nuxt, import.meta.url)` from `@owdproject/kit-tailwind/kit/registerTailwindPath`
-- **Nuxt UI themes:** install `@owdproject/kit-nuxt-ui` (optional) — no PrimeVue
-- `meta.name`: `desktop-theme-<slug>`
-
-## Extension modules (`@owdproject/module-*`)
-
-- `defineDesktopModule` with `meta.configKey` (e.g. `fs`, `terminal`)
-- Module augmentation in `types/desktop.d.ts`
-- Headless modules skip Tailwind registration
-
-## Scripts (publishable packages)
-
-| Script | Purpose |
-|--------|---------|
-| `dev:prepare` | `nuxt-module-build build --stub` + playground `nuxt prepare` |
-| `dev` | Local playground dev server |
-| `dev:generate` | Static GH Pages build (`NUXT_APP_BASE_URL=/<slug>/`) |
-| `prepack` | Full `nuxt-module-build build` before npm publish |
-| `validate` | `desktop validate .` |
-
-Do **not** add a `prepare` script on publishable packages.
-
-## Validate
-
-From package root:
-
-```bash
-pnpm run dev:prepare
-desktop validate .
-```
-
-From monorepo client root:
-
-```bash
-pnpm run validate:modules
-```
-
-See [`MIGRATION_3.4.md`](./MIGRATION_3.4.md) for import path changes (kit-primevue, module-fs).
-
-## Desktop control panel (TUI)
-
-Run `pnpm desktop` from the client monorepo root.
-
-- Toggle apps/modules in the catalog (tabs `1`/`2`), pick a theme in tab `3`, then press `w` to review installs.
-- Each **new** package opens an install wizard: choose **npm**, **GitHub HTTPS**, or **GitHub SSH** (when SSH auth is detected).
-- Catalog columns: `[+]` add, `[-]` remove, `[*]` on desktop; `NPM` / `GIT` / `LOC` source slots; yellow publisher = untrusted.
-- Sort: `o` cycle, `O` open sort picker (Updated, Name, Stars, Installed). Pending toggles affect Installed sort.
-- Settings (`g`): GitHub username (fork clones), trusted orgs list, SSH test (`t`).
-- CLI: `desktop add <pkg> --npm`, `--dev`, `--from <user>`, `--protocol ssh`.

package/dist/module.d.mts

@@ -1,13 +0,0 @@
-import * as nuxt_schema from 'nuxt/schema';
-
-declare const _default: nuxt_schema.NuxtModule<{
-    theme: string;
-    apps: never[];
-    modules: never[];
-}, {
-    theme: string;
-    apps: never[];
-    modules: never[];
-}, false>;
-
-export { _default as default };

package/dist/module.json

@@ -1,9 +0,0 @@
-{
-  "name": "desktop",
-  "configKey": "desktop",
-  "version": "3.4.0",
-  "builder": {
-    "@nuxt/module-builder": "1.0.2",
-    "unbuild": "unknown"
-  }
-}