dopairb 0.2.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 83be2be298c392a6739e1fdef9293579796f7d80dd3a5b3aaccc65cf34f60d4c
-  data.tar.gz: 8afedc6a382a671a5e3dc13720f1934599757cadd6aacb28b88b69cd1986b0ac
+  metadata.gz: afb5e40866c1cdf891ccf500611c568c91f693715f120e69822088e7bdcffdf3
+  data.tar.gz: 25b611a5ac21351f1f9adf5fd811cbc6c8422651dd7cab94dbb878d68d25930d
 SHA512:
-  metadata.gz: 7aed8c09308468b4e3ed6e992cba5d4245d349c66bf88abfa37a4d6a214a1f457dd4610db944f49e5d53c1e024ebfc4bed7bf82fa81ef319d65e158547139633
-  data.tar.gz: 2c6609aeb7f8939fe95c0278592bf45cc67f68eb52d715e3527837074ecea19dda912505d630715e2a5ef760d630b33a3b778f07a39faba81aef5def8fbe1119
+  metadata.gz: 46b1c5c6e4b4450e0297b21d70a24da9ad379603512de745e208837a57a79f7b004eed7c5a748261c78052b1bb1aa44c564595d599552d3471c5055d5182a871
+  data.tar.gz: 8979f157991d9e6451e7ceb8df3fc480a86ee39bd350f2afe363d5c87ccc187e62dc729eefab57deaf3aaa6f975aee6e37a6f948cd7f7353b3fef574ee09e406

data/README.md

@@ -3,6 +3,10 @@
 An interactive Ruby shell that answers every keystroke, evaluation, result and exception with loud terminal effects.
 It is built as an IRB extension. The design spec is [spec.md](spec.md) (in Japanese).
 
+https://github.com/user-attachments/assets/98b037e1-5a30-4abd-812d-233a60ab2de4
+
+A 72-second promo with sound and English/Japanese subtitles: plain irb, then `dopa on`, the setup, and "Happy dopa Ruby!". The scripts that record dopairb sessions like this one are in [docs/recording](docs/recording).
+
 ```
 dopairb(main):001> (1..100).sum                     COMBO 00  SCORE 33  [⣿⣿⣀⣀⣀⣀⣀⣀] x1.5
                     ⠂⠌⠟⠃        <- sparks, afterglow and HUD on every keystroke
@@ -29,30 +33,41 @@ To try it without installing, run `ruby exe/dopairb` in the checkout.
 ## Usage
 
 ```console
-$ dopairb                 # start it (IRB options are passed through)
+$ dopairb                 # start it, at full blast with sound (IRB options are passed through)
 $ dopairb --calm          # quieter: low intensity, no flash, shorter effects
-$ dopairb --max           # everything at maximum; the biggest moments go full screen
 $ dopairb --party         # max + full-screen flash + sound effects
-$ dopairb --sound         # synthesized sound effects (--sound=bell for the terminal bell)
+$ dopairb --intensity=normal --no-sound   # the tamer pre-0.4.0 defaults
 $ dopairb --no-flash      # suppress flashing, available from the very first start
 $ DOPAIRB="intensity=low,flash=off" dopairb
 ```
 
-To enable it in your regular `irb`, add this to `~/.irbrc`:
+To turn your regular `irb` into dopairb, add this to `~/.irbrc`:
 
 ```ruby
-require "dopairb"
-Dopairb.enable            # also e.g. Dopairb.enable(flash: :off, intensity: :low)
+begin
+  require "dopairb"   # adds the `dopa` command; `dopa on` starts the show
+  Dopairb.enable      # ...or start with the show on (e.g. Dopairb.enable(sound: :off))
+rescue LoadError
+  # a Ruby without dopairb keeps plain irb
+end
 ```
 
+With only the `require`, irb stays plain until you type `dopa on`.
+The title (and the loading screen on a cold start) plays right before the first prompt, as with the `dopairb` command.
+Sessions opened by `binding.irb` get the effects too; `Dopairb.enable(binding_irb: false)` keeps them plain.
+Settings for a single run (`dopairb` options and `$DOPAIRB`) win over the ones given to `Dopairb.enable` in `.irbrc`.
+
 Inside a session, the `dopa` command changes settings:
 
 ```
 dopa                  show settings and session stats
+dopa on / dopa off    switch the show on (back to the last level) or off
 dopa off|low|normal|max
 dopa calm / dopa party
 dopa demo             play every effect once (does not change your score)
 dopa loading          show the loading screen
