@playcademy/vite-plugin 1.1.2 → 1.1.3-beta.10

package/dist/lib/cli-shortcuts.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Append custom shortcuts to Vite's CLI hotkeys.
+ *
+ * Vite has no additive API for shortcuts — the only seam is wrapping
+ * `bindCLIShortcuts` before Vite calls it. Both plugin variants (game and
+ * dashboard) hang their hotkeys off this one wrapper so the fragile
+ * Vite-internals handling lives in a single place.
+ */
+import type { ViteDevServer } from 'vite';
+type CustomShortcuts = NonNullable<NonNullable<Parameters<ViteDevServer['bindCLIShortcuts']>[0]>['customShortcuts']>;
+export declare function appendCliShortcuts(server: ViteDevServer, shortcuts: CustomShortcuts): void;
+export {};

package/dist/lib/dashboard-app.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Dashboard app auto-start for game dev
+ *
+ * When the project declares a dashboard, the game's dev server starts the
+ * dashboard app's own dev script alongside the sandbox and backend — one
+ * command brings up the whole loop: game UI, game worker, dashboard UI,
+ * dashboard worker, all sharing the same local data. The child is the
+ * dashboard's regular Vite process (with the plugin's dashboard mode), so
+ * running it standalone or auto-started behaves identically.
+ */
+import { spawn } from 'node:child_process';
+import type { PluginLogger } from './logging';
+/**
+ * Set in the spawned environment so a misconfigured project (for example
+ * `dashboard.directory` pointing back at the game app) cannot recursively
+ * auto-start dashboards from inside a dashboard child.
+ */
+export declare const DASHBOARD_CHILD_ENV = "PLAYCADEMY_DASHBOARD_CHILD";
+/**
+ * Dev-only endpoint the dashboard child's Vite server exposes so the game
+ * terminal can toggle the dashboard role: the auto-started child forwards
+ * its output but has no keyboard of its own, so `a` in the game terminal
+ * POSTs here instead.
+ */
+export declare const DASHBOARD_ROLE_TOGGLE_PATH = "/__playcademy/dashboard/toggle-role";
+export interface DashboardAppManager {
+    /** Signals the child group immediately; resolves once it has exited. */
+    stop(): Promise<void>;
+    /** Port the dashboard app's Vite server was told to bind */
+    port: number;
+}
+export interface SetupDashboardAppOptions {
+    enabled: boolean;
+    configPath?: string;
+    /** Port the dashboard app's Vite must bind (canonical default when unset) */
+    port?: number;
+    /** Injectable for tests */
+    spawnImpl?: typeof spawn;
+    logger?: PluginLogger;
+}
+/**
+ * Reduce a raw child output line to what the parent should relay: ANSI
+ * stripped (the noise patterns must see plain text — color codes sit
+ * between every token), the child's own timestamp prefix removed, and
+ * startup noise dropped entirely. Returns null for lines to swallow.
+ */
+export declare function sanitizeChildOutputLine(rawLine: string): string | null;
+/**
+ * Start the dashboard app's dev script when the project has a dashboard.
+ * Returns null when disabled, running inside a dashboard child, no config
+ * exists, or no dashboard is configured — game dev proceeds without one.
+ * A dashboard that IS configured but fails to load warns instead of
+ * silently doing nothing.
+ */
+export declare function setupDashboardApp(options: SetupDashboardAppOptions): Promise<DashboardAppManager | null>;

package/dist/lib/game-backend/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Backend server management
+ */
+export { setupGameBackendDevServer } from './server';

package/dist/lib/game-backend/server.d.ts

@@ -0,0 +1,9 @@
+import type { GameBackendDevServerOptions, GameBackendServerManager } from '../../types';
+/**
+ * Sets up the CLI dev server with hot reload enabled.
+ * Loads config, checks if backend is needed, and starts server if appropriate.
+ * Returns null if no config or the project has no backend features.
+ *
+ * Used by the Vite plugin to manage the game backend server.
+ */
+export declare function setupGameBackendDevServer(options: GameBackendDevServerOptions): Promise<GameBackendServerManager | null>;

