create-vizcraft-playground 0.1.0 → 0.2.0

package/README.md

@@ -0,0 +1,103 @@
+# create-vizcraft-playground
+
+Scaffold a new [VizCraft](https://www.npmjs.com/package/vizcraft) interactive visualization playground in seconds.
+
+## Usage
+
+```bash
+npx create-vizcraft-playground my-playground
+```
+
+Or without a project name — the CLI will prompt you:
+
+```bash
+npx create-vizcraft-playground
+```
+
+The scaffolder will ask for:
+
+- **Project directory name**
+- **Playground title** shown on the landing page
+- **Subtitle** — one-liner description
+- **Accent colour** — hex value for the primary theme colour
+
+Then just install and run:
+
+```bash
+cd my-playground
+npm install
+npm run dev
+```
+
+Open [http://localhost:5173](http://localhost:5173).
+
+## Re-running the setup wizard
+
+You can re-configure the title, subtitle, and accent colour at any time:
+
+```bash
+npm run init
+```
+
+This regenerates `src/playground.config.ts`.
+
+## Adding a plugin
+
+Generate a new visualization plugin:
+
+```bash
+npm run generate <plugin-name> --category "Category Name"
+```
+
+Example:
+
+```bash
+npm run generate supply-demand --category "Microeconomics"
+```
+
+This creates `src/plugins/<plugin-name>/` and wires it into the registry automatically. See [template/README.md](template/README.md) for full plugin docs.
+
+### Sandbox plugins
+
+Use the `--sandbox` flag to generate an interactive, architecture-builder-style plugin where users can dynamically add and remove components and the scene, steps, and animations all adapt reactively:
+
+```bash
+npm run generate cloud-lab --category "Systems" --sandbox
+```
+
+A sandbox plugin differs from a standard one in a few key ways:
+
+- **Controls panel** — a `controls.tsx` component rendered in the Shell sidebar lets users toggle infrastructure components on and off.
+- **Dynamic steps** — steps are derived from the current component state, so adding a cache or load balancer automatically adds relevant walkthrough steps.
+- **Declarative flow engine** — a `flow-engine.ts` file describes all signal animations as data. No imperative per-step animation code; adding a step means adding a config entry.
+- **8 files** instead of the standard 6, including `flow-engine.ts` and `controls.tsx`.
+
+Use sandbox plugins when you want an interactive scene where composition affects both the narrative and the visualization.
+
+### Timeline plugins
+
+Use the `--timeline` flag to generate a progressive-reveal timeline plugin with animated nodes, a colored progress bar, auto-pan, and declarative steps generated from a data array:
+
+```bash
+npm run generate historical-events --category "History" --timeline
+```
+
+A timeline plugin differs from the standard one in a few key ways:
+
+- **Declarative flow engine** — a `flow-engine.ts` file defines steps as data. Per-item steps are auto-generated from the items array so adding an item automatically adds a step.
+- **Data file** — a `data.ts` file contains the timeline items, category colors, era ranges, and connection definitions.
+- **Progressive reveal** — items light up one-by-one with a 3-state system (reached / active / upcoming) and a colored progress bar tracks progress.
+- **Animated nodes** — the active node rises up with an `animateTo()` entrance and the camera auto-pans via `zoomToNode()`.
+- **8 files** instead of the standard 6, including `flow-engine.ts` and `data.ts`.
+
+Use timeline plugins when you want a chronological walkthrough with per-item detail cards and connection overlays.
+
+## Requirements
+
+- Node.js 20+
+
+3. Add a short summary sentence.
+
+## Template docs
+
+Scaffolded playground usage and plugin-generation docs are in template/README.md.

package/index.js

@@ -160,6 +160,10 @@ export default playgroundConfig;
   console.log("");
   console.log('    npm run generate my-concept --category "My Category"');
   console.log("");
+  console.log("  Or scaffold a sandbox plugin (dynamic components, flow engine):");
+  console.log("");
+  console.log('    npm run generate my-concept --sandbox --category "My Category"');
+  console.log("");
 
   rl.close();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-vizcraft-playground",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Scaffold a new VizCraft interactive visualization playground",
   "type": "module",
   "bin": {

package/template/README.md

@@ -35,7 +35,27 @@ For example:
 npm run generate supply-demand --category "Microeconomics"
 ```
 
-This creates `src/plugins/<plugin-name>/` with six files and wires it into the registry automatically. If the category doesn't exist yet, it will be created.
+This creates `src/plugins/<plugin-name>/` and wires it into the registry automatically. If the category doesn't exist yet, it will be created.
+
+### Generate a sandbox plugin
+
+Use the sandbox option when you want dynamic infrastructure toggles and adaptive step flows:
+
+```bash
+npm run generate cloud-lab --category "Systems" --sandbox
+```
+
+The generator includes sandbox-aware defaults and structure for component toggles, step mapping, and interaction-focused scenes.
+
+### Generate a timeline plugin
+
+Use the timeline option when you want a progressive-reveal timeline with animated nodes, a progress bar, and declarative steps auto-generated from a data array:
+
+```bash
+npm run generate historical-events --category "History" --timeline
+```
+
+A timeline plugin generates 8 files (the standard 6 plus `flow-engine.ts` and `data.ts`). Steps are built dynamically from the items array in `data.ts` — adding an item automatically adds a step.
 
 ### Plugin structure