+dopa gallery          the bonus art you have collected (`dopa gallery starry_night` shows one)
+dopa gallery tour     a full-screen slideshow of all 100; uncollected ones appear as silhouettes
 dopa flash=off duration=0.5 ...
 ```
 
@@ -60,10 +75,10 @@ dopa flash=off duration=0.5 ...
 
 | Setting | Values | Default | Meaning |
 | --- | --- | --- | --- |
-| `intensity` | off / low / normal / max | normal | Overall amount. `off` behaves exactly like plain IRB |
+| `intensity` | off / low / normal / max | max | Overall amount. `off` behaves exactly like plain IRB |
 | `motion` | on / off | on | `off` disables animation (badges only) |
 | `flash` | off / soft / full | soft | `soft` flashes only the effect area, `full` inverts the whole screen |
-| `sound` | off / bell / sfx | off | `sfx` plays synthesized sound effects, `bell` rings the terminal bell on big moments |
+| `sound` | off / bell / sfx | sfx | `sfx` plays synthesized sound effects, `bell` rings the terminal bell on big moments |
 | `hud` | on / off | on | COMBO / SCORE / CHARGE on the right of the prompt line |
 | `duration` | 0.1–5 | 1.0 | Length multiplier for every effect |
 | `color` | auto / truecolor / 256 / 16 / none | auto | `none` when `NO_COLOR` is set |
@@ -71,6 +86,7 @@ dopa flash=off duration=0.5 ...
 | `charge` | 0–0.3 s | 0.12 | Wind-up before a fast result lands; 0 disables it |
 | `intro` | on / off | on | Title animation at startup |
 | `keys` | on / off | on | Per-keystroke effects |
+| `binding_irb` | on / off | on | Effects in sessions opened by `binding.irb` too |
 
 ## Effects
 
@@ -80,6 +96,7 @@ When several fire at once, only the biggest plays. The smaller ones are folded i
 | Moment | Effect |
 | --- | --- |
 | Typing | A spark trail right of the cursor, a brief glow on the typed character, embers falling below, a x1.0–x3.0 multiplier |
+| Typing streak of 8, 16, 32 … 1024 keys | Powers of two, in big half-block letters under the input: `8-BIT RUSH!`, `16-BIT COMBO!`, `32-BIT BLAZE!!`, `64-BIT OVERDRIVE!!`, `128-BIT HYPER MODE!!`, `0x100 OVERFLOW!!!`, `2^9 GODSPEED!!!`, `1KiB TYPING LEGEND!!!`, with a bonus of 4 points per key |
 | Resuming after a pause | Reignites with `CHARGE!` |
 | Backspace / Delete | The deleted character shatters and falls. The next keystroke shows `RECOVERY` |
 | Cursor movement | A light streak in the direction of travel |
@@ -104,12 +121,32 @@ When several fire at once, only the biggest plays. The smaller ones are folded i
 | Other exceptions | A red flash and a glitching `FAILED` |
 | Ctrl-C | The stored charge scatters, `INTERRUPTED` |
 | First eval / COMBO 5, 10, 25… / eval count 10, 50, 100… | `FIRST HIT!` / `COMBO 10!` / `100 EVALS` |
+| Lucky success (about 1 in 10, up to 1 in 5 with a full CHARGE) | `CRITICAL!!`: a slash, a red flash and x2 / x4 / x8 points |
+| Very lucky success (1 in 67) | `JACKPOT!!`: three slot reels stop on 7-7-7, coins rain, x16 points |
+| COMBO 10 and beyond | `FEVER TIME!`: every point counts double until the next error; the HUD glows in rainbow `FEVER!` |
+| Beating your all-time best combo | `BEST COMBO!` |
+| Level up, jackpot, or a lucky drop (see [Career](#career)) | `LEVEL UP!` / `JACKPOT PRIZE` / `ART DROP!`, then a famous painting is unveiled full screen as bonus art |
 | Numeric record (more than doubled) | `NEW RECORD` |
 | Success right after an error | `FIXED!` (after one error) / `COMEBACK!` (after a streak), both huge |
 | Exit | A full-screen finale: the title drops, stats slam in one by one, the total score counts up under a drum roll, a rank is stamped (S/A/B/C with a cheerful title), then fireworks. The result is left behind as a plain table |
 
 Error effects name the kind of error. They never make fun of the failure.
 
+## Career
+
+Between sessions dopairb keeps a small profile: lifetime XP (the sum of your scores), level, best score, best combo, a day streak and the bonus art you have collected.
+Levels need powers of two: LV 2 at 512 XP, LV 3 at 1,024, LV 4 at 2,048, and so on.
+Each level-up and each jackpot unveils a masterpiece full screen, and now and then (about 1 success in 50) one simply drops: `ART DROP!`. There are 100 public-domain works to collect, from the Lascaux horses and Hokusai's *Great Wave* through Vermeer, Turner and van Gogh to Klimt, Kandinsky and Mondrian, all painted procedurally in half blocks (no image files ship with the gem). New ones come first; `dopa gallery` lists yours.
+
+![100 frames, five of them filled](docs/gallery-teaser.png)
+
+The startup title shows your level and day streak, and the finale shows `NEW BEST!` and an XP bar.
+
+The profile is `~/.local/state/dopairb/profile.json` (`$XDG_STATE_HOME` is honored). Set `DOPAIRB_PROFILE=path` to use another file, or `DOPAIRB_PROFILE=off` to keep nothing; levels are then not shown.
+Non-interactive runs never touch it.
+
+`DOPAIRB_SEED=n` makes the luck (critical hits, jackpots, particles) repeatable, which helps when recording a demo.
+
 ## Sound
 
 With `sound=sfx`, every effect has a sound: key clicks, `NICE!` chimes, a comet ping, a stamp thump, a count-up that ends in a boom, fanfares and explosions for the big moments, a buzz or crack for errors.
@@ -129,6 +166,37 @@ PowerShell takes a few hundred milliseconds to start, so with it only the result
 When no player is found, `sfx` falls back to the terminal bell on big moments.
 Sound plays on the machine that runs dopairb, so over ssh you will not hear it.
 
+## Claude Code (dopacc)
+
+The gem also ships `dopacc`, which puts the show on top of [Claude Code](https://claude.com/claude-code):
+
+https://github.com/user-attachments/assets/458acc90-72ba-4a81-a352-082cde2096d5
+
+```
+gem install dopairb
+dopacc install        # adds hooks + a status line to ~/.claude/settings.json
+```
+
+Then restart Claude Code. From then on:
+
+- Every successful tool call adds to the COMBO with a chime. At 10 and above it is FEVER (x2 score).
+- At COMBO 8, 16, 32, ... a full-screen `COMBO 16!` banner with fireworks takes over the screen for two seconds.
+- A tool call has a 1/64 chance of a `JACKPOT!!` (x16).
+- A failed tool call breaks the combo with a crack.
+- When Claude finishes a turn that used tools, a full-screen `MISSION COMPLETE!` shows the turn's tools, score, combo and best.
+- The status line shows `COMBO / SCORE / BEST` (an existing `statusLine` is left alone).
+
+```
+dopacc off / calm / on   # nothing / sounds only / everything (inside Claude Code: ! dopacc off)
+dopacc status
+dopacc demo              # ! dopacc demo inside Claude Code shows a banner right away
+dopacc uninstall
+```
+
+`dopacc install --project` writes to `./.claude/settings.local.json` instead. `DOPACC=off` in the environment silences it too.
+
+How it works: Claude Code owns the terminal and its hooks run without one. So a hook walks up the process tree to Claude Code's tty, draws the banner on it, and then has Claude Code repaint. With the fullscreen TUI (`"tui": "fullscreen"`), it draws over Claude Code's screen and makes it lay itself out again by narrowing the window by one column for a moment. With the classic TUI, it draws on the alternate screen and switches back. Progress is kept in `~/.local/state/dopairb/dopacc.json`. Hooks never fail: whatever happens, they exit 0 silently (`DOPACC_DEBUG=1` prints errors).
+
 ## Readable, never broken
 
 - IRB evaluates and prints as usual. `=> value`, exception messages and backtraces come from IRB itself.
@@ -172,7 +240,7 @@ The rest is terminal-independent logic:
 - Scores live for the session only and are not saved.
 - Effects use Unicode. Any glyph that is not one column wide is swapped for ASCII or braille at runtime.
 - Start it with the `dopairb` command, or call `Dopairb.enable` in `.irbrc`.
-- IRB sessions entered via `binding.irb` get the same Context hook. The result screen appears only when the outermost session ends.
+- IRB sessions entered via `binding.irb` get the same Context hook (unless `binding_irb=off`; detected with `IRB::Context#from_binding?`). The result screen appears only when the outermost session ends.
 
 ## Performance
 

