@owdproject/core 3.1.4-beta.0 → 3.2.0

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"
-}

package/runtime/composables/useClipboardFs.ts

@@ -1,25 +0,0 @@
-import { ref } from 'vue'
-
-type ClipboardOperation = 'copy' | 'cut'
-
-const clipboardFiles = ref<string[]>([])
-const clipboardType = ref<ClipboardOperation | null>(null)
-
-export function useClipboardFs() {
-  function setClipboard(paths: string[], type: ClipboardOperation) {
-    clipboardFiles.value = paths
-    clipboardType.value = type
-  }
-
-  function clearClipboard() {
-    clipboardFiles.value = []
-    clipboardType.value = null
-  }
-
-  return {
-    clipboardFiles,
-    clipboardType,
-    setClipboard,
-    clearClipboard,
-  }
-}

package/runtime/core/managers/ApplicationManager.ts

@@ -1,281 +0,0 @@
-import type { Reactive } from '@vue/reactivity'
-import { reactive, markRaw } from '@vue/reactivity'
-import { ApplicationController } from '../controllers/ApplicationController'
-import { normalizeApplicationConfig } from '../../utils/utilApp'
-import { debugLog } from '../../utils/utilDebug'
-import * as shellwords from 'shellwords'
-import yargsParser from 'yargs-parser'
-
-export class ApplicationManager implements IApplicationManager {
-  public apps = reactive(new Map<string, IApplicationController>())
-
-  constructor() {}
-
-  /**
-   * Define new application
-   *
-   * @param id
-   * @param config
-   */
-  public async defineApp(id: string, config: ApplicationConfig) {
-    if (this.isAppDefined(id)) {
-      debugLog(`App "${id}" is already defined`)
-      return this.getAppById(id)!
-    }
-
-    const normalizedConfig = normalizeApplicationConfig(config)
-    const applicationConfig = markRaw(normalizedConfig)
-
-    const applicationController: IApplicationController = new ApplicationController(id, applicationConfig)
-    await applicationController.initApplication()
-
-    this.apps.set(id, applicationController)
-
-    return applicationController
-  }
-
-  /**
-   * Check if app has been defned
-   *
-   * @param {string} id
-   */
-  public isAppDefined(id: string) {
-    return this.getAppById(id)
-  }
-
-  /**
-   * Retrieves an app instance by its unique identifier
-   *
-   * @param {string} id
-   */
-  public getAppById(id: string) {
-    return this.apps.get(id)
-  }
-
-  /**
-   * Check if app is running
-   *
-   * @param {string} id
-   */
-  public isAppRunning(id: string) {
-    if (!this.isAppDefined(id)) {
-      throw Error(`App "${id}" is not defined`)
-    }
-
-    const applicationController: IApplicationController = this.getAppById(id)!
-
-    if (!applicationController.isRunning) {
-      return false
-    }
-
-    return true
-  }
-
-  /**
-   * Launch app entry
-   *
-   * @param id
-   * @param entryKey
-   */
-  public async launchAppEntry(
-    id: string,
-    entryKey: string,
-  ): Promise<IApplicationController | undefined | void> {
-    if (!this.isAppDefined(id)) {
-      throw Error(`App "${id}" is not defined`)
-    }
-
-    const applicationController: IApplicationController = this.getAppById(id)!
-
-    if (
-      applicationController.config.entries &&
-      !applicationController.config.entries.hasOwnProperty(entryKey)
-    ) {
-      throw Error(`App entry "${entryKey}" is not defined in ${id} application`)
-    }
-
-    const entry: ApplicationEntry = applicationController.config.entries[entryKey]!
-
-    await this.execAppCommand(applicationController.id, entry.command)
-  }
-
-  /**
-   * Run app command
-   *
-   * @param id
-   * @param rawCommand
-   */
-  public async execAppCommand(
-    id: string,
-    rawCommand: string,
-  ): Promise<CommandOutput> {
-    if (!this.isAppDefined(id)) {
-      throw Error(`App "${id}" is not defined`)
-    }
-
-    const applicationController: IApplicationController = this.getAppById(id)!
-
-    const args = shellwords.split(rawCommand)
-    const parsed = yargsParser(args)
-    const command: string = parsed._[0]
-
-    if (
-      applicationController.config.commands &&
-      !applicationController.config.commands.hasOwnProperty(command)
-    ) {
-      throw Error(
-        `App command "${command}" is not defined in ${id} application`,
-      )
-    }
-
-    const commandFn: any = applicationController.config.commands![command]
-
-    const commandOutput = await commandFn(
-      applicationController,
-      parsed,
-    )
-
-    applicationController.setRunning(true)
-
-    return commandOutput
-  }
-
-  /**
-   * Close application
-   *
-   * @param id
-   */
-  public closeApp(id: string) {
-    if (!this.isAppDefined(id)) {
-      throw Error(`App "${id}" is not defined`)
-    }
-
-    const applicationController: IApplicationController = this.getAppById(id)!
-
-    applicationController.closeAllWindows()
-    applicationController.setRunning(false)
-  }
-
-  /**
-   * Array of available menu entries for system bars, docks
-   */
-  public get appsEntries() {
-    const entries: Reactive<ApplicationEntryWithInherited[]> = reactive([])
-
-    for (const applicationController of this.apps.values()) {
-      if (!applicationController.config.entries) {
-        continue
-      }
-
-      for (const entryKey of Object.keys(
-        applicationController.config.entries,
-      )) {
-        const entry: ApplicationEntry =
-          applicationController.config.entries[entryKey]!
-
-        entries.push({
-          application: applicationController,
-          title:
-            entry.title !== undefined
-              ? entry.title
-              : applicationController.config.title,
-          icon:
-            entry.icon !== undefined
-              ? entry.icon
-              : applicationController.config.icon,
-          category:
-            entry.category !== undefined
-              ? entry.category
-              : applicationController.config.category,
-          visibility: entry.visibility ?? 'primary',
-          command: entry.command,
-        })
-      }
-    }
-
-    return entries
-  }
-
-  /**
-   * Array of opened windows for system bars, docks
-   */
-  public get windowsOpened() {
-    const windows: Reactive<Map<string, IWindowController>[]> = reactive([])
-
-    for (const applicationController of this.apps.values()) {
-      if (applicationController.isRunning) {
-        windows.push(...applicationController.windows)
-      }
-    }
-
-    return windows
-  }
-
-  /**
-   * Array of opened windows for system bars, docks
-   */
-  public get appsRunning() {
-    const applications: Reactive<IApplicationController[]> = reactive([])
-
-    for (const applicationController of this.apps.values()) {
-      if (applicationController.isRunning) {
-        applications.push(applicationController)
-      }
-    }
-
-    return applications
-  }
-
-  public getWindowOpenedId(windowId: string) {
-    const mapWindowFound: Map<string, IWindowController> | undefined =
-      this.windowsOpened.find((window: any) => {
-        return window[1].state.id === windowId
-      })
-
-    if (mapWindowFound) {
-      // @ts-ignore
-      return mapWindowFound[1] as IWindowController
-    }
-  }
-
-  /**
-   * Gets all unique categories from the installed apps
-   */
-  public get appCategories(): string[] {
-    const categories = new Set<string>()
-
-    for (const applicationController of this.apps.values()) {
-      if (applicationController.config.category) {
-        categories.add(applicationController.config.category)
-      }
-    }
-    return Array.from(categories).sort()
-  }
-
-  /**
-   * Gets the apps ordered by category
-   */
-  public get appsByCategory(): {
-    [category: string]: IApplicationController[]
-  } {
-    const categorizedApps: {
-      [category: string]: IApplicationController[]
-    } = {}
-
-    for (const applicationController of this.apps.values()) {
-      const category = applicationController.config.category || 'other'
-      if (!categorizedApps[category]) {
-        categorizedApps[category] = []
-      }
-      categorizedApps[category].push(applicationController)
-    }
-
-    for (const category in categorizedApps) {
-      categorizedApps[category]!.sort((a, b) =>
-        a.config.title.localeCompare(b.config.title),
-      )
-    }
-
-    return categorizedApps
-  }
-}