@playcademy/vite-plugin 0.1.37 → 0.1.40

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

@@ -3,4 +3,4 @@
  */
 export { startSandbox } from './server';
 export { extractProjectInfo } from './project-info';
-export { detectTimebackOptions } from './timeback';
+export { detectTimebackOptions, getEffectiveTimebackId, hasTimebackCredentials, validateTimebackConfig, generateTimebackJson, } from './timeback';

package/dist/lib/sandbox/project-info.d.ts

@@ -3,8 +3,12 @@
  */
 import type { ResolvedConfig } from 'vite';
 import type { ProjectInfo } from '../../types';
+import type { PlaycademyTimebackOptions } from '../../types/options';
 /**
  * Extracts project information from playcademy.config and package.json
  * Used to initialize sandbox with correct project metadata
+ *
+ * @param viteConfig - Resolved Vite configuration
+ * @param timebackOptions - Optional timeback options from vite.config.ts for courseId overrides
  */
-export declare function extractProjectInfo(viteConfig: ResolvedConfig): Promise<ProjectInfo>;
+export declare function extractProjectInfo(viteConfig: ResolvedConfig, timebackOptions?: PlaycademyTimebackOptions): Promise<ProjectInfo>;

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

@@ -1,5 +1,6 @@
 import type { ResolvedConfig } from 'vite';
 import type { SandboxManager } from '../../types';
