stimulus-pdf-viewer-rails 0.1.0

data/config/importmap.rb

@@ -0,0 +1,4 @@
+# Importmap pins for stimulus-pdf-viewer
+# These are automatically added when the gem is loaded
+
+pin "stimulus-pdf-viewer", to: "stimulus-pdf-viewer.esm.js"

data/lib/generators/stimulus_pdf_viewer/install/templates/views/_toolbar.html.erb

@@ -0,0 +1,220 @@
+<div class="pdf-toolbar">
+  <%# Left section: Sidebar toggle + Page navigation + Zoom %>
+  <div class="pdf-toolbar-section pdf-toolbar-left">
+    <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#toggleSidebar" title="Toggle thumbnails">
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+        <rect x="3" y="3" width="7" height="18" rx="1" />
+        <line x1="14" y1="6" x2="21" y2="6" />
+        <line x1="14" y1="12" x2="21" y2="12" />
+        <line x1="14" y1="18" x2="21" y2="18" />
+      </svg>
+    </button>
+
+    <div class="pdf-toolbar-separator"></div>
+
+    <div class="pdf-toolbar-group pdf-toolbar-nav">
+      <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#previousPage" title="Previous page" data-pdf-viewer-target="prevBtn">
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+          <path d="M8 12L3 7l5-5v10z" />
+        </svg>
+      </button>
+      <div class="pdf-page-input-container">
+        <input type="number" class="pdf-page-input" data-action="change->pdf-viewer#goToPage keydown->pdf-viewer#handlePageInputKey" data-pdf-viewer-target="pageInput" min="1" value="1" autocomplete="off">
+        <span class="pdf-page-separator">/</span>
+        <span class="pdf-page-count" data-pdf-viewer-target="pageCount">-</span>
+      </div>
+      <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#nextPage" title="Next page" data-pdf-viewer-target="nextBtn">
+        <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+          <path d="M8 4l5 5-5 5V4z" />
+        </svg>
+      </button>
+    </div>
+
+    <div class="pdf-toolbar-separator"></div>
+
+    <div class="pdf-toolbar-group pdf-toolbar-zoom">
+      <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#zoomOut" title="Zoom out">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <circle cx="11" cy="11" r="8" />
+          <line x1="21" y1="21" x2="16.65" y2="16.65" />
+          <line x1="8" y1="11" x2="14" y2="11" />
+        </svg>
+      </button>
+      <select class="pdf-zoom-select" data-action="change->pdf-viewer#setZoom" data-pdf-viewer-target="zoomSelect">
+        <option value="auto" selected>Auto</option>
+        <option value="page-width">Page Width</option>
+        <option value="page-fit">Page Fit</option>
+        <option value="page-actual">Actual Size</option>
+        <option disabled>-----</option>
+        <option value="0.5">50%</option>
+        <option value="0.75">75%</option>
+        <option value="1">100%</option>
+        <option value="1.25">125%</option>
+        <option value="1.5">150%</option>
+        <option value="2">200%</option>
+        <option value="3">300%</option>
+      </select>
+      <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#zoomIn" title="Zoom in">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <circle cx="11" cy="11" r="8" />
+          <line x1="21" y1="21" x2="16.65" y2="16.65" />
+          <line x1="11" y1="8" x2="11" y2="14" />
+          <line x1="8" y1="11" x2="14" y2="11" />
+        </svg>
+      </button>
+    </div>
+  </div>
+
+  <%# Right section: Annotation tools %>
+  <div class="pdf-toolbar-section pdf-toolbar-right">
+    <div class="pdf-toolbar-group pdf-toolbar-tools">
+      <button class="pdf-tool-btn active" data-tool="select" data-action="click->pdf-viewer#selectTool" aria-label="Select tool">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M3 3l7.07 16.97 2.51-7.39 7.39-2.51L3 3z" />
+          <path d="M13 13l6 6" />
+        </svg>
+        <span>Select</span>
+      </button>
+      <button class="pdf-tool-btn" data-tool="highlight" data-action="click->pdf-viewer#selectTool" aria-label="Highlight tool">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M12 20h9" />
+          <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z" />
+          <rect x="2" y="18" width="8" height="4" rx="1" fill="#FFEB3B" stroke="none" />
+        </svg>
+        <span>Highlight</span>
+      </button>
+      <button class="pdf-tool-btn" data-tool="underline" data-action="click->pdf-viewer#selectTool" aria-label="Underline tool">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+          <line x1="4" y1="21" x2="20" y2="21" stroke-width="3" />
+        </svg>
+        <span>Underline</span>
+      </button>
+      <button class="pdf-tool-btn" data-tool="note" data-action="click->pdf-viewer#selectTool" aria-label="Add note">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z" fill="#FFF9C4" />
+          <line x1="8" y1="9" x2="16" y2="9" />
+          <line x1="8" y1="13" x2="14" y2="13" />
+        </svg>
+        <span>Add Note</span>
+      </button>
+      <button class="pdf-tool-btn" data-tool="ink" data-action="click->pdf-viewer#selectTool" aria-label="Draw tool">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M17 3a2.828 2.828 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5L17 3z" />
+        </svg>
+        <span>Draw</span>
+      </button>
+    </div>
+
+    <div class="pdf-toolbar-separator"></div>
+
+    <div class="pdf-toolbar-group pdf-toolbar-colors" data-pdf-viewer-target="colorPicker">
+      <%# Color picker will be rendered here by JavaScript %>
+    </div>
+
+    <div class="pdf-toolbar-separator"></div>
+
+    <div class="pdf-toolbar-group pdf-toolbar-actions">
+      <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#toggleSearch" title="Search (Ctrl+F)">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <circle cx="11" cy="11" r="8" />
+          <line x1="21" y1="21" x2="16.65" y2="16.65" />
+        </svg>
+      </button>
+      <div class="pdf-toolbar-separator"></div>
+
+      <%# Overflow menu button (visible on mobile only) %>
+      <button class="pdf-toolbar-overflow-btn" data-action="click->pdf-viewer#toggleOverflowMenu" title="More tools" data-pdf-viewer-target="overflowBtn">
+        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+          <circle cx="12" cy="12" r="1" fill="currentColor" />
+          <circle cx="12" cy="5" r="1" fill="currentColor" />
+          <circle cx="12" cy="19" r="1" fill="currentColor" />
+        </svg>
+      </button>
+
+      <button class="pdf-toolbar-btn" data-action="click->pdf-viewer#toggleAnnotationSidebar" title="Annotations">
+        <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+          <line x1="17" y1="6" x2="21" y2="6" />
+          <line x1="17" y1="12" x2="21" y2="12" />
+          <line x1="17" y1="18" x2="21" y2="18" />
+          <rect x="3" y="3" width="7" height="18" rx="1" />
+        </svg>
+      </button>
+    </div>
+
+    <%# Overflow menu dropdown (mobile - nav, zoom, actions) %>
+    <div class="pdf-toolbar-overflow-menu" data-pdf-viewer-target="overflowMenu">
+      <%# Page Navigation %>
+      <div class="pdf-overflow-section">
+        <div class="pdf-overflow-row">
+          <button class="pdf-overflow-btn" data-action="click->pdf-viewer#previousPage" title="Previous page">
+            <svg width="20" height="20" viewBox="0 0 16 16" fill="currentColor">
+              <path d="M8 12L3 7l5-5v10z" />
+            </svg>
+          </button>
+          <div class="pdf-overflow-page-display">
+            <span data-pdf-viewer-target="overflowPageNum">1</span>
+            <span class="pdf-page-separator">/</span>
+            <span data-pdf-viewer-target="overflowPageCount">-</span>
+          </div>
+          <button class="pdf-overflow-btn" data-action="click->pdf-viewer#nextPage" title="Next page">
+            <svg width="20" height="20" viewBox="0 0 16 16" fill="currentColor">
+              <path d="M8 4l5 5-5 5V4z" />
+            </svg>
+          </button>
+        </div>
+      </div>
+
+      <%# More Tools (underline, ink) %>
+      <div class="pdf-overflow-section">
+        <div class="pdf-overflow-section-title">More Tools</div>
+        <div class="pdf-overflow-tools">
+          <button class="pdf-overflow-tool-btn" data-tool="underline" data-action="click->pdf-viewer#selectToolFromOverflow" aria-label="Underline tool">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M6 3v7a6 6 0 0 0 6 6 6 6 0 0 0 6-6V3" />
+              <line x1="4" y1="21" x2="20" y2="21" stroke-width="3" />
+            </svg>
+            <span>Underline</span>
+          </button>
+          <button class="pdf-overflow-tool-btn" data-tool="ink" data-action="click->pdf-viewer#selectToolFromOverflow" aria-label="Draw tool">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <path d="M17 3a2.828 2.828 0 1 1 4 4L7.5 20.5 2 22l1.5-5.5L17 3z" />
+            </svg>
+            <span>Draw</span>
+          </button>
+        </div>
+      </div>
+
+      <%# Actions %>
+      <div class="pdf-overflow-section">
+        <div class="pdf-overflow-actions">
+          <button class="pdf-overflow-action-btn" data-action="click->pdf-viewer#toggleSearch">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+              <circle cx="11" cy="11" r="8" />
+              <line x1="21" y1="21" x2="16.65" y2="16.65" />
+            </svg>
+            <span>Search</span>
+          </button>
+          <button class="pdf-overflow-action-btn" data-action="click->pdf-viewer#toggleSidebar">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <rect x="3" y="3" width="7" height="18" rx="1" />
+              <line x1="14" y1="6" x2="21" y2="6" />
+              <line x1="14" y1="12" x2="21" y2="12" />
+              <line x1="14" y1="18" x2="21" y2="18" />
+            </svg>
+            <span>Thumbnails</span>
+          </button>
+          <button class="pdf-overflow-action-btn" data-action="click->pdf-viewer#toggleAnnotationSidebar">
+            <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+              <line x1="17" y1="6" x2="21" y2="6" />
+              <line x1="17" y1="12" x2="21" y2="12" />
+              <line x1="17" y1="18" x2="21" y2="18" />
+              <rect x="3" y="3" width="7" height="18" rx="1" />
+            </svg>
+            <span>Annotations</span>
+          </button>
+        </div>
+      </div>
+    </div>
+  </div>
+</div>

