kotoshu 0.3.0

data/lib/kotoshu/integrity/audit_log.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+require "fileutils"
+
+module Kotoshu
+  module Integrity
+    # Append-only JSON audit log of every resource download.
+    #
+    # Each entry is one JSON object per line, written to `audit.log`
+    # under the configured Kotoshu home directory. The log is consulted
+    # by users when investigating "what did Kotoshu fetch?" and by CI
+    # for reproducibility audits.
+    #
+    # Statuses:
+    #   "verified"    — content matched manifest entry's SHA-256
+    #   "unverified"  — no manifest entry available; bytes trusted as-is
+    #   "mismatch"    — SHA-256 mismatch (also raises IntegrityError)
+    #   "missing"     — attempted download failed (network, 404, etc.)
+    #
+    # The log is opened, appended, and closed per entry — no long-lived
+    # file handle. Writes are line-buffered and fsync'd so the record
+    # survives a crash mid-batch.
+    class AuditLog
+      # Default location: $XDG_DATA_HOME/kotoshu/audit.log
+      # (~/.local/share/kotoshu/audit.log), or $KOTOSHU_AUDIT_LOG.
+      def self.default_path
+        Kotoshu::Paths.audit_log_path
+      end
+
+      attr_reader :path
+
+      def initialize(path: self.class.default_path)
+        @path = path
+      end
+
+      # Record one download attempt. Returns the written entry hash.
+      #
+      # @param url [String] Source URL
+      # @param size [Integer, nil] Bytes downloaded (nil on missing)
+      # @param sha256 [String, nil] Computed SHA-256 of bytes (nil on missing)
+      # @param manifest_sha256 [String, nil] Expected SHA-256 from manifest
+      # @param status [String] One of: verified, unverified, mismatch, missing
+      # @param resource_id [String, nil] Caller-supplied resource identifier
+      def record(url:, status:, size: nil, sha256: nil,
+                 manifest_sha256: nil, resource_id: nil)
+        entry = {
+          timestamp: Time.now.utc.iso8601,
+          url: url,
+          resource_id: resource_id,
+          size: size,
+          sha256: sha256,
+          manifest_sha256: manifest_sha256,
+          status: status
+        }
+        FileUtils.mkdir_p(File.dirname(@path))
+        File.open(@path, "a", encoding: "UTF-8") do |f|
+          f.flock(File::LOCK_EX)
+          f.write("#{entry.to_json}\n")
+          f.fsync
+        end
+        entry
+      end
+
+      # Iterate every recorded entry (parsed Hashes).
+      def each
+        return enum_for(:each) unless block_given?
+        return unless File.exist?(@path)
+
+        File.foreach(@path, encoding: "UTF-8") do |line|
+          line = line.strip
+          next if line.empty?
+
+          yield JSON.parse(line)
+        end
+      end
+
+      def entries
+        each.to_a
+      end
+
+      def clear!
+        FileUtils.rm_f(@path)
+      end
+    end
+  end
+end

