Live Preview Architecture for Code Playgrounds

The defining feature of a code playground is instant feedback. Users write code and see the result immediately, without a manual build step. This seemingly simple interaction hides significant architectural complexity. Updating the preview on every keystroke wastes resources and creates visual flicker. Waiting too long breaks the sense of immediacy. The preview system must compile TypeScript, inject HTML and CSS, reset the sandbox state, and render the output, all within a time budget that feels instantaneous. This article describes the live preview architecture in Kodepad, covering the reactive pipeline, debouncing strategies, incremental CSS updates, and the coordination between the editor, compiler, and sandbox.

The Reactive Pipeline

Kodepad's preview system is a unidirectional data pipeline. Editor changes flow through a series of transformation stages before reaching the sandbox iframe. Each stage has a clear responsibility and a defined interface:

// src/preview/pipeline.ts
interface PipelineStage<TInput, TOutput> {
  transform(input: TInput): Promise<TOutput> | TOutput;
}
 
interface EditorState {
  html: string;
  css: string;
  typescript: string;
  version: number;
}
 
interface CompiledOutput {
  html: string;
  css: string;
  javascript: string;
  errors: CompilationError[];
  version: number;
}
 
interface CompilationError {
  file: "html" | "css" | "typescript";
  message: string;
  line: number;
  column: number;
}
 
class PreviewPipeline {
  private debouncer: Debouncer;
  private compiler: TypeScriptCompiler;
  private sandbox: SandboxController;
  private currentVersion: number = 0;
 
  constructor(
    compiler: TypeScriptCompiler,
    sandbox: SandboxController,
    debounceMs: number = 300
  ) {
    this.compiler = compiler;
    this.sandbox = sandbox;
    this.debouncer = new Debouncer(debounceMs);
  }
 
  onEditorChange(state: EditorState): void {
    this.currentVersion = state.version;
 
    this.debouncer.run(async () => {
      // Skip if a newer version has arrived during debounce
      if (state.version < this.currentVersion) return;
 
      const compiled = await this.compile(state);
 
      // Skip if a newer version arrived during compilation
      if (compiled.version < this.currentVersion) return;
 
      if (compiled.errors.length === 0) {
        this.sandbox.execute(compiled);
      }
 
      this.emitDiagnostics(compiled.errors);
    });
  }
 
  private async compile(state: EditorState): Promise<CompiledOutput> {
    const jsResult = await this.compiler.compile(state.typescript);
    return {
      html: state.html,
      css: state.css,
      javascript: jsResult.code,
      errors: jsResult.diagnostics.map((d) => ({
        file: "typescript",
        message: d.messageText,
        line: d.line,
        column: d.column,
      })),
      version: state.version,
    };
  }
 
  private emitDiagnostics(errors: CompilationError[]): void {
    // Update editor markers, console panel, etc.
  }
}

The version number is the linchpin of this architecture. Every editor change increments the version, and every stage checks whether it is still processing the latest version before proceeding. This eliminates the "stale update" problem where a slow compilation finishes after the user has already made further changes, overwriting a more recent preview with an outdated one.

Debouncing Strategies

Not all edits deserve the same debounce delay. A single character insertion in the middle of a word is likely part of a longer edit sequence, while pressing Enter or a semicolon often signals the completion of a statement. Kodepad uses an adaptive debouncing strategy:

class AdaptiveDebouncer {
  private timer: ReturnType<typeof setTimeout> | null = null;
  private lastEditTime: number = 0;
  private baseDelay: number;
  private minDelay: number;
  private maxDelay: number;
 
  constructor(
    baseDelay: number = 300,
    minDelay: number = 100,
    maxDelay: number = 1000
  ) {
    this.baseDelay = baseDelay;
    this.minDelay = minDelay;
    this.maxDelay = maxDelay;
  }
 
  run(callback: () => void, editContext: EditContext): void {
    if (this.timer) clearTimeout(this.timer);
 
    const delay = this.computeDelay(editContext);
    this.timer = setTimeout(() => {
      this.timer = null;
      callback();
    }, delay);
 
    this.lastEditTime = Date.now();
  }
 