data/lib/generators/stimulus_pdf_viewer/install/templates/views/_viewer.html.erb

@@ -0,0 +1,54 @@
+<%#
+  PDF Viewer partial example for Rails
+
+  Required local variables:
+    - document: An object with `file` (ActiveStorage attachment) and `name` attributes
+    - annotations_url: Path to the annotations REST endpoint
+
+  Optional local variables:
+    - user_name: Current user's name (for watermarks)
+    - organization_name: Organization name (for watermarks)
+    - initial_page: Page number to open on load
+    - initial_annotation: Annotation ID to highlight on load
+    - tracking_url: Endpoint for time tracking (optional)
+%>
+
+<div class="pdf-viewer-container"
+     data-controller="pdf-viewer"
+     data-pdf-viewer-target="container"
+     data-pdf-viewer-document-url-value="<%= url_for(document.file) %>"
+     data-pdf-viewer-document-name-value="<%= document.name %>"
+     data-pdf-viewer-annotations-url-value="<%= annotations_url %>"
+     <% if local_assigns[:user_name] %>
+       data-pdf-viewer-user-name-value="<%= user_name %>"
+     <% end %>
+     <% if local_assigns[:organization_name] %>
+       data-pdf-viewer-organization-name-value="<%= organization_name %>"
+     <% end %>
+     <% if local_assigns[:initial_page] %>
+       data-pdf-viewer-initial-page-value="<%= initial_page %>"
+     <% end %>
+     <% if local_assigns[:initial_annotation] %>
+       data-pdf-viewer-initial-annotation-value="<%= initial_annotation %>"
+     <% end %>
+     <% if local_assigns[:tracking_url] %>
+       data-pdf-viewer-tracking-url-value="<%= tracking_url %>"
+     <% end %>>
+
+  <%# Toolbar - render the toolbar partial %>
+  <div class="pdf-viewer-toolbar">
+    <%= render "path/to/toolbar" %>
+  </div>
+
+  <%# Main viewer body %>
+  <div class="pdf-viewer-body">
+    <%# Loading overlay - shown while PDF loads %>
+    <div class="pdf-loading-overlay" data-pdf-viewer-target="loadingOverlay">
+      <div class="pdf-loading-spinner"></div>
+      <div class="pdf-loading-text">Loading document...</div>
+    </div>
+
+    <%# PDF pages container - pages are rendered here by JavaScript %>
+    <div class="pdf-pages-container"></div>
+  </div>
+</div>

