@playcademy/vite-plugin 0.1.40 → 0.2.0

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

@@ -14,6 +14,6 @@ export interface PluginLogger {
 }
 /**
  * Creates a logger adapter that formats logs in Vite's style with [playcademy] prefix
- * @param prefix - Prefix to add to all logs (e.g., 'backend', 'sandbox')
+ * @param domain - Domain to add to all logs (e.g., 'backend', 'sandbox')
  */
-export declare function createLoggerAdapter(prefix: string): PluginLogger;
+export declare function createLoggerAdapter(domain: string): PluginLogger;

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

@@ -1,6 +1,6 @@
 /**
  * Logging utilities
  */
-export { createLoggerAdapter } from './adapter';
 export type { PluginLogger } from './adapter';
-export { log, printBanner } from './utils';
+export { createLoggerAdapter } from './adapter';
+export { createBackendBannerOptions, createTimebackBannerOptions, log, printBanner } from './utils';

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

@@ -1,5 +1,5 @@
 import type { ResolvedConfig } from 'vite';
-import type { ProjectInfo } from '../../types';
+import type { BannerOptions } from '../../types';
 /**
  * Centralized logging utilities for the Vite plugin.
  * Provides clear, prefixed, and color-coded output for multiple servers.
@@ -9,17 +9,18 @@ export declare const log: {
     backend: (msg: string) => void;
     playcademy: (msg: string) => void;
 };
+/**
+ * Create backend banner options from server info
+ */
+export declare function createBackendBannerOptions(backendPort: number | undefined, vitePort: number | undefined): BannerOptions['backend'];
+/**
+ * Create timeback banner options from sandbox state
+ */
+export declare function createTimebackBannerOptions(timebackMode: 'mock' | 'remote' | 'local' | null | undefined, courseCount: number | undefined): BannerOptions['timeback'];
 /**
  * Prints a startup banner showing all running servers in Vite's style.
  *
  * @param viteConfig - Vite resolved configuration
- * @param servers - Object containing port numbers for each server
- * @param projectInfo - Project information
- * @param pluginVersion - Vite plugin version string
+ * @param options - Banner display options
  */
-export declare function printBanner(viteConfig: ResolvedConfig, servers: {
-    sandbox: number;
-    backend?: number;
-    realtime?: number;
-    vite?: number;
-}, projectInfo: ProjectInfo, pluginVersion: string): void;
+export declare function printBanner(viteConfig: ResolvedConfig, options: BannerOptions): void;

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

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

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

@@ -2,8 +2,7 @@
  * Project information extraction for sandbox initialization
  */
 import type { ResolvedConfig } from 'vite';
-import type { ProjectInfo } from '../../types';
-import type { PlaycademyTimebackOptions } from '../../types/options';
+import type { PlaycademyTimebackOptions, ProjectInfo } from '../../types';
 /**
  * Extracts project information from playcademy.config and package.json
  * Used to initialize sandbox with correct project metadata

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

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

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

@@ -3,11 +3,12 @@
  */
 import type { ResolvedConfig } from 'vite';
 import type { TimebackConfig } from '@playcademy/sandbox/config';
+import type { TimebackPluginContext } from '../../types';
 import type { PlaycademyTimebackOptions } from '../../types/options';
 /**
- * Get the effective timebackId - defaults to 'mock' if courses are configured
+ * Get the effective Timeback ID - defaults to 'mock' if courses are configured
  */