package/dist/lib/logging/hot-reload.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hot reload callbacks — log a rebuild outcome under the given domain
+ * (`backend` for the game worker, `dashboard` for the dashboard worker).
+ */
+import type { ResolvedConfig } from 'vite';
+/**
+ * Creates hot reload callbacks for logging rebuild results.
+ */
+export declare function createHotReloadCallbacks(viteConfig: ResolvedConfig, domain: string): {
+    onSuccess: (changedPath?: string) => void;
+    onError: (error: unknown) => void;
+};

package/dist/lib/logging/index.d.ts

@@ -3,4 +3,5 @@
  */
 export type { PluginLogger } from './adapter';
 export { createLoggerAdapter } from './adapter';
-export { createBackendBannerOptions, createTimebackBannerOptions, log, printBanner } from './utils';
+export * from './hot-reload';
+export { createGameBannerOptions, createTimebackBannerOptions, printBanner } from './utils';

package/dist/lib/logging/utils.d.ts

@@ -1,18 +1,13 @@
-import type { ResolvedConfig } from 'vite';
-import type { BannerOptions } from '../../types';
 /**
  * Centralized logging utilities for the Vite plugin.
  * Provides clear, prefixed, and color-coded output for multiple servers.
  */
-export declare const log: {
-    sandbox: (msg: string) => void;
-    backend: (msg: string) => void;
-    playcademy: (msg: string) => void;
-};
+import type { ResolvedConfig } from 'vite';
+import type { BannerOptions } from '../../types';
 /**
- * Create backend banner options from server info
+ * Create game backend banner options from server info
  */
-export declare function createBackendBannerOptions(backendPort: number | undefined, vitePort: number | undefined): BannerOptions['backend'];
+export declare function createGameBannerOptions(gameBackendPort: number | undefined, vitePort: number | undefined): BannerOptions['gameBackend'];
 /**
  * Create timeback banner options from sandbox state
  */

package/dist/server/hotkeys/toggle-dashboard-role.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 'a' hotkey - cycle the auto-started dashboard app's role (admin/viewer)
+ *
+ * The dashboard child forwards its output into the game terminal but its
+ * own hotkeys need a keyboard, so the game terminal reaches its role
+ * toggle through the dev-only endpoint the child exposes. The child logs
+ * the role change itself; that line is forwarded here, so success needs
+ * no extra output.
+ */
+import type { HotkeyOptions } from '../../types';
+export declare function toggleDashboardRoleHotkey(options: HotkeyOptions): {
+    key: string;
+    description: string;
+    action: () => undefined;
+};

package/dist/server/state.d.ts

@@ -7,14 +7,16 @@
  * these references at module scope to properly clean them up on restart.
  */
 import type { ViteDevServer } from 'vite';
