@owdproject/nuxt 0.0.0-stage → 4.0.0-alpha.3

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2025  Open Web Desktop Team ~ github.com/owdproject
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
+IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,78 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+  <h1>@owdproject/nuxt</h1>
+
+  <p>
+    <strong>Official Nuxt & Vue 3 Reactive Adapter for Open Web Desktop.</strong><br /><br />
+    Reactive composables, pointer drag/resize hooks, and WindowController<br />
+    bindings powered by <code>@owdproject/core</code>.
+  </p>
+
+  <br />
+
+  <p>
+    <a href="https://npmjs.com/package/@owdproject/nuxt"><img src="https://img.shields.io/npm/v/@owdproject/nuxt/alpha.svg?style=flat&colorA=020420&colorB=00DC82" alt="npm version" /></a>
+    <a href="https://nuxt.com"><img src="https://img.shields.io/badge/Nuxt-020420?logo=nuxt" alt="Nuxt" /></a>
+    <a href="https://github.com/owdproject/core/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-00DC82.svg?style=flat&colorA=020420&colorB=00DC82" alt="License" /></a>
+  </p>
+
+</div>
+
+---
+
+## Overview
+
+`@owdproject/nuxt` (`4.0.0-alpha.0`) bridges [`@owdproject/core`](https://npmjs.com/package/@owdproject/core) to Vue 3 and Nuxt via `shallowRef` subscriptions, computed selectors, and automatic `onScopeDispose` cleanup.
+
+The package includes the Nuxt module, `desktop.config.ts` support, shell components, and Vue bindings.
+
+Register it in `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  ssr: false,
+  modules: ['@owdproject/nuxt'],
+  desktop: {
+    theme: '@owdproject/nuxt-theme-win95',
+  },
+})
+```
+
+Install the theme separately. Inline `desktop` options override `desktop.config.ts`; app and module arrays are merged.
+
+---
+
+## Quick Start
+
+```bash
+pnpm add @owdproject/core@4.0.0-alpha.0 @owdproject/nuxt@4.0.0-alpha.0
+```
+
+```vue
+<script setup lang="ts">
+import { useDesktop, useDesktopDrag, useDesktopResize } from '@owdproject/nuxt'
+
+const { desktop, windows, focusedWindow } = useDesktop({
+  workarea: { x: 0, y: 32, width: 1440, height: 868 },
+})
+</script>
+```
+
+---
+
+## Exported Composables & Classes
+
+| Export | Description |
+| :--- | :--- |
+| **`useDesktop(instanceOrOptions?)`** | Reactive bindings for `windows`, `applications`, `workspace`, `commands`, `events`, and `focusedWindow`. |
+| **`useWindowManager(manager?)`** | Reactive wrapper around a `WindowManager` instance. |
+| **`useWindowInstance(instance)`** | Subscribes a single `WindowInstance` to a Vue `shallowRef<WindowState>`. |
+| **`useDesktopDrag(options)`** | W3C Pointer drag composable with snap-zone detection and auto-cleanup. |
+| **`useDesktopResize(options)`** | 8-directional W3C Pointer resize composable with min/max constraint enforcement. |
+| **`WindowController`** | Reactive Vue wrapper around `@owdproject/core`'s `windowMachine`. |
+
+---
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

package/dist/kit/authoring.d.ts

@@ -0,0 +1,96 @@
+import type { DesktopConfig, DesktopExtensionDirs, DesktopExtensionKind, DesktopExtensionMeta, DesktopFramework } from '../types/index.js';
+import { defineNuxtModule, type NuxtModule } from '@nuxt/kit';
+import type { Nuxt } from '@nuxt/schema';
+/** Root `desktop.config.ts` helper — keep this file free of `import.meta` for jiti. */
+export declare function defineDesktopConfig(config: DesktopConfig): DesktopConfig;
+/**
+ * Default directories a desktop distribution collects extensions from, relative to its
+ * root. A Nuxt desktop uses `apps/`, `modules/` and `themes/`; the monorepo keeps
+ * framework modules under `packages/`, so both slots are listed.
+ */
+export declare const DESKTOP_EXTENSION_DIRS: DesktopExtensionDirs;
+/**
+ * Parses a framework-first extension short name (`nuxt-app-todo`, `react-theme-win95`)
+ * into its parts. Legacy names without a framework segment (`app-todo`) are accepted
+ * with `framework` left undefined. Returns `null` when the kind is unknown.
+ */
+export declare function parseDesktopExtensionName(shortName: string): {
+    framework?: DesktopFramework;
+    kind: DesktopExtensionKind;
+    name: string;
+} | null;
+/**
+ * Runtime validation for the object exported from `desktop.config.ts`
+ * (or legacy `owd.config.ts`).
+ */
+export declare function assertValidDesktopUserConfig(config: unknown, configFile?: string): void;
+export declare const DESKTOP_CONFIG_FILENAME = "desktop.config.ts";
+export declare const LEGACY_DESKTOP_CONFIG_FILENAME = "owd.config.ts";
+export declare const LEGACY_CONFIG_DEPRECATION = "[@owdproject/nuxt] owd.config.ts is deprecated and kept only for backward compatibility; rename to desktop.config.ts.";
+export type ResolvedDesktopConfigPath = {
+    path: string;
+    file: string;
+    legacy: boolean;
+};
+export declare function resolveDesktopConfigPath(rootDir: string): ResolvedDesktopConfigPath | null;
+export declare function warnLegacyDesktopConfig(resolved: ResolvedDesktopConfigPath | null | undefined): void;
+/** Path used when creating or updating config from the CLI (always the new filename). */
+export declare function desktopConfigWritePath(desktopDir: string): string;
+/**
+ * Warn when desktop.config.ts contains keys that look like Nuxt options.
+ * Extension keys (fs, terminal, custom app namespaces) are intentionally not validated here.
+ */
+export declare function warnDesktopConfigKeys(config: Record<string, unknown>, configFile?: string): void;
+/**
+ * Writes a resolved extension namespace to `runtimeConfig.public.desktop[configKey]`.
+ * Used by {@link defineDesktopModule} after Nuxt merges inline options with module defaults.
+ */
+export declare function setDesktopExtensionConfig(nuxt: Nuxt, configKey: string, resolved: Record<string, unknown>): void;
+/**
+ * Merges theme or module defaults into an extension namespace on `public.desktop`.
+ * User values from desktop.config win over `partial` (defu: partial fills undefined only).
+ */
+export declare function mergeDesktopExtensionConfig(nuxt: Nuxt, configKey: string, partial: Record<string, unknown>): void;
+/**
+ * Reads the declarative extension contract (`kind`, `framework`, `adapter`, …) from a
+ * package's Nuxt module `meta`. Build-time only — no runtime imports. Used to keep the
+ * collection contract framework-agnostic across desktop distributions.
+ */
+export declare function readExtensionMeta(modulePath: string): Promise<Partial<DesktopExtensionMeta>>;
+/**
+ * Validates an extension contract and returns a normalized copy. Throws on an unknown
+ * kind/framework so misconfigured extensions fail at build time instead of at runtime.
+ */
+export declare function assertDesktopExtensionMeta(meta: Partial<DesktopExtensionMeta>, packageName?: string): DesktopExtensionMeta;
+/**
+ * Installs a desktop theme, module, or app package.
+ * When the package exposes `meta.configKey`, passes `desktop[configKey]` to `installModule`
+ * so Nuxt merges desktop.config with module defaults.
+ */
+export declare function installDesktopPackage(nuxt: Nuxt, modulePath: string, desktop?: Record<string, unknown>): Promise<void>;
+type DesktopModuleMeta = {
+    name: string;
+    configKey: string;
+} & Partial<Omit<DesktopExtensionMeta, 'configKey'>>;
+type DesktopModuleDefinition = NuxtModule<Record<string, unknown>, Record<string, unknown>, false> & {
+    meta: DesktopModuleMeta;
+};
+/**
+ * Nuxt module wrapper for desktop apps and extension modules (`configKey` → desktop.config namespace).
+ * Publishes merged options to `runtimeConfig.public.desktop[configKey]` after setup runs.
+ */
+export declare function defineDesktopModule(definition: DesktopModuleDefinition): ReturnType<typeof defineNuxtModule>;
+type DesktopThemeDefinition = NuxtModule<Record<string, unknown>, Record<string, unknown>, false>;
+/**
+ * Nuxt module wrapper for desktop themes.
+ * Merges theme shell defaults into `runtimeConfig.public.desktop` (user desktop.config wins).
+ */
+export declare function defineDesktopTheme(definition: DesktopThemeDefinition): ReturnType<typeof defineNuxtModule>;
+/**
+ * Build-time check if a desktop module, app, or theme is registered in desktop.config.ts.
+ * Useful during theme or module setup hooks before Nuxt finishes installing modules.
+ */
+export declare function hasDesktopModule(nuxt: Nuxt, packageName: string): boolean;
+/** Inline Nuxt options override the file; extension arrays are merged without duplicates. */
+export declare function mergeDesktopConfig(inline: DesktopConfig, file: DesktopConfig, coreVersion: string): DesktopConfig;
+export {};

package/dist/kit/authoring.js

@@ -0,0 +1,260 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import {
+  defineNuxtModule,
+  installModule,
+  resolvePath
+} from "@nuxt/kit";
+import { defu } from "defu";
+export function defineDesktopConfig(config) {
+  return config;
+}
+export const DESKTOP_EXTENSION_DIRS = {
+  apps: ["apps"],
+  modules: ["modules", "packages"],
+  themes: ["themes"]
+};
+const FRAMEWORK_SEGMENTS = [
+  "nuxt",
+  "vue",
+  "react",
+  "svelte",
+  "angular",
+  "astro"
+];
+const KIND_SEGMENTS = [
+  "app",
+  "module",
+  "theme",
+  "kit"
+];
+export function parseDesktopExtensionName(shortName) {
+  const parts = shortName.split("-");
+  let framework;
+  if (FRAMEWORK_SEGMENTS.includes(parts[0])) {
+    framework = parts.shift();
+  }
+  const kind = parts[0];
+  if (!KIND_SEGMENTS.includes(kind)) return null;
+  return { framework, kind, name: parts.slice(1).join("-") };
+}
+export function assertValidDesktopUserConfig(config, configFile = "desktop.config.ts") {
+  if (!config || typeof config !== "object" || Array.isArray(config)) {
+    throw new Error(
+      `[@owdproject/nuxt] ${configFile} must default-export a non-array object from defineDesktopConfig({ ... }).`
+    );
+  }
+  const c = config;
+  if (c.theme != null && typeof c.theme !== "string") {
+    throw new Error(
+      `[@owdproject/nuxt] ${configFile}: \`theme\` must be a string (npm package name or local path of the theme module).`
+    );
+  }
+  if (c.apps !== void 0) {
+    if (!Array.isArray(c.apps) || !c.apps.every((item) => typeof item === "string")) {
+      throw new Error(
+        `[@owdproject/nuxt] ${configFile}: \`apps\` must be an array of strings (Nuxt module package names or local paths).`
+      );
+    }
+  }
+  if (c.modules !== void 0) {
+    if (!Array.isArray(c.modules) || !c.modules.every((item) => typeof item === "string")) {
+      throw new Error(
+        `[@owdproject/nuxt] ${configFile}: \`modules\` must be an array of strings (Nuxt module package names or local paths).`
+      );
+    }
+  }
+}
+export const DESKTOP_CONFIG_FILENAME = "desktop.config.ts";
+export const LEGACY_DESKTOP_CONFIG_FILENAME = "owd.config.ts";
+export const LEGACY_CONFIG_DEPRECATION = "[@owdproject/nuxt] owd.config.ts is deprecated and kept only for backward compatibility; rename to desktop.config.ts.";
+export function resolveDesktopConfigPath(rootDir) {
+  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/nuxt] 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) {
+  if (resolved?.legacy) {
+    console.warn(LEGACY_CONFIG_DEPRECATION);
+  }
+}
+export function desktopConfigWritePath(desktopDir) {
+  return join(desktopDir, DESKTOP_CONFIG_FILENAME);
+}
+const NUXT_OPTION_KEYS = /* @__PURE__ */ new Set([
+  "ssr",
+  "devtools",
+  "vite",
+  "nitro",
+  "runtimeConfig",
+  "app",
+  "appConfig",
+  "css",
+  "plugins",
+  "hooks",
+  "extends",
+  "compatibilityDate",
+  "experimental",
+  "future",
+  "i18n",
+  "tailwindcss",
+  "primevue"
+]);
+export function warnDesktopConfigKeys(config, configFile = "desktop.config.ts") {
+  for (const key of Object.keys(config)) {
+    if (NUXT_OPTION_KEYS.has(key)) {
+      console.warn(
+        `[@owdproject/nuxt] ${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, ... }).`
+      );
+    }
+  }
+}
+export function setDesktopExtensionConfig(nuxt, configKey, resolved) {
+  const pub = nuxt.options.runtimeConfig.public ??= {};
+  const desktop = pub.desktop ??= {};
+  desktop[configKey] = resolved;
+}
+export function mergeDesktopExtensionConfig(nuxt, configKey, partial) {
+  const pub = nuxt.options.runtimeConfig.public ??= {};
+  const desktop = pub.desktop ??= {};
+  const existing = desktop[configKey];
+  const base = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : {};
+  desktop[configKey] = defu(partial, base);
+}
+async function readConfigKey(mod) {
+  if (!mod) return void 0;
+  let meta = mod.meta ?? mod.default?.meta;
+  if (!meta) {
+    const getMeta = mod.getMeta ?? mod.default?.getMeta;
+    if (typeof getMeta === "function") {
+      try {
+        meta = await getMeta();
+      } catch (e) {
+        console.warn("[@owdproject/nuxt] failed to call getMeta():", e);
+      }
+    }
+  }
+  const key = meta?.configKey;
+  return typeof key === "string" && key.length > 0 ? key : void 0;
+}
+export async function readExtensionMeta(modulePath) {
+  const meta = (await loadModuleDescriptor(modulePath))?.meta ?? {};
+  return {
+    kind: meta.kind,
+    framework: meta.framework,
+    packageName: meta.packageName,
+    configKey: meta.configKey,
+    entry: meta.entry,
+    adapter: meta.adapter,
+    requires: meta.requires
+  };
+}
+export function assertDesktopExtensionMeta(meta, packageName = "unknown") {
+  if (!meta.kind || !KIND_SEGMENTS.includes(meta.kind)) {
+    throw new Error(
+      `[@owdproject/nuxt] ${packageName}: extension meta.kind must be one of ${KIND_SEGMENTS.join(", ")}.`
+    );
+  }
+  if (!meta.framework || !FRAMEWORK_SEGMENTS.includes(meta.framework)) {
+    throw new Error(
+      `[@owdproject/nuxt] ${packageName}: extension meta.framework must be one of ${FRAMEWORK_SEGMENTS.join(", ")}.`
+    );
+  }
+  return meta;
+}
+async function loadModuleDescriptor(modulePath) {
+  try {
+    const resolvedPath = await resolvePath(modulePath);
+    const imported = await import(resolvedPath);
+    return imported.default ?? imported;
+  } catch (e) {
+    console.warn(`[@owdproject/nuxt] loadModuleDescriptor failed for "${modulePath}":`, e);
+    return void 0;
+  }
+}
+export async function installDesktopPackage(nuxt, modulePath, desktop) {
+  const descriptor = await loadModuleDescriptor(modulePath);
+  const configKey = await readConfigKey(descriptor);
+  if (configKey && desktop) {
+    const slice = desktop[configKey];
+    const inline = slice && typeof slice === "object" && !Array.isArray(slice) ? slice : {};
+    await installModule(modulePath, inline);
+    return;
+  }
+  await installModule(modulePath);
+}
+export function defineDesktopModule(definition) {
+  const configKey = definition.meta.configKey;
+  if (!configKey) {
+    throw new Error(
+      '[@owdproject/nuxt] defineDesktopModule requires meta.configKey (e.g. "terminal", "fs", "audit").'
+    );
+  }
+  const userSetup = definition.setup;
+  return defineNuxtModule({
+    ...definition,
+    async setup(options, nuxt) {
+      setDesktopExtensionConfig(
+        nuxt,
+        configKey,
+        options
+      );
+      if (typeof userSetup === "function") {
+        return userSetup(options, nuxt);
+      }
+    }
+  });
+}
+export function defineDesktopTheme(definition) {
+  const userSetup = definition.setup;
+  return defineNuxtModule({
+    ...definition,
+    meta: {
+      ...definition.meta,
+      configKey: "desktop"
+    },
+    async setup(options, nuxt) {
+      const pub = nuxt.options.runtimeConfig.public ??= {};
+      pub.desktop = defu(
+        pub.desktop ?? {},
+        options
+      );
+      if (typeof userSetup === "function") {
+        return userSetup(options, nuxt);
+      }
+    }
+  });
+}
+export function hasDesktopModule(nuxt, packageName) {
+  const desktop = nuxt.options.runtimeConfig.public.desktop;
+  if (!desktop) return false;
+  const contains = (item) => item ? String(item).includes(packageName) : false;
+  return contains(desktop.theme) || (desktop.modules?.some(contains) ?? false) || (desktop.apps?.some(contains) ?? false);
+}
+export function mergeDesktopConfig(inline, file, coreVersion) {
+  assertValidDesktopUserConfig(inline, "nuxt.config.ts desktop options");
+  assertValidDesktopUserConfig(file);
+  const merged = defu(inline, file, { coreVersion });
+  for (const key of ["apps", "modules"]) {
+    if (merged[key]) merged[key] = [...new Set(merged[key])];
+  }
+  return merged;
+}

package/dist/kit/defineDesktopApp.d.ts

@@ -0,0 +1 @@
+export * from '../runtime/utils/defineDesktopApp.js';

package/dist/kit/defineDesktopApp.js

@@ -0,0 +1 @@
+export * from "../runtime/utils/defineDesktopApp";

package/dist/kit/defineDesktopPlugin.d.ts

@@ -0,0 +1 @@
+export * from '../runtime/utils/defineDesktopPlugin.js';

package/dist/kit/defineDesktopPlugin.js

@@ -0,0 +1 @@
+export * from "../runtime/utils/defineDesktopPlugin";