sailfork / t3code-github / .repos/ alchemy-effect/ demos/ effect-prezzy/ shared/ intro.ts

/**
 * The intro, resolved: `intro/build.ts` turns the authored steps
 * (`intro/steps.ts`) into this JSON (tokens highlighted, marks and type
 * errors located), and the Remotion `Intro` composition renders it. Every
 * step is one press of → in the presenter.
 */

export interface Token {
  text: string;
  color: string;
  bold?: boolean;
}

export type Tone = "construct" | "runtime" | "good" | "bad" | "neutral";

/** A hand-drawn mark over a range of code (0-based line/column). */
export interface Mark {
  kind: "circle" | "underline" | "strike" | "box" | "highlight";
  line: number;
  col: number;
  len: number;
  /** For multi-line boxes: the last line covered. */
  toLine?: number;
  label?: string;
  side?: "right" | "left" | "above" | "below";
  tone?: Tone;
  /** Set the label further away, with a hand-drawn arrow pointing at the mark. */
  arrow?: boolean;
}

/** A span of text in a code block. */
export interface Span {
  line: number;
  col: number;
  len: number;
}

/** A line drawn from text in one pane to text in the pane beside it. */
export interface CodeLink {
  from: Span;
  to: Span;
  tone?: Tone;
}

export interface CodeError {
  line: number;
  col: number;
  len: number;
  code: string;
  message: string[];
  /** Shown under the code, like an editor tooltip, instead of in the right column. */
  below?: boolean;
}

export interface PanelItem {
  title: string;
  body?: string;
  mono?: string;
  tone?: Tone;
  /** 0–1: draws a proportional bar (illustrative sizes). */
  bar?: number;
}

/** The Worker's bundle beside the code: its size and every client in it. */
export interface BundlePanel {
  label: string;
  /** Kilobytes. */
  size: number;
  /** Every client in the bundle. */
  items: string[];
  /** The clients the code actually calls. */
  used?: string[];
  /** Hand-written note under the wall; `{extra}` is the number of unused clients. */
  note?: string;
}

/** One entry of an Effect's `Req`: open until something provides it. */
export interface ReqItem {
  /** The requirement's type name, as the compiler prints it. */
  name: string;
  state?: "open" | "met" | "bad";
  /** Short text beside it: what it's for, or what satisfies it. `\n` breaks lines. */
  note?: string;
}

/** The requirements of the code on screen, listed beside it. */
export interface ReqPanel {
  label: string;
  items: ReqItem[];
  /** Other Effects' Req, each under its own small heading below `items`. */
  parts?: { label: string; items: ReqItem[] }[];
}

/** Construction creates the resources once; then requests arrive, over and over. */
export interface PhaseTimeline {
  /** Rows, top to bottom; the last is the function that runs per request. */
  resources: { title: string; color: string }[];
  requests: number;
}

/** A value threaded down a call chain, drawn beside the code. */
export interface Drill {
  /** Small heading above the chain. */
  label: string;
  /** The value being passed down: highlighted and threaded wherever it appears. */
  name: string;
  /** One call per line, outermost first; leading spaces set the depth. */
  lines: string[];
  /** Hand-written note under the chain. */
  note?: string;
}

/** A small architecture drawing beside the code: it evolves with the code. */
export interface MiniNode {
  id: string;
  title: string;
  color: string;
  /** Centre, in pixels inside the drawing area. */
  x: number;
  y: number;
  /** Config lines under the node; lines new in this step appear in green. */
  notes?: string[];
  /** A hypothetical node: dashed outline, e.g. "what would this even be?" */
  ghost?: boolean;
}

export interface MiniGraph {
  nodes: MiniNode[];
  /** `label` sits on the arrow: the permission that connection grants. */
  edges: { from: string; to: string; tone?: Tone; label?: string }[];
  /** Short facts shown under the drawing (permissions, env vars, errors). */
  cards?: { text: string; tone?: Tone }[];
  /** Requests arriving at a node from outside, drawn as a looping stream. */
  incoming?: { to: string; label: string; tone?: Tone };
  /** A dashed frame around the whole drawing, e.g. "everything construction builds". */
  frame?: { label: string; tone?: Tone };
  /** Labelled boxes around groups of nodes, e.g. one per stage. */
  groups?: { label: string; nodes: string[]; tone?: Tone }[];
  /** Hand-written labels at a position in the drawing. */
  labels?: {
    /** `\n` breaks lines. */
    text: string;
    x: number;
    y: number;
    tone?: Tone;
    /** Hand-drawn arrows from the label to what it's about. */
    arrows?: { from: [number, number]; to: [number, number] }[];
  }[];
}