data/lib/generators/stimulus_pdf_viewer/install_generator.rb

@@ -0,0 +1,95 @@
+require "rails/generators"
+
+module StimulusPdfViewer
+  module Generators
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("install/templates", __dir__)
+
+      desc "Install stimulus-pdf-viewer into your Rails application"
+
+      def register_stimulus_controller
+        say "Registering Stimulus controller..."
+
+        controller_registration = <<~JS
+
+          // PDF Viewer
+          import { PdfViewerController, PdfDownloadController } from "stimulus-pdf-viewer"
+          application.register("pdf-viewer", PdfViewerController)
+          application.register("pdf-download", PdfDownloadController)
+        JS
+
+        controllers_file = "app/javascript/controllers/index.js"
+
+        if File.exist?(controllers_file)
+          append_to_file controllers_file, controller_registration
+          say "Added controller registration to #{controllers_file}", :green
+        else
+          say "Could not find #{controllers_file}. Please manually register the controllers:", :yellow
+          say controller_registration
+        end
+      end
+
+      def add_stylesheet_import
+        say "Adding stylesheet import..."
+
+        stylesheet_import = '@import "stimulus-pdf-viewer";'
+
+        # Try common stylesheet locations
+        stylesheet_files = [
+          "app/assets/stylesheets/application.scss",
+          "app/assets/stylesheets/application.css.scss",
+          "app/assets/stylesheets/application.sass.scss"
+        ]
+
+        stylesheet_file = stylesheet_files.find { |f| File.exist?(f) }
+
+        if stylesheet_file
+          append_to_file stylesheet_file, "\n#{stylesheet_import}\n"
+          say "Added stylesheet import to #{stylesheet_file}", :green
+        else
+          say "Could not find a SCSS stylesheet. Please manually add:", :yellow
+          say stylesheet_import
+        end
+      end
+
+      def add_pdf_worker_meta_tag
+        say "Adding PDF.js worker meta tag..."
+
+        meta_tag = '<meta name="pdf-worker-src" content="https://cdnjs.cloudflare.com/ajax/libs/pdf.js/4.0.379/pdf.worker.min.js">'
+
+        layout_file = "app/views/layouts/application.html.erb"
+
+        if File.exist?(layout_file)
+          inject_into_file layout_file, "    #{meta_tag}\n", after: "<head>\n"
+          say "Added PDF worker meta tag to #{layout_file}", :green
+        else
+          say "Could not find #{layout_file}. Please manually add to your <head>:", :yellow
+          say meta_tag
+        end
+      end
+
+      def copy_example_partials
+        if yes?("Would you like to copy example view partials? (y/n)")
+          directory "views", "app/views/pdf_viewer"
+          say "Copied example partials to app/views/pdf_viewer/", :green
+        end
+      end
+
+      def show_next_steps
+        say ""
+        say "=" * 60, :green
+        say "stimulus-pdf-viewer installed successfully!", :green
+        say "=" * 60, :green
+        say ""
+        say "Next steps:"
+        say "1. Create an Annotation model and controller for your app"
+        say "2. Set up routes for annotations REST API"
+        say "3. Add the PDF viewer partial to your views"
+        say ""
+        say "See the README for detailed integration instructions:"
+        say "https://github.com/jhubert/stimulus-pdf-viewer-rails"
+        say ""
+      end
+    end
+  end
+end

