@skyvexsoftware/stratos-sdk 0.1.5 → 0.1.7

package/README.md

@@ -16,169 +16,177 @@ Scaffold a new plugin project:
 pnpx create-stratos-plugin
 ```
 
-Or manually create a project with `plugin.json`, `vite.config.ts`, and `src/ui/index.tsx`. See the [plugin developer guide](https://skyvexsoftware.com/docs/plugins) for details.
+This generates a ready-to-develop plugin with Tailwind CSS, TypeScript, and Vite preconfigured.
 
-## Available APIs
+### Development
 
-### Plugin Contract Types
+1. Open the Stratos app with `--dev` flag
+2. In your plugin directory, run:
 
-Type definitions for the plugin system:
-
-```ts
-import type {
-  PluginManifest,
-  PluginContext,
-  PluginUIContext,
-  PluginBackgroundModule,
-  PluginUIModule,
-} from "@skyvexsoftware/stratos-sdk";
+```bash
+pnpm dev
 ```
 
-### Vite Plugin Config
+Your plugin auto-connects to the running Stratos app and appears in the sidebar. Code changes auto-reload.
 
-The SDK provides a shared Vite configuration for building plugins:
+### Project Structure
 
-```ts
-import { createPluginConfig } from "@skyvexsoftware/stratos-sdk/vite";
-
-export default createPluginConfig({
-  pluginDir: import.meta.dirname,
-  ui: { entry: "src/ui/index.tsx" },
-  background: { entry: "src/background/index.ts" }, // optional
-});
+```
+my-plugin/
+├── plugin.json           # Plugin manifest (name, version, author, settings)
+├── package.json
+├── vite.config.ts        # Uses createPluginConfig from SDK
+├── tsconfig.json
+├── src/
+│   ├── ui/
+│   │   ├── index.tsx     # UI entry (default export: React component)
+│   │   └── global.css    # Tailwind CSS
+│   └── background/       # Optional: main process module
+│       └── index.ts      # Exports onStart(ctx) and onStop()
+└── assets/
+    ├── icon-light.svg    # Sidebar icon (dark theme)
+    └── icon-dark.svg     # Sidebar icon (light theme)
 ```
 
-This handles UI bundling with externals, background module builds, asset copying, dev server auto-connect, and HMR.
+### Building
+
+```bash
+pnpm build                # Build for distribution
+```
 
-### Helper Functions
+Produces `dist/` with bundled UI, background module (if any), manifest, and assets. Zip and upload to the Skyvex website.
 
-#### `createPlugin(module)`
+## Vite Config
 
-Validates and returns a typed plugin background module:
+The SDK provides `createPluginConfig` which handles bundling, externals, dev server auto-connect, and asset copying:
 
 ```ts
-import { createPlugin } from "@skyvexsoftware/stratos-sdk";
+import { createPluginConfig } from "@skyvexsoftware/stratos-sdk/vite";
+import tailwindcss from "@tailwindcss/vite";
 
