kward 0.66.0

data/lib/kward/prompts/commands.rb

@@ -0,0 +1,50 @@
+require_relative "../config_files"
+
+module Kward
+  module PromptCommands
+    BUILTIN_COMMANDS = [
+      { name: "exit", description: "Exit the interactive session.", argument_hint: "" },
+      { name: "quit", description: "Exit the interactive session.", argument_hint: "" },
+      { name: "new", description: "Start a new session.", argument_hint: "" },
+      { name: "resume", description: "Resume a saved session.", argument_hint: "[path]" },
+      { name: "name", description: "Name or clear the current session.", argument_hint: "[name]" },
+      { name: "clone", description: "Clone the current session.", argument_hint: "" },
+      { name: "copy", description: "Copy clean session text to the clipboard.", argument_hint: "[last|transcript]" },
+      { name: "export", description: "Export the current session as Markdown.", argument_hint: "[path]" },
+      { name: "compact", description: "Compact the current conversation context.", argument_hint: "[instructions]" },
+      { name: "redraw", description: "Refresh the visible terminal.", argument_hint: "" },
+      { name: "settings", description: "Configure prompt overlays.", argument_hint: "" },
+      { name: "login", description: "Log in with an OAuth provider.", argument_hint: "" },
+      { name: "model", description: "Select the default model.", argument_hint: "" },
+      { name: "openrouter/catalog", description: "List the full OpenRouter model catalog.", argument_hint: "" },
+      { name: "reasoning", description: "Select reasoning effort.", argument_hint: "" },
+      { name: "status", description: "Show the current status message.", argument_hint: "" },
+      { name: "stats", description: "Show telemetry logging stats.", argument_hint: "[range]" },
+      { name: "crew", description: "Reserved for future crew commands.", argument_hint: "" },
+      { name: "memory", description: "Inspect and manage Kward memory.", argument_hint: "[enable|disable|auto-summary|core|add|list|forget|promote|inspect|why|summarize]" }
+    ].freeze
+    BUILTIN_RESERVED_COMMAND_NAMES = BUILTIN_COMMANDS.map { |command| command[:name] }.freeze
+    SLASH_COMMAND_PATTERN = %r{\A/(\S+)(?:\s+(.*))?\z}m
+
+    module_function
+
+    def parse(input)
+      match = input.to_s.match(SLASH_COMMAND_PATTERN)
+      return nil unless match
+
+      [match[1], match[2].to_s]
+    end
+
+    def expand(input, templates: nil, reserved_commands: BUILTIN_RESERVED_COMMAND_NAMES)
+      parsed = parse(input)
+      return nil unless parsed
+
+      command, arguments = parsed
+      templates ||= ConfigFiles.prompt_templates(reserved_commands: reserved_commands)
+      template = templates.find { |candidate| candidate.command == command }
+      return nil unless template
+
+      template.expand(arguments)
+    end
+  end
+end

data/lib/kward/prompts/templates.rb

@@ -0,0 +1,60 @@
+module Kward
+  module Prompts
+    class Templates
+      def initialize(config_dir:, template_class:, markdown_parser:)
+        @config_dir = config_dir
+        @template_class = template_class
+        @markdown_parser = markdown_parser
+      end
+
+      def prompt_templates(reserved_commands: [])
+        prompts_root = File.join(@config_dir, "prompts")
+        return [] unless Dir.exist?(prompts_root)
+
+        reserved = reserved_commands.map(&:to_s)
+        seen = {}
+        Dir.glob(File.join(prompts_root, "*.md")).sort.filter_map do |path|
+          template = parse_prompt_template(path)
+          next unless template
+
+          if reserved.include?(template.command)
+            warn "Warning: skipping Kward prompt command /#{template.command}: reserved command"
+            next
+          end
+          if seen[template.command]
+            warn "Warning: skipping duplicate Kward prompt command /#{template.command}: #{path}"
+            next
+          end
+
+          seen[template.command] = true
+          template
+        end
+      rescue StandardError => e
+        warn "Warning: skipping Kward prompt templates in #{prompts_root}: #{e.message}"
+        []
+      end
+
+      private
+
+      def parse_prompt_template(path)
+        command = File.basename(path, ".md")
+        unless command.match?(/\A[A-Za-z0-9][A-Za-z0-9_-]*\z/)
+          warn "Warning: skipping Kward prompt template #{path}: invalid command name"
+          return nil
+        end
+
+        frontmatter, body = @markdown_parser.call(path)
+        @template_class.new(
+          command: command,
+          description: frontmatter.fetch("description", "").to_s.strip,
+          argument_hint: frontmatter.fetch("argument-hint", "").to_s.strip,
+          body: body,
+          path: path
+        )
+      rescue StandardError => e
+        warn "Warning: skipping Kward prompt template #{path}: #{e.message}"
+        nil
+      end
+    end
+  end
+end

