@stevejtrettel/shader-sandbox 0.1.0

package/src/project/loaderHelper.ts

@@ -0,0 +1,300 @@
+/**
+ * Helper functions for loading demo files
+ * Called by the generated loader
+ */
+
+import {
+  ShadertoyProject,
+  ShadertoyConfig,
+  PassName,
+  ChannelValue,
+  ChannelJSONObject,
+} from './types';
+
+/**
+ * Case-insensitive file lookup helper.
+ * Returns the actual key from the record that matches the path (case-insensitive).
+ */
+function findFileCaseInsensitive<T>(
+  files: Record<string, T>,
+  path: string
+): string | null {
+  // First try exact match
+  if (path in files) return path;
+
+  // Try case-insensitive match
+  const lowerPath = path.toLowerCase();
+  for (const key of Object.keys(files)) {
+    if (key.toLowerCase() === lowerPath) {
+      return key;
+    }
+  }
+  return null;
+}
+
+/**
+ * Type guard for PassName.
+ */
+function isPassName(s: string): s is PassName {
+  return s === 'Image' || s === 'BufferA' || s === 'BufferB' || s === 'BufferC' || s === 'BufferD';
+}
+
+/**
+ * Parse a channel value (string shorthand or object) into normalized ChannelJSONObject.
+ */
+function parseChannelValue(value: ChannelValue): ChannelJSONObject | null {
+  if (typeof value === 'string') {
+    if (isPassName(value)) {
+      return { buffer: value };
+    }
+    if (value === 'keyboard') {
+      return { keyboard: true };
+    }
+    return { texture: value };
+  }
+  return value;
+}
+
+export async function loadDemo(
+  demoName: string,
+  glslFiles: Record<string, () => Promise<string>>,
+  jsonFiles: Record<string, () => Promise<ShadertoyConfig>>,
+  imageFiles: Record<string, () => Promise<string>>
+): Promise<ShadertoyProject> {
+  const configPath = `/demos/${demoName}/config.json`;
+  const hasConfig = configPath in jsonFiles;
+
+  if (hasConfig) {
+    const config = await jsonFiles[configPath]();
+    const hasPassConfigs = config.Image || config.BufferA || config.BufferB ||
+                           config.BufferC || config.BufferD;
+
+    if (hasPassConfigs) {
+      return loadWithConfig(demoName, config, glslFiles, imageFiles);
+    } else {
+      // Config with only settings (layout, controls, etc.) but no passes
+      return loadSinglePass(demoName, glslFiles, config);
+    }
+  } else {
+    return loadSinglePass(demoName, glslFiles);
+  }
+}
+
+async function loadSinglePass(
+  demoName: string,
+  glslFiles: Record<string, () => Promise<string>>,
+  configOverrides?: Partial<ShadertoyConfig>
+): Promise<ShadertoyProject> {
+  const imagePath = `/demos/${demoName}/image.glsl`;
+  const actualImagePath = findFileCaseInsensitive(glslFiles, imagePath);
+
+  if (!actualImagePath) {
+    throw new Error(`Demo '${demoName}' not found. Expected ${imagePath}`);
+  }
+
+  const imageSource = await glslFiles[actualImagePath]();
+
+  const layout = configOverrides?.layout || 'tabbed';
+  const controls = configOverrides?.controls ?? true;
+  const title = configOverrides?.title ||
+                demoName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+
+  return {
+    root: `/demos/${demoName}`,
+    meta: {
+      title,
+      author: configOverrides?.author || null,
+      description: configOverrides?.description || null,
+    },
+    layout,
+    controls,
+    commonSource: null,
+    passes: {
+      Image: {
+        name: 'Image',
+        glslSource: imageSource,
+        channels: [
+          { kind: 'none' },
+          { kind: 'none' },
+          { kind: 'none' },
+          { kind: 'none' },
+        ],
+      },
+    },
+    textures: [],
+  };
+}
+
+async function loadWithConfig(
+  demoName: string,
+  config: ShadertoyConfig,
+  glslFiles: Record<string, () => Promise<string>>,
+  imageFiles: Record<string, () => Promise<string>>
+): Promise<ShadertoyProject> {
+
+  // Extract pass configs from top level
+  const passConfigs = {
+    Image: config.Image,
+    BufferA: config.BufferA,
+    BufferB: config.BufferB,
+    BufferC: config.BufferC,
+    BufferD: config.BufferD,
+  };
+
+  // Load common source
+  let commonSource: string | null = null;
+  if (config.common) {
+    const commonPath = `/demos/${demoName}/${config.common}`;
+    const actualCommonPath = findFileCaseInsensitive(glslFiles, commonPath);
+    if (actualCommonPath) {
+      commonSource = await glslFiles[actualCommonPath]();
+    }
+  } else {
+    const defaultCommonPath = `/demos/${demoName}/common.glsl`;
+    const actualCommonPath = findFileCaseInsensitive(glslFiles, defaultCommonPath);
+    if (actualCommonPath) {
+      commonSource = await glslFiles[actualCommonPath]();
+    }
+  }
+
+  // Collect all texture paths
+  const texturePathsSet = new Set<string>();
+  const passOrder = ['Image', 'BufferA', 'BufferB', 'BufferC', 'BufferD'] as const;
+
+  for (const passName of passOrder) {
+    const passConfig = passConfigs[passName];
+    if (!passConfig) continue;
+
+    for (const channelKey of ['iChannel0', 'iChannel1', 'iChannel2', 'iChannel3'] as const) {
+      const channelValue = passConfig[channelKey];
+      if (!channelValue) continue;
+
+      const parsed = parseChannelValue(channelValue);
+      if (parsed && 'texture' in parsed) {
+        texturePathsSet.add(parsed.texture);
+      }
+    }
+  }
+
+  // Load textures
+  const textures: any[] = [];
+  const texturePathToName = new Map<string, string>();
+
+  for (const texturePath of texturePathsSet) {
+    const fullPath = `/demos/${demoName}/${texturePath.replace(/^\.\//, '')}`;
+    const actualPath = findFileCaseInsensitive(imageFiles, fullPath);
+
+    if (!actualPath) {
+      throw new Error(`Texture not found: ${texturePath} (expected at ${fullPath})`);
+    }
+
+    const imageUrl = await imageFiles[actualPath]();
+    const textureFilename = texturePath.split('/').pop()!;
+    const textureName = textureFilename.replace(/\.[^.]+$/, '');
+
+    textures.push({
+      name: textureName,
+      filename: textureFilename,  // Preserve original filename for display
+      source: imageUrl,
+      filter: 'linear' as const,
+      wrap: 'repeat' as const,
+    });
+
+    texturePathToName.set(texturePath, textureName);
+  }
+
+  // Build passes
+  const passes: any = {};
+
+  for (const passName of passOrder) {
+    const passConfig = passConfigs[passName];
+    if (!passConfig) continue;
+
+    const defaultNames: Record<string, string> = {
+      Image: 'image.glsl',
+      BufferA: 'bufferA.glsl',
+      BufferB: 'bufferB.glsl',
+      BufferC: 'bufferC.glsl',
+      BufferD: 'bufferD.glsl',
+    };
+
+    const sourceFile = passConfig.source || defaultNames[passName];
+    const sourcePath = `/demos/${demoName}/${sourceFile}`;
+    const actualSourcePath = findFileCaseInsensitive(glslFiles, sourcePath);
+
+    if (!actualSourcePath) {
+      throw new Error(`Missing shader file: ${sourcePath}`);
+    }
+
+    const glslSource = await glslFiles[actualSourcePath]();
+
+    const channels = [
+      normalizeChannel(passConfig.iChannel0, texturePathToName),
+      normalizeChannel(passConfig.iChannel1, texturePathToName),
+      normalizeChannel(passConfig.iChannel2, texturePathToName),
+      normalizeChannel(passConfig.iChannel3, texturePathToName),
+    ];
+
+    passes[passName] = {
+      name: passName,
+      glslSource,
+      channels,
+    };
+  }
+
+  if (!passes.Image) {
+    throw new Error(`Demo '${demoName}' must have an Image pass`);
+  }
+
+  const title = config.title ||
+                demoName.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+  const author = config.author || null;
+  const description = config.description || null;
+  const layout = config.layout || 'tabbed';
+  const controls = config.controls ?? true;
+
+  return {
+    root: `/demos/${demoName}`,
+    meta: { title, author, description },
+    layout,
+    controls,
+    commonSource,
+    passes,
+    textures,
+  };
+}
+
+function normalizeChannel(channelValue: ChannelValue | undefined, texturePathToName?: Map<string, string>): any {
+  if (!channelValue) {
+    return { kind: 'none' };
+  }
+
+  // Parse string shorthand
+  const parsed = parseChannelValue(channelValue);
+  if (!parsed) {
+    return { kind: 'none' };
+  }
+
+  if ('buffer' in parsed) {
+    return {
+      kind: 'buffer',
+      buffer: parsed.buffer,
+      current: !!parsed.current,
+    };
+  }
+
+  if ('texture' in parsed) {
+    const textureName = texturePathToName?.get(parsed.texture) || parsed.texture;
+    return {
+      kind: 'texture',
+      name: textureName,
+      cubemap: parsed.type === 'cubemap',
+    };
+  }
+
+  if ('keyboard' in parsed) {
+    return { kind: 'keyboard' };
+  }
+
+  return { kind: 'none' };
+}