data/exe/dopacc

@@ -0,0 +1,84 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# dopacc: dopairb's show on top of Claude Code.
+require_relative "../lib/dopairb/claude_code"
+
+CC = Dopairb::ClaudeCode
+
+def settings_path(args)
+  if (a = args.find { |x| x.start_with?("--settings=") })
+    a.delete_prefix("--settings=")
+  elsif args.include?("--project")
+    File.join(Dir.pwd, ".claude", "settings.local.json")
+  else
+    File.join(ENV["CLAUDE_CONFIG_DIR"] || File.expand_path("~/.claude"), "settings.json")
+  end
+end
+
+USAGE = <<~TXT
+  Usage: dopacc COMMAND
+
+    install [--project] [--no-statusline]  add the hooks to Claude Code's settings
+                                           (~/.claude/settings.json, or ./.claude/settings.local.json)
+    uninstall [--project]                  remove them again
+    on | calm | off                        full show / sounds only / nothing
+    status                                 mode, combo and score
+    demo [TEXT]                            try the full-screen banner (run it as `! dopacc demo` in Claude Code)
+    hook                                   (called by Claude Code with the hook JSON on stdin)
+    statusline                             (called by Claude Code for the status line)
+TXT
+
+cmd, *args = ARGV
+case cmd
+when "hook"
+  # Never get in Claude Code's way: whatever happens, exit 0 quietly.
+  begin
+    plan = CC::Hook.run($stdin.read)
+    if ENV["DOPACC_DRY"]
+      puts JSON.generate(plan)
+    else
+      plan.each do |e|
+        if e[:show]
+          CC::Screen.show(e[:show], sub: e[:sub], palette: e[:palette], sound: e[:sound])
+        elsif e[:sound]
+          CC::Screen.play(e[:sound])
+        end
+      end
+    end
+  rescue StandardError, LoadError => e
+    warn "dopacc: #{e.class}: #{e.message}" if ENV["DOPACC_DEBUG"]
+  end
+  exit 0
+when "statusline"
+  $stdin.read unless $stdin.tty?
+  print CC.statusline
+when *CC::MODES
+  CC::State.update { |s| s["mode"] = cmd }
+  puts "dopacc: #{cmd}"
+when "status"
+  s = CC::State.read
+  puts "mode #{s["mode"]}  combo #{s["combo"]}  best #{s["best"]}  score #{CC::Hook.commas(s["score"])}  tools #{s["tools"]}"
+  puts "hooks #{CC::Installer.installed?(settings_path(args)) ? "installed" : "not installed"} (#{settings_path(args)})"
+when "install"
+  path = settings_path(args)
+  notes = CC::Installer.install(path, statusline: !args.include?("--no-statusline"))
+  puts "dopacc: hooks added to #{path}"
+  notes.each { |n| puts "  #{n}" }
+  puts "  restart Claude Code (or open /hooks) to start the show; `dopacc off` to pause it"
+when "uninstall"
+  path = settings_path(args)
+  CC::Installer.uninstall(path)
+  puts "dopacc: hooks removed from #{path}"
+when "demo"
+  shown = CC::Screen.show(args.empty? ? "DOPA CLAUDE!" : args.join(" "), sub: "dopacc demo")
+  warn "dopacc: no terminal found (run it from inside Claude Code: ! dopacc demo)" unless shown
+when nil, "-h", "--help", "help"
+  puts USAGE
+when "--version"
+  require_relative "../lib/dopairb/version"
+  puts "dopacc (dopairb #{Dopairb::VERSION})"
+else
+  warn USAGE
+  exit 2
+end

