@owdproject/core 3.1.4 → 3.2.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,12 @@ export const useDesktopStore = defineStore(
       window: {
         positionZ: number
       }
-      defaultApps: {[key: string]: string}
+      explorer: {
+        navExpandedKeys: string[]
+        quickAccessPins: { id: string; label: string; path: string; icon?: string }[]
+      }
+      defaultApps: Record<string, { applicationId: string; entry: string }>
+      personalization: DesktopPersonalization
     }>({
       workspace: {
         overview: false,
@@ -29,11 +69,48 @@ export const useDesktopStore = defineStore(
       window: {
         positionZ: 0,
       },
-      defaultApps: {}
+      explorer: {
+        navExpandedKeys: [
+          'quickAccess',
+          'thisPc',
+        ],
+        quickAccessPins: [],
+      },
+      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/storeDesktopExplorer.ts

@@ -0,0 +1,74 @@
+import { defineStore } from 'pinia'
+import { computed } from 'vue'
+import { useDesktopStore } from './storeDesktop'
+
+type ExplorerQuickAccessPin = {
+  id: string
+  label: string
+  path: string
+  icon?: string
+}
+
+export const useDesktopExplorerStore = defineStore(
+  'owd/desktop/explorer',
+  () => {
+    const desktopStore = useDesktopStore()
+
+    const navExpandedKeys = computed(
+      () => desktopStore.state.explorer.navExpandedKeys,
+    )
+    const quickAccessPins = computed(
+      () => desktopStore.state.explorer.quickAccessPins,
+    )
+
+    function setNavExpandedKeys(keys: string[]) {
+      desktopStore.state.explorer.navExpandedKeys = [...new Set(keys)]
+    }
+
+    function setQuickAccessPins(pins: ExplorerQuickAccessPin[]) {
+      desktopStore.state.explorer.quickAccessPins = pins
+    }
+
+    function pinQuickAccess(entry: ExplorerQuickAccessPin) {
+      const exists = desktopStore.state.explorer.quickAccessPins.some(
+        (pin) => pin.path === entry.path,
+      )
+      if (exists) return
+      desktopStore.state.explorer.quickAccessPins.push(entry)
+    }
+
+    function unpinQuickAccess(path: string) {
+      desktopStore.state.explorer.quickAccessPins =
+        desktopStore.state.explorer.quickAccessPins.filter(
+          (pin) => pin.path !== path,
+        )
+    }
+
+    function reorderQuickAccess(startIndex: number, endIndex: number) {
+      const list = [...desktopStore.state.explorer.quickAccessPins]
+      if (
+        startIndex < 0 ||
+        endIndex < 0 ||
+        startIndex >= list.length ||
+        endIndex >= list.length ||
+        startIndex === endIndex
+      ) {
+        return
+      }
+      const [item] = list.splice(startIndex, 1)
+      if (!item) return
+      list.splice(endIndex, 0, item)
+      desktopStore.state.explorer.quickAccessPins = list
+    }
+
+    return {
+      navExpandedKeys,
+      quickAccessPins,
+      setNavExpandedKeys,
+      setQuickAccessPins,
+      pinQuickAccess,
+      unpinQuickAccess,
+      reorderQuickAccess,
+    }
+  },
+)

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/validateOwdUserConfig.ts

@@ -0,0 +1,44 @@
+/**
+ * Runtime validation for the object exported from `desktop.config.ts`
+ * (or legacy `owd.config.ts`).
+ */
+export function assertValidOwdUserConfig(
+  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,15 +355,36 @@ interface DesktopConfig {
   modules?: string[]
   apps?: string[]
 
-  name?: stringThis
+  docs?: DocsModuleConfig
+
+  name?: string
   defaultApps?: DefaultAppsConfig
   features?: string[]
+  explorer?: DesktopExplorerConfig
 
   systemBar?: DesktopSystemBarConfig
   dockBar?: DesktopDockBarConfig
   workspaces?: DesktopWorkspacesConfig
 }
 
+interface DesktopExplorerFolderConfig {
+  id: string
+  label: string
+  path: string
+  icon?: string
+}
+
+interface DesktopExplorerConfig {
+  quickAccess?: DesktopExplorerFolderConfig[]
+  quickAccessExtra?: DesktopExplorerFolderConfig[]
+  quickAccessOverride?: DesktopExplorerFolderConfig[]
+  specialFolders?: DesktopExplorerFolderConfig[]
+  specialFoldersExtra?: DesktopExplorerFolderConfig[]
+  specialFoldersOverride?: DesktopExplorerFolderConfig[]
+  /** Friendly labels for ZenFS mount points shown under “This PC” (paths → label). */
+  mountLabels?: Record<string, string>
+}
+
 interface DesktopWindowsConfig {
   position: 'relative' | 'absolute' | 'fixed'
 }
@@ -375,9 +426,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"
-}