create-vizcraft-playground 0.1.0

package/template/src/playground.config.ts

@@ -0,0 +1,27 @@
+/* ═══════════════════════════════════════════════════════
+ *  Playground Configuration
+ *
+ *  Single source of truth for branding & metadata.
+ *  Run `npm run init` to regenerate this file interactively,
+ *  or edit the values below directly.
+ * ═══════════════════════════════════════════════════════ */
+
+export interface PlaygroundConfig {
+  /** Project slug (kebab-case), used in package.json name */
+  name: string;
+  /** Display title shown on the landing page */
+  title: string;
+  /** One-liner shown below the title on the landing page */
+  subtitle: string;
+  /** Primary accent colour (hex) */
+  accent: string;
+}
+
+const playgroundConfig: PlaygroundConfig = {
+  name: "vizcraft-playground",
+  title: "VizCraft Playground",
+  subtitle: "Explore interactive visualizations.",
+  accent: "#3b82f6",
+};
+
+export default playgroundConfig;

package/template/src/plugins/hello-world/concepts.tsx

@@ -0,0 +1,70 @@
+import React from "react";
+import type { InfoModalSection } from "../../components/InfoModal/InfoModal";
+
+export type ConceptKey = "how-plugins-work";
+
+interface ConceptDefinition {
+  title: string;
+  subtitle: string;
+  accentColor: string;
+  sections: InfoModalSection[];
+  aside?: React.ReactNode;
+}
+
+export const concepts: Record<ConceptKey, ConceptDefinition> = {
+  "how-plugins-work": {
+    title: "How Plugins Work",
+    subtitle: "The building blocks of every playground demo",
+    accentColor: "#60a5fa",
+    sections: [
+      {
+        title: "Plugin anatomy",
+        accent: "#60a5fa",
+        content: (
+          <>
+            <p>
+              Every plugin lives in <code>src/plugins/your-name/</code> and
+              contains six files:
+            </p>
+            <ul style={{ paddingLeft: "1.2rem", marginTop: "0.5rem" }}>
+              <li>
+                <strong>index.ts</strong> — registers the plugin with the
+                playground (id, name, steps, reducer).
+              </li>
+              <li>
+                <strong>yourNameSlice.ts</strong> — Redux Toolkit slice for
+                local state.
+              </li>
+              <li>
+                <strong>useYourNameAnimation.ts</strong> — a hook that
+                orchestrates step-by-step animations.
+              </li>
+              <li>
+                <strong>main.tsx</strong> — the React component that renders
+                nodes, edges, and UI using the plugin-kit.
+              </li>
+              <li>
+                <strong>main.scss</strong> — plugin-specific styles.
+              </li>
+              <li>
+                <strong>concepts.tsx</strong> — definitions for the clickable
+                info pills.
+              </li>
+            </ul>
+          </>
+        ),
+      },
+      {
+        title: "Scaffolding a new plugin",
+        accent: "#34d399",
+        content: (
+          <p>
+            Run <code>npm run generate my-plugin --category "My Category"</code>{" "}
+            to create all six files and wire the plugin into the registry
+            automatically.
+          </p>
+        ),
+      },
+    ],
+  },
+};

package/template/src/plugins/hello-world/helloWorldSlice.ts

@@ -0,0 +1,29 @@
+import { createSlice, type PayloadAction } from "@reduxjs/toolkit";
+
+export type HelloWorldPhase = "idle" | "greeting" | "done";
+
+export interface HelloWorldState {
+  phase: HelloWorldPhase;
+  message: string;
+}
+
+export const initialState: HelloWorldState = {
+  phase: "idle",
+  message: "Press Next to see the plugin system in action.",
+};
+
+const helloWorldSlice = createSlice({
+  name: "helloWorld",
+  initialState,
+  reducers: {
+    patchState(state, action: PayloadAction<Partial<HelloWorldState>>) {
+      Object.assign(state, action.payload);
+    },
+    reset() {
+      return initialState;
+    },
+  },
+});
+
+export const { patchState, reset } = helloWorldSlice.actions;
+export default helloWorldSlice.reducer;

package/template/src/plugins/hello-world/index.ts