package/src/project/types.ts

@@ -0,0 +1,243 @@
+/**
+ * Project Layer - Type Definitions for Shadertoy Projects
+ *
+ * Pure TypeScript interfaces matching Shadertoy's mental model.
+ * Based on docs/project-spec.md
+ */
+
+// =============================================================================
+// Pass Names (Fixed set matching Shadertoy)
+// =============================================================================
+
+export type PassName = 'Image' | 'BufferA' | 'BufferB' | 'BufferC' | 'BufferD';
+
+// =============================================================================
+// Channel Definitions (JSON Config Format)
+// =============================================================================
+
+/**
+ * Reference to another buffer pass.
+ * By default, reads the previous frame (safe for all cases).
+ * Use current: true to read from a buffer that has already run this frame.
+ */
+export interface ChannelJSONBuffer {
+  buffer: PassName;
+  current?: boolean;  // Default: false (read previous frame)
+}
+
+/**
+ * Reference to external texture (image file).
+ */
+export interface ChannelJSONTexture {
+  texture: string;  // Path to image file
+  filter?: 'nearest' | 'linear';  // Default: 'linear'
+  wrap?: 'clamp' | 'repeat';      // Default: 'repeat'
+  type?: '2d' | 'cubemap';        // Default: '2d'. Cubemap uses equirectangular projection.
+}
+
+/**
+ * Reference to keyboard texture (runtime-provided).
+ */
+export interface ChannelJSONKeyboard {
+  keyboard: true;
+}
+
+/**
+ * Union type for channel sources in JSON config (object form).
+ */
+export type ChannelJSONObject =
+  | ChannelJSONBuffer
+  | ChannelJSONTexture
+  | ChannelJSONKeyboard;
+
+/**
+ * Channel value in simplified config format.
+ * Can be a string shorthand or full object:
+ * - "BufferA", "BufferB", etc. → buffer reference
+ * - "keyboard" → keyboard input
+ * - "photo.jpg" (with extension) → texture file
+ * - { buffer: "BufferA" } → explicit buffer with options
+ * - { texture: "photo.jpg", filter: "nearest" } → texture with options
+ */
+export type ChannelValue = string | ChannelJSONObject;
+
+// =============================================================================
+// Config Format (config.json) - Simplified flat format
+// =============================================================================
+
+/**
+ * Pass configuration in simplified format.
+ * Channel bindings are directly on the pass object.
+ *
+ * Example:
+ * {
+ *   "iChannel0": "BufferA",
+ *   "iChannel1": "photo.jpg",
+ *   "source": "custom.glsl"  // optional
+ * }
+ */
+export interface PassConfigSimplified {
+  /** Optional custom source file path */
+  source?: string;
+  /** Channel bindings - string shorthand or full object */
+  iChannel0?: ChannelValue;
+  iChannel1?: ChannelValue;
+  iChannel2?: ChannelValue;
+  iChannel3?: ChannelValue;
+}
+
+/**
+ * Top-level config.json structure (simplified flat format).
+ *
+ * Example:
+ * {
+ *   "title": "My Shader",
+ *   "layout": "split",
+ *   "controls": true,
+ *
+ *   "BufferA": {
+ *     "iChannel0": "BufferA"
+ *   },
+ *   "Image": {
+ *     "iChannel0": "BufferA"
+ *   }
+ * }
+ */
+export interface ShadertoyConfig {
+  // Metadata (flat, not nested)
+  title?: string;
+  author?: string;
+  description?: string;
+
+  // Settings
+  layout?: 'fullscreen' | 'default' | 'split' | 'tabbed';
+  controls?: boolean;
+  common?: string;
+
+  // Passes (at top level)
+  Image?: PassConfigSimplified;
+  BufferA?: PassConfigSimplified;
+  BufferB?: PassConfigSimplified;
+  BufferC?: PassConfigSimplified;
+  BufferD?: PassConfigSimplified;
+}
+
+// =============================================================================
+// Internal Channel Representation (Normalized)
+// =============================================================================
+
+/**
+ * Normalized channel source for engine consumption.
+ * All channels are represented as one of these discriminated union variants.
+ */
+export type ChannelSource =
+  | { kind: 'none' }
+  | { kind: 'buffer'; buffer: PassName; current: boolean }
+  | { kind: 'texture'; name: string; cubemap: boolean }  // Internal texture ID (e.g., "tex0")
+  | { kind: 'keyboard' };
+
+/**
+ * Exactly 4 channels (iChannel0-3), matching Shadertoy's fixed channel count.
+ */
+export type Channels = [ChannelSource, ChannelSource, ChannelSource, ChannelSource];
+
+// =============================================================================
+// Texture Definitions
+// =============================================================================
+
+/**
+ * External 2D texture loaded from image file.
+ * Textures are deduplicated by (source, filter, wrap) tuple.
+ */
+export interface ShadertoyTexture2D {
+  name: string;  // Internal ID (e.g., "tex0", "tex1")
+  filename?: string;  // Original filename for display (e.g., "texture.png")
+  source: string;  // Path/URL to image file
+  filter: 'nearest' | 'linear';
+  wrap: 'clamp' | 'repeat';
+}
+
+// =============================================================================
+// Pass Definition (In-Memory)
+// =============================================================================
+
+/**
+ * A single shader pass in the rendering pipeline.
+ */
+export interface ShadertoyPass {
+  name: PassName;
+  glslSource: string;  // Full GLSL source code
+  channels: Channels;  // iChannel0..3
+}
+
+// =============================================================================
+// Project Metadata
+// =============================================================================
+
+/**
+ * Project metadata (title, author, description).
+ */
+export interface ShadertoyMeta {
+  title: string;
+  author: string | null;
+  description: string | null;
+}
+
+// =============================================================================
+// Main Project Definition (Normalized, Engine-Ready)
+// =============================================================================
+
+/**
+ * Complete in-memory representation of a Shadertoy project.
+ * Produced by loadProject() and consumed by ShadertoyEngine.
+ *
+ * Guarantees:
+ * - passes.Image always exists
+ * - All passes have exactly 4 channels (missing → kind: 'none')
+ * - Textures are deduplicated
+ * - All paths resolved and GLSL loaded
+ */
+export interface ShadertoyProject {
+  /**
+   * Project root directory path.
+   */
+  root: string;
+
+  /**
+   * Project metadata.
+   */
+  meta: ShadertoyMeta;
+
+  /**
+   * Layout mode for the shader viewer.
+   */
+  layout: 'fullscreen' | 'default' | 'split' | 'tabbed';
+
+  /**
+   * Whether to show playback controls (play/pause, reset).
+   */
+  controls: boolean;
+
+  /**
+   * Common GLSL code (prepended to all shaders), or null if none.
+   */
+  commonSource: string | null;
+
+  /**
+   * Pass definitions.
+   * Image is always present, BufferA-D are optional.
+   */
+  passes: {
+    Image: ShadertoyPass;
+    BufferA?: ShadertoyPass;
+    BufferB?: ShadertoyPass;
+    BufferC?: ShadertoyPass;
+    BufferD?: ShadertoyPass;
+  };
+
+  /**
+   * Deduplicated list of external textures.
+   * All ChannelSource with kind: 'texture2D' refer to names in this list.
+   */
+  textures: ShadertoyTexture2D[];
+}

package/src/styles/base.css

@@ -0,0 +1,29 @@
+/**
+ * Base Styles - Global resets and root element styling
+ */
+
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+html, body {
+  width: 100%;
+  height: 100%;
+  overflow: hidden;
+  font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+}
+
+body {
+  background: #f5f5f5;
+}
+
+#app {
+  width: 100%;
+  height: 100%;
+}
+
+canvas {
+  display: block;
+}

package/src/styles/embed.css

@@ -0,0 +1,14 @@
+/**
+ * Embed Styles - Scoped to shader container only
+ */
+
+.shader-demo {
+  position: relative;
+  width: 100%;
+}
+
+.shader-demo canvas {
+  display: block;
+  width: 100%;
+  height: 100%;
+}

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Shader Collection</title>
+    <style>
+      * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+      }
+      html, body {
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+      #app {
+        width: 100%;
+        height: 100%;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>