data/lib/kotoshu/integrity/manifest.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "json"
+require "digest"
+require_relative "../core/exceptions"
+
+module Kotoshu
+  module Integrity
+    # Parsed view of a content repo's `manifest.json`.
+    #
+    # Format (per TODO.impl/09-integrity-security.md task 1):
+    #
+    #   {
+    #     "version": 1,
+    #     "generated_at": "2026-06-25T10:00:00Z",
+    #     "resources": {
+    #       "en/spelling/index.dic": {
+    #         "size": 49568,
+    #         "sha256": "ab12...",
+    #         "language": "en",
+    #         "type": "spelling",
+    #         "license": "LGPL/MPL/GPL",
+    #         "source": "SCROLL"
+    #       }
+    #     }
+    #   }
+    #
+    # Construction:
+    #
+    #   manifest = Manifest.parse(json_string)
+    #   manifest.fetch("en/spelling/index.dic")  # => Entry or nil
+    #   manifest.verify_content!("en/spelling/index.dic", bytes) # raises on mismatch
+    #
+    # `Manifest.load(url, http:)`, returns nil when the manifest 404s (graceful
+    # degradation — see module docs).
+    class Manifest
+      Entry = Struct.new(:path, :sha256, :size, :language, :type, :license, :source,
+                         keyword_init: true) do
+        def verify?(content)
+          Digest::SHA256.hexdigest(content) == sha256
+        end
+      end
+
+      # Parse a manifest JSON string. Returns an empty Manifest if the JSON
+      # is parseable but has no resources (caller treats as "no constraints").
+      def self.parse(json)
+        data = JSON.parse(json)
+        entries = {}
+        (data["resources"] || {}).each do |path, fields|
+          entries[path] = Entry.new(
+            path: path,
+            sha256: fields["sha256"],
+            size: fields["size"],
+            language: fields["language"],
+            type: fields["type"],
+            license: fields["license"],
+            source: fields["source"]
+          )
+        end
+        new(entries, version: data["version"], generated_at: data["generated_at"])
+      rescue JSON::ParserError => e
+        raise Kotoshu::IntegrityError.new(
+          "manifest",
+          expected: "<valid JSON>",
+          actual: "<parse error: #{e.message}>"
+        )
+      end
+
+      # Fetch and parse a manifest from a URL. Returns nil when the
+      # manifest is absent (HTTP 404/410) so callers can fall back to
+      # unverified downloads — see module docs. Any other failure
+      # (5xx, network error, parse error) raises.
+      def self.load(url, http: Kotoshu::Integrity::NetHTTP)
+        body = http.get(url)
+        return nil if body.nil?
+
+        parse(body)
+      end
+
+      attr_reader :entries, :version, :generated_at
+
+      def initialize(entries, version: nil, generated_at: nil)
+        @entries = entries
+        @version = version
+        @generated_at = generated_at
+      end
+
+      def fetch(path)
+        @entries[path]
+      end
+
+      def empty?
+        @entries.empty?
+      end
+
+      # Verify that content for `path` matches the manifest entry.
+      # Raises {Kotoshu::IntegrityError} on mismatch. No-op when the
+      # manifest has no entry for `path` (returns nil — caller decides
+      # whether to treat absence as failure in strict mode).
+      def verify_content!(path, content, url: nil)
+        entry = @entries[path]
+        return nil unless entry
+
+        actual = Digest::SHA256.hexdigest(content)
+        unless actual == entry.sha256
+          raise Kotoshu::IntegrityError.new(
+            path,
+            expected: entry.sha256,
+            actual: actual,
+            url: url
+          )
+        end
+        true
+      end
+    end
+  end
+end

data/lib/kotoshu/integrity/net_http.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+
+module Kotoshu
+  module Integrity
+    # Thin wrapper around Net::HTTP so manifest fetches are testable
+    # without the network. Returns response body as a String on 2xx,
+    # nil on 404/410 (so callers can treat "manifest not published yet"
+    # as graceful degradation), and raises on other errors.
+    module NetHTTP
+      class << self
+        def get(url, redirect_limit: 3)
+          uri = URI(url)
+          raise ArgumentError, "Only http/https supported: #{url}" unless
+            uri.scheme == "http" || uri.scheme == "https"
+
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = (uri.scheme == "https")
+          http.open_timeout = 10
+          http.read_timeout = 30
+
+          request = Net::HTTP::Get.new(uri.request_uri)
+          response = http.request(request)
+
+          case response
+          when Net::HTTPSuccess
+            response.body
+          when Net::HTTPNotFound, Net::HTTPGone
+            nil
+          when Net::HTTPRedirection
+            raise TooManyRedirects if redirect_limit.zero?
+
+            get(response["location"], redirect_limit: redirect_limit - 1)
+          else
+            raise HttpError, "GET #{url} failed: #{response.code} #{response.message}"
+          end
+        end
+      end
+
+      class HttpError < StandardError; end
+      class TooManyRedirects < StandardError; end
+    end
+  end
+end

data/lib/kotoshu/integrity.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  # Integrity verification for downloaded resources.
+  #
+  # Two cooperating pieces:
+  #
+  # - {Manifest} — parsed view of a content repo's `manifest.json`. Lookup
+  #   by relative path yields the expected SHA-256 and size.
+  # - {AuditLog} — append-only JSON log at `$XDG_DATA_HOME/kotoshu/audit.log` recording
+  #   every download's URL, size, computed SHA-256, manifest hash (when
+  #   available), and status.
+  #
+  # Caches call `Manifest.verify_content!` after each download. If the
+  # manifest is absent (the upstream repo hasn't shipped one yet), the
+  # caller logs the download with status `"unverified"` and proceeds —
+  # graceful degradation. When a manifest IS present and the SHA-256
+  # doesn't match, {Kotoshu::IntegrityError} is raised and the corrupt
+  # bytes are removed before they reach the cache.
+  module Integrity
+    autoload :Manifest, "kotoshu/integrity/manifest"
+    autoload :AuditLog, "kotoshu/integrity/audit_log"
+    autoload :NetHTTP, "kotoshu/integrity/net_http"
+  end
+end

