highlite 0.1.0

data/app/javascript/highlite/lib/pdf_renderer.js

@@ -0,0 +1,212 @@
+/**
+ * PdfRenderer — PDF.js wrapper that abstracts all PDF.js interactions.
+ *
+ * Loads a PDF document from a URL and provides methods for rendering pages,
+ * text layers, thumbnails, and extracting metadata.
+ *
+ * @example
+ *   const renderer = new PdfRenderer("/documents/sample.pdf")
+ *   const { pageCount, title } = await renderer.load()
+ *   await renderer.renderPage(1, canvasElement, 1.5)
+ */
+
+const PDFJS_WORKER_CDN =
+  "https://cdn.jsdelivr.net/npm/pdfjs-dist@5.4.624/build/pdf.worker.min.mjs"
+
+export class PdfRenderer {
+  /**
+   * @param {string} url - URL of the PDF to load
+   * @param {Object} [options={}]
+   * @param {string} [options.workerSrc] - Custom PDF.js worker URL
+   */
+  constructor(url, options = {}) {
+    this.url = url
+    this.options = options
+    this.pdfjs = null
+    this.document = null
+    this._pages = new Map()
+  }
+
+  /**
+   * Load the PDF document. Must be called before any other method.
+   * @returns {Promise<{pageCount: number, title: string|null}>}
+   */
+  async load() {
+    this.pdfjs = await import("pdfjs-dist")
+    this.pdfjs.GlobalWorkerOptions.workerSrc =
+      this.options.workerSrc || PDFJS_WORKER_CDN
+
+    try {
+      this.document = await this.pdfjs.getDocument({ url: this.url }).promise
+    } catch (error) {
+      throw new Error(`Failed to load PDF from ${this.url}: ${error.message}`)
+    }
+
+    const metadata = await this.document.getMetadata().catch(() => null)
+    const title = metadata?.info?.Title || null
+
+    return { pageCount: this.document.numPages, title }
+  }
+
+  /**
+   * Get a cached page proxy.
+   * @param {number} pageNum - 1-based page number
+   * @returns {Promise<PDFPageProxy>}
+   */
+  async _getPage(pageNum) {
+    if (!this.document) throw new Error("PDF not loaded. Call load() first.")
+    if (pageNum < 1 || pageNum > this.document.numPages) {
+      throw new RangeError(
+        `Page ${pageNum} out of range (1-${this.document.numPages})`
+      )
+    }
+
+    if (!this._pages.has(pageNum)) {
+      this._pages.set(pageNum, await this.document.getPage(pageNum))
+    }
+    return this._pages.get(pageNum)
+  }
+
+  /**
+   * Get the viewport for a page at a given scale.
+   * @param {number} pageNum - 1-based page number
+   * @param {number} scale
+   * @returns {Promise<PDFPageViewport>}
+   */
+  async getViewport(pageNum, scale) {
+    const page = await this._getPage(pageNum)
+    return page.getViewport({ scale })
+  }
+
+  /**
+   * Render a page onto a canvas element.
+   * @param {number} pageNum - 1-based page number
+   * @param {HTMLCanvasElement} canvas
+   * @param {number} scale
+   * @returns {Promise<void>}
+   */
+  async renderPage(pageNum, canvas, scale) {
+    const page = await this._getPage(pageNum)
+    const viewport = page.getViewport({ scale })
+    const context = canvas.getContext("2d")
+
+    const dpr = window.devicePixelRatio || 1
+    canvas.width = Math.floor(viewport.width * dpr)
+    canvas.height = Math.floor(viewport.height * dpr)
+    canvas.style.width = `${Math.floor(viewport.width)}px`
+    canvas.style.height = `${Math.floor(viewport.height)}px`
+
+    context.setTransform(dpr, 0, 0, dpr, 0, 0)
+
+    await page.render({ canvasContext: context, viewport }).promise
+  }
+
+  /**
+   * Render the selectable text layer for a page.
+   * Creates positioned span elements that overlay the canvas for text selection.
+   * @param {number} pageNum - 1-based page number
+   * @param {HTMLElement} container - Element to render text spans into
+   * @param {PDFPageViewport} viewport
+   * @returns {Promise<void>}
+   */
+  async renderTextLayer(pageNum, container, viewport) {
+    const page = await this._getPage(pageNum)
+    const textContent = await page.getTextContent()
+
+    // Clear existing text layer content
+    container.innerHTML = ""
+
+    // Use PDF.js TextLayer API
+    const textLayer = new this.pdfjs.TextLayer({
+      textContentSource: textContent,
+      container,
+      viewport,
+    })
+
+    await textLayer.render()
+  }
+
+  /**
+   * Render a small thumbnail of a page.
+   * @param {number} pageNum - 1-based page number
+   * @param {HTMLCanvasElement} canvas
+   * @param {number} [scale=0.2]
+   * @returns {Promise<void>}
+   */
+  async renderThumbnail(pageNum, canvas, scale = 0.2) {
+    await this.renderPage(pageNum, canvas, scale)
+  }
+
+  /**
+   * Extract the outline (table of contents) from the PDF.
+   * @returns {Promise<Array<{title: string, dest: *, items: Array}>>}
+   */
+  async getOutline() {
+    if (!this.document) throw new Error("PDF not loaded. Call load() first.")
+
+    const outline = await this.document.getOutline()
+    if (!outline) return []
+
+    return this._normalizeOutline(outline)
+  }
+
+  /**
+   * Recursively normalize outline items, resolving page numbers from destinations.
+   * @param {Array} items - Raw outline items from PDF.js
+   * @returns {Promise<Array<{title: string, pageNum: number|null, items: Array}>>}
+   */
+  async _normalizeOutline(items) {
+    const results = []
+
+    for (const item of items) {
+      let pageNum = null
+
+      try {
+        if (item.dest) {
+          const dest =
+            typeof item.dest === "string"
+              ? await this.document.getDestination(item.dest)
+              : item.dest
+
+          if (dest && dest[0]) {
+            const pageIndex = await this.document.getPageIndex(dest[0])
+            pageNum = pageIndex + 1 // Convert 0-based to 1-based
+          }
+        }
+      } catch {
+        // Destination resolution can fail for malformed PDFs; skip silently
+      }
+
+      const children = item.items?.length
+        ? await this._normalizeOutline(item.items)
+        : []
+
+      results.push({ title: item.title, pageNum, items: children })
+    }
+
+    return results
+  }
+
+  /**
+   * Get plain text content for a page.
+   * @param {number} pageNum - 1-based page number
+   * @returns {Promise<string>}
+   */
+  async getPageText(pageNum) {
+    const page = await this._getPage(pageNum)
+    const textContent = await page.getTextContent()
+
+    return textContent.items.map((item) => item.str).join(" ")
+  }
+
+  /**
+   * Clean up resources. Call when the viewer is torn down.
+   */
+  destroy() {
+    if (this.document) {
+      this.document.destroy()
+      this.document = null
+    }
+    this._pages.clear()
+  }
+}

