@playcademy/vite-plugin 0.1.38 → 0.2.0

package/README.md

@@ -132,14 +132,25 @@ export default defineConfig({
 
 ## Plugin Options
 
+### Top-Level Options
+
+| Option       | Type                         | Default      | Description                                  |
+| ------------ | ---------------------------- | ------------ | -------------------------------------------- |
+| `configPath` | `string`                     | `undefined`  | Path to playcademy.config.js (auto-detected) |
+| `mode`       | `'platform' \| 'standalone'` | `'platform'` | Plugin operation mode                        |
+
+**Mode Options:**
+
+- `'platform'`: Full Playcademy experience with sandbox server, backend bundling, and shell wrapper (recommended)
+- `'standalone'`: Backend bundling only, no platform features
+
 ### Export Options (`export`)
 
-Configuration for manifest generation and build output:
+Configuration for build output:
 
-| Option     | Type      | Default | Description                                    |
-| ---------- | --------- | ------- | ---------------------------------------------- |
-| `platform` | `string`  | `'web'` | Platform identifier (e.g., 'web', 'godot@4.3') |
-| `autoZip`  | `boolean` | `true`  | Create deployment zip archive                  |
+| Option    | Type      | Default | Description                   |
+| --------- | --------- | ------- | ----------------------------- |
+| `autoZip` | `boolean` | `true`  | Create deployment zip archive |
 
 ### Sandbox Options (`sandbox`)
 
@@ -164,15 +175,32 @@ Configuration for the development sandbox server:
 | `enabled` | `boolean` | `false`      | Enable WebSocket server          |
 | `port`    | `number`  | API port + 1 | Custom port for WebSocket server |
 
+### Display Options (`display`)
+
+Configuration for visual elements during development:
+
+| Option      | Type      | Default | Description                             |
+| ----------- | --------- | ------- | --------------------------------------- |
+| `hideBadge` | `boolean` | `false` | Hide the Playcademy badge in the corner |
+
 ### TimeBack Options (`timeback`)
 
-Configuration for TimeBack integration testing during local development:
+Configuration for TimeBack integration testing during local development. Set to `false` to explicitly disable TimeBack even if configured in playcademy.config.
+
+| Option         | Type                                                                  | Default                 | Description                                       |
+| -------------- | --------------------------------------------------------------------- | ----------------------- | ------------------------------------------------- |
+| `id`           | `string`                                                              | auto-generated mock ID  | TimeBack student ID                               |
+| `role`         | `'student' \| 'parent' \| 'teacher' \| 'administrator' \| 'guardian'` | `'student'`             | User role for testing different permission levels |
+| `organization` | `'mock' \| object`                                                    | `'mock'`                | Organization (school/district) configuration      |
+| `courses`      | `Record<string, 'mock' \| string \| null>`                            | all courses from config | Course enrollment overrides                       |
 
-| Option       | Type                                                    | Default     | Description                                                    |
-| ------------ | ------------------------------------------------------- | ----------- | -------------------------------------------------------------- |
-| `timebackId` | `'mock' \| string`                                      | `'mock'`    | TimeBack student ID (defaults to mock when courses configured) |
-| `courses`    | `Record<string, 'mock' \| string>`                      | `undefined` | Course enrollments mapping (`'Subject:Grade'`)                 |
-| `role`       | `'student' \| 'parent' \| 'teacher' \| 'administrator'` | `'student'` | User role for testing different permission levels              |
+#### Organization Object Properties
+
+| Property | Type                                                                         | Default                | Description            |
+| -------- | ---------------------------------------------------------------------------- | ---------------------- | ---------------------- |
+| `id`     | `string`                                                                     | `'PLAYCADEMY'`         | Organization sourcedId |
+| `name`   | `string`                                                                     | `'Playcademy Studios'` | Organization name      |
+| `type`   | `'school' \| 'district' \| 'department' \| 'local' \| 'state' \| 'national'` | `'department'`         | Organization type      |
 
 #### TimeBack Configuration Example
 
@@ -181,13 +209,43 @@ export default defineConfig({
     plugins: [
         playcademy({
             timeback: {
-                // timebackId defaults to 'mock' when courses are configured
+                // All courses from playcademy.config.js enrolled by default with mock IDs
+                role: 'student', // Test as student (default)
+            },
+        }),
+    ],
+})
+
+// Override specific courses
+export default defineConfig({
+    plugins: [
+        playcademy({
+            timeback: {
                 courses: {
                     'FastMath:3': 'mock', // Mock enrollment for grade 3
-                    'FastMath:4': 'mock', // Mock enrollment for grade 4
+                    'FastMath:4': null, // Exclude from enrollment (test partial)
                     'Science:5': 'real-course-id-123', // Real TimeBack course
                 },
-                role: 'student', // Test as student (default)
+            },
+        }),
+    ],
+})
+
+// Full real TimeBack integration
+export default defineConfig({
+    plugins: [
+        playcademy({
+            timeback: {
+                id: 'real-student-sourced-id',
+                organization: {
+                    id: 'real-org-id',
+                    name: 'Springfield Elementary',
+                    type: 'school',
+                },
+                courses: {
+                    'FastMath:3': 'real-course-id-g3',
+                    'FastMath:4': 'real-course-id-g4',
+                },
             },
         }),
     ],
@@ -202,9 +260,10 @@ During development, the plugin provides keyboard shortcuts in the terminal:
 | --- | -------------------------------------------------------- |
 | `m` | Toggle between platform and standalone modes             |
 | `d` | Recreate sandbox database (resets to fresh seeded state) |
+| `p` | Cycle platform user role (player → developer → admin)    |
 | `t` | Cycle TimeBack role (student → parent → teacher → admin) |
 
-The `t` hotkey automatically reloads your browser when the role changes, making it easy to test different user permission levels without modifying configuration.
+> **Note:** Some configuration changes require recreating the sandbox database to take effect. Press `d` after changing options like `timeback.id`, `timeback.organization`, or `timeback.courses` in your vite.config.ts.
 
 ## Build Output
 
@@ -448,7 +507,7 @@ export default defineConfig({
     plugins: [
         playcademy({
             timeback: {
-                timebackId: 'mock',
+                // id defaults to auto-generated mock ID
                 courses: {
                     'FastMath:3': 'mock',
                     'FastMath:4': 'mock',
@@ -460,7 +519,7 @@ export default defineConfig({
 })
 ```
 
-During development, press `t` in the terminal to cycle through roles (student → parent → teacher → administrator) and test different permission levels. The browser reloads automatically.
+During development, press `t` in the terminal to cycle through roles (student → parent → teacher → administrator → guardian) and test different permission levels. The browser reloads automatically.
 
 ## Troubleshooting