@owdproject/core 3.1.4 → 3.3.0

package/runtime/stores/storeDesktop.ts

@@ -1,6 +1,41 @@
 import { defineStore } from 'pinia'
 import { ref } from 'vue'
 
+export type DesktopWindowSurface = 'acrylic' | 'solid'
+
+export type DesktopAppearance = 'dark' | 'light'
+
+export type DesktopPersonalization = {
+  windowSurface: DesktopWindowSurface
+  /** Used when windowSurface is solid (CSS color string). */
+  windowTint: string
+  appearance: DesktopAppearance
+}
+
+export const defaultDesktopPersonalization: DesktopPersonalization = {
+  windowSurface: 'acrylic',
+  windowTint: '#2d2d30',
+  appearance: 'dark',
+}
+
+export function mergePersonalization(
+  raw: Partial<DesktopPersonalization> | undefined | null,
+): DesktopPersonalization {
+  const windowSurface =
+    raw?.windowSurface === 'solid' || raw?.windowSurface === 'acrylic'
+      ? raw.windowSurface
+      : defaultDesktopPersonalization.windowSurface
+  const appearance =
+    raw?.appearance === 'light' || raw?.appearance === 'dark'
+      ? raw.appearance
+      : defaultDesktopPersonalization.appearance
+  const tint =
+    typeof raw?.windowTint === 'string' && raw.windowTint.trim()
+      ? raw.windowTint.trim()
+      : defaultDesktopPersonalization.windowTint
+  return { windowSurface, windowTint: tint, appearance }
+}
+
 export const useDesktopStore = defineStore(
   'owd/desktop',
   () => {
@@ -16,7 +51,8 @@ export const useDesktopStore = defineStore(
       window: {
         positionZ: number
       }
-      defaultApps: {[key: string]: string}
+      defaultApps: Record<string, { applicationId: string; entry: string }>
+      personalization: DesktopPersonalization
     }>({
       workspace: {
         overview: false,
@@ -29,11 +65,41 @@ export const useDesktopStore = defineStore(
       window: {
         positionZ: 0,
       },
-      defaultApps: {}
+      defaultApps: {},
+      personalization: { ...defaultDesktopPersonalization },
     })
 
+    function setWindowSurface(value: DesktopWindowSurface) {
+      const base = mergePersonalization(state.value.personalization)
+      state.value.personalization = mergePersonalization({
+        ...base,
+        windowSurface: value,
+      })
+    }
+
+    function setWindowTint(value: string) {
+      const v = value.trim()
+      if (!v) return
+      const base = mergePersonalization(state.value.personalization)
+      state.value.personalization = mergePersonalization({
+        ...base,
+        windowTint: v,
+      })
+    }
+
+    function setAppearance(value: DesktopAppearance) {
+      const base = mergePersonalization(state.value.personalization)
+      state.value.personalization = mergePersonalization({
+        ...base,
+        appearance: value,
+      })
+    }
+
     return {
       state,
+      setWindowSurface,
+      setWindowTint,
+      setAppearance,
     }
   },
   {

package/runtime/stores/storeDesktopDefaultApps.ts

@@ -27,12 +27,12 @@ export const useDesktopDefaultAppsStore = defineStore(
     /**
      * Gets the default app config for a given feature
      */
-    function getDefaultApp(feature: string): DefaultAppConfig {
+    function getDefaultApp(feature: string): DefaultAppConfig | undefined {
       if (!desktopStore.state.hasOwnProperty('defaultApps')) {
         desktopStore.state.defaultApps = {}
       }
 
-      return desktopStore.state.defaultApps[feature] as DefaultAppConfig
+      return desktopStore.state.defaultApps[feature]
     }
 
     /**

package/runtime/stores/storeDesktopWorkspace.ts

@@ -23,13 +23,23 @@ export const useDesktopWorkspaceStore = defineStore(
     function setupWorkspaces() {
       if (desktopStore.state.workspace.list.length === 0) {
         createWorkspace()
-        desktopStore.state.workspace.active = desktopStore.state.workspace
-          .list[0] as string
       }
 
       if (desktopStore.state.workspace.list.length === 1) {
         createWorkspace()
       }
+
+      const list = desktopStore.state.workspace.list
+      const active = desktopStore.state.workspace.active
+      if (!active || !list.includes(active)) {
+        desktopStore.state.workspace.active = list[0] ?? ''
+      }
+    }
+
+    /** Id of the workspace new windows should use (after setupWorkspaces). */
+    function resolveActiveWorkspaceId(): string {
+      setupWorkspaces()
+      return desktopStore.state.workspace.active || desktopStore.state.workspace.list[0] || ''
     }
 
     function setOverview(value: boolean) {
@@ -56,8 +66,10 @@ export const useDesktopWorkspaceStore = defineStore(
       list,
       workspaceActiveIndex,
       setupWorkspaces,
+      resolveActiveWorkspaceId,
       setOverview,
       setWorkspace,
+      createWorkspace,
     }
   },
 )

package/runtime/utils/captureElementToCanvas.ts

@@ -0,0 +1,21 @@
+/**
+ * Renders a DOM subtree to a canvas via html2canvas (optional dependency).
+ * Used for workspace thumbnails / previews; returns null if capture fails or html2canvas is missing.
+ */
+export async function captureElementToCanvas(
+  element: HTMLElement | null | undefined,
+  options?: Record<string, unknown>,
+): Promise<HTMLCanvasElement | null> {
+  if (!element || typeof window === 'undefined') {
+    return null
+  }
+  try {
+    const { default: html2canvas } = await import('html2canvas')
+    return await html2canvas(element, {
+      allowTaint: true,
+      ...(options as object),
+    })
+  } catch {
+    return null
+  }
+}

package/runtime/utils/explorerEntryPath.ts

@@ -0,0 +1,10 @@
+/**
+ * Absolute path for a listing entry under `basePath` (virtual FS paths).
+ * Avoids `//fileName` when `basePath` is `/` or has trailing slashes.
+ */
+export function explorerEntryAbsolutePath(basePath: string, fileName: string): string {
+  const normalizedBase = (basePath ?? '/').replace(/\/+$/, '') || '/'
+  const tail = fileName.replace(/^\/+/, '')
+  if (normalizedBase === '/') return `/${tail}`
+  return `${normalizedBase}/${tail}`
+}

package/runtime/utils/resolveDesktopConfigPath.ts

@@ -0,0 +1,52 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+export const DESKTOP_CONFIG_FILENAME = 'desktop.config.ts'
+export const LEGACY_DESKTOP_CONFIG_FILENAME = 'owd.config.ts'
+
+export const LEGACY_CONFIG_DEPRECATION =
+  '[@owdproject/core] owd.config.ts is deprecated and kept only for backward compatibility; rename to desktop.config.ts (required from @owdproject/core 3.2).'
+
+export type ResolvedDesktopConfigPath = {
+  path: string
+  file: string
+  legacy: boolean
+}
+
+export function resolveDesktopConfigPath(
+  rootDir: string,
+): ResolvedDesktopConfigPath | null {
+  const desktopPath = join(rootDir, DESKTOP_CONFIG_FILENAME)
+  const legacyPath = join(rootDir, LEGACY_DESKTOP_CONFIG_FILENAME)
+  const hasDesktop = existsSync(desktopPath)
+  const hasLegacy = existsSync(legacyPath)
+
+  if (hasDesktop && hasLegacy) {
+    console.warn(
+      '[@owdproject/core] Both desktop.config.ts and owd.config.ts exist; using desktop.config.ts. Remove owd.config.ts.',
+    )
+    return { path: desktopPath, file: DESKTOP_CONFIG_FILENAME, legacy: false }
+  }
+
+  if (hasDesktop) {
+    return { path: desktopPath, file: DESKTOP_CONFIG_FILENAME, legacy: false }
+  }
+
+  if (hasLegacy) {
+    return {
+      path: legacyPath,
+      file: LEGACY_DESKTOP_CONFIG_FILENAME,
+      legacy: true,
+    }
+  }
+
+  return null
+}
+
+export function warnLegacyDesktopConfig(
+  resolved: ResolvedDesktopConfigPath | null | undefined,
+): void {
+  if (resolved?.legacy) {
+    console.warn(LEGACY_CONFIG_DEPRECATION)
+  }
+}

package/runtime/utils/splitDesktopUserConfig.ts

@@ -0,0 +1,85 @@
+/**
+ * Keys consumed by {@link @owdproject/core} module setup (install order).
+ * Must not be spread onto `_nuxt.options`.
+ */
+export const DESKTOP_MODULE_KEYS = ['theme', 'apps', 'modules'] as const
+
+/**
+ * Known desktop shell keys merged into `runtimeConfig.public.desktop` / `appConfig.desktop`.
+ * Additional keys are merged with a dev warning (extensions, theme overrides).
+ */
+export const DESKTOP_RUNTIME_KEYS = new Set([
+  ...DESKTOP_MODULE_KEYS,
+  'docs',
+  'name',
+  'defaultApps',
+  'features',
+  'explorer',
+  'systemBar',
+  'dockBar',
+  'workspaces',
+])
+
+/** Nuxt top-level option names — warn if present in desktop.config (likely misconfiguration). */
+const NUXT_OPTION_KEYS = new Set([
+  'ssr',
+  'modules',
+  'devtools',
+  'vite',
+  'nitro',
+  'runtimeConfig',
+  'app',
+  'appConfig',
+  'css',
+  'plugins',
+  'hooks',
+  'extends',
+  'compatibilityDate',
+  'experimental',
+  'future',
+  'i18n',
+  'tailwindcss',
+  'primevue',
+])
+
+export type SplitDesktopUserConfigResult = {
+  theme?: string
+  apps?: string[]
+  modules?: string[]
+  desktopRuntime: Record<string, unknown>
+}
+
+export function splitDesktopUserConfig(
+  config: Record<string, unknown>,
+  configFile = 'desktop.config.ts',
+): SplitDesktopUserConfigResult {
+  const theme =
+    typeof config.theme === 'string' ? config.theme : undefined
+  const apps = Array.isArray(config.apps)
+    ? (config.apps as string[])
+    : undefined
+  const modules = Array.isArray(config.modules)
+    ? (config.modules as string[])
+    : undefined
+
+  const desktopRuntime: Record<string, unknown> = {}
+
+  for (const [key, value] of Object.entries(config)) {
+    if (DESKTOP_MODULE_KEYS.includes(key as (typeof DESKTOP_MODULE_KEYS)[number])) {
+      continue
+    }
+    desktopRuntime[key] = value
+
+    if (NUXT_OPTION_KEYS.has(key)) {
+      console.warn(
+        `[@owdproject/core] ${configFile}: key "${key}" looks like a Nuxt option and is ignored for _nuxt.options. Move it to nuxt.config.ts; shell values belong under defineDesktopConfig({ systemBar, workspaces, ... }).`,
+      )
+    } else if (!DESKTOP_RUNTIME_KEYS.has(key)) {
+      console.warn(
+        `[@owdproject/core] ${configFile}: unknown desktop key "${key}" — merged into runtimeConfig.public.desktop only.`,
+      )
+    }
+  }
+
+  return { theme, apps, modules, desktopRuntime }
+}

package/runtime/utils/utilCommon.ts

@@ -24,35 +24,3 @@ export function deepEqual(obj1: any, obj2: any) {
   }
   return true
 }
-
-export function deepMerge<T>(target: T, source: Partial<T>): T {
-  function isObject(value: any): value is Record<string, any> {
-    return (
-      value !== null &&
-      typeof value === 'object' &&
-      !Array.isArray(value) &&
-      !(value instanceof Date) &&
-      !(value instanceof RegExp)
-    )
-  }
-
-  if (isObject(target) && isObject(source)) {
-    const result = { ...target }
-
-    for (const key in source) {
-      const targetValue = (target as any)[key]
-      const sourceValue = (source as any)[key]
-
-      if (isObject(sourceValue) && isObject(targetValue)) {
-        // @ts-ignore
-        result[key] = deepMerge(targetValue, sourceValue)
-      } else {
-        result[key] = sourceValue
-      }
-    }
-
-    return result
-  }
-
-  return source as T
-}

package/runtime/utils/utilDesktop.ts

@@ -1,8 +1,33 @@
+import { getActivePinia } from 'pinia'
 import { useApplicationManager } from '../composables/useApplicationManager'
 
-export function defineDesktopApp(config: ApplicationConfig) {
+const pendingDesktopApps: ApplicationConfig[] = []
+
+/**
+ * Register a desktop app. Queues until Pinia is active when theme/app plugins
+ * run before @pinia/nuxt (e.g. published apps using `app:created`).
+ */
+export async function defineDesktopApp(config: ApplicationConfig) {
+  if (import.meta.server) return undefined
+
+  if (getActivePinia()) {
+    const applicationManager = useApplicationManager()
+    return applicationManager.defineApp(config.id, config)
+  }
+
+  pendingDesktopApps.push(config)
+  return undefined
+}
+
+export async function flushPendingDesktopApps() {
+  if (pendingDesktopApps.length === 0 || !getActivePinia()) return
+
+  const queue = pendingDesktopApps.splice(0, pendingDesktopApps.length)
   const applicationManager = useApplicationManager()
-  return applicationManager.defineApp(config.id, config)
+
+  for (const config of queue) {
+    await applicationManager.defineApp(config.id, config)
+  }
 }
 
 export function defineDesktopConfig(config: DesktopConfig) {

package/runtime/utils/validateDesktopUserConfig.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime validation for the object exported from `desktop.config.ts`
+ * (or legacy `owd.config.ts`).
+ */
+export function assertValidDesktopUserConfig(
+  config: unknown,
+  configFile = 'desktop.config.ts',
+): void {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) {
+    throw new Error(
+      `[@owdproject/core] ${configFile} must default-export a non-array object from defineDesktopConfig({ ... }).`,
+    )
+  }
+
+  const c = config as Record<string, unknown>
+
+  if (c.theme != null && typeof c.theme !== 'string') {
+    throw new Error(
+      `[@owdproject/core] ${configFile}: \`theme\` must be a string (npm package name of the theme module).`,
+    )
+  }
+
+  if (c.apps !== undefined) {
+    if (
+      !Array.isArray(c.apps) ||
+      !(c.apps as unknown[]).every((item) => typeof item === 'string')
+    ) {
+      throw new Error(
+        `[@owdproject/core] ${configFile}: \`apps\` must be an array of strings (Nuxt module package names).`,
+      )
+    }
+  }
+
+  if (c.modules !== undefined) {
+    if (
+      !Array.isArray(c.modules) ||
+      !(c.modules as unknown[]).every((item) => typeof item === 'string')
+    ) {
+      throw new Error(
+        `[@owdproject/core] ${configFile}: \`modules\` must be an array of strings (Nuxt module package names).`,
+      )
+    }
+  }
+}

package/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { Nuxt } from '@nuxt/schema'
+import type { ShallowRef } from 'vue'
 import { useApplicationManager } from '../runtime/composables/useApplicationManager'
 
 declare module 'nuxt/schema' {
@@ -16,7 +17,7 @@ interface IApplicationManager {
 
   get appsRunning(): Reactive<IApplicationController[]>
 
-  get windowsOpened(): Reactive<IWindowController[]>
+  get windowsOpened(): Reactive<Map<string, IWindowController>>
 
   get appCategories(): string[]
 
@@ -84,7 +85,8 @@ interface IApplicationController {
   get meta(): { [key: string]: any }
 
   store: Pinia
-  windows: Reactive<Map<string, IWindowController>>
+  windows: Map<string, IWindowController>
+  openWindowCount: ShallowRef<number>
 
   isRunning: boolean
 
@@ -116,7 +118,7 @@ interface IApplicationController {
   get windowsOpened(): Reactive<Map<string, IWindowController>>
 }
 
-interface IWindowController {
+export interface IWindowController {
   application: IApplicationController
   instanced: boolean
   model: string
@@ -134,6 +136,8 @@ interface IWindowController {
   // sizes
   get size(): WindowSize
 
+  get position(): WindowPosition | undefined
+
   // minimize
   get isMinimizable(): boolean
 
@@ -179,14 +183,27 @@ interface IWindowController {
     setTitleOverride(title: string | undefined): void
     resetTitleOverride(): void
   }
+
+  /** Payload restored with window state (e.g. explorer cwd in `path`). */
+  get meta(): { path?: string } & Record<string, unknown>
+
+  /** Chrome menu model (e.g. PrimeVue Menubar). */
+  menu: unknown[]
+
+  setMenu(menu: unknown[]): void
+
+  destroy(): boolean
+
+  /** Set by module-fs when an explorer surface mounts on this window. */
+  fsExplorer?: any
 }
 
-interface WindowContent {
+export interface WindowContent {
   padded?: boolean
   centered?: boolean
 }
 
-interface WindowConfig {
+export interface WindowConfig {
   title?: string
   category?: string
   icon?: string
@@ -309,15 +326,28 @@ type ApplicationEntryVisibility = 'primary' | 'secondary' | 'hidden'
 // DESKTOP
 
 interface IDesktopManager {
-  defaultApps: DefaultAppsConfig
+  defaultApps: import('vue').ComputedRef<Record<string, DefaultAppConfig>>
 
-  getDefaultApp(feature: string)
+  getDefaultApp(feature: string): DefaultAppConfig | undefined
 
   setDefaultApp(
     feature: string,
     application: IApplicationController,
-    command: ApplicationCommand,
-  )
+    entry: string,
+  ): void
+}
+
+interface DocsModuleUserSourceConfig {
+  cwd: string
+  prefix?: string
+  include?: string
+  exclude?: string[]
+}
+
+interface DocsModuleConfig {
+  basePath?: string
+  title?: string
+  sources?: DocsModuleUserSourceConfig[]
 }
 
 interface DesktopConfig {
@@ -325,7 +355,9 @@ interface DesktopConfig {
   modules?: string[]
   apps?: string[]
 
-  name?: stringThis
+  docs?: DocsModuleConfig
+
+  name?: string
   defaultApps?: DefaultAppsConfig
   features?: string[]
 
@@ -375,9 +407,10 @@ interface DefaultAppsConfig {
   [key: string]: DefaultAppConfig
 }
 
+/** Stored default for a feature: which app and which entry key to use. */
 interface DefaultAppConfig {
-  application: IApplicationController
-  entry: ApplicationEntry
+  applicationId: string
+  entry: string
 }
 
 export function defineDesktopApp(config: ApplicationConfig)

package/CHANGELOG.md

@@ -1,25 +0,0 @@
-## 3.1.4 (2025-05-22)
-
-### 🚀 Features
-
-- Allow apps to have a menu ([4bfea74](https://github.com/owdproject/client/commit/4bfea74))
-- Add methods to better handle window changes ([54d1346](https://github.com/owdproject/client/commit/54d1346))
-- Check if owd.config.ts is available and valid ([4920302](https://github.com/owdproject/client/commit/4920302))
-- Add fit-parent to CoreWindow.vue ([59e068c](https://github.com/owdproject/client/commit/59e068c))
-- Add focus() to WindowController and set methods as public (deprecate actions) ([710f7be](https://github.com/owdproject/client/commit/710f7be))
-- Add owd global command ([f98c74c](https://github.com/owdproject/client/commit/f98c74c))
-- Add useClipboardFs.ts composable ([cf934f4](https://github.com/owdproject/client/commit/cf934f4))
-- Add window utils in ApplicationController.ts ([ffc97d0](https://github.com/owdproject/client/commit/ffc97d0))
-- Export most used functions from core ([6635af7](https://github.com/owdproject/client/commit/6635af7))
-- Merge owd.config.ts with nuxt.config.ts in module.ts ([069243c](https://github.com/owdproject/client/commit/069243c))
-- Implement basic owd.config.ts ([d052552](https://github.com/owdproject/client/commit/d052552))
-- Rewrite project ([cbbd45d](https://github.com/owdproject/client/commit/cbbd45d))
-
-### 🩹 Fixes
-
-- Add key on CoreApplicationWindowsRender v-for ([d2e8e3c](https://github.com/owdproject/client/commit/d2e8e3c))
-- Check if entries property is set before normalizing in utilApp.ts ([6092c33](https://github.com/owdproject/client/commit/6092c33))
-- Add missing min-width ([aa0c1b5](https://github.com/owdproject/client/commit/aa0c1b5))
-- Minor improvements ([7f79208](https://github.com/owdproject/client/commit/7f79208))
-- Fix imports ([44740cd](https://github.com/owdproject/client/commit/44740cd))
-- Set window starting positionZ to 0 ([b99352e](https://github.com/owdproject/client/commit/b99352e))

package/project.json

@@ -1,4 +0,0 @@
-{
-  "name": "core",
-  "version": "3.1.3"
-}

package/runtime/components/Core/Application/CoreApplicationWindowsRender.vue

@@ -1,19 +0,0 @@
-<script setup lang="ts">
-defineProps<{
-  workspaceFilter?: string
-  windows: Map<string, IApplicationController['windows']>
-}>()
-</script>
-
-<template>
-  <template v-for="[windowId, window] in windows" :key="windowId">
-    <component
-      v-if="
-        !workspaceFilter ||
-        (workspaceFilter && window.state.workspace === workspaceFilter)
-      "
-      :window="window"
-      :is="window.config.component"
-    />
-  </template>
-</template>

package/runtime/components/Core/Explorer/CoreExplorerFile.vue

@@ -1,76 +0,0 @@
-<template>
-  <li
-    :class="[
-      'owd-explorer-file',
-      { 'owd-explorer-file--inactive': props.inactive },
-    ]"
-  >
-    <a
-      :href="props.url"
-      :target="props.target"
-      :title="props.title"
-      @click="props.fn"
-    >
-      <img :src="props.icon" :alt="props.title" />
-      <div class="owd-explorer-file__name" v-html="props.name" />
-    </a>
-  </li>
-</template>
-
-<script setup lang="ts">
-const props = defineProps<{
-  name: string
-  title: string
-  icon: string
-  url: string
-  target: string
-  inactive: boolean
-}>()
-</script>
-
-<style scoped lang="scss">
-li.file {
-  width: 100px;
-  margin: 0 5px 5px 0;
-  text-align: center;
-  float: left;
-  border-radius: 2px;
-  border: 1px solid rgba(0, 0, 0, 0);
-
-  @media (max-width: 480px) {
-    margin-right: 0;
-  }
-
-  @media (min-width: 480px) {
-    &:not(.inactive):hover {
-    }
-  }
-
-  &.inactive {
-    filter: grayscale(100%);
-    opacity: 0.2;
-  }
-
-  a {
-    display: block;
-    color: #ccc;
-    text-decoration: none;
-    transition: color 0.15s ease-in-out;
-    padding: 10px 0;
-
-    img {
-      vertical-align: middle;
-      height: 32px;
-      border-radius: 2px;
-    }
-
-    div.name {
-      font-size: 12px;
-      letter-spacing: -0.2px;
-      line-height: 10px;
-      margin-top: 10px;
-      cursor: pointer;
-    }
-  }
-}
-</style>