data/app/views/highlite/_floating_toolbar.html.erb

@@ -0,0 +1,79 @@
+<%# Floating annotation toolbar — positioned on the right edge of the PDF viewer %>
+
+<div class="absolute right-4 top-1/2 -translate-y-1/2 z-20 flex flex-col gap-1.5 p-1.5 bg-gray-800/90 backdrop-blur rounded-xl shadow-lg">
+  <%# Select / cursor tool %>
+  <button type="button"
+          data-action="highlite--highlight#setTool"
+          data-highlite--highlight-tool-param="select"
+          data-highlite--highlight-target="toolButton"
+          class="p-2 rounded-lg text-white bg-gray-700 hover:bg-gray-600 ring-2 ring-blue-500 transition-all"
+          title="Select">
+    <svg class="h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M15.042 21.672 13.684 16.6m0 0-2.51 2.225.569-9.47 5.227 7.917-3.286-.672Zm-7.518-.267A8.25 8.25 0 1 1 20.25 10.5M8.288 14.212A5.25 5.25 0 1 1 17.25 10.5" />
+    </svg>
+  </button>
+
+  <%# Text highlight tool %>
+  <button type="button"
+          data-action="highlite--highlight#setTool"
+          data-highlite--highlight-tool-param="text"
+          data-highlite--highlight-target="toolButton"
+          class="p-2 rounded-lg text-gray-400 hover:text-white hover:bg-gray-600 transition-all"
+          title="Text highlight">
+    <svg class="h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+      <path stroke-linecap="round" stroke-linejoin="round" d="m16.862 4.487 1.687-1.688a1.875 1.875 0 1 1 2.652 2.652L10.582 16.07a4.5 4.5 0 0 1-1.897 1.13L6 18l.8-2.685a4.5 4.5 0 0 1 1.13-1.897l8.932-8.931Zm0 0L19.5 7.125M18 14v4.75A2.25 2.25 0 0 1 15.75 21H5.25A2.25 2.25 0 0 1 3 18.75V8.25A2.25 2.25 0 0 1 5.25 6H10" />
+    </svg>
+  </button>
+
+  <%# Area highlight tool %>
+  <button type="button"
+          data-action="highlite--highlight#setTool"
+          data-highlite--highlight-tool-param="area"
+          data-highlite--highlight-target="toolButton"
+          class="p-2 rounded-lg text-gray-400 hover:text-white hover:bg-gray-600 transition-all"
+          title="Area highlight">
+    <svg class="h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M5.25 7.5A2.25 2.25 0 0 1 7.5 5.25h9a2.25 2.25 0 0 1 2.25 2.25v9a2.25 2.25 0 0 1-2.25 2.25h-9a2.25 2.25 0 0 1-2.25-2.25v-9Z" />
+    </svg>
+  </button>
+
+  <%# Divider %>
+  <div class="border-t border-gray-600 mx-1"></div>
+
+  <%# Color buttons %>
+  <button type="button"
+          data-action="highlite--highlight#setColor"
+          data-highlite--highlight-color-param="rgba(255, 226, 143, 0.5)"
+          data-highlite--highlight-target="colorButton"
+          class="w-8 h-8 mx-auto rounded-full ring-2 ring-blue-500 transition-all"
+          style="background-color: rgba(255, 226, 143, 0.8)"
+          title="Yellow">
+  </button>
+
+  <button type="button"
+          data-action="highlite--highlight#setColor"
+          data-highlite--highlight-color-param="rgba(166, 227, 161, 0.5)"
+          data-highlite--highlight-target="colorButton"
+          class="w-8 h-8 mx-auto rounded-full ring-2 ring-transparent hover:ring-gray-500 transition-all"
+          style="background-color: rgba(166, 227, 161, 0.8)"
+          title="Green">
+  </button>
+
+  <button type="button"
+          data-action="highlite--highlight#setColor"
+          data-highlite--highlight-color-param="rgba(137, 180, 250, 0.5)"
+          data-highlite--highlight-target="colorButton"
+          class="w-8 h-8 mx-auto rounded-full ring-2 ring-transparent hover:ring-gray-500 transition-all"
+          style="background-color: rgba(137, 180, 250, 0.8)"
+          title="Blue">
+  </button>
+
+  <button type="button"
+          data-action="highlite--highlight#setColor"
+          data-highlite--highlight-color-param="rgba(245, 194, 231, 0.5)"
+          data-highlite--highlight-target="colorButton"
+          class="w-8 h-8 mx-auto rounded-full ring-2 ring-transparent hover:ring-gray-500 transition-all"
+          style="background-color: rgba(245, 194, 231, 0.8)"
+          title="Pink">
+  </button>
+</div>

