The best way to control Claude Code, Codex and more from any computer or phone

main
ts 432 lines 13.1 KB
Raw
1 /**
2 * The intro, resolved: `intro/build.ts` turns the authored steps
3 * (`intro/steps.ts`) into this JSON (tokens highlighted, marks and type
4 * errors located), and the Remotion `Intro` composition renders it. Every
5 * step is one press of → in the presenter.
6 */
7
8 export interface Token {
9 text: string;
10 color: string;
11 bold?: boolean;
12 }
13
14 export type Tone = "construct" | "runtime" | "good" | "bad" | "neutral";
15
16 /** A hand-drawn mark over a range of code (0-based line/column). */
17 export interface Mark {
18 kind: "circle" | "underline" | "strike" | "box" | "highlight";
19 line: number;
20 col: number;
21 len: number;
22 /** For multi-line boxes: the last line covered. */
23 toLine?: number;
24 label?: string;
25 side?: "right" | "left" | "above" | "below";
26 tone?: Tone;
27 /** Set the label further away, with a hand-drawn arrow pointing at the mark. */
28 arrow?: boolean;
29 }
30
31 /** A span of text in a code block. */
32 export interface Span {
33 line: number;
34 col: number;
35 len: number;
36 }
37
38 /** A line drawn from text in one pane to text in the pane beside it. */
39 export interface CodeLink {
40 from: Span;
41 to: Span;
42 tone?: Tone;
43 }
44
45 export interface CodeError {
46 line: number;
47 col: number;
48 len: number;
49 code: string;
50 message: string[];
51 /** Shown under the code, like an editor tooltip, instead of in the right column. */
52 below?: boolean;
53 }
54
55 export interface PanelItem {
56 title: string;
57 body?: string;
58 mono?: string;
59 tone?: Tone;
60 /** 0–1: draws a proportional bar (illustrative sizes). */
61 bar?: number;
62 }
63
64 /** The Worker's bundle beside the code: its size and every client in it. */
65 export interface BundlePanel {
66 label: string;
67 /** Kilobytes. */
68 size: number;
69 /** Every client in the bundle. */
70 items: string[];
71 /** The clients the code actually calls. */
72 used?: string[];
73 /** Hand-written note under the wall; `{extra}` is the number of unused clients. */
74 note?: string;
75 }
76
77 /** One entry of an Effect's `Req`: open until something provides it. */
78 export interface ReqItem {
79 /** The requirement's type name, as the compiler prints it. */
80 name: string;
81 state?: "open" | "met" | "bad";
82 /** Short text beside it: what it's for, or what satisfies it. `\n` breaks lines. */
83 note?: string;
84 }
85
86 /** The requirements of the code on screen, listed beside it. */
87 export interface ReqPanel {
88 label: string;
89 items: ReqItem[];
90 /** Other Effects' Req, each under its own small heading below `items`. */
91 parts?: { label: string; items: ReqItem[] }[];
92 }
93
94 /** Construction creates the resources once; then requests arrive, over and over. */
95 export interface PhaseTimeline {
96 /** Rows, top to bottom; the last is the function that runs per request. */
97 resources: { title: string; color: string }[];
98 requests: number;
99 }
100
101 /** A value threaded down a call chain, drawn beside the code. */
102 export interface Drill {
103 /** Small heading above the chain. */
104 label: string;
105 /** The value being passed down: highlighted and threaded wherever it appears. */
106 name: string;
107 /** One call per line, outermost first; leading spaces set the depth. */
108 lines: string[];
109 /** Hand-written note under the chain. */
110 note?: string;
111 }
112
113 /** A small architecture drawing beside the code: it evolves with the code. */
114 export interface MiniNode {
115 id: string;
116 title: string;
117 color: string;
118 /** Centre, in pixels inside the drawing area. */
119 x: number;
120 y: number;
121 /** Config lines under the node; lines new in this step appear in green. */
122 notes?: string[];
123 /** A hypothetical node: dashed outline, e.g. "what would this even be?" */
124 ghost?: boolean;
125 }
126
127 export interface MiniGraph {
128 nodes: MiniNode[];
129 /** `label` sits on the arrow: the permission that connection grants. */
130 edges: { from: string; to: string; tone?: Tone; label?: string }[];
131 /** Short facts shown under the drawing (permissions, env vars, errors). */
132 cards?: { text: string; tone?: Tone }[];
133 /** Requests arriving at a node from outside, drawn as a looping stream. */
134 incoming?: { to: string; label: string; tone?: Tone };
135 /** A dashed frame around the whole drawing, e.g. "everything construction builds". */
136 frame?: { label: string; tone?: Tone };
137 /** Labelled boxes around groups of nodes, e.g. one per stage. */
138 groups?: { label: string; nodes: string[]; tone?: Tone }[];
139 /** Hand-written labels at a position in the drawing. */
140 labels?: {
141 /** `\n` breaks lines. */
142 text: string;
143 x: number;
144 y: number;
145 tone?: Tone;
146 /** Hand-drawn arrows from the label to what it's about. */
147 arrows?: { from: [number, number]; to: [number, number] }[];
148 }[];
149 }
150
151 export interface CodeStep {
152 kind: "code";
153 title: string;
154 notes: string;
155 /** A row of options under the code, with the current one lit (as on roll slides). */
156 reel?: { items: string[]; at: number };
157 /** What the new lines add, in pyramid terms: tints them and labels them. */
158 layer?: "resource" | "binding" | "api";
159 /** Consecutive code steps in the same group morph into each other. */
160 group: string;
161 /** File name on the editor tab, or undefined for a pseudo-code block. */
162 file?: string;
163 /** The imagined language: labelled as such on screen. */
164 pseudo?: boolean;
165 lines: Token[][];
166 fontSize: number;
167 tints: { from: number; to: number; tone: Tone }[];
168 focus?: { from: number; to: number };
169 marks: Mark[];
170 error?: CodeError;
171 panel?: { title: string; items: PanelItem[] };
172 diagram?: MiniGraph;
173 /** The two phases over time, drawn where the diagram goes. */
174 timeline?: PhaseTimeline;
175 drill?: Drill;
176 req?: ReqPanel;
177 bundle?: BundlePanel;
178 /** A second file shown side by side, on the right. */
179 beside?: CodeStep;
180 /** Lines from text in this pane to text in `beside`: how the two are coupled. */
181 links?: CodeLink[];
182 /** A file generated from this one, drawn under it with a labelled arrow, and its links to `beside`. */
183 under?: { step: CodeStep; label: string; links?: CodeLink[] };
184 /** Arcs from text in the code to what it becomes in `diagram`: a node, or an edge's label. */
185 diagramLinks?: { from: Span; to: { node: string } | { edge: [string, string] }; tone?: Tone }[];
186 /** A big hand-drawn red X across the code: this approach is wrong. */
187 cross?: boolean;
188 /** A hand-written aside in the bottom-right corner. */
189 aside?: {
190 text: string;
191 tone?: Tone;
192 /** A photo that pops in above the text: a path under `intro/assets/`. */
193 image?: string;
194 /** Bottom-left, beside the photo, for slides whose right side is full. */
195 at?: "left" | "right";
196 };
197 /** No change highlight or spotlight on this step. */
198 quiet?: boolean;
199 /**
200 * Per line: added (+, green) or removed (-, red) since this file was last on
201 * screen. Removed lines are kept in `lines` so they can be shown. `start`/`end`
202 * mark the part of a rewritten line that actually changed.
203 */
204 diff?: ({ kind: "add" | "del"; start?: number; end?: number } | null)[];
205 frames: number;
206 }
207
208 export interface SlideStep {
209 kind: "slide";
210 title: string;
211 notes: string;
212 layout: "title" | "section";
213 eyebrow?: string;
214 heading: string;
215 subtitle?: string;
216 footer?: string;
217 frames: number;
218 }
219
220 export interface BoardStep {
221 kind: "board";
222 title: string;
223 notes: string;
224 board: string;
225 stage: number;
226 frames: number;
227 }
228
229 /** A terminal pane: the command and the output shown so far (ANSI colours allowed). */
230 export interface TerminalStep {
231 kind: "terminal";
232 title: string;
233 notes: string;
234 group: string;
235 /** Tab labels across the top; the active one is highlighted. */
236 tabs?: string[];
237 active?: number;
238 lines: Token[][];
239 /** Lines that are new since the previous step (they fade in). */
240 fresh: number;
241 /** A live deploy under the lines: each row moves pending → in progress → done on its own schedule. */
242 progress?: {
243 rows: { name: string; type?: string; binding?: boolean; from: number; to: number }[];
244 /** Lines that appear once every row is done, at frame `at`. */
245 done: Token[][];
246 at: number;
247 };
248 frames: number;
249 }
250
251 /** A browser window showing one screenshot. */
252 export interface BrowserStep {
253 kind: "browser";
254 title: string;
255 notes: string;
256 url: string;
257 image: string;
258 frames: number;
259 }
260
261 /** The parts of the path from an edit to production (the loop deck's map). */
262 export type LoopPart =
263 | "edit"
264 | "types"
265 | "local"
266 | "live"
267 | "push"
268 | "pr"
269 | "prTest"
270 | "comment"
271 | "merge"
272 | "staging"
273 | "stagingTest"
274 | "prod"
275 | "feedback";
276
277 /** The whole loop, drawn full screen, with some parts lit. */
278 export interface LoopStep {
279 kind: "loop";
280 title: string;
281 notes: string;
282 /** Parts drawn so far, for building the map up; omit to draw everything. */
283 show?: LoopPart[];
284 lit?: LoopPart[];
285 focus?: LoopPart[];
286 frames: number;
287 }
288
289 /** A pull request page: its checks, and comments (e.g. the preview link). */
290 export interface CommentStep {
291 kind: "comment";
292 title: string;
293 notes: string;
294 pr: { number: number; title: string; branch: string };
295 checks: { name: string; state: "pending" | "passed" | "failed"; detail?: string }[];
296 comments: { author: string; bot?: boolean; lines: string[] }[];
297 frames: number;
298 }
299
300 /** One layer of an application, drawn as a band of the pyramid. */
301 export interface PyramidLayer {
302 id: string;
303 title: string;
304 detail: string;
305 color: string;
306 }
307
308 /** An application's layers as a pyramid, bottom first, with notes beside them. */
309 export interface PyramidStep {
310 kind: "pyramid";
311 title: string;
312 notes: string;
313 /** Layers drawn so far, bottom first. */
314 layers: PyramidLayer[];
315 /** Layers at full strength; the rest are dimmed. Omit to light everything. */
316 lit?: string[];
317 /** Hand-written notes to the right of a layer. */
318 side?: {
319 layer: string;
320 text: string;
321 tone?: Tone;
322 /** Code set in a column right of the pyramid, instead of a hand-written note. */
323 code?: boolean;
324 /** The code, highlighted (filled in by the build). */
325 tokens?: Token[][];
326 }[];
327 /** A column beside the pyramid, spanning every layer (observability). */
328 pillar?: { title: string; lines: string[]; color: string };
329 /** A bracket over every layer, with a label. */
330 brace?: { text: string; sub?: string };
331 /** A dashed line under a layer, splitting the stack into two programs. */
332 cut?: { under: string; above: string; below: string };
333 /** One feature, cut vertically through every layer: what it needs in each. */
334 slice?: { label: string; items: Record<string, string> };
335 /** Several features, each cut vertically through the layers, side by side. */
336 slices?: { label: string; items: Record<string, string> }[];
337 /** The stack rebuilt from modules: bricks laid in the pyramid's rows, bottom first. */
338 bricks?: {
339 row: number;
340 title: string;
341 detail: string;
342 color: string;
343 /** Fixed place in the row (0-based) out of `of`, so a row doesn't reflow as bricks arrive. */
344 col?: number;
345 of?: number;
346 }[];
347 frames: number;
348 }
349
350 /**
351 * Code that stays put while a few spans of it roll to the next value, like a
352 * slot machine: each keypress swaps a provider, and nothing else moves.
353 */
354 export interface RollStep {
355 kind: "roll";
356 title: string;
357 notes: string;
358 /** Consecutive roll steps of one group animate from each other. */
359 group: string;
360 file?: string;
361 fontSize: number;
362 lines: Token[][];
363 /** The spans that change between the steps of a group, by index. */
364 slots: { line: number; start: number; end: number; active?: boolean }[];
365 /** What the current code generates at deploy, beside it. */
366 beside?: { file: string; lines: Token[][] };
367 /** Every option in the roll, with the current one lit. */
368 reel?: { items: string[]; at: number };
369 /** Spin one slot through these values, slot-machine style, before it lands on its own. */
370 spin?: { slot: number; through: string[]; reelFrom: number };
371 frames: number;
372 }
373
374 /** A full-screen architecture drawing: boxes, and arrows between them. */
375 export interface ArchStep {
376 kind: "arch";
377 title: string;
378 notes: string;
379 nodes: {
380 id: string;
381 title: string;
382 sub?: string;
383 color: string;
384 x: number;
385 y: number;
386 w?: number;
387 h?: number;
388 }[];
389 /** Row labels down the left edge, so the drawing reads top to bottom. */
390 lanes?: { label: string; y: number; color: string }[];
391 /** `dashed` edges are telemetry, not requests. */
392 /** `dashed` edges are telemetry; `elbow` edges leave sideways, then turn down. */
393 edges: { from: string; to: string; label?: string; dashed?: boolean; elbow?: boolean }[];
394 frames: number;
395 }
396
397 /** A mocked observability dashboard (hypothetical UI), optionally with its monitor firing. */
398 export interface DashStep {
399 kind: "dash";
400 title: string;
401 notes: string;
402 /** Show the monitor alert firing, and the error spike that triggered it. */
403 alert?: boolean;
404 frames: number;
405 }
406
407 export type IntroStep =
408 | DashStep
409 | ArchStep
410 | RollStep
411 | CodeStep
412 | SlideStep
413 | BoardStep
414 | TerminalStep
415 | BrowserStep
416 | LoopStep
417 | CommentStep
418 | PyramidStep;
419
420 export interface IntroJson {
421 steps: IntroStep[];
422 }
423
424 /** Frame ranges of each step, back to back. */
425 export const introTimeline = (steps: IntroStep[]) => {
426 let from = 0;
427 return steps.map((step) => {
428 const range = { from, to: from + step.frames };
429 from = range.to;
430 return range;
431 });
432 };