@playcademy/vite-plugin 0.1.26-alpha.6 → 0.1.26-alpha.7

package/README.md

@@ -78,13 +78,15 @@ export default defineConfig({
     plugins: [
         playcademy({
             export: {
-                platform: 'web', // Platform identifier (auto-detected)
                 autoZip: true, // Create deployment zip (enabled by default)
             },
             sandbox: {
                 autoStart: true, // Start sandbox automatically
-                url: 'http://localhost:4321', // Sandbox URL
                 verbose: false, // Enable debug logging
+                logLevel: 'info', // Log level (debug, info, warn, error)
+                seed: true, // Seed database with demo data
+                recreateDb: false, // Recreate database on each start
+                memoryOnly: false, // Use in-memory database
                 realtime: {
                     enabled: false, // Disabled by default, enable for multiplayer
                     port: 4322, // Defaults to API port + 1
@@ -143,14 +145,24 @@ Configuration for manifest generation and build output:
 
 Configuration for the development sandbox server:
 
-| Option       | Type                                     | Default                       | Description                      |
-| ------------ | ---------------------------------------- | ----------------------------- | -------------------------------- |
-| `autoStart`  | `boolean`                                | `true`                        | Start sandbox during development |
-| `url`        | `string`                                 | `'http://localhost:4321/api'` | Sandbox server URL               |
-| `verbose`    | `boolean`                                | `false`                       | Enable verbose logging           |
-| `logLevel`   | `'debug' \| 'info' \| 'warn' \| 'error'` | `'info'`                      | Log level for sandbox server     |
-| `recreateDb` | `boolean`                                | `false`                       | Recreate database on each start  |
-| `realtime`   | `object`                                 | `{...}`                       | Real-time server configuration   |
+| Option         | Type                                     | Default                       | Description                             |
+| -------------- | ---------------------------------------- | ----------------------------- | --------------------------------------- |
+| `autoStart`    | `boolean`                                | `true`                        | Start sandbox during development        |
+| `url`          | `string`                                 | `'http://localhost:4321/api'` | Sandbox server URL                      |
+| `verbose`      | `boolean`                                | `false`                       | Enable verbose logging                  |
+| `logLevel`     | `'debug' \| 'info' \| 'warn' \| 'error'` | `'info'`                      | Log level for sandbox server            |
+| `recreateDb`   | `boolean`                                | `false`                       | Recreate database on each start         |
+| `seed`         | `boolean`                                | `true`                        | Seed database with demo data            |
+| `memoryOnly`   | `boolean`                                | `false`                       | Use in-memory database (non-persistent) |
+| `databasePath` | `string`                                 | `undefined`                   | Custom path for database file           |
+| `realtime`     | `object`                                 | `{ enabled: false }`          | Real-time server configuration          |
+
+#### Realtime Options (`sandbox.realtime`)
+
+| Option    | Type      | Default      | Description                      |
+| --------- | --------- | ------------ | -------------------------------- |
+| `enabled` | `boolean` | `false`      | Enable WebSocket server          |
+| `port`    | `number`  | API port + 1 | Custom port for WebSocket server |
 
 ## Build Output
 
@@ -317,6 +329,7 @@ export default defineConfig({
             sandbox: {
                 realtime: {
                     enabled: true,
+                    port: 4322, // Optional: custom WebSocket port
                 },
             },
         }),
@@ -324,6 +337,36 @@ export default defineConfig({
 })
 ```
 
+### Testing with Clean Database
+
+```typescript
+// Start with a fresh database on each dev server restart
+export default defineConfig({
+    plugins: [
+        playcademy({
+            sandbox: {
+                recreateDb: true, // Recreate database on each start
+            },
+        }),
+    ],
+})
+```
+
+### In-Memory Database for CI
+
+```typescript
+// Use in-memory database for fast, ephemeral testing
+export default defineConfig({
+    plugins: [
+        playcademy({
+            sandbox: {
+                memoryOnly: true, // Database in RAM only
+            },
+        }),
+    ],
+})
+```
+
 ### Godot Export
 
 ```typescript

package/dist/index.js

@@ -41271,7 +41271,11 @@ function printBanner(viteConfig, servers, projectInfo, pluginVersion) {
   viteConfig.logger.info(`${INDENT}${import_picocolors3.green("➜")}  ${import_picocolors3.bold("Game:")}     ${import_picocolors3.cyan(projectInfo.slug)}`);
   viteConfig.logger.info(`${INDENT}${import_picocolors3.green("➜")}  ${import_picocolors3.bold("Sandbox:")}  ${import_picocolors3.cyan(`http://localhost:${import_picocolors3.bold(servers.sandbox.toString())}/api`)}`);
   if (servers.backend) {
-    viteConfig.logger.info(`${INDENT}${import_picocolors3.green("➜")}  ${import_picocolors3.bold("Backend:")}  ${import_picocolors3.cyan(`http://localhost:${import_picocolors3.bold(servers.backend.toString())}/api`)}`);
+    const backendUrl = servers.vite ? `http://localhost:${import_picocolors3.bold(servers.vite.toString())}/api ${import_picocolors3.dim(`(via ${servers.backend})`)}` : `http://localhost:${import_picocolors3.bold(servers.backend.toString())}/api`;
+    viteConfig.logger.info(`${INDENT}${import_picocolors3.green("➜")}  ${import_picocolors3.bold("Backend:")}  ${import_picocolors3.cyan(backendUrl)}`);
+  }
+  if (servers.realtime) {
+    viteConfig.logger.info(`${INDENT}${import_picocolors3.green("➜")}  ${import_picocolors3.bold("Realtime:")} ${import_picocolors3.cyan(`ws://localhost:${import_picocolors3.bold(servers.realtime.toString())}`)}`);
   }
   viteConfig.logger.info("");
 }
@@ -41359,7 +41363,7 @@ async function setupCliDevServer(options) {
 var import_picocolors5 = __toESM(require_picocolors(), 1);
 import { DEFAULT_PORTS as DEFAULT_PORTS2 } from "playcademy/constants";
 
-// ../sandbox/dist/server/index.js
+// ../sandbox/dist/server.js
 import { createRequire as createRequire2 } from "node:module";
 import * as s3 from "fs";
 import * as o3 from "path";
@@ -153167,30 +153171,30 @@ var package_default2 = {
   type: "module",
   exports: {
     ".": {
-      import: "./dist/server/index.js",
-      types: "./dist/server/index.d.ts"
+      import: "./dist/server.js",
+      types: "./dist/server.d.ts"
     },
     "./cli": {
-      import: "./dist/cli/index.js",
-      types: "./dist/cli/index.d.ts"
+      import: "./dist/cli.js",
+      types: "./dist/cli.d.ts"
     },
     "./config": {
-      import: "./dist/config/index.js",
-      types: "./dist/config/index.d.ts"
+      import: "./dist/config.js",
+      types: "./dist/config.d.ts"
     }
   },
   bin: {
-    "playcademy-sandbox": "./dist/cli/index.js"
+    "playcademy-sandbox": "./dist/cli.js"
   },
   files: [
     "dist"
   ],
   scripts: {
     build: "bun run build.ts",
-    dev: "bun --watch src/cli.ts",
+    dev: "bun --watch src/cli",
+    docs: "typedoc",
     pub: "bun publish.ts",
-    start: "bun src/cli.ts",
-    docs: "typedoc"
+    start: "bun src/cli.ts"
   },
   dependencies: {
     "@electric-sql/pglite": "^0.3.2",
@@ -194511,21 +194515,14 @@ async function getTodayXpFromEvents(db, userId, date4, timezone2) {
   };
 }
 init_src();
-async function checkGameAccess(gameId, user) {
+async function verifyGameAccessById(gameId, user) {
   if (user.role !== "admin") {
     const existingGame = await getDatabase().query.games.findFirst({
       where: and(eq(games.id, gameId), eq(games.developerId, user.id)),
       columns: { id: true }
     });
     if (!existingGame) {
-      const gameExists = await getDatabase().query.games.findFirst({
-        where: eq(games.id, gameId),
-        columns: { id: true }
-      });
-      if (!gameExists) {
-        throw ApiError.notFound("Game not found");
-      }
-      throw ApiError.forbidden("You do not own this game");
+      throw ApiError.notFound("Game not found");
     }
   } else {
     const gameExists = await getDatabase().query.games.findFirst({
@@ -195006,6 +195003,10 @@ async function applyForDeveloperStatus(ctx) {
   }
   try {
     await db.update(users).set({ developerStatus: "pending" }).where(eq(users.id, user.id));
+    log2.info("[API] Developer status application submitted", {
+      userId: user.id,
+      newStatus: "pending"
+    });
   } catch (error2) {
     log2.error(`Error updating developer status for user ${user.id}:`, {
       error: error2
@@ -200375,6 +200376,7 @@ async function initiateUpload(ctx) {
     throw ApiError.badRequest("Invalid JSON body");
   }
   const { fileName, gameId } = inputData;
+  await verifyGameAccessById(gameId, user);
   if (!uploadDeps) {
     throw ApiError.internal("Upload dependencies not configured");
   }
@@ -200511,7 +200513,7 @@ async function deleteGame(ctx) {
   if (!gameId) {
     throw ApiError.badRequest("Missing game ID");
   }
-  await checkGameAccess(gameId, user);
+  await verifyGameAccessById(gameId, user);
   try {
     const db = getDatabase();
     const gameToDelete = await db.query.games.findFirst({
@@ -200526,6 +200528,11 @@ async function deleteGame(ctx) {
     if (result.length === 0) {
       throw ApiError.notFound("Game not found for deletion");
     }
+    log2.info("[API] Game deleted", {
+      gameId: result[0].id,
+      slug: gameToDelete?.slug,
+      hadActiveDeployment: !!activeDeployment
+    });
     if (activeDeployment?.provider === "cloudflare") {
       try {
         const cloudflare2 = getCloudflareProvider();
@@ -200541,7 +200548,7 @@ async function deleteGame(ctx) {
           });
         }
       } catch (cleanupError) {
-        log2.info("Non-fatal: Failed to cleanup Cloudflare Worker for deleted game", {
+        log2.warn("Non-fatal: Failed to cleanup Cloudflare Worker for deleted game", {
           gameId,
           deploymentId: activeDeployment.deploymentId,
           cleanupError
@@ -200700,11 +200707,17 @@ async function upsertGameBySlug(ctx) {
           gameId: gameResponse.id
         }).where(eq(mapElements.id, metadataInput.mapElementId));
       } catch (mapError) {
-        log2.info(`Failed to update map element ${metadataInput.mapElementId}:`, {
+        log2.warn(`Failed to update map element ${metadataInput.mapElementId}:`, {
           mapError
         });
       }
     }
+    log2.info("[API] Game upserted", {
+      gameId: gameResponse.id,
+      slug: gameResponse.slug,
+      operation: isUpdate ? "update" : "create",
+      displayName: gameResponse.displayName
+    });
     return gameResponse;
   } catch (error2) {
     if (error2 instanceof ApiError) {
@@ -200925,6 +200938,12 @@ async function createItem(ctx) {
     if (!newItem) {
       throw ApiError.internal("Failed to create item in database");
     }
+    log2.info("[API] Item created", {
+      itemId: newItem.id,
+      displayName: newItem.displayName,
+      type: newItem.type,
+      gameId: newItem.gameId
+    });
     return newItem;
   } catch (error2) {
     if (error2 instanceof Error) {
@@ -200977,6 +200996,11 @@ async function updateItem(ctx) {
     if (!updatedItem) {
       throw ApiError.notFound("Item not found for update");
     }
+    log2.info("[API] Item updated", {
+      itemId: updatedItem.id,
+      displayName: updatedItem.displayName,
+      updatedFields: Object.keys(inputData)
+    });
     return updatedItem;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -201012,6 +201036,9 @@ async function deleteItem(ctx) {
     if (result.length === 0) {
       throw ApiError.notFound("Item not found for deletion");
     }
+    log2.info("[API] Item deleted", {
+      itemId: result[0].id
+    });
   } catch (error2) {
     if (error2 instanceof ApiError) {
       throw error2;
@@ -201136,6 +201163,12 @@ async function createGameItem(ctx) {
     if (!newItem) {
       throw ApiError.internal("Failed to create item in database");
     }
+    log2.info("[API] Game item created", {
+      itemId: newItem.id,
+      gameId: newItem.gameId,
+      displayName: newItem.displayName,
+      type: newItem.type
+    });
     return newItem;
   } catch (error2) {
     if (error2 instanceof Error) {
@@ -201199,6 +201232,12 @@ async function updateGameItem(ctx) {
     if (!updatedItem) {
       throw ApiError.notFound("Item not found for update");
     }
+    log2.info("[API] Game item updated", {
+      itemId: updatedItem.id,
+      gameId: updatedItem.gameId,
+      displayName: updatedItem.displayName,
+      updatedFields: Object.keys(inputData)
+    });
     return updatedItem;
   } catch (error2) {
     if (error2 instanceof ApiError) {
@@ -201241,6 +201280,10 @@ async function deleteGameItem(ctx) {
     if (result.length === 0) {
       throw ApiError.notFound("Item not found for this game");
     }
+    log2.info("[API] Game item deleted", {
+      itemId: result[0].id,
+      gameId
+    });
   } catch (error2) {
     if (error2 instanceof ApiError) {
       throw error2;
@@ -201304,6 +201347,13 @@ async function createGameItemShopListing(ctx) {
     if (!newListing) {
       throw ApiError.internal("Failed to create shop listing in database");
     }
+    log2.info("[API] Game item shop listing created", {
+      listingId: newListing.id,
+      gameId,
+      itemId,
+      currencyId: newListing.currencyId,
+      price: newListing.price
+    });
     return newListing;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -201412,6 +201462,12 @@ async function updateGameItemShopListing(ctx) {
     if (!updatedListing) {
       throw ApiError.notFound("Shop listing not found for this item");
     }
+    log2.info("[API] Game item shop listing updated", {
+      listingId: updatedListing.id,
+      gameId,
+      itemId,
+      updatedFields: Object.keys(inputData)
+    });
     return updatedListing;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -201458,7 +201514,11 @@ async function deleteGameItemShopListing(ctx) {
     if (result.length === 0) {
       throw ApiError.notFound("Shop listing not found for this item");
     }
-    log2.info(`Shop listing deleted for item ${itemId} by user ${user.id}`);
+    log2.info("[API] Game item shop listing deleted", {
+      listingId: result[0].id,
+      gameId,
+      itemId
+    });
   } catch (error2) {
     if (error2 instanceof ApiError) {
       throw error2;
@@ -202300,6 +202360,12 @@ async function addInventoryItem(ctx) {
       }
       return updatedQuantity;
     });
+    log2.info("[API] Inventory item added", {
+      userId: user.id,
+      itemId,
+      quantityAdded: qty,
+      newTotal
+    });
     return { newTotal };
   } catch (error2) {
     if (error2 instanceof ApiError) {
@@ -202350,6 +202416,12 @@ async function removeInventoryItem(ctx) {
       }
       return updatedItemRecord.quantity;
     });
+    log2.info("[API] Inventory item removed", {
+      userId: user.id,
+      itemId,
+      quantityRemoved: qty,
+      newTotal
+    });
     return { newTotal };
   } catch (error2) {
     if (error2 instanceof ApiError) {
@@ -202703,6 +202775,12 @@ async function createCurrency(ctx) {
     if (!newCurrency) {
       throw ApiError.internal("Failed to create currency in database");
     }
+    log2.info("[API] Currency created", {
+      currencyId: newCurrency.id,
+      itemId: newCurrency.itemId,
+      symbol: newCurrency.symbol,
+      isPrimary: newCurrency.isPrimary
+    });
     return newCurrency;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -202756,6 +202834,11 @@ async function updateCurrency(ctx) {
     if (!updatedCurrency) {
       throw ApiError.notFound("Currency not found for update");
     }
+    log2.info("[API] Currency updated", {
+      currencyId: updatedCurrency.id,
+      itemId: updatedCurrency.itemId,
+      updatedFields: Object.keys(inputData)
+    });
     return updatedCurrency;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -202794,6 +202877,9 @@ async function deleteCurrency(ctx) {
     if (result.length === 0) {
       throw ApiError.notFound("Currency not found for deletion");
     }
+    log2.info("[API] Currency deleted", {
+      currencyId: result[0].id
+    });
   } catch (error2) {
     if (error2 instanceof ApiError)
       throw error2;
@@ -203287,6 +203373,12 @@ async function createShopListing(ctx) {
     if (!newListing) {
       throw ApiError.internal("Failed to create shop listing in database");
     }
+    log2.info("[API] Shop listing created", {
+      listingId: newListing.id,
+      itemId: newListing.itemId,
+      currencyId: newListing.currencyId,
+      price: newListing.price
+    });
     return newListing;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -203404,6 +203496,11 @@ async function updateShopListing(ctx) {
     if (!updatedListing) {
       throw ApiError.notFound("Shop listing not found for update");
     }
+    log2.info("[API] Shop listing updated", {
+      listingId: updatedListing.id,
+      itemId: updatedListing.itemId,
+      updatedFields: Object.keys(inputData)
+    });
     return updatedListing;
   } catch (error2) {
     if (error2 instanceof ApiError)
@@ -203447,6 +203544,9 @@ async function deleteShopListing(ctx) {
     if (result.length === 0) {
       throw ApiError.notFound("Shop listing not found for deletion");
     }
+    log2.info("[API] Shop listing deleted", {
+      listingId: result[0].id
+    });
   } catch (error2) {
     if (error2 instanceof ApiError)
       throw error2;
@@ -203715,6 +203815,10 @@ async function createPlayerCharacter(ctx) {
       await tx.update(users).set({ characterCreated: true }).where(eq(users.id, user.id));
       return characterRow;
     });
+    log2.info("[API] Player character created", {
+      userId: user.id,
+      characterId: result.id
+    });
     return result;
   } catch (error2) {
     log2.error("Error creating player character", { error: error2 });
@@ -203749,6 +203853,11 @@ async function updatePlayerCharacter(ctx) {
     const [row] = await db.update(playerCharacters).set({ ...payload, updatedAt: new Date }).where(eq(playerCharacters.userId, user.id)).returning();
     if (!row)
       throw ApiError.notFound("Player character not found");
+    log2.info("[API] Player character updated", {
+      userId: user.id,
+      characterId: row.id,
+      updatedFields: Object.keys(payload)
+    });
     return row;
   } catch (error2) {
     log2.error("Error updating player character", { error: error2 });
@@ -205397,17 +205506,30 @@ function detectTimebackOptions() {
 }
 
 // src/lib/sandbox/server.ts
-function printSandboxInfo(viteConfig, apiPort, realtimePort, projectInfo) {
+function printSandboxInfo(viteConfig, apiPort, realtimePort, projectInfo, realtimeEnabled) {
   viteConfig.logger.info("");
   viteConfig.logger.info(`  ${import_picocolors5.default.green(import_picocolors5.default.bold("PLAYCADEMY"))} ${import_picocolors5.default.green(`v${version3}`)}`);
   viteConfig.logger.info("");
   viteConfig.logger.info(`  ${import_picocolors5.default.green("➜")}  ${import_picocolors5.default.bold("Game:")}     ${import_picocolors5.default.cyan(projectInfo.slug)}`);
   viteConfig.logger.info(`  ${import_picocolors5.default.green("➜")}  ${import_picocolors5.default.bold("Sandbox:")}  ${import_picocolors5.default.cyan(`http://localhost:${import_picocolors5.default.bold(apiPort.toString())}/api`)}`);
-  viteConfig.logger.info(`  ${import_picocolors5.default.green("➜")}  ${import_picocolors5.default.bold("Realtime:")} ${import_picocolors5.default.cyan(`ws://localhost:${import_picocolors5.default.bold(realtimePort.toString())}`)}`);
+  if (realtimeEnabled) {
+    viteConfig.logger.info(`  ${import_picocolors5.default.green("➜")}  ${import_picocolors5.default.bold("Realtime:")} ${import_picocolors5.default.cyan(`ws://localhost:${import_picocolors5.default.bold(realtimePort.toString())}`)}`);
+  }
   viteConfig.logger.info("");
 }
 async function startSandbox(viteConfig, autoStart = true, options = {}) {
-  const { verbose = false, customUrl, quiet = false, recreateDb = false, logLevel = "info" } = options;
+  const {
+    verbose = false,
+    customUrl,
+    quiet = false,
+    recreateDb = false,
+    seed = true,
+    memoryOnly = false,
+    databasePath,
+    realtimeEnabled = false,
+    realtimePort,
+    logLevel = "info"
+  } = options;
   if (!autoStart || viteConfig.command !== "serve") {
     const baseUrl = customUrl ?? `http://localhost:${DEFAULT_PORTS2.SANDBOX}`;
     const deriveRealtimeUrl = (url) => {
@@ -205424,6 +205546,7 @@ async function startSandbox(viteConfig, autoStart = true, options = {}) {
       baseUrl,
       realtimeUrl: deriveRealtimeUrl(baseUrl),
       port: DEFAULT_PORTS2.SANDBOX,
+      realtimePort: undefined,
       project: null,
       cleanup: () => {}
     };
@@ -205431,17 +205554,19 @@ async function startSandbox(viteConfig, autoStart = true, options = {}) {
   try {
     const sandboxPort = await findAvailablePort(DEFAULT_PORTS2.SANDBOX);
     const baseUrl = `http://localhost:${sandboxPort}`;
-    const realtimePort = await findAvailablePort(sandboxPort + 1);
-    const realtimeUrl = `ws://localhost:${realtimePort}`;
     const projectInfo = await extractProjectInfo(viteConfig);
     const timebackOptions = detectTimebackOptions();
+    const finalRealtimePort = realtimePort ?? await findAvailablePort(sandboxPort + 1);
+    const realtimeUrl = `ws://localhost:${finalRealtimePort}`;
     const server = await startServer2(sandboxPort, projectInfo, {
       verbose,
       quiet,
-      seed: true,
+      seed,
+      memoryOnly,
+      databasePath,
       recreateDb,
       logLevel,
-      realtime: { enabled: false, port: realtimePort },
+      realtime: { enabled: realtimeEnabled, port: finalRealtimePort },
       timeback: timebackOptions,
       logger: createLoggerAdapter("sandbox")
     });
@@ -205454,13 +205579,14 @@ async function startSandbox(viteConfig, autoStart = true, options = {}) {
     });
     if (!quiet) {
       setTimeout(() => {
-        printSandboxInfo(viteConfig, sandboxPort, realtimePort, projectInfo);
+        printSandboxInfo(viteConfig, sandboxPort, finalRealtimePort, projectInfo, realtimeEnabled);
       }, 100);
     }
     return {
       baseUrl,
       realtimeUrl,
       port: sandboxPort,
+      realtimePort: realtimeEnabled ? finalRealtimePort : undefined,
       project: projectInfo,
       cleanup: () => {
         cleanupServerInfo("sandbox", viteConfig.root, process.pid);
@@ -205475,6 +205601,7 @@ async function startSandbox(viteConfig, autoStart = true, options = {}) {
       baseUrl: `http://localhost:${DEFAULT_PORTS2.SANDBOX}`,
       realtimeUrl: "ws://localhost:4322",
       port: DEFAULT_PORTS2.SANDBOX,
+      realtimePort: undefined,
       project: null,
       cleanup: () => {}
     };
@@ -205956,7 +206083,12 @@ async function configurePlatformMode(server, viteConfig, options) {
     logLevel: options.logLevel,
     customUrl: options.sandboxUrl,
     quiet: true,
-    recreateDb: options.recreateDb
+    recreateDb: options.recreateDb,
+    seed: options.seed,
+    memoryOnly: options.memoryOnly,
+    databasePath: options.databasePath,
+    realtimeEnabled: options.realtimeEnabled,
+    realtimePort: options.realtimePort
   });
   serverState.sandbox = sandbox;
   const backend = await setupCliDevServer({
@@ -205972,7 +206104,13 @@ async function configurePlatformMode(server, viteConfig, options) {
   server.httpServer?.once("listening", () => {
     setTimeout(async () => {
       const projectInfo = await extractProjectInfo(viteConfig);
-      printBanner(viteConfig, { sandbox: sandbox.port, backend: backend?.port }, projectInfo, package_default.version);
+      const vitePort = server.config.server.port;
+      printBanner(viteConfig, {
+        sandbox: sandbox.port,
+        backend: backend?.port,
+        realtime: sandbox.realtimePort,
+        vite: vitePort
+      }, projectInfo, package_default.version);
     }, 100);
   });
 }
@@ -206043,6 +206181,11 @@ async function configureServerHook(server, context) {
     logLevel: context.options.logLevel,
     sandboxUrl: context.options.sandboxUrl,
     recreateDb: context.options.recreateDb,
+    seed: context.options.seed,
+    memoryOnly: context.options.memoryOnly,
+    databasePath: context.options.databasePath,
+    realtimeEnabled: context.options.realtimeEnabled,
+    realtimePort: context.options.realtimePort,
     showBadge: context.options.showBadge,
     preferredBackendPort: preferredPort
   };
@@ -206100,6 +206243,7 @@ function resolveOptions(options) {
   const exportOptions = options.export ?? {};
   const sandboxOptions = options.sandbox ?? {};
   const shellOptions = options.shell ?? {};
+  const realtimeOptions = sandboxOptions.realtime ?? {};
   return {
     mode: options.mode ?? "platform",
     autoZip: exportOptions.autoZip ?? true,
@@ -206108,6 +206252,11 @@ function resolveOptions(options) {
     verbose: sandboxOptions.verbose ?? false,
     logLevel: sandboxOptions.logLevel ?? "info",
     recreateDb: sandboxOptions.recreateDb ?? false,
+    seed: sandboxOptions.seed ?? true,
+    memoryOnly: sandboxOptions.memoryOnly ?? false,
+    databasePath: sandboxOptions.databasePath,
+    realtimeEnabled: realtimeOptions.enabled ?? false,
+    realtimePort: realtimeOptions.port,
     showBadge: shellOptions.showBadge ?? true
   };
 }

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

@@ -20,4 +20,6 @@ export declare const log: {
 export declare function printBanner(viteConfig: ResolvedConfig, servers: {
     sandbox: number;
     backend?: number;
+    realtime?: number;
+    vite?: number;
 }, projectInfo: ProjectInfo, pluginVersion: string): void;

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

@@ -5,5 +5,10 @@ export declare function startSandbox(viteConfig: ResolvedConfig, autoStart?: boo
     customUrl?: string;
     quiet?: boolean;
     recreateDb?: boolean;
+    seed?: boolean;
+    memoryOnly?: boolean;
+    databasePath?: string;
+    realtimeEnabled?: boolean;
+    realtimePort?: number;
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
 }): Promise<SandboxManager>;

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

@@ -9,6 +9,11 @@ export interface PlatformModeOptions {
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     sandboxUrl: string;
     recreateDb: boolean;
+    seed: boolean;
+    memoryOnly: boolean;
+    databasePath?: string;
+    realtimeEnabled: boolean;
+    realtimePort?: number;
     showBadge: boolean;
     preferredBackendPort: number;
 }

package/dist/types/internal.d.ts

@@ -14,6 +14,11 @@ export interface ResolvedPluginOptions {
     verbose: boolean;
     logLevel: 'debug' | 'info' | 'warn' | 'error';
     recreateDb: boolean;
+    seed: boolean;
+    memoryOnly: boolean;
+    databasePath?: string;
+    realtimeEnabled: boolean;
+    realtimePort?: number;
     showBadge: boolean;
 }
 /**
@@ -50,6 +55,7 @@ export interface SandboxManager {
     baseUrl: string;
     realtimeUrl: string;
     port: number;
+    realtimePort?: number;
     project: ProjectInfo | null;
     cleanup: () => void;
 }

package/dist/types/options.d.ts

@@ -3,58 +3,319 @@
  */
 /**
  * Plugin operation mode
- * - 'platform': Full Playcademy platform with sandbox + backend + shell wrapper (default)
- * - 'standalone': Backend only, no sandbox or shell (for testing integrations)
+ *
+ * Controls how the Vite plugin operates during development:
+ * - `'platform'`: Full Playcademy platform experience with sandbox server, backend bundling, and shell wrapper (default)
+ * - `'standalone'`: Backend only, no sandbox or shell
+ *
+ * @default 'platform'
  */
 export type PlaycademyMode = 'platform' | 'standalone';
 /**
- * Configuration options for exporting Playcademy games
+ * Configuration options for exporting/building Playcademy games
+ *
+ * Controls how your game is packaged for deployment.
  */
 export interface PlaycademyExportOptions {
     /**
-     * Automatically create a deployment zip archive at .playcademy/{project-name}.zip
+     * Automatically create a deployment zip archive after build.
+     *
+     * The zip file is created at `.playcademy/{project-name}.zip` and contains
+     * all files needed for deployment (frontend assets + backend bundle).
+     *
      * @default true
+     * @example
+     * ```ts
+     * export: {
+     *   autoZip: false // Disable auto-zipping
+     * }
+     * ```
      */
     autoZip?: boolean;
 }
 /**
  * Configuration options for the Playcademy sandbox server
+ *
+ * The sandbox server provides a local development environment that simulates
+ * the Playcademy platform, including API endpoints, authentication, and database.
  */
 export interface PlaycademySandboxOptions {
+    /**
+     * Automatically start the sandbox server when Vite starts.
+     *
+     * Set to `false` if you want to start the sandbox server manually.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * sandbox: {
+     *   autoStart: false // Start sandbox manually
+     * }
+     * ```
+     */
     autoStart?: boolean;
+    /**
+     * Custom URL for the sandbox server.
+     *
+     * Useful if you need to run the sandbox on a specific host or port.
+     * By default, the sandbox uses `http://localhost:{port}` where port
+     * is auto-assigned.
+     *
+     * @example
+     * ```ts
+     * sandbox: {
+     *   url: 'http://localhost:8788'
+     * }
+     * ```
+     */
     url?: string;
+    /**
+     * Enable verbose logging for the sandbox server.
+     *
+     * Shows detailed information about requests, database operations, and more.
+     * Equivalent to setting `logLevel: 'debug'`.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * sandbox: {
+     *   verbose: true
+     * }
+     * ```
+     */
     verbose?: boolean;
     /**
-     * Log level for the sandbox server
+     * Log level for the sandbox server.
+     *
+     * Controls the verbosity of sandbox server logs:
+     * - `'debug'`: Very detailed logs (all operations)
+     * - `'info'`: Standard operational logs
+     * - `'warn'`: Warnings only
+     * - `'error'`: Errors only
+     *
      * @default 'info'
+     * @example
+     * ```ts
+     * sandbox: {
+     *   logLevel: 'debug' // Show all debug info
+     * }
+     * ```
      */
     logLevel?: 'debug' | 'info' | 'warn' | 'error';
     /**
-     * Recreate the sandbox database on each start
+     * Recreate the sandbox database on each server start.
+     *
+     * When `true`, the database is dropped and recreated with seed data
+     * every time the dev server starts. Useful for ensuring a clean state
+     * during development.
+     *
+     * **Warning**: All existing data will be lost on each restart.
+     *
      * @default false
+     * @example
+     * ```ts
+     * sandbox: {
+     *   recreateDb: true // Fresh database on every restart
+     * }
+     * ```
      */
     recreateDb?: boolean;
+    /**
+     * Seed the database with demo data on startup.
+     *
+     * Creates demo users, games, achievements, and other platform data
+     * for testing. Disable if you want to start with an empty database.
+     *
+     * @default true
+     * @example
+     * ```ts
+     * sandbox: {
+     *   seed: false // Start with empty database
+     * }
+     * ```
+     */
+    seed?: boolean;
+    /**
+     * Use an in-memory database instead of a file.
+     *
+     * The database only exists in RAM and is lost when the server stops.
+     * Faster but non-persistent. Useful for testing and CI environments.
+     *
+     * @default false
+     * @example
+     * ```ts
+     * sandbox: {
+     *   memoryOnly: true // Database in RAM only
+     * }
+     * ```
+     */
+    memoryOnly?: boolean;
+    /**
+     * Custom path for the database file.
+     *
+     * Specifies where the SQLite database file should be stored.
+     * If not provided, defaults to a path based on node_modules location.
+     *
+     * Special value `':memory:'` creates an in-memory database
+     * (equivalent to `memoryOnly: true`).
+     *
+     * @example
+     * ```ts
+     * sandbox: {
+     *   databasePath: './my-game-sandbox.db'
+     * }
+     * ```
+     *
+     * @example
+     * ```ts
+     * sandbox: {
+     *   databasePath: ':memory:' // In-memory database
+     * }
+     * ```
+     */
+    databasePath?: string;
+    /**
+     * Real-time/WebSocket server configuration.
+     *
+     * The real-time server provides WebSocket support for live updates,
+     * multiplayer features, and other real-time functionality.
+     *
+     * @default { enabled: false }
+     * @example
+     * ```ts
+     * sandbox: {
+     *   realtime: {
+     *     enabled: true,
+     *     port: 4322 // Custom WebSocket port
+     *   }
+     * }
+     * ```
+     */
+    realtime?: {
+        /**
+         * Enable the real-time/WebSocket server.
+         *
+         * @default false
+         */
+        enabled?: boolean;
+        /**
+         * Port for the WebSocket server.
+         *
+         * By default, uses the HTTP port + 1 (e.g., if HTTP is 4321,
+         * WebSocket will be 4322).
+         */
+        port?: number;
+    };
 }
 /**
  * Configuration options for the development shell wrapper
+ *
+ * The shell provides the platform UI during development, including the
+ * Playcademy badge, game selection, and other platform features.
  */
 export interface PlaycademyShellOptions {
     /**
-     * Show the Playcademy badge in the corner during development
+     * Show the Playcademy badge in the corner during development.
+     *
      * @default true
+     * @example
+     * ```ts
+     * shell: {
+     *   showBadge: false // Hide the badge
+     * }
+     * ```
      */
     showBadge?: boolean;
 }
 /**
- * Main plugin configuration options
+ * Main configuration options for the Playcademy Vite plugin
+ *
+ * Configure how your game integrates with the Playcademy platform during
+ * development and build.
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import { playcademy } from '@playcademy/vite-plugin'
+ *
+ * export default defineConfig({
+ *   plugins: [
+ *     playcademy({
+ *       mode: 'platform',
+ *       sandbox: {
+ *         logLevel: 'debug',
+ *         recreateDb: true
+ *       },
+ *       shell: {
+ *         showBadge: true
+ *       }
+ *     })
+ *   ]
+ * })
+ * ```
  */
 export interface PlaycademyPluginOptions {
     /**
-     * Plugin operation mode
+     * Plugin operation mode.
+     *
+     * - `'platform'`: Full development experience with sandbox server and shell (recommended)
+     * - `'standalone'`: Backend bundling only, no platform features
+     *
+     * Most games should use `'platform'` mode.
+     *
      * @default 'platform'
+     * @example
+     * ```ts
+     * {
+     *   mode: 'standalone' // For testing backend in isolation
+     * }
+     * ```
      */
     mode?: PlaycademyMode;
+    /**
+     * Export/build configuration options.
+     *
+     * Controls how your game is packaged for deployment.
+     *
+     * @example
+     * ```ts
+     * {
+     *   export: {
+     *     autoZip: true // Create deployment zip automatically
+     *   }
+     * }
+     * ```
+     */
     export?: PlaycademyExportOptions;
+    /**
+     * Sandbox server configuration options.
+     *
+     * The sandbox provides a local Playcademy platform environment for development.
+     *
+     * @example
+     * ```ts
+     * {
+     *   sandbox: {
+     *     logLevel: 'debug',
+     *     recreateDb: true
+     *   }
+     * }
+     * ```
+     */
     sandbox?: PlaycademySandboxOptions;
+    /**
+     * Development shell configuration options.
+     *
+     * The shell wraps your game with platform UI during development.
+     *
+     * @example
+     * ```ts
+     * {
+     *   shell: {
+     *     showBadge: false
+     *   }
+     * }
+     * ```
+     */
     shell?: PlaycademyShellOptions;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@playcademy/vite-plugin",
-    "version": "0.1.26-alpha.6",
+    "version": "0.1.26-alpha.7",
     "type": "module",
     "exports": {
         ".": {