tahweel 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32c33604a9634bbcf0c683c1b5c0b76bdd2339e4beb0b6107ff94449e6f38453
-  data.tar.gz: e02b8a16c1b75c903a7e78f4cbb55795164f90e91ae1190113c156ca7fda5524
+  metadata.gz: cfa4c4ffbb0b1229794addc7ae400b8af9fda793e7c17b403d4aa60bd92fa7f6
+  data.tar.gz: 2d236076739f2ae1b892669487b6ac839b1a5420c1928621787e6387e7ba50ab
 SHA512:
-  metadata.gz: 979019e30d2698a5a99930f694392c2ed43efb9e52f2c88534e5647490c7bc157360b6f2cd1fa745758c1f8b3ad019dce1fc25e616a9a77408c67555cb025260
-  data.tar.gz: 6b0cd84acd43c4935214eb444273eab9b0f1f8b4717873d872da2c576d3b5f0cd1818416540a84857c77db7a25492435cd513bcffee3455e9f7a94a7c6f96adf
+  metadata.gz: de06384d492cd26925dee76392119d0cd7c05d279e1aaafa97d055091558513847b051f5c65bc505a5213623a36004f734fbe0794b414ebc28c6982639841960
+  data.tar.gz: 31e2d05fbaf89c4f09ef3859243052ffd00f95ffa277368826e9ebed11539b401d8b8487920c799b6bc2bf5d52ab36cfa4ff4771f9661a38a839d5353dfed2bf

data/.vscode/settings.json