-export declare function getEffectiveTimebackId(timeback?: Pick<PlaycademyTimebackOptions, 'timebackId' | 'courses'>): string | undefined;
+export declare function getEffectiveTimebackId(timeback?: Pick<PlaycademyTimebackOptions, 'id' | 'courses'>): string | undefined;
 /**
  * Auto-detect TimeBack configuration from environment variables
  *
@@ -23,10 +24,34 @@ 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;
+type OrgType = 'school' | 'district' | 'department' | 'local' | 'state' | 'national';
+/** SDK-compatible organization shape (includes isPrimary for array format) */
+type SdkOrganization = {
+    id: string;
+    name: string | null;
+    type: string;
+    isPrimary: boolean;
+};
 /**
- * Generate TimeBack data JSON from timeback config.
- * Includes role and enrollments for passing to the game shell.
+ * Resolve organization config to a normalized object.
+ * Used by sandbox config which expects a single organization.
+ * Merges provided values with defaults - only override what you need.
+ */
+export declare function resolveOrganization(orgConfig: PlaycademyTimebackOptions['organization']): {
+    id: string;
+    name?: string;
+    type?: OrgType;
+};
+/**
+ * Resolve organization config into SDK-compatible organizations array.
+ * In dev mode we always have one primary org; defaults to Playcademy mock org.
+ */
+export declare function resolveOrganizations(orgConfig: PlaycademyTimebackOptions['organization']): SdkOrganization[];
+/**
+ * Generate TimeBack data JSON for the game shell.
  *
- * @returns JSON string with { role, enrollments } or undefined if no courses configured
+ * @param context - TimeBack context with base courses and optional overrides
+ * @returns JSON string with { role, enrollments, organizations }, or 'null' if no courses
  */
-export declare function generateTimebackJson(timeback?: PlaycademyTimebackOptions): string | undefined;
+export declare function generateTimebackJson(context?: TimebackPluginContext): string;
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Sandbox Game Token Generator
+ *
+ * Creates a simple JWT-like token for local development that mimics
+ * the platform's game token structure. The sandbox auth will parse
+ * this token to extract the game slug and user ID.
+ *
+ * Format: base64(header).base64(payload).signature
+ * Where:
+ *   - header: { "alg": "none", "typ": "sandbox" }
+ *   - payload: { "sub": gameSlug, "uid": demoUserId }
+ *   - signature: "sandbox" (not cryptographically verified)
+ */
+import type { PlatformRoleOverride } from '../../types';
+/**
+ * Create a sandbox game token
+ *
+ * This token allows the sandbox auth to identify both the user
+ * and the game context, mimicking how the platform issues game JWTs.
+ *
+ * @param gameSlug - The game's slug (used to look up game in sandbox DB)
+ * @param role - Platform role (defaults to 'player')
+ * @returns JWT-like token string
+ */
+export declare function createSandboxGameToken(gameSlug: string, role?: PlatformRoleOverride): string;

package/dist/server/config-watcher.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Watch for config file changes and recreate sandbox
+ *
+ * Watches both playcademy.config.* and vite.config.* files.
+ * When either changes, the sandbox database is recreated automatically.
+ */
+import type { ResolvedConfig, ViteDevServer } from 'vite';
+import type { PlatformModeOptions } from '../types';
+/**
+ * Setup file watcher for config file changes
+ *
+ * Watches playcademy.config.* and vite.config.* files.
+ * When either changes, the sandbox database is automatically recreated.
+ */
+export declare function setupConfigWatcher(server: ViteDevServer, viteConfig: ResolvedConfig, platformModeOptions: PlatformModeOptions): void;

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

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

package/dist/server/middleware.d.ts

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

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

@@ -0,0 +1,21 @@
+/**
+ * Shared utility for recreating the sandbox database
+ */
+import type { ResolvedConfig } from 'vite';
+import type { PlatformModeOptions } from '../types';
+export interface RecreateSandboxOptions {
+    viteConfig: ResolvedConfig;
+    platformModeOptions: PlatformModeOptions;
+}
+export interface RecreateSandboxResult {
+    success: boolean;
+    error?: string;
+}
+/**
+ * Recreate the sandbox database
+ *
+ * This is a shared utility used by:
+ * - 'd' hotkey (manual recreation)
+ * - Config file watcher (automatic recreation on playcademy.config.js changes)
+ */
+export declare function recreateSandbox(options: RecreateSandboxOptions): Promise<RecreateSandboxResult>;

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, TimebackRoleOverride } from '../types';
+import type { CliServerManager, PlatformRoleOverride, SandboxManager, TimebackRoleOverride } from '../types';
 import type { PlaycademyMode } from '../types/options';
 /**
  * Module-level server references
@@ -18,6 +18,7 @@ export declare const serverState: {
     viteServer: ViteDevServer | null;
     currentMode: PlaycademyMode;
     timebackRoleOverride: TimebackRoleOverride | null;
+    platformRoleOverride: PlatformRoleOverride | null;
 };
 /**
  * Get sandbox server reference
@@ -63,3 +64,11 @@ export declare function getTimebackRoleOverride(): TimebackRoleOverride | null;
  * Set TimeBack role override
  */
 export declare function setTimebackRoleOverride(role: TimebackRoleOverride | null): void;