-export default createPlugin({
-  async onStart(ctx) {
-    ctx.logger.info("MyPlugin", "Starting...");
-  },
-  async onStop() {
-    // cleanup
+export default createPluginConfig({
+  ui: { entry: "src/ui/index.tsx" },
+  background: { entry: "src/background/index.ts" }, // optional
+  vite: {
+    plugins: [tailwindcss()],
   },
 });
 ```
 
-#### `PluginRouter` component
-
-Optional lightweight router for plugins that need internal multi-page navigation:
+The `vite` option accepts any Vite config to merge in (plugins, resolve, css, etc.).
 
-```tsx
-import { PluginRouter } from "@skyvexsoftware/stratos-sdk";
-import TrackingPage from "./pages/TrackingPage";
-import HistoryPage from "./pages/HistoryPage";
-import HistoryDetailPage from "./pages/HistoryDetailPage";
+## Plugin Manifest
 
-const routes = [
-  { path: "tracking", component: TrackingPage },
-  { path: "history", component: HistoryPage },
-  { path: "history/:id", component: HistoryDetailPage },
-];
+`plugin.json` defines your plugin's metadata:
 
-export default function MyPluginRoot() {
-  return <PluginRouter routes={routes} defaultPath="tracking" />;
+```json
+{
+  "$schema": "https://cdn.skyvexsoftware.com/schemas/stratos-plugin.json",
+  "id": "my-plugin",
+  "type": "airline",
+  "name": "My Plugin",
+  "version": "0.1.0",
+  "description": "A Stratos plugin",
+  "author": { "id": "my-org", "name": "My Organization" },
+  "icon_light": "icon-light.svg",
+  "icon_dark": "icon-dark.svg"
 }
 ```
 
-For single-page plugins, just export the component directly:
+- `type`: `"airline"` (scoped to a virtual airline) or `"user"` (user-installed)
+- `availableSettings`: Optional array of setting definitions (boolean, text, number, list, etc.)
 
-```tsx
-import HomePage from "./HomePage";
-export default HomePage;
-```
+## API Reference
 
-#### `usePluginRoute()`
+### UI Context
 
-Returns the current sub-path within the plugin (the URL portion after `/plugins/{pluginId}/`):
+Access shell services from plugin components:
 
 ```tsx
-import { usePluginRoute } from "@skyvexsoftware/stratos-sdk";
+import { usePluginContext } from "@skyvexsoftware/stratos-sdk";
 
 function MyComponent() {
-  const { subPath } = usePluginRoute();
-  // e.g. "history/abc123"
-}
-```
-
-#### `usePluginParams()`
-
-Access route params matched by `PluginRouter` (e.g. `history/:id`):
-
-```tsx
-import { usePluginParams } from "@skyvexsoftware/stratos-sdk";
-
-function DetailPage() {
-  const { id } = usePluginParams<{ id: string }>();
-  // id === "abc123" when URL is /plugins/my-plugin/history/abc123
+  const {
+    pluginId,
+    auth,        // { isAuthenticated, token, user }
+    airline,     // { id, name, icao, logo_light, logo_dark }
+    config,      // { get(key, defaultValue) }
+    navigation,  // { navigateTo, navigateToPlugin, navigateToShell }
+    toast,       // { success, error, info, warning }
+    logger,      // { info, warn, error, debug }
+  } = usePluginContext();
 }
 ```
 
-### React Hooks
-
-Access shell services from plugin components. All hooks must be used within a `PluginShellProvider` (provided by the shell at runtime).
+Individual hooks are also available:
 
 | Hook                   | Returns              | Description                    |
 | ---------------------- | -------------------- | ------------------------------ |
+| `usePluginContext()`   | Full PluginUIContext | All services combined          |
 | `useShellAuth()`       | Auth state           | Authentication state and token |
 | `useShellConfig()`     | Config store         | Scoped configuration access    |
 | `useShellNavigation()` | Navigation helpers   | Route navigation utilities     |
 | `useShellToast()`      | Toast API            | Toast/notification functions   |
 | `usePluginLogger()`    | Logger               | Scoped renderer-side logger    |
-| `usePluginContext()`   | Full PluginUIContext | All of the above combined      |
 
-```tsx
-import { useShellAuth, useShellToast } from "@skyvexsoftware/stratos-sdk";
+### Background Module
 
-function MyComponent() {
-  const { isAuthenticated } = useShellAuth();
-  const toast = useShellToast();
-
-  return (
-    <button onClick={() => toast.success("Hello!")}>
-      {isAuthenticated ? "Logged in" : "Not authenticated"}
-    </button>
-  );
-}
+Optional main-process code with access to IPC, Express routes, SQLite, and more:
+
+```ts
+import { createPlugin } from "@skyvexsoftware/stratos-sdk";
+
+export default createPlugin({
+  async onStart(ctx) {
+    // ctx.logger  — scoped logger
+    // ctx.config  — per-plugin config store
+    // ctx.ipc     — IPC handler registration
+    // ctx.auth    — read-only auth token access
+    // ctx.server  — Express router registration
+    // ctx.database — SQLite database access
+    ctx.logger.info("MyPlugin", "Started");
+  },
+  async onStop() {
+    // cleanup
+  },
+});
 ```
 
-### UI Primitives
+### Routing
 
-Pre-styled shadcn/ui components using Tailwind CSS and Radix UI:
+For multi-page plugins, use `PluginRouter`:
 
 ```tsx
-import { Button, Card, CardContent, Input, Label } from "@skyvexsoftware/stratos-sdk";
+import { PluginRouter } from "@skyvexsoftware/stratos-sdk";
+
+const routes = [
+  { path: "home", component: HomePage },
+  { path: "settings", component: SettingsPage },
+  { path: "detail/:id", component: DetailPage },
+];
+
+export default function Plugin() {
+  return <PluginRouter routes={routes} defaultPath="home" />;
+}
 ```
 
-Available components:
+For single-page plugins, just export the component directly.
+
+### UI Components
 
-- **Button** — with variants: default, destructive, outline, secondary, ghost, link
-- **Card** — CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter
-- **Dialog** — DialogTrigger, DialogContent, DialogHeader, DialogFooter, DialogTitle, DialogDescription
-- **Input** — text input with validation states
-- **Label** — form label
-- **Select** — SelectTrigger, SelectContent, SelectItem, SelectGroup, SelectValue
-- **Badge** — with variants: default, secondary, destructive, outline
-- **Separator** — horizontal or vertical divider
-- **Tabs** — TabsList, TabsTrigger, TabsContent
-- **Tooltip** — TooltipProvider, TooltipTrigger, TooltipContent
+Pre-styled shadcn/ui components that match the Stratos design system:
+
+```tsx
+import { Button, Card, CardContent, Input, Dialog } from "@skyvexsoftware/stratos-sdk";
+```
 
-### Shared Types
+Available: Button, Card, Dialog, Input, Label, Select, Badge, Separator, Tabs, Tooltip, AlertDialog, RadioGroup, Slider, Switch, Textarea.
 
-Common types used across plugins:
+### Types
 
 ```ts
 import { FlightPhase, SimulatorType } from "@skyvexsoftware/stratos-sdk";
-import type { FlightData, ThemeMode } from "@skyvexsoftware/stratos-sdk";
+import type { FlightData, PluginManifest, PluginContext } from "@skyvexsoftware/stratos-sdk";
 ```
 
 ### Utilities
@@ -186,21 +194,10 @@ import type { FlightData, ThemeMode } from "@skyvexsoftware/stratos-sdk";
 ```ts
 import { cn } from "@skyvexsoftware/stratos-sdk";
 
-// Tailwind class merging utility
-cn("bg-red-500", conditional && "text-white", className);
+// Tailwind class merging
+cn("bg-red-500", isActive && "text-white", className);
 ```
 
-## Peer Dependencies
-
-The SDK expects these to be provided by the Stratos shell at runtime:
-
-- `react` ^19.0.0
-- `@radix-ui/react-*` (dialog, label, select, separator, slot, tabs, tooltip)
-- `@tanstack/react-query` ^5.0.0
-- `class-variance-authority` ^0.7.0
-- `lucide-react` >=0.300.0
-- `socket.io-client` ^4.0.0
-
 ## License
 
 MIT

package/dist/vite/plugin-config.d.ts

@@ -29,13 +29,16 @@ declare const BG_EXTERNALS: string[];
  */
 declare function stratosExternals(): Plugin;
 export type PluginBuildOptions = {
-    pluginDir: string;
+    /** Plugin root directory. Defaults to process.cwd(). */
+    pluginDir?: string;
     ui?: {
         entry: string;
     };
     background?: {
         entry: string;
     };
+    /** Extra Vite config to merge (plugins, css, etc.) */
+    vite?: UserConfig;
 };
 /**
  * Create a Vite config for building a Stratos plugin.

package/dist/vite/plugin-config.js

@@ -157,26 +157,20 @@ function copyDirSync(src, dest) {
  * - "background"     → builds the background module (Node.js, ESM)
  */
 export function createPluginConfig(options) {
-    const { pluginDir, ui, background } = options;
+    const { pluginDir = process.cwd(), ui, background, vite: extraConfig, } = options;
     const target = process.env.BUILD_TARGET;
     if (target === "background" && background) {
         return createBackgroundConfig(pluginDir, background.entry);
     }
     if (ui) {
-        return createUIConfig(pluginDir, ui.entry);
+        return createUIConfig(pluginDir, ui.entry, extraConfig);
     }
     throw new Error("No build target. Provide a ui entry or set BUILD_TARGET=background.");
 }
-function createUIConfig(pluginDir, entry) {
+function createUIConfig(pluginDir, entry, extraConfig) {
     const isProduction = process.env.NODE_ENV === "production";
     return {
         root: pluginDir,
-        plugins: [
-            serveExternals(),
-            stratosDevServer({ pluginDir }),
-            stratosExternals(),
-            copyPluginAssets(pluginDir),
-        ],
         server: {
             cors: {
                 origin: [
@@ -185,6 +179,14 @@ function createUIConfig(pluginDir, entry) {
                     /^http:\/\/localhost:\d+$/,
                 ],
             },
+            hmr: {
+                // When modules are loaded via stratos-dev:// protocol, Vite's HMR
+                // client needs to connect back to THIS dev server's WebSocket directly.
+                // Without this, it would try to derive the WS URL from the custom
+                // protocol scheme, which doesn't work.
+                protocol: "ws",
+                host: "localhost",
+            },
         },
         optimizeDeps: {
             exclude: [
@@ -212,6 +214,15 @@ function createUIConfig(pluginDir, entry) {
             jsx: "automatic",
             jsxImportSource: "react",
         },
+        // Merge extra config: plugins are concatenated, other keys shallow-merged
+        ...extraConfig,
+        plugins: [
+            serveExternals(),
+            stratosDevServer({ pluginDir }),
+            stratosExternals(),
+            copyPluginAssets(pluginDir),
+            ...(extraConfig?.plugins ?? []),
+        ],
     };
 }
 function createBackgroundConfig(pluginDir, entry) {

package/dist/vite/serve-externals.js

@@ -19,7 +19,7 @@ export function serveExternals() {
     return {
         name: "stratos-serve-externals",
         apply: "serve",
-        enforce: "pre",
+        enforce: "post",
         transform(code, id) {
             // Only process JS/TS source files
             const ext = id.slice(id.lastIndexOf("."));
@@ -69,6 +69,23 @@ export function serveExternals() {
                 // 6. Side-effect imports: import "pkg"
                 result = result.replace(new RegExp(`import\\s+['"]${escaped}['"]\\s*;?`, "g"), `// (stratos-serve-externals: side-effect import of "${modId}" removed)`);
             }
+            // Second pass: catch Vite-resolved paths like
+            //   import { jsxDEV } from "/node_modules/react/jsx-dev-runtime.js?v=..."
+            // These are injected by esbuild's JSX transform after our source-level pass.
+            for (const modId of EXTERNAL_PACKAGES) {
+                // Convert package name to a path pattern: "react/jsx-dev-runtime" -> "react/jsx-dev-runtime"
+                const pathPattern = modId.replace(/\//g, "/");
+                const global = `window.__stratos_modules__[${JSON.stringify(modId)}]`;
+                // Match: import { x } from "/node_modules/{pkg}.js?v=..." or "/{pkg}?..."
+                const resolvedRe = new RegExp(`import\\s*\\{([^}]+)\\}\\s+from\\s+['"][^'"]*/${escapeRegExp(pathPattern)}(?:\\.js)?(?:\\?[^'"]*)?['"]\\s*;?`, "g");
+                result = result.replace(resolvedRe, (_, names) => {
+                    const destructured = names.replace(/([\w$]+)\s+as\s+([\w$]+)/g, "$1: $2");
+                    return `const {${destructured}} = ${global};`;
+                });
+                // Match: import Default from "/node_modules/{pkg}.js?v=..."
+                const resolvedDefaultRe = new RegExp(`import\\s+([\\w$]+)\\s+from\\s+['"][^'"]*/${escapeRegExp(pathPattern)}(?:\\.js)?(?:\\?[^'"]*)?['"]\\s*;?`, "g");
+                result = result.replace(resolvedDefaultRe, (_, def) => `const ${def} = ${global}.default || ${global};`);
+            }
             if (result === code)
                 return null;
             return { code: result, map: null };

package/dist/vite/stratos-dev-server.js

@@ -20,6 +20,9 @@ import { io as ioClient } from "socket.io-client";
  */
 export function stratosDevServer(options) {
     const { pluginDir } = options;
+    // Shared state between configureServer and handleHotUpdate hooks
+    let socket = null;
+    let pluginId = "unknown";
     return {
         name: "stratos-dev-server",
         apply: "serve",
@@ -28,7 +31,6 @@ export function stratosDevServer(options) {
                 (process.env.STRATOS_PORT
                     ? parseInt(process.env.STRATOS_PORT, 10)
                     : 2066);
-            let socket = null;
             let retryTimeout = null;
             let retryDelay = 3000;
             const MAX_RETRY_DELAY = 30000;
@@ -41,7 +43,7 @@ export function stratosDevServer(options) {
             catch {
                 console.error("[stratos-dev-server] Failed to read plugin.json at", manifestPath);
             }
-            const pluginId = manifest.id ?? "unknown";
+            pluginId = manifest.id ?? "unknown";
             function clearRetry() {
                 if (retryTimeout) {
                     clearTimeout(retryTimeout);
@@ -183,9 +185,35 @@ export function stratosDevServer(options) {
             process.once("SIGTERM", cleanup);
             // Start connecting after the HTTP server is listening
             server.httpServer?.once("listening", () => {
+                // Set the HMR port dynamically so Vite's HMR client connects
+                // directly to this dev server's WebSocket (cross-origin is OK for WS).
+                const addr = server.httpServer?.address();
+                if (addr && typeof addr === "object") {
+                    server.config.server.hmr =
+                        typeof server.config.server.hmr === "object"
+                            ? {
+                                ...server.config.server.hmr,
+                                port: addr.port,
+                                clientPort: addr.port,
+                            }
+                            : { port: addr.port, clientPort: addr.port };
+                }
                 connect();
             });
         },
+        // Notify Stratos when UI source files change so it can reload the plugin
+        handleHotUpdate({ file }) {
+            // Only signal for UI source changes (not background, not config files)
+            if (file.includes("/src/") && !file.includes("/src/background/")) {
+                if (socket?.connected) {
+                    console.log(`[stratos-dev-server] UI source changed: ${path.basename(file)}`);
+                    socket.emit("dev:plugin-ui-updated", {
+                        pluginId,
+                        timestamp: Date.now(),
+                    });
+                }
+            }
+        },
     };
 }
 //# sourceMappingURL=stratos-dev-server.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyvexsoftware/stratos-sdk",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Plugin SDK for Stratos — types, hooks, and UI components",
   "author": {
     "name": "Skyvex Software",