data/lib/kward/prompts.rb

@@ -0,0 +1,58 @@
+require_relative "config_files"
+
+module Kward
+  module Prompts
+    module_function
+
+    def system_message(workspace_root: Dir.pwd, include_workspace_personality: true, model: nil, reasoning_effort: nil, now: Time.now, memory_context: nil, plugin_context: nil)
+      {
+        role: "system",
+        content: prompt_parts(workspace_root: workspace_root, include_workspace_personality: include_workspace_personality, model: model, reasoning_effort: reasoning_effort, now: now, memory_context: memory_context, plugin_context: plugin_context).compact.join("\n\n")
+      }
+    end
+
+    def prompt_parts(workspace_root: Dir.pwd, include_workspace_personality: true, model: nil, reasoning_effort: nil, now: Time.now, memory_context: nil, plugin_context: nil)
+      parts = [base_prompt, config_agents_prompt]
+      parts << memory_context unless memory_context.to_s.empty?
+      parts << persona_prompt(workspace_root, model: model, reasoning_effort: reasoning_effort, now: now) if include_workspace_personality
+      parts << plugin_context unless plugin_context.to_s.empty? || !include_workspace_personality
+      parts << skills_prompt
+      parts << workspace_agents_prompt(workspace_root)
+      parts
+    end
+
+    def base_prompt
+      <<~PROMPT.strip
+        You are Kward, a concise practical CLI coding agent. You are allowed to use the tools. Help users understand and modify software projects. Inspect files before changing them, make the smallest correct change, preserve existing style, and summarize what changed. Be honest about limitations.
+      PROMPT
+    end
+
+    def config_agents_prompt
+      ConfigFiles.agents_prompt
+    end
+
+    def persona_prompt(workspace_root = Dir.pwd, model: nil, reasoning_effort: nil, now: Time.now)
+      ConfigFiles.persona_prompt(workspace_root, model: model, reasoning_effort: reasoning_effort, now: now)
+    end
+
+    def workspace_agents_prompt(workspace_root = Dir.pwd)
+      ConfigFiles.workspace_agents_prompt(workspace_root)
+    end
+
+    def skills_prompt
+      skills = ConfigFiles.skills
+      return nil if skills.empty?
+
+      lines = [
+        "Configured skills are available in the Kward config directory.",
+        "When a task matches a skill, use read_skill to load its instructions before proceeding.",
+        "Available skills:"
+      ]
+      skills.each do |skill|
+        description = skill.description.empty? ? "No description provided." : skill.description
+        lines << "- #{skill.name}: #{description}"
+      end
+      lines.join("\n")
+    end
+  end
+end

data/lib/kward/resources/avatar_kward_logo.rb