+/**
+ * Get current platform role override
+ */
+export declare function getPlatformRoleOverride(): PlatformRoleOverride | null;
+/**
+ * Set platform role override
+ */
+export declare function setPlatformRoleOverride(role: PlatformRoleOverride | null): void;

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * Type exports for the Playcademy Vite Plugin
  */
-export type { PlaycademyExportOptions, PlaycademySandboxOptions, PlaycademyShellOptions, PlaycademyPluginOptions, PlaycademyMode, } from './options';
-export type { ResolvedPluginOptions, PluginContext, PlaycademyOutputData, ProjectInfo, TimebackCourseConfig, SandboxManager, CliServerManager, CliDevServerOptions, PlatformModeOptions, StandaloneModeOptions, HotkeyOptions, TimebackRoleOverride, } from './internal';
-export { TIMEBACK_ROLES } from './internal';
+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 { TIMEBACK_ROLES, PLATFORM_ROLES } from './internal';

package/dist/types/internal.d.ts

@@ -8,6 +8,11 @@ import type { PlaycademyMode, PlaycademyTimebackOptions } from './options';
  */
 export declare const TIMEBACK_ROLES: readonly ["student", "parent", "teacher", "administrator"];
 export type TimebackRoleOverride = (typeof TIMEBACK_ROLES)[number];
+/**
+ * Platform roles that can be cycled through in dev mode
+ */
+export declare const PLATFORM_ROLES: readonly ["player", "developer", "admin"];
+export type PlatformRoleOverride = (typeof PLATFORM_ROLES)[number];
 /**
  * Internal resolved plugin options
  */
@@ -25,8 +30,8 @@ export interface ResolvedPluginOptions {
     databasePath?: string;
     realtimeEnabled: boolean;
     realtimePort?: number;
-    showBadge: boolean;
-    timeback?: PlaycademyTimebackOptions;
+    hideBadge: boolean;
+    timeback?: PlaycademyTimebackOptions | false;
 }
 /**
  * Plugin context shared across hooks
@@ -35,6 +40,7 @@ export interface PluginContext {
     options: ResolvedPluginOptions;
     viteConfig: ResolvedConfig | null;
     backendPort: number | null;
+    sandboxPort: number | null;
     buildOutputs: PlaycademyOutputData;
 }
 /**
@@ -56,6 +62,19 @@ export interface TimebackCourseConfig {
     totalXp?: number | null;
     masterableUnits?: number | null;
 }
+/**
+ * Combined TimeBack context for vite-plugin internal use.
+ * Bundles base courses (from config) with user overrides (from plugin options).
+ *
+ * NOTE: This is different from SDK's TimebackInitContext which is the
+ * payload sent to games. This is for plugin configuration bundling.
+ */
+export interface TimebackPluginContext {
+    /** Base courses from playcademy.config.js */
+    baseCourses: TimebackCourseConfig[];
+    /** User overrides from vite.config.ts plugin options */
+    overrides?: PlaycademyTimebackOptions;
+}
 /**
  * Project information extracted from package.json and directory structure
  */