data/lib/kotoshu/keyboard/layout.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Keyboard
+    # Base class for keyboard layouts
+    #
+    # Each layout defines key positions and provides distance calculations
+    # for typo detection and suggestion ranking in spell checking.
+    #
+    # @example Using a keyboard layout
+    #   layout = Keyboard::Layouts::QWERTY.new
+    #   layout.distance('q', 'w')  # => 1 (adjacent keys)
+    #   layout.distance('q', 'p')  # => 8 (far apart)
+    #   layout.adjacent_keys('q')  # => ['w', 'a', 's']
+    #
+    # @example Checking language support
+    #   qwerty = Keyboard::Layouts::QWERTY.new
+    #   qwerty.supports_language?('en')  # => true
+    #   qwerty.supports_language?('de')  # => false
+    #
+    class Layout
+      # @return [String] the name of this keyboard layout
+      attr_reader :name
+
+      # @return [Array<String>] list of language codes this layout supports
+      attr_reader :language_codes
+
+      # @return [Hash] mapping of key characters to [row, col] positions
+      attr_reader :key_positions
+
+      # Initialize a keyboard layout
+      #
+      # @param name [String] the name of the layout
+      # @param language_codes [Array<String>] list of language codes this layout supports
+      # @param key_positions [Hash] mapping of key characters to [row, col] positions
+      def initialize(name:, language_codes:, key_positions:)
+        @name = name
+        @language_codes = Array(language_codes).freeze
+        @key_positions = key_positions.freeze
+      end
+
+      # Get position [row, col] for a key
+      #
+      # @param key [String] the key character to look up
+      # @return [Array<Integer>, nil] the [row, col] position, or nil if key not found
+      def position(key)
+        @key_positions[key.downcase]
+      end
+
+      # Calculate Manhattan distance between two keys
+      #
+      # Manhattan distance is the sum of absolute differences of row and column:
+      # distance = abs(row1 - row2) + abs(col1 - col2)
+      #
+      # @param key1 [String] first key character
+      # @param key2 [String] second key character
+      # @return [Integer] Manhattan distance (0 if same key, Float::INFINITY if either key not found)
+      def distance(key1, key2)
+        pos1 = position(key1)
+        pos2 = position(key2)
+
+        return Float::INFINITY unless pos1 && pos2
+
+        (pos1[0] - pos2[0]).abs + (pos1[1] - pos2[1]).abs
+      end
+
+      # Check if layout supports a language
+      #
+      # Supports both exact matching and language variant matching.
+      # For example, if 'en' is supported, then 'en-US', 'en-GB', etc. are also supported.
+      #
+      # @param language_code [String] the language code to check (e.g., 'en', 'en-US', 'de')
+      # @return [Boolean] true if this layout supports the language
+      def supports_language?(language_code)
+        # Try exact match first
+        return true if @language_codes.include?(language_code)
+
+        # Try base language match (e.g., 'en' for 'en-US')
+        base_lang = language_code.to_s.split('-').first
+        @language_codes.include?(base_lang)
+      end
+
+      # Get adjacent keys for a given key (within 1 unit distance)
+      #
+      # Adjacent keys are those that are directly next to the given key
+      # horizontally or vertically (not diagonal).
+      #
+      # @param key [String] the key character to find adjacent keys for
+      # @return [Array<String>] list of adjacent key characters
+      def adjacent_keys(key)
+        pos = position(key)
+        return [] unless pos
+
+        @key_positions.select do |k, p|
+          next if k == key
+          ((p[0] - pos[0]).abs + (p[1] - pos[1]).abs) == 1
+        end.keys
+      end
+
+      # String representation of the layout
+      #
+      # @return [String] layout name
+      def to_s
+        "Keyboard::#{@name}"
+      end
+
+      # Inspect method for debugging
+      #
+      # @return [String] detailed inspection string
+      def inspect
+        "#<#{self.class} name=#{@name} languages=#{@language_codes.join(',')}>"
+      end
+    end
+  end
+end

