pocketbook 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 37b9f2a71ec28291568640b6d39517ceea652a88bd482ab777031cd37ad454f1
+  data.tar.gz: abf41efcbdb373f4cef42f1d412688fd8fe2f8b8d2a3648ae7791135ad12b152
+SHA512:
+  metadata.gz: 8a2e3236ae901546cc3ba5d78fae971ad157eca451347f1281a7266fd94ae9feb05bd020cdc3f08b3c36cdc8e6c4d58dd3f883af7b1a95f38b34b753e360fcbf
+  data.tar.gz: 5bbc0dd0f9f9005db089d0da98f73ec55e1b2bcb1c73eff8345d8a3d55db63afb3d3029346b064a36aeb7ae8264b744bad77ab30dd9048220a730f6cb12c9e62

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pocketbook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,308 @@
+<div align="center">
+  <img src="pocketbook.png" alt="Pocketbook Logo" width="200">
+</div>
+
+# Pocketbook
+
+Turn markdown into easily shareable, print-ready PDFs.
+
+Pocketbook is an alpha Ruby project for generating book-style PDFs from markdown using a theme template and print CSS. It is built for:
+
+- authors and self-publishers who write in markdown
+- developers who need repeatable markdown-to-PDF output
+- designers and publishers who want layout control via reusable themes
+
+## Why Pocketbook
+
+- **Markdown-first**: Keep content in plain markdown files. Use one file or many.
+- **Print-first**: Render with CSS `@page`, named pages, running elements, and mirrored margins.
+- **Theme-driven**: Package template and style variants together for consistent output.
+- **Shareable output**: Produce a polished PDF that is easy to distribute.
+- **Testable rendering**: Validate layout stability with fixture-driven visual regression tests.
+
+## Start In 60 Seconds
+
+### 1. Install the gem
+
+```bash
+gem install pocketbook
+```
+
+### 2. Generate your first PDF
+
+```bash
+pocketbook build \
+  examples/sample.md \
+  --theme classic \
+  --style light \
+  --size A4 \
+  --output output/book-a4.pdf
+```
+
+For a plain document without cover, TOC, or back cover sections, use the basic theme:
+
+```bash
+pocketbook build \
+  examples/sample.md \
+  --theme themes/basic \
+  --style plain \
+  --size A4 \
+  --output output/document-a4.pdf
+```
+
+`classic` is the default bundled theme. Use `--theme themes/basic` when you want a plain content-only layout.
+
+When `--theme` receives a bare name such as `classic`, Pocketbook first looks for a bundled theme with that name. If none exists, it falls back to resolving the value from the current working directory. Any explicit path such as `themes/classic`, `./my-theme`, or `/abs/path/to/theme.yml` is resolved directly as a path.
+
+### 4. Open the result
+
+Your PDF is ready at `output/book-a4.pdf`.
+
+To automatically open the generated PDF in your default viewer:
+
+```bash
+pocketbook build examples/sample.md --open
+```
+
+## Live Rebuild While Editing
+
+Use the dedicated `watch` command to rebuild the PDF when relevant files change.
+
+```bash
+pocketbook watch \
+  examples/sample.md \
+  --theme themes/classic \
+  --style light \
+  --size A4 \
+  --output output/book-a4.pdf
+```
+
+By default, changes are debounced by 350ms. You can tune it:
+
+```bash
+pocketbook watch \
+  examples/sample.md \
+  --theme themes/classic \
+  --output output/book-a4.pdf \
+  --debounce-ms 500
+```
+
+After each successful rebuild, Pocketbook prints:
+
+- a `file://...` PDF link
+- an `xdg-open "..."` command you can run directly
+
+## What The Generated PDF Includes
+
+- cover page
+- generated table of contents
+- body pages with mirrored margins
+- running header, footer, and page marker
+- backcover page
+
+## Build From Multiple Markdown Files
+
+Pass files positionally to concatenate them in order:
+
+```bash
+pocketbook build \
+  chapters/01-intro.md \
+  chapters/02-method.md \
+  chapters/03-results.md \
+  --theme themes/classic \
+  --style light \
+  --size A4 \
+  --output output/book-multi-input.pdf
+```
+
+## Requirements
+
+Runtime requirements:
+
+- Ruby 3.x
+- local Chrome or Chromium (used by `ferrum`)
+
+Development/test-only dependencies:
+
+- ImageMagick (`compare`) for visual diff metric checks in `bin/test-render`
+- Poppler tools (`pdftoppm`, `pdfinfo`, `pdftotext`) for page rasterization and text/page-count assertions
+
+Example package names:
+
+- Debian/Ubuntu: `imagemagick poppler-utils chromium`
+- macOS (Homebrew): `imagemagick poppler`
+
+## Theme Workflow (Progressive)
+
+Pocketbook supports progressive themeing. Start simple, then add structure only if needed.
+
+### Level 0: no custom theme files
+
+Use the bundled default theme:
+
+```bash
+pocketbook build book.md --output output/book.pdf
+```
+
+### Level 1: CSS-only theme (recommended first step)
+
+Create a folder with `theme.css`:
+
+```txt
+themes/
+  clean/
+    theme.css
+```
+
+Then build with it:
+
+```bash
+pocketbook build book.md --theme themes/clean --output output/book.pdf
+```
+
+### Level 2: Optional custom template
+
+Add `template.html.erb` (or `layout.html.erb`) to the theme directory:
+
+```txt
+themes/
+  clean/
+    theme.css
+    template.html.erb
+```
+
+### Optional metadata manifest (`theme.yml`)
+
+`theme.yml` is optional. Use it only when you need explicit style maps, template path overrides, or defaults.
+
+Supported top-level keys:
+
+- `name`
+- `version`
+- `template`
+- `styles`
+- `defaults`
+
+Supported `defaults` keys:
+
+- `style`
+- `title`
+- `subtitle`
+- `author`
+- `publisher`
+- `backcover_text`
+- `size`
+
+Example `theme.yml`:
+
+```yaml
+name: classic
+version: 0.2.0
+template: template.html.erb
+styles:
+  light:
+    - styles/base.css
+    - styles/light.css
+  dark:
+    - styles/base.css
+    - styles/dark.css
+defaults:
+  style: light
+  publisher: Pocketbook Labs
+```
+
+Style selection precedence:
+
+1. `--style` CLI flag
+2. `defaults.style` in `theme.yml` (if manifest exists)
+3. `default` style when discoverable (for example `theme.css`)
+4. first discovered style
+
+## Front Matter
+
+The first markdown input file can include YAML front matter.
+
+Supported keys:
+
+- `title`
+- `subtitle`
+- `author`
+- `publisher`
+- `backcover_text`
+- `size`
+
+Metadata precedence:
+
+1. CLI flags
+2. markdown front matter
+3. theme defaults
+4. renderer defaults
+
+## Visual Regression Tests
+
+Pocketbook ships with fixture-driven visual regression tests using `minitest`.
+
+```bash
+# Check current output against expected fixtures
+bin/test-render check
+
+# Rebuild expected fixtures from current renderer output
+bin/test-render update
+
+# Print configured fixture case IDs
+bin/test-render list
+```
+
+Fixture layout:
+
+- `test/fixtures/inputs/`: markdown fixtures
+- `test/fixtures/expected/<case-id>/pages/`: expected PNG pages
+- `test/fixtures/cases.yml`: case manifest
+
+## CLI
+
+```text
+Usage: pocketbook build FILE.md [MORE.md ...] [options]
+
+Main commands:
+  build                             Build a PDF (default command)
+  watch                             Rebuild PDF on file changes
+  theme new NAME                    Scaffold a new theme directory
+  theme validate [THEME]            Validate that a theme resolves correctly
+  theme inspect [THEME]             Print resolved theme details
+  theme get URL                     Download a theme from a GitHub theme.yml URL
+```
+
+Theme command examples:
+
+```bash
+# Themes are stored globally by default in ~/.pocketbook/themes
+pocketbook theme new clean
+pocketbook theme new clean --with-template
+pocketbook theme validate clean
+pocketbook theme inspect classic --style dark
+pocketbook theme get https://github.com/org/repo/blob/main/themes/minimal/theme.yml
+```
+
+Build diagnostics example:
+
+```bash
+pocketbook build examples/sample.md --diagnostics --open
+```
+
+## Contributing
+
+Contributions are welcome.
+
+Start with [CONTRIBUTING.md](CONTRIBUTING.md) for setup, validation commands, and pull request expectations.
+
+Quick path:
+
+1. Fork the repo and create a feature branch.
+2. Run `bundle install`.
+3. Make your changes and run `bin/test-render check`.
+4. Open a pull request with a short summary and rationale.
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE).