@@ -75,7 +94,9 @@ export interface SandboxManager {
     port: number;
     realtimePort?: number;
     project: ProjectInfo | null;
-    cleanup: () => void;
+    timebackMode?: 'mock' | 'remote' | 'local' | null;
+    setRole?: (role: TimebackRoleOverride) => void;
+    cleanup: () => void | Promise<void>;
 }
 /**
  * CLI server manager interface for controlling backend server lifecycle
@@ -92,7 +113,7 @@ export interface CliServerManager {
  * Options for setting up the CLI dev server
  */
 export interface CliDevServerOptions {
-    preferredPort: number;
+    port: number;
     viteConfig: ResolvedConfig;
     platformUrl?: string;
     configPath?: string;
@@ -102,6 +123,7 @@ export interface CliDevServerOptions {
  */
 export interface PlatformModeOptions {
     startSandbox: boolean;
+    sandboxPort: number;
     verbose: boolean;
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     sandboxUrl: string;
@@ -111,16 +133,16 @@ export interface PlatformModeOptions {
     databasePath?: string;
     realtimeEnabled: boolean;
     realtimePort?: number;
-    showBadge: boolean;
-    preferredBackendPort: number;
+    hideBadge: boolean;
+    backendPort: number;
     configPath?: string;
-    timeback?: PlaycademyTimebackOptions;
+    timeback?: PlaycademyTimebackOptions | false;
 }
 /**
  * Options for standalone mode (backend only)
  */
 export interface StandaloneModeOptions {
-    preferredPort: number;
+    backendPort: number;
     configPath?: string;
 }
 /**
@@ -130,3 +152,32 @@ export interface HotkeyOptions {
     viteConfig: ResolvedConfig;
     platformModeOptions: PlatformModeOptions;
 }
+/**
+ * Options for the startup banner
+ */
+export interface BannerOptions {
+    /** Plugin version */
+    version: string;
+    /** Game/project name (platform mode only) */
+    gameName?: string;
+    /** Sandbox server info */
+    sandbox?: {
+        port: number;
+        enabled: true;
+    } | {
+        enabled: false;
+    };
+    /** Backend server info */
+    backend?: {
+        port: number;
+        /** Vite port for proxied URL display */
+        vitePort?: number;
+    };
+    /** Realtime server port (platform mode only) */
+    realtimePort?: number;
+    /** Timeback info (platform mode only) */
+    timeback?: {
+        courseCount: number;
+        mode: 'mock' | 'remote' | 'local';
+    };
+}

package/dist/types/options.d.ts

@@ -208,29 +208,38 @@ export interface PlaycademySandboxOptions {
     };
 }
 /**
- * TimeBack integration configuration for local development
+ * Timeback integration configuration for local development.
+ *
+ * By default, all courses from playcademy.config.js are enrolled with mock IDs.
+ * Use this to override specific courses or exclude them from enrollment.
  *
  * @example
  * ```ts
- * // Mock enrollments (timebackId auto-generated, role defaults to 'student')
+ * // Use all defaults (all courses from config with mock IDs)
+ * timeback: {}
+ *
+ * // Override role only (still enrolls all courses with mock IDs)
+ * timeback: {
+ *   role: 'teacher',
+ * }
+ *
+ * // Override specific course with real ID (others still use mock)
  * timeback: {
  *   courses: {
- *     'FastMath:3': 'mock',
- *     'FastMath:4': 'mock',
+ *     'FastMath:3': 'real-course-id-g3',
  *   },
  * }
  *
- * // Testing as a parent viewing their child's progress
+ * // Exclude a course from enrollment (test partial enrollment)
  * timeback: {
- *   role: 'parent',
  *   courses: {
- *     'FastMath:3': 'mock',
+ *     'FastMath:4': null,  // Not enrolled in grade 4
  *   },
  * }
  *
- * // Real TimeBack integration (requires env credentials)
+ * // Full real Timeback integration
  * timeback: {
- *   timebackId: 'real-student-sourced-id',
+ *   id: 'real-student-sourced-id',
  *   courses: {
  *     'FastMath:3': 'real-course-id-g3',
  *     'FastMath:4': 'real-course-id-g4',
@@ -240,20 +249,38 @@ export interface PlaycademySandboxOptions {
  */
 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.
+     * Timeback ID for the test user. Defaults to auto-generated mock ID.
+     * Set to a real student sourcedId for testing against real Timeback.
      */
-    timebackId?: string;
+    id?: 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.
+     * Organization (school/district) configuration.
+     * Defaults to PLAYCADEMY mock organization. All properties are optional -
+     * only override what you need.
      */
-    courses: Record<string, 'mock' | string>;
+    organization?: 'mock' | {
+        /** Organization sourcedId (defaults to PLAYCADEMY) */
+        id?: string;
+        /** Organization display name (defaults to 'Playcademy Studios') */
+        name?: string;
+        /** Organization type (defaults to 'department') */
+        type?: 'school' | 'district' | 'department' | 'local' | 'state' | 'national';
+    };
+    /**
+     * Course enrollment overrides. By default, all courses from playcademy.config.js
+     * are enrolled with mock IDs.
+     *
+     * - Omit entirely: Use all courses from config with mock IDs
+     * - `'mock'` or omit key: Use mock ID for that course
+     * - Real string: Use that course ID
+     * - `null`: Exclude from enrollment (test partial enrollment)
+     */
+    courses?: Record<string, 'mock' | string | null>;
 }
 /**
  * Configuration options for the development shell wrapper
@@ -261,19 +288,19 @@ export interface PlaycademyTimebackOptions {
  * The shell provides the platform UI during development, including the
  * Playcademy badge, game selection, and other platform features.
  */
-export interface PlaycademyShellOptions {
+export interface PlaycademyDisplayOptions {
     /**
-     * Show the Playcademy badge in the corner during development.
+     * Hide the Playcademy badge in the corner during development.
      *
-     * @default true
+     * @default false
      * @example
      * ```ts
-     * shell: {
-     *   showBadge: false // Hide the badge
+     * display: {
+     *   hideBadge: true // Hide the badge
      * }
      * ```
      */
-    showBadge?: boolean;
+    hideBadge?: boolean;
 }
 /**
  * Main configuration options for the Playcademy Vite plugin
@@ -294,8 +321,8 @@ export interface PlaycademyShellOptions {
  *         logLevel: 'debug',
  *         recreateDb: true
  *       },
- *       shell: {
- *         showBadge: true
+ *       display: {
+ *         hideBadge: true
  *       }
  *     })
  *   ]
@@ -368,25 +395,25 @@ export interface PlaycademyPluginOptions {
      */
     sandbox?: PlaycademySandboxOptions;
     /**
-     * Development shell configuration options.
+     * Display configuration options.
      *
-     * The shell wraps your game with platform UI during development.
+     * Control visual elements during development.
      *
      * @example
      * ```ts
      * {
-     *   shell: {
-     *     showBadge: false
+     *   display: {
+     *     hideBadge: true
      *   }
      * }
      * ```
      */
-    shell?: PlaycademyShellOptions;
+    display?: PlaycademyDisplayOptions;
     /**
-     * TimeBack integration configuration.
+     * Timeback integration configuration.
      *
-     * Configure mock or real TimeBack enrollments for local development.
-     * `timebackId` is auto-generated for mock testing.
+     * Configure mock or real Timeback enrollments for local development.
+     * Timeback `id` is auto-generated for mock testing.
      *
      * @example
      * ```ts
@@ -397,6 +424,8 @@ export interface PlaycademyPluginOptions {
      *   },
      * }
      * ```
+     *
+     * Set to `false` to explicitly disable Timeback even if configured in playcademy.config.
      */
-    timeback?: PlaycademyTimebackOptions;
+    timeback?: PlaycademyTimebackOptions | false;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "0.1.40",
+    "version": "0.2.0",
     "type": "module",
     "exports": {
         ".": {
@@ -19,13 +19,14 @@
         "pub": "bun publish.ts"
     },
     "dependencies": {
+        "@playcademy/utils": "0.0.1",
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.14.25"
+        "playcademy": "0.14.26"
     },
     "devDependencies": {
         "@inquirer/prompts": "^7.8.6",
-        "@playcademy/sandbox": "0.2.3",
+        "@playcademy/sandbox": "0.3.0",
         "@types/archiver": "^6.0.3",
         "@types/bun": "latest"
     },