data/app/views/highlite/_left_sidebar.html.erb

@@ -0,0 +1,43 @@
+<%# Left sidebar — Outline and Pages tabs with dark theme %>
+
+<div class="flex flex-col h-full bg-gray-900 text-gray-300 border-r border-gray-700">
+  <%# Tab bar %>
+  <div class="flex border-b border-gray-700">
+    <button type="button"
+            data-action="highlite--sidebar#showOutline"
+            data-highlite--sidebar-target="outlineTab"
+            class="flex-1 px-4 py-3 text-base font-medium text-gray-500 border-b-2 border-transparent hover:text-gray-300 transition-colors highlite-tab-active">
+      Outline
+    </button>
+    <button type="button"
+            data-action="highlite--sidebar#showPages"
+            data-highlite--sidebar-target="pagesTab"
+            class="flex-1 px-4 py-3 text-base font-medium text-gray-500 border-b-2 border-transparent hover:text-gray-300 transition-colors">
+      Pages
+    </button>
+  </div>
+
+  <%# Outline panel %>
+  <div data-highlite--sidebar-target="outlinePanel"
+       class="flex-1 overflow-y-auto p-3">
+    <div class="text-sm text-gray-500 italic py-4 text-center">
+      Loading outline&hellip;
+    </div>
+  </div>
+
+  <%# Pages (thumbnails) panel %>
+  <div data-highlite--sidebar-target="pagesPanel"
+       class="flex-1 overflow-y-auto p-3 hidden">
+    <div data-highlite--sidebar-target="thumbnailsContainer"
+         class="grid grid-cols-1 gap-2">
+      <div class="text-sm text-gray-500 italic py-4 text-center">
+        Loading pages&hellip;
+      </div>
+    </div>
+  </div>
+
+  <%# Page counter at bottom %>
+  <div data-highlite--sidebar-target="pageCounter"
+       class="border-t border-gray-700 px-3 py-2 text-base text-gray-500 text-center">
+  </div>
+</div>