@@ -1,5 +1,6 @@
 {
   "workbench.iconTheme": "vscode-icons",
+  "editor.rulers": [80, 120, 140],
   "files.insertFinalNewline": true,
   "[ruby]": {
     "editor.defaultFormatter": "Shopify.ruby-lsp",

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-01-03
+
+### Changed
+
+- Normalize line endings in DOCX writer to proper OOXML line breaks
+- Add Windows EXE build workflow
+
 ## [0.1.1] - 2025-12-03
 
 ### Changed

data/bin/tahweel

@@ -11,10 +11,15 @@ require "tahweel/cli/progress_renderer"
 begin
   soft, hard = Process.getrlimit(:NOFILE)
   Process.setrlimit(:NOFILE, [4096, hard].min) if soft < 4096
-rescue StandardError
-  puts "\e[31mTahweel failed to increase the soft limit of file descriptors to 4096."
-  puts "If you faced connection errors or the CLI froze, try running `ulimit -n 4096` in your terminal."
-  puts "If you still face issues, please report them at https://github.com/ieasybooks/tahweel.rb/issues.\e[0m"
+rescue Exception # rubocop:disable Lint/RescueException
+  if Gem.win_platform?
+    puts "\e[33mWarning: Could not adjust file descriptor limit on Windows. Proceeding with default limits."
+    puts "If you faced connection errors or the CLI froze, please report at https://github.com/ieasybooks/tahweel.rb/issues.\e[0m"
+  else
+    puts "\e[33mWarning: Tahweel failed to increase the soft limit of file descriptors to 4096."
+    puts "If you faced connection errors or the CLI froze, try running `ulimit -n 4096` in your terminal."
+    puts "If you still face issues, please report them at https://github.com/ieasybooks/tahweel.rb/issues.\e[0m"
+  end
 end
 
 begin
@@ -27,7 +32,7 @@ begin
     exit 0
   end
 
-  Tahweel::Authorizer.authorize if options[:file_concurrency] > 1 && options[:processor] == :google_drive
+  Tahweel::Authorizer.authorize if options[:processor] == :google_drive
 
   base_path = File.directory?(input_path) ? input_path : File.dirname(input_path)
 

data/bin/tahweel-ui

@@ -0,0 +1,300 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Add the ../lib directory to the load path so we can require 'tahweel'
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "matrix"
+require "glimmer-dsl-libui"
+require "launchy"
+require "tahweel"
+
+Tahweel::Authorizer.authorize unless defined?(Ocran)
+
+class TahweelApp # rubocop:disable Metrics/ClassLength,Style/Documentation
+  include Glimmer::LibUI::Application
+
+  TRANSLATIONS = {
+    # https://www.perplexity.ai/search/add-direction-unicode-controls-Z5haIOFEQZeCbG5B8Wt2dg#3
+    ar: {
+      window_title: "تحويل",
+      title_label: "‫تحويل: حوّل الملفات من صيغة ‪PDF‬ إلى ‪TXT‬ و ‪DOCX‬ ↓‬",
+      note_label: "‫ملاحظة: يدعم تحويل الملفات بصيغة ‪PDF‬ أو صورة (‪JPG‬ و ‪JPEG‬ و ‪PNG‬) فقط.‬",
+      file_btn: "تحويل ملف واحد",
+      folder_btn: "تحويل مجلد كامل",
+      language_btn: "English",
+      global_progress: "التقدم العام:",
+      file_progress: "تقدم الملف الحالي:",
+      status_done: "انتهى التحويل.",
+      msg_success_title: "اكتمل التحويل",
+      msg_error_title: "خطأ",
+      msg_no_files: "لم نعثر على ملفات لتحويلها.",
+      msg_bad_extension: "صيغة الملف غير مدعومة.",
+      stage_preparing: "جارٍ التحضير...",
+      stage_splitting: "جارٍ تقسيم الملف...",
+      stage_ocr: "جارٍ استخراج النصوص...",
+      stage_done: "انتهى"
+    },
+    en: {
+      window_title: "Tahweel",
+      title_label: "Tahweel: Convert PDF files to TXT and DOCX ↓",
+      note_label: "Note: Tahweel supports PDF or image files (JPG, JPEG, and PNG) only.",
+      file_btn: "Convert a Single File",
+      folder_btn: "Convert a Folder",
+      language_btn: "العربية",
+      global_progress: "Progress:",
+      file_progress: "Current File:",
+      status_done: "Conversion complete.",
+      msg_success_title: "Conversion Complete",
+      msg_error_title: "Error",
+      msg_no_files: "No files found to convert.",
+      msg_bad_extension: "Unsupported file format.",
+      stage_preparing: "Preparing...",
+      stage_splitting: "Splitting file...",
+      stage_ocr: "Extracting text...",
+      stage_done: "Done"
+    }
+  }.freeze
+
+  def initialize(*args)
+    @lang = :ar
+    @rtl_components = []
+    @ltr_components = []
+
+    super
+  end
+
+  body do
+    @main_window = window(t(:window_title)) do
+      margined true
+
+      vertical_box do
+        @header_label = right_aligned_label(t(:title_label))
+        convert_buttons
+        @note_label = right_aligned_label(t(:note_label))
+
+        @progress_section = progress_section
+        @progress_section.visible = false
+
+        horizontal_separator { stretchy false }
+
+        @language_btn = language_button
+      end
+    end
+  end
+
+  private
+
+  def language_button # rubocop:disable Metrics/MethodLength
+    ref = nil
+
+    horizontal_box do
+      stretchy false
+
+      right_alignment_label = label("") { stretchy true }
+      right_alignment_label.visible = false
+      @rtl_components << right_alignment_label
+
+      ref = button(t(:language_btn)) do
+        stretchy false
+        on_clicked { toggle_language }
+      end
+
+      left_alignment_label = label("") { stretchy true }
+      @ltr_components << left_alignment_label
+    end
+
+    ref
+  end
+
+  def convert_buttons
+    horizontal_box do
+      @ar_convert_folder_btn = button(t(:folder_btn, lang: :ar)) { on_clicked { on_folder_click } }
+      @rtl_components << @ar_convert_folder_btn
+
+      @convert_file_btn = button(t(:file_btn)) { on_clicked { on_file_click } }
+
+      @en_convert_folder_btn = button(t(:folder_btn, lang: :en)) { on_clicked { on_folder_click } }
+      @en_convert_folder_btn.visible = false
+      @rtl_components << @en_convert_folder_btn
+    end
+  end
+
+  def progress_section
+    group do
+      stretchy false
+
+      vertical_box do
+        @global_progress_label = right_aligned_label(t(:global_progress))
+        @global_progress = progress_bar { stretchy true }
+
+        @file_progress_label = right_aligned_label(t(:file_progress))
+        @file_progress = progress_bar { stretchy true }
+      end
+    end
+  end
+
+  def on_file_click
+    file = open_file
+    convert(File.dirname(file), [file]) if file && valid_file?(file)
+  end
+
+  def valid_file?(file)
+    return true if %w[.pdf .jpg .jpeg .png].include? File.extname(file).downcase
+
+    msg_box_error(t(:msg_error_title), t(:msg_bad_extension))
+    false
+  end
+
+  def on_folder_click
+    folder = open_folder
+    paths = collect_files(folder)
+    convert(folder, paths) if paths.any?
+  end
+
+  def collect_files(folder)
+    paths = folder ? Tahweel::CLI::FileCollector.collect(folder) : []
+    return paths if folder && paths.any?
+
+    msg_box_error(t(:msg_error_title), t(:msg_no_files))
+    []
+  end
+
+  def convert(folder, paths)
+    disable_window
+    @progress_section.visible = true
+
+    Thread.new do
+      paths.each_with_index { |path, index| process_path(path, index, paths.size) }
+      finish_conversion(folder, paths.size)
+    end
+  end
+
+  def disable_window
+    @convert_file_btn.enabled = false
+    @ar_convert_folder_btn.enabled = false
+    @en_convert_folder_btn.enabled = false
+    @language_btn.enabled = false
+  end
+
+  def process_path(path, index, total_files)
+    reset_file_progress(index, total_files)
+
+    Tahweel::CLI::FileProcessor.process(path, options(path)) { update_file_progress(_1) }
+  end
+
+  def reset_file_progress(index, total_files)
+    Glimmer::LibUI.queue_main do
+      @global_progress.value = ((index.to_f / total_files) * 100).to_i
+      @global_progress_label.text = "\u202B#{t(:global_progress)} (\u202A#{index}/#{total_files}\u202C)\u202C"
+      @file_progress.value = 0
+      @file_progress_label.text = "#{t(:file_progress)} #{t(:stage_preparing)}"
+    end
+  end
+
+  def options(path)
+    {
+      dpi: 150,
+      processor: :google_drive,
+      ocr_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
+      file_concurrency: 1,
+      formats: %i[txt docx],
+      base_input_path: File.directory?(path) ? path : File.dirname(path)
+    }
+  end
+
+  def update_file_progress(progress)
+    Glimmer::LibUI.queue_main do
+      @file_progress.value = progress[:percentage].to_i
+      @file_progress_label.text = "#{t(:file_progress)} (#{stage_text(progress[:stage])})"
+    end
+  end
+
+  def stage_text(stage)
+    case stage
+    when :splitting then t(:stage_splitting)
+    when :ocr       then t(:stage_ocr)
+    end
+  end
+
+  def finish_conversion(folder, total_files)
+    Glimmer::LibUI.queue_main do
+      @global_progress.value = 100
+      @file_progress.value = 100
+      @global_progress_label.text = "#{t(:global_progress)} (#{total_files}/#{total_files})"
+      @file_progress_label.text = "#{t(:file_progress)} (#{t(:stage_done)})"
+
+      enable_window
+      msg_box(t(:msg_success_title), convert_finished_message(total_files))
+    end
+
+    Launchy.open(folder)
+  end
+
+  def enable_window
+    @convert_file_btn.enabled = true
+    @ar_convert_folder_btn.enabled = true
+    @en_convert_folder_btn.enabled = true
+    @language_btn.enabled = true
+  end
+
+  def convert_finished_message(files_count)
+    if @lang == :en
+      "Finished converting #{files_count} file(s) successfully."
+    else
+      arabic_convert_finished_message(files_count)
+    end
+  end
+
+  def arabic_convert_finished_message(files_count)
+    return "انتهى تحويل ملف واحد بنجاح." if files_count == 1
+    return "انتهى تحويل ملفين بنجاح." if files_count == 2
+
+    last_two_digits = files_count % 100
+
+    suffix = case last_two_digits
+             when 0..2 then "ملف"
+             when 3..10 then "ملفات"
+             else "ملفًا"
+             end
+
+    "انتهى تحويل #{files_count} #{suffix} بنجاح."
+  end
+
+  def toggle_language # rubocop:disable Metrics/AbcSize
+    @lang = @lang == :ar ? :en : :ar
+
+    @main_window.title = t(:window_title)
+    @header_label.text = t(:title_label)
+    @note_label.text = t(:note_label)
+    @convert_file_btn.text = t(:file_btn)
+    @language_btn.text = t(:language_btn)
+
+    @global_progress_label.text = t(:global_progress)
+    @file_progress_label.text = t(:file_progress)
+
+    @rtl_components.each { _1.visible = !_1.visible }
+    @ltr_components.each { _1.visible = !_1.visible }
+  end
+
+  def t(key, lang: nil) = TRANSLATIONS[lang || @lang][key]
+
+  def right_aligned_label(text)
+    ref = nil
+
+    horizontal_box do
+      right_alignment_label = label("") { stretchy true }
+      @rtl_components << right_alignment_label
+
+      ref = label(text) { stretchy false }
+
+      left_alignment_label = label("") { stretchy true }
+      left_alignment_label.visible = false
+      @ltr_components << left_alignment_label
+    end
+
+    ref
+  end
+end
+
+TahweelApp.launch unless defined?(Ocran)

data/lib/tahweel/authorizer.rb

@@ -1,12 +1,13 @@
 # frozen_string_literal: true
 
-require "google/apis/drive_v3"
-require "googleauth"
-require "googleauth/stores/file_token_store"
+require "fileutils"
 require "socket"
 require "uri"
+
+require "googleauth"
+require "googleauth/stores/file_token_store"
+require "google/apis/drive_v3"
 require "launchy"
-require "fileutils"
 require "xdg"
 
 module Tahweel
@@ -104,7 +105,16 @@ module Tahweel
     end
 
     # Opens the system default browser to the Google Authorization URL.
-    def open_browser_for_auth = Launchy.open(@authorizer.get_authorization_url(base_url: REDIRECT_URI))
+    def open_browser_for_auth
+      url = @authorizer.get_authorization_url(base_url: REDIRECT_URI)
+
+      if Gem.win_platform?
+        # https://github.com/copiousfreetime/launchy/issues/167
+        system("start \"\" \"#{url}\"")
+      else
+        Launchy.open(url)
+      end
+    end
 
     # Listens on the local server for the OAuth callback request.
     # Handles multiple incoming requests to filter out noise (like favicon.ico).

data/lib/tahweel/cli/file_processor.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require "fileutils"
 require "pathname"
 
 module Tahweel
@@ -17,7 +18,7 @@ module Tahweel
       # @option options [String] :output The directory to save output files (defaults to current directory).
       # @option options [Integer] :dpi DPI for PDF conversion (defaults to 150).
       # @option options [Symbol] :processor The OCR processor to use (e.g., :google_drive).
-      # @option options [Integer] :page_concurrency Max concurrent operations.
+      # @option options [Integer] :ocr_concurrency Max concurrent operations.
       # @option options [Array<Symbol>] :formats Output formats (e.g., [:txt, :docx]).
       # @option options [String] :page_separator Separator string for TXT output.
       # @option options [String] :base_input_path The base path used to determine relative output structure.
@@ -66,8 +67,11 @@ module Tahweel
 
       private
 
+      # Creates the output directory if it doesn't exist.
       def ensure_output_directory_exists = FileUtils.mkdir_p(output_directory)
 
+      # Checks if all requested output formats already exist.
+      # @return [Boolean] True if all output files exist.
       def all_outputs_exist?
         @options[:formats].all? do |format|
           extension = Tahweel::Writer.new(format: format).extension
@@ -75,22 +79,29 @@ module Tahweel
         end
       end
 
+      # Checks if the input file is a PDF.
+      # @return [Boolean]
       def pdf? = File.extname(@file_path).downcase == ".pdf"
 
+      # Handles PDF processing: splitting, OCR, and saving.
+      # @param &block [Proc] Progress callback.
       def process_pdf(&)
         texts = Tahweel.convert(
           @file_path,
           dpi: @options[:dpi],
           processor: @options[:processor],
-          concurrency: @options.fetch(:page_concurrency, Tahweel::Converter::DEFAULT_CONCURRENCY),
+          concurrency: @options.fetch(:ocr_concurrency, Tahweel::Converter::DEFAULT_CONCURRENCY),
           &
         )
 
         write_output(texts)
       end
 
+      # Handles single image processing.
       def process_image = write_output([Tahweel.extract(@file_path, processor: @options[:processor])])
 
+      # Writes the extracted text to all configured formats.
+      # @param texts [Array<String>] The list of extracted texts (per page).
       def write_output(texts)
         Tahweel::Writer.write(
           texts,
@@ -100,6 +111,7 @@ module Tahweel
         )
       end
 
+      # @return [String] The full path for output files without extension.
       def base_output_path = File.join(output_directory, File.basename(@file_path, ".*"))
 
       # Determines the output directory.

data/lib/tahweel/cli/options.rb

@@ -3,6 +3,13 @@
 require "etc"
 require "optparse"
 
+require_relative "../version"
+require_relative "../converter"
+require_relative "../ocr"
+require_relative "../writer"
+require_relative "../writers/txt"
+require_relative "file_collector"
+
 module Tahweel
   module CLI
     # Parses command-line arguments for the Tahweel CLI.
@@ -26,11 +33,13 @@ module Tahweel
         options
       end
 
+      # Returns the default configuration options.
+      # @return [Hash] Default options.
       def self.default_options
         {
           dpi: 150,
           processor: :google_drive,
-          page_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
+          ocr_concurrency: Tahweel::Converter::DEFAULT_CONCURRENCY,
           file_concurrency: (Etc.nprocessors - 2).clamp(2..),
           output: nil,
           formats: %i[txt docx],
@@ -38,6 +47,10 @@ module Tahweel
         }
       end
 
+      # Configures the OptionParser instance.
+      #
+      # @param opts [OptionParser] The parser instance.
+      # @param options [Hash] The options hash to populate.
       def self.configure_parser(opts, options) # rubocop:disable Metrics/MethodLength,Metrics/AbcSize
         opts.program_name = "tahweel"
         opts.version = Tahweel::VERSION
@@ -69,17 +82,17 @@ module Tahweel
         end
 
         opts.on(
-          "-P", "--page-concurrency PAGE_CONCURRENCY", POSITIVE_INTEGER,
-          "Max concurrent OCR operations (default: #{options[:page_concurrency]})"
+          "-F", "--file-concurrency FILE_CONCURRENCY", POSITIVE_INTEGER,
+          "Max concurrent files to process (default: CPUs - 2 = #{options[:file_concurrency]})"
         ) do |value|
-          options[:page_concurrency] = value
+          options[:file_concurrency] = value
         end
 
         opts.on(
-          "-F", "--file-concurrency FILE_CONCURRENCY", POSITIVE_INTEGER,
-          "Max concurrent files to process (default: CPUs - 2 = #{options[:file_concurrency]})"
+          "-O", "--ocr-concurrency OCR_CONCURRENCY", POSITIVE_INTEGER,
+          "Max concurrent OCR operations (default: #{options[:ocr_concurrency]})"
         ) do |value|
-          options[:file_concurrency] = value
+          options[:ocr_concurrency] = value
         end
 
         opts.on(
@@ -104,6 +117,10 @@ module Tahweel
         end
       end
 
+      # Validates that arguments were provided.
+      #
+      # @param args [Array<String>] The remaining arguments after parsing.
+      # @param parser [OptionParser] The parser instance for printing help.
       def self.validate_args!(args, parser)
         return unless args.empty?
 

data/lib/tahweel/cli/progress_renderer.rb

@@ -102,6 +102,7 @@ module Tahweel
 
       private
 
+      # Starts a background thread to refresh the display periodically.
       def start_ticker
         @ticker_thread = Thread.new do
           while @running
@@ -111,6 +112,7 @@ module Tahweel
         end
       end
 
+      # Renders the progress dashboard to stdout.
       def render # rubocop:disable Metrics/AbcSize,Metrics/MethodLength
         # Move cursor up to the start of our block
         $stdout.print "\e[#{@concurrency + 1}A"
@@ -138,6 +140,11 @@ module Tahweel
         $stdout.flush
       end
 
+      # Truncates a file path to fit within the display.
+      #
+      # @param path [String] The file path.
+      # @param max_length [Integer] Maximum allowed length.
+      # @return [String] The truncated path.
       def truncate_path(path, max_length)
         return path.ljust(max_length) if path.length <= max_length
 

data/lib/tahweel/converter.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
+require "fileutils"
+
 require_relative "pdf_splitter"
 require_relative "ocr"
-require "fileutils"
 
 module Tahweel
   # Orchestrates the full conversion process:
@@ -60,10 +61,10 @@ module Tahweel
     # }
     # @return [Array<String>] An array containing the text of each page.
     def convert(&)
-      image_paths, temp_dir = PdfSplitter.split(@pdf_path, dpi: @dpi, &).values_at(:image_paths, :folder_path)
+      images_paths, temp_dir = PdfSplitter.split(@pdf_path, dpi: @dpi, &).values_at(:images_paths, :folder_path)
 
       begin
-        process_images(image_paths, Ocr.new(processor: @processor_type), &)
+        process_images(images_paths, Ocr.new(processor: @processor_type), &)
       ensure
         FileUtils.rm_rf(temp_dir)
       end
@@ -71,31 +72,55 @@ module Tahweel
 
     private
 
-    def process_images(image_paths, ocr_engine, &)
-      texts = Array.new(image_paths.size)
+    # Processes the list of images concurrently using the specified OCR engine.
+    #
+    # @param images_paths [Array<String>] List of paths to the image files.
+    # @param ocr_engine [Tahweel::Ocr] The initialized OCR engine instance.
+    # @param &block [Proc] Block to yield progress updates.
+    # @return [Array<String>] The text extracted from the images.
+    def process_images(images_paths, ocr_engine, &)
+      texts = Array.new(images_paths.size)
       mutex = Mutex.new
       processed_count = 0
 
-      run_workers(build_queue(image_paths), ocr_engine, texts, mutex) do
+      run_workers(build_queue(images_paths), ocr_engine, texts, mutex) do
         processed_count += 1
-        report_progress(processed_count, image_paths.size, &)
+        report_progress(processed_count, images_paths.size, &)
       end
 
       texts
     end
 
-    def build_queue(image_paths)
+    # Builds a queue of images paths and their indices.
+    #
+    # @param images_paths [Array<String>] List of image paths.
+    # @return [Queue] A queue containing [path, index] tuples.
+    def build_queue(images_paths)
       queue = Queue.new
-      image_paths.each_with_index { |path, index| queue << [path, index] }
+      images_paths.each_with_index { |path, index| queue << [path, index] }
       queue
     end
 
+    # Spawns worker threads to process items from the queue.
+    #
+    # @param queue [Queue] The queue of images to process.
+    # @param ocr_engine [Tahweel::Ocr] The OCR engine.
+    # @param texts [Array<String>] Shared array to store results.
+    # @param mutex [Mutex] Mutex for thread-safe updates.
+    # @param &block [Proc] Block to yield progress updates.
     def run_workers(queue, ocr_engine, texts, mutex, &)
       Array.new(@concurrency) do
         Thread.new { process_queue_items(queue, ocr_engine, texts, mutex, &) }
       end.each(&:join)
     end
 
+    # Processing loop for a single worker thread.
+    #
+    # @param queue [Queue] The shared queue.
+    # @param ocr_engine [Tahweel::Ocr] The OCR engine.
+    # @param texts [Array<String>] Shared result array.
+    # @param mutex [Mutex] Synchronization primitive.
+    # @param &block [Proc] Block to yield progress updates.
     def process_queue_items(queue, ocr_engine, texts, mutex, &)
       loop do
         begin
@@ -109,6 +134,13 @@ module Tahweel
       end
     end
 
+    # Thread-safe saving of OCR results.
+    #
+    # @param texts [Array<String>] The results array.
+    # @param index [Integer] Index of the current page.
+    # @param text [String] Extracted text.
+    # @param mutex [Mutex] Synchronization primitive.
+    # @yield Executes the progress reporting block within the lock.
     def save_result(texts, index, text, mutex)
       mutex.synchronize do
         texts[index] = text
@@ -116,6 +148,11 @@ module Tahweel
       end
     end
 
+    # Reports progress to the optional block.
+    #
+    # @param processed [Integer] Number of pages processed.
+    # @param total [Integer] Total number of pages.
+    # @yield [Hash] Progress information.
     def report_progress(processed, total)
       return unless block_given?
 

data/lib/tahweel/pdf_splitter.rb

@@ -1,14 +1,15 @@
 # frozen_string_literal: true
 
+require "etc"
 require "fileutils"
-require "rbconfig"
 require "securerandom"
 require "tmpdir"
-require "vips"
+
+require_relative "poppler_installer"
 
 module Tahweel
   # Handles the logic for splitting a PDF file into individual image pages.
-  # Uses the libvips library for high-performance image processing.
+  # Uses Poppler utils (pdftoppm, pdfinfo) for high-performance image processing.
   class PdfSplitter
     # Default DPI used when converting PDF pages to images.
     # 150 DPI is a good balance between quality and file size for general documents.
@@ -25,7 +26,7 @@ module Tahweel
     #   percentage: Float,
     #   remaining_pages: Integer
     # }
-    # @return [Hash] A hash containing the :folder_path (String) and :image_paths (Array<String>).
+    # @return [Hash] A hash containing the :folder_path (String) and :images_paths (Array<String>).
     def self.split(pdf_path, dpi: DEFAULT_DPI, &) = new(pdf_path, dpi:).split(&)
 
     # Initializes a new PdfSplitter instance.
@@ -35,13 +36,12 @@ module Tahweel
     def initialize(pdf_path, dpi: DEFAULT_DPI)
       @pdf_path = pdf_path
       @dpi = dpi
-      @image_paths = []
     end
 
     # Executes the PDF splitting process.
     #
     # This method performs the following steps:
-    # 1. Checks if libvips is installed (skips on Windows).
+    # 1. Checks if Poppler utils are available (installs if missing on Windows).
     # 2. Validates the existence of the source PDF file.
     # 3. Creates a unique temporary directory for output.
     # 4. Iterates through each page of the PDF and converts it to a PNG image.
@@ -55,12 +55,11 @@ module Tahweel
     # }
     # @return [Hash] Result hash with keys:
     #   - :folder_path [String] The absolute path to the temporary directory containing the images.
-    #   - :image_paths [Array<String>] List of absolute paths for each generated image file.
-    # @raise [RuntimeError] If the PDF file is not found or libvips is missing.
-    # @raise [Vips::Error] If the underlying VIPS library encounters an error during processing.
+    #   - :images_paths [Array<String>] List of absolute paths for each generated image file.
+    # @raise [RuntimeError] If the PDF file is not found.
     def split(&)
-      check_libvips_installed!
       validate_file_exists!
+      PopplerInstaller.ensure_installed!
       setup_output_directory
       process_pages(&)
       result
@@ -68,20 +67,7 @@ module Tahweel
 
     private
 
-    attr_reader :pdf_path, :dpi, :image_paths, :output_dir
-
-    # Checks if the `vips` CLI tool is available in the system PATH.
-    # Skips this check on Windows systems, assuming the environment is managed differently.
-    # Aborts execution with an error message if vips is missing.
-    def check_libvips_installed!
-      return if /mswin|mingw|cygwin/.match?(RbConfig::CONFIG["host_os"])
-      return if system("vips --version", out: File::NULL, err: File::NULL)
-
-      abort "Error: libvips is not installed. Please install it before using Tahweel.\n" \
-            "MacOS: `brew install vips`\n" \
-            "Ubuntu: `sudo apt install libvips42`\n" \
-            "Windows: Already installed with the Tahweel gem"
-    end
+    attr_reader :pdf_path, :dpi, :output_dir
 
     # Ensures the source PDF file actually exists.
     # @raise [RuntimeError] if the file is missing.
@@ -106,33 +92,101 @@ module Tahweel
     # }
     # @return [void]
     def process_pages(&)
-      total_pages.times do |i|
-        extract_page(i)
+      mutex = Mutex.new
+      processed_count = 0
+
+      run_workers(build_queue, mutex) do
+        processed_count += 1
+        report_progress(processed_count, &)
+      end
+    end
+
+    # Builds a queue containing all page indices to be processed.
+    # @return [Queue] The queue populated with page numbers.
+    def build_queue
+      queue = Queue.new
+      total_pages.times { queue << _1 }
+      queue
+    end
 
-        next unless block_given?
+    # Spawns and manages worker threads to process the queue.
+    #
+    # @param queue [Queue] The queue of pages to process.
+    # @param mutex [Mutex] Synchronization primitive for thread safety.
+    # @param &block [Proc] Block to execute when a page is processed.
+    def run_workers(queue, mutex, &)
+      concurrency = (Etc.nprocessors - 2).clamp(2..)
+
+      Array.new([concurrency, total_pages].min) do
+        Thread.new { process_queue_items(queue, mutex, &) }
+      end.each(&:join)
+    end
 
-        yield({
-          file_path: @pdf_path, stage: :splitting,
-          current_page: i + 1,
-          percentage: (((i + 1).to_f / total_pages) * 100).round(2),
-          remaining_pages: total_pages - (i + 1)
-        })
+    # Processing loop for individual worker threads.
+    #
+    # @param queue [Queue] The shared queue of pages.
+    # @param mutex [Mutex] Synchronization primitive.
+    # @param &block [Proc] Block to yield for progress updates.
+    def process_queue_items(queue, mutex, &)
+      loop do
+        begin
+          page_num = queue.pop(true)
+        rescue ThreadError
+          break
+        end
+
+        extract_page(page_num)
+
+        mutex.synchronize(&)
       end
     end
 
+    # Reports progress back to the caller.
+    #
+    # @param processed [Integer] Number of pages processed so far.
+    # @param &block [Proc] The progress callback block.
+    def report_progress(processed, &)
+      return unless block_given?
+
+      yield({
+        file_path: @pdf_path, stage: :splitting,
+        current_page: processed,
+        percentage: ((processed.to_f / total_pages) * 100).round(2),
+        remaining_pages: total_pages - processed
+      })
+    end
+
     # Calculates the total number of pages in the PDF by loading the first page metadata.
     # @return [Integer] The page count.
     def total_pages
-      @total_pages ||= Vips::Image.pdfload(pdf_path, page: 0, dpi: dpi, access: :sequential).get("pdf-n_pages")
+      @total_pages ||= begin
+        output = `#{PopplerInstaller.pdfinfo_path} "#{pdf_path}"`.encode(
+          "UTF-8",
+          invalid: :replace, undef: :replace, replace: ""
+        )
+
+        pages = output[/Pages:\s*(\d+)/, 1]
+        raise "Failed to get page count from PDF: #{output}" unless pages
+
+        pages.to_i
+      end
     end
 
     # Extracts a specific page from the PDF and saves it as a PNG.
     #
     # @param page_num [Integer] The zero-based index of the page to extract.
     def extract_page(page_num)
-      output_path = File.join(output_dir, "page_#{page_num + 1}.png")
-      Vips::Image.pdfload(pdf_path, page: page_num, dpi: dpi, access: :sequential).write_to_file(output_path)
-      image_paths << output_path
+      output_prefix = File.join(output_dir, "page")
+
+      system(
+        PopplerInstaller.pdftoppm_path,
+        "-png",
+        "-r", dpi.to_s,
+        "-f", (page_num + 1).to_s,
+        "-l", (page_num + 1).to_s,
+        pdf_path,
+        output_prefix
+      )
     end
 
     # Constructs the final result hash.
@@ -140,7 +194,7 @@ module Tahweel
     def result
       {
         folder_path: output_dir,
-        image_paths: image_paths
+        images_paths: Dir.glob(File.join(output_dir, "page-*.png")).sort!
       }
     end
   end

data/lib/tahweel/poppler_installer.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "json"
+require "net/http"
+require "open-uri"
+require "uri"
+
+require "xdg"
+require "zip"
+
+module Tahweel
+  # Handles the installation and path resolution for Poppler utilities.
+  #
+  # On Windows, this class can automatically download and install the necessary
+  # binaries if they are not present. On other platforms, it provides instructions
+  # for manual installation.
+  class PopplerInstaller
+    POPPLER_REPO_API = "https://api.github.com/repos/oschwartz10612/poppler-windows/releases/latest"
+
+    # Ensures that Poppler utilities are installed.
+    #
+    # On Windows: Installs Poppler locally if not found.
+    # On other platforms: Aborts with an error message if Poppler is missing.
+    #
+    # @raise [SystemExit] if Poppler is missing on non-Windows platforms.
+    def self.ensure_installed! # rubocop:disable Metrics/MethodLength
+      installer = new
+      return if installer.installed?
+
+      if Gem.win_platform?
+        installer.install
+      else
+        abort <<~MSG
+          Error: Poppler utilities are not installed. Please install them:
+          MacOS:  `brew install poppler`
+          Ubuntu: `sudo apt install poppler-utils`
+        MSG
+      end
+    end
+
+    # Returns the path to the `pdftoppm` executable.
+    # @return [String] path to the executable.
+    def self.pdftoppm_path = new.pdftoppm_path
+
+    # Returns the path to the `pdfinfo` executable.
+    # @return [String] path to the executable.
+    def self.pdfinfo_path = new.pdfinfo_path
+
+    # Installs Poppler binaries on Windows.
+    #
+    # Downloads the latest release from GitHub and extracts it to the cache directory.
+    # Does nothing if already installed.
+    def install
+      zip_path = nil
+      return if installed?
+
+      zip_path = download_release_file
+      extract_zip_file(zip_path)
+    ensure
+      FileUtils.rm_f(zip_path) if zip_path
+    end
+
+    # Checks if Poppler utilities are available.
+    #
+    # @return [Boolean] true if `pdftoppm` and `pdfinfo` are in the PATH or cached.
+    def installed? = (command_exists?("pdftoppm") && command_exists?("pdfinfo")) || cached?
+
+    # Checks if Poppler binaries are present in the local cache (Windows only).
+    #
+    # @return [Boolean] true if cached binaries exist.
+    def cached?
+      return false unless Gem.win_platform?
+
+      File.exist?(File.join(cached_bin_path, "pdftoppm.exe"))
+    end
+
+    # Resolves the path to the `pdftoppm` executable.
+    #
+    # Prioritizes the system PATH, falling back to the cached version on Windows.
+    #
+    # @return [String] path to `pdftoppm`.
+    def pdftoppm_path
+      return "pdftoppm" if command_exists?("pdftoppm")
+
+      Gem.win_platform? ? File.join(cached_bin_path, "pdftoppm.exe") : nil
+    end
+
+    # Resolves the path to the `pdfinfo` executable.
+    #
+    # Prioritizes the system PATH, falling back to the cached version on Windows.
+    #
+    # @return [String] path to `pdfinfo`.
+    def pdfinfo_path
+      return "pdfinfo" if command_exists?("pdfinfo")
+
+      Gem.win_platform? ? File.join(cached_bin_path, "pdfinfo.exe") : nil
+    end
+
+    private
+
+    # Locates the `bin` directory within the cached Poppler installation.
+    #
+    # Searches for a directory matching "poppler-*" in the cache directory and returns
+    # the path to its `Library/bin` subdirectory.
+    #
+    # @return [String] Path to the `bin` directory, or an empty string if not found.
+    def cached_bin_path
+      poppler_root = Dir.glob(File.join(cache_dir, "poppler-*")).first
+      return "" unless poppler_root
+
+      File.join(poppler_root, "Library", "bin")
+    end
+
+    # Checks if a command is available in the system path.
+    #
+    # @param cmd [String] The command to check for.
+    # @return [Boolean] true if the command exists in the PATH.
+    def command_exists?(cmd)
+      tool = Gem.win_platform? ? "where" : "which"
+      system("#{tool} #{cmd} > #{File::NULL} 2>&1")
+    end
+
+    # Downloads the latest Poppler release zip file.
+    #
+    # Fetches the download URL from the GitHub API and saves the file to the cache directory.
+    #
+    # @return [String] The local path to the downloaded zip file.
+    def download_release_file
+      release_url = latest_release_url
+      zip_path = File.join(cache_dir, File.basename(release_url))
+      URI.parse(release_url).open { File.binwrite(zip_path, _1.read) }
+      zip_path
+    end
+
+    # Retrieves the download URL for the latest Windows release of Poppler.
+    #
+    # Queries the GitHub API for the latest release and finds the asset matching "Release*.zip".
+    #
+    # @return [String] The download URL of the asset.
+    # @raise [SystemExit] if the API request fails or no valid asset is found.
+    def latest_release_url # rubocop:disable Metrics/AbcSize
+      uri = URI(POPPLER_REPO_API)
+      request = Net::HTTP::Get.new(uri)
+      request["User-Agent"] = "Tahweel-Gem"
+
+      response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { _1.request(request) }
+
+      unless response.is_a?(Net::HTTPSuccess)
+        abort "Failed to fetch Poppler release info: #{response.code} #{response.message}"
+      end
+
+      asset = JSON.parse(response.body)["assets"].find { _1["name"].match?(/^Release.*\.zip$/) }
+
+      asset ? asset["browser_download_url"] : abort("No valid Windows release found for Poppler.")
+    end
+
+    # Extracts the downloaded zip file to the cache directory.
+    #
+    # @param zip_path [String] Path to the zip file to extract.
+    def extract_zip_file(zip_path)
+      Zip::File.open(zip_path) do |zip_file|
+        zip_file.each do |entry|
+          entry_dest = File.join(cache_dir, entry.name)
+          FileUtils.mkdir_p(File.dirname(entry_dest))
+          zip_file.extract(entry, entry_dest) { true }
+        end
+      end
+    end
+
+    # Resolves the directory used for caching downloaded binaries.
+    #
+    # Uses the XDG cache home directory if available, otherwise defaults to `~/.cache/tahweel/poppler`.
+    #
+    # @return [String] Path to the cache directory.
+    def cache_dir
+      base = XDG.new.cache_home.to_s
+      base = File.join(Dir.home, ".cache") if base.empty?
+
+      dir = File.join(base, "tahweel", "poppler")
+      FileUtils.mkdir_p(dir)
+      dir
+    end
+  end
+end

data/lib/tahweel/processors/google_drive.rb

@@ -43,7 +43,7 @@ module Tahweel
 
         begin
           file_id = upload_file(file_path)
-          download_text(file_id).gsub("\r\n", "\n").gsub("________________", "").strip
+          download_text(file_id).gsub("________________", "").strip
         ensure
           delete_file(file_id)
         end

data/lib/tahweel/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Tahweel
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/tahweel/writer.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
-require_relative "writers/txt"
 require_relative "writers/docx"
 require_relative "writers/json"
+require_relative "writers/txt"
 
 module Tahweel
   # Factory class for writing extracted text to different formats.

data/lib/tahweel/writers/docx.rb

@@ -14,10 +14,11 @@ module Tahweel
       # Writes the extracted texts to a file.
       #
       # It applies several transformations to the text before writing:
-      # 1. Normalizes line endings to `\n`.
+      # 1. Normalizes all line endings (`\r\n`, `\r`) to `\n`.
       # 2. Collapses consecutive identical whitespace characters.
       # 3. Compacts the text by merging short lines if the page is too long (> 40 lines).
       # 4. Determines text alignment (RTL/LTR) based on content.
+      # 5. Converts `\n` to proper OOXML line breaks for cross-platform compatibility.
       #
       # @param texts [Array<String>] The extracted texts (one per page).
       # @param destination [String] The output file path.
@@ -26,10 +27,10 @@ module Tahweel
       def write(texts, destination, options = {}) # rubocop:disable Lint/UnusedMethodArgument
         Caracal::Document.save(destination) do |docx|
           texts.each_with_index do |text, index|
-            text = text.gsub(/(\r\n)+/, "\n").gsub(/(\s)\1+/, '\1').strip
+            text = text.gsub(/\r\n?/, "\n").gsub(/(\s)\1+/, '\1').strip
             text = compact_shortest_lines(text) while expected_lines_in_page(text) > 40
 
-            docx.p text, size: 20, align: alignment_for(text)
+            write_paragraph(docx, text)
 
             docx.page if index < texts.size - 1
           end
@@ -38,6 +39,28 @@ module Tahweel
 
       private
 
+      # Writes a paragraph with proper OOXML line breaks.
+      #
+      # Raw newline characters (\n, \r\n) are not valid line breaks in DOCX format.
+      # Microsoft Word on Windows requires proper <w:br/> elements for line breaks,
+      # while macOS Pages is more lenient. This method uses Caracal's `br` method
+      # to insert cross-platform compatible line breaks.
+      #
+      # @param docx [Caracal::Document] The document to write to.
+      # @param text [String] The text content with newlines.
+      # @return [void]
+      def write_paragraph(docx, text)
+        lines = text.split("\n")
+        alignment = alignment_for(text)
+
+        docx.p align: alignment do
+          lines.each_with_index do |line, line_index|
+            text line, size: 20
+            br if line_index < lines.size - 1
+          end
+        end
+      end
+
       # Determines the text alignment based on the ratio of Arabic to non-Arabic characters.
       #
       # @param text [String] The text to analyze.

data/lib/tahweel.rb

@@ -1,14 +1,19 @@
 # frozen_string_literal: true
 
 require_relative "tahweel/version"
+require_relative "tahweel/cli/options"
+require_relative "tahweel/cli/file_processor"
+require_relative "tahweel/cli/file_collector"
 require_relative "tahweel/authorizer"
+require_relative "tahweel/poppler_installer"
 require_relative "tahweel/pdf_splitter"
 require_relative "tahweel/ocr"
+require_relative "tahweel/processors/google_drive"
 require_relative "tahweel/converter"
 require_relative "tahweel/writer"
-require_relative "tahweel/cli/file_processor"
-require_relative "tahweel/cli/file_collector"
-require_relative "tahweel/cli/options"
+require_relative "tahweel/writers/txt"
+require_relative "tahweel/writers/docx"
+require_relative "tahweel/writers/json"
 
 module Tahweel # rubocop:disable Style/Documentation
   class Error < StandardError; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tahweel
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Ali Hamdi Ali Fadel
@@ -23,6 +23,48 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: csv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.3'
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: glimmer-dsl-libui
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.13.1
 - !ruby/object:Gem::Dependency
   name: google-apis-drive_v3
   requirement: !ruby/object:Gem::Requirement
@@ -79,20 +121,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.3'
-- !ruby/object:Gem::Dependency
-  name: ruby-vips
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.2'
 - !ruby/object:Gem::Dependency
   name: xdg
   requirement: !ruby/object:Gem::Requirement
@@ -114,6 +142,7 @@ email:
 executables:
 - tahweel
 - tahweel-clear
+- tahweel-ui
 extensions: []
 extra_rdoc_files: []
 files:
@@ -124,8 +153,11 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- assets/logo.png
+- assets/windows/tahweel.ico
 - bin/tahweel
 - bin/tahweel-clear
+- bin/tahweel-ui
 - lib/tahweel.rb
 - lib/tahweel/authorizer.rb
 - lib/tahweel/cli/file_collector.rb
@@ -135,6 +167,7 @@ files:
 - lib/tahweel/converter.rb
 - lib/tahweel/ocr.rb
 - lib/tahweel/pdf_splitter.rb
+- lib/tahweel/poppler_installer.rb
 - lib/tahweel/processors/google_drive.rb
 - lib/tahweel/templates/success.html
 - lib/tahweel/version.rb