The best way to control Claude Code, Codex and more from any computer or phone
| 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 | }; |