-import type { CliServerManager, PlatformRoleOverride, SandboxManager, TimebackRoleOverride } from '../types';
+import type { DashboardAppManager } from '../lib/dashboard-app';
+import type { GameBackendServerManager, PlatformRoleOverride, SandboxManager, TimebackRoleOverride } from '../types';
 import type { PlaycademyMode } from '../types/options';
 /**
  * Module-level server references
  */
 export declare const serverState: {
     sandbox: SandboxManager | null;
-    backend: CliServerManager | null;
+    gameBackend: GameBackendServerManager | null;
+    dashboardApp: DashboardAppManager | null;
     viteServer: ViteDevServer | null;
     currentMode: PlaycademyMode;
     timebackRoleOverride: TimebackRoleOverride | null;
@@ -28,14 +30,6 @@ export declare function getSandboxRef(): SandboxManager | null;
  * Set sandbox server reference
  */
 export declare function setSandboxRef(sandbox: SandboxManager | null): void;
-/**
- * Get backend server reference
- */
-export declare function getBackendRef(): CliServerManager | null;
-/**
- * Set backend server reference
- */
-export declare function setBackendRef(backend: CliServerManager | null): void;
 /**
  * Check if any servers are currently running
  */

package/dist/types/index.d.ts

@@ -2,5 +2,5 @@
  * Type exports for the Playcademy Vite Plugin
  */
 export type { PlaycademyExportOptions, PlaycademySandboxOptions, PlaycademyDisplayOptions, PlaycademyPluginOptions, PlaycademyTimebackOptions, PlaycademyMode, } from './options';
-export type { BannerOptions, CliDevServerOptions, CliServerManager, HotkeyOptions, PlatformModeOptions, PlatformRoleOverride, PlaycademyOutputData, PluginContext, ProjectInfo, ResolvedPluginOptions, SandboxManager, StandaloneModeOptions, TimebackCourseConfig, TimebackPluginContext, TimebackRoleOverride, } from './internal';
+export type { BannerOptions, GameBackendDevServerOptions, GameBackendServerManager, HotkeyOptions, PlatformModeOptions, PlatformRoleOverride, PlaycademyOutputData, PluginContext, ProjectInfo, ResolvedPluginOptions, SandboxManager, StandaloneModeOptions, TimebackCourseConfig, TimebackPluginContext, TimebackRoleOverride, } from './internal';
 export { TIMEBACK_ROLES, PLATFORM_ROLES } from './internal';

package/dist/types/internal.d.ts

@@ -19,9 +19,13 @@ export type PlatformRoleOverride = (typeof PLATFORM_ROLES)[number];
 export interface ResolvedPluginOptions {
     configPath?: string;
     mode: PlaycademyMode;
+    gameBackendPort: number;
+    sandboxPort: number;
+    dashboardAppPort: number;
     autoZip: boolean;
     sandboxUrl: string;
     startSandbox: boolean;
+    startDashboard: boolean;
     verbose: boolean;
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     recreateDb: boolean;
@@ -37,8 +41,6 @@ export interface ResolvedPluginOptions {
 export interface PluginContext {
     options: ResolvedPluginOptions;
     viteConfig: ResolvedConfig | null;
-    backendPort: number | null;
-    sandboxPort: number | null;
     buildOutputs: PlaycademyOutputData;
 }
 /**
@@ -99,7 +101,7 @@ export interface SandboxManager {
 /**
  * CLI server manager interface for controlling backend server lifecycle
  */
-export interface CliServerManager {
+export interface GameBackendServerManager {
     server: {
         dispose: () => Promise<void>;
     };
@@ -110,7 +112,7 @@ export interface CliServerManager {
 /**
  * Options for setting up the CLI dev server
  */
-export interface CliDevServerOptions {
+export interface GameBackendDevServerOptions {
     port: number;
     viteConfig: ResolvedConfig;
     platformUrl?: string;
@@ -122,7 +124,9 @@ export interface CliDevServerOptions {
  */
 export interface PlatformModeOptions {
     startSandbox: boolean;
+    startDashboard: boolean;
     sandboxPort: number;
+    dashboardAppPort: number;
     verbose: boolean;
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     sandboxUrl: string;
@@ -131,7 +135,7 @@ export interface PlatformModeOptions {
     memoryOnly: boolean;
     databasePath?: string;
     hideBadge: boolean;
-    backendPort: number;
+    gameBackendPort: number;
     configPath?: string;
     timeback?: PlaycademyTimebackOptions | false;
 }
@@ -139,7 +143,7 @@ export interface PlatformModeOptions {
  * Options for standalone mode (backend only)
  */
 export interface StandaloneModeOptions {
-    backendPort: number;
+    gameBackendPort: number;
     configPath?: string;
 }
 /**
@@ -165,11 +169,15 @@ export interface BannerOptions {
         enabled: false;
     };
     /** Backend server info */
-    backend?: {
+    gameBackend?: {
         port: number;
         /** Vite port for proxied URL display */
         vitePort?: number;
     };
+    /** Dashboard app info (when auto-started alongside the game) */
+    dashboard?: {
+        port: number;
+    };
     /** Timeback info (shell-backed modes only) */
     timeback?: {
         courseCount: number;

package/dist/types/options.d.ts

@@ -12,6 +12,31 @@
  * @default 'platform'
  */
 export type PlaycademyMode = 'platform' | 'demo' | 'standalone';
+/**
+ * Configuration for developing a game's dashboard app.
+ *
+ * In dashboard mode the plugin runs the real composed dashboard worker —
+ * the platform's auth layer plus your api/ routes — under Miniflare, with
+ * the same local data the game's dev server uses, and proxies `/api/*` to
+ * it with an always-signed-in developer session.
+ */
+export interface PlaycademyDashboardOptions {
+    /**
+     * The role of the local developer identity.
+     *
+     * Set `'viewer'` to exercise read-only UI states and route role policy.
+     * Toggle at runtime with the `d` hotkey in the Vite terminal.
+     *
+     * @default 'admin'
+     */
+    role?: 'admin' | 'viewer';
+    /**
+     * Port for the local dashboard worker.
+     *
+     * @default 8789
+     */
+    workerPort?: number;
+}
 /**
  * Configuration options for exporting/building Playcademy games
  *
@@ -334,6 +359,65 @@ export interface PlaycademyPluginOptions {
      * ```
      */
     mode?: PlaycademyMode;
+    /**
+     * Develop a dashboard app instead of a game.
+     *
+     * Runs the real composed dashboard worker (platform auth layer + your
+     * api/ routes) locally and proxies `/api/*` to it with a signed-in
+     * session; disables the game machinery (sandbox, shell, backend
+     * bundling, manifest/zip). `playcademy dashboard init` sets this up.
+     *
+     * @example
+     * ```ts
+     * {
+     *   dashboard: true
+     * }
+     * ```
+     * @example
+     * ```ts
+     * {
+     *   dashboard: { role: 'viewer' } // exercise read-only UI states
+     * }
+     * ```
+     */
+    dashboard?: boolean | PlaycademyDashboardOptions;
+    /**
+     * Port for the local game backend worker.
+     *
+     * Override when the default collides with another dev server on the
+     * same machine — every internal consumer (the /api proxy, hot reload,
+     * the dev shell) follows this port.
+     *
+     * @default 8788
+     */
+    gameBackendPort?: number;
+    /**
+     * Port for the local sandbox platform.
+     *
+     * @default 4321
+     */
+    sandboxPort?: number;
+    /**
+     * Port for the auto-started dashboard app's Vite server.
+     *
+     * The game's dev server assigns this port when it spawns the dashboard
+     * app (with `--strictPort`), so the dashboard's own vite config cannot
+     * move it.
+     *
+     * @default 8790
+     */
+    dashboardAppPort?: number;
+    /**
+     * Auto-start the project's dashboard app alongside game dev.
+     *
+     * When the project's playcademy.config declares a dashboard, the game's
+     * dev server starts the dashboard's own dev script next to the sandbox
+     * and backend. Set `false` to run the dashboard separately (or not at
+     * all) with `playcademy dashboard dev`.
+     *
+     * @default true
+     */
+    startDashboard?: boolean;
     /**
      * Export/build configuration options.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "1.1.2",
+    "version": "1.1.3-beta.10",
     "type": "module",
     "exports": {
         ".": {
@@ -19,7 +19,7 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.27.0"
+        "playcademy": "0.27.1-beta.10"
     },
     "devDependencies": {
         "@electric-sql/pglite": "^0.3.16",
@@ -35,6 +35,6 @@
     "peerDependencies": {
         "@playcademy/sdk": ">=0.12.0",
         "typescript": "^5 || ^6",
-        "vite": "^5 || ^6 || ^7"
+        "vite": "^5 || ^6 || ^7 || ^8"
     }
 }

package/dist/lib/backend/hot-reload.d.ts

@@ -1,11 +0,0 @@
-/**
- * Hot reload callbacks for backend server
- */
-import type { ResolvedConfig } from 'vite';
-/**
- * Creates hot reload callbacks for logging backend updates.
- */
-export declare function createHotReloadCallbacks(viteConfig: ResolvedConfig): {
-    onSuccess: (changedPath?: string) => void;
-    onError: (error: unknown) => void;
-};

package/dist/lib/backend/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Backend server management
- */
-export { setupCliDevServer } from './server';
-export { createHotReloadCallbacks } from './hot-reload';

package/dist/lib/backend/server.d.ts

@@ -1,9 +0,0 @@
-import type { CliDevServerOptions, CliServerManager } from '../../types';
-/**
- * Sets up the CLI dev server with hot reload enabled.
- * Loads config, checks if backend is needed, and starts server if appropriate.
- * Returns null if no config or no integrations (backend not needed).
- *
- * Used by the Vite plugin to manage the game backend server.
- */
-export declare function setupCliDevServer(options: CliDevServerOptions): Promise<CliServerManager | null>;