@owdproject/core 3.3.1 → 3.4.0

package/runtime/composables/useDesktopShellOptions.ts

@@ -0,0 +1,36 @@
+import { useAppConfig } from 'nuxt/app'
+import { computed } from 'vue'
+
+/**
+ * Reads shared desktop shell flags from `appConfig.desktop` (merged from runtime config).
+ * Themes use this for taskbar/dock visibility without duplicating `useAppConfig` wiring.
+ */
+type DesktopAppShape = {
+  systemBar?: {
+    enabled?: boolean
+    position?: string
+    startButton?: boolean
+  }
+}
+
+export function useDesktopShellOptions() {
+  const appConfig = useAppConfig()
+
+  const desktop = () => appConfig.desktop as DesktopAppShape | undefined
+
+  const systemBarEnabled = computed(
+    () => desktop()?.systemBar?.enabled !== false,
+  )
+
+  const systemBarPosition = computed(() => desktop()?.systemBar?.position)
+
+  const startButtonEnabled = computed(
+    () => desktop()?.systemBar?.startButton !== false,
+  )
+
+  return {
+    systemBarEnabled,
+    systemBarPosition,
+    startButtonEnabled,
+  }
+}

package/runtime/composables/useDesktopShellReady.ts

@@ -0,0 +1,7 @@
+import { useNuxtApp } from 'nuxt/app'
+
+/** True after `desktop-shell-init` has bound Pinia and run kernel workspace bootstrap. */
+export function useDesktopShellReady() {
+  const nuxtApp = useNuxtApp()
+  return nuxtApp.$desktopShellReady === true
+}

package/runtime/composables/useDesktopWorkArea.ts

@@ -0,0 +1,93 @@
+import type { Ref } from 'vue'
+import { onScopeDispose, watch } from 'vue'
+import {
+  EMPTY_DESKTOP_WORK_AREA,
+  useDesktopWindowStore,
+} from '@owdproject/core/runtime/stores/storeDesktopWindow'
+import { useDesktopWorkspaceStore } from '@owdproject/core/runtime/stores/storeDesktopWorkspace'
+
+function measureElement(el: HTMLElement) {
+  const rect = el.getBoundingClientRect()
+  return {
+    x: rect.left,
+    y: rect.top,
+    width: rect.width,
+    height: rect.height,
+  }
+}
+
+/**
+ * Tracks the desktop shell stage rectangle (area under system bar, above dock).
+ * Writes measured bounds to {@link useDesktopWindowStore.workArea}.
+ * Pass the same ref themes use for workspace overview live scale.
+ */
+export function useDesktopWorkArea(
+  shellStageRef: Ref<HTMLElement | null | undefined>,
+) {
+  const desktopWindowStore = useDesktopWindowStore()
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+
+  let resizeObserver: ResizeObserver | null = null
+
+  function refreshWorkArea() {
+    const el = shellStageRef.value
+    if (!el) {
+      desktopWindowStore.setWorkArea({ ...EMPTY_DESKTOP_WORK_AREA })
+      return
+    }
+    desktopWindowStore.setWorkArea(measureElement(el))
+  }
+
+  function disconnectObserver() {
+    resizeObserver?.disconnect()
+    resizeObserver = null
+  }
+
+  function observeStage(el: HTMLElement) {
+    disconnectObserver()
+    refreshWorkArea()
+
+    if (typeof ResizeObserver === 'undefined') {
+      return
+    }
+
+    resizeObserver = new ResizeObserver(() => refreshWorkArea())
+    resizeObserver.observe(el)
+  }
+
+  watch(
+    shellStageRef,
+    (el) => {
+      disconnectObserver()
+      if (el instanceof HTMLElement) {
+        observeStage(el)
+      } else {
+        desktopWindowStore.setWorkArea({ ...EMPTY_DESKTOP_WORK_AREA })
+      }
+    },
+    { immediate: true },
+  )
+
+  watch(
+    () => desktopWorkspaceStore.overview,
+    (open) => {
+      if (!open) {
+        refreshWorkArea()
+      }
+    },
+  )
+
+  if (typeof globalThis !== 'undefined') {
+    globalThis.addEventListener('resize', refreshWorkArea)
+    onScopeDispose(() => {
+      globalThis.removeEventListener('resize', refreshWorkArea)
+      disconnectObserver()
+    })
+  } else {
+    onScopeDispose(disconnectObserver)
+  }
+
+  return {
+    refreshWorkArea,
+  }
+}