data/app/views/highlite/_right_sidebar.html.erb

@@ -0,0 +1,56 @@
+<%# Default right sidebar — Highlights panel (dark theme) %>
+<%# This partial can be overridden by the host app %>
+
+<div class="flex flex-col h-full bg-gray-900 text-gray-300 border-l border-gray-700">
+  <%# Header %>
+  <div class="flex items-center justify-between px-4 py-3 border-b border-gray-700">
+    <div class="flex items-center gap-2">
+      <svg class="h-4 w-4 text-gray-400" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m0 12.75h7.5m-7.5 3H12M10.5 2.25H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" />
+      </svg>
+      <span class="text-base font-medium text-white">Highlights</span>
+    </div>
+    <span data-highlite--highlights-panel-target="count"
+          class="text-sm bg-gray-700 text-gray-300 px-2 py-0.5 rounded-full">
+      0
+    </span>
+  </div>
+
+  <%# Search input %>
+  <div class="px-3 py-2 border-b border-gray-700">
+    <div class="relative">
+      <svg class="absolute left-2.5 top-1/2 -translate-y-1/2 h-3.5 w-3.5 text-gray-500" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m21 21-5.197-5.197m0 0A7.5 7.5 0 1 0 5.196 5.196a7.5 7.5 0 0 0 10.607 10.607Z" />
+      </svg>
+      <input type="text"
+             placeholder="Search highlights..."
+             data-highlite--highlights-panel-target="searchInput"
+             data-action="input->highlite--highlights-panel#search"
+             class="w-full bg-gray-800 border border-gray-700 rounded text-sm text-gray-300 placeholder-gray-500 pl-8 pr-3 py-1.5 focus:outline-none focus:ring-1 focus:ring-blue-500 focus:border-blue-500">
+    </div>
+  </div>
+
+  <%# Highlights list (populated dynamically by JS) %>
+  <div data-highlite--highlights-panel-target="list"
+       class="flex-1 overflow-y-auto px-3 py-2">
+    <div class="flex flex-col items-center justify-center h-full text-center py-8">
+      <svg class="h-8 w-8 text-gray-600 mb-2" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M9.53 16.122a3 3 0 0 0-5.78 1.128 2.25 2.25 0 0 1-2.4 2.245 4.5 4.5 0 0 0 8.4-2.245c0-.399-.078-.78-.22-1.128Zm0 0a15.998 15.998 0 0 0 3.388-1.62m-5.043-.025a15.994 15.994 0 0 1 1.622-3.395m3.42 3.42a15.995 15.995 0 0 0 4.764-4.648l3.876-5.814a1.151 1.151 0 0 0-1.597-1.597L14.146 6.32a15.996 15.996 0 0 0-4.649 4.763m3.42 3.42a6.776 6.776 0 0 0-3.42-3.42" />
+      </svg>
+      <p class="text-sm text-gray-500">No highlights yet</p>
+      <p class="text-sm text-gray-600 mt-1">Select text or use the area tool to add highlights</p>
+    </div>
+  </div>
+
+  <%# Clear all button %>
+  <div class="border-t border-gray-700 px-3 py-2">
+    <button type="button"
+            data-action="highlite--highlights-panel#clearAll"
+            class="w-full flex items-center justify-center gap-1.5 px-3 py-1.5 text-sm text-gray-400 hover:text-red-400 hover:bg-gray-800 rounded transition-colors">
+      <svg class="h-3.5 w-3.5" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="m14.74 9-.346 9m-4.788 0L9.26 9m9.968-3.21c.342.052.682.107 1.022.166m-1.022-.165L18.16 19.673a2.25 2.25 0 0 1-2.244 2.077H8.084a2.25 2.25 0 0 1-2.244-2.077L4.772 5.79m14.456 0a48.108 48.108 0 0 0-3.478-.397m-12 .562c.34-.059.68-.114 1.022-.165m0 0a48.11 48.11 0 0 1 3.478-.397m7.5 0v-.916c0-1.18-.91-2.164-2.09-2.201a51.964 51.964 0 0 0-3.32 0c-1.18.037-2.09 1.022-2.09 2.201v.916m7.5 0a48.667 48.667 0 0 0-7.5 0" />
+      </svg>
+      Clear All Highlights
+    </button>
+  </div>
+</div>