export interface CodeStep {
  kind: "code";
  title: string;
  notes: string;
  /** A row of options under the code, with the current one lit (as on roll slides). */
  reel?: { items: string[]; at: number };
  /** What the new lines add, in pyramid terms: tints them and labels them. */
  layer?: "resource" | "binding" | "api";
  /** Consecutive code steps in the same group morph into each other. */
  group: string;
  /** File name on the editor tab, or undefined for a pseudo-code block. */
  file?: string;
  /** The imagined language: labelled as such on screen. */
  pseudo?: boolean;
  lines: Token[][];
  fontSize: number;
  tints: { from: number; to: number; tone: Tone }[];
  focus?: { from: number; to: number };
  marks: Mark[];
  error?: CodeError;
  panel?: { title: string; items: PanelItem[] };
  diagram?: MiniGraph;
  /** The two phases over time, drawn where the diagram goes. */
  timeline?: PhaseTimeline;
  drill?: Drill;
  req?: ReqPanel;
  bundle?: BundlePanel;
  /** A second file shown side by side, on the right. */
  beside?: CodeStep;
  /** Lines from text in this pane to text in `beside`: how the two are coupled. */
  links?: CodeLink[];
  /** A file generated from this one, drawn under it with a labelled arrow, and its links to `beside`. */
  under?: { step: CodeStep; label: string; links?: CodeLink[] };
  /** Arcs from text in the code to what it becomes in `diagram`: a node, or an edge's label. */
  diagramLinks?: { from: Span; to: { node: string } | { edge: [string, string] }; tone?: Tone }[];
  /** A big hand-drawn red X across the code: this approach is wrong. */
  cross?: boolean;
  /** A hand-written aside in the bottom-right corner. */
  aside?: {
    text: string;
    tone?: Tone;
    /** A photo that pops in above the text: a path under `intro/assets/`. */
    image?: string;
    /** Bottom-left, beside the photo, for slides whose right side is full. */
    at?: "left" | "right";
  };
  /** No change highlight or spotlight on this step. */
  quiet?: boolean;
  /**
   * Per line: added (+, green) or removed (-, red) since this file was last on
   * screen. Removed lines are kept in `lines` so they can be shown. `start`/`end`
   * mark the part of a rewritten line that actually changed.
   */
  diff?: ({ kind: "add" | "del"; start?: number; end?: number } | null)[];
  frames: number;
}

export interface SlideStep {
  kind: "slide";
  title: string;
  notes: string;
  layout: "title" | "section";
  eyebrow?: string;
  heading: string;
  subtitle?: string;
  footer?: string;
  frames: number;
}

export interface BoardStep {
  kind: "board";
  title: string;
  notes: string;
  board: string;
  stage: number;
  frames: number;
}

/** A terminal pane: the command and the output shown so far (ANSI colours allowed). */
export interface TerminalStep {
  kind: "terminal";
  title: string;
  notes: string;
  group: string;
  /** Tab labels across the top; the active one is highlighted. */
  tabs?: string[];
  active?: number;
  lines: Token[][];
  /** Lines that are new since the previous step (they fade in). */
  fresh: number;
  /** A live deploy under the lines: each row moves pending → in progress → done on its own schedule. */
  progress?: {
    rows: { name: string; type?: string; binding?: boolean; from: number; to: number }[];
    /** Lines that appear once every row is done, at frame `at`. */
    done: Token[][];
    at: number;
  };
  frames: number;
}

/** A browser window showing one screenshot. */
export interface BrowserStep {
  kind: "browser";
  title: string;
  notes: string;
  url: string;
  image: string;
  frames: number;
}

/** The parts of the path from an edit to production (the loop deck's map). */
export type LoopPart =
  | "edit"
  | "types"
  | "local"
  | "live"
  | "push"
  | "pr"
  | "prTest"
  | "comment"
  | "merge"
  | "staging"
  | "stagingTest"
  | "prod"
  | "feedback";

/** The whole loop, drawn full screen, with some parts lit. */
export interface LoopStep {
  kind: "loop";
  title: string;
  notes: string;
  /** Parts drawn so far, for building the map up; omit to draw everything. */
  show?: LoopPart[];
  lit?: LoopPart[];
  focus?: LoopPart[];
  frames: number;
}