data/lib/stimulus-pdf-viewer-rails.rb

@@ -0,0 +1,2 @@
+# Convenience require for the gem
+require "stimulus_pdf_viewer/rails"

data/lib/stimulus_pdf_viewer/rails/engine.rb

@@ -0,0 +1,26 @@
+module StimulusPdfViewer
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace StimulusPdfViewer
+
+      initializer "stimulus-pdf-viewer.assets" do |app|
+        # Add our assets to the asset paths
+        app.config.assets.paths << root.join("app/assets/javascripts")
+        app.config.assets.paths << root.join("app/assets/stylesheets")
+        app.config.assets.paths << root.join("app/assets/images")
+
+        # Precompile the main JS file
+        app.config.assets.precompile += %w[
+          stimulus-pdf-viewer.esm.js
+          stimulus-pdf-viewer.js
+        ]
+      end
+
+      initializer "stimulus-pdf-viewer.importmap", before: "importmap" do |app|
+        if app.config.respond_to?(:importmap)
+          app.config.importmap.paths << root.join("config/importmap.rb")
+        end
+      end
+    end
+  end
+end

data/lib/stimulus_pdf_viewer/rails/version.rb

@@ -0,0 +1,7 @@
+module StimulusPdfViewer
+  module Rails
+    VERSION = "0.1.0"
+    # This should match the npm package version
+    STIMULUS_PDF_VIEWER_VERSION = "0.1.0"
+  end
+end