@@ -0,0 +1,48 @@
+import type { Action, Dispatch } from "@reduxjs/toolkit";
+import type { DemoPlugin, DemoStep } from "../../types/ModelPlugin";
+import HelloWorldVisualization from "./main";
+import helloWorldReducer, {
+  type HelloWorldState,
+  initialState,
+  reset,
+} from "./helloWorldSlice";
+
+type LocalRootState = { helloWorld: HelloWorldState };
+
+const HelloWorldPlugin: DemoPlugin<
+  HelloWorldState,
+  Action,
+  LocalRootState,
+  Dispatch<Action>
+> = {
+  id: "hello-world",
+  name: "Hello World",
+  description:
+    "A minimal reference plugin — two nodes, one signal, three steps. Study this to learn how the plugin system works.",
+  initialState,
+  reducer: helloWorldReducer,
+  Component: HelloWorldVisualization,
+  restartConfig: { text: "Replay", color: "#1e40af" },
+  getSteps: (_: HelloWorldState): DemoStep[] => [
+    {
+      label: "Idle",
+      autoAdvance: false,
+      nextButtonText: "Send Signal",
+    },
+    {
+      label: "Signal in flight",
+      autoAdvance: true,
+      processingText: "Sending…",
+    },
+    {
+      label: "Delivered",
+      autoAdvance: true,
+    },
+  ],
+  init: (dispatch) => {
+    dispatch(reset());
+  },
+  selector: (state: LocalRootState) => state.helloWorld,
+};
+
+export default HelloWorldPlugin;

package/template/src/plugins/hello-world/main.scss