/** A pull request page: its checks, and comments (e.g. the preview link). */
export interface CommentStep {
  kind: "comment";
  title: string;
  notes: string;
  pr: { number: number; title: string; branch: string };
  checks: { name: string; state: "pending" | "passed" | "failed"; detail?: string }[];
  comments: { author: string; bot?: boolean; lines: string[] }[];
  frames: number;
}

/** One layer of an application, drawn as a band of the pyramid. */
export interface PyramidLayer {
  id: string;
  title: string;
  detail: string;
  color: string;
}

/** An application's layers as a pyramid, bottom first, with notes beside them. */
export interface PyramidStep {
  kind: "pyramid";
  title: string;
  notes: string;
  /** Layers drawn so far, bottom first. */
  layers: PyramidLayer[];
  /** Layers at full strength; the rest are dimmed. Omit to light everything. */
  lit?: string[];
  /** Hand-written notes to the right of a layer. */
  side?: {
    layer: string;
    text: string;
    tone?: Tone;
    /** Code set in a column right of the pyramid, instead of a hand-written note. */
    code?: boolean;
    /** The code, highlighted (filled in by the build). */
    tokens?: Token[][];
  }[];
  /** A column beside the pyramid, spanning every layer (observability). */
  pillar?: { title: string; lines: string[]; color: string };
  /** A bracket over every layer, with a label. */
  brace?: { text: string; sub?: string };
  /** A dashed line under a layer, splitting the stack into two programs. */
  cut?: { under: string; above: string; below: string };
  /** One feature, cut vertically through every layer: what it needs in each. */
  slice?: { label: string; items: Record<string, string> };
  /** Several features, each cut vertically through the layers, side by side. */
  slices?: { label: string; items: Record<string, string> }[];
  /** The stack rebuilt from modules: bricks laid in the pyramid's rows, bottom first. */
  bricks?: {
    row: number;
    title: string;
    detail: string;
    color: string;
    /** Fixed place in the row (0-based) out of `of`, so a row doesn't reflow as bricks arrive. */
    col?: number;
    of?: number;
  }[];
  frames: number;
}

/**
 * Code that stays put while a few spans of it roll to the next value, like a
 * slot machine: each keypress swaps a provider, and nothing else moves.
 */
export interface RollStep {
  kind: "roll";
  title: string;
  notes: string;
  /** Consecutive roll steps of one group animate from each other. */
  group: string;
  file?: string;
  fontSize: number;
  lines: Token[][];
  /** The spans that change between the steps of a group, by index. */
  slots: { line: number; start: number; end: number; active?: boolean }[];
  /** What the current code generates at deploy, beside it. */
  beside?: { file: string; lines: Token[][] };
  /** Every option in the roll, with the current one lit. */
  reel?: { items: string[]; at: number };
  /** Spin one slot through these values, slot-machine style, before it lands on its own. */
  spin?: { slot: number; through: string[]; reelFrom: number };
  frames: number;
}

/** A full-screen architecture drawing: boxes, and arrows between them. */
export interface ArchStep {
  kind: "arch";
  title: string;
  notes: string;
  nodes: {
    id: string;
    title: string;
    sub?: string;
    color: string;
    x: number;
    y: number;
    w?: number;
    h?: number;
  }[];
  /** Row labels down the left edge, so the drawing reads top to bottom. */
  lanes?: { label: string; y: number; color: string }[];
  /** `dashed` edges are telemetry, not requests. */
  /** `dashed` edges are telemetry; `elbow` edges leave sideways, then turn down. */
  edges: { from: string; to: string; label?: string; dashed?: boolean; elbow?: boolean }[];
  frames: number;
}

/** A mocked observability dashboard (hypothetical UI), optionally with its monitor firing. */
export interface DashStep {
  kind: "dash";
  title: string;
  notes: string;
  /** Show the monitor alert firing, and the error spike that triggered it. */
  alert?: boolean;
  frames: number;
}

export type IntroStep =
  | DashStep
  | ArchStep
  | RollStep
  | CodeStep
  | SlideStep
  | BoardStep
  | TerminalStep
  | BrowserStep
  | LoopStep
  | CommentStep
  | PyramidStep;

export interface IntroJson {
  steps: IntroStep[];
}

/** Frame ranges of each step, back to back. */
export const introTimeline = (steps: IntroStep[]) => {
  let from = 0;
  return steps.map((step) => {
    const range = { from, to: from + step.frames };
    from = range.to;
    return range;
  });
};