data/lib/dopairb/claude_code.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "json"
+require "fileutils"
+
+module Dopairb
+  # dopacc: the dopairb show on top of Claude Code, driven by its hooks.
+  #
+  # Claude Code owns the terminal, so a hook finds Claude Code's tty by
+  # walking up the process tree, draws a full-screen banner on it and then
+  # makes Claude Code lay its screen out again by wiggling the window size.
+  # Everything here is cheap to load; the effects (`require "dopairb"`) are
+  # only loaded when something is actually drawn or played.
+  module ClaudeCode
+    MODES = %w[on calm off].freeze
+    HOOK_EVENTS = %w[PostToolUse PostToolUseFailure Stop].freeze
+    JACKPOT_CHANCE = 1 / 64.0
+    FEVER_COMBO = 10
+    DONE = ["MISSION COMPLETE!", "DONE!", "NICE WORK!", "GG!", "CLEAR!"].freeze
+
+    # Shared progress in a JSON file, updated under an exclusive lock
+    # because hooks of parallel tool calls run at the same time.
+    module State
+      DEFAULTS = { "mode" => "on", "session" => nil, "combo" => 0, "best" => 0, "score" => 0,
+                   "tools" => 0, "turn_tools" => 0, "turn_score" => 0 }.freeze
+
+      module_function
+
+      def path
+        ENV["DOPACC_STATE"] || File.join(ENV["XDG_STATE_HOME"] || File.expand_path("~/.local/state"), "dopairb", "dopacc.json")
+      end
+
+      def read
+        DEFAULTS.merge(JSON.parse(File.read(path)))
+      rescue SystemCallError, JSON::ParserError
+        DEFAULTS.dup
+      end
+
+      # Yields the state; whatever the block changes is written back.
+      def update
+        FileUtils.mkdir_p(File.dirname(path))
+        File.open(path, File::RDWR | File::CREAT, 0o644) do |f|
+          f.flock(File::LOCK_EX)
+          s = DEFAULTS.merge((JSON.parse(f.read) rescue {}))
+          result = yield s
+          f.rewind
+          f.truncate(0)
+          f.write(JSON.pretty_generate(s))
+          result
+        end
+      end
+    end
+
+    # One hook call: hook JSON in, a list of effects out.
+    module Hook
+      module_function
+
+      def run(input, rng: nil)
+        ev = (JSON.parse(input) rescue {})
+        return [] if %w[off 0 false].include?(ENV["DOPACC"].to_s)
+        mode = nil
+        plan = State.update do |s|
+          mode = s["mode"]
+          next [] if mode == "off"
+          rng ||= rng_for(s["tools"])
+          if s["session"] != ev["session_id"]
+            s.merge!("session" => ev["session_id"], "combo" => 0, "turn_tools" => 0, "turn_score" => 0)
+          end
+          case ev["hook_event_name"]
+          when "PostToolUse" then success(s, rng)
+          when "PostToolUseFailure" then failure(s)
+          when "Stop" then stop(s, rng)
+          else []
+          end
+        end
+        # calm: sounds only, never take the screen
+        plan = plan.map { |e| e[:show] ? { sound: e[:sound] } : e } if mode == "calm"
+        plan
+      end
+
+      # DOPACC_SEED makes the luck repeatable (for recordings), call by call.
+      def rng_for(tools)
+        ENV["DOPACC_SEED"] ? Random.new(ENV["DOPACC_SEED"].to_i * 1000 + tools) : Random.new
+      end
+
+      def success(s, rng)
+        s["combo"] += 1
+        s["tools"] += 1
+        s["turn_tools"] += 1
+        combo = s["combo"]
+        new_best = combo > s["best"]
+        s["best"] = combo if new_best
+        gain = (10 + combo) * (combo >= FEVER_COMBO ? 2 : 1)
+        jackpot = rng.rand < JACKPOT_CHANCE
+        gain *= 16 if jackpot
+        s["score"] += gain
+        s["turn_score"] += gain
+        if jackpot
+          [{ show: "JACKPOT!!", sub: "+#{commas(gain)} (x16)", palette: :GOLD, sound: :jackpot }]
+        elsif combo >= 8 && (combo & (combo - 1)).zero?
+          [{ show: "COMBO #{combo}!", sub: new_best ? "ALL-TIME BEST!" : "#{combo}-HIT CHAIN", palette: :FIRE, sound: :mega }]
+        else
+          [{ sound: combo >= FEVER_COMBO ? :hit : :nice }]
+        end
+      end
+
+      def failure(s)
+        broken = s["combo"] >= 4
+        s["combo"] = 0
+        [{ sound: broken ? :crack : :error }]
+      end
+
+      def stop(s, rng)
+        tools = s["turn_tools"]
+        score = s["turn_score"]
+        s["turn_tools"] = 0
+        s["turn_score"] = 0
+        # a plain answer (no tools) only gets a jingle
+        return [{ sound: :result }] if tools.zero?
+        [{ show: DONE.sample(random: rng), sub: "#{tools} TOOLS  +#{commas(score)}  COMBO #{s["combo"]}  BEST #{s["best"]}",
+           palette: :GOLD, sound: :mega }]
+      end
+
+      def commas(n) = n.to_s.reverse.scan(/\d{1,3}/).join(",").reverse
+    end
+
+    # Drawing on Claude Code's terminal from a hook process.
+    module Screen
+      module_function
+
+      # => [pid, "/dev/pts/N"] of the nearest ancestor that owns a terminal
+      def find(pid = Process.ppid)
+        while pid && pid > 1
+          tty = tty_of(pid)
+          return [pid, tty] if tty
+          pid = parent_of(pid)
+        end
+        nil
+      end
+
+      def tty_of(pid)
+        if File.directory?("/proc/#{pid}/fd")
+          [1, 2, 0].each do |fd|
+            t = (File.readlink("/proc/#{pid}/fd/#{fd}") rescue nil)
+            return t if t&.start_with?("/dev/pts/", "/dev/tty")
+          end
+          nil
+        else
+          t = `ps -o tty= -p #{pid.to_i} 2>/dev/null`.strip
+          t.empty? || t.start_with?("?", "-") ? nil : "/dev/#{t.delete_prefix("/dev/")}"
+        end
+      end
+
+      def parent_of(pid)
+        if File.exist?("/proc/#{pid}/stat")
+          File.read("/proc/#{pid}/stat")[/\) \S (\d+)/, 1]&.to_i
+        else
+          `ps -o ppid= -p #{pid.to_i} 2>/dev/null`.strip.then { |s| s.empty? ? nil : s.to_i }
+        end
+      rescue SystemCallError
+        nil
+      end
+
+      # Claude Code's fullscreen TUI already lives on the alternate screen;
+      # the classic one draws on the main screen.
+      def fullscreen?(cwd = Dir.pwd)
+        return false if truthy?(ENV["CLAUDE_CODE_DISABLE_ALTERNATE_SCREEN"])
+        return true if truthy?(ENV["CLAUDE_CODE_NO_FLICKER"])
+        tui = nil
+        [File.expand_path("~/.claude/settings.json"), File.join(cwd, ".claude/settings.json"),
+         File.join(cwd, ".claude/settings.local.json")].each do |f|
+          v = (JSON.parse(File.read(f))["tui"] rescue nil)
+          tui = v if v
+        end
+        tui == "fullscreen"
+      end
+
+      def truthy?(v) = !v.nil? && !%w[0 false no off].include?(v.to_s.downcase) && !v.empty?
+
+      def show(text, sub: nil, palette: :GOLD, sound: :mega, secs: 2.0, cwd: Dir.pwd)
+        _pid, path = find
+        return false unless path
+        require_relative "../dopairb"
+        # hooks of parallel tool calls take turns on the screen
+        FileUtils.mkdir_p(File.dirname(State.path))
+        lock = File.open("#{State.path}.lock", File::RDWR | File::CREAT, 0o644)
+        lock.flock(File::LOCK_EX)
+        tty = File.open(path, "r+")
+        tty.sync = true
+        Term.out = tty
+        Term.input = tty
+        rows, cols = tty.winsize
+        swap = !fullscreen?(cwd)
+        play(sound) if sound
+        ctx = Ctx.new(w: cols - 1, rows: rows, depth: Term.depth(Config.new), config: Config.new, rng: Random.new,
+                      input: nil, pre: 0.0, compact: false)
+        banner = Scenes::Banner.new(ctx, nil, text: text, sub: sub, palette: Color.const_get(palette),
+                                              mega: true, rainbow: true, alt: true)
+        tty.write(swap ? "\e[?1049h\e[?25l\e[2J" : "\e7\e[?25l\e[2J")
+        t0 = now
+        while (t = now - t0) < secs
+          c = Canvas.new(cols - 1, rows)
+          banner.draw(c, t)
+          lines = c.render(ctx.depth, shake: banner.shake(t))
+          tty.write("\e[H" + lines.map { |l| "#{l}\e[0m\e[K" }.join("\r\n"))
+          sleep [1 / 30.0 - (now - t0 - t), 0].max
+        end
+        if swap
+          tty.write("\e[0m\e[?1049l\e[?25h")
+        else
+          # A real size change makes the TUI lay everything out again.
+          tty.write("\e[0m\e[2J\e8")
+          tty.winsize = [rows, cols - 1]
+          sleep 0.08
+          tty.winsize = [rows, cols]
+        end
+        true
+      ensure
+        tty&.close
+        lock&.close
+      end
+
+      # Players outlive the hook process, which exits right away.
+      def play(name)
+        require_relative "../dopairb"
+        kind, argv = Sound.backend
+        return false unless kind
+        return Sound.log_play(argv[0], name, 0.0, 1.0) if kind == :log # recordings
+        path, = Sound.file(name)
+        cmd = if kind == :slow
+                win = IO.popen(["wslpath", "-w", path], err: File::NULL, &:read).strip
+                argv + ["(New-Object Media.SoundPlayer '#{win}').PlaySync()"]
+              else
+                argv + [path]
+              end
+        Process.detach(Process.spawn(*cmd, in: File::NULL, out: File::NULL, err: File::NULL, pgroup: true))
+        true
+      end
+
+      def now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+    end
+
+    # `dopacc install`: hooks (and a status line) in Claude Code's settings.
+    module Installer
+      module_function
+
+      def command
+        bin = File.join(Gem.bindir, "dopacc") if defined?(Gem)
+        exe = if bin && File.exist?(bin) then bin
+              elsif File.basename($PROGRAM_NAME) == "dopacc" then File.expand_path($PROGRAM_NAME)
+              else "dopacc"
+              end
+        exe.include?(" ") ? "\"#{exe}\"" : exe
+      end
+
+      def ours?(hook) = hook["command"].to_s.match?(/dopacc(\"?)? hook\z/)
+
+      def install(settings_path, statusline: true)
+        s = load(settings_path)
+        strip!(s)
+        hooks = (s["hooks"] ||= {})
+        HOOK_EVENTS.each do |ev|
+          (hooks[ev] ||= []) << { "matcher" => "", "hooks" => [{ "type" => "command", "command" => "#{command} hook", "timeout" => 15 }] }
+        end
+        notes = []
+        if statusline
+          if s["statusLine"].nil? || s["statusLine"]["command"].to_s.include?("dopacc")
+            s["statusLine"] = { "type" => "command", "command" => "#{command} statusline" }
+          else
+            notes << "kept your statusLine; `dopacc statusline` prints the COMBO line if you want to add it"
+          end
+        end
+        save(settings_path, s)
+        notes
+      end
+
+      def uninstall(settings_path)
+        s = load(settings_path)
+        strip!(s)
+        s.delete("statusLine") if s["statusLine"].to_h["command"].to_s.include?("dopacc")
+        save(settings_path, s)
+      end
+
+      def installed?(settings_path)
+        load(settings_path).fetch("hooks", {}).values.flatten.any? { |m| m.fetch("hooks", []).any? { |h| ours?(h) } }
+      end
+
+      def strip!(s)
+        hooks = s["hooks"] or return
+        hooks.each_value do |matchers|
+          matchers.each { |m| m["hooks"]&.reject! { |h| ours?(h) } }
+          matchers.reject! { |m| m["hooks"]&.empty? }
+        end
+        hooks.reject! { |_, v| v.empty? }
+        s.delete("hooks") if hooks.empty?
+      end
+
+      def load(path)
+        File.exist?(path) ? JSON.parse(File.read(path)) : {}
+      end
+
+      def save(path, s)
+        FileUtils.mkdir_p(File.dirname(path))
+        FileUtils.cp(path, "#{path}.bak") if File.exist?(path)
+        tmp = "#{path}.#{Process.pid}.tmp"
+        File.write(tmp, JSON.pretty_generate(s) + "\n")
+        File.rename(tmp, path)
+      end
+    end
+
+    # `dopacc statusline`: one line, no effects library, fast.
+    def self.statusline(s = State.read)
+      return "\e[2mdopacc off\e[0m" if s["mode"] == "off"
+      combo = s["combo"]
+      fever = combo >= FEVER_COMBO
+      head = fever ? rainbow("FEVER!") + " " : ""
+      "#{head}\e[1;38;2;255;170;60mCOMBO #{combo}\e[0m  \e[38;2;255;220;120mSCORE #{Hook.commas(s["score"])}\e[0m  " \
+        "\e[2mBEST #{s["best"]}#{s["mode"] == "calm" ? "  (calm)" : ""}\e[0m"
+    end
+
+    def self.rainbow(str)
+      t = Time.now.to_f * 2
+      str.chars.each_with_index.map do |ch, i|
+        h = (t + i * 0.15) % 1.0
+        r, g, b = [0, 2, 4].map { |k| (Math.sin((h + k / 6.0) * 2 * Math::PI) * 127 + 128).round }
+        "\e[1;38;2;#{r};#{g};#{b}m#{ch}"
+      end.join + "\e[0m"
+    end
+  end
+end

data/lib/dopairb/cli.rb

@@ -15,13 +15,13 @@ module Dopairb
         o.separator ""
         o.separator "IRB with fireworks. Every other option is handed to IRB."
         o.separator ""
-        o.on("--intensity=LEVEL", Config::INTENSITIES.map(&:to_s), "off / low / normal (default) / max") { |v| settings << [:intensity, v] }
+        o.on("--intensity=LEVEL", Config::INTENSITIES.map(&:to_s), "off / low / normal / max (default)") { |v| settings << [:intensity, v] }
         o.on("--calm", "low intensity, no flash, shorter effects") { settings.concat([[:intensity, :low], [:flash, :off], [:duration, 0.7]]) }
-        o.on("--max", "everything at maximum") { settings << [:intensity, :max] }
+        o.on("--max", "everything at maximum (the default)") { settings << [:intensity, :max] }
         o.on("--party", "max + full-screen flash + sound effects") { settings.concat([[:intensity, :max], [:flash, :full], [:sound, :sfx]]) }
         o.on("--[no-]flash[=MODE]", "flash: off / soft (default) / full") { |v| settings << [:flash, v.nil? ? :soft : (v == false ? :off : v)] }
         o.on("--[no-]motion", "animations (default on)") { |v| settings << [:motion, v] }
-        o.on("--[no-]sound[=MODE]", "sound: off (default) / bell / sfx") { |v| settings << [:sound, v.nil? ? :sfx : (v == false ? :off : v)] }
+        o.on("--[no-]sound[=MODE]", "sound: off / bell / sfx (default)") { |v| settings << [:sound, v.nil? ? :sfx : (v == false ? :off : v)] }
         o.on("--[no-]hud", "COMBO / SCORE next to the prompt (default on)") { |v| settings << [:hud, v] }
         o.on("--[no-]keys", "per-keystroke effects (default on)") { |v| settings << [:keys, v] }
         o.on("--[no-]intro", "title animation (default on)") { |v| settings << [:intro, v] }
@@ -61,9 +61,7 @@ module Dopairb
       ours, irb_args = split_args(argv.dup)
       settings = []
       parser(settings).parse!(ours)
-      settings.each do |k, v|
-        k == :string ? Dopairb.config.apply_string(v) : Dopairb.config.set(k, v)
-      end
+      settings.each { |k, v| Dopairb.override(k, v) }
       run_irb(irb_args)
     rescue OptionParser::ParseError, ArgumentError => e
       warn "dopairb: #{e.message}"

data/lib/dopairb/config.rb

@@ -21,15 +21,16 @@ module Dopairb
       charge: "seconds (max 0.3) of wind-up before a fast result lands; 0 disables",
       intro: "on / off  -- title animation at startup",
       keys: "on / off  -- per-keystroke effects while typing",
+      binding_irb: "on / off  -- effects in sessions opened by binding.irb too",
     }.freeze
 
-    attr_reader :intensity, :motion, :flash, :sound, :hud, :duration, :color, :trail, :charge, :intro, :keys
+    attr_reader :intensity, :motion, :flash, :sound, :hud, :duration, :color, :trail, :charge, :intro, :keys, :binding_irb
 
     def initialize
-      @intensity = :normal
+      @intensity = :max
       @motion = true
       @flash = :soft
-      @sound = :off
+      @sound = :sfx
       @hud = true
       @duration = 1.0
       @color = :auto
@@ -37,6 +38,7 @@ module Dopairb
       @charge = 0.12
       @intro = true
       @keys = true
+      @binding_irb = true
     end
 
     def level
@@ -60,7 +62,7 @@ module Dopairb
       when :sound
         v = bool_or_nil(value)
         @sound = v.nil? ? enum(value, SOUNDS, name) : (v ? :sfx : :off)
-      when :motion, :hud, :intro, :keys
+      when :motion, :hud, :intro, :keys, :binding_irb
         v = bool_or_nil(value)
         raise ArgumentError, "#{name} expects on/off, got #{value.inspect}" if v.nil?
         instance_variable_set(:"@#{name}", v)