@@ -0,0 +1,48 @@
+# Generated from avatar_kward_32x32.png as RGB terminal cells.
+# The interactive banner uses this data instead of decoding a PNG at runtime.
+module Kward
+  module Resources
+    module AvatarKwardLogo
+      PIXELS = [
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, [36, 40, 24], [39, 42, 25], [39, 42, 25], [33, 36, 21], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, [33, 36, 23], [78, 86, 52], [85, 93, 56], [84, 93, 55], [65, 72, 43], [31, 33, 19], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, [49, 54, 33], [78, 86, 52], [85, 93, 56], [85, 93, 56], [85, 93, 56], [84, 93, 55], [75, 83, 49], [35, 38, 23], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, [61, 68, 40], [80, 88, 53], [85, 93, 56], [75, 83, 49], [72, 80, 48], [70, 78, 46], [78, 86, 52], [84, 93, 55], [76, 85, 51], [50, 55, 34], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, [42, 46, 27], [80, 88, 53], [84, 93, 55], [70, 78, 46], [23, 25, 15], [37, 38, 29], [34, 35, 26], [33, 37, 22], [74, 81, 48], [83, 92, 55], [78, 86, 52], [24, 26, 15], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, [34, 37, 22], [83, 92, 55], [85, 93, 56], [69, 77, 46], [18, 19, 12], [53, 53, 45], [135, 132, 115], [128, 125, 111], [40, 40, 36], [21, 23, 14], [72, 80, 48], [80, 88, 53], [39, 44, 26], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, [18, 20, 13], [58, 63, 38], [85, 93, 56], [55, 61, 36], [23, 25, 15], [43, 42, 35], [146, 142, 129], [176, 173, 156], [179, 175, 159], [146, 142, 129], [67, 65, 58], [27, 30, 19], [62, 68, 41], [80, 88, 53], [54, 60, 35], nil, nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, [23, 26, 16], [74, 81, 48], [69, 77, 46], [21, 23, 14], [31, 31, 25], [108, 105, 91], [153, 150, 134], [134, 132, 118], [173, 169, 154], [183, 179, 163], [134, 132, 118], [27, 26, 21], [25, 28, 16], [70, 78, 46], [72, 80, 48], [21, 23, 14], nil, nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, [8, 10, 6], [66, 73, 45], [58, 63, 37], [14, 15, 9], [3, 3, 2], [87, 85, 74], [160, 157, 139], [160, 157, 139], [134, 132, 118], [80, 78, 69], [173, 169, 154], [175, 171, 155], [76, 74, 65], [5, 5, 4], [14, 15, 9], [63, 70, 42], [66, 73, 45], [2, 3, 2], nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, [18, 19, 12], [59, 65, 40], [23, 23, 21], [0, 0, 0], [100, 98, 86], [160, 157, 139], [163, 160, 143], [138, 136, 121], [70, 68, 58], [173, 169, 154], [175, 171, 155], [183, 179, 163], [179, 175, 159], [92, 90, 82], [1, 1, 1], [27, 30, 19], [62, 68, 41], [16, 17, 11], nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, [15, 15, 11], [62, 68, 42], [72, 70, 61], [87, 85, 74], [44, 43, 36], [77, 76, 65], [108, 105, 91], [149, 146, 130], [123, 119, 105], [158, 155, 140], [168, 164, 149], [144, 140, 126], [160, 156, 142], [118, 115, 104], [77, 76, 65], [53, 53, 45], [103, 102, 85], [76, 74, 65], [66, 72, 43], [20, 20, 13], nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, [35, 38, 23], [78, 86, 52], [135, 132, 115], [113, 109, 94], [129, 128, 109], [23, 25, 15], [33, 55, 8], [96, 108, 72], [87, 85, 74], [168, 164, 149], [158, 155, 140], [97, 94, 83], [96, 108, 72], [24, 40, 6], [30, 33, 20], [142, 141, 122], [104, 102, 90], [153, 150, 134], [75, 83, 49], [37, 41, 25], nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, [2, 2, 1], [63, 70, 42], [87, 95, 60], [134, 132, 118], [77, 76, 65], [104, 102, 90], [5, 5, 4], [72, 133, 6], [100, 184, 10], [39, 44, 26], [160, 156, 142], [146, 142, 129], [47, 70, 19], [103, 188, 10], [56, 105, 5], [10, 10, 8], [128, 125, 111], [72, 70, 61], [149, 146, 130], [84, 93, 55], [54, 60, 36], [2, 3, 2], nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, [46, 51, 30], [67, 74, 44], [44, 48, 30], [114, 111, 97], [80, 78, 69], [103, 102, 85], [34, 35, 26], [33, 55, 8], [59, 97, 13], [82, 84, 65], [166, 162, 147], [156, 152, 138], [76, 85, 51], [59, 97, 13], [29, 46, 8], [43, 42, 35], [134, 132, 118], [92, 90, 82], [128, 125, 111], [39, 44, 26], [65, 72, 43], [43, 48, 29], nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, [17, 19, 12], [63, 70, 42], [31, 35, 21], [5, 5, 4], [39, 39, 33], [70, 68, 58], [53, 53, 45], [103, 102, 85], [58, 56, 48], [77, 76, 65], [113, 109, 94], [171, 167, 151], [163, 160, 143], [108, 105, 91], [72, 70, 61], [64, 62, 54], [108, 105, 91], [59, 58, 50], [84, 82, 71], [39, 39, 33], [3, 3, 2], [39, 44, 26], [58, 64, 39], nil, nil, nil, nil, nil],
+        [nil, nil, nil, [2, 3, 2], [43, 47, 28], [68, 75, 45], [15, 17, 11], [0, 0, 0], [0, 0, 0], [8, 8, 7], [12, 12, 11], [59, 58, 50], [92, 89, 75], [27, 26, 21], [100, 96, 82], [171, 167, 151], [163, 160, 143], [70, 68, 58], [44, 43, 36], [114, 111, 97], [58, 56, 48], [15, 14, 13], [5, 5, 4], [0, 0, 0], [0, 0, 0], [23, 25, 15], [69, 77, 46], [30, 33, 20], nil, nil, nil, nil],
+        [nil, nil, nil, [37, 41, 26], [63, 70, 42], [27, 30, 19], [1, 1, 1], [0, 0, 0], [8, 8, 7], [32, 33, 30], [20, 20, 18], [6, 6, 5], [64, 62, 54], [31, 31, 25], [100, 96, 82], [171, 167, 151], [163, 160, 143], [70, 68, 58], [51, 49, 43], [70, 68, 58], [6, 6, 5], [23, 23, 21], [35, 35, 33], [6, 6, 5], [0, 0, 0], [1, 1, 1], [33, 37, 22], [58, 63, 37], [32, 35, 21], nil, nil, nil],
+        [nil, nil, nil, [52, 58, 35], [80, 88, 53], [52, 58, 34], [10, 10, 8], [5, 5, 4], [32, 33, 30], [23, 23, 21], [0, 0, 0], [23, 23, 21], [59, 58, 50], [70, 68, 58], [72, 70, 61], [166, 162, 147], [153, 150, 134], [67, 65, 58], [76, 74, 65], [62, 61, 57], [19, 19, 17], [0, 0, 0], [31, 31, 25], [32, 33, 30], [3, 3, 2], [15, 17, 11], [55, 61, 36], [80, 88, 53], [39, 42, 25], nil, nil, nil],
+        [nil, nil, nil, [23, 24, 16], [54, 60, 36], [83, 92, 55], [27, 30, 19], [44, 44, 40], [19, 19, 17], [1, 1, 1], [1, 1, 1], [49, 48, 45], [44, 44, 40], [103, 102, 85], [44, 44, 40], [158, 155, 140], [144, 140, 126], [64, 62, 54], [92, 89, 75], [49, 48, 45], [40, 40, 36], [0, 0, 0], [3, 3, 2], [19, 19, 17], [49, 48, 45], [36, 40, 24], [83, 92, 55], [44, 48, 30], [23, 25, 16], nil, nil, nil],
+        [nil, nil, nil, [50, 55, 34], [49, 54, 33], [62, 68, 41], [67, 74, 44], [30, 33, 20], [12, 12, 11], [30, 30, 28], [20, 20, 18], [30, 30, 28], [12, 12, 11], [92, 89, 75], [51, 49, 43], [160, 156, 142], [144, 140, 126], [64, 62, 54], [77, 76, 65], [12, 12, 11], [35, 35, 33], [17, 17, 16], [35, 35, 33], [10, 10, 8], [34, 35, 26], [68, 75, 45], [58, 63, 37], [51, 56, 34], [43, 48, 29], nil, nil, nil],
+        [nil, nil, [30, 33, 21], [68, 75, 45], [70, 78, 46], [39, 44, 26], [59, 65, 40], [67, 74, 44], [21, 23, 14], [8, 8, 7], [19, 19, 17], [32, 33, 30], [10, 10, 8], [15, 14, 13], [92, 89, 75], [168, 164, 149], [160, 157, 139], [70, 68, 58], [12, 12, 11], [10, 10, 8], [35, 35, 33], [17, 17, 16], [10, 10, 8], [21, 23, 14], [72, 80, 48], [55, 61, 36], [47, 52, 31], [72, 80, 48], [66, 72, 43], [25, 26, 18], nil, nil],
+        [nil, nil, [22, 24, 14], [27, 30, 18], [55, 61, 36], [84, 93, 55], [44, 48, 30], [54, 60, 36], [74, 81, 48], [25, 28, 16], [1, 1, 1], [49, 48, 45], [32, 33, 30], [1, 1, 1], [92, 89, 75], [123, 119, 105], [118, 115, 104], [67, 63, 54], [1, 1, 1], [44, 44, 40], [40, 40, 36], [1, 1, 1], [30, 33, 20], [76, 85, 51], [52, 58, 34], [51, 56, 34], [81, 90, 54], [47, 52, 31], [26, 28, 17], nil, nil, nil],
+        [nil, [30, 33, 21], [66, 72, 43], [80, 88, 53], [80, 88, 53], [45, 50, 29], [33, 37, 22], [51, 56, 34], [42, 47, 27], [68, 75, 45], [38, 42, 25], [19, 19, 17], [35, 35, 33], [12, 12, 11], [37, 35, 30], [70, 68, 58], [67, 63, 54], [27, 26, 21], [17, 17, 16], [35, 35, 33], [17, 17, 16], [39, 44, 26], [70, 78, 46], [42, 47, 27], [54, 60, 36], [31, 35, 21], [31, 35, 21], [63, 70, 42], [78, 86, 52], [65, 71, 42], nil, nil],
+        [nil, [14, 15, 9], [36, 39, 23], [63, 70, 42], [81, 90, 54], [62, 68, 41], [51, 56, 34], [39, 44, 26], [14, 15, 9], [49, 54, 33], [69, 77, 46], [25, 28, 16], [20, 20, 18], [8, 8, 7], [6, 6, 5], [43, 42, 35], [37, 35, 30], [3, 3, 2], [12, 12, 11], [19, 19, 17], [30, 33, 20], [70, 78, 46], [44, 48, 30], [14, 15, 9], [44, 48, 30], [49, 54, 33], [52, 58, 34], [72, 80, 48], [54, 60, 36], [36, 39, 23], [12, 14, 11], nil],
+        [nil, [5, 5, 5], nil, [53, 58, 35], [84, 93, 55], [84, 93, 55], [81, 90, 54], [69, 77, 46], [55, 61, 36], [15, 17, 11], [39, 44, 26], [68, 75, 45], [59, 65, 40], [18, 19, 12], [10, 10, 8], [62, 61, 57], [56, 55, 53], [6, 6, 5], [23, 25, 15], [63, 70, 42], [69, 77, 46], [36, 40, 24], [15, 17, 11], [58, 63, 37], [67, 74, 44], [80, 88, 53], [84, 93, 55], [83, 92, 55], [39, 43, 26], nil, [2, 2, 1], nil],
+        [nil, nil, nil, [25, 29, 18], [45, 50, 29], [27, 30, 19], [22, 25, 15], [75, 83, 50], [84, 93, 55], [54, 60, 36], [15, 17, 11], [18, 19, 12], [42, 47, 27], [74, 81, 48], [12, 12, 11], [23, 23, 21], [19, 19, 17], [30, 33, 20], [74, 81, 48], [38, 42, 25], [15, 17, 11], [15, 17, 11], [62, 68, 41], [83, 92, 55], [21, 23, 14], [33, 37, 22], [49, 54, 33], [21, 23, 14], nil, nil, nil, [4, 4, 4]],
+        [nil, nil, nil, [64, 71, 42], [43, 47, 28], [7, 7, 4], nil, [51, 56, 35], [83, 92, 55], [70, 78, 46], [47, 52, 31], [38, 42, 25], [31, 35, 21], [54, 60, 36], [17, 17, 16], [51, 51, 48], [46, 46, 43], [27, 30, 19], [52, 58, 34], [30, 33, 20], [39, 44, 26], [49, 54, 33], [76, 85, 51], [85, 93, 56], [43, 48, 29], [14, 14, 10], [8, 8, 7], [49, 54, 33], [62, 67, 41], nil, nil, nil],
+        [nil, nil, nil, [34, 38, 24], [37, 39, 24], nil, nil, [34, 37, 22], [75, 83, 50], [35, 39, 24], [1, 1, 1], [43, 48, 29], [66, 72, 43], [20, 21, 12], [3, 1, 1], [2, 2, 2], [2, 2, 2], [3, 3, 3], [27, 30, 18], [66, 72, 43], [35, 38, 23], [2, 1, 1], [42, 46, 28], [76, 85, 51], [5, 5, 4], nil, [2, 3, 2], [36, 40, 24], [22, 25, 15], nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, [14, 15, 10], [67, 74, 44], [29, 32, 19], nil, nil, nil, [25, 29, 18], nil, nil, nil, nil, nil, nil, [23, 25, 16], nil, nil, nil, [29, 32, 19], [52, 58, 35], nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, [22, 24, 15], nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, [23, 26, 16], nil, nil, nil, nil, nil, nil, nil],
+        [nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil, nil],
+      ]
+
+      PIXELS.each do |row|
+        row.each { |color| color.freeze if color }
+        row.freeze
+      end
+      PIXELS.freeze
+    end
+  end
+end

