@playcademy/vite-plugin 1.2.1-beta.2 → 1.2.1-beta.21

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

@@ -1,5 +1,5 @@
 /**
- * 'm' hotkey - cycle platform/demo/standalone mode
+ * 'm' hotkey - cycle platform/demo(/child)/standalone mode
  */
 import type { HotkeyOptions } from '../../types';
 export declare function toggleModeHotkey(options: HotkeyOptions): {

package/dist/server/middleware.d.ts

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

package/dist/server/modes.d.ts

@@ -1,4 +1,17 @@
-import type { PlaycademyMode } from '../types/options';
+import type { PlaycademyMode, PlaycademyParentOptions } from '../types/options';
 export type ShellMode = Exclude<PlaycademyMode, 'standalone'>;
+/**
+ * Validates the `parent` plugin option for child mode. TypeScript users
+ * cannot get this wrong, but a plain-JS vite config can pass a hollow
+ * object; without this check the failure surfaces as an unrelated
+ * TypeError inside the child game, nowhere near the config that caused
+ * it.
+ */
+export declare function assertChildParentOptions(parent: PlaycademyParentOptions | undefined | null): void;
 export declare function isShellMode(mode: PlaycademyMode): mode is ShellMode;
-export declare function getNextMode(mode: PlaycademyMode): PlaycademyMode;
+/**
+ * The `m` hotkey's cycle. `'child'` joins it only when a parent context is
+ * configured: cycling a game into child mode with no intent to deliver
+ * would boot it into a meaningless state.
+ */
+export declare function getNextMode(mode: PlaycademyMode, includeChild: boolean): PlaycademyMode;

package/dist/server/state.d.ts

@@ -9,7 +9,7 @@
 import type { ViteDevServer } from 'vite';
 import type { DashboardAppManager } from '../lib/dashboard-app';
 import type { GameBackendServerManager, PlatformRoleOverride, SandboxManager, TimebackRoleOverride } from '../types';
-import type { PlaycademyMode } from '../types/options';
+import type { PlaycademyMode, PlaycademyParentOptions } from '../types/options';
 /**
  * Module-level server references
  */
@@ -19,6 +19,7 @@ export declare const serverState: {
     dashboardApp: DashboardAppManager | null;
     viteServer: ViteDevServer | null;
     currentMode: PlaycademyMode;
+    parentOptions: PlaycademyParentOptions | null;
     timebackRoleOverride: TimebackRoleOverride | null;
     platformRoleOverride: PlatformRoleOverride | null;
 };
@@ -38,6 +39,14 @@ export declare function hasActiveServers(): boolean;
  * Get current mode
  */
 export declare function getCurrentMode(): PlaycademyMode;
+/**
+ * Get the parent-game context for child mode (null unless configured)
+ */
+export declare function getParentOptions(): PlaycademyParentOptions | null;
+/**
+ * Set the parent-game context for child mode
+ */
+export declare function setParentOptions(parent: PlaycademyParentOptions | null): void;
 /**
  * Set current mode
  */

package/dist/types/index.d.ts

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

package/dist/types/internal.d.ts

@@ -2,7 +2,16 @@
  * Internal plugin state and context types
  */
 import type { ResolvedConfig } from 'vite';
-import type { PlaycademyMode, PlaycademyTimebackOptions } from './options';
+import type { PlaycademyMode, PlaycademyParentOptions, PlaycademyTimebackOptions, ShellCorner } from './options';
+/**
+ * Display options with every default applied.
+ */
+export interface ResolvedDisplayOptions {
+    hideBadge: boolean;
+    badgePosition: ShellCorner;
+    hideRelayPanel: boolean;
+    relayPanelPosition: ShellCorner;
+}
 /**
  * TimeBack roles that can be cycled through in dev mode
  */
@@ -19,6 +28,7 @@ export type PlatformRoleOverride = (typeof PLATFORM_ROLES)[number];
 export interface ResolvedPluginOptions {
     configPath?: string;
     mode: PlaycademyMode;
+    parent?: PlaycademyParentOptions;
     gameBackendPort: number;
     sandboxPort: number;
     dashboardAppPort: number;
@@ -32,7 +42,7 @@ export interface ResolvedPluginOptions {
     seed: boolean;
     memoryOnly: boolean;
     databasePath?: string;
-    hideBadge: boolean;
+    display: ResolvedDisplayOptions;
     timeback?: PlaycademyTimebackOptions | false;
 }
 /**
@@ -134,7 +144,7 @@ export interface PlatformModeOptions {
     seed: boolean;
     memoryOnly: boolean;
     databasePath?: string;
-    hideBadge: boolean;
+    display: ResolvedDisplayOptions;
     gameBackendPort: number;
     configPath?: string;
     timeback?: PlaycademyTimebackOptions | false;

package/dist/types/options.d.ts

@@ -1,17 +1,51 @@
 /**
  * Plugin configuration options
  */
+import type { ParentGameContext, PlaycademyMode as SdkPlaycademyMode } from '@playcademy/sdk/types';
 /**
  * Plugin operation mode
  *
  * Controls how the Vite plugin operates during development:
  * - `'platform'`: Full Playcademy platform experience with sandbox server, backend bundling, and shell wrapper (default)
  * - `'demo'`: Shell-backed development mode that initializes the SDK with `mode: 'demo'`
+ * - `'child'`: Shell impersonates a parent game: INIT carries `mode: 'child'` and the
+ *   `parent` block, and the shell displays what the game relays (requires the `parent` option)
  * - `'standalone'`: Backend only, no sandbox or shell
  *
+ * The union is the SDK's own `PlaycademyMode`, aliased so the two can
+ * never drift: whatever mode the plugin serves lands verbatim in the
+ * game's INIT payload.
+ *
  * @default 'platform'
  */
-export type PlaycademyMode = 'platform' | 'demo' | 'standalone';
+export type PlaycademyMode = SdkPlaycademyMode;
+/**
+ * Parent-game context the dev shell presents in `mode: 'child'`.
+ *
+ * In production a child game is launched by a parent game via
+ * `client.embed.launch()`; the dev shell plays that parent role locally so a
+ * child game can be developed without one. See the parent-child game
+ * embedding proposal (`docs/dev/timeback/` in the platform repo).
+ *
+ * Fields mirror the SDK's `ParentGameContext`, and each is typed from it
+ * directly. The block the dev shell actually sends is additionally checked
+ * against `ParentGameContext` where it is built (see the server middleware),
+ * so it cannot drift from what a real parent game would send.
+ */
+export interface PlaycademyParentOptions {
+    /**
+     * Parent game id stamped into the INIT payload's `parent` block.
+     *
+     * @default 'dev-parent-game'
+     */
+    gameId?: ParentGameContext['gameId'];
+    /**
+     * The `LaunchIntent` delivered to the game as `client.parent.intent`:
+     * which lesson to serve (`lessonId`, in the game's own vocabulary),
+     * and at which pedagogy stage (`eLevel`, the platform's E1-E4 taxonomy).
+     */
+    intent: ParentGameContext['intent'];
+}
 /**
  * Configuration for developing a game's dashboard app.
  *
@@ -276,25 +310,43 @@ export interface PlaycademyTimebackOptions {
      */
     courses?: Record<string, 'mock' | string | null | false>;
 }
+/**
+ * Screen corner for the dev shell's overlay elements.
+ */
+export type ShellCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
 /**
  * Configuration options for the development shell wrapper
  *
  * The shell provides the platform UI during development, including the
- * Playcademy badge and iframe wrapper used by `platform` and `demo` modes.
+ * Playcademy badge and iframe wrapper used by shell modes (`platform`,
+ * `demo`, and `child`).
  */
 export interface PlaycademyDisplayOptions {
     /**
-     * Hide the Playcademy badge in the corner during development.
+     * Hide the Playcademy badge during development.
      *
      * @default false
-     * @example
-     * ```ts
-     * display: {
-     *   hideBadge: true // Hide the badge
-     * }
-     * ```
      */
     hideBadge?: boolean;
+    /**
+     * Corner the badge sits in.
+     *
+     * @default 'top-left'
+     */
+    badgePosition?: ShellCorner;
+    /**
+     * Hide the child-mode relay panel (the live view of what the game
+     * relays to its parent: timing and the end-activity report).
+     *
+     * @default false
+     */
+    hideRelayPanel?: boolean;
+    /**
+     * Corner the relay panel sits in.
+     *
+     * @default 'bottom-left'
+     */
+    relayPanelPosition?: ShellCorner;
 }
 /**
  * Main configuration options for the Playcademy Vite plugin
@@ -345,6 +397,7 @@ export interface PlaycademyPluginOptions {
      *
      * - `'platform'`: Full development experience with sandbox server and shell (recommended)
      * - `'demo'`: Sandbox + shell, but initializes the SDK with `mode: 'demo'`
+     * - `'child'`: Sandbox + shell, but the shell plays a parent game (requires `parent`)
      * - `'standalone'`: Backend bundling only, no platform features
      *
      * Most games should use `'platform'` mode; use `'demo'` to exercise
@@ -359,6 +412,20 @@ export interface PlaycademyPluginOptions {
      * ```
      */
     mode?: PlaycademyMode;
+    /**
+     * Parent-game context for `mode: 'child'`: what the dev shell's INIT
+     * carries in its `parent` block. Required when `mode` is `'child'`;
+     * also enables `'child'` in the `m` hotkey's mode cycle.
+     *
+     * @example
+     * ```ts
+     * {
+     *   mode: 'child',
+     *   parent: { intent: { lessonId: 'two-digit-add', eLevel: 'E2' } }
+     * }
+     * ```
+     */
+    parent?: PlaycademyParentOptions;
     /**
      * Develop a dashboard app instead of a game.
      *
@@ -458,7 +525,8 @@ export interface PlaycademyPluginOptions {
      * ```ts
      * {
      *   display: {
-     *     hideBadge: true
+     *     hideBadge: true,
+     *     relayPanelPosition: 'bottom-right'
      *   }
      * }
      * ```

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "1.2.1-beta.2",
+    "version": "1.2.1-beta.21",
     "type": "module",
     "exports": {
         ".": {
@@ -19,21 +19,21 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.28.1-beta.2"
+        "playcademy": "0.28.1-beta.21"
     },
     "devDependencies": {
         "@electric-sql/pglite": "^0.3.16",
         "@inquirer/prompts": "^7.8.6",
         "@playcademy/constants": "0.0.1",
-        "@playcademy/sandbox": "0.7.1-beta.2",
-        "@playcademy/sdk": "0.16.1-beta.2",
+        "@playcademy/sandbox": "0.7.1-beta.20",
+        "@playcademy/sdk": "0.16.1-beta.20",
         "@playcademy/types": "0.0.1",
         "@playcademy/utils": "0.0.1",
         "@types/archiver": "^6.0.3",
         "@types/bun": "1.3.5"
     },
     "peerDependencies": {
-        "@playcademy/sdk": ">=0.12.0",
+        "@playcademy/sdk": ">=0.17.0",
         "typescript": "^5 || ^6",
         "vite": "^5 || ^6 || ^7 || ^8"
     }