data/lib/kotoshu/keyboard/layouts/azerty.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../layout'
+
+module Kotoshu
+  module Keyboard
+    module Layouts
+      # AZERTY keyboard layout
+      #
+      # Standard AZERTY layout used for:
+      # - French (fr, fr-FR)
+      # - Belgium (be)
+      #
+      # Key differences from QWERTY:
+      # - a and q are swapped (a/q → q/a)
+      # - z and w are swapped (z/w → w/z)
+      # - Number row is shifted (requires Shift for numbers)
+      # - Has accent keys: é, à, ç, è, ù
+      #
+      # Key positions use [row, col] coordinates where:
+      # - row 0: number/symbol row (²&é"'(-...)
+      # - row 1: top row (azerty...)
+      # - row 2: home row (qsdfg...)
+      # - row 3: bottom row (wxcvb...) - note: w is here
+      class AZERTY < Layout
+        # Key positions for AZERTY layout
+        # Each key maps to [row, column] coordinates
+        KEY_POSITIONS = {
+          # Top row (number/symbol row - numbers require Shift)
+          '`' => [0, 0], '1' => [0, 1], '2' => [0, 2], '3' => [0, 3], '4' => [0, 4],
+          '5' => [0, 5], '6' => [0, 6], '7' => [0, 7], '8' => [0, 8], '9' => [0, 9],
+          '0' => [0, 10], ')' => [0, 11], '=' => [0, 12],
+          # Top row (AZERTY - note a and q swapped, z and w swapped)
+          'a' => [1, 0], 'z' => [1, 1], 'e' => [1, 2], 'r' => [1, 3], 't' => [1, 4],
+          'y' => [1, 5], 'u' => [1, 6], 'i' => [1, 7], 'o' => [1, 8], 'p' => [1, 9],
+          '^' => [1, 10], '$' => [1, 11],
+          # Home row (QSDFG - note q is here)
+          'q' => [2, 0], 's' => [2, 1], 'd' => [2, 2], 'f' => [2, 3], 'g' => [2, 4],
+          'h' => [2, 5], 'j' => [2, 6], 'k' => [2, 7], 'l' => [2, 8], 'm' => [2, 9],
+          'ù' => [2, 10],
+          # Bottom row (WXCVB - note w is here)
+          'w' => [3, 0], 'x' => [3, 1], 'c' => [3, 2], 'v' => [3, 3], 'b' => [3, 4],
+          'n' => [3, 5], ',' => [3, 6], ';' => [3, 7], ':' => [3, 8], '!' => [3, 9]
+        }.freeze
+
+        # Initialize AZERTY layout
+        def initialize
+          super(
+            name: 'AZERTY',
+            language_codes: %w[fr be fr-FR],
+            key_positions: KEY_POSITIONS
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/keyboard/layouts/dvorak.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative '../layout'
+
+module Kotoshu
+  module Keyboard
+    module Layouts
+      # Dvorak keyboard layout
+      #
+      # Dvorak Simplified Keyboard layout designed for efficiency:
+      # - English (en, en-US) with Dvorak layout
+      #
+      # Key differences from QWERTY:
+      # - Vowels (AOEUIDHTNS) on home row left
+      # - Most common consonants on home row right
+      # - Designed to minimize finger movement
+      # - ~70% of keystrokes on home row (vs ~32% for QWERTY)
+      #
+      # Key positions use [row, col] coordinates where:
+      # - row 0: number row (`1"2>...)
+      # - row 1: top row (',.<pyfg...)
+      # - row 2: home row (aoeuidhtns...)
+      # - row 3: bottom row (;qjkxbmwvz)
+      class Dvorak < Layout
+        # Key positions for Dvorak layout
+        # Each key maps to [row, column] coordinates
+        KEY_POSITIONS = {
+          # Number row
+          '`' => [0, 0], '1' => [0, 1], '2' => [0, 2], '3' => [0, 3], '4' => [0, 4],
+          '5' => [0, 5], '6' => [0, 6], '7' => [0, 7], '8' => [0, 8], '9' => [0, 9],
+          '0' => [0, 10], '[' => [0, 11], ']' => [0, 12],
+          # Top row (punctuation and high-frequency consonants)
+          '\'' => [1, 0], ',' => [1, 1], '.' => [1, 2], 'p' => [1, 3], 'y' => [1, 4],
+          'f' => [1, 5], 'g' => [1, 6], 'c' => [1, 7], 'r' => [1, 8], 'l' => [1, 9],
+          '/' => [1, 10], '=' => [1, 11],
+          # Home row (vowels left, high-frequency consonants right)
+          'a' => [2, 0], 'o' => [2, 1], 'e' => [2, 2], 'u' => [2, 3], 'i' => [2, 4],
+          'd' => [2, 5], 'h' => [2, 6], 't' => [2, 7], 'n' => [2, 8], 's' => [2, 9],
+          '-' => [2, 10],
+          # Bottom row (low-frequency letters)
+          ';' => [3, 0], 'q' => [3, 1], 'j' => [3, 2], 'k' => [3, 3], 'x' => [3, 4],
+          'b' => [3, 5], 'm' => [3, 6], 'w' => [3, 7], 'v' => [3, 8], 'z' => [3, 9]
+        }.freeze
+
+        # Initialize Dvorak layout
+        def initialize
+          super(
+            name: 'Dvorak',
+            language_codes: %w[en en-US],
+            key_positions: KEY_POSITIONS
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/keyboard/layouts/jcuken.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require_relative '../layout'
+
+module Kotoshu
+  module Keyboard
+    module Layouts
+      # JCUKEN keyboard layout
+      #
+      # Standard JCUKEN layout used for:
+      # - Russian (ru, ru-RU)
+      # - Ukrainian (uk)
+      # - Belarusian (be)
+      # - Bulgarian (bg)
+      #
+      # This is the standard Cyrillic keyboard layout.
+      # Key differences from QWERTY:
+      # - Completely different alphabet (Cyrillic: 33 letters)
+      # - JCUKEN mapping corresponds to QWERTY positions
+      # - Has special keys: ё, ъ, ь
+      #
+      # Key positions use [row, col] coordinates where:
+      # - row 0: number row (ё1"2...)
+      # - row 1: top row (йцукен...)
+      # - row 2: home row (фывап...)
+      # - row 3: bottom row (ячсми...)
+      class JCUKEN < Layout
+        # Key positions for JCUKEN layout (Cyrillic)
+        # Each key maps to [row, column] coordinates
+        KEY_POSITIONS = {
+          # Number row
+          'ё' => [0, 0], '1' => [0, 1], '2' => [0, 2], '3' => [0, 3], '4' => [0, 4],
+          '5' => [0, 5], '6' => [0, 6], '7' => [0, 7], '8' => [0, 8], '9' => [0, 9],
+          '0' => [0, 10], '-' => [0, 11], '=' => [0, 12],
+          # Top row (ЙЦУКЕН - corresponds to QWERTY)
+          'й' => [1, 0], 'ц' => [1, 1], 'у' => [1, 2], 'к' => [1, 3], 'е' => [1, 4],
+          'н' => [1, 5], 'г' => [1, 6], 'ш' => [1, 7], 'щ' => [1, 8], 'з' => [1, 9],
+          'х' => [1, 10], 'ъ' => [1, 11],
+          # Home row (ФЫВАПРОЛД - corresponds to ASDFGHJKL)
+          'ф' => [2, 0], 'ы' => [2, 1], 'в' => [2, 2], 'а' => [2, 3], 'п' => [2, 4],
+          'р' => [2, 5], 'о' => [2, 6], 'л' => [2, 7], 'д' => [2, 8], 'ж' => [2, 9],
+          'э' => [2, 10],
+          # Bottom row (ЯЧСМИТЬБЮ - corresponds to ZXCVBNM)
+          'я' => [3, 0], 'ч' => [3, 1], 'с' => [3, 2], 'м' => [3, 3], 'и' => [3, 4],
+          'т' => [3, 5], 'ь' => [3, 6], 'б' => [3, 7], 'ю' => [3, 8], '.' => [3, 9]
+        }.freeze
+
+        # Initialize JCUKEN layout
+        def initialize
+          super(
+            name: 'JCUKEN',
+            language_codes: %w[ru uk be bg ru-RU],
+            key_positions: KEY_POSITIONS
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/keyboard/layouts/qwerty.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require_relative '../layout'
+
+module Kotoshu
+  module Keyboard
+    module Layouts
+      # QWERTY keyboard layout
+      #
+      # Standard QWERTY layout used for:
+      # - English (en, en-US, en-GB, etc.)
+      # - Spanish (es)
+      # - Portuguese (pt, pt-BR, pt-PT)
+      # - United States (us)
+      #
+      # Key positions use [row, col] coordinates where:
+      # - row 0: number row (`1`2`3...)
+      # - row 1: top row (qwerty...)
+      # - row 2: home row (asdfg...)
+      # - row 3: bottom row (zxcvb...)
+      class QWERTY < Layout
+        # Key positions for QWERTY layout
+        # Each key maps to [row, column] coordinates
+        KEY_POSITIONS = {
+          # Number row
+          '`' => [0, 0], '1' => [0, 1], '2' => [0, 2], '3' => [0, 3], '4' => [0, 4],
+          '5' => [0, 5], '6' => [0, 6], '7' => [0, 7], '8' => [0, 8], '9' => [0, 9],
+          '0' => [0, 10], '-' => [0, 11], '=' => [0, 12],
+          # Top row (QWERTY)
+          'q' => [1, 0], 'w' => [1, 1], 'e' => [1, 2], 'r' => [1, 3], 't' => [1, 4],
+          'y' => [1, 5], 'u' => [1, 6], 'i' => [1, 7], 'o' => [1, 8], 'p' => [1, 9],
+          '[' => [1, 10], ']' => [1, 11], '\\' => [1, 12],
+          # Home row (ASDFG)
+          'a' => [2, 0], 's' => [2, 1], 'd' => [2, 2], 'f' => [2, 3], 'g' => [2, 4],
+          'h' => [2, 5], 'j' => [2, 6], 'k' => [2, 7], 'l' => [2, 8], ';' => [2, 9],
+          '\'' => [2, 10],
+          # Bottom row (ZXCVB)
+          'z' => [3, 0], 'x' => [3, 1], 'c' => [3, 2], 'v' => [3, 3], 'b' => [3, 4],
+          'n' => [3, 5], 'm' => [3, 6], ',' => [3, 7], '.' => [3, 8], '/' => [3, 9]
+        }.freeze
+
+        # Initialize QWERTY layout
+        def initialize
+          super(
+            name: 'QWERTY',
+            language_codes: %w[en es pt us en-US en-GB en-AU en-CA en-NZ en-ZA
+                             es-ES es-MX pt-BR pt-PT],
+            key_positions: KEY_POSITIONS
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/keyboard/layouts/qwertz.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative '../layout'
+
+module Kotoshu
+  module Keyboard
+    module Layouts
+      # QWERTZ keyboard layout
+      #
+      # Standard QWERTZ layout used for:
+      # - German (de, de-DE, de-AT, de-CH)
+      # - Austria (at)
+      # - Switzerland (ch)
+      #
+      # Key differences from QWERTY:
+      # - z and y are swapped (z/y → y/z)
+      # - Has umlaut keys: ä, ö, ü
+      # - Has ß key (Eszett)
+      #
+      # Key positions use [row, col] coordinates where:
+      # - row 0: number row (^°1"2...)
+      # - row 1: top row (qwertz...)
+      # - row 2: home row (asdfg...)
+      # - row 3: bottom row (yxcvb...) - note: y is here, not in top row
+      class QWERTZ < Layout
+        # Key positions for QWERTZ layout
+        # Each key maps to [row, column] coordinates
+        KEY_POSITIONS = {
+          # Number row
+          '^' => [0, 0], '1' => [0, 1], '2' => [0, 2], '3' => [0, 3], '4' => [0, 4],
+          '5' => [0, 5], '6' => [0, 6], '7' => [0, 7], '8' => [0, 8], '9' => [0, 9],
+          '0' => [0, 10], 'ß' => [0, 11], '´' => [0, 12],
+          # Top row (QWERTZ - note z and y are swapped)
+          'q' => [1, 0], 'w' => [1, 1], 'e' => [1, 2], 'r' => [1, 3], 't' => [1, 4],
+          'z' => [1, 5], 'u' => [1, 6], 'i' => [1, 7], 'o' => [1, 8], 'p' => [1, 9],
+          'ü' => [1, 10], '+' => [1, 11],
+          # Home row (ASDFG)
+          'a' => [2, 0], 's' => [2, 1], 'd' => [2, 2], 'f' => [2, 3], 'g' => [2, 4],
+          'h' => [2, 5], 'j' => [2, 6], 'k' => [2, 7], 'l' => [2, 8], 'ö' => [2, 9],
+          'ä' => [2, 10],
+          # Bottom row (YXCVB - note y is here)
+          'y' => [3, 0], 'x' => [3, 1], 'c' => [3, 2], 'v' => [3, 3], 'b' => [3, 4],
+          'n' => [3, 5], 'm' => [3, 6], ',' => [3, 7], '.' => [3, 8], '-' => [3, 9]
+        }.freeze
+
+        # Initialize QWERTZ layout
+        def initialize
+          super(
+            name: 'QWERTZ',
+            language_codes: %w[de at ch de-DE de-AT de-CH],
+            key_positions: KEY_POSITIONS
+          )
+        end
+      end
+    end
+  end
+end