data/app/views/highlite/_toolbar.html.erb

@@ -0,0 +1,63 @@
+<%# Top toolbar — zoom controls and page info %>
+
+<div class="sticky top-0 z-30 bg-white border-b border-gray-200 flex items-center justify-between px-4 py-2">
+  <%# Left: Logo / title %>
+  <div class="flex items-center gap-2 text-base font-medium text-gray-700">
+    <svg class="h-5 w-5 text-gray-500" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="1.5" stroke="currentColor">
+      <path stroke-linecap="round" stroke-linejoin="round" d="M19.5 14.25v-2.625a3.375 3.375 0 0 0-3.375-3.375h-1.5A1.125 1.125 0 0 1 13.5 7.125v-1.5a3.375 3.375 0 0 0-3.375-3.375H8.25m2.25 0H5.625c-.621 0-1.125.504-1.125 1.125v17.25c0 .621.504 1.125 1.125 1.125h12.75c.621 0 1.125-.504 1.125-1.125V11.25a9 9 0 0 0-9-9Z" />
+    </svg>
+    <span>PDF Viewer</span>
+  </div>
+
+  <%# Center: Zoom controls %>
+  <div class="flex items-center gap-1">
+    <%# Auto (fit width) %>
+    <button type="button"
+            data-action="highlite--viewer#zoomFit"
+            class="px-2.5 py-1 text-sm font-medium text-gray-600 bg-gray-100 hover:bg-gray-200 rounded transition-colors"
+            title="Fit to width">
+      Auto
+    </button>
+
+    <%# Zoom out %>
+    <button type="button"
+            data-action="highlite--viewer#zoomOut"
+            class="p-1.5 text-gray-500 hover:text-gray-700 hover:bg-gray-100 rounded transition-colors"
+            title="Zoom out (Ctrl+-)">
+      <svg class="h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M5 12h14" />
+      </svg>
+    </button>
+
+    <%# Zoom level display %>
+    <span data-highlite--viewer-target="zoomLevel"
+          class="min-w-[3.5rem] text-center text-sm font-medium text-gray-600">
+      150%
+    </span>
+
+    <%# Zoom in %>
+    <button type="button"
+            data-action="highlite--viewer#zoomIn"
+            class="p-1.5 text-gray-500 hover:text-gray-700 hover:bg-gray-100 rounded transition-colors"
+            title="Zoom in (Ctrl++)">
+      <svg class="h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M12 4.5v15m7.5-7.5h-15" />
+      </svg>
+    </button>
+
+    <%# Reset to default %>
+    <button type="button"
+            data-action="highlite--viewer#zoomAuto"
+            class="p-1.5 text-gray-500 hover:text-gray-700 hover:bg-gray-100 rounded transition-colors"
+            title="Reset zoom (Ctrl+0)">
+      <svg class="h-4 w-4" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor">
+        <path stroke-linecap="round" stroke-linejoin="round" d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.992 0 3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182M2.985 19.644l3.182-3.182" />
+      </svg>
+    </button>
+  </div>
+
+  <%# Right: Page info %>
+  <div class="flex items-center gap-2 text-base text-gray-500">
+    <span data-highlite--viewer-target="pageInfo">Page 1 of 1</span>
+  </div>
+</div>

