0
# Code Execution System
1

2
Types for executing and displaying code within presentations, including context interfaces and output formatting options.
3

4
## Capabilities
5

6
### Code Runner Interface
7

8
Core interface for executing code within Slidev presentations.
9

10
```typescript { .api }
11
/**
12
 * Code runner function that executes code and returns outputs
13
 * @param code - The code string to execute
14
 * @param ctx - Context providing options and utilities
15
 * @returns Promise resolving to code outputs
16
 */
17
type CodeRunner = (code: string, ctx: CodeRunnerContext) => Awaitable<CodeRunnerOutputs>;
18

19
type CodeRunnerProviders = Record<string, CodeRunner>;
20
```
21

22
### Code Runner Context
23

24
Context interface providing options and utilities to code runners.
25

26
```typescript { .api }
27
/**
28
 * Context interface for code runners
29
 */
30
interface CodeRunnerContext {
31
  /** Options passed to runner via the runnerOptions prop */
32
  options: Record<string, unknown>;
33
  /** Highlight code with shiki */
34
  highlight: (code: string, lang: string, options?: Partial<CodeToHastOptions>) => string;
35
  /** Use (other) code runner to run code */
36
  run: (code: string, lang: string) => Promise<CodeRunnerOutputs>;
37
}
38
```
39

40
### Code Runner Output Types
41

42
Various output types that code runners can return.
43

44
```typescript { .api }
45
/**
46
 * HTML output for rendering HTML content
47
 * Note: Slidev does NOT sanitize HTML - ensure it's from trusted sources
48
 */
49
interface CodeRunnerOutputHtml {
50
  html: string;
51
}
52

53
/**
54
 * DOM element output for rendering DOM elements
55
 */
56
interface CodeRunnerOutputDom {
57
  element: HTMLElement;
58
}
59

60
/**
61
 * Error output for displaying error messages
62
 */
63
interface CodeRunnerOutputError {
64
  error: string;
65
}
66

67
/**
68
 * Text output for displaying formatted text
69
 */
70
interface CodeRunnerOutputText {
71
  text: string;
72
  class?: string;
73
  highlightLang?: string;
74
}
75

76
/**
77
 * Array of text outputs
78
 */
79
type CodeRunnerOutputTextArray = CodeRunnerOutputText[];
80

81
/**
82
 * Union type of all possible output types
83
 */
84
type CodeRunnerOutput = 
85
  | CodeRunnerOutputHtml 
86
  | CodeRunnerOutputError 
87
  | CodeRunnerOutputText 
88
  | CodeRunnerOutputTextArray 
89
  | CodeRunnerOutputDom;
90

91
/**
92
 * Code runner outputs with reactive support
93
 */
94
type CodeRunnerOutputs = MaybeRefOrGetter<Arrayable<CodeRunnerOutput>>;
95
```
96

97
## Usage Examples
98

99
**Basic Code Runner Implementation:**
100

101
```typescript
102
import type { CodeRunner, CodeRunnerContext } from "@slidev/types";
103

104
const pythonRunner: CodeRunner = async (code: string, ctx: CodeRunnerContext) => {
105
  try {
106
    // Execute Python code (pseudo-implementation)
107
    const result = await executePython(code, ctx.options);
108
    
109
    return {
110
      text: result.stdout,
111
      class: "text-green-600",
112
      highlightLang: "python"
113
    };
114
  } catch (error) {
115
    return {
116
      error: `Python execution failed: ${error.message}`
117
    };
118
  }
119
};
120

121
// Register the runner
122
const runners = {
123
  python: pythonRunner,
124
  py: pythonRunner
125
};
126
```
127

128
**HTML Output Runner:**
129

130
```typescript
131
const htmlRunner: CodeRunner = async (code: string, ctx: CodeRunnerContext) => {
132
  // Validate and sanitize HTML if needed
133
  const safeHtml = sanitizeHtml(code);
134
  
135
  return {
136
    html: `<div class="demo-output">${safeHtml}</div>`
137
  };
138
};
139
```
140

141
**DOM Element Runner:**
142

143
```typescript
144
const canvasRunner: CodeRunner = async (code: string, ctx: CodeRunnerContext) => {
145
  const canvas = document.createElement('canvas');
146
  canvas.width = 400;
147
  canvas.height = 300;
148
  
149
  // Execute drawing code on canvas
150
  const drawingFunction = new Function('canvas', 'ctx', code);
151
  const canvasCtx = canvas.getContext('2d');
152
  drawingFunction(canvas, canvasCtx);
153
  
154
  return {
155
    element: canvas
156
  };
157
};
158
```
159

160
**Multi-output Runner:**
161

162
```typescript
163
const testRunner: CodeRunner = async (code: string, ctx: CodeRunnerContext) => {
164
  const results = await runTests(code);
165
  
166
  return results.map(result => ({
167
    text: `${result.name}: ${result.status}`,
168
    class: result.passed ? "text-green-600" : "text-red-600"
169
  }));
170
};
171
```
172

173
**Using Context Features:**
174

175
```typescript
176
const enhancedRunner: CodeRunner = async (code: string, ctx: CodeRunnerContext) => {
177
  // Use highlighting capability
178
  const highlightedCode = ctx.highlight(code, 'javascript');
179
  
180
  // Use nested execution
181
  const dependencies = await ctx.run('npm list', 'bash');
182
  
183
  // Access runner options
184
  const timeout = ctx.options.timeout || 5000;
185
  
186
  try {
187
    const result = await executeWithTimeout(code, timeout);
188
    return {
189
      html: `
190
        <div class="execution-result">
191
          <h4>Code:</h4>
192
          ${highlightedCode}
193
          <h4>Result:</h4>
194
          <pre>${result}</pre>
195
        </div>
196
      `
197
    };
198
  } catch (error) {
199
    return {
200
      error: `Execution timeout after ${timeout}ms`
201
    };
202
  }
203
};
204
```