Compiler Pipeline

Workshop's compiler transforms .ws source text into a RenderGraph through eight sequential stages. Each stage has exactly one input, one output, and one responsibility. Data flows in one direction only.

text
.ws Source
  ↓
1. Lexer ─────── raw text → classified line stream
  ↓
2. Parser ────── line stream → abstract syntax tree
  ↓
3. Normalizer ── AST → AST with all defaults resolved
  ↓
4. Policy Engine ── resolved AST → brand-constrained AST
  ↓
5. Timing Calculator ── AST → AST with frame-level timing
  ↓
6. Layout Solver ── AST → AST with pixel positions
  ↓
7. Physics Solver ── AST → AST with animation keyframes
  ↓
8. Compiler (Emitter) ── AST → RenderGraph JSON

Stage 1: Lexer

Converts raw UTF-8 text into a stream of classified lines. Handles encoding normalization (BOM, CRLF → LF), comment removal, indent measurement, and blank line filtering. This is the only stage that touches raw characters.

Stage 2: Parser

Builds an abstract syntax tree (AST) from the token stream. Identifies Film blocks, Scene blocks, element declarations, modifiers, sequencing keywords, beats, and define blocks. Produces structured diagnostics for syntax errors with line and column numbers.

Stage 3: Normalizer

Resolves defaults and expands shorthand. Loads the mood profile and fills in every parameter not explicitly set — size, color, entrance, exit, timing, spacing. After normalization, every element has a complete set of concrete values.

Stage 4: Policy Engine

Applies ThemePack overrides and validates brand constraints. If a ThemePack is active, its palette and typography replace the mood's defaults. Also validates org-level constraints.

Stage 5: Timing Calculator

Computes hold durations from text content. Counts syllables, estimates reading speed adjusted by tempo, and calculates how long each element stays on screen. Explicit durations override calculated values. All timing is snapped to exact frame boundaries.

Stage 6: Layout Solver

Positions elements within the frame. Handles grid layouts, split layouts, and default centering. Calculates bounding boxes, margins, gutters, and safe zones. Position values resolve to specific pixel coordinates.

Stage 7: Physics Solver

Calculates spring dynamics for entrance and exit animations. Each mood defines spring parameters (mass, tension, friction, damping). The solver converts these into keyframe arrays that describe the exact motion path. This is why entrances feel physically grounded rather than mathematically eased.

Stage 8: Compiler (Emitter)

Assembles the final RenderGraph JSON from all resolved values — metadata, timeline with scenes and elements, animation keyframes, asset references, and global settings.

Determinism Guarantee

Every stage is pure — no randomness, no external state, no time-dependent behavior. The same .ws input produces byte-identical RenderGraph output regardless of when or where it compiles.

Diagnostics

Each stage can emit diagnostics: errors (compilation stops), warnings (compilation continues), and info (suggestions). These include line number, column, and human-readable message.

Next Steps