data/lib/stimulus_pdf_viewer/rails.rb

@@ -0,0 +1,7 @@
+require "stimulus_pdf_viewer/rails/version"
+require "stimulus_pdf_viewer/rails/engine"
+
+module StimulusPdfViewer
+  module Rails
+  end
+end

data/lib/tasks/assets.rake

@@ -0,0 +1,196 @@
+require "fileutils"
+require "json"
+require "open-uri"
+require "tmpdir"
+
+namespace :stimulus_pdf_viewer do
+  desc "Update vendored assets from stimulus-pdf-viewer npm package"
+  task :update, [:version] do |_t, args|
+    version = args[:version] || "latest"
+    updater = StimulusPdfViewerAssetUpdater.new(version)
+    updater.run
+  end
+
+  desc "Check for newer versions of stimulus-pdf-viewer"
+  task :check do
+    checker = StimulusPdfViewerVersionChecker.new
+    checker.run
+  end
+end
+
+class StimulusPdfViewerAssetUpdater
+  NPM_REGISTRY_URL = "https://registry.npmjs.org/stimulus-pdf-viewer"
+  GEM_ROOT = File.expand_path("../..", __dir__)
+
+  ASSET_MAPPINGS = {
+    "dist/stimulus-pdf-viewer.esm.js" => "app/assets/javascripts/stimulus-pdf-viewer.esm.js",
+    "dist/stimulus-pdf-viewer.js" => "app/assets/javascripts/stimulus-pdf-viewer.js",
+    "styles/pdf-viewer.scss" => "app/assets/stylesheets/stimulus-pdf-viewer.scss"
+  }.freeze
+
+  CURSOR_SOURCE_DIR = "assets/cursors"
+  CURSOR_DEST_DIR = "app/assets/images/stimulus-pdf-viewer"
+
+  def initialize(version)
+    @requested_version = version
+  end
+
+  def run
+    puts "Fetching package info from npm registry..."
+    package_info = fetch_package_info
+
+    @version = resolve_version(package_info)
+    puts "Target version: #{@version}"
+
+    current_version = read_current_version
+    if current_version == @version && @requested_version == "latest"
+      puts "Already at version #{@version}. Use rake stimulus_pdf_viewer:update[#{@version}] to force reinstall."
+      return
+    end
+
+    if current_version == @version
+      puts "Reinstalling version #{@version}..."
+    else
+      puts "Updating from #{current_version} to #{@version}..."
+    end
+
+    Dir.mktmpdir do |tmpdir|
+      tarball_path = download_package(package_info, tmpdir)
+      extract_package(tarball_path, tmpdir)
+
+      package_dir = File.join(tmpdir, "package")
+      copy_assets(package_dir)
+      update_version_file
+    end
+
+    puts "Successfully updated to version #{@version}"
+  end
+
+  private
+
+  def fetch_package_info
+    JSON.parse(URI.open(NPM_REGISTRY_URL).read)
+  rescue OpenURI::HTTPError => e
+    abort "Failed to fetch package info: #{e.message}"
+  end
+
+  def resolve_version(package_info)
+    if @requested_version == "latest"
+      package_info["dist-tags"]["latest"]
+    else
+      unless package_info["versions"].key?(@requested_version)
+        available = package_info["versions"].keys.last(10).join(", ")
+        abort "Version #{@requested_version} not found. Recent versions: #{available}"
+      end
+      @requested_version
+    end
+  end
+
+  def read_current_version
+    version_file = File.join(GEM_ROOT, "lib/stimulus_pdf_viewer/rails/version.rb")
+    content = File.read(version_file)
+    match = content.match(/STIMULUS_PDF_VIEWER_VERSION\s*=\s*["']([^"']+)["']/)
+    match ? match[1] : "unknown"
+  end
+
+  def download_package(package_info, tmpdir)
+    tarball_url = package_info["versions"][@version]["dist"]["tarball"]
+    tarball_path = File.join(tmpdir, "package.tgz")
+
+    puts "Downloading #{tarball_url}..."
+    File.open(tarball_path, "wb") do |file|
+      URI.open(tarball_url) { |remote| file.write(remote.read) }
+    end
+
+    tarball_path
+  end
+
+  def extract_package(tarball_path, tmpdir)
+    puts "Extracting package..."
+    system("tar", "-xzf", tarball_path, "-C", tmpdir, exception: true)
+  end
+
+  def copy_assets(package_dir)
+    puts "Copying assets..."
+
+    ASSET_MAPPINGS.each do |src, dest|
+      src_path = File.join(package_dir, src)
+      dest_path = File.join(GEM_ROOT, dest)
+
+      unless File.exist?(src_path)
+        warn "  Warning: #{src} not found in package"
+        next
+      end
+
+      FileUtils.cp(src_path, dest_path)
+      puts "  #{src} -> #{dest}"
+    end
+
+    copy_cursors(package_dir)
+  end
+
+  def copy_cursors(package_dir)
+    cursor_src = File.join(package_dir, CURSOR_SOURCE_DIR)
+    cursor_dest = File.join(GEM_ROOT, CURSOR_DEST_DIR)
+
+    unless Dir.exist?(cursor_src)
+      warn "  Warning: #{CURSOR_SOURCE_DIR} not found in package"
+      return
+    end
+
+    FileUtils.mkdir_p(cursor_dest)
+
+    Dir.glob(File.join(cursor_src, "*.svg")).each do |svg|
+      FileUtils.cp(svg, cursor_dest)
+      puts "  #{CURSOR_SOURCE_DIR}/#{File.basename(svg)} -> #{CURSOR_DEST_DIR}/"
+    end
+  end
+
+  def update_version_file
+    version_file = File.join(GEM_ROOT, "lib/stimulus_pdf_viewer/rails/version.rb")
+    content = File.read(version_file)
+
+    updated = content.gsub(
+      /STIMULUS_PDF_VIEWER_VERSION\s*=\s*["'][^"']+["']/,
+      "STIMULUS_PDF_VIEWER_VERSION = \"#{@version}\""
+    )
+
+    File.write(version_file, updated)
+    puts "Updated STIMULUS_PDF_VIEWER_VERSION to #{@version}"
+  end
+end
+
+class StimulusPdfViewerVersionChecker
+  NPM_REGISTRY_URL = "https://registry.npmjs.org/stimulus-pdf-viewer"
+  GEM_ROOT = File.expand_path("../..", __dir__)
+
+  def run
+    current = read_current_version
+    latest = fetch_latest_version
+
+    puts "Current vendored version: #{current}"
+    puts "Latest npm version: #{latest}"
+
+    if current == latest
+      puts "You are up to date!"
+    else
+      puts "Update available! Run: rake stimulus_pdf_viewer:update"
+    end
+  end
+
+  private
+
+  def read_current_version
+    version_file = File.join(GEM_ROOT, "lib/stimulus_pdf_viewer/rails/version.rb")
+    content = File.read(version_file)
+    match = content.match(/STIMULUS_PDF_VIEWER_VERSION\s*=\s*["']([^"']+)["']/)
+    match ? match[1] : "unknown"
+  end
+
+  def fetch_latest_version
+    response = JSON.parse(URI.open(NPM_REGISTRY_URL).read)
+    response["dist-tags"]["latest"]
+  rescue OpenURI::HTTPError => e
+    abort "Failed to fetch package info: #{e.message}"
+  end
+end