  private computeDelay(context: EditContext): number {
    // Immediate triggers: these edits usually mean "run now"
    if (context.triggeredByShortcut) return 0;
 
    // Fast triggers: structural changes that complete a thought
    if (context.insertedText === ";" || context.insertedText === "}") {
      return this.minDelay;
    }
 
    // Paste operations: user pasted a block of code, run soon
    if (context.isPaste) return this.minDelay;
 
    // Rapid typing: increase delay to batch edits
    const timeSinceLastEdit = Date.now() - this.lastEditTime;
    if (timeSinceLastEdit < 100) {
      return Math.min(this.maxDelay, this.baseDelay * 1.5);
    }
 
    return this.baseDelay;
  }
 
  cancel(): void {
    if (this.timer) {
      clearTimeout(this.timer);
      this.timer = null;
    }
  }
}
 
interface EditContext {
  insertedText: string;
  isPaste: boolean;
  triggeredByShortcut: boolean;
  changedFile: "html" | "css" | "typescript";
}

This adaptive approach means that when a user presses Ctrl+S or the explicit "Run" button, the preview updates instantly. When they are typing a variable name, the system waits for a pause. When they paste a code snippet, it runs quickly. The result feels responsive without wasteful re-execution.

Incremental CSS Updates

Full document replacement in the sandbox iframe is necessary when HTML or JavaScript changes, because the DOM and script execution context need to start fresh. But CSS changes do not require a full reset. Injecting updated styles into the existing document preserves the current DOM state, running animations, scroll positions, and form inputs:

class IncrementalCSSUpdater {
  private sandbox: HTMLIFrameElement;
  private styleElementId: string = "kodepad-injected-styles";
 
  constructor(sandbox: HTMLIFrameElement) {
    this.sandbox = sandbox;
  }
 
  updateCSS(css: string): boolean {
    try {
      const sandboxDoc = this.sandbox.contentDocument;
      if (!sandboxDoc) return false;
 
      let styleEl = sandboxDoc.getElementById(this.styleElementId);
      if (!styleEl) {
        styleEl = sandboxDoc.createElement("style");
        styleEl.id = this.styleElementId;
        sandboxDoc.head.appendChild(styleEl);
      }
 
      styleEl.textContent = css;
      return true;
    } catch {
      // Cross-origin restriction; fall back to full reload
      return false;
    }
  }
}
 
// In the pipeline, route CSS-only changes through the incremental path
class SmartPreviewUpdater {
  private cssUpdater: IncrementalCSSUpdater;
  private sandbox: SandboxController;
  private lastHtml: string = "";
  private lastJs: string = "";
 
  constructor(
    sandbox: SandboxController,
    cssUpdater: IncrementalCSSUpdater
  ) {
    this.sandbox = sandbox;
    this.cssUpdater = cssUpdater;
  }
 
  update(compiled: CompiledOutput): void {
    const htmlChanged = compiled.html !== this.lastHtml;
    const jsChanged = compiled.javascript !== this.lastJs;
 
    if (htmlChanged || jsChanged) {
      // Full reload required
      this.sandbox.execute(compiled);
      this.lastHtml = compiled.html;
      this.lastJs = compiled.javascript;
    } else {
      // CSS-only change: inject incrementally
      const success = this.cssUpdater.updateCSS(compiled.css);
      if (!success) {
        // Fallback to full reload
        this.sandbox.execute(compiled);
      }
    }
  }
}

This optimization makes CSS editing feel instantaneous. The user adjusts a color or margin and sees the result without the flash of a full document reload. It is one of those details that users do not consciously notice but that makes the experience feel polished.

Error Display and Recovery

When user code contains errors, the preview system must communicate them clearly without destroying the last valid preview. Kodepad maintains a "last known good" state and overlays error information rather than replacing the preview content:

interface PreviewState {
  status: "idle" | "compiling" | "running" | "error" | "success";
  lastGoodOutput: CompiledOutput | null;
  errors: CompilationError[];
}
 