+import type { PlaycademyTimebackOptions } from '../../types/options';
 export declare function startSandbox(viteConfig: ResolvedConfig, autoStart?: boolean, options?: {
     verbose?: boolean;
     customUrl?: string;
@@ -11,4 +12,6 @@ export declare function startSandbox(viteConfig: ResolvedConfig, autoStart?: boo
     realtimeEnabled?: boolean;
     realtimePort?: number;
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
+    timebackId?: string;
+    timebackOptions?: PlaycademyTimebackOptions;
 }): Promise<SandboxManager>;

package/dist/lib/sandbox/timeback.d.ts

@@ -1,7 +1,13 @@
 /**
- * TimeBack configuration detection from environment variables
+ * TimeBack configuration and enrollment utilities
  */
+import type { ResolvedConfig } from 'vite';
 import type { TimebackConfig } from '@playcademy/sandbox/config';
+import type { PlaycademyTimebackOptions } from '../../types/options';
+/**
+ * Get the effective timebackId - defaults to 'mock' if courses are configured
+ */
+export declare function getEffectiveTimebackId(timeback?: Pick<PlaycademyTimebackOptions, 'timebackId' | 'courses'>): string | undefined;
 /**
  * Auto-detect TimeBack configuration from environment variables
  *
@@ -9,3 +15,18 @@ import type { TimebackConfig } from '@playcademy/sandbox/config';
  * Returns undefined if no TimeBack configuration is detected.
  */
 export declare function detectTimebackOptions(): Partial<TimebackConfig> | undefined;
+/**
+ * Check if TimeBack credentials are fully configured
+ */
+export declare function hasTimebackCredentials(): boolean;
+/**
+ * Validate TimeBack config and warn if real course IDs are used without credentials
+ */
+export declare function validateTimebackConfig(viteConfig: ResolvedConfig, timeback?: PlaycademyTimebackOptions): void;
+/**
+ * Generate TimeBack data JSON from timeback config.
+ * Includes role and enrollments for passing to the game shell.
+ *
+ * @returns JSON string with { role, enrollments } or undefined if no courses configured
+ */
+export declare function generateTimebackJson(timeback?: PlaycademyTimebackOptions): string | undefined;

package/dist/server/hotkeys/cycle-timeback-role.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 't' hotkey - cycle TimeBack user role
+ */
+import type { HotkeyOptions } from '../../types';
+export declare const cycleTimebackRoleHotkey: (options: HotkeyOptions) => {
+    key: string;
+    description: string;
+    action: () => void;
+};

package/dist/server/hotkeys/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * CLI Hotkeys for the Playcademy Vite plugin
+ */
+import type { HotkeyOptions } from '../../types';
+export declare function getHotkeys(options: HotkeyOptions): {
+    key: string;
+    description: string;
+    action: () => void;
+}[];

package/dist/server/hotkeys/recreate-database.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 'd' hotkey - recreate sandbox database
+ */
+import type { HotkeyOptions } from '../../types';
+export declare const recreateDatabaseHotkey: (options: HotkeyOptions) => {
+    key: string;
+    description: string;
+    action: () => Promise<void>;
+};

package/dist/server/hotkeys/toggle-mode.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 'm' hotkey - toggle platform/standalone mode
+ */
+import type { HotkeyOptions } from '../../types';
+export declare const toggleModeHotkey: (options: HotkeyOptions) => {
+    key: string;
+    description: string;
+    action: () => Promise<void>;
+};

package/dist/server/middleware.d.ts

@@ -1,3 +1,8 @@
 import type { ViteDevServer } from 'vite';
 import type { SandboxManager } from '../types';
-export declare function devServerMiddleware(server: ViteDevServer, sandbox: SandboxManager, gameUrl: string | undefined, showBadge: boolean): void;
+import type { PlaycademyTimebackOptions } from '../types/options';
+export interface ShellOptions {
+    showBadge: boolean;
+    timeback?: PlaycademyTimebackOptions;
+}
+export declare function devServerMiddleware(server: ViteDevServer, sandbox: SandboxManager, gameUrl: string | undefined, options: ShellOptions): void;

package/dist/server/state.d.ts

@@ -7,7 +7,7 @@
  * these references at module scope to properly clean them up on restart.
  */
 import type { ViteDevServer } from 'vite';
-import type { CliServerManager, SandboxManager } from '../types';
+import type { CliServerManager, SandboxManager, TimebackRoleOverride } from '../types';
 import type { PlaycademyMode } from '../types/options';
 /**
  * Module-level server references
@@ -17,6 +17,7 @@ export declare const serverState: {
     backend: CliServerManager | null;
     viteServer: ViteDevServer | null;
     currentMode: PlaycademyMode;
+    timebackRoleOverride: TimebackRoleOverride | null;
 };
 /**
  * Get sandbox server reference
@@ -54,3 +55,11 @@ export declare function getViteServerRef(): ViteDevServer | null;
  * Set Vite dev server reference
  */
 export declare function setViteServerRef(server: ViteDevServer | null): void;
+/**
+ * Get current TimeBack role override
+ */
+export declare function getTimebackRoleOverride(): TimebackRoleOverride | null;
+/**
+ * Set TimeBack role override
+ */
+export declare function setTimebackRoleOverride(role: TimebackRoleOverride | null): void;

package/dist/types/index.d.ts

@@ -2,4 +2,5 @@
  * Type exports for the Playcademy Vite Plugin
  */
 export type { PlaycademyExportOptions, PlaycademySandboxOptions, PlaycademyShellOptions, PlaycademyPluginOptions, PlaycademyMode, } from './options';
-export type { ResolvedPluginOptions, PluginContext, PlaycademyOutputData, ProjectInfo, SandboxManager, CliServerManager, CliDevServerOptions, PlatformModeOptions, StandaloneModeOptions, ModeSwitcherOptions, } from './internal';
+export type { ResolvedPluginOptions, PluginContext, PlaycademyOutputData, ProjectInfo, TimebackCourseConfig, SandboxManager, CliServerManager, CliDevServerOptions, PlatformModeOptions, StandaloneModeOptions, HotkeyOptions, TimebackRoleOverride, } from './internal';
+export { TIMEBACK_ROLES } from './internal';

package/dist/types/internal.d.ts

@@ -2,7 +2,12 @@
  * Internal plugin state and context types
  */
 import type { ResolvedConfig } from 'vite';
-import type { PlaycademyMode } from './options';
+import type { PlaycademyMode, PlaycademyTimebackOptions } from './options';
+/**
+ * TimeBack roles that can be cycled through in dev mode
+ */
+export declare const TIMEBACK_ROLES: readonly ["student", "parent", "teacher", "administrator"];
+export type TimebackRoleOverride = (typeof TIMEBACK_ROLES)[number];
 /**
  * Internal resolved plugin options
  */
@@ -21,6 +26,7 @@ export interface ResolvedPluginOptions {
     realtimeEnabled: boolean;
     realtimePort?: number;
     showBadge: boolean;
+    timeback?: PlaycademyTimebackOptions;
 }
 /**
  * Plugin context shared across hooks
@@ -40,6 +46,16 @@ export interface PlaycademyOutputData {
     zipPath?: string;
     zipSizeKb?: string;
 }
+/**
+ * TimeBack course configuration from playcademy.config
+ */
+export interface TimebackCourseConfig {
+    subject: string;
+    grade: number;
+    courseId?: string;
+    totalXp?: number | null;
+    masterableUnits?: number | null;
+}
 /**
  * Project information extracted from package.json and directory structure
  */
@@ -48,6 +64,7 @@ export interface ProjectInfo {
     displayName: string;
     version: string;
     description?: string;
+    timebackCourses?: TimebackCourseConfig[];
 }
 /**
  * Sandbox manager interface for controlling sandbox lifecycle
@@ -97,6 +114,7 @@ export interface PlatformModeOptions {
     showBadge: boolean;
     preferredBackendPort: number;
     configPath?: string;
+    timeback?: PlaycademyTimebackOptions;
 }
 /**
  * Options for standalone mode (backend only)
@@ -106,9 +124,9 @@ export interface StandaloneModeOptions {
     configPath?: string;
 }
 /**
- * Options for mode switching
+ * Options for hotkeys and mode switching
  */
-export interface ModeSwitcherOptions {
+export interface HotkeyOptions {
     viteConfig: ResolvedConfig;
     platformModeOptions: PlatformModeOptions;
 }

package/dist/types/options.d.ts

@@ -207,6 +207,54 @@ export interface PlaycademySandboxOptions {
         port?: number;
     };
 }
+/**
+ * TimeBack integration configuration for local development
+ *
+ * @example
+ * ```ts
+ * // Mock enrollments (timebackId auto-generated, role defaults to 'student')
+ * timeback: {
+ *   courses: {
+ *     'FastMath:3': 'mock',
+ *     'FastMath:4': 'mock',
+ *   },
+ * }
+ *
+ * // Testing as a parent viewing their child's progress
+ * timeback: {
+ *   role: 'parent',
+ *   courses: {
+ *     'FastMath:3': 'mock',
+ *   },
+ * }
+ *
+ * // Real TimeBack integration (requires env credentials)
+ * timeback: {
+ *   timebackId: 'real-student-sourced-id',
+ *   courses: {
+ *     'FastMath:3': 'real-course-id-g3',
+ *     'FastMath:4': 'real-course-id-g4',
+ *   },
+ * }
+ * ```
+ */
+export interface PlaycademyTimebackOptions {
+    /**
+     * TimeBack ID for the test user. Optional for mock testing (auto-generated).
+     * Required when testing against real TimeBack - use the student's sourcedId.
+     */
+    timebackId?: string;
+    /**
+     * User role for testing. Defaults to 'student'.
+     * Use this to test parent/teacher views of your game.
+     */
+    role?: 'student' | 'parent' | 'teacher' | 'administrator' | 'guardian';
+    /**
+     * Course enrollments mapping 'Subject:Grade' to 'mock' or real course ID.
+     * Only courses listed here will be enrolled - allows testing partial enrollment.
+     */
+    courses: Record<string, 'mock' | string>;
+}
 /**
  * Configuration options for the development shell wrapper
  *
@@ -334,4 +382,21 @@ export interface PlaycademyPluginOptions {
      * ```
      */
     shell?: PlaycademyShellOptions;
+    /**
+     * TimeBack integration configuration.
+     *
+     * Configure mock or real TimeBack enrollments for local development.
+     * `timebackId` is auto-generated for mock testing.
+     *
+     * @example
+     * ```ts
+     * timeback: {
+     *   courses: {
+     *     'FastMath:3': 'mock',
+     *     'FastMath:4': 'mock',
+     *   },
+     * }
+     * ```
+     */
+    timeback?: PlaycademyTimebackOptions;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "0.1.37",
+    "version": "0.1.40",
     "type": "module",
     "exports": {
         ".": {
@@ -21,11 +21,11 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.14.24"
+        "playcademy": "0.14.25"
     },
     "devDependencies": {
         "@inquirer/prompts": "^7.8.6",
-        "@playcademy/sandbox": "0.1.11",
+        "@playcademy/sandbox": "0.2.3",
         "@types/archiver": "^6.0.3",
         "@types/bun": "latest"
     },

package/dist/server/mode-switcher.d.ts

@@ -1,9 +0,0 @@
-/**
- * Mode switching functionality
- * Handles toggling between platform and standalone modes
- */
-import type { ModeSwitcherOptions } from '../types';
-/**
- * Toggle between platform and standalone modes
- */
-export declare function toggleMode(options: ModeSwitcherOptions): Promise<void>;

package/dist/server/recreate-sandbox-database.d.ts

@@ -1,14 +0,0 @@
-/**
- * Sandbox database recreation functionality
- * Handles recreating the sandbox database on-demand
- */
-import type { ResolvedConfig } from 'vite';
-import type { PlatformModeOptions } from '../types';
-export interface RecreateSandboxDatabaseOptions {
-    viteConfig: ResolvedConfig;
-    platformModeOptions: PlatformModeOptions;
-}
-/**
- * Recreate the sandbox database
- */
-export declare function recreateSandboxDatabase(options: RecreateSandboxDatabaseOptions): Promise<void>;