@@ -0,0 +1,32 @@
+.hello-world-root {
+  --hw-bg: #020617;
+  --hw-panel: rgba(7, 17, 34, 0.88);
+  --hw-border: rgba(148, 163, 184, 0.18);
+  --hw-text: #e2e8f0;
+
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  color: var(--hw-text);
+  background:
+    radial-gradient(circle at top left, rgba(59, 130, 246, 0.14), transparent 28%),
+    radial-gradient(circle at bottom right, rgba(52, 211, 153, 0.12), transparent 30%),
+    linear-gradient(180deg, #020617 0%, #071325 100%);
+}
+
+.hello-world-stage {
+  background: var(--hw-panel);
+  border: 1px solid var(--hw-border);
+  box-shadow: 0 20px 42px -28px rgba(0, 0, 0, 0.7);
+  border-radius: 24px;
+  padding: 1rem;
+  display: flex;
+  flex-direction: column;
+  min-height: 0;
+}
+
+.hello-world-phase--idle .vc-stat-badge__value { color: #94a3b8; }
+.hello-world-phase--greeting .vc-stat-badge__value { color: #60a5fa; }
+.hello-world-phase--done .vc-stat-badge__value { color: #34d399; }

package/template/src/plugins/hello-world/main.tsx

@@ -0,0 +1,144 @@
+import React, { useLayoutEffect, useRef, useEffect } from "react";
+import {
+  viz,
+  type PanZoomController,
+  type SignalOverlayParams,
+} from "vizcraft";
+import {
+  useConceptModal,
+  ConceptPills,
+  PluginLayout,
+  StageHeader,
+  StatBadge,
+  SidePanel,
+  SideCard,
+  CanvasStage,
+} from "../../components/plugin-kit";
+import { concepts, type ConceptKey } from "./concepts";
+import {
+  useHelloWorldAnimation,
+  type Signal,
+} from "./useHelloWorldAnimation";
+import "./main.scss";
+
+interface Props {
+  onAnimationComplete?: () => void;
+}
+
+const W = 900;
+const H = 500;
+
+const HelloWorldVisualization: React.FC<Props> = ({ onAnimationComplete }) => {
+  const { runtime, currentStep, signals } =
+    useHelloWorldAnimation(onAnimationComplete);
+  const { openConcept, ConceptModal } = useConceptModal<ConceptKey>(concepts);
+  const containerRef = useRef<HTMLDivElement>(null!);
+  const builderRef = useRef<ReturnType<typeof viz> | null>(null);
+  const pzRef = useRef<PanZoomController | null>(null);
+
+  const { phase, message } = runtime;
+  const isGreeting = phase === "greeting" || phase === "done";
+
+  /* ── Build VizCraft scene ─────────────────────────────── */
+  const scene = (() => {
+    const b = viz().view(W, H);
+
+    b.node("sender")
+      .at(200, 250)
+      .rect(140, 60, 12)
+      .fill(isGreeting ? "#1e40af" : "#0f172a")
+      .stroke(isGreeting ? "#60a5fa" : "#334155", 2)
+      .label("Sender", { fill: "#fff", fontSize: 14, fontWeight: "bold" });
+
+    b.node("receiver")
+      .at(650, 250)
+      .rect(140, 60, 12)
+      .fill(phase === "done" ? "#065f46" : "#0f172a")
+      .stroke(phase === "done" ? "#34d399" : "#334155", 2)
+      .label("Receiver", { fill: "#fff", fontSize: 14, fontWeight: "bold" });
+
+    b.edge("sender", "receiver", "link")
+      .stroke("#475569", 2)
+      .animate("flow", { duration: "3s" });
+
+    if (signals.length > 0) {
+      b.overlay((o) => {
+        signals.forEach((sig) => {
+          const { id, ...params } = sig;
+          o.add("signal", params as SignalOverlayParams, { key: id });
+        });
+      });
+    }
+
+    return b;
+  })();
+
+  /* ── Mount / destroy ────────────────────────────────── */
+  useLayoutEffect(() => {
+    if (!containerRef.current) return;
+    const saved = pzRef.current?.getState() ?? null;
+    builderRef.current?.destroy();
+    builderRef.current = scene;
+    pzRef.current =
+      scene.mount(containerRef.current, {
+        autoplay: true,
+        panZoom: true,
+        initialZoom: saved?.zoom ?? 1,
+        initialPan: saved?.pan ?? { x: 0, y: 0 },
+      }) ?? null;
+  }, [scene]);
+
+  useEffect(() => {
+    return () => {
+      builderRef.current?.destroy();
+      builderRef.current = null;
+      pzRef.current = null;
+    };
+  }, []);
+
+  /* ── Pills ──────────────────────────────────────────── */
+  const pills = [
+    {
+      key: "how-plugins-work",
+      label: "How Plugins Work",
+      color: "#93c5fd",
+      borderColor: "#3b82f6",
+    },
+  ];
+
+  /* ── Render ─────────────────────────────────────────── */
+  return (
+    <div className="hello-world-root">
+      <PluginLayout
+        toolbar={<ConceptPills pills={pills} onOpen={openConcept} />}
+        canvas={
+          <div className="hello-world-stage">
+            <StageHeader title="Hello World" subtitle="A minimal reference plugin">
+              <StatBadge
+                label="Phase"
+                value={phase}
+                className={`hello-world-phase hello-world-phase--${phase}`}
+              />
+            </StageHeader>
+            <CanvasStage canvasRef={containerRef} />
+          </div>
+        }
+        sidebar={
+          <SidePanel>
+            <SideCard label="What's happening" variant="explanation">
+              <p>{message}</p>
+            </SideCard>
+            <SideCard label="Current step" variant="info">
+              <p style={{ fontSize: "2rem", fontWeight: 700, margin: 0 }}>
+                {currentStep}
+              </p>
+            </SideCard>
+          </SidePanel>
+        }
+      />
+      <ConceptModal />
+    </div>
+  );
+};
+
+export default HelloWorldVisualization;

package/template/src/plugins/hello-world/useHelloWorldAnimation.ts

@@ -0,0 +1,99 @@
+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 } from "./helloWorldSlice";
+
+export type Signal = { id: string } & SignalOverlayParams;
+
+export const useHelloWorldAnimation = (onAnimationComplete?: () => void) => {
+  const dispatch = useDispatch();
+  const { currentStep } = useSelector((state: RootState) => state.simulation);
+  const runtime = useSelector((state: RootState) => state.helloWorld);
+  const [signals, setSignals] = useState<Signal[]>([]);
+  const timeoutsRef = useRef<Array<ReturnType<typeof setTimeout>>>([]);
+  const onCompleteRef = useRef(onAnimationComplete);
+
+  onCompleteRef.current = onAnimationComplete;
+
+  const cleanup = useCallback(() => {
+    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 finish = useCallback(() => onCompleteRef.current?.(), []);
+
+  useEffect(() => {
+    cleanup();
+
+    const run = async () => {
+      switch (currentStep) {
+        case 0:
+          dispatch(reset());
+          finish();
+          break;
+
+        case 1:
+          dispatch(
+            patchState({
+              phase: "greeting",
+              message: "A signal is traveling between the two nodes.",
+            }),
+          );
+          setSignals([
+            {
+              id: "hello-sig",
+              from: "sender",
+              to: "receiver",
+              progress: 0,
+              magnitude: 1,
+            },
+          ]);
+          await sleep(1400);
+          setSignals([
+            {
+              id: "hello-sig",
+              from: "sender",
+              to: "receiver",
+              progress: 1,
+              magnitude: 1,
+            },
+          ]);
+          await sleep(400);
+          finish();
+          break;
+
+        case 2:
+          dispatch(
+            patchState({
+              phase: "done",
+              message:
+                "Signal delivered! This is how every plugin works — define nodes, edges, signals, and step logic.",
+            }),
+          );
+          setSignals([]);
+          await sleep(200);
+          finish();
+          break;
+
+        default:
+          finish();
+      }
+    };
+
+    run();
+    return cleanup;
+  }, [currentStep]);
+
+  return { runtime, currentStep, signals };
+};

package/template/src/registry.ts

@@ -0,0 +1,73 @@
+import type { DemoPlugin } from "./types/ModelPlugin";
+import HelloWorldPlugin from "./plugins/hello-world";
+
+/* ──────────────────────────────────────────────────────────
+ *  Plugin Category Registry
+ *
+ *  To add a new category:
+ *    1. Push a new PluginCategory into `categories` below.
+ *
+ *  To add a plugin to an existing category:
+ *    1. Import the plugin.
+ *    2. Add it to the `plugins` array of the target category.
+ *
+ *  The store, routes, and landing page all derive from this
+ *  single source of truth — no other files need to change.
+ * ────────────────────────────────────────────────────────── */
+
+export interface PluginCategory {
+  /** URL slug, e.g. "system-design" */
+  id: string;
+  /** Display name shown on the landing page */
+  name: string;
+  /** One-liner for the landing card */
+  description: string;
+  /** Accent colour for the card / heading */
+  accent: string;
+  /** Plugins that belong to this category */
+  plugins: DemoPlugin[];
+}
+
+export const categories: PluginCategory[] = [
+  {
+    id: "examples",
+    name: "Examples",
+    description:
+      "Reference plugins that demonstrate how the playground engine works.",
+    accent: "#6366f1",
+    plugins: [HelloWorldPlugin],
+  },
+];
+
+/* ── Helpers ─────────────────────────────────────────────── */
+
+/** Flat list of every registered plugin. */
+export const allPlugins: DemoPlugin[] = categories.flatMap((c) => c.plugins);
+
+/** kebab-case → camelCase  ("event-streaming" → "eventStreaming") */
+export const toCamelCase = (s: string) =>
+  s.replace(/-(\w)/g, (_, c: string) => c.toUpperCase());
+
+/**
+ * Build a `{ [camelKey]: reducer }` map for configureStore.
+ */
+export const pluginReducerMap = Object.fromEntries(
+  allPlugins.map((p) => [toCamelCase(p.id), p.reducer]),
+);
+
+/** Look up which category a plugin belongs to. */
+export function categoryForPlugin(
+  pluginId: string,
+): PluginCategory | undefined {
+  return categories.find((c) => c.plugins.some((p) => p.id === pluginId));
+}
+
+/** Look up a plugin by id. */
+export function findPlugin(pluginId: string): DemoPlugin | undefined {
+  return allPlugins.find((p) => p.id === pluginId);
+}
+
+/** Look up a category by id. */
+export function findCategory(categoryId: string): PluginCategory | undefined {
+  return categories.find((c) => c.id === categoryId);
+}

package/template/src/store/slices/simulationSlice.ts

@@ -0,0 +1,47 @@
+import { createSlice, type PayloadAction } from "@reduxjs/toolkit";
+
+interface SimulationState {
+  currentStep: number;
+  passCount: number;
+  isPlaying: boolean;
+}
+
+const initialState: SimulationState = {
+  currentStep: 0,
+  passCount: 1,
+  isPlaying: false,
+};
+
+const simulationSlice = createSlice({
+  name: "simulation",
+  initialState,
+  reducers: {
+    nextStep(state, action: PayloadAction<number>) {
+      // action.payload is maxSteps
+      state.currentStep = Math.min(state.currentStep + 1, action.payload);
+    },
+    setStep(state, action: PayloadAction<number>) {
+      state.currentStep = action.payload;
+    },
+    incrementPass(state) {
+      state.passCount += 1;
+    },
+    resetSimulation(state) {
+      state.currentStep = 0;
+      state.passCount = 1;
+      state.isPlaying = false;
+    },
+    setIsPlaying(state, action: PayloadAction<boolean>) {
+      state.isPlaying = action.payload;
+    },
+  },
+});
+
+export const {
+  nextStep,
+  setStep,
+  incrementPass,
+  resetSimulation,
+  setIsPlaying,
+} = simulationSlice.actions;
+export default simulationSlice.reducer;

package/template/src/store/store.ts

@@ -0,0 +1,13 @@
+import { configureStore } from "@reduxjs/toolkit";
+import simulationReducer from "./slices/simulationSlice";
+import { pluginReducerMap } from "../registry";
+
+export const store = configureStore({
+  reducer: {
+    ...pluginReducerMap,
+    simulation: simulationReducer,
+  },
+});
+
+export type RootState = ReturnType<typeof store.getState>;
+export type AppDispatch = typeof store.dispatch;

package/template/src/types/ModelPlugin.ts

@@ -0,0 +1,55 @@
+import React from "react";
+import type { Reducer, Action } from "@reduxjs/toolkit";
+
+export interface DemoPluginComponentProps {
+  onAnimationComplete?: () => void;
+}
+
+export interface DemoPlugin<
+  State = any,
+  Actions extends Action = any,
+  TRootState = any,
+  TDispatch = any,
+> {
+  id: string;
+  name: string;
+  description: string;
+
+  // State Management
+  initialState: State;
+  reducer: Reducer<State, Actions>;
+
+  // Rendering
+  Component: React.FC<DemoPluginComponentProps>;
+  Controls?: React.FC; // Optional settings panel
+
+  // Customization
+  restartConfig?: {
+    text?: string;
+    color?: string;
+  };
+
+  getSteps: (state: State) => (string | DemoStep)[];
+
+  // Lifecycle & Data Access
+  init: (dispatch: TDispatch) => void;
+  selector: (state: TRootState) => State;
+}
+
+export interface DemoStep {
+  label: string;
+  /**
+   * If true, the shell will automatically proceed to the next step
+   * after this step's animation/action is complete, without waiting for user input.
+   * Default: false (Requires "Next Step" button press)
+   */
+  autoAdvance?: boolean;
+
+  // Customization for the "Next Step" button
+  /** Text to display on the button when waiting for user input. Default: "Next Step" */
+  nextButtonText?: string;
+  /** Text to display on the button while processing/animating. Default: "Processing..." */
+  processingText?: string;
+  /** Background color of the button. Can be a CSS color string. Default: Theme blue */
+  nextButtonColor?: string;
+}

package/template/src/utils/random.ts

@@ -0,0 +1,11 @@
+export /**
+ * Generates a deterministic pseudo-random number between 0 and 1 based on a seed.
+ * This is widely used in shader code (GLSL) for generating noise.
+ * The magic number 43758.5453123 is a canonical constant optimized to produce
+ * a "random-looking" distribution of bits in the floating point mantissa when
+ * multiplied by the sine of the seed.
+ */
+function deterministicRandom(seed: number): number {
+  const raw = Math.sin(seed) * 43758.5453123;
+  return raw - Math.floor(raw);
+}

package/template/tsconfig.app.json

@@ -0,0 +1,35 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": [
+      "ES2022",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "module": "ESNext",
+    "types": [
+      "vite/client"
+    ],
+    "skipLibCheck": true,
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    "esModuleInterop": true
+  },
+  "include": [
+    "src"
+  ]
+}