data/app/views/highlite/_viewer.html.erb

@@ -0,0 +1,63 @@
+<%# Main 3-panel layout for the PDF viewer.
+     Locals: url, document_id, scale, show_toolbar, show_left_sidebar,
+             show_right_sidebar, right_sidebar_partial %>
+
+<div class="flex flex-col h-screen overflow-hidden"
+     data-controller="highlite--viewer highlite--highlight"
+     data-highlite--viewer-url-value="<%= url %>"
+     data-highlite--viewer-document-id-value="<%= document_id %>"
+     data-highlite--viewer-scale-value="<%= scale %>"
+     data-highlite--highlight-document-id-value="<%= document_id %>">
+
+  <% if show_toolbar %>
+    <%= render "highlite/toolbar" %>
+  <% end %>
+
+  <div class="flex flex-1 min-h-0">
+    <%# Left Sidebar — Outline & Pages %>
+    <% if show_left_sidebar %>
+      <div class="w-[280px] flex-shrink-0" data-controller="highlite--sidebar">
+        <%= render "highlite/left_sidebar" %>
+      </div>
+    <% end %>
+
+    <%# Center — PDF Viewer %>
+    <div class="flex-1 relative bg-gray-900 overflow-hidden">
+      <%# Loading overlay %>
+      <div data-highlite--viewer-target="loader"
+           class="absolute inset-0 z-40 flex items-center justify-center bg-gray-900">
+        <div class="flex flex-col items-center gap-3 text-gray-400">
+          <svg class="animate-spin h-8 w-8" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24">
+            <circle class="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" stroke-width="4"></circle>
+            <path class="opacity-75" fill="currentColor" d="M4 12a8 8 0 018-8V0C5.373 0 0 5.373 0 12h4zm2 5.291A7.962 7.962 0 014 12H0c0 3.042 1.135 5.824 3 7.938l3-2.647z"></path>
+          </svg>
+          <span class="text-sm">Loading PDF&hellip;</span>
+        </div>
+      </div>
+
+      <%# Scrollable pages container %>
+      <div data-highlite--viewer-target="pagesContainer"
+           class="highlite-pages-container h-full overflow-auto">
+      </div>
+
+      <%# Floating annotation toolbar %>
+      <%= render "highlite/floating_toolbar" %>
+    </div>
+
+    <%# Right Sidebar — Highlights panel (overridable) %>
+    <% if show_right_sidebar %>
+      <div class="w-[320px] flex-shrink-0"
+           data-controller="highlite--highlights-panel"
+           data-highlite--highlights-panel-document-id-value="<%= document_id %>">
+        <% if right_sidebar_partial.present? %>
+          <%= render partial: right_sidebar_partial %>
+        <% else %>
+          <%= render "highlite/right_sidebar" %>
+        <% end %>
+      </div>
+    <% end %>
+  </div>
+
+  <%# Page info (used by viewer controller) %>
+  <div data-highlite--viewer-target="pageInfo" class="hidden"></div>
+</div>

data/config/importmap.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+version = Highlite.configuration.pdf_js_version
+
+pin "pdfjs-dist", to: "https://cdn.jsdelivr.net/npm/pdfjs-dist@#{version}/build/pdf.min.mjs", preload: true
+pin "pdfjs-dist/build/pdf.worker.min.mjs",
+    to: "https://cdn.jsdelivr.net/npm/pdfjs-dist@#{version}/build/pdf.worker.min.mjs"
+
+# Gem JS entry point and internal modules
+pin "highlite", to: "highlite/index.js"
+pin "highlite/lib/pdf_renderer", to: "highlite/lib/pdf_renderer.js"
+pin "highlite/lib/highlight_store", to: "highlite/lib/highlight_store.js"
+pin "highlite/controllers/viewer_controller", to: "highlite/controllers/viewer_controller.js"
+pin "highlite/controllers/highlight_controller", to: "highlite/controllers/highlight_controller.js"
+pin "highlite/controllers/sidebar_controller", to: "highlite/controllers/sidebar_controller.js"
+pin "highlite/controllers/highlights_panel_controller",
+    to: "highlite/controllers/highlights_panel_controller.js"

