create-vizcraft-playground 0.1.0 → 0.1.1

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.1.1",
   "description": "Scaffold a new VizCraft interactive visualization playground",
   "type": "module",
   "bin": {

package/template/scripts/generate-plugin.js

@@ -6,14 +6,17 @@ const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
 // ── Arg parsing ────────────────────────────────────────────
-// Usage:  npm run generate <plugin-name> [--category "Category Name"]
+// Usage:  npm run generate <plugin-name> [--category "Category Name"] [--sandbox]
 const args = process.argv.slice(2);
 let pluginName = null;
 let categoryName = null;
+let isSandbox = false;
 
 for (let i = 0; i < args.length; i++) {
   if (args[i] === "--category" || args[i] === "-c") {
     categoryName = args[++i];
+  } else if (args[i] === "--sandbox" || args[i] === "-s") {
+    isSandbox = true;
   } else if (!args[i].startsWith("-")) {
     pluginName = args[i];
   }
@@ -21,9 +24,11 @@ for (let i = 0; i < args.length; i++) {
 
 if (!pluginName) {
   console.error(
-    "Usage: npm run generate <plugin-name> [--category \"Category Name\"]\n" +
+    "Usage: npm run generate <plugin-name> [--category \"Category Name\"] [--sandbox]\n" +
       "       Name must be kebab-case, e.g. npm run generate api-gateway\n" +
-      "       --category / -c   Existing or new category to place the plugin in",
+      "       --category / -c   Existing or new category to place the plugin in\n" +
+      "       --sandbox / -s    Generate a sandbox plugin with declarative flow engine,\n" +
+      "                         Controls panel, and dynamic component toggling",
   );
   process.exit(1);
 }
@@ -49,7 +54,175 @@ fs.mkdirSync(targetDir, { recursive: true });
 /* ================================================================
    1. Redux Slice  — ${camelName}Slice.ts
    ================================================================ */
-const sliceContent = `import { createSlice, type PayloadAction } from "@reduxjs/toolkit";
+let sliceContent;
+if (isSandbox) {
+sliceContent = `import { createSlice, type PayloadAction } from "@reduxjs/toolkit";
+
+/* ── Addable infrastructure components ───────────────── */
+export interface InfraComponents {
+  // TODO: add your togglable components here
+  // database: boolean;
+  // loadBalancer: boolean;
+  // cache: boolean;
+  // extraServers: number;
+}
+
+export type ComponentName = keyof InfraComponents;
+
+/** Which components require which prerequisites. */
+const PREREQUISITES: Partial<Record<ComponentName, ComponentName[]>> = {
+  // cache: ["database"],
+};
+
+/** Which components cascade-remove when toggled off. */
+const CASCADE_REMOVE: Partial<Record<ComponentName, ComponentName[]>> = {
+  // database: ["cache"],
+};
+
+/* ── Client model ────────────────────────────────────── */
+export interface ClientNode {
+  id: string;
+  type: "desktop" | "mobile";
+}
+
+/* ── State shape ─────────────────────────────────────── */
+export interface ${pascalName}State {
+  components: InfraComponents;
+  clients: ClientNode[];
+
+  /* derived metrics (recomputed by computeMetrics) */
+  requestsPerSecond: number;
+  maxCapacity: number;
+  throughput: number;
+  droppedRequests: number;
+
+  /* ui */
+  hotZones: string[];
+  explanation: string;
+  phase: string;
+}
+
+const defaultClients: ClientNode[] = [
+  { id: "client-1", type: "desktop" },
+  { id: "client-2", type: "mobile" },
+  { id: "client-3", type: "desktop" },
+];
+
+/* ── Capacity model ──────────────────────────────────── */
+function getMaxCapacity(c: InfraComponents): number {
+  let cap = 60; // base solo capacity
+  // TODO: adjust capacity based on components
+  return cap;
+}
+
+export function computeMetrics(state: ${pascalName}State) {
+  const rps = state.clients.length * 10;
+  state.requestsPerSecond = rps;
+  state.maxCapacity = getMaxCapacity(state.components);
+  state.throughput = Math.min(rps, state.maxCapacity);
+  state.droppedRequests = Math.max(0, rps - state.maxCapacity);
+}
+
+function describeArch(c: InfraComponents): string {
+  const parts: string[] = ["Server"];
+  // TODO: push active component labels
+  return parts.join(" + ");
+}
+
+export const initialState: ${pascalName}State = {
+  components: {
+    // TODO: initialise your components (all off by default)
+  } as InfraComponents,
+  clients: defaultClients,
+
+  requestsPerSecond: 30,
+  maxCapacity: 60,
+  throughput: 30,
+  droppedRequests: 0,
+
+  hotZones: [],
+  explanation: "Welcome — build the architecture using the controls above.",
+  phase: "overview",
+};
+
+computeMetrics(initialState);
+
+/* ── Slice ───────────────────────────────────────────── */
+const ${camelName}Slice = createSlice({
+  name: "${camelName}",
+  initialState,
+  reducers: {
+    reset: () => {
+      const s = { ...initialState, clients: [...initialState.clients] };
+      computeMetrics(s);
+      return s;
+    },
+    patchState(state, action: PayloadAction<Partial<${pascalName}State>>) {
+      Object.assign(state, action.payload);
+    },
+    recalcMetrics(state) {
+      computeMetrics(state);
+    },
+
+    /* ── Component toggles ─────────────────────────── */
+    addComponent(state, action: PayloadAction<ComponentName>) {
+      const name = action.payload;
+      const prereqs = PREREQUISITES[name];
+      if (prereqs?.some((p) => !state.components[p])) return;
+
+      // TODO: handle numeric components (e.g. extraServers)
+      if (state.components[name]) return;
+      (state.components[name] as boolean) = true;
+
+      computeMetrics(state);
+      state.explanation = \`Added! Architecture: \${describeArch(state.components)}. Capacity: ~\${state.maxCapacity} rps.\`;
+    },
+
+    removeComponent(state, action: PayloadAction<ComponentName>) {
+      const name = action.payload;
+      if (!state.components[name]) return;
+      (state.components[name] as boolean) = false;
+
+      const cascades = CASCADE_REMOVE[name];
+      if (cascades) {
+        for (const dep of cascades) {
+          (state.components[dep] as boolean) = false;
+        }
+      }
+
+      computeMetrics(state);
+      state.explanation = \`Removed. Architecture: \${describeArch(state.components)}. Capacity: ~\${state.maxCapacity} rps.\`;
+    },
+
+    /* ── Client controls ───────────────────────────── */
+    addClient(state) {
+      if (state.clients.length >= 12) return;
+      const id = \`client-\${Date.now()}\`;
+      const type = state.clients.length % 2 === 0 ? "desktop" : "mobile";
+      state.clients.push({ id, type });
+      computeMetrics(state);
+    },
+    removeClient(state) {
+      if (state.clients.length <= 1) return;
+      state.clients.pop();
+      computeMetrics(state);
+    },
+  },
+});
+
+export const {
+  reset,
+  patchState,
+  recalcMetrics,
+  addComponent,
+  removeComponent,
+  addClient,
+  removeClient,
+} = ${camelName}Slice.actions;
+export default ${camelName}Slice.reducer;
+`;
+} else {
+sliceContent = `import { createSlice, type PayloadAction } from "@reduxjs/toolkit";
 
 export type ${pascalName}Phase = "overview" | "processing" | "summary";
 
@@ -81,13 +254,196 @@ const ${camelName}Slice = createSlice({
 export const { patchState, reset } = ${camelName}Slice.actions;
 export default ${camelName}Slice.reducer;
 `;
+} // end if/else sandbox slice
 
 fs.writeFileSync(path.join(targetDir, `${camelName}Slice.ts`), sliceContent);
 
 /* ================================================================
    2. Animation Hook  — use${pascalName}Animation.ts
    ================================================================ */
-const hookContent = `import { useCallback, useEffect, useRef, useState } from "react";
+let hookContent;
+if (isSandbox) {
+hookContent = `import { useCallback, useEffect, useRef, useState } from "react";
+import { useDispatch, useSelector } from "react-redux";
+import type { SignalOverlayParams } from "vizcraft";
+import { type RootState } from "../../store/store";
+import {
+  patchState,
+  reset,
+  recalcMetrics,
+  type ${pascalName}State,
+} from "./${camelName}Slice";
+import { STEPS, buildSteps, executeFlow, type StepKey } from "./flow-engine";
+
+export type Signal = { id: string; color?: string } & SignalOverlayParams;
+
+/* ──────────────────────────────────────────────────────────
+   Declarative animation hook.
+
+   Reads step config from STEPS, resolves the current step
+   key, then uses executeFlow to run the declared beats.
+   No per-step imperative code needed.
+   ────────────────────────────────────────────────────────── */
+
+export const use${pascalName}Animation = (onAnimationComplete?: () => void) => {
+  const dispatch = useDispatch();
+  const { currentStep } = useSelector((state: RootState) => state.simulation);
+  const runtime = useSelector(
+    (state: RootState) => state.${camelName},
+  ) as ${pascalName}State;
+  const [signals, setSignals] = useState<Signal[]>([]);
+  const rafRef = useRef<number>(0);
+  const timeoutsRef = useRef<Array<ReturnType<typeof setTimeout>>>([]);
+  const onCompleteRef = useRef(onAnimationComplete);
+  const runtimeRef = useRef(runtime);
+
+  onCompleteRef.current = onAnimationComplete;
+  runtimeRef.current = runtime;
+
+  const cleanup = useCallback(() => {
+    cancelAnimationFrame(rafRef.current);
+    timeoutsRef.current.forEach((id) => clearTimeout(id));
+    timeoutsRef.current = [];
+    setSignals([]);
+  }, []);
+
+  const sleep = useCallback(
+    (ms: number) =>
+      new Promise<void>((resolve) => {
+        const id = setTimeout(resolve, ms);
+        timeoutsRef.current.push(id);
+      }),
+    [],
+  );
+
+  const animateParallel = useCallback(
+    (pairs: { from: string; to: string }[], duration: number) => {
+      return new Promise<void>((resolve) => {
+        const start = performance.now();
+        const sigs = pairs.map((p, i) => ({
+          id: \`par-\${i}-\${Date.now()}\`,
+          from: p.from,
+          to: p.to,
+          progress: 0,
+          magnitude: 0.8,
+        }));
+
+        const tick = (now: number) => {
+          const p = Math.min((now - start) / duration, 1);
+          setSignals(sigs.map((s) => ({ ...s, progress: p })));
+          if (p < 1) {
+            rafRef.current = requestAnimationFrame(tick);
+          } else {
+            resolve();
+          }
+        };
+        rafRef.current = requestAnimationFrame(tick);
+      });
+    },
+    [],
+  );
+
+  /* ── Resolve current step ─────────────────────────── */
+  const steps = buildSteps(runtime);
+  const currentKey: StepKey | undefined = steps[currentStep]?.key;
+
+  /* ── Generic step executor ────────────────────────── */
+  useEffect(() => {
+    let cancelled = false;
+    cleanup();
+
+    const finish = () => {
+      if (!cancelled) setTimeout(() => onCompleteRef.current?.(), 0);
+    };
+    const rt = () => runtimeRef.current;
+    const doPatch = (p: Partial<${pascalName}State>) => dispatch(patchState(p));
+
+    const stepDef = STEPS.find((s) => s.key === currentKey);
+    if (!stepDef) {
+      finish();
+      return cleanup;
+    }
+
+    const run = async () => {
+      // 1. Special actions
+      if (stepDef.action === "reset") {
+        dispatch(reset());
+        finish();
+        return;
+      }
+
+      // 2. Recalc metrics early (for non-flow steps)
+      if (stepDef.recalcMetrics && !stepDef.flow) {
+        dispatch(recalcMetrics());
+      }
+
+      // 3. Set phase
+      if (stepDef.phase) {
+        const phase =
+          typeof stepDef.phase === "function"
+            ? stepDef.phase(rt())
+            : stepDef.phase;
+        doPatch({ phase });
+      }
+
+      // 4. Set initial hot zones for non-flow steps
+      if (stepDef.finalHotZones !== undefined && !stepDef.flow) {
+        doPatch({ hotZones: stepDef.finalHotZones });
+      }
+
+      // 5. Execute flow beats
+      if (stepDef.flow) {
+        await executeFlow(stepDef.flow, {
+          animateParallel,
+          patch: doPatch,
+          getState: rt,
+          cancelled: () => cancelled,
+        });
+        if (cancelled) return;
+      }
+
+      // 6. Recalc after flow
+      if (stepDef.recalcMetrics && stepDef.flow) {
+        dispatch(recalcMetrics());
+      }
+
+      // 7. Delay
+      if (stepDef.delay) {
+        await sleep(stepDef.delay);
+        if (cancelled) return;
+      }
+
+      // 8. Final hot zones
+      if (stepDef.finalHotZones !== undefined) {
+        doPatch({ hotZones: stepDef.finalHotZones });
+      } else if (!stepDef.flow) {
+        doPatch({ hotZones: [] });
+      }
+
+      // 9. Final explanation
+      if (stepDef.explain) {
+        const explanation =
+          typeof stepDef.explain === "function"
+            ? stepDef.explain(rt())
+            : stepDef.explain;
+        doPatch({ explanation });
+      }
+
+      finish();
+    };
+
+    run();
+    return () => {
+      cancelled = true;
+      cleanup();
+    };
+  }, [currentStep, currentKey, cleanup, dispatch, sleep, animateParallel]);
+
+  return { runtime, signals };
+};
+`;
+} else {
+hookContent = `import { useCallback, useEffect, useRef, useState } from "react";
 import { useDispatch, useSelector } from "react-redux";
 import type { SignalOverlayParams } from "vizcraft";
 import { type RootState } from "../../store/store";
@@ -178,6 +534,7 @@ export const use${pascalName}Animation = (onAnimationComplete?: () => void) => {
   };
 };
 `;
+} // end if/else sandbox hook
 
 fs.writeFileSync(
   path.join(targetDir, `use${pascalName}Animation.ts`),
@@ -414,7 +771,52 @@ fs.writeFileSync(path.join(targetDir, "main.scss"), scssContent);
 /* ================================================================
    6. Plugin Registration  — index.ts
    ================================================================ */
-const indexContent = `import type { Action, Dispatch } from "@reduxjs/toolkit";
+let indexContent;
+if (isSandbox) {
+indexContent = `import type { Action, Dispatch } from "@reduxjs/toolkit";
+import type { DemoPlugin, DemoStep } from "../../types/ModelPlugin";
+import ${pascalName}Visualization from "./main";
+import ${pascalName}Controls from "./controls";
+import ${camelName}Reducer, {
+  type ${pascalName}State,
+  initialState,
+  reset,
+} from "./${camelName}Slice";
+import {
+  buildSteps,
+  type StepKey,
+  type TaggedStep,
+} from "./flow-engine";
+
+type LocalRootState = { ${camelName}: ${pascalName}State };
+
+const ${pascalName}Plugin: DemoPlugin<
+  ${pascalName}State,
+  Action,
+  LocalRootState,
+  Dispatch<Action>
+> = {
+  id: "${pluginName}",
+  name: "${pascalName}",
+  description: "Describe what this demo teaches in one sentence.",
+  initialState,
+  reducer: ${camelName}Reducer,
+  Component: ${pascalName}Visualization,
+  Controls: ${pascalName}Controls,
+  restartConfig: { text: "Replay", color: "#3b82f6" },
+  getSteps: (state: ${pascalName}State): DemoStep[] => buildSteps(state),
+  init: (dispatch) => {
+    dispatch(reset());
+  },
+  selector: (state: LocalRootState) => state.${camelName},
+};
+
+export { buildSteps };
+export type { StepKey, TaggedStep };
+export default ${pascalName}Plugin;
+`;
+} else {
+indexContent = `import type { Action, Dispatch } from "@reduxjs/toolkit";
 import type { DemoPlugin, DemoStep } from "../../types/ModelPlugin";
 import ${pascalName}Visualization from "./main";
 import ${camelName}Reducer, {
@@ -462,11 +864,345 @@ const ${pascalName}Plugin: DemoPlugin<
 
 export default ${pascalName}Plugin;
 `;
+} // end if/else sandbox index
 
 fs.writeFileSync(path.join(targetDir, "index.ts"), indexContent);
 
 /* ================================================================
-   7. Update registry.ts — add import + wire into category
+   7. (Sandbox only) Flow Engine  — flow-engine.ts
+   ================================================================ */
+if (isSandbox) {
+const flowEngineContent = `import type { InfraComponents, ${pascalName}State } from "./${camelName}Slice";
+
+/* ══════════════════════════════════════════════════════════
+   Declarative Flow Engine
+
+   Define steps and their animation flows as DATA.
+   The engine handles token expansion, signal routing,
+   hot-zone derivation, and sequential execution.
+   ══════════════════════════════════════════════════════════ */
+
+/* ── Token expansion ─────────────────────────────────────
+   Use $-prefixed tokens as shorthand for dynamic node sets.
+   The engine expands them to actual node IDs at runtime.
+   ──────────────────────────────────────────────────────── */
+
+export function expandToken(
+  token: string,
+  state: ${pascalName}State,
+): string[] {
+  if (token === "$clients") return state.clients.map((c) => c.id);
+  // TODO: add more token expansions, e.g.:
+  // if (token === "$servers") {
+  //   const count = 1 + state.components.extraServers;
+  //   return Array.from({ length: count }, (_, i) => \`server-\${i}\`);
+  // }
+  return [token];
+}
+
+/* ── Flow Beat ───────────────────────────────────────────
+   One animation segment: signals travel from → to.
+   Tokens ($clients, $servers) expand to parallel signals.
+   ──────────────────────────────────────────────────────── */
+
+export interface FlowBeat {
+  from: string;
+  to: string;
+  when?: (c: InfraComponents) => boolean;
+  duration?: number;
+  explain?: string;
+}
+
+/* ── Step Definition ─────────────────────────────────────
+   Declarative config for one step in the visualization.
+   ──────────────────────────────────────────────────────── */
+
+export type StepKey = "overview" | "send-traffic" | "observe-metrics" | "summary";
+// TODO: add more step keys as you add components
+
+export interface StepDef {
+  key: StepKey;
+  label: string;
+  when?: (c: InfraComponents) => boolean;
+  nextButton?: string | ((c: InfraComponents) => string);
+  nextButtonColor?: string;
+  processingText?: string;
+  phase?: string | ((s: ${pascalName}State) => string);
+  flow?: FlowBeat[];
+  delay?: number;
+  recalcMetrics?: boolean;
+  finalHotZones?: string[];
+  explain?: string | ((s: ${pascalName}State) => string);
+  action?: "reset";
+}
+
+/* ── Step Configuration ──────────────────────────────────
+   Single source of truth. Each step gets its own unique
+   flow — never repeat the same signal path in two steps.
+   ──────────────────────────────────────────────────────── */
+
+export const STEPS: StepDef[] = [
+  {
+    key: "overview",
+    label: "Architecture Overview",
+    nextButton: "Send Traffic",
+    action: "reset",
+  },
+  {
+    key: "send-traffic",
+    label: "Send Traffic",
+    processingText: "Sending...",
+    nextButtonColor: "#2563eb",
+    phase: "traffic",
+    flow: [
+      {
+        from: "$clients",
+        to: "cloud",
+        duration: 700,
+        explain: "Clients send requests through the internet.",
+      },
+      {
+        from: "cloud",
+        to: "server-0",
+        duration: 600,
+        explain: "Requests arrive at the server.",
+      },
+    ],
+    recalcMetrics: true,
+    explain: (s) =>
+      \`Traffic flowing. \${s.requestsPerSecond} rps demand, \${s.maxCapacity} capacity.\`,
+  },
+  {
+    key: "observe-metrics",
+    label: "Observe Metrics",
+    nextButtonColor: "#2563eb",
+    recalcMetrics: true,
+    delay: 500,
+    phase: (s) => (s.droppedRequests > 0 ? "overloaded" : "stable"),
+    finalHotZones: ["server-0"],
+    explain: (s) =>
+      s.droppedRequests > 0
+        ? \`Overloaded! \${s.droppedRequests} requests dropped.\`
+        : \`Stable at \${s.throughput} rps. Try adding components.\`,
+  },
+  // TODO: add component-specific steps here (each with unique flow)
+  {
+    key: "summary",
+    label: "Summary",
+    phase: "summary",
+    explain: (s) =>
+      \`Max capacity: ~\${s.maxCapacity} rps. Try adding or removing components and replaying.\`,
+  },
+];
+
+/* ── Build active steps from config ──────────────────── */
+
+export interface TaggedStep {
+  key: StepKey;
+  label: string;
+  autoAdvance?: boolean;
+  nextButtonText?: string;
+  nextButtonColor?: string;
+  processingText?: string;
+}
+
+export function buildSteps(state: ${pascalName}State): TaggedStep[] {
+  const { components: c } = state;
+  const active = STEPS.filter((s) => !s.when || s.when(c));
+
+  return active.map((step, i) => {
+    const nextStep = active[i + 1];
+    let nextButtonText: string | undefined;
+    if (typeof step.nextButton === "function") {
+      nextButtonText = step.nextButton(c);
+    } else if (typeof step.nextButton === "string") {
+      nextButtonText = step.nextButton;
+    } else if (nextStep) {
+      nextButtonText = nextStep.label;
+    }
+
+    return {
+      key: step.key,
+      label: step.label,
+      autoAdvance: false,
+      nextButtonText,
+      nextButtonColor: step.nextButtonColor,
+      processingText: step.processingText,
+    };
+  });
+}
+
+/* ── Flow Executor ───────────────────────────────────── */
+
+export interface FlowExecutorDeps {
+  animateParallel: (
+    pairs: { from: string; to: string }[],
+    duration: number,
+  ) => Promise<void>;
+  patch: (p: Partial<${pascalName}State>) => void;
+  getState: () => ${pascalName}State;
+  cancelled: () => boolean;
+}
+
+export async function executeFlow(
+  beats: FlowBeat[],
+  deps: FlowExecutorDeps,
+): Promise<void> {
+  const components = deps.getState().components;
+  const activeBeats = beats.filter((b) => !b.when || b.when(components));
+
+  for (const beat of activeBeats) {
+    if (deps.cancelled()) return;
+
+    const state = deps.getState();
+    const froms = expandToken(beat.from, state);
+    const tos = expandToken(beat.to, state);
+
+    // Cartesian product → parallel signal pairs
+    const pairs: { from: string; to: string }[] = [];
+    for (const f of froms) {
+      for (const t of tos) {
+        pairs.push({ from: f, to: t });
+      }
+    }
+
+    const hotZones = [...new Set([...froms, ...tos])];
+    const update: Partial<${pascalName}State> = { hotZones };
+    if (beat.explain) update.explanation = beat.explain;
+    deps.patch(update);
+
+    await deps.animateParallel(pairs, beat.duration ?? 600);
+  }
+}
+`;
+
+fs.writeFileSync(path.join(targetDir, "flow-engine.ts"), flowEngineContent);
+
+/* ================================================================
+   8. (Sandbox only) Controls  — controls.tsx
+   ================================================================ */
+const controlsContent = `import React from "react";
+import { useDispatch, useSelector } from "react-redux";
+import { type RootState } from "../../store/store";
+import { resetSimulation } from "../../store/slices/simulationSlice";
+import {
+  addClient,
+  removeClient,
+  addComponent,
+  removeComponent,
+  type ${pascalName}State,
+  type ComponentName,
+} from "./${camelName}Slice";
+
+/* ── Component toggle descriptor ─────────────────────── */
+interface Toggle {
+  name: ComponentName;
+  label: string;
+  addLabel: string;
+  removeLabel: string;
+  color: string;
+  requires?: ComponentName[];
+  multi?: boolean;
+}
+
+const TOGGLES: Toggle[] = [
+  // TODO: define your component toggles here, e.g.:
+  // {
+  //   name: "database",
+  //   label: "Database",
+  //   addLabel: "+ Database",
+  //   removeLabel: "− Database",
+  //   color: "#22c55e",
+  // },
+];
+
+const ${pascalName}Controls: React.FC = () => {
+  const dispatch = useDispatch();
+  const { components, clients } = useSelector(
+    (state: RootState) => state.${camelName},
+  ) as ${pascalName}State;
+
+  const handleAdd = (name: ComponentName) => {
+    dispatch(addComponent(name));
+    dispatch(resetSimulation());
+  };
+
+  const handleRemove = (name: ComponentName) => {
+    dispatch(removeComponent(name));
+    dispatch(resetSimulation());
+  };
+
+  return (
+    <div className="${pluginName}-controls">
+      {/* Client count */}
+      <div className="${pluginName}-controls__group">
+        <button
+          className="${pluginName}-controls__btn"
+          onClick={() => dispatch(removeClient())}
+          disabled={clients.length <= 1}
+        >
+          −
+        </button>
+        <span className="${pluginName}-controls__label">
+          {clients.length} client{clients.length !== 1 ? "s" : ""}
+        </span>
+        <button
+          className="${pluginName}-controls__btn"
+          onClick={() => dispatch(addClient())}
+          disabled={clients.length >= 12}
+        >
+          +
+        </button>
+      </div>
+
+      <span className="${pluginName}-controls__sep" />
+
+      {/* Infrastructure toggles */}
+      {TOGGLES.map((t) => {
+        const isActive = t.multi
+          ? (components[t.name] as number) > 0
+          : !!components[t.name];
+        const prereqMet =
+          !t.requires || t.requires.every((r) => !!components[r]);
+        const canAdd = t.multi
+          ? prereqMet
+          : !isActive && prereqMet;
+
+        return (
+          <div key={t.name} className="${pluginName}-controls__group">
+            {isActive && (
+              <button
+                className="${pluginName}-controls__btn ${pluginName}-controls__btn--remove"
+                style={{ borderColor: t.color }}
+                onClick={() => handleRemove(t.name)}
+              >
+                {t.removeLabel}
+              </button>
+            )}
+            {canAdd && (
+              <button
+                className="${pluginName}-controls__btn ${pluginName}-controls__btn--add"
+                style={{ borderColor: t.color }}
+                onClick={() => handleAdd(t.name)}
+              >
+                {t.addLabel}
+              </button>
+            )}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+export default ${pascalName}Controls;
+`;
+
+fs.writeFileSync(path.join(targetDir, "controls.tsx"), controlsContent);
+} // end sandbox-only files
+
+/* ================================================================
+   9. Update registry.ts — add import + wire into category
    ================================================================ */
 const registryPath = path.join(__dirname, "../src/registry.ts");
 if (fs.existsSync(registryPath)) {
@@ -577,7 +1313,7 @@ if (fs.existsSync(registryPath)) {
 
 console.log("");
 console.log(
-  '✔ Created plugin "' + pluginName + '" in src/plugins/' + pluginName,
+  '✔ Created ' + (isSandbox ? 'sandbox ' : '') + 'plugin "' + pluginName + '" in src/plugins/' + pluginName,
 );
 console.log("");
 console.log("  Files generated:");
@@ -587,8 +1323,20 @@ console.log("    • concepts.tsx        — InfoModal concept definitions");
 console.log("    • main.tsx            — Component (uses plugin-kit)");
 console.log("    • main.scss           — Styles");
 console.log("    • index.ts            — Plugin registration");
+if (isSandbox) {
+  console.log("    • flow-engine.ts      — Declarative step & flow config");
+  console.log("    • controls.tsx        — Controls panel (component toggles)");
+}
 console.log("");
 console.log("  Next steps:");
-console.log("    1. Define your VizCraft nodes/edges in main.tsx");
-console.log("    2. Add step animations in use" + pascalName + "Animation.ts");
-console.log("    3. Add concept pills & definitions in concepts.tsx");
+if (isSandbox) {
+  console.log("    1. Define InfraComponents in " + camelName + "Slice.ts");
+  console.log("    2. Add togglable components to TOGGLES in controls.tsx");
+  console.log("    3. Define steps declaratively in STEPS array (flow-engine.ts)");
+  console.log("    4. Build dynamic scene in main.tsx (nodes/edges adapt to state)");
+  console.log("    5. Add concept pills & definitions in concepts.tsx");
+} else {
+  console.log("    1. Define your VizCraft nodes/edges in main.tsx");
+  console.log("    2. Add step animations in use" + pascalName + "Animation.ts");
+  console.log("    3. Add concept pills & definitions in concepts.tsx");
+}

package/template/src/App.scss

@@ -12,11 +12,7 @@
   /* dark slate */
   color: #e5e7eb;
   /* light gray */
-  font-family:
-    system-ui,
-    -apple-system,
-    BlinkMacSystemFont,
-    "Segoe UI",
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
     sans-serif;
   background-color: #111827; // Gray-900
 }
@@ -58,9 +54,7 @@
     align-items: center;
     justify-content: center;
     flex-shrink: 0;
-    transition:
-      background 0.15s,
-      border-color 0.15s;
+    transition: background 0.15s, border-color 0.15s;
     padding: 0;
 
     &:hover {
@@ -130,8 +124,25 @@
   position: relative;
   overflow: hidden;
   display: flex;
+  flex-direction: column;
   justify-content: center;
   align-items: center;
   padding: 2rem;
   background-color: #111827; // Gray-900
 }
+
+/* ── Plugin Controls slot ─────────────────────────── */
+.plugin-controls {
+  width: 100%;
+  flex-shrink: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.5rem 1rem;
+  background: rgba(15, 23, 42, 0.6);
+  border-bottom: 1px solid rgba(148, 163, 184, 0.1);
+  border-radius: 12px 12px 0 0;
+  backdrop-filter: blur(8px);
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}

package/template/src/components/Shell.tsx

@@ -134,6 +134,11 @@ const Shell: React.FC<ShellProps> = ({ plugin, category }) => {
         />
 
         <div className="visualization-container">
+          {plugin.Controls && (
+            <div className="plugin-controls">
+              <plugin.Controls />
+            </div>
+          )}
           <plugin.Component onAnimationComplete={handleAnimationComplete} />
         </div>
       </div>

package/template/src/index.scss

@@ -1,4 +1,4 @@
-@import "./components/plugin-kit/plugin-kit.scss";
+@use "./components/plugin-kit/plugin-kit.scss";
 
 :root {
   font-family: system-ui, Avenir, Helvetica, Arial, sans-serif;