class PreviewStateManager {
  private state: PreviewState = {
    status: "idle",
    lastGoodOutput: null,
    errors: [],
  };
  private listeners: Set<(state: PreviewState) => void> = new Set();
 
  onCompilationStart(): void {
    this.setState({ status: "compiling" });
  }
 
  onCompilationResult(output: CompiledOutput): void {
    if (output.errors.length > 0) {
      this.setState({
        status: "error",
        errors: output.errors,
        // Keep the last good output visible
      });
    } else {
      this.setState({
        status: "running",
        lastGoodOutput: output,
        errors: [],
      });
    }
  }
 
  onExecutionComplete(): void {
    this.setState({ status: "success" });
  }
 
  private setState(partial: Partial<PreviewState>): void {
    this.state = { ...this.state, ...partial };
    this.listeners.forEach((fn) => fn(this.state));
  }
 
  subscribe(listener: (state: PreviewState) => void): () => void {
    this.listeners.add(listener);
    return () => this.listeners.delete(listener);
  }
}

The "keep last good output" strategy means the user sees their working code in the preview while fixing a syntax error. The error message appears as an overlay or in the console panel, but the preview does not go blank. This is a small but meaningful UX improvement over playgrounds that show a white screen or a full-page error on every typo.

Performance Monitoring

To maintain the perception of instant feedback, we monitor the end-to-end latency of the preview pipeline and alert when it degrades:

class PreviewPerformanceMonitor {
  private measurements: number[] = [];
  private readonly windowSize: number = 50;
  private readonly warningThresholdMs: number = 500;
 
  recordLatency(editTimestamp: number, previewTimestamp: number): void {
    const latency = previewTimestamp - editTimestamp;
    this.measurements.push(latency);
 
    if (this.measurements.length > this.windowSize) {
      this.measurements.shift();
    }
 
    const p95 = this.percentile(95);
    if (p95 > this.warningThresholdMs) {
      console.warn(
        `Preview latency p95: ${p95.toFixed(0)}ms (threshold: ${this.warningThresholdMs}ms)`
      );
    }
  }
 
  private percentile(p: number): number {
    const sorted = [...this.measurements].sort((a, b) => a - b);
    const index = Math.ceil((p / 100) * sorted.length) - 1;
    return sorted[index];
  }
 
  getStats(): { p50: number; p95: number; p99: number } {
    return {
      p50: this.percentile(50),
      p95: this.percentile(95),
      p99: this.percentile(99),
    };
  }
}

In production, we track these metrics and use them to tune debounce delays and compilation strategies. If p95 latency exceeds 500ms, we investigate whether the bottleneck is TypeScript compilation, sandbox communication, or rendering.

Conclusion

A live preview system is the heart of any code playground. The architecture must balance immediacy against efficiency, handling the tension between "update on every keystroke" and "don't waste resources on intermediate states." Kodepad's approach, a versioned reactive pipeline with adaptive debouncing, incremental CSS updates, graceful error handling, and continuous performance monitoring, provides a preview experience that feels instant while remaining resource-efficient.

The key insight is that different types of changes deserve different update strategies. CSS changes can be injected incrementally. JavaScript changes require a full sandbox reset. Rapid keystrokes should be batched. Explicit run commands should execute immediately. By recognizing these distinctions and routing changes through appropriate paths, the preview system delivers the right trade-off between speed and correctness for every interaction.

Live Preview Architecture for Code Playgrounds

The Reactive Pipeline

Debouncing Strategies

Incremental CSS Updates

Error Display and Recovery

Performance Monitoring

Conclusion

Related Articles

Rapid Prototyping: From Idea to Demo in Minutes

Code Playgrounds in Developer Education

Developer Tools That Boost Productivity

Related Articles

Rapid Prototyping: From Idea to Demo in Minutes
October 9, 20258 min read

Code Playgrounds in Developer Education
October 7, 20258 min read

Developer Tools That Boost Productivity
October 5, 20257 min read