npm - @playcademy/vite-plugin - Versions diffs - 1.2.1-beta.4 → 1.2.1-beta.5 - Mend

@playcademy/vite-plugin 1.2.1-beta.4 → 1.2.1-beta.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (9) hide show

package/dist/index.js +310 -35
package/dist/server/hotkeys/toggle-mode.d.ts +1 -1
package/dist/server/middleware.d.ts +3 -2
package/dist/server/modes.d.ts +15 -2
package/dist/server/state.d.ts +10 -1
package/dist/types/index.d.ts +2 -2
package/dist/types/internal.d.ts +13 -3
package/dist/types/options.d.ts +78 -10
package/package.json +5 -5

package/dist/index.js CHANGED Viewed

@@ -23757,6 +23757,7 @@ var POSTHOG_CONFIG = {
   uiHost: "https://us.posthog.com"
 };
 // ../constants/src/timeback.ts
+var VALID_E_LEVELS = ["E1", "E2", "E3", "E4"];
 var TIMEBACK_ORG_SOURCED_ID = "PLAYCADEMY";
 var TIMEBACK_ORG_NAME = "Playcademy Studios";
 var TIMEBACK_ORG_TYPE = "department";
@@ -24314,7 +24315,7 @@ import path2 from "node:path";
 // package.json
 var package_default = {
   name: "@playcademy/vite-plugin",
-  version: "1.2.1-beta.4",
+  version: "1.2.1-beta.5",
   type: "module",
   exports: {
     ".": {
@@ -24347,7 +24348,7 @@ var package_default = {
     "@types/bun": "1.3.5"
   },
   peerDependencies: {
-    "@playcademy/sdk": ">=0.12.0",
+    "@playcademy/sdk": ">=0.17.0",
     typescript: "^5 || ^6",
     vite: "^5 || ^6 || ^7 || ^8"
   }
@@ -24635,6 +24636,7 @@ var serverState = {
   dashboardApp: null,
   viteServer: null,
   currentMode: "platform",
+  parentOptions: null,
   timebackRoleOverride: null,
   platformRoleOverride: null
 };
@@ -24647,6 +24649,12 @@ function hasActiveServers() {
 function getCurrentMode() {
   return serverState.currentMode;
 }
+function getParentOptions() {
+  return serverState.parentOptions;
+}
+function setParentOptions(parent) {
+  serverState.parentOptions = parent;
+}
 function setCurrentMode(mode) {
   serverState.currentMode = mode;
 }
@@ -24703,14 +24711,31 @@ import path5 from "node:path";
 import { CONFIG_FILE_NAMES } from "playcademy/constants";
 // src/server/modes.ts
+function assertChildParentOptions(parent) {
+  if (!parent) {
+    throw new Error("[Playcademy] mode: 'child' requires the `parent` option, e.g. parent: { intent: { lessonId: 'my-lesson', eLevel: 'E2' } }");
+  }
+  if (!parent.intent) {
+    throw new Error("[Playcademy] mode: 'child' requires `parent.intent`: the child game boots straight into the lesson it names");
+  }
+  if (!parent.intent.lessonId) {
+    throw new Error("[Playcademy] `parent.intent.lessonId` is required and must be non-empty");
+  }
+  if (!parent.intent.eLevel || !VALID_E_LEVELS.includes(parent.intent.eLevel)) {
+    throw new Error("[Playcademy] `parent.intent.eLevel` is required, one of 'E1' | 'E2' | 'E3' | 'E4'");
+  }
+}
 function isShellMode(mode) {
   return mode !== "standalone";
 }
-function getNextMode(mode) {
+function getNextMode(mode, includeChild) {
   if (mode === "platform") {
     return "demo";
   }
   if (mode === "demo") {
+    return includeChild ? "child" : "standalone";
+  }
+  if (mode === "child") {
     return "standalone";
   }
   return "platform";
@@ -25887,7 +25912,7 @@ var package_default2;
 var init_package = __esm(() => {
   package_default2 = {
     name: "@playcademy/sandbox",
-    version: "0.7.1-beta.4",
+    version: "0.7.1-beta.5",
     description: "Local development server for Playcademy game development",
     type: "module",
     exports: {
@@ -181514,10 +181539,24 @@ var shell_default2 = `<!doctype html>
                 height: 100vh;
                 overflow: hidden;
             }
-            #badge {
-                position: fixed;
+            .corner-top-left {
                 top: 0.5rem;
                 left: 0.5rem;
+            }
+            .corner-top-right {
+                top: 0.5rem;
+                right: 0.5rem;
+            }
+            .corner-bottom-left {
+                bottom: 0.5rem;
+                left: 0.5rem;
+            }
+            .corner-bottom-right {
+                bottom: 0.5rem;
+                right: 0.5rem;
+            }
+            #badge {
+                position: fixed;
                 background: rgba(23, 23, 23, 0.9);
                 color: white;
                 padding: 0.25rem 0.5rem;
@@ -181532,6 +181571,28 @@ var shell_default2 = `<!doctype html>
             #badge.offline {
                 background: rgba(211, 47, 47, 0.9);
             }
+            #relay {
+                position: fixed;
+                background: rgba(23, 23, 23, 0.9);
+                color: #e0e0e0;
+                padding: 0.5rem 0.75rem;
+                border-radius: 4px;
+                font-family: 'VT323', monospace;
+                font-size: 1rem;
+                z-index: 9999;
+                backdrop-filter: blur(10px);
+                letter-spacing: 0.05em;
+                max-width: 26rem;
+            }
+            #relay .dim {
+                color: #9e9e9e;
+            }
+            #relay-report {
+                color: #7cfc98;
+            }
+            #relay-report.ignored {
+                color: #f87171;
+            }
             #frame {
                 position: absolute;
                 inset: 0;
@@ -181545,11 +181606,26 @@ var shell_default2 = `<!doctype html>
         </style>
     </head>
     <body>
-        <div id="badge">PLAYCADEMY</div>
+        <div id="badge" class="corner-{{BADGE_POSITION}}">PLAYCADEMY</div>
+        <div id="relay" class="hidden corner-{{RELAY_PANEL_POSITION}}">
+            <div id="relay-intent"></div>
+            <div id="relay-time" class="dim">active 0s / paused 0s</div>
+            <div id="relay-report"></div>
+        </div>
         <iframe id="frame" class="hidden"></iframe>
         <script type="module">
-            const { MessageEvents, messaging } = await import('/@playcademy/shell-sdk')
+            const {
+                MessageEvents,
+                messaging,
+                HANDSHAKE_RESEND_INTERVAL_MS,
+                HANDSHAKE_MAX_DURATION_MS,
+                SDK_SUPPORTS_CHILD_MODE,
+            } = await import('/@playcademy/shell-sdk')
+            // ============================================================
+            // Templated config (filled in by the dev server middleware)
+            // ============================================================
             const CONFIG = {
                 sandboxUrl: '{{SANDBOX_URL}}',
@@ -181557,27 +181633,149 @@ var shell_default2 = `<!doctype html>
                 gameToken: '{{GAME_TOKEN}}',
                 gameUrl: '{{GAME_URL}}' || undefined,
                 mode: '{{MODE}}',
-                timebackJson: '{{TIMEBACK_DATA}}',
+                timebackJson: {{TIMEBACK_DATA}},
+                parentJson: {{PARENT_DATA}},
                 hideBadge: '{{HIDE_BADGE}}' === 'true',
+                hideRelayPanel: '{{HIDE_RELAY_PANEL}}' === 'true',
             }
-            const timeback = (() => {
+            function parseJsonOrNull(raw) {
                 try {
-                    return JSON.parse(CONFIG.timebackJson)
+                    return JSON.parse(raw)
                 } catch {
                     return null
                 }
-            })()
+            }
-            const badge = document.getElementById('badge')
-            const frame = document.getElementById('frame')
+            const timeback = parseJsonOrNull(CONFIG.timebackJson)
+            const parentContext = parseJsonOrNull(CONFIG.parentJson)
-            if (CONFIG.hideBadge) {
-                badge.classList.add('hidden')
+            if (CONFIG.mode === 'child' && !SDK_SUPPORTS_CHILD_MODE) {
+                console.error(
+                    "[Playcademy] mode 'child' needs an @playcademy/sdk that ships client.parent (>= 0.16.0); the project's installed SDK predates it. Upgrade the SDK dependency.",
+                )
             }
+            // ============================================================
+            // DOM + logging
+            // ============================================================
+            const badge = document.getElementById('badge')
+            const frame = document.getElementById('frame')
             const log = (...args) => window.PLAYCADEMY_DEBUG && console.log('[DevShell]', ...args)
+            // ============================================================
+            // Child-mode relay panel
+            // ============================================================
+            // In child mode the shell plays the parent game, and the game's
+            // relayed messages replace every backend POST it would otherwise
+            // make - they ARE the integration's output, so the panel shows
+            // them: the opened run, live timing, and the final report.
+            const relayPanel = (() => {
+                const root = document.getElementById('relay')
+                const els = {
+                    intent: document.getElementById('relay-intent'),
+                    time: document.getElementById('relay-time'),
+                    report: document.getElementById('relay-report'),
+                }
+                // Each relay message is a cumulative snapshot of ONE window
+                // (keyed by windowStartedAtMs), and the tracker rotates
+                // windows on its 15s accounting cadence and on tab-hide.
+                // Keep the latest snapshot per window; sum the windows.
+                const windows = new Map()
+                let sawBeat = false
+                let reported = false
+                const isTrackerRelay = type =>
+                    type === MessageEvents.TIMEBACK_ACTIVITY_START ||
+                    type === MessageEvents.TIMEBACK_HEARTBEAT_RELAY ||
+                    type === MessageEvents.TIMEBACK_ACTIVITY_END
+                function show(intent) {
+                    const { lessonId, eLevel } = intent ?? {}
+                    els.intent.textContent = \`intent: \${lessonId}\${eLevel ? \` (\${eLevel})\` : ''}\`
+                    root.classList.remove('hidden')
+                }
+                function onMessage(type, payload) {
+                    if (type === MessageEvents.READY) {
+                        // A reloaded game document is a fresh launch.
+                        reported = false
+                        windows.clear()
+                        els.report.textContent = ''
+                        els.report.classList.remove('ignored')
+                        return
+                    }
+                    // One report per launch, exactly like a production
+                    // parent: after the report the books are closed, so a
+                    // replay loop fails here, at the developer's desk.
+                    if (reported && isTrackerRelay(type)) {
+                        els.report.textContent = '⚠ ignored: already reported (one report per launch)'
+                        els.report.classList.add('ignored')
+                        console.error(
+                            '[DevShell] this launch already reported; ignoring tracker relays, exactly as a parent game would. One report per launch: report once, then exit.',
+                        )
+                        return
+                    }
+                    if (type === MessageEvents.TIMEBACK_ACTIVITY_START) {
+                        // A fresh run's timing must not sum with the last
+                        // run's windows.
+                        windows.clear()
+                        console.log('[DevShell] child relay: activity start', payload)
+                    }
+                    if (type === MessageEvents.TIMEBACK_HEARTBEAT_RELAY) {
+                        const key = payload?.windowStartedAtMs
+                        if (typeof key === 'number') {
+                            windows.set(key, {
+                                activeMs: payload?.timingData?.activeMs ?? 0,
+                                pausedMs: payload?.timingData?.pausedMs ?? 0,
+                            })
+                        }
+                        let activeMs = 0
+                        let pausedMs = 0
+                        for (const w of windows.values()) {
+                            activeMs += w.activeMs
+                            pausedMs += w.pausedMs
+                        }
+                        els.time.textContent = \`active \${Math.round(activeMs / 1000)}s / paused \${Math.round(pausedMs / 1000)}s\`
+                        // Dim zeros that never brighten mean the game never
+                        // called startActivity().
+                        if (!sawBeat) {
+                            sawBeat = true
+                            els.time.classList.remove('dim')
+                        }
+                    }
+                    if (type === MessageEvents.TIMEBACK_ACTIVITY_END) {
+                        const score = payload?.scoreData
+                        // durationSeconds is the FULL sitting;
+                        // sessionTimingData is only the post-flush remainder
+                        // (near zero by design).
+                        const seconds = payload?.timingData?.durationSeconds
+                        els.report.textContent = \`report: \${score?.correctQuestions}/\${score?.totalQuestions} correct, xp \${payload?.xpEarned ?? 'n/a'}, \${seconds}s (full report in console)\`
+                        console.log('[DevShell] child relay: end-activity report', payload)
+                        reported = true
+                    }
+                }
+                return { show, onMessage }
+            })()
+            // ============================================================
+            // Sandbox liveness
+            // ============================================================
             async function checkSandbox() {
                 // Use the public /health endpoint as a pure liveness probe.
                 // We used to hit /api/users/me here, but that's \`requireNonAnonymous\`
@@ -181598,14 +181796,25 @@ var shell_default2 = `<!doctype html>
                 }
             }
-            function initHandshake(timebackData) {
+            // ============================================================
+            // INIT handshake (shell → game)
+            // ============================================================
+            function initHandshake() {
                 const payload = {
                     baseUrl: CONFIG.sandboxUrl,
                     gameUrl: CONFIG.gameUrl,
                     gameId: CONFIG.gameId,
                     token: CONFIG.gameToken,
                     mode: CONFIG.mode,
-                    timeback: timebackData,
+                    // A production parent never forwards its own timeback
+                    // user context to a child; mirror that omission.
+                    timeback: CONFIG.mode === 'child' ? undefined : timeback,
+                    parent: parentContext ?? undefined,
+                    // Child embedders consume the relay stream (the panel
+                    // below), so the game's tracker must not beacon its own
+                    // backend on unload — same flag embed.launch() sets.
+                    hasHeartbeatRelay: CONFIG.mode === 'child' ? true : undefined,
                 }
                 let interval, timeout
@@ -181628,11 +181837,14 @@ var shell_default2 = `<!doctype html>
                     frame.classList.remove('hidden')
                     log('Frame loaded, starting handshake')
                     send()
-                    interval = setInterval(send, 300)
+                    interval = setInterval(send, HANDSHAKE_RESEND_INTERVAL_MS)
+                    // The SDK's constant exceeds the game's 25s INIT wait so
+                    // a struggling game can send INIT_ERROR before the shell
+                    // gives up.
                     timeout = setTimeout(() => {
                         stop()
                         log('Handshake timeout')
-                    }, 10000)
+                    }, HANDSHAKE_MAX_DURATION_MS)
                 }
                 messaging.listen(MessageEvents.READY, () => {
@@ -181643,29 +181855,67 @@ var shell_default2 = `<!doctype html>
                 frame.src = '/'
             }
-            window.addEventListener('message', e => {
-                if (e.source !== frame.contentWindow) return
-                const { type, ...payload } = e.data || {}
-                if (type?.startsWith('PLAYCADEMY_')) {
-                    log('Message:', type, payload)
-                    messaging.send(type, payload)
+            // ============================================================
+            // Game → shell message routing
+            // ============================================================
+            // The wire shape is { type, payload }. Everything the game posts
+            // gets logged and re-dispatched locally so shell-side listeners
+            // (messaging.listen) can consume it; in child mode the relay
+            // panel also gets each payload.
+            window.addEventListener('message', event => {
+                if (event.source !== frame.contentWindow) return
+                const { type, payload } = event.data || {}
+                if (!type?.startsWith('PLAYCADEMY_')) return
+                log('Message:', type, payload)
+                if (CONFIG.mode === 'child') {
+                    relayPanel.onMessage(type, payload)
                 }
+                messaging.send(type, payload)
             })
-            checkSandbox().then(() => initHandshake(timeback))
+            // ============================================================
+            // Boot
+            // ============================================================
+            if (CONFIG.hideBadge) {
+                badge.classList.add('hidden')
+            }
+            if (CONFIG.mode === 'child' && parentContext) {
+                badge.textContent = 'PLAYCADEMY CHILD'
+                if (!CONFIG.hideRelayPanel) {
+                    relayPanel.show(parentContext.intent)
+                }
+            }
+            checkSandbox().then(() => initHandshake())
         </script>
     </body>
 </html>
 `;
 // src/server/middleware.ts
+function jsonScriptLiteral(json6) {
+  return JSON.stringify(json6).replace(/</g, String.raw`\u003c`);
+}
 function generateLoaderHTML(sandboxUrl, gameSlug, gameId, options, gameUrl) {
   const timebackJson = generateTimebackJson(options.timeback);
   const mode = getCurrentMode();
+  const parentOptions = getParentOptions();
+  const parentJson = mode === "child" && parentOptions ? JSON.stringify({
+    gameId: parentOptions.gameId ?? "dev-parent-game",
+    intent: parentOptions.intent
+  }) : "null";
   const tokenIdentity = mode === "demo" ? "anonymous" : getPlatformRoleOverride() ?? "player";
   const gameToken = createSandboxGameToken(gameSlug, tokenIdentity);
   const handshakeGameId = gameId || gameSlug;
-  return shell_default2.replace(/{{SANDBOX_URL}}/g, sandboxUrl).replace(/{{GAME_ID}}/g, handshakeGameId).replace(/{{GAME_TOKEN}}/g, gameToken).replace(/{{GAME_URL}}/g, gameUrl || "").replace(/{{MODE}}/g, isShellMode(mode) ? mode : "platform").replace(/{{TIMEBACK_DATA}}/g, timebackJson).replace(/{{HIDE_BADGE}}/g, String(options.hideBadge));
+  return shell_default2.replace(/{{SANDBOX_URL}}/g, () => sandboxUrl).replace(/{{GAME_ID}}/g, () => handshakeGameId).replace(/{{GAME_TOKEN}}/g, () => gameToken).replace(/{{GAME_URL}}/g, () => gameUrl || "").replace(/{{MODE}}/g, () => isShellMode(mode) ? mode : "platform").replace(/{{TIMEBACK_DATA}}/g, () => jsonScriptLiteral(timebackJson)).replace(/{{PARENT_DATA}}/g, () => jsonScriptLiteral(parentJson)).replace(/{{HIDE_BADGE}}/g, () => String(options.display.hideBadge)).replace(/{{BADGE_POSITION}}/g, () => options.display.badgePosition).replace(/{{HIDE_RELAY_PANEL}}/g, () => String(options.display.hideRelayPanel)).replace(/{{RELAY_PANEL_POSITION}}/g, () => options.display.relayPanelPosition);
 }
 function devServerMiddleware(server, sandbox, gameUrl, options) {
   server.middlewares.use("/", (req, res, next) => {
@@ -181724,7 +181974,7 @@ async function recreateSandbox(options) {
   if (sandbox.project && serverState.gameBackend) {
     const gameUrl = `http://localhost:${serverState.gameBackend.port}`;
     devServerMiddleware(viteServer, sandbox, gameUrl, {
-      hideBadge: platformModeOptions.hideBadge,
+      display: platformModeOptions.display,
       timeback: timebackDisabled ? undefined : {
         baseCourses: sandbox.project.timebackCourses ?? [],
         overrides: timebackOptions
@@ -182029,7 +182279,7 @@ async function configurePlatformMode(server, viteConfig, options) {
       overrides: timebackOptions
     };
     devServerMiddleware(server, sandbox, gameUrl, {
-      hideBadge: options.hideBadge,
+      display: options.display,
       timeback: timebackContext
     });
   }
@@ -182081,13 +182331,21 @@ async function configureStandaloneMode(server, viteConfig, options) {
 // src/server/hotkeys/toggle-mode.ts
 async function toggleMode(options) {
   const currentMode = getCurrentMode();
-  const newMode = getNextMode(currentMode);
+  let newMode = getNextMode(currentMode, getParentOptions() !== null);
   const viteServer = getViteServerRef();
   const prefix2 = createLogPrefix("playcademy");
   if (!viteServer) {
     options.viteConfig.logger.error(`${prefix2} ${import_picocolors16.red("Cannot toggle mode: no Vite server reference")}`);
     return;
   }
+  if (newMode === "child") {
+    try {
+      assertChildParentOptions(getParentOptions());
+    } catch (error89) {
+      options.viteConfig.logger.error(`${prefix2} ${import_picocolors16.red(errorMessage(error89))}`);
+      newMode = getNextMode(newMode, false);
+    }
+  }
   await cleanupServers();
   await new Promise((resolve2) => setTimeout(resolve2, 100));
   setCurrentMode(newMode);
@@ -182104,7 +182362,7 @@ async function toggleMode(options) {
 function toggleModeHotkey(options) {
   return {
     key: "m",
-    description: `${import_picocolors16.cyan(import_picocolors16.bold("[playcademy]"))} cycle platform/demo/standalone mode`,
+    description: `${import_picocolors16.cyan(import_picocolors16.bold("[playcademy]"))} cycle dev mode`,
     action: () => toggleMode(options)
   };
 }
@@ -182145,8 +182403,12 @@ async function configureServerHook(server, context) {
   if (!context.viteConfig) {
     throw new Error("[Playcademy] Vite config not resolved before configureServer");
   }
+  if (context.options.mode === "child") {
+    assertChildParentOptions(context.options.parent);
+  }
   setViteServerRef(server);
   setCurrentMode(context.options.mode);
+  setParentOptions(context.options.parent ?? null);
   setupProcessShutdownHandlers();
   await registerAssetMiddleware(server, context.viteConfig.root, context.options.configPath);
   if (hasActiveServers()) {
@@ -182164,7 +182426,7 @@ async function configureServerHook(server, context) {
     seed: context.options.seed,
     memoryOnly: context.options.memoryOnly,
     databasePath: context.options.databasePath,
-    hideBadge: context.options.hideBadge,
+    display: context.options.display,
     gameBackendPort: context.options.gameBackendPort,
     configPath: context.options.configPath,
     timeback: context.options.timeback
@@ -182193,7 +182455,14 @@ function resolveShellSdkId(id) {
 }
 function loadShellSdk(id) {
   if (id === SHELL_SDK_ID) {
-    return `export { MessageEvents, messaging } from '@playcademy/sdk'`;
+    return [
+      `export { MessageEvents, messaging } from '@playcademy/sdk'`,
+      `import * as internal from '@playcademy/sdk/internal'`,
+      `export const HANDSHAKE_RESEND_INTERVAL_MS = internal.HANDSHAKE_RESEND_INTERVAL_MS ?? 300`,
+      `export const HANDSHAKE_MAX_DURATION_MS = internal.HANDSHAKE_MAX_DURATION_MS ?? 30000`,
+      `export const SDK_SUPPORTS_CHILD_MODE = internal.HANDSHAKE_MAX_DURATION_MS !== undefined`
+    ].join(`
+`);
   }
 }
@@ -182266,6 +182535,7 @@ function resolveOptions(options) {
   return {
     configPath: options.configPath,
     mode: options.mode ?? "platform",
+    parent: options.parent,
     gameBackendPort: options.gameBackendPort ?? DEFAULT_PORTS4.GAME,
     sandboxPort,
     dashboardAppPort: options.dashboardAppPort ?? DEFAULT_PORTS4.DASHBOARD_APP,
@@ -182279,7 +182549,12 @@ function resolveOptions(options) {
     seed: sandboxOptions.seed ?? true,
     memoryOnly: sandboxOptions.memoryOnly ?? false,
     databasePath: sandboxOptions.databasePath,
-    hideBadge: displayOptions.hideBadge ?? false,
+    display: {
+      hideBadge: displayOptions.hideBadge ?? false,
+      badgePosition: displayOptions.badgePosition ?? "top-left",
+      hideRelayPanel: displayOptions.hideRelayPanel ?? false,
+      relayPanelPosition: displayOptions.relayPanelPosition ?? "bottom-left"
+    },
     timeback: options.timeback
   };
 }

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "1.2.1-beta.4",
+    "version": "1.2.1-beta.5",
     "type": "module",
     "exports": {
         ".": {
@@ -19,21 +19,21 @@
     "dependencies": {
         "archiver": "^7.0.1",
         "picocolors": "^1.1.1",
-        "playcademy": "0.28.1-beta.4"
+        "playcademy": "0.28.1-beta.5"
     },
     "devDependencies": {
         "@electric-sql/pglite": "^0.3.16",
         "@inquirer/prompts": "^7.8.6",
         "@playcademy/constants": "0.0.1",
-        "@playcademy/sandbox": "0.7.1-beta.4",
-        "@playcademy/sdk": "0.16.1-beta.4",
+        "@playcademy/sandbox": "0.7.1-beta.5",
+        "@playcademy/sdk": "0.16.1-beta.5",
         "@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"
     }