data/lib/generators/highlite/install/install_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Highlite
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install Highlite: creates initializer and optionally copies sidebar override template"
+
+      class_option :sidebar, type: :boolean, default: false,
+                             desc: "Copy the right sidebar partial for customization"
+
+      def create_initializer
+        template "initializer.rb.tt", "config/initializers/highlite.rb"
+      end
+
+      def copy_sidebar_override
+        return unless options[:sidebar]
+
+        template "_right_sidebar.html.erb.tt",
+                 "app/views/highlite/_right_sidebar.html.erb"
+      end
+
+      def add_importmap_pin
+        return unless File.exist?(Rails.root.join("config/importmap.rb"))
+
+        append_to_file "config/importmap.rb", <<~RUBY
+
+          # Highlite
+          pin "highlite", to: "highlite/index.js"
+        RUBY
+      end
+
+      def show_readme
+        say ""
+        say "Highlite installed successfully!", :green
+        say ""
+        say "Usage in any view:"
+        say '  <%= highlite_viewer(url: url_for(@document.file), document_id: @document.id) %>'
+        say ""
+      end
+    end
+  end
+end

data/lib/generators/highlite/install/templates/_right_sidebar.html.erb.tt

@@ -0,0 +1,16 @@
+<%# Custom right sidebar for Highlite %>
+<%# This partial receives: url, document_id, and options %>
+<%# Customize below to fit your application's needs %>
+
+<div data-controller="highlite--highlights-panel"
+     data-highlite--highlights-panel-document-id-value="<%%= document_id %>"
+     class="h-full flex flex-col">
+  <div class="p-3 border-b border-gray-200">
+    <h3 class="text-sm font-semibold text-gray-700">Highlights</h3>
+  </div>
+
+  <div data-highlite--highlights-panel-target="list"
+       class="flex-1 overflow-y-auto p-3 space-y-2">
+    <%# Highlights will be rendered here by the controller %>
+  </div>
+</div>

data/lib/generators/highlite/install/templates/initializer.rb.tt

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+Highlite.configure do |config|
+  # PDF.js version (served from jsDelivr CDN)
+  # config.pdf_js_version = "5.4.624"
+
+  # Default highlight colors (rgba strings)
+  # config.default_colors = [
+  #   "rgba(255, 226, 143, 0.5)", # yellow
+  #   "rgba(166, 227, 161, 0.5)", # green
+  #   "rgba(137, 180, 250, 0.5)", # blue
+  #   "rgba(245, 194, 231, 0.5)"  # pink
+  # ]
+
+  # Enabled toolbar tools (:text for text selection, :area for rectangle drawing)
+  # config.toolbar_tools = [:text, :area]
+
+  # Override the right sidebar partial (set to a partial path string)
+  # config.right_sidebar_partial = "my_app/custom_sidebar"
+end

data/lib/highlite/configuration.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Highlite
+  class Configuration
+    attr_accessor :pdf_js_version, :default_colors, :toolbar_tools, :right_sidebar_partial
+
+    def initialize
+      @pdf_js_version = "5.4.624"
+      @default_colors = [
+        "rgba(255, 226, 143, 0.5)", # yellow
+        "rgba(166, 227, 161, 0.5)", # green
+        "rgba(137, 180, 250, 0.5)", # blue
+        "rgba(245, 194, 231, 0.5)"  # pink
+      ]
+      @toolbar_tools = %i[text area]
+      @right_sidebar_partial = nil
+    end
+
+    def self.instance
+      @instance ||= new
+    end
+
+    def self.reset!
+      @instance = new
+    end
+  end
+end