data/lib/kward/resources/pixel_logo.rb

@@ -0,0 +1,230 @@
+require "zlib"
+
+module Kward
+  module PixelLogo
+    PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+    TRANSPARENT_ALPHA = 128
+
+    module_function
+
+    def rows_from_png(path, width:, height:)
+      rows_from_pixels(indexed_png_pixels(path), width: width, height: height)
+    rescue StandardError
+      []
+    end
+
+    def rows_from_pixels(pixels, width:, height:)
+      scaled = scale_pixels(pixels, width: width, height: height)
+      render_rows(scaled)
+    rescue StandardError
+      []
+    end
+
+    def half_block_rows_from_png(path, width:, pixel_height:)
+      half_block_rows_from_pixels(indexed_png_pixels(path), width: width, pixel_height: pixel_height)
+    rescue StandardError
+      []
+    end
+
+    def half_block_rows_from_pixels(pixels, width:, pixel_height:)
+      scaled = scale_pixels(pixels, width: width, height: pixel_height)
+      render_half_block_rows(scaled)
+    rescue StandardError
+      []
+    end
+
+    def indexed_png_pixels(path)
+      data = File.binread(path)
+      raise "Invalid PNG" unless data.start_with?(PNG_SIGNATURE)
+
+      png_width = nil
+      png_height = nil
+      bit_depth = nil
+      color_type = nil
+      interlace = nil
+      palette = nil
+      transparency = []
+      idat = +"".b
+
+      each_chunk(data) do |type, chunk|
+        case type
+        when "IHDR"
+          png_width, png_height, bit_depth, color_type, _compression, _filter, interlace = chunk.unpack("NNCCCCC")
+        when "PLTE"
+          palette = chunk.bytes.each_slice(3).map { |red, green, blue| [red, green, blue, 255] }
+        when "tRNS"
+          transparency = chunk.bytes
+        when "IDAT"
+          idat << chunk
+        end
+      end
+
+      raise "Unsupported PNG" unless png_width && png_height && palette
+      raise "Unsupported PNG" unless bit_depth == 8 && color_type == 3 && interlace == 0
+
+      transparency.each_with_index do |alpha, index|
+        palette[index] = palette[index][0, 3] + [alpha] if palette[index]
+      end
+
+      unfilter_indexed_rows(Zlib::Inflate.inflate(idat), png_width, png_height).map do |row|
+        row.map { |index| palette[index] || [0, 0, 0, 0] }
+      end
+    end
+
+    def each_chunk(data)
+      offset = PNG_SIGNATURE.bytesize
+      while offset < data.bytesize
+        length = data[offset, 4].unpack1("N")
+        type = data[offset + 4, 4]
+        chunk = data[offset + 8, length]
+        yield type, chunk
+        offset += length + 12
+      end
+    end
+
+    def unfilter_indexed_rows(raw, width, height)
+      rows = []
+      previous = Array.new(width, 0)
+      offset = 0
+
+      height.times do
+        filter = raw.getbyte(offset)
+        offset += 1
+        scanline = raw.byteslice(offset, width).bytes
+        offset += width
+        row = unfilter_scanline(scanline, previous, filter)
+        rows << row
+        previous = row
+      end
+
+      rows
+    end
+
+    def unfilter_scanline(scanline, previous, filter)
+      row = []
+      scanline.each_with_index do |byte, index|
+        left = index.zero? ? 0 : row[index - 1]
+        up = previous[index] || 0
+        up_left = index.zero? ? 0 : previous[index - 1]
+        row << case filter
+               when 0 then byte
+               when 1 then (byte + left) & 0xff
+               when 2 then (byte + up) & 0xff
+               when 3 then (byte + ((left + up) / 2)) & 0xff
+               when 4 then (byte + paeth(left, up, up_left)) & 0xff
+               else byte
+               end
+      end
+      row
+    end
+
+    def paeth(left, up, up_left)
+      estimate = left + up - up_left
+      left_distance = (estimate - left).abs
+      up_distance = (estimate - up).abs
+      up_left_distance = (estimate - up_left).abs
+      return left if left_distance <= up_distance && left_distance <= up_left_distance
+      return up if up_distance <= up_left_distance
+
+      up_left
+    end
+
+    def scale_pixels(pixels, width:, height:)
+      source_height = pixels.length
+      source_width = pixels.first.length
+
+      height.times.map do |target_y|
+        source_y_start = target_y * source_height / height
+        source_y_end = [(target_y + 1) * source_height / height, source_y_start + 1].max
+        width.times.map do |target_x|
+          source_x_start = target_x * source_width / width
+          source_x_end = [(target_x + 1) * source_width / width, source_x_start + 1].max
+          dominant_color(pixels, source_x_start...source_x_end, source_y_start...source_y_end)
+        end
+      end
+    end
+
+    def dominant_color(pixels, x_range, y_range)
+      counts = Hash.new(0)
+      y_range.each do |y|
+        x_range.each do |x|
+          counts[visible_color(pixels[y][x])] += 1
+        end
+      end
+      counts.max_by { |_color, count| count }&.first
+    end
+
+    def visible_color(color)
+      return nil unless color
+
+      red, green, blue, alpha = color
+      return nil if !alpha.nil? && alpha.to_i < TRANSPARENT_ALPHA
+
+      [red, green, blue]
+    end
+
+    def render_rows(rows)
+      rows.map do |row|
+        current = nil
+        rendered = +""
+        row.each do |color|
+          if color != current
+            rendered << background_sgr(color)
+            current = color
+          end
+          rendered << " "
+        end
+        rendered << reset_sgr if current
+        rendered
+      end
+    end
+
+    def render_half_block_rows(rows)
+      rows.each_slice(2).map do |top_row, bottom_row|
+        bottom_row ||= Array.new(top_row.length)
+        current_foreground = nil
+        current_background = nil
+        rendered = +""
+        top_row.each_with_index do |top, index|
+          bottom = bottom_row[index]
+          foreground, background, glyph = half_block_cell(top, bottom)
+          if background != current_background
+            rendered << background_sgr(background)
+            current_background = background
+          end
+          if foreground != current_foreground
+            rendered << foreground_sgr(foreground)
+            current_foreground = foreground
+          end
+          rendered << glyph
+        end
+        rendered << reset_sgr if current_foreground || current_background
+        rendered
+      end
+    end
+
+    def half_block_cell(top, bottom)
+      if top && bottom
+        [top, bottom, "▀"]
+      elsif top
+        [top, nil, "▀"]
+      elsif bottom
+        [bottom, nil, "▄"]
+      else
+        [nil, nil, " "]
+      end
+    end
+
+    def foreground_sgr(color)
+      color ? "\e[38;2;#{color.join(";")}m" : "\e[39m"
+    end
+
+    def background_sgr(color)
+      color ? "\e[48;2;#{color.join(";")}m" : "\e[49m"
+    end
+
+    def reset_sgr
+      "\e[0m"
+    end
+  end
+end