WGSL: A Primer

Note

This repository is a modernized, refined, and expanded fork of the archived original 2023 Tour of WGSL.

This repository contains the source code for the WGSL: A Primer (WebGPU Shading Language) website. The site is generated using ProperDocs (an actively maintained static site generator), and the interactive visualizers are powered by TypeScript and compiled/bundled using Vite.

The purpose of this project is to provide a highly interactive introduction to WGSL through examples that can be modified and run directly by the user in their browser.

Key Features

WGSL: A Primer 2.0 comes packed with powerful, premium interactive editor and workspace upgrades:

• Integrated Docked Status Bar: A premium compilation and workspace control bar attached directly to the base of the code editor.
• On-Demand & Live Execution: Run/Compile on demand via the Run button, or toggle Live Updates for automatic, debounced compilation as you type.
• Responsive Workspace Layouts: Choose between Minimize, Split, and Maximize editor modes using segmented layout button groups to optimize your reading and rendering space.
• Theme-Adaptive High-Legibility Code Themes: Automatic, observer-driven toggling of the CodeMirror 6 theme (editor background, syntax highlighting, and selection matching) when switching the main site between light and dark modes.
• Dismissible Definition Tooltips: Position your text cursor over attributes (e.g., @builtin), types, or functions (e.g., sin) and press ctrl-o to trigger context-aware documentation. Easily dismiss tooltips using Escape, clicking away, or focusing out.
• Canvas Animation Play/Pause: Hover or tap the rendering canvas to overlay a glassmorphic button to play or pause the shader animation loop, saving system resources.
• Keyboard Shortcuts Bypass: Prevents accidental page navigation from standard keyboard bindings when focusing inside the code editor or playground workspace.

Development

Prerequisites

To build and run the project locally, you will need:

1. Python (version 3.13 or newer)
2. Node.js (version 20 or newer, along with npm)

Quickstart

1. Clone the Repository:

   git clone https://github.com/webmaven/tour-of-wgsl.git
   cd tour-of-wgsl

2. Set Up Python Virtual Environment: Initialize a Python virtual environment and install the required documentation packages:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt

3. Install Node Dependencies:

   npm install

4. Run the Development Server: Start both the TypeScript Vite compiler/bundler and the ProperDocs development server with hot-reloading:

   npm run serve

   This should start the dev server locally. Open your browser and navigate to http://127.0.0.1:8000/wgsl-primer/.

5. Linting & Formatting:

   • Verify TypeScript type safety: npx tsc --noEmit
   • Lint the TypeScript files: npm run lint
   • Format the entire codebase: npm run format

---

Directory Structure

• docs/: Contains the Markdown files for the tutorial sections and lessons, plus images and compiled JS/CSS assets.

  [!NOTE] Do NOT manually modify files inside docs/assets/ directly, as they are generated by the Vite build process.

• assets/ts/: Contains the TypeScript source code for the interactive WGSL visualizers and the site's frontend logic.
• hooks/: Contains custom Python hooks used by ProperDocs (e.g., wgsl_tour.py) to process pages or customize layout.
• properdocs.yml: The main ProperDocs configuration file.
• vite.config.ts: Configuration file for the Vite asset compiler/bundler.
• .github/workflows/: Contains GitHub Actions workflows for CI validation and automatic deployment.

---

Shaders & Frontmatter

Each lesson page is configured in standard Markdown. If a page features an interactive shader visualizer playground, it will specify its associated shader source path in the page's YAML frontmatter:

---
title: 'Uniform Variables'
shader: ./var-uniform.wgsl
---

When a user visits the page, the shader is automatically fetched, loaded into the text box (powered by CodeMirror 6), and made editable and executable in real-time.

Math Delimiters

To avoid collision with code parameters or shell variables containing dollar signs ($), LaTeX math rendering is configured to strictly use \( and \) for inline equations, and \[ and \] for display equations:

• Inline: \( E = mc^2 \)
• Display: \[ \sum_{i=1}^{n} i = \frac{n(n+1)}{2} \]

---

Getting WebGPU in your Browser

WebGPU is supported by default in modern web browsers (released after mid-2023). Ensure you are running an up-to-date version of a compatible browser:

• Chrome / Edge (v113 or newer)
• Firefox (v130 or newer)
• Safari (v18 or newer on macOS)

No special flags or nightly builds are required. If the interactive visualizers do not render, check that your device's GPU drivers are up-to-date and that hardware acceleration is enabled in your browser settings.

---

Licensing & Lineage

WGSL: A Primer uses a multi-tiered license structure designed to clearly distinguish original upstream assets from modern improvements:

1. Curriculum Content & Prose (CC-BY 4.0):
   • All lessons, guides, explanations, diagrams, mathematical formulas, and tutorial text added or modified in 2026 are Copyright © 2026 Michael R. Bernstein and licensed under the Creative Commons Attribution 4.0 International (CC-BY 4.0) license. See LICENSE-TEXT for full license text.
2. Software & Infrastructure (Apache 2.0):
   • All site configurations, python build hooks, build utilities, newly created interactive TypeScript visualizer modules, and custom stylesheets added or modified in 2026 are Copyright © 2026 Michael R. Bernstein and licensed under the Apache License 2.0. See LICENSE-CODE for full license text.
3. Upstream Code & Structure (BSD 3-Clause):
   • The original 2023 files, curriculum structures, and core assets are Copyright © 2023 and licensed under the BSD 3-Clause License (preserved in the root LICENSE-UPSTREAM file).
   • Where files combine both upstream and modern work (derivative work), they are dual-licensed: modern 2026 contributions are licensed under Apache 2.0 (for code) or CC-BY 4.0 (for prose), while original 2023 BSD 3-Clause copyrights are preserved intact. Newly created or fully rewritten files are governed solely by the 2026 license terms.