playcademy 0.27.1-beta.2 → 0.27.1-beta.4

package/dist/bucket.d.ts

@@ -109,6 +109,34 @@ interface IntegrationsConfig {
     /** Queues (optional) */
     queues?: Record<string, QueueConfig | boolean>;
 }
+/**
+ * Developer dashboard configuration.
+ *
+ * The dashboard is a separate app in the game's repo, deployed as a sibling
+ * worker with `playcademy dashboard deploy`. Auth and session plumbing are
+ * platform-managed; the dashboard app itself is just a static SPA build.
+ */
+interface DashboardConfig {
+    /** Path to the dashboard app, relative to the config file (default: './dashboard') */
+    directory?: string;
+    /** Build command run inside the dashboard directory (defaults to the workspace package manager's build script) */
+    buildCommand?: string[];
+    /** Path to the dashboard build output, relative to the dashboard directory (default: 'dist') */
+    buildPath?: string;
+    /** Colors for the platform-managed login/invite page (hex); unset uses the built-in palette */
+    theme?: DashboardThemeConfig;
+}
+/**
+ * Login-page theming. Two seeds — a primary (button, focus, background
+ * wash) and a secondary accent — the platform derives the full palette
+ * from. Either may be omitted to keep that half of the built-in palette.
+ */
+interface DashboardThemeConfig {
+    /** Primary color as a hex string, e.g. '#e0245e' */
+    primary?: string;
+    /** Secondary/accent color as a hex string, e.g. '#ffd166' */
+    secondary?: string;
+}
 /**
  * Unified Playcademy configuration
  * Used for playcademy.config.{js,json}
@@ -130,6 +158,8 @@ interface PlaycademyConfig {
     externalUrl?: string;
     /** Game platform */
     platform?: 'web' | 'godot';
+    /** Developer dashboard app (optional) — `true` uses defaults */
+    dashboard?: DashboardConfig | boolean;
     /** Integrations (database, custom routes, external services) */
     integrations?: IntegrationsConfig;
 }

package/dist/bucket.js

@@ -22,62 +22,12 @@ var init_file_loader = __esm({
 import { existsSync } from "fs";
 import { join as join8 } from "path";
 
-// ../constants/src/timeback.ts
-var TIMEBACK_ROUTES = {
-  END_ACTIVITY: "/integrations/timeback/end-activity",
-  GET_XP: "/integrations/timeback/xp",
-  GET_MASTERY: "/integrations/timeback/mastery",
-  GET_HIGHEST_GRADE_MASTERED: "/integrations/timeback/highest-grade-mastered",
-  HEARTBEAT: "/integrations/timeback/heartbeat",
-  ADVANCE_COURSE: "/integrations/timeback/advance-course",
-  UNENROLL_COURSE: "/integrations/timeback/unenroll-course"
-};
-var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
-  xp: 1,
-  mastery: 0,
-  score: 2
-};
-var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
-  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
-  mastery: 0,
-  time: 60,
-  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
-};
-
-// ../constants/src/cloudflare.ts
-var CLOUDFLARE_COMPATIBILITY_DATE = "2025-10-11";
-
-// ../edge-play/src/constants.ts
+// ../edge-play/src/lib/constants.ts
 var ASSET_PREFIX = "_assets/";
 var MANIFEST_KEY = "_manifest.json";
 var ASSET_ROUTE_PREFIX = "/api/assets/";
-var ROUTES = {
-  /** Route index (lists available routes) */
-  INDEX: "/api",
-  /** Health check endpoint */
-  HEALTH: "/api/health",
-  /**
-   * Built-in content-addressable asset serving.
-   *
-   * Serves files from the game's BUCKET (R2) binding under their
-   * content-hashed keys, with immutable caching. Registered in the
-   * terminal tier so a game's own `server/api/assets/[...path].ts`
-   * route supersedes it.
-   */
-  ASSETS: `${ASSET_ROUTE_PREFIX}*`,
-  /** TimeBack integration routes */
-  TIMEBACK: {
-    END_ACTIVITY: `/api${TIMEBACK_ROUTES.END_ACTIVITY}`,
-    GET_XP: `/api${TIMEBACK_ROUTES.GET_XP}`,
-    GET_MASTERY: `/api${TIMEBACK_ROUTES.GET_MASTERY}`,
-    GET_HIGHEST_GRADE_MASTERED: `/api${TIMEBACK_ROUTES.GET_HIGHEST_GRADE_MASTERED}`,
-    HEARTBEAT: `/api${TIMEBACK_ROUTES.HEARTBEAT}`,
-    ADVANCE_COURSE: `/api${TIMEBACK_ROUTES.ADVANCE_COURSE}`,
-    UNENROLL_COURSE: `/api${TIMEBACK_ROUTES.UNENROLL_COURSE}`
-  }
-};
 