package/runtime/composables/useTerminalManager.ts

@@ -3,14 +3,73 @@ import { debugLog } from '../utils/utilDebug'
 
 const commands = new Map<string, TerminalCommand>()
 
+// ─── formatting helpers ──────────────────────────────────────────────────────
+
+function padEnd(str: string, len: number): string {
+  return str.length >= len ? str : str + ' '.repeat(len - str.length)
+}
+
+function buildHelpList(): string {
+  const sorted = Array.from(commands.values()).sort((a, b) =>
+    a.name.localeCompare(b.name),
+  )
+
+  const colWidth = Math.max(...sorted.map((c) => c.name.length)) + 4
+
+  const rows = sorted
+    .map((cmd) => `  ${padEnd(cmd.name, colWidth)}${cmd.description ?? ''}`)
+    .join('\n')
+
+  return (
+    `Available commands:\n\n` +
+    rows +
+    `\n\nType 'help <command>' for more details.`
+  )
+}
+
+function buildHelpDetail(cmd: TerminalCommand): string {
+  const lines: string[] = []
+
+  lines.push(`  ${cmd.name}${cmd.description ? ` — ${cmd.description}` : ''}`)
+  lines.push('')
+
+  if (cmd.usage) {
+    lines.push(`  Usage: ${cmd.usage}`)
+    lines.push('')
+  }
+
+  if (cmd.args && cmd.args.length > 0) {
+    lines.push('  Arguments:')
+    const argColW = Math.max(...cmd.args.map((a) => a.name.length)) + 4
+    for (const arg of cmd.args) {
+      const required = arg.required ? '' : ' (optional)'
+      lines.push(
+        `    ${padEnd(arg.name, argColW)}${arg.description ?? ''}${required}`,
+      )
+    }
+    lines.push('')
+  }
+
+  if (cmd.options && cmd.options.length > 0) {
+    lines.push('  Options:')
+    const optColW = Math.max(...cmd.options.map((o) => o.flag.length)) + 4
+    for (const opt of cmd.options) {
+      lines.push(`    ${padEnd(opt.flag, optColW)}${opt.description ?? ''}`)
+    }
+    lines.push('')
+  }
+
+  return lines.join('\n').trimEnd()
+}
+
+// ─── composable ─────────────────────────────────────────────────────────────
+
 /**
  * Terminal Manager Composable (Singleton)
  */