data/bin/pocketbook

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+require "pocketbook"
+Pocketbook::CLI.run(ARGV)

data/bin/test-render

@@ -0,0 +1,49 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "yaml"
+
+ROOT = File.expand_path("..", __dir__)
+FIXTURE_CASES = File.join(ROOT, "test", "fixtures", "cases.yml")
+
+def usage
+  <<~TEXT
+    Usage: bin/test-render [check|update|list]
+
+      check   Run fixture-driven visual regression tests (default)
+      update  Rebuild expected PNG fixtures from current renderer output
+      list    Print configured fixture case IDs
+  TEXT
+end
+
+def list_cases
+  data = YAML.safe_load(File.read(FIXTURE_CASES), aliases: true) || {}
+  cases = data.fetch("cases", [])
+  abort("No fixture cases configured in #{FIXTURE_CASES}") if cases.empty?
+
+  cases.each { |entry| puts entry.fetch("id") }
+end
+
+command = ARGV[0] || "check"
+
+Dir.chdir(ROOT)
+
+case command
+when "check"
+  env = {}
+when "update"
+  env = { "POCKETBOOK_UPDATE_FIXTURES" => "1" }
+when "list"
+  list_cases
+  exit(0)
+when "-h", "--help", "help"
+  puts usage
+  exit(0)
+else
+  warn "Unknown command: #{command}"
+  warn usage
+  exit(1)
+end
+
+success = system(env, "bundle", "exec", "ruby", "-Itest", "test/visual_regression_test.rb")
+exit(success ? 0 : 1)

