token_reel 0.2.0

data/lib/token_reel/highlight.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module TokenReel
+  # A small, dependency-free syntax colorizer for text inside fenced
+  # code blocks. It isn't a real per-language grammar -- just enough
+  # regex-based token classing (comments, strings, numbers, a shared
+  # keyword list spanning a handful of mainstream languages) to make
+  # demo code read as code instead of one flat color. The language tag
+  # on a fence (```ruby) is cosmetic; every fence is highlighted the
+  # same way.
+  module Highlight
+    KEYWORDS = %w[
+      def end class module function fn func return if elif elsif else
+      unless while until for do begin rescue ensure raise throw try
+      catch except finally break next continue yield case when switch
+      match default import export from require include use pub package
+      namespace let const var static final public private protected
+      abstract new self this super nil null none true false async await
+      int float double bool bool8 string char void byte long short
+      struct enum interface extends implements typeof instanceof
+      in of as with lambda del pass global nonlocal
+    ].freeze
+
+    # One token per iteration: a comment to end-of-line, a quoted
+    # string (single/double/backtick, backslash-escaped), an integer
+    # or float, an identifier/keyword, or a single other character
+    # (whitespace, punctuation, operators).
+    TOKEN = /
+      (?<comment>\#.*\z|\/\/.*\z)
+      |(?<string>"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'|`(?:[^`\\]|\\.)*`)
+      |(?<number>\b\d+(?:\.\d+)?\b)
+      |(?<word>[A-Za-z_][A-Za-z0-9_]*)
+      |(?<other>.)
+    /x
+
+    # Splits one line of code into color-tagged spans. Adjacent tokens
+    # that land on the same color are merged, so a run of plain text
+    # becomes one span instead of one per character.
+    def self.spans(line, palette)
+      out = []
+      line.scan(TOKEN) do
+        m = Regexp.last_match
+        text, color = classify(m, palette)
+        if out.any? && out.last[:color] == color
+          out.last[:text] += text
+        else
+          out << { text: text, color: color }
+        end
+      end
+      out
+    end
+
+    def self.classify(m, palette)
+      return [m[:comment], palette[:syn_comment]] if m[:comment]
+      return [m[:string], palette[:syn_string]] if m[:string]
+      return [m[:number], palette[:syn_number]] if m[:number]
+      return [m[:word], KEYWORDS.include?(m[:word]) ? palette[:syn_keyword] : palette[:fg]] if m[:word]
+
+      [m[:other], palette[:fg]]
+    end
+  end
+end

data/lib/token_reel/renderer.rb

@@ -0,0 +1,273 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module TokenReel
+  # Turns a Timeline::State into a terminal-window PNG. Text layout is
+  # done in Ruby (word wrap, cursor placement); ImageMagick just draws
+  # the rectangles and glyphs we tell it to.
+  class Renderer
+    HEADER_H = 40
+    PAD_X = 18
+    PAD_Y = 14
+    DOT_R = 6
+
+    attr_reader :char_w, :char_h, :total_lines
+
+    def self.convert_binary
+      @convert_binary ||= %w[magick convert].find { |bin| system("which #{bin} > /dev/null 2>&1") } ||
+                           raise(RenderError, "ImageMagick not found: install `imagemagick` (needs `convert` or `magick` on PATH)")
+    end
+
+    def initialize(config, timeline)
+      @config = config
+      @timeline = timeline
+      @palette = Theme.fetch(config.theme)
+      @font = Fonts.resolve!(config.font)
+      calibrate!
+      # The window is a fixed config.rows lines tall, like a real
+      # console -- every frame shares this height regardless of how
+      # much text it holds.
+      @total_lines = @config.rows
+      @width = @config.cols * char_w + PAD_X * 2
+      @height = HEADER_H + PAD_Y * 2 + total_lines * char_h
+    end
+
+    def render(state, out_path)
+      lines = wrap_body(state)
+      # Once a frame's content outgrows the window, scroll: keep only
+      # the most recent total_lines lines, same as a real terminal
+      # dropping its oldest lines off the top.
+      lines = lines.last(total_lines) if lines.size > total_lines
+      pad = [total_lines - lines.size, 0].max
+      lines += [{ text: "", color: @palette[:fg] }] * pad
+
+      argv = ["-size", "#{@width}x#{@height}", "xc:#{@palette[:bg]}"]
+      argv += header_bar_args
+      y = HEADER_H + PAD_Y + char_h - (char_h * 0.28).round
+      lines.each do |line|
+        argv += line_args(line, y)
+        y += char_h
+      end
+      argv << out_path
+
+      run!(argv)
+      out_path
+    end
+
+    private
+
+    # Measures the font's per-character advance width, not a single
+    # glyph's ink width -- those differ (a glyph is typically narrower
+    # than its cell) and only the advance width is what lines up
+    # correctly when text is drawn as several separate -annotate calls,
+    # as syntax-highlighted spans are. Comparing two label: widths of
+    # different lengths and dividing by the difference in length
+    # cancels out the fixed left/right bearing "label:" adds around the
+    # text, isolating the true per-character advance.
+    SHORT_CALIB_LEN = 10
+    LONG_CALIB_LEN = 30
+
+    def calibrate!
+      Dir.mktmpdir do |dir|
+        short = File.join(dir, "short.png")
+        long = File.join(dir, "long.png")
+        run!(["-background", "none", "-fill", "black", "-font", @font,
+              "-pointsize", @config.font_size.to_s, "label:#{'0' * SHORT_CALIB_LEN}", short])
+        run!(["-background", "none", "-fill", "black", "-font", @font,
+              "-pointsize", @config.font_size.to_s, "label:#{'0' * LONG_CALIB_LEN}", long])
+        w_short, h = `identify -format "%w %h" #{Shellwords.escape(short)}`.split.map(&:to_i)
+        w_long, = `identify -format "%w %h" #{Shellwords.escape(long)}`.split.map(&:to_i)
+        raise RenderError, "could not calibrate font metrics for #{@font.inspect}" if w_short.to_i <= 0 || w_long.to_i <= 0
+
+        @char_w = ((w_long - w_short).to_f / (LONG_CALIB_LEN - SHORT_CALIB_LEN)).round
+        @char_h = (h * 1.35).round
+      end
+    end
+
+    def header_bar_args
+      args = ["-fill", @palette[:header], "-draw", "rectangle 0,0 #{@width},#{HEADER_H}"]
+      cx = PAD_X
+      cy = HEADER_H / 2
+      [@palette[:dot_red], @palette[:dot_yellow], @palette[:dot_green]].each do |color|
+        args += ["-fill", color, "-draw", "circle #{cx},#{cy} #{cx + DOT_R},#{cy}"]
+        cx += DOT_R * 3
+      end
+      args += ["-fill", @palette[:muted], "-font", @font, "-pointsize", (@config.font_size * 0.7).round.to_s,
+               "-gravity", "North", "-annotate", "+0+#{(HEADER_H - @config.font_size * 0.7) / 2 - 2}", escape_annotate(@config.title),
+               "-gravity", "NorthWest"]
+      args
+    end
+
+    # A line is either a single-color {text:, color:} (prose) or a
+    # multi-color {spans: [{text:, color:}, ...]} (a highlighted code
+    # line). Spans are drawn as consecutive -annotate calls, each
+    # offset by the fixed glyph width times the characters already
+    # placed -- exact because the font is monospace.
+    def line_args(line, y)
+      if line[:spans]
+        x = PAD_X
+        line[:spans].flat_map do |span|
+          args = annotate_args(span[:text], span[:color], x, y)
+          x += char_w * span[:text].length
+          args
+        end
+      else
+        annotate_args(line[:text], line[:color], PAD_X, y)
+      end
+    end
+
+    # ImageMagick's -annotate silently trims leading whitespace off the
+    # text it's given -- a mixed span like " sum(" would draw as "sum("
+    # flush against whatever x we asked for, one glyph closer than
+    # intended, colliding with the previous span. Since we position
+    # every span explicitly rather than relying on IM's own text flow,
+    # the fix is to strip the whitespace ourselves and shift x by
+    # however many characters we stripped, so IM never sees (and can't
+    # silently eat) leading whitespace in what it draws. A whitespace-
+    # only span -- e.g. a code line's leading indent, its own span
+    # since it's a different color to what follows -- draws nothing at
+    # all, correctly, since the canvas is already blank there.
+    def annotate_args(text, color, x, y)
+      leading = text[/\A\s*/].length
+      visible = text.strip
+      return [] if visible.empty?
+
+      ["-fill", color, "-font", @font, "-pointsize", @config.font_size.to_s,
+       "-annotate", "+#{x + char_w * leading}+#{y}", escape_annotate(visible)]
+    end
+
+    # ImageMagick's -annotate treats a literal backslash in the text as
+    # the start of an escape (e.g. a bare "\n" becomes a real line
+    # break), independent of our own word-wrap. Text like a shell
+    # `"...\n..."` argument that never got interpreted as a real
+    # newline would otherwise grow extra lines IM knows about but our
+    # canvas-height math (based on real "\n" splits) doesn't -- pushing
+    # later lines down until they overflow and overlap. Doubling
+    # backslashes makes IM render them literally instead.
+    def escape_annotate(text)
+      text.gsub("\\") { "\\\\" }
+    end
+
+    # Builds the wrapped, cursor-annotated lines for a state, without
+    # the trailing pad-to-total_lines step (callers that need a fixed
+    # canvas height add that themselves).
+    def wrap_body(state)
+      body = wrap_text("#{@config.label}#{state.prompt_text}", @config.cols)
+                .map { |l| { text: l, color: @palette[:prompt] } }
+
+      case state.phase
+      when :typing_prompt
+        append_cursor!(body, state.cursor_on)
+        return body
+      when :thinking
+        body << { text: "", color: @palette[:fg] }
+        dots = "." * state.dot_count
+        body << { text: "#{@config.thinking_label}#{dots}", color: @palette[:muted] }
+        append_cursor!(body, state.cursor_on)
+        return body
+      when :reasoning
+        body << { text: "", color: @palette[:fg] }
+        body << { text: @config.thinking_label, color: @palette[:muted] }
+        body += code_aware_lines(state.reasoning_text, @config.cols - 2, @palette[:muted])
+                  .map { |l| indent_line(l, "  ") }
+        append_cursor!(body, state.cursor_on)
+        return body
+      else
+        body << { text: "", color: @palette[:fg] }
+        body += code_aware_lines(state.response_text, @config.cols, @palette[:fg])
+        append_cursor!(body, state.cursor_on)
+        return body
+      end
+    end
+
+    def append_cursor!(body, cursor_on)
+      return unless cursor_on
+
+      last = body.last
+      if last[:spans]
+        last[:spans] << { text: @config.cursor_char, color: @palette[:fg] }
+      else
+        last[:text] = "#{last[:text]}#{@config.cursor_char}"
+      end
+    end
+
+    def indent_line(line, prefix)
+      if line[:spans]
+        { spans: [{ text: prefix, color: @palette[:muted] }] + line[:spans] }
+      else
+        { text: "#{prefix}#{line[:text]}", color: line[:color] }
+      end
+    end
+
+    def wrap_text(str, cols)
+      str.split("\n", -1).flat_map { |para| wrap_paragraph(para, cols) }
+    end
+
+    FENCE = /\A\s{0,3}(?:```|~~~)/
+    # A trailing line consisting of only 1-2 backticks/tildes could
+    # still grow into a real fence marker on the next frame (relevant
+    # with --unit char, where streaming can stop mid-marker). Since
+    # only the very last line of a partially-revealed text can be
+    # incomplete like this, it's held back for a frame rather than
+    # guessed at -- guessing wrong either toggles code state a
+    # character early or (worse) briefly counts an extra line that the
+    # fully-revealed text, which sized the canvas, never has.
+    PENDING_FENCE = /\A\s{0,3}(?:`{1,2}|~{1,2})\z/
+
+    # Walks text line by line, toggling in/out of "code" on fence
+    # markers (```/~~~). Fence marker lines themselves are dropped from
+    # the output -- the fence is how the source marks the block, not
+    # something meant to show up in a rendered chat transcript. Prose
+    # lines word-wrap and render in a single color, same as before;
+    # code lines are split into syntax-highlighted spans. Because this
+    # runs on whatever prefix of the text has streamed in so far, an
+    # unterminated trailing fence is simply treated as "still in code".
+    def code_aware_lines(text, cols, prose_color)
+      in_code = false
+      out = []
+      raw_lines = text.split("\n", -1)
+      raw_lines.pop if PENDING_FENCE.match?(raw_lines.last.to_s)
+
+      raw_lines.each do |raw|
+        if raw =~ FENCE
+          in_code = !in_code
+          next
+        end
+
+        out.concat(in_code ? wrap_code_line(raw, cols) : wrap_paragraph(raw, cols).map { |l| { text: l, color: prose_color } })
+      end
+
+      out << { text: "", color: prose_color } if out.empty?
+      out
+    end
+
+    def wrap_code_line(raw, cols)
+      chunks = raw.empty? ? [""] : raw.chars.each_slice([cols, 1].max).map(&:join)
+      chunks.map { |chunk| { spans: Highlight.spans(chunk, @palette) } }
+    end
+
+    def wrap_paragraph(line, cols)
+      return [""] if line.empty?
+
+      words = line.scan(/\S+\s*|\s+/)
+      lines = []
+      current = +""
+      words.each do |w|
+        if !current.empty? && (current.length + w.length) > cols
+          lines << current.rstrip
+          current = w.lstrip
+        else
+          current << w
+        end
+      end
+      lines << current.rstrip unless current.empty?
+      lines
+    end
+
+    def run!(argv)
+      _out, err, status = Open3.capture3(self.class.convert_binary, *argv)
+      raise RenderError, "ImageMagick failed: #{err}" unless status.success?
+    end
+  end
+end

data/lib/token_reel/script.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+module TokenReel
+  # Parses a single Markdown file into the named sections a render
+  # needs -- prompt, reasoning, and response -- so a whole exchange can
+  # be written and version-controlled as one file instead of juggling
+  # separate --prompt/--response flags.
+  #
+  # Recognized headings (any level, case-insensitive; content before
+  # the first recognized heading is ignored):
+  #
+  #   # Prompt | User | Input | Question
+  #   # Reasoning | Thinking | Thought
+  #   # Output | Response | Answer | Assistant
+  #
+  # A heading is only recognized outside of a fenced code block, so a
+  # shell/Python comment like "# Output" inside a ```fence``` never
+  # gets mistaken for a section header. Fence markers themselves are
+  # kept in the extracted section text -- Renderer is what looks for
+  # them, so this works the same whether the text came from a Markdown
+  # file or a plain --response string.
+  #
+  # `.template` returns a starter file with all three headings already
+  # in place, for `token_reel --init-markdown` to write out.
+  module Script
+    SECTION_ALIASES = {
+      "prompt" => :prompt, "user" => :prompt, "input" => :prompt, "question" => :prompt,
+      "reasoning" => :reasoning, "thinking" => :reasoning, "thought" => :reasoning,
+      "output" => :response, "response" => :response, "answer" => :response, "assistant" => :response
+    }.freeze
+
+    HEADING = /\A\s{0,3}\#{1,6}\s+(.+?)\s*\z/
+    FENCE = /\A\s{0,3}(?:```|~~~)/
+
+    TEMPLATE = <<~MD
+      ## Prompt
+
+      Replace this with the prompt text (shown as typed input).
+
+      ## Reasoning
+
+      Optional -- delete this whole section if you don't want a "thinking"
+      trace. Replace this with the reasoning text; it streams first, then
+      is replaced by the response.
+
+      ## Output
+
+      Replace this with the response text (streamed as output). Code
+      fences work here too and are syntax-highlighted:
+
+      ```ruby
+      def hello
+        puts "hi"
+      end
+      ```
+    MD
+
+    # A starter Markdown file with the three recognized headings
+    # already in place, ready to fill in and pass to `-m`/`--markdown`.
+    def self.template
+      TEMPLATE
+    end
+
+    # Returns { prompt: "...", reasoning: "...", response: "..." },
+    # omitting keys whose section was absent from the file.
+    def self.parse(text)
+      sections = Hash.new { |h, k| h[k] = +"" }
+      current = nil
+      in_fence = false
+
+      text.each_line do |line|
+        stripped = line.chomp
+        in_fence = !in_fence if stripped =~ FENCE
+
+        if !in_fence && (m = HEADING.match(stripped)) && (key = SECTION_ALIASES[m[1].downcase])
+          current = key
+          next
+        end
+
+        sections[current] << line if current
+      end
+
+      sections.transform_values(&:strip)
+    end
+  end
+end

data/lib/token_reel/theme.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module TokenReel
+  module Theme
+    PALETTES = {
+      dark: {
+        bg: "#0d1117", header: "#161b22", border: "#30363d",
+        fg: "#c9d1d9", prompt: "#7ee787", muted: "#8b949e",
+        dot_red: "#ff5f56", dot_yellow: "#ffbd2e", dot_green: "#27c93f",
+        syn_keyword: "#ff7b72", syn_string: "#a5d6ff", syn_number: "#79c0ff", syn_comment: "#8b949e"
+      },
+      matrix: {
+        bg: "#000000", header: "#000000", border: "#003300",
+        fg: "#00ff41", prompt: "#00ff41", muted: "#008f11",
+        dot_red: "#003300", dot_yellow: "#005500", dot_green: "#00ff41",
+        syn_keyword: "#00ffae", syn_string: "#7fff7f", syn_number: "#39ff14", syn_comment: "#008f11"
+      },
+      light: {
+        bg: "#ffffff", header: "#f0f0f0", border: "#d0d0d0",
+        fg: "#24292f", prompt: "#116329", muted: "#6e7781",
+        dot_red: "#ff5f56", dot_yellow: "#ffbd2e", dot_green: "#27c93f",
+        syn_keyword: "#cf222e", syn_string: "#0a3069", syn_number: "#0550ae", syn_comment: "#6e7781"
+      },
+      solarized: {
+        bg: "#002b36", header: "#073642", border: "#586e75",
+        fg: "#eee8d5", prompt: "#2aa198", muted: "#93a1a1",
+        dot_red: "#dc322f", dot_yellow: "#b58900", dot_green: "#859900",
+        syn_keyword: "#268bd2", syn_string: "#859900", syn_number: "#cb4b16", syn_comment: "#93a1a1"
+      }
+    }.freeze
+
+    def self.fetch(name)
+      PALETTES.fetch(name.to_sym) do
+        raise ConfigError, "unknown theme #{name.inspect} (valid: #{PALETTES.keys.join(', ')})"
+      end
+    end
+  end
+end

data/lib/token_reel/timeline.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module TokenReel
+  # A snapshot of the screen at a given moment: how much of the prompt,
+  # reasoning, and response are visible, which "phase" we're in, and
+  # whether the cursor happens to be in its "on" blink state.
+  State = Struct.new(:phase, :prompt_text, :reasoning_text, :response_text, :cursor_on, :dot_count, keyword_init: true) do
+    # Identical signatures render to the identical frame, so the
+    # sampler can skip re-rendering and just extend the previous
+    # frame's delay instead.
+    def signature
+      [phase, prompt_text, reasoning_text, response_text, cursor_on, dot_count]
+    end
+  end
+
+  # Pure function of time -> State. Doesn't touch the filesystem or
+  # ImageMagick at all, which makes it cheap to sample as densely as
+  # we like when building the frame list.
+  class Timeline
+    BLINK_HZ = 2.0     # cursor toggles this many times per second
+    DOT_INTERVAL = 0.35 # seconds between "thinking..." dot ticks
+
+    attr_reader :prompt_tokens, :reasoning_tokens, :response_tokens,
+                :prompt_full, :reasoning_full, :response_full,
+                :prompt_done_t, :thinking_end_t, :reasoning_end_t, :stream_end_t, :duration
+
+    def initialize(config)
+      @config = config
+      @prompt_tokens = Tokenizer.tokenize(config.prompt, config.unit)
+      @reasoning_tokens = Tokenizer.tokenize(config.reasoning, config.unit)
+      @response_tokens = Tokenizer.tokenize(config.response, config.unit)
+      @prompt_full = prompt_tokens.join
+      @reasoning_full = reasoning_tokens.join
+      @response_full = response_tokens.join
+
+      @prompt_interval = config.prompt_tps.to_f.positive? ? 1.0 / config.prompt_tps : 0
+      @reasoning_interval = config.reasoning_tps.to_f.positive? ? 1.0 / config.reasoning_tps : 1.0 / config.tps
+      @response_interval = 1.0 / config.tps
+
+      @prompt_done_t = @prompt_interval * prompt_tokens.size
+      @thinking_end_t = prompt_done_t + config.ttft.to_f
+      @reasoning_end_t = thinking_end_t + @reasoning_interval * reasoning_tokens.size
+      @stream_end_t = reasoning_end_t + @response_interval * response_tokens.size
+      @duration = stream_end_t + config.hold.to_f
+    end
+
+    def state_at(t)
+      t = t.clamp(0, duration)
+
+      if t < prompt_done_t
+        n = @prompt_interval.positive? ? (t / @prompt_interval).floor : prompt_tokens.size
+        State.new(
+          phase: :typing_prompt,
+          prompt_text: prompt_tokens[0...n].join,
+          reasoning_text: "",
+          response_text: "",
+          cursor_on: blink_on?(t),
+          dot_count: 0
+        )
+      elsif t < thinking_end_t
+        elapsed = t - prompt_done_t
+        State.new(
+          phase: :thinking,
+          prompt_text: prompt_full,
+          reasoning_text: "",
+          response_text: "",
+          cursor_on: blink_on?(t),
+          dot_count: ((elapsed / DOT_INTERVAL).to_i % 4)
+        )
+      elsif t < reasoning_end_t
+        elapsed = t - thinking_end_t
+        n = @reasoning_interval.positive? ? (elapsed / @reasoning_interval).floor : reasoning_tokens.size
+        n = n.clamp(0, reasoning_tokens.size)
+        State.new(
+          phase: :reasoning,
+          prompt_text: prompt_full,
+          reasoning_text: reasoning_tokens[0...n].join,
+          response_text: "",
+          cursor_on: blink_on?(t),
+          dot_count: 0
+        )
+      else
+        elapsed = t - reasoning_end_t
+        n = @response_interval.positive? ? (elapsed / @response_interval).floor : response_tokens.size
+        n = n.clamp(0, response_tokens.size)
+        done = n >= response_tokens.size
+        State.new(
+          phase: done ? :done : :streaming,
+          prompt_text: prompt_full,
+          reasoning_text: "",
+          response_text: response_tokens[0...n].join,
+          cursor_on: blink_on?(t),
+          dot_count: 0
+        )
+      end
+    end
+
+    # The fully-revealed, cursor-off state -- used to size the canvas
+    # so every frame in the GIF shares identical dimensions.
+    def final_state
+      State.new(phase: :done, prompt_text: prompt_full, reasoning_text: "", response_text: response_full,
+                 cursor_on: false, dot_count: 0)
+    end
+
+    # The reasoning phase in full, cursor off -- used alongside
+    # final_state to size the canvas, since the reasoning trace (shown
+    # only while streaming, then replaced by the response) can be
+    # taller than the finished response.
+    def max_reasoning_state
+      State.new(phase: :reasoning, prompt_text: prompt_full, reasoning_text: reasoning_full, response_text: "",
+                 cursor_on: false, dot_count: 0)
+    end
+
+    private
+
+    def blink_on?(t)
+      (t * (2 * BLINK_HZ)).to_i.even?
+    end
+  end
+end

data/lib/token_reel/tokenizer.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module TokenReel
+  # Splits text into the chunks that get revealed one-by-one while
+  # streaming. Joining the tokens back together always reproduces the
+  # original string exactly.
+  module Tokenizer
+    def self.tokenize(text, unit)
+      return [] if text.nil? || text.empty?
+
+      case unit.to_sym
+      when :char
+        text.each_char.to_a
+      when :word
+        # "word" + any trailing whitespace travels together, so a token
+        # reveals as a whole word (closer to how LLM tokens/BPE chunks
+        # tend to land) instead of one raw character at a time.
+        text.scan(/\S+\s*|\s+/)
+      else
+        raise ConfigError, "unknown unit #{unit.inspect} (valid: word, char)"
+      end
+    end
+  end
+end

data/lib/token_reel/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TokenReel
+  VERSION = "0.2.0"
+end

data/lib/token_reel.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+require_relative "token_reel/version"
+require_relative "token_reel/errors"
+require_relative "token_reel/theme"
+require_relative "token_reel/tokenizer"
+require_relative "token_reel/script"
+require_relative "token_reel/config"
+require_relative "token_reel/timeline"
+require_relative "token_reel/fonts"
+require_relative "token_reel/highlight"
+require_relative "token_reel/renderer"
+require_relative "token_reel/gif_writer"
+require_relative "token_reel/generator"
+require_relative "token_reel/cli"
+
+module TokenReel
+  # Convenience one-liner: TokenReel.generate(prompt: "...", response: "...", tps: 12)
+  def self.generate(**opts)
+    config = Config.new
+    opts.each do |k, v|
+      setter = "#{k}="
+      raise ConfigError, "unknown option #{k.inspect}" unless config.respond_to?(setter)
+
+      config.public_send(setter, v)
+    end
+    Generator.new(config).generate!
+  end
+end

data/token_reel.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "lib/token_reel/version"
+
+Gem::Specification.new do |spec|
+  spec.name        = "token_reel"
+  spec.version     = TokenReel::VERSION
+  spec.authors     = ["Thomas Powell"]
+  spec.email       = ["twilliampowell@gmail.com"]
+  spec.summary     = "Render terminal-style GIFs of an LLM prompt/response, streamed at a chosen tokens/sec and time-to-first-token"
+  spec.description = <<~DESC
+    token_reel renders a "CLI demo"-style animated GIF of a prompt being
+    answered: the prompt appears, there's a configurable pause (time to
+    first token), and the response streams in word-by-word or
+    character-by-character at a configurable tokens/sec rate -- handy for
+    READMEs, blog posts, and talks that want to show off an LLM CLI
+    without shelling out to a real model (or a real screen recorder).
+  DESC
+  spec.homepage    = "https://github.com/stringsn88keys/token_reel"
+  spec.license     = "MIT"
+  spec.required_ruby_version = ">= 3.0"
+
+  spec.metadata["homepage_uri"]    = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+
+  spec.files = Dir.chdir(__dir__) do
+    if system("git rev-parse --git-dir > /dev/null 2>&1")
+      `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
+    else
+      Dir.glob("{lib,exe}/**/*", File::FNM_DOTMATCH).select { |f| File.file?(f) } +
+        %w[README.md token_reel.gemspec]
+    end
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rspec", "~> 3.12"
+end