-export function useTerminalManager() {
+export function useTerminalManager(): ITerminalManager {
   /**
    * Add a new terminal command
-   *
-   * @param command
    */
   const addCommand = (command: TerminalCommand) => {
     for (const existingCommand of commands.keys()) {
@@ -33,23 +92,55 @@ export function useTerminalManager() {
     return Array.from(commands.keys())
   }
 
+  /**
+   * Get a single command by name
+   */
+  const getCommand = (name: string): TerminalCommand | undefined => {
+    return commands.get(name)
+  }
+
+  /**
+   * Get all registered commands with metadata
+   */
+  const getAllCommands = (): TerminalCommand[] => {
+    return Array.from(commands.values())
+  }
+
   /**
    * Execute a terminal command
-   *
-   * @param input
    */
   const execCommand = async (input: string): Promise<CommandOutput | void> => {
     const applicationManager = useApplicationManager()
 
-    const [name, ...args] = input.trim().split(/\s+/)
+    const trimmed = input.trim()
+    const [name, ...rest] = trimmed.split(/\s+/)
+
+    if (!name) return
+
+    // ── built-in: help ────────────────────────────────────────────────────────
+    if (name === 'help') {
+      const target = rest[0]
+
+      if (!target) {
+        return { message: buildHelpList() }
+      }
+
+      const cmd = commands.get(target)
+      if (!cmd) {
+        return {
+          message: `help: command not found: '${target}'\nType 'help' to list available commands.`,
+          isError: true,
+        }
+      }
 
-    if (!name) {
-      return
+      return { message: buildHelpDetail(cmd) }
     }
+    // ─────────────────────────────────────────────────────────────────────────
 
     if (!commands.has(name)) {
       return {
-        message: `Command "${name}" not found`,
+        message: `Command not found: '${name}'\nType 'help' to list available commands.`,
+        isError: true,
       }
     }
 
@@ -61,6 +152,8 @@ export function useTerminalManager() {
   return {
     addCommand,
     listCommands,
+    getCommand,
+    getAllCommands,
     execCommand,
   }
 }

package/runtime/composables/useToggleWindowMaximize.ts

@@ -0,0 +1,35 @@
+import { inject } from 'vue'
+import {
+  useDesktopWindowStore,
+} from '../stores/storeDesktopWindow'
+import { toggleWindowMaximizeLayout } from '../utils/utilWindowMaximizeLayout'
+import {
+  DESKTOP_TOGGLE_WINDOW_MAXIMIZE_KEY,
+  type DesktopToggleWindowMaximizeFn,
+} from '../constants/desktopShellKeys'
+
+export type { DesktopToggleWindowMaximizeFn }
+
+/**
+ * Maximize / restore a window. Themes may override via
+ * {@link DESKTOP_TOGGLE_WINDOW_MAXIMIZE_KEY}; otherwise uses
+ * {@link useDesktopWindowStore.workArea} (when measured) or
+ * {@link IWindowController.actions.toggleMaximize}.
+ */
+export function useToggleWindowMaximize(): DesktopToggleWindowMaximizeFn {
+  const override = inject(DESKTOP_TOGGLE_WINDOW_MAXIMIZE_KEY, null)
+  if (override) return override
+
+  const desktopWindowStore = useDesktopWindowStore()
+
+  return function toggle(win: IWindowController | undefined) {
+    if (!win?.instanced) return false
+
+    const workArea = desktopWindowStore.workArea
+    if (workArea.width > 0 && workArea.height > 0) {
+      return toggleWindowMaximizeLayout(win, workArea)
+    }
+
+    return win.actions.toggleMaximize()
+  }
+}

package/runtime/composables/useWindowDragHandlers.ts

@@ -0,0 +1,47 @@
+import type { IWindowController } from '@owdproject/core'
+import { useDesktopWindowStore } from '../stores/storeDesktopWindow'
+import { useDesktopWorkspaceStore } from '../stores/storeDesktopWorkspace'
+import { useWorkspaceEdgeDrop } from './useWorkspaceEdgeDrop'
+import { useWindowSnapDrop } from './useWindowSnapDrop'
+
+/**
+ * Wire workspace edge drop and window snap to theme `Window.vue` drag events.
+ */
+export function useWindowDragHandlers(
+  getWindow: () => IWindowController | undefined,
+) {
+  const desktopWindowStore = useDesktopWindowStore()
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+  const { beginWindowDrag, endWindowDrag } = useWorkspaceEdgeDrop()
+  const { beginWindowSnapDrag, endWindowSnapDrag } = useWindowSnapDrop()
+
+  function onDragStart() {
+    const win = getWindow()
+    if (!win?.state?.id || desktopWorkspaceStore.overview) return
+
+    beginWindowDrag(win.state.id)
+    beginWindowSnapDrag(
+      win.state.id,
+      desktopWindowStore.workArea,
+      win.isMaximizable,
+    )
+  }
+
+  function onDragEnd(data: { left: number; top: number }) {
+    const win = getWindow()
+    if (!win || desktopWorkspaceStore.overview) return
+
+    const snapped = endWindowSnapDrag(win)
+    if (snapped) return
+
+    const moved = endWindowDrag(win)
+    if (!moved) {
+      win.actions.setPosition({ x: data.left, y: data.top })
+      if (win.state.layout && win.state.layout !== 'normal') {
+        win.actions.clearLayout()
+      }
+    }
+  }
+
+  return { onDragStart, onDragEnd }
+}

package/runtime/composables/useWindowSnapDrop.ts

@@ -0,0 +1,112 @@
+import type { DesktopWorkAreaRect, IWindowController } from '@owdproject/core'
+import type { Ref } from 'vue'
+import { computed, ref } from 'vue'
+import { useDesktopWorkspaceStore } from '../stores/storeDesktopWorkspace'
+import {
+  detectSnapZone,
+  type SnapZoneHint,
+} from '../utils/utilDetectSnapZone'
+import { applySnapToWindow, computeSnapRect } from '../utils/utilWindowLayout'
+import { useWorkspaceEdgeDrop } from './useWorkspaceEdgeDrop'
+
+const snapHint = ref<SnapZoneHint | null>(null)
+const isSnapDragActive = ref(false)
+let snapDraggingWindowId: string | null = null
+let activeWorkArea: DesktopWorkAreaRect = { x: 0, y: 0, width: 0, height: 0 }
+
+function onDocumentPointerMove(e: PointerEvent) {
+  updateSnapHintFromPointer(e.clientX, e.clientY)
+}
+
+function onDocumentMouseMove(e: MouseEvent) {
+  updateSnapHintFromPointer(e.clientX, e.clientY)
+}
+
+function stopSnapPointerTracking() {
+  document.removeEventListener('pointermove', onDocumentPointerMove)
+  document.removeEventListener('mousemove', onDocumentMouseMove)
+}
+
+function updateSnapHintFromPointer(clientX: number, clientY: number) {
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+
+  if (!isSnapDragActive.value || desktopWorkspaceStore.overview) {
+    snapHint.value = null
+    return
+  }
+
+  const deferSide =
+    desktopWorkspaceStore.list.length > 1 &&
+    !desktopWorkspaceStore.overview
+
+  snapHint.value = detectSnapZone(clientX, clientY, activeWorkArea, {
+    deferSideSnapForWorkspaceEdge: deferSide,
+  })
+}
+
+/**
+ * While dragging a maximizable window, highlight snap zones in the shell work area.
+ */
+export function useWindowSnapDrop() {
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+
+  function beginWindowSnapDrag(
+    windowId: string,
+    workArea: DesktopWorkAreaRect,
+    maximizable: boolean,
+  ) {
+    if (desktopWorkspaceStore.overview) return
+    if (!maximizable) return
+    if (workArea.width <= 0 || workArea.height <= 0) return
+
+    snapDraggingWindowId = windowId
+    isSnapDragActive.value = true
+    activeWorkArea = { ...workArea }
+    snapHint.value = null
+
+    document.addEventListener('pointermove', onDocumentPointerMove, {
+      passive: true,
+    })
+    document.addEventListener('mousemove', onDocumentMouseMove, {
+      passive: true,
+    })
+  }
+
+  function commitSnapDrop(win: IWindowController): boolean {
+    const zone = snapHint.value
+    if (!zone || !snapDraggingWindowId) return false
+
+    return applySnapToWindow(win, zone, activeWorkArea)
+  }
+
+  function endWindowSnapDrag(win?: IWindowController): boolean {
+    stopSnapPointerTracking()
+
+    let snapped = false
+    if (win && snapHint.value) {
+      snapped = commitSnapDrop(win)
+    }
+
+    isSnapDragActive.value = false
+    snapDraggingWindowId = null
+    snapHint.value = null
+
+    return snapped
+  }
+
+  const snapHintRect = computed(() => {
+    const zone = snapHint.value
+    if (!zone || activeWorkArea.width <= 0) return null
+
+    return computeSnapRect(zone, activeWorkArea)
+  })
+
+  return {
+    snapHint,
+    snapHintRect,
+    isSnapDragActive,
+    beginWindowSnapDrag,
+    endWindowSnapDrag,
+    activeWorkArea: () => activeWorkArea,
+  }
+}

package/runtime/composables/useWorkspaceEdgeDrop.ts

@@ -0,0 +1,176 @@
+import type { IWindowController } from '@owdproject/core'
+import { computed, ref } from 'vue'
+import { useDesktopWorkspaceStore } from '../stores/storeDesktopWorkspace'
+import { WORKSPACE_EDGE_DROP_PX } from '../constants/shellLayout'
+
+const edgeHint = ref<'left' | 'right' | null>(null)
+const isWindowDragActive = ref(false)
+let draggingWindowId: string | null = null
+
+function adjacentWorkspaceId(side: 'left' | 'right'): string | null {
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+  if (desktopWorkspaceStore.overview) return null
+  const list = desktopWorkspaceStore.list
+  if (list.length < 2) return null
+
+  const index = desktopWorkspaceStore.workspaceActiveIndex
+  if (index < 0) return null
+
+  if (side === 'left' && index > 0) {
+    return list[index - 1] ?? null
+  }
+  if (side === 'right' && index < list.length - 1) {
+    return list[index + 1] ?? null
+  }
+  return null
+}
+
+function updateEdgeHintFromClientX(clientX: number) {
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+  if (!isWindowDragActive.value || desktopWorkspaceStore.overview) {
+    edgeHint.value = null
+    return
+  }
+
+  const viewportWidth =
+    typeof globalThis !== 'undefined' ? globalThis.innerWidth : 0
+
+  if (clientX <= WORKSPACE_EDGE_DROP_PX && adjacentWorkspaceId('left')) {
+    edgeHint.value = 'left'
+    return
+  }
+
+  if (
+    clientX >= viewportWidth - WORKSPACE_EDGE_DROP_PX &&
+    adjacentWorkspaceId('right')
+  ) {
+    edgeHint.value = 'right'
+    return
+  }
+
+  edgeHint.value = null
+}
+
+function onDocumentPointerMove(e: PointerEvent) {
+  updateEdgeHintFromClientX(e.clientX)
+}
+
+function stopPointerTracking() {
+  document.removeEventListener('pointermove', onDocumentPointerMove)
+}
+
+/**
+ * While dragging a window (normal desktop, not overview), highlight left/right
+ * screen edges when an adjacent workspace exists so the user can drop there.
+ */
+export function useWorkspaceEdgeDrop() {
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+
+  function beginWindowDrag(windowId: string) {
+    if (desktopWorkspaceStore.overview) return
+    if (desktopWorkspaceStore.list.length < 2) return
+
+    draggingWindowId = windowId
+    isWindowDragActive.value = true
+    edgeHint.value = null
+
+    document.addEventListener('pointermove', onDocumentPointerMove, {
+      passive: true,
+    })
+  }
+
+  function commitEdgeDrop(win: IWindowController) {
+    const side = edgeHint.value
+    if (!side || !draggingWindowId) return false
+
+    const targetWorkspaceId = adjacentWorkspaceId(side)
+    if (!targetWorkspaceId) return false
+
+    win.actions.setWorkspace(targetWorkspaceId)
+    desktopWorkspaceStore.setWorkspace(targetWorkspaceId)
+
+    const inset = WORKSPACE_EDGE_DROP_PX + 24
+    const pos = win.position
+    if (pos && typeof pos.y === 'number') {
+      const viewportWidth =
+        typeof globalThis !== 'undefined' ? globalThis.innerWidth : 1920
+      const rawWidth = win.size?.width ?? 400
+      const width =
+        typeof rawWidth === 'number'
+          ? rawWidth
+          : Number.parseFloat(String(rawWidth)) || 400
+      const x =
+        side === 'left'
+          ? inset
+          : Math.max(inset, viewportWidth - width - inset)
+      win.actions.setPosition({ x, y: pos.y })
+    }
+
+    return true
+  }
+
+  function endWindowDrag(win?: IWindowController): boolean {
+    stopPointerTracking()
+
+    let moved = false
+    if (win && edgeHint.value) {
+      moved = commitEdgeDrop(win)
+    }
+
+    isWindowDragActive.value = false
+    draggingWindowId = null
+    edgeHint.value = null
+
+    return moved
+  }
+
+  const edgeTargetDesktopIndex = computed(() => {
+    const side = edgeHint.value
+    if (!side) return null
+
+    const targetId = adjacentWorkspaceId(side)
+    if (!targetId) return null
+
+    const index = desktopWorkspaceStore.list.indexOf(targetId)
+    return index >= 0 ? index + 1 : null
+  })
+
+  return {
+    edgeHint,
+    edgeTargetDesktopIndex,
+    isWindowDragActive,
+    beginWindowDrag,
+    endWindowDrag,
+    adjacentWorkspaceId,
+  }
+}
+
+/**
+ * Wire {@link useWorkspaceEdgeDrop} to DesktopWindow drag events (theme Window wrapper).
+ */
+export function useWorkspaceEdgeDropWindowHandlers(
+  getWindow: () => IWindowController | undefined,
+) {
+  const desktopWorkspaceStore = useDesktopWorkspaceStore()
+  const { beginWindowDrag, endWindowDrag } = useWorkspaceEdgeDrop()
+
+  function onDragStart() {
+    const win = getWindow()
+    if (!win?.state?.id || desktopWorkspaceStore.overview) return
+    beginWindowDrag(win.state.id)
+  }
+
+  function onDragEnd(data: { left: number; top: number }) {
+    const win = getWindow()
+    const moved =
+      Boolean(win) &&
+      !desktopWorkspaceStore.overview &&
+      endWindowDrag(win)
+
+    if (!moved && win) {
+      win.actions.setPosition({ x: data.left, y: data.top })
+    }
+  }
+
+  return { onDragStart, onDragEnd }
+}

package/runtime/composables/useWorkspaceManager.ts

@@ -1,6 +1,7 @@
 import { useEventListener } from '@vueuse/core'
 import { useApplicationManager } from './useApplicationManager'
 import { useDesktopWorkspaceStore } from '../stores/storeDesktopWorkspace'
+import { collectWindowsOnWorkspace } from '../utils/utilWorkspaceWindows'
 
 /**
  * Keyboard + HTML5 drop handlers for workspace management (move windows between desktops).
@@ -34,8 +35,33 @@ export function useWorkspaceManager() {
     win?.actions.setWorkspace(workspaceId)
   }
 
+  /**
+   * Remove a virtual desktop: migrate its windows to the last remaining workspace
+   * (excluding the removed id), then drop the workspace from the list.
+   */
+  function removeWorkspace(workspaceId: string): boolean {
+    if (desktopWorkspaceStore.list.length <= 2) return false
+
+    const fallbackId = desktopWorkspaceStore.resolveWorkspaceFallback(workspaceId)
+    if (!fallbackId) return false
+
+    const activeId = desktopWorkspaceStore.active
+    const windows = collectWindowsOnWorkspace(
+      applicationManager.apps.values(),
+      workspaceId,
+      activeId,
+    )
+
+    for (const win of windows) {
+      win.actions.setWorkspace(fallbackId)
+    }
+
+    return desktopWorkspaceStore.removeWorkspace(workspaceId)
+  }
+
   return {
     onWorkspaceDragOver,
     onWorkspaceDrop,
+    removeWorkspace,
   }
 }