-// src/lib/bundle/backend.ts
+// src/lib/bundle/game-backend.ts
 import { join as join6 } from "node:path";
 
 // src/constants/api.ts
@@ -85,16 +35,16 @@ import { join as join2 } from "node:path";
 
 // src/constants/server.ts
 import { join } from "node:path";
-var SERVER_ROOT_DIRECTORY = "server";
-var SERVER_LIB_DIRECTORY = join(SERVER_ROOT_DIRECTORY, "lib");
+var GAME_SERVER_ROOT_DIRECTORY = "server";
+var GAME_SERVER_LIB_DIRECTORY = join(GAME_SERVER_ROOT_DIRECTORY, "lib");
 
 // src/constants/api.ts
-var DEFAULT_API_ROUTES_DIRECTORY = join2(SERVER_ROOT_DIRECTORY, "api");
+var GAME_API_ROUTES_DIRECTORY = join2(GAME_SERVER_ROOT_DIRECTORY, "api");
 
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.20-beta.1",
+  version: "0.0.20-beta.3",
   type: "module",
   exports: {
     "./server": {
@@ -200,6 +150,22 @@ var CLI_DEFAULT_OUTPUTS = {
   WORKER_BUNDLE: join5(WORKSPACE_NAME, "worker-bundle.js")
 };
 
+// ../constants/src/timeback.ts
+var TIMEBACK_GAME_METRIC_DECIMAL_PLACES = {
+  xp: 1,
+  mastery: 0,
+  score: 2
+};
+var TIMEBACK_GAME_METRIC_COMPARISON_TOLERANCE = {
+  xp: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.xp,
+  mastery: 0,
+  time: 60,
+  score: 0.5 / 10 ** TIMEBACK_GAME_METRIC_DECIMAL_PLACES.score
+};
+
+// ../constants/src/cloudflare.ts
+var CLOUDFLARE_COMPATIBILITY_DATE = "2025-10-11";
+
 // src/lib/core/client.ts
 import { PlaycademyClient } from "@playcademy/sdk/internal";
 
@@ -327,11 +293,13 @@ import {
 // src/lib/core/transpile.ts
 import * as esbuild2 from "esbuild";
 
-// src/lib/bundle/backend.ts
-function getCustomRoutesDirectory(projectPath, config) {
+// src/lib/bundle/game-backend.ts
+function resolveGameRoutesDir(config) {
   const customRoutes = config?.integrations?.customRoutes;
-  const customRoutesDir = typeof customRoutes === "object" && customRoutes.directory || DEFAULT_API_ROUTES_DIRECTORY;
-  return join6(projectPath, customRoutesDir);
+  return typeof customRoutes === "object" && customRoutes.directory || GAME_API_ROUTES_DIRECTORY;
+}
+function getGameRoutesDirectory(projectPath, config) {
+  return join6(projectPath, resolveGameRoutesDir(config));
 }
 
 // src/lib/bucket/local.ts
@@ -354,7 +322,7 @@ async function openLocalBucket() {
 // src/lib/bucket/dev.ts
 var ASSET_DEV_ROUTE_PREFIX = ASSET_ROUTE_PREFIX;
 function hasCustomAssetsRoute(projectRoot, config) {
-  const routesDir = getCustomRoutesDirectory(projectRoot, config);
+  const routesDir = getGameRoutesDirectory(projectRoot, config);
   return existsSync(join8(routesDir, "assets")) || existsSync(join8(routesDir, "assets.ts"));
 }
 function openLocalAssetBucket() {

package/dist/cli.js

@@ -506,11 +506,16 @@ function writeBlank() {
   _consoleLog();
   lastWasBlank = true;
 }
+var FG_RESET = "\x1B[39m";
+function nestColor(content, color2) {
+  const open = color2("").replace(FG_RESET, "");
+  return color2(open ? content.replaceAll(FG_RESET, open) : content);
+}
 function customTransform(text) {
   let result = text;
-  result = result.replace(/`([^`]+)`/g, (_, code) => greenBright(code));
   result = result.replace(/<<([^>]+)>>/g, (_, url) => blueBright(underline(url)));
   result = result.replace(/<([^>]+)>/g, (_, path2) => blueBright(path2));
+  result = result.replace(/`([^`]+)`/g, (_, code) => nestColor(code, greenBright));
   return result;
 }
 function formatTable(data, title) {
@@ -1180,12 +1185,12 @@ import { join as join3 } from "node:path";
 
 // src/constants/server.ts
 import { join as join2 } from "node:path";
-var SERVER_ROOT_DIRECTORY = "server";
-var SERVER_LIB_DIRECTORY = join2(SERVER_ROOT_DIRECTORY, "lib");
-var HOOKS_FILE = "hooks";
+var GAME_SERVER_ROOT_DIRECTORY = "server";
+var GAME_SERVER_LIB_DIRECTORY = join2(GAME_SERVER_ROOT_DIRECTORY, "lib");
+var GAME_HOOKS_FILE = "hooks";
 
 // src/constants/api.ts
-var DEFAULT_API_ROUTES_DIRECTORY = join3(SERVER_ROOT_DIRECTORY, "api");
+var GAME_API_ROUTES_DIRECTORY = join3(GAME_SERVER_ROOT_DIRECTORY, "api");
 var AUTH_API_SUBDIRECTORY = "auth";
 var SAMPLE_API_SUBDIRECTORY = "sample";
 var SAMPLE_CUSTOM_FILENAME = "custom.ts";
@@ -1196,7 +1201,7 @@ var SAMPLE_BUCKET_FILENAME = "bucket.ts";
 // ../better-auth/package.json
 var package_default = {
   name: "@playcademy/better-auth",
-  version: "0.0.20-beta.1",
+  version: "0.0.20-beta.3",
   type: "module",
   exports: {
     "./server": {
@@ -1350,7 +1355,7 @@ var NON_INTERACTIVE_HINTS = {
   PROJECT_DIRECTORY: "Pass a project directory argument or run interactively.",
   MIGRATE_MODE: "Pass --migrate keep or --migrate replace.",
   BUILD_PATH: "Pass --build or set buildPath in playcademy.config.",
-  DASHBOARD_DRIFT: "Resolve dashboard drift interactively or update local config first.",
+  GAME_METADATA_DRIFT: "Resolve game metadata drift interactively or update local config first.",
   TIMEBACK_DRIFT: "Resolve TimeBack config drift interactively before deploying."
 };
 
@@ -1612,6 +1617,40 @@ function validateQueueKey(queueKey) {
 }
 
 // src/lib/config/loader.ts
+function validateDashboardConfig(dashboard) {
+  if (dashboard === true || dashboard === false) {
+    return;
+  }
+  if (typeof dashboard !== "object" || dashboard === null || Array.isArray(dashboard)) {
+    throw new ConfigError(
+      'The "dashboard" field must be a boolean or an object',
+      "dashboard",
+      "Use dashboard: true, or dashboard: { directory: './dashboard' }"
+    );
+  }
+  const config = dashboard;
+  if (config.directory !== void 0 && typeof config.directory !== "string") {
+    throw new ConfigError(
+      'The "dashboard.directory" field must be a string',
+      "dashboard.directory",
+      "Use a path relative to your config file: directory: './dashboard'"
+    );
+  }
+  if (config.buildCommand !== void 0 && (!Array.isArray(config.buildCommand) || config.buildCommand.some((part) => typeof part !== "string"))) {
+    throw new ConfigError(
+      'The "dashboard.buildCommand" field must be an array of strings',
+      "dashboard.buildCommand",
+      "Use command array form: buildCommand: ['bun', 'run', 'build']"
+    );
+  }
+  if (config.buildPath !== void 0 && typeof config.buildPath !== "string") {
+    throw new ConfigError(
+      'The "dashboard.buildPath" field must be a string',
+      "dashboard.buildPath",
+      "Use a path relative to the dashboard directory: buildPath: 'dist'"
+    );
+  }
+}
 function validateQueuesConfig(configName, queues) {
   if (typeof queues !== "object" || queues === null || Array.isArray(queues)) {
     throw new ConfigError(
@@ -1845,6 +1884,9 @@ function validateConfig(config) {
       'Add a name property to your config: name: "My App Name"'
     );
   }
+  if (cfg.dashboard !== void 0) {
+    validateDashboardConfig(cfg.dashboard);
+  }
   if (cfg.integrations) {
     if (typeof cfg.integrations !== "object") {
       throw new ConfigError(
@@ -2546,7 +2588,7 @@ async function promptForTemplate(framework) {
   });
 }
 
-// src/lib/deploy/godot.ts
+// src/lib/deploy/game/godot.ts
 import { existsSync as existsSync7, mkdirSync as mkdirSync2, readFileSync as readFileSync2, rmSync } from "fs";
 import { join as join10 } from "path";
 function isGodotProject() {
@@ -2559,11 +2601,10 @@ import { execSync as execSync3 } from "child_process";
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import path from "node:path";
 var viteConfigTemplate = loadTemplateString("config/vite-config.ts");
-async function findViteConfig() {
-  const workspace = getWorkspace();
+async function findViteConfig(cwd = getWorkspace()) {
   const result = await findFile(
     ["vite.config.ts", "vite.config.js", "vite.config.mts", "vite.config.mjs"],
-    { cwd: workspace }
+    { cwd }
   );
   return result?.path ?? null;
 }
@@ -2572,23 +2613,22 @@ function isPluginConfigured(configPath) {
   return content.includes("@playcademy/vite-plugin") || content.includes("playcademy(");
 }
 async function addVitePlugin(options = {}) {
-  const { install = false } = options;
-  const workspace = getWorkspace();
-  const pkgPath = path.join(workspace, "package.json");
+  const { install = false, dir = getWorkspace() } = options;
+  const pkgPath = path.join(dir, "package.json");
   const pkg = JSON.parse(readFileSync3(pkgPath, "utf8"));
   const hasPlugin = pkg.dependencies?.["@playcademy/vite-plugin"] || pkg.devDependencies?.["@playcademy/vite-plugin"];
   if (hasPlugin) {
     return false;
   }
   if (install) {
-    const pm = detectPackageManager(workspace);
+    const pm = detectPackageManager(dir);
     const command = getAddDevDependencyCommand(pm, "@playcademy/vite-plugin");
     try {
       await runStep(
         "Installing @playcademy/vite-plugin...",
         async () => {
           execSync3(command, {
-            cwd: workspace,
+            cwd: dir,
             stdio: ["ignore", "ignore", "ignore"]
           });
         },
@@ -2607,7 +2647,7 @@ async function addVitePlugin(options = {}) {
   }
   return true;
 }
-async function updateViteConfig(configPath) {
+async function updateViteConfig(configPath, pluginCall = "playcademy()") {
   let content = readFileSync3(configPath, "utf8");
   if (!content.includes("@playcademy/vite-plugin")) {
     const importMatch = content.match(/import .+ from ['"]vite['"]/);
@@ -2621,17 +2661,17 @@ import { playcademy } from '@playcademy/vite-plugin'${content.slice(importIndex)
 ${content}`;
     }
   }
-  if (!content.includes("playcademy()")) {
+  if (!content.includes("playcademy(")) {
     const pluginsMatch = content.match(/plugins:\s*\[/);
     if (pluginsMatch) {
       const pluginsIndex = pluginsMatch.index + pluginsMatch[0].length;
-      content = `${content.slice(0, pluginsIndex)}playcademy(),${content.slice(pluginsIndex)}`;
+      content = `${content.slice(0, pluginsIndex)}${pluginCall},${content.slice(pluginsIndex)}`;
     } else {
       const defineConfigMatch = content.match(/defineConfig\(\{/);
       if (defineConfigMatch) {
         const configIndex = defineConfigMatch.index + defineConfigMatch[0].length;
         content = `${content.slice(0, configIndex)}
-    plugins: [playcademy()],${content.slice(configIndex)}`;
+    plugins: [${pluginCall}],${content.slice(configIndex)}`;
       }
     }
   }
@@ -2841,14 +2881,14 @@ ${socialProviders.join(",\n")}
   return authContent;
 }
 function scaffoldAuthConfig(workspace, authContent) {
-  const libDir = join12(workspace, SERVER_LIB_DIRECTORY);
+  const libDir = join12(workspace, GAME_SERVER_LIB_DIRECTORY);
   if (!existsSync10(libDir)) {
     mkdirSync4(libDir, { recursive: true });
   }
   writeFileSync5(join12(libDir, AUTH_CONFIG_FILE), authContent);
 }
 function scaffoldAuthRoutes(workspace) {
-  const apiDir = join12(workspace, DEFAULT_API_ROUTES_DIRECTORY);
+  const apiDir = join12(workspace, GAME_API_ROUTES_DIRECTORY);
   const authApiDir = join12(apiDir, AUTH_API_SUBDIRECTORY);
   if (!existsSync10(authApiDir)) {
     mkdirSync4(authApiDir, { recursive: true });
@@ -2875,7 +2915,7 @@ export * from './auth'
   }
 }
 function scaffoldProtectedExample(workspace) {
-  const apiDir = join12(workspace, DEFAULT_API_ROUTES_DIRECTORY);
+  const apiDir = join12(workspace, GAME_API_ROUTES_DIRECTORY);
   const sampleDir = join12(apiDir, SAMPLE_API_SUBDIRECTORY);
   if (!existsSync10(sampleDir)) {
     mkdirSync4(sampleDir, { recursive: true });
@@ -2951,7 +2991,7 @@ import { existsSync as existsSync11, mkdirSync as mkdirSync5, readFileSync as re
 import { join as join13 } from "node:path";
 
 // src/version.ts
-var cliVersion = false ? "0.0.0-dev" : "0.27.1-beta.2";
+var cliVersion = false ? "0.0.0-dev" : "0.27.1-beta.4";
 
 // src/lib/init/database.ts
 var drizzleConfigTemplate = loadTemplateString("database/drizzle-config.ts");
@@ -3039,8 +3079,7 @@ async function setupPackageJson2(workspace, appName, stepOptions) {
     return true;
   }
 }
-function hasDatabaseSetup() {
-  const workspace = getWorkspace();
+function hasDatabaseSetup(workspace = getWorkspace()) {
   return DRIZZLE_CONFIG_FILES.some((filename) => existsSync11(join13(workspace, filename)));
 }
 
@@ -3301,7 +3340,7 @@ async function promptForCustomRoutes(requiresRoutes = false) {
   }
   const directory = await input({
     message: "API routes directory:",
-    default: DEFAULT_API_ROUTES_DIRECTORY,
+    default: GAME_API_ROUTES_DIRECTORY,
     nonInteractiveHint: NON_INTERACTIVE_HINTS.API_ROUTES_DIRECTORY,
     validate: (value) => {
       if (!value || value.trim().length === 0) {
@@ -3364,22 +3403,24 @@ function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
-// src/lib/bundle/backend.ts
+// src/lib/bundle/game-backend.ts
 import { existsSync as existsSync13 } from "node:fs";
 import { join as join15 } from "node:path";
 var HOOKS_EXTENSIONS = [".ts", ".tsx", ".js", ".mjs", ".cjs"];
-function getCustomRoutesDirectory(projectPath, config) {
+function resolveGameRoutesDir(config) {
   const customRoutes = config?.integrations?.customRoutes;
-  const customRoutesDir = typeof customRoutes === "object" && customRoutes.directory || DEFAULT_API_ROUTES_DIRECTORY;
-  return join15(projectPath, customRoutesDir);
+  return typeof customRoutes === "object" && customRoutes.directory || GAME_API_ROUTES_DIRECTORY;
+}
+function getGameRoutesDirectory(projectPath, config) {
+  return join15(projectPath, resolveGameRoutesDir(config));
 }
-function hasLocalCustomRoutes(projectPath, config) {
-  const customRoutesDir = getCustomRoutesDirectory(projectPath, config);
+function hasGameCustomRoutes(projectPath, config) {
+  const customRoutesDir = getGameRoutesDirectory(projectPath, config);
   return existsSync13(customRoutesDir);
 }
-function hasHooksModule(workspace) {
+function hasGameHooksModule(workspace) {
   return HOOKS_EXTENSIONS.some(
-    (ext) => existsSync13(join15(workspace, SERVER_ROOT_DIRECTORY, `${HOOKS_FILE}${ext}`))
+    (ext) => existsSync13(join15(workspace, GAME_SERVER_ROOT_DIRECTORY, `${GAME_HOOKS_FILE}${ext}`))
   );
 }
 
@@ -3409,27 +3450,27 @@ function hasKVSetup(config) {
 init_file_loader();
 import { existsSync as existsSync14, readFileSync as readFileSync8, writeFileSync as writeFileSync8 } from "fs";
 import { join as join16 } from "path";
-function hasAllRequiredIncludes(config) {
+function hasAllRequiredIncludes(config, required) {
   if (!config.include) {
     return false;
   }
-  return TSCONFIG_REQUIRED_INCLUDES.every((entry) => config.include.includes(entry));
+  return required.every((entry) => config.include.includes(entry));
 }
-function getMissingIncludes(config) {
+function getMissingIncludes(config, required) {
   if (!config.include) {
-    return [...TSCONFIG_REQUIRED_INCLUDES];
+    return [...required];
   }
-  return TSCONFIG_REQUIRED_INCLUDES.filter((entry) => !config.include.includes(entry));
+  return required.filter((entry) => !config.include.includes(entry));
 }
-function addRequiredIncludes(config) {
+function addRequiredIncludes(config, required) {
   if (!config.include) {
     config.include = [];
   }
-  for (const entry of getMissingIncludes(config)) {
+  for (const entry of getMissingIncludes(config, required)) {
     config.include.push(entry);
   }
 }
-function updateExistingIncludeArray(content) {
+function updateExistingIncludeArray(content, required) {
   const includeRegex = /"include"\s*:\s*\[([^\]]*)\]/;
   const match = content.match(includeRegex);
   if (!match || !match[1]) {
@@ -3437,9 +3478,7 @@ function updateExistingIncludeArray(content) {
   }
   const fullMatch = match[0];
   const arrayContents = match[1];
-  const missingEntries = TSCONFIG_REQUIRED_INCLUDES.filter(
-    (entry) => !arrayContents.includes(entry)
-  );
+  const missingEntries = required.filter((entry) => !arrayContents.includes(entry));
   if (missingEntries.length === 0) {
     return content;
   }
@@ -3459,7 +3498,7 @@ function updateExistingIncludeArray(content) {
   const newIncludeArray = `"include": [${newArrayContents}]`;
   return content.replace(fullMatch, newIncludeArray);
 }
-function addNewIncludeProperty(content) {
+function addNewIncludeProperty(content, required) {
   const closingBraceMatch = content.match(/\n(\s*)\}(\s*)$/);
   if (!closingBraceMatch || closingBraceMatch.index === void 0) {
     return null;
@@ -3469,17 +3508,17 @@ function addNewIncludeProperty(content) {
   const insertPosition = closingBraceMatch.index;
   const beforeClosing = content.slice(0, insertPosition).trim();
   const needsComma = beforeClosing.endsWith("]") || beforeClosing.endsWith("}") || beforeClosing.endsWith('"');
-  const entriesStr = TSCONFIG_REQUIRED_INCLUDES.map((e) => `"${e}"`).join(", ");
+  const entriesStr = required.map((e) => `"${e}"`).join(", ");
   const comma = needsComma ? "," : "";
   const includeEntry = `${comma}
 ${propertyIndent}"include": [${entriesStr}]`;
   const updatedContent = content.slice(0, insertPosition) + includeEntry + content.slice(insertPosition);
   return updatedContent;
 }
-function addToIncludeArrayPreservingComments(content) {
-  return updateExistingIncludeArray(content) || addNewIncludeProperty(content);
+function addToIncludeArrayPreservingComments(content, required) {
+  return updateExistingIncludeArray(content, required) || addNewIncludeProperty(content, required);
 }
-async function ensureTsconfigIncludes(workspace) {
+async function ensureTsconfigIncludes(workspace, required = TSCONFIG_REQUIRED_INCLUDES) {
   for (const filename of TSCONFIG_FILES) {
     const configPath = join16(workspace, filename);
     if (existsSync14(configPath)) {
@@ -3489,19 +3528,22 @@ async function ensureTsconfigIncludes(workspace) {
           stripComments: true
         });
         if (config && (!config.references || filename === TSCONFIG_JSON)) {
-          if (hasAllRequiredIncludes(config)) {
+          if (hasAllRequiredIncludes(config, required)) {
             return filename;
           }
           try {
             const rawContent = readFileSync8(configPath, "utf8");
-            const updatedContent = addToIncludeArrayPreservingComments(rawContent);
+            const updatedContent = addToIncludeArrayPreservingComments(
+              rawContent,
+              required
+            );
             if (updatedContent && updatedContent !== rawContent) {
               writeFileSync8(configPath, updatedContent);
               return filename;
             }
           } catch {
           }
-          addRequiredIncludes(config);
+          addRequiredIncludes(config, required);
           writeFileSync8(configPath, `${JSON.stringify(config, null, 4)}
 `);
           return filename;
@@ -3520,9 +3562,9 @@ function detectBackendFeatures(workspace, config) {
     hasDB: hasDatabaseSetup(),
     hasKV: hasKVSetup(config),
     hasBucket: hasBucketSetup(config),
-    hasRoutes: hasLocalCustomRoutes(workspace, config),
+    hasRoutes: hasGameCustomRoutes(workspace, config),
     hasQueues: hasQueueSetup(config),
-    hasHooks: hasHooksModule(workspace),
+    hasHooks: hasGameHooksModule(workspace),
     hasSecrets: hasEnvFile(workspace)
   };
 }

package/dist/constants.d.ts

@@ -7,7 +7,11 @@ export { GAME_WORKER_DOMAINS, PLAYCADEMY_BASE_URLS, PLAYCADEMY_DOMAINS } from '@
  * Default directory for custom API routes
  * Used when integrations.customRoutes.directory is not specified in config
  */
-declare const DEFAULT_API_ROUTES_DIRECTORY: string;
+declare const GAME_API_ROUTES_DIRECTORY: string;
+/**
+ * Route directory inside a dashboard app (relative to the dashboard root)
+ */
+declare const DASHBOARD_API_ROUTES_DIRECTORY = "api";
 /**
  * Auth routes subdirectory name within API directory (fixed structure)
  */
@@ -75,7 +79,7 @@ declare const DEFAULT_BUCKET_DIRECTORY = "bucket";
  * Cloudflare-related constants
  *
  * Worker runtime pins (`CLOUDFLARE_COMPATIBILITY_DATE`,
- * `BACKEND_COMPATIBILITY_FLAGS`) live in `@playcademy/constants` so every
+ * `WORKER_COMPATIBILITY_FLAGS`) live in `@playcademy/constants` so every
  * package that deploys or emulates workers (CLI, cloudflare, sdk, api-core)
  * agrees on a single source of truth. Import them from there directly.
  */
@@ -310,12 +314,25 @@ declare const CLI_FILES: {
 
 /**
  * Default port numbers for local development servers
+ *
+ * Canonical on purpose: picking a free port at startup caused port climbing
+ * across dev-server restarts (8788 → 8789 → …) while the old process was
+ * still releasing its bind. Every server binds its canonical port and waits
+ * for it to free instead, so URLs stay stable between runs.
  */
 declare const DEFAULT_PORTS: {
     /** Sandbox server (mock platform API) */
     readonly SANDBOX: 4321;
     /** Backend dev server (project backend with HMR) */
-    readonly BACKEND: 8788;
+    readonly GAME: 8788;
+    /** Dashboard worker dev server (composed dashboard runtime + routes) */
+    readonly DASHBOARD: 8789;
+    /**
+     * Dashboard app dev server (the dashboard's own Vite). Deliberately in
+     * the 87xx family with the other backend ports — 5174 collided with the
+     * platform hub's local dev server.
+     */
+    readonly DASHBOARD_APP: 8790;
 };
 
 /**
@@ -334,7 +351,7 @@ declare const NON_INTERACTIVE_HINTS: {
     readonly PROJECT_DIRECTORY: 'Pass a project directory argument or run interactively.';
     readonly MIGRATE_MODE: 'Pass --migrate keep or --migrate replace.';
     readonly BUILD_PATH: 'Pass --build or set buildPath in playcademy.config.';
-    readonly DASHBOARD_DRIFT: 'Resolve dashboard drift interactively or update local config first.';
+    readonly GAME_METADATA_DRIFT: 'Resolve game metadata drift interactively or update local config first.';
     readonly TIMEBACK_DRIFT: 'Resolve TimeBack config drift interactively before deploying.';
 };
 
@@ -347,15 +364,15 @@ declare const NON_INTERACTIVE_HINTS: {
 /**
  * Server root directory (fixed location)
  */
-declare const SERVER_ROOT_DIRECTORY = "server";
+declare const GAME_SERVER_ROOT_DIRECTORY = "server";
 /**
  * Server library/utilities directory (fixed location)
  */
-declare const SERVER_LIB_DIRECTORY: string;
+declare const GAME_SERVER_LIB_DIRECTORY: string;
 /**
  * Hooks file basename (without extension) inside server/
  */
-declare const HOOKS_FILE = "hooks";
+declare const GAME_HOOKS_FILE = "hooks";
 /**
  * Public assets directory (fixed location)
  */
@@ -376,4 +393,4 @@ declare const CONFIG_FILE_NAMES: string[];
  */
 declare const DOCS_URL = "https://docs.dev.playcademy.net/platform";
 
-export { AUTH_API_SUBDIRECTORY, AUTH_CONFIG_FILE, AUTH_PROVIDER_NAMES, BETTER_AUTH_VERSION, BUCKET_ALWAYS_SKIP, CALLBACK_PATH, CALLBACK_PORT, CLI_DEFAULT_OUTPUTS, CLI_DIRECTORIES, CLI_FILES, CLI_USER_DIRECTORIES, CLOUDFLARE_BINDINGS, CONFIG_FILE_NAMES, DB_FILES, DEFAULT_API_ROUTES_DIRECTORY, DEFAULT_BUCKET_DIRECTORY, DEFAULT_DATABASE_DIRECTORY, DEFAULT_PORTS, DEFAULT_TEMPLATE_REF, DOCS_URL, DRIZZLE_CONFIG_FILES, ENV_EXAMPLE_FILE, ENV_FILES, GODOT_ADDON_URL, GODOT_BUILD_DIRECTORIES, GODOT_BUILD_OUTPUTS, GODOT_EXECUTABLE_PATTERNS, GODOT_EXPORT_PRESETS_FILE, GODOT_PROJECT_FILE, GODOT_WEB_PLATFORM, HOOKS_FILE, MINIFLARE_D1_DIRECTORY, NON_INTERACTIVE_HINTS, OAUTH_CALLBACK_URL_PATTERN, PLACEHOLDER_APP_URL, PLAYCADEMY_AUTH_VERSION, PRESIGNED_UPLOAD_THRESHOLD, PUBLIC_DIRECTORY, QUEUE_NAME_PREFIX, SAMPLE_API_SUBDIRECTORY, SAMPLE_BUCKET_FILENAME, SAMPLE_CUSTOM_FILENAME, SAMPLE_DATABASE_FILENAME, SAMPLE_KV_FILENAME, SCHEMA_SUBDIRECTORY, SELF_WORKER_NAME_BINDING, SERVER_LIB_DIRECTORY, SERVER_ROOT_DIRECTORY, SSO_AUTH_TIMEOUT_MS, TEMPLATE_RENAME_FILES, TEMPLATE_REPOS, TSCONFIG_APP_JSON, TSCONFIG_FILES, TSCONFIG_JSON, TSCONFIG_REQUIRED_INCLUDES, WORKSPACE_NAME, cacheVersionDir, getConfigDir, nativeBinaryPath };
+export { AUTH_API_SUBDIRECTORY, AUTH_CONFIG_FILE, AUTH_PROVIDER_NAMES, BETTER_AUTH_VERSION, BUCKET_ALWAYS_SKIP, CALLBACK_PATH, CALLBACK_PORT, CLI_DEFAULT_OUTPUTS, CLI_DIRECTORIES, CLI_FILES, CLI_USER_DIRECTORIES, CLOUDFLARE_BINDINGS, CONFIG_FILE_NAMES, DASHBOARD_API_ROUTES_DIRECTORY, DB_FILES, DEFAULT_BUCKET_DIRECTORY, DEFAULT_DATABASE_DIRECTORY, DEFAULT_PORTS, DEFAULT_TEMPLATE_REF, DOCS_URL, DRIZZLE_CONFIG_FILES, ENV_EXAMPLE_FILE, ENV_FILES, GAME_API_ROUTES_DIRECTORY, GAME_HOOKS_FILE, GAME_SERVER_LIB_DIRECTORY, GAME_SERVER_ROOT_DIRECTORY, GODOT_ADDON_URL, GODOT_BUILD_DIRECTORIES, GODOT_BUILD_OUTPUTS, GODOT_EXECUTABLE_PATTERNS, GODOT_EXPORT_PRESETS_FILE, GODOT_PROJECT_FILE, GODOT_WEB_PLATFORM, MINIFLARE_D1_DIRECTORY, NON_INTERACTIVE_HINTS, OAUTH_CALLBACK_URL_PATTERN, PLACEHOLDER_APP_URL, PLAYCADEMY_AUTH_VERSION, PRESIGNED_UPLOAD_THRESHOLD, PUBLIC_DIRECTORY, QUEUE_NAME_PREFIX, SAMPLE_API_SUBDIRECTORY, SAMPLE_BUCKET_FILENAME, SAMPLE_CUSTOM_FILENAME, SAMPLE_DATABASE_FILENAME, SAMPLE_KV_FILENAME, SCHEMA_SUBDIRECTORY, SELF_WORKER_NAME_BINDING, SSO_AUTH_TIMEOUT_MS, TEMPLATE_RENAME_FILES, TEMPLATE_REPOS, TSCONFIG_APP_JSON, TSCONFIG_FILES, TSCONFIG_JSON, TSCONFIG_REQUIRED_INCLUDES, WORKSPACE_NAME, cacheVersionDir, getConfigDir, nativeBinaryPath };