data/lib/pocketbook/book.rb

@@ -0,0 +1,28 @@
+module Pocketbook
+  class Book
+    attr_reader :inputs, :theme, :metadata
+
+    def initialize(inputs:, theme:, metadata: {})
+      @inputs = inputs
+      @theme = theme
+      @metadata = metadata
+    end
+
+    def render_to(output_path)
+      BookRenderer.new(
+        inputs: @inputs,
+        theme: @theme,
+        output_path: output_path,
+        metadata: @metadata
+      ).render
+    end
+
+    def render_html
+      BookRenderer.new(
+        inputs: @inputs,
+        theme: @theme,
+        metadata: @metadata
+      ).render_html
+    end
+  end
+end

data/lib/pocketbook/book_renderer/chapter.rb

@@ -0,0 +1,85 @@
+require "cgi"
+require "kramdown"
+
+module Pocketbook
+  class BookRenderer
+    class Chapter
+      TocHeading = Struct.new(:id, :title, :level, keyword_init: true)
+
+      Compiled = Struct.new(:id, :source, :title, :html, :toc_headings, keyword_init: true) do
+        def article_html(escape_html:)
+          <<~HTML
+            <article class="chapter" id="#{escape_html.call(id)}" data-source="#{escape_html.call(source)}" data-title="#{escape_html.call(title)}">
+              <p class="running-chapter-title" aria-hidden="true">#{escape_html.call(title)}</p>
+              #{html}
+            </article>
+          HTML
+        end
+      end
+
+      def initialize(front_matter: FrontMatter.new)
+        @front_matter = front_matter
+      end
+
+      def compile(inputs:)
+        front_matter = {}
+
+        chapters = inputs.map.with_index do |path, index|
+          raw = File.read(path)
+
+          if index.zero?
+            front_matter, raw = @front_matter.extract(raw)
+          end
+
+          title = detect_title(raw, path)
+          chapter_html = Kramdown::Document.new(raw, input: "GFM").to_html
+
+          Compiled.new(
+            id: chapter_id(title, index),
+            source: path,
+            title: title,
+            html: chapter_html,
+            toc_headings: extract_toc_headings(chapter_html)
+          )
+        end
+
+        [chapters, front_matter]
+      end
+
+      private
+
+      def chapter_id(title, index)
+        slug = title.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/\A-+|-+\z/, "")
+        slug = "chapter" if slug.empty?
+
+        "chapter-#{index + 1}-#{slug}"
+      end
+
+      def detect_title(markdown, path)
+        markdown.each_line do |line|
+          if (match = line.match(/\A#\s+(.+)\s*$/))
+            return match[1].strip
+          end
+        end
+
+        File.basename(path, File.extname(path)).tr("_", " ")
+      end
+
+      def extract_toc_headings(chapter_html)
+        chapter_html.scan(/<h([1-3])([^>]*)>(.*?)<\/h\1>/mi).filter_map do |level, attributes, inner_html|
+          id_match = attributes.match(/\bid=(['"])(.*?)\1/i)
+          next if id_match.nil?
+
+          text = CGI.unescapeHTML(inner_html.gsub(/<[^>]+>/, " ").gsub(/\s+/, " ").strip)
+          next if text.empty?
+
+          TocHeading.new(
+            id: id_match[2],
+            title: text,
+            level: level.to_i
+          )
+        end
+      end
+    end
+  end
+end

data/lib/pocketbook/book_renderer/front_matter.rb

@@ -0,0 +1,27 @@
+require "yaml"
+
+module Pocketbook
+  class BookRenderer
+    class FrontMatter
+      def extract(markdown)
+        match = markdown.match(/\A---\s*\n(.*?)\n---\s*\n/m)
+        return [{}, markdown] unless match
+
+        data = YAML.safe_load(match[1], aliases: true)
+        data = {} unless data.is_a?(Hash)
+
+        [symbolize_keys(data), markdown[match[0].length..]]
+      rescue Psych::SyntaxError
+        [{}, markdown]
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.each_with_object({}) do |(key, value), output|
+          output[key.to_sym] = value
+        end
+      end
+    end
+  end
+end

data/lib/pocketbook/book_renderer/metadata.rb

@@ -0,0 +1,70 @@
+module Pocketbook
+  class BookRenderer
+    class Metadata
+      DEFAULT_VALUES = {
+        title: "Untitled Book",
+        subtitle: "",
+        author: "Unknown Author",
+        publisher: "Pocketbook",
+        backcover_text: "",
+        size: "6in 9in"
+      }.freeze
+
+      METADATA_KEYS = %i[title subtitle author publisher backcover_text size].freeze
+
+      def resolve(theme_defaults:, cli_metadata:, front_matter:, first_input_path:)
+        metadata = DEFAULT_VALUES
+          .merge(theme_defaults)
+          .merge(cli_metadata)
+
+        metadata[:size] = normalize_size(metadata[:size])
+        apply_front_matter!(metadata, front_matter, cli_metadata)
+        apply_input_fallbacks!(metadata, first_input_path)
+
+        metadata
+      end
+
+      private
+
+      def apply_front_matter!(metadata, front_matter, cli_metadata)
+        return if front_matter.empty?
+
+        METADATA_KEYS.each do |key|
+          next unless front_matter.key?(key)
+          next if blank?(front_matter[key])
+          next if cli_metadata.key?(key) && !blank?(cli_metadata[key])
+
+          metadata[key] = front_matter[key].to_s
+        end
+      end
+
+      def apply_input_fallbacks!(metadata, first_input_path)
+        first_input_name = File.basename(first_input_path, File.extname(first_input_path)).tr("_", " ")
+
+        if metadata[:title] == DEFAULT_VALUES[:title]
+          metadata[:title] = first_input_name.split.map(&:capitalize).join(" ")
+        end
+
+        if blank?(metadata[:backcover_text])
+          metadata[:backcover_text] = "A pocketbook generated from markdown."
+        end
+
+        metadata[:size] = normalize_size(metadata[:size])
+      end
+
+      def normalize_size(value)
+        raw = value.to_s.strip
+        return DEFAULT_VALUES[:size] if raw.empty?
+
+        match = raw.match(/\A(\d+(?:\.\d+)?(?:in|mm|cm|pt|pc|px))\s*[xX]\s*(\d+(?:\.\d+)?(?:in|mm|cm|pt|pc|px))\z/)
+        return "#{match[1]} #{match[2]}" if match
+
+        raw
+      end
+
+      def blank?(value)
+        value.nil? || value.to_s.strip.empty?
+      end
+    end
+  end
+end

data/lib/pocketbook/book_renderer/pdf.rb

@@ -0,0 +1,42 @@
+require "tmpdir"
+require "ferrum"
+require_relative "../pdf_document"
+
+module Pocketbook
+  class BookRenderer
+    class Pdf
+      def write(html:, output_path:)
+        Dir.mktmpdir("pocketbook") do |dir|
+          html_path = File.join(dir, "book.html")
+          File.write(html_path, html)
+
+          browser = Ferrum::Browser.new(timeout: 30)
+          page = browser.create_page
+          page.go_to("file://#{html_path}")
+          page.network.wait_for_idle
+          page.pdf(
+            path: output_path,
+            print_background: true,
+            prefer_css_page_size: true
+          )
+        ensure
+          browser&.quit
+        end
+      end
+
+      def toc_page_numbers(pdf_path:, toc_targets:)
+        return {} if toc_targets.empty?
+
+        pdf_document_for(pdf_path).toc_page_numbers(toc_targets)
+      rescue StandardError
+        {}
+      end
+
+      private
+
+      def pdf_document_for(pdf_path)
+        Pocketbook::PdfDocument.open(pdf_path)
+      end
+    end
+  end
+end

data/lib/pocketbook/book_renderer/toc.rb

@@ -0,0 +1,55 @@
+module Pocketbook
+  class BookRenderer
+    class Toc
+      def build(chapters:, escape_html:, page_numbers: {})
+        toc_entries(chapters).map do |entry|
+          toc_item_html(
+            id: entry[:id],
+            title: entry[:title],
+            level: entry[:level],
+            page_number: page_numbers[entry[:id]],
+            escape_html: escape_html
+          )
+        end.join("\n")
+      end
+
+      def targets(chapters:)
+        toc_entries(chapters).map { |entry| entry[:id] }
+      end
+
+      private
+
+      def toc_entries(chapters)
+        entries = []
+
+        chapters.each do |chapter|
+          headings = chapter.toc_headings || []
+          if headings.empty?
+            entries << { id: chapter.id, title: chapter.title, level: 1 }
+            next
+          end
+
+          headings.each do |heading|
+            entries << { id: heading.id, title: heading.title, level: heading.level }
+          end
+        end
+
+        entries
+      end
+
+      def toc_item_html(id:, title:, level:, page_number:, escape_html:)
+        page_label = page_number.nil? ? "" : escape_html.call(page_number)
+
+        <<~HTML
+          <li class="toc-item toc-item-level-#{level}">
+            <a class="toc-link" href="##{escape_html.call(id)}">
+              <span class="toc-title">#{escape_html.call(title)}</span>
+              <span class="toc-fill" aria-hidden="true"></span>
+              <span class="toc-page" aria-label="Page">#{page_label}</span>
+            </a>
+          </li>
+        HTML
+      end
+    end
+  end
+end