sakusei 0.4.0 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 51994014be2b8900d793d1954389a52a2726b54703cd60673886f7b85cfbeaa2
-  data.tar.gz: d650c71e17c76b74f770dd32cc83b45848cacd0b1f7a8f49c3d4eb98185fee50
+  metadata.gz: 1845947d6ebe2f9b6c5732093eff5bbd90aa7bc2a60ad79a568033bd8c674e57
+  data.tar.gz: 595a6804e797c8b0c58804b7df122b5a738e5592b786f4a0c29454801c864ed9
 SHA512:
-  metadata.gz: 0c8a398207d15178355e2da253dd4e3d20e9e524a044125214e7c074f264892a5ae9749b2773cf42c4de353532d731a8798d52eb922da38f6d0e5e5185940f8c
-  data.tar.gz: 0b8970fdb542f9fe5f2b81bda13019be3893501735c62962f7a66e60c2acc8f38672ccf74fc4df08ece6b149796d84da52a4207b1ccde31793d079856c426ce7
+  metadata.gz: 0c2d9f30c83d0f1de7c73f8c23dcfe590208c057e95cfae0a261a64a36f7a386f3e0e34d9ba1849b46407ce4e19bd86e6dc3544db861fa8ab2f92cf0ac868d6d
+  data.tar.gz: 29428e2b7e9dbbe86753c58a537b6596f55a7ff7c075efe9bf40c1b0a2ada7d6f9921273400cc8226cf5acb12613a8caffed8ce9efc55576fe9a7d9b7790ca71

data/.claude/settings.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "defaultMode": "auto",
+    "allow": [
+      "Bash(git *)"
+    ]
+  }
+}

data/CLAUDE.md

@@ -0,0 +1,86 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+Run all tests:
+
+```bash
+bundle exec rake test
+```
+
+Run a single test file:
+
+```bash
+ruby -Ilib -Itest test/sakusei/test_builder_break_syntax.rb
+```
+
+Build and install the gem locally:
+
+```bash
+rake install
+```
+
+Build a PDF from one of the examples:
+
+```bash
+bundle exec sakusei build examples/getting-started.md
+```
+
+Live-preview a markdown file in the browser:
+
+```bash
+bundle exec sakusei-preview examples/getting-started.md
+```
+
+## Architecture
+
+Sakusei ships two CLIs:
+
+- `bin/sakusei` (Thor) — the build CLI that produces PDFs.
+- `bin/sakusei-preview` — a separate live-render binary backed by `Sakusei::PreviewServer`. Watches the source file, its `@include` partials, the active style pack, and referenced images; re-renders to HTML on change via `npx md-to-pdf --as-html` and reloads the browser tab. Loads paged.js from a CDN so `@page`/`page-break-*` rules are visible as document pages. Use this for fast iteration; use `sakusei build` for the final PDF.
+
+Both CLIs share the multi-stage build pipeline.
+
+### Build pipeline
+
+`Builder#build` in `lib/sakusei/builder.rb` runs these steps in order:
+
+1. **StylePack.discover** — walks up the directory tree from the source file, looking for `.sakusei/style_packs/<name>/` at each level. Falls back to the built-in pack at `lib/templates/default_style_pack/`.
+2. **FileResolver** — resolves `<!-- @include ./file.md -->` directives and concatenates the content.
+3. **ErbProcessor** — evaluates ERB in the markdown. Available helpers: `today(format)`, `env(name, default)`, `sh(command)`, `include_file(path)`, `image_path(relative_path)`, `document_headings(path)`.
+4. **expand_break_syntax** — expands `::break::` shorthand to `<div class="page-break"></div>`.
+5. **VueProcessor** — finds `<vue-component name="Foo" prop="value" />` tags, renders them server-side via `lib/sakusei/vue_renderer.js` using Node.js + `@vue/server-renderer` in a single batched call.
+6. **HeadingWrapper** — wraps h2/h3 headings with their immediately following content block in keep-together divs to prevent orphaned headings.
+7. **MdToPdfConverter** / **HtmlConverter** — both extend `ConverterBase` (`lib/sakusei/converter_base.rb`) and assemble the `npx md-to-pdf` command with config, stylesheets, and header/footer from the style pack. `MdToPdfConverter` runs it in a temp dir and returns the PDF path; `HtmlConverter` adds `--as-html` and returns the HTML string (used by the live preview server).
+
+`Builder#build_html` runs stages 1–6 and ends in `HtmlConverter`, sharing the pipeline with `Builder#build` so the preview matches the final PDF.
+
+`MultiFileBuilder` handles glob patterns and multiple source files, delegating to `Builder` per file and concatenating results.
+
+### Style packs
+
+A style pack is a directory containing:
+
+- `config.js` — md-to-pdf configuration (Puppeteer/Chrome options)
+- `style.css` — stylesheet applied after `lib/templates/base.css`
+- `header.html`, `footer.html` — Puppeteer page chrome injected before the markdown content
+- `components/*.vue` — Vue 3 SFCs, rendered server-side at build time (optional)
+- `package.json` — if present, npm dependencies are auto-installed on first use
+
+`lib/templates/base.css` is always applied first and provides keep-together rules for tables, code blocks, blockquotes, images, and common custom classes.
+
+Style pack discovery walks up the directory tree from the source file; a named pack can live in any ancestor's `.sakusei/` directory. The default pack in `lib/templates/default_style_pack/` is the final fallback.
+
+### Vue component system
+
+Components are referenced in markdown as `<vue-component name="MyComponent" prop="value" />`. `VueProcessor` finds all such tags in a first pass, replaces them with numbered placeholders, then sends a single JSON batch to `vue_renderer.js` via stdin. The JS renderer uses `@vue/server-renderer` to render each component and returns HTML + scoped CSS back as JSON. Scoped CSS is injected as a `<style>` block at the top of the document.
+
+Component resolution order: local `./components/<Name>.vue` → style pack `components/<Name>.vue`.
+
+Vue components support named slots via `<template #slotname>...</template>` inside the tag. Slot content is converted from Markdown to HTML before being passed to the renderer.
+
+### Tests
+
+Tests use Minitest. Fixtures live in `test/fixtures/` (markdown samples and stub style packs). `test/test_vue_renderer.js` is a standalone Node.js test for the JS renderer. The base test class `Sakusei::TestCase` provides `fixtures_dir` and a `temp_dir` that auto-cleans on teardown.

data/Gemfile.lock

@@ -0,0 +1,82 @@
+PATH
+  remote: .
+  specs:
+    sakusei (0.5.8)
+      erb (~> 4.0)
+      listen (~> 3.8)
+      thor (~> 1.2)
+      webrick (~> 1.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.9)
+      public_suffix (>= 2.0.2, < 8.0)
+    ast (2.4.3)
+    bigdecimal (4.0.1)
+    cgi (0.5.1)
+    erb (4.0.3)
+      cgi (>= 0.3.3)
+    ffi (1.17.4)
+    ffi (1.17.4-arm64-darwin)
+    json (2.19.2)
+    json-schema (6.2.0)
+      addressable (~> 2.8)
+      bigdecimal (>= 3.1, < 5)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    listen (3.10.0)
+      logger
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    logger (1.7.0)
+    mcp (0.9.0)
+      json-schema (>= 4.1)
+    minitest (5.27.0)
+    parallel (1.27.0)
+    parser (3.3.10.2)
+      ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    public_suffix (7.0.5)
+    racc (1.8.1)
+    rainbow (3.1.1)
+    rake (13.3.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.11.1)
+      ffi (~> 1.0)
+    regexp_parser (2.11.3)
+    rubocop (1.85.1)
+      json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
+      mcp (~> 0.6)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    ruby-progressbar (1.13.0)
+    thor (1.5.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    webrick (1.9.2)
+
+PLATFORMS
+  arm64-darwin-24
+  ruby
+
+DEPENDENCIES
+  minitest (~> 5.0)
+  rake (~> 13.0)
+  rubocop (~> 1.0)
+  sakusei!
+
+BUNDLED WITH
+   2.7.2

data/bin/sakusei-preview

@@ -0,0 +1,40 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'optparse'
+require 'sakusei'
+require 'sakusei/preview_server'
+
+options = { open: true, paged: true }
+parser = OptionParser.new do |opts|
+  opts.banner = 'Usage: sakusei-preview FILE [options]'
+
+  opts.on('-p', '--port PORT', Integer, "Port to bind (default #{Sakusei::PreviewServer::DEFAULT_PORT})") { |v| options[:port] = v }
+  opts.on('-s', '--style PACK', 'Style pack name to use') { |v| options[:style] = v }
+  opts.on('-c', '--config FILE', 'Path to md-to-pdf config file') { |v| options[:config] = v }
+  opts.on('--stylesheet FILE', 'Path to CSS stylesheet') { |v| options[:stylesheet] = v }
+  opts.on('--no-open', 'Do not open the browser automatically') { options[:open] = false }
+  opts.on('--no-paged', 'Disable paged.js pagination (show as scrolling HTML)') { options[:paged] = false }
+  opts.on('-h', '--help', 'Show this help') { puts opts; exit 0 }
+end
+
+args = parser.parse(ARGV)
+if args.empty?
+  warn parser
+  exit 1
+end
+
+source_file = args.first
+unless File.exist?(source_file)
+  warn "File not found: #{source_file}"
+  exit 1
+end
+
+begin
+  Sakusei::PreviewServer.new(source_file, options).run
+rescue Interrupt
+  exit 0
+rescue Sakusei::Error => e
+  warn "[sakusei-preview] #{e.message}"
+  exit 1
+end

data/lib/sakusei/builder.rb

@@ -7,6 +7,7 @@ require_relative 'image_path_resolver'
 require_relative 'vue_processor'
 require_relative 'heading_wrapper'
 require_relative 'md_to_pdf_converter'
+require_relative 'html_converter'
 
 module Sakusei
   class Builder
@@ -14,48 +15,64 @@ module Sakusei
       @source_file = File.expand_path(source_file)
       @options = options
       @source_dir = File.dirname(@source_file)
+      @file_resolver = nil
+    end
+
+    attr_reader :source_file, :source_dir
+
+    # Files that contributed to the most recent build (source + @include partials).
+    # Populated after #build, #build_html, or #build_processed_content runs.
+    def resolved_input_files
+      files = [@source_file]
+      files.concat(@file_resolver.resolved_files.to_a) if @file_resolver
+      files.uniq
     end
 
     def build
-      # 1. Discover and load style pack
+      style_pack, processed_content = build_processed_content
+      $stderr.puts "[sakusei] converting to PDF..."
+      output_path = generate_output_path
+      convert_to_pdf(processed_content, output_path, style_pack)
+      $stderr.puts "[sakusei] written: #{output_path}"
+      output_path
+    end
+
+    # Run the full pipeline up to (but not including) PDF conversion, then
+    # render the processed markdown to a styled HTML string via md-to-pdf --as-html.
+    # Returns [html_string, style_pack].
+    def build_html
+      style_pack, processed_content = build_processed_content
+      html = HtmlConverter.new(processed_content, style_pack, @options.merge(source_dir: @source_dir)).convert
+      [html, style_pack]
+    end
+
+    private
+
+    def build_processed_content
       $stderr.puts "[sakusei] discovering style pack..."
       style_pack = discover_style_pack
       $stderr.puts "[sakusei] style pack: #{style_pack.name} (#{style_pack.path})"
 
-      # 2. Resolve and concatenate file references
       $stderr.puts "[sakusei] resolving file includes..."
       resolved_content = resolve_files
 
-      # 3. Process ERB templates
       $stderr.puts "[sakusei] processing ERB..."
       processed_content = process_erb(resolved_content)
 
-      # 3.5. Expand shorthand syntax (e.g. ::break:: → page-break div)
       processed_content = expand_break_syntax(processed_content)
-
-      # 4. Process Vue components (if available)
       processed_content = process_vue(processed_content, style_pack)
-
-      # 4.5 Wrap h2/h3 headings with their following block to prevent orphaned headings
       processed_content = wrap_headings(processed_content)
 
-      # 5. Convert to PDF
-      $stderr.puts "[sakusei] converting to PDF..."
-      output_path = generate_output_path
-      convert_to_pdf(processed_content, output_path, style_pack)
-
-      $stderr.puts "[sakusei] written: #{output_path}"
-      output_path
+      [style_pack, processed_content]
     end
 
-    private
-
     def discover_style_pack
       StylePack.discover(@options[:source_dir] || @source_dir, @options[:style])
     end
 
     def resolve_files
-      FileResolver.new(@source_file).resolve
+      @file_resolver = FileResolver.new(@source_file)
+      @file_resolver.resolve
     end
 
     def process_erb(content)

data/lib/sakusei/converter_base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module Sakusei
+  class ConverterBase
+    def initialize(content, style_pack, options = {})
+      @content    = content
+      @style_pack = style_pack
+      @options    = options
+      @source_dir = options[:source_dir]
+    end
+
+    protected
+
+    def copy_images(temp_dir)
+      return unless @source_dir
+
+      image_paths.each do |rel_path|
+        src = File.expand_path(rel_path, @source_dir)
+        next unless File.exist?(src)
+
+        dest = File.join(temp_dir, rel_path)
+        FileUtils.mkdir_p(File.dirname(dest))
+        FileUtils.cp(src, dest)
+      end
+    end
+
+    def image_paths
+      paths = []
+      @content.scan(/!\[[^\]]*\]\(([^)]+)\)/) { |m| paths << m[0].strip }
+      @content.scan(/src="([^"]+)"/) { |m| paths << m[0].strip }
+      paths.reject { |p| p.match?(/\A(https?:|data:|\/\/)/) || p.start_with?('/') }
+           .uniq
+    end
+
+    def page_chrome_prefix
+      return '' unless @style_pack
+      %i[header footer].map do |part|
+        path = @style_pack.public_send(part)
+        path ? File.read(path) + "\n" : ''
+      end.join
+    end
+
+    def build_command(temp_md, temp_dir, extra_flags = [])
+      cmd = ['npx', 'md-to-pdf']
+
+      config = @options[:config] || @style_pack&.config
+      cmd << '--config-file' << config if config
+
+      stylesheets = [StylePack.base_stylesheet]
+      pack_stylesheet = @options[:stylesheet] || @style_pack&.stylesheet
+      stylesheets << pack_stylesheet if pack_stylesheet
+      stylesheets.each { |s| cmd << '--stylesheet' << s }
+
+      cmd << '--basedir' << temp_dir
+      extra_flags.each { |f| cmd << f }
+      cmd << temp_md
+      cmd
+    end
+  end
+end

data/lib/sakusei/file_resolver.rb

@@ -5,6 +5,8 @@ module Sakusei
   class FileResolver
     INCLUDE_PATTERN = /<!--\s*@include\s+(\S+)\s*-->/
 
+    attr_reader :resolved_files
+
     def initialize(source_file)
       @source_file = source_file
       @source_dir = File.dirname(source_file)

data/lib/sakusei/html_converter.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'open3'
+require 'tmpdir'
+require_relative 'converter_base'
+
+module Sakusei
+  # Converts markdown content to a styled HTML string by invoking
+  # `npx md-to-pdf --as-html`. Used by the live preview server.
+  class HtmlConverter < ConverterBase
+    def convert
+      Dir.mktmpdir('sakusei-html') do |temp_dir|
+        temp_md = File.join(temp_dir, 'input.md')
+        # Header/footer files are injected as @page margin chrome by PreviewServer.
+        # Don't prepend them to the body the way MdToPdfConverter does for PDF output.
+        File.write(temp_md, @content)
+
+        copy_images(temp_dir)
+
+        cmd = build_command(temp_md, temp_dir, ['--as-html'])
+        stdout, stderr, status = Open3.capture3(*cmd)
+
+        unless status.success?
+          raise Error, "HTML conversion failed: #{stderr.strip}\n#{stdout.strip}"
+        end
+
+        html_path = File.join(temp_dir, 'input.html')
+        raise Error, "md-to-pdf did not produce HTML at #{html_path}" unless File.exist?(html_path)
+
+        File.read(html_path)
+      end
+    end
+  end
+end

data/lib/sakusei/md_to_pdf_converter.rb

@@ -2,16 +2,14 @@
 
 require 'fileutils'
 require 'tmpdir'
+require_relative 'converter_base'
 
 module Sakusei
   # Converts markdown content to PDF using md-to-pdf
-  class MdToPdfConverter
+  class MdToPdfConverter < ConverterBase
     def initialize(content, output_path, style_pack, options = {})
-      @content    = content
+      super(content, style_pack, options)
       @output_path = output_path
-      @style_pack = style_pack
-      @options    = options
-      @source_dir = options[:source_dir]
     end
 
     def convert
@@ -24,7 +22,7 @@ module Sakusei
         # so md-to-pdf's HTTP server can serve them by their relative paths.
         copy_images(temp_dir)
 
-        cmd = build_command(temp_md, temp_dir)
+        cmd = build_command(temp_md, temp_dir).join(' ')
         result = system(cmd)
         raise Error, 'PDF conversion failed' unless result
 
@@ -33,65 +31,5 @@ module Sakusei
 
       @output_path
     end
-
-    private
-
-    # Scans content for relative image paths (markdown and HTML img src),
-    # and copies each referenced file into temp_dir at the same relative path.
-    def copy_images(temp_dir)
-      return unless @source_dir
-
-      image_paths.each do |rel_path|
-        src = File.expand_path(rel_path, @source_dir)
-        next unless File.exist?(src)
-
-        dest = File.join(temp_dir, rel_path)
-        FileUtils.mkdir_p(File.dirname(dest))
-        FileUtils.cp(src, dest)
-      end
-    end
-
-    # Extracts relative image paths from both markdown syntax and HTML img tags.
-    def image_paths
-      paths = []
-
-      # Markdown: ![alt](path)
-      @content.scan(/!\[[^\]]*\]\(([^)]+)\)/) { |m| paths << m[0].strip }
-
-      # HTML: src="path" (covers Vue-rendered img tags)
-      @content.scan(/src="([^"]+)"/) { |m| paths << m[0].strip }
-
-      # Filter to relative paths only (skip http, https, data URIs, absolute paths)
-      paths.reject { |p| p.match?(/\A(https?:|data:|\/\/)/) || p.start_with?('/') }
-           .uniq
-    end
-
-    def page_chrome_prefix
-      return '' unless @style_pack
-      %i[header footer].map do |part|
-        path = @style_pack.public_send(part)
-        path ? File.read(path) + "\n" : ''
-      end.join
-    end
-
-    def build_command(temp_path, temp_dir)
-      cmd = ['npx', 'md-to-pdf']
-
-      config = @options[:config] || @style_pack.config
-      cmd << '--config-file' << config if config
-
-      stylesheets = [StylePack.base_stylesheet]
-      pack_stylesheet = @options[:stylesheet] || @style_pack.stylesheet
-      stylesheets << pack_stylesheet if pack_stylesheet
-      stylesheets.each { |s| cmd << '--stylesheet' << s }
-
-      # Set basedir to temp_dir so relativePath resolves to /input.md,
-      # making image src="images/foo.jpg" resolve to http://localhost:PORT/images/foo.jpg
-      # which is served from temp_dir where we've copied the assets.
-      cmd << '--basedir' << temp_dir
-
-      cmd << temp_path
-      cmd.join(' ')
-    end
   end
 end

data/lib/sakusei/page_chrome_translator.rb

@@ -0,0 +1,268 @@
+# frozen_string_literal: true
+
+require 'date'
+require 'json'
+require 'open3'
+
+module Sakusei
+  # Builds the live-preview's page chrome from the style pack's PDF
+  # configuration, matching what Puppeteer renders for the PDF as closely as
+  # possible.
+  #
+  # Source of truth is `pdf_options.headerTemplate` / `footerTemplate` /
+  # `format` / `margin` inside `config.js`. We evaluate `config.js` with Node
+  # to expand JS template literals (e.g. `${wordmarkDataUri}`), then translate
+  # the resulting HTML strings into running elements + @page CSS.
+  #
+  # Strategy: Puppeteer's headerTemplate / footerTemplate are arbitrary HTML
+  # (with images, flex layouts, multi-column structures). CSS @page margin
+  # boxes only accept a content string, not arbitrary HTML — so we use
+  # CSS Paged Media's running-element mechanism instead:
+  #
+  #   .sakusei-running-header { position: running(sk_header); }
+  #   @page { @top-center { content: element(sk_header); } }
+  #
+  # Placeholder rewrites (matching Puppeteer's chrome semantics):
+  # - <span class="pageNumber"></span> → <span class="sk-pn"></span>, with
+  #   .sk-pn::after { content: counter(page); }
+  # - <span class="totalPages"></span> → <span class="sk-tp"></span>, similar
+  # - <span class="title"></span> → "" (Puppeteer leaves it blank by default)
+  # - <span class="date"></span> → today's date (static at build time)
+  # - <span class="url"></span> → ""
+  # - <img src="rel/path"> → <img src="/__pack/rel/path"> so the browser can
+  #   fetch images from the style-pack directory. Data URIs and absolute
+  #   URLs pass through unchanged.
+  #
+  # Returns { css:, html: } — caller injects css into <head>, prepends html
+  # into <body>.
+  class PageChromeTranslator
+    HEADER_RUNNING_NAME = 'sk_header'
+    FOOTER_RUNNING_NAME = 'sk_footer'
+    HEADER_CLASS        = 'sakusei-running-header'
+    FOOTER_CLASS        = 'sakusei-running-footer'
+    PAGE_NUMBER_CLASS   = 'sk-pn'
+    TOTAL_PAGES_CLASS   = 'sk-tp'
+
+    NODE_EXTRACT_SCRIPT = <<~JS.freeze
+      try {
+        const c = require(process.argv[1]);
+        const o = (c && c.pdf_options) || {};
+        const enabled = o.displayHeaderFooter !== false;
+        process.stdout.write(JSON.stringify({
+          format: o.format || null,
+          margin: o.margin || null,
+          headerTemplate: enabled ? (o.headerTemplate || null) : null,
+          footerTemplate: enabled ? (o.footerTemplate || null) : null
+        }));
+      } catch (e) {
+        process.stderr.write(String(e && e.stack || e));
+        process.exit(2);
+      }
+    JS
+
+    def initialize(style_pack)
+      @style_pack = style_pack
+    end
+
+    def build
+      return empty_result unless @style_pack
+      opts = read_pdf_options
+
+      # Extract chrome strip backgrounds from the templates BEFORE we strip them.
+      # Puppeteer's PDF chrome uses a `position: fixed; top: -10cm; bottom: -10cm`
+      # div that breaks out to fill the full chrome strip. paged.js's running
+      # elements live inside the @top-center / @bottom-center margin boxes which
+      # are constrained to the page's content width, so the same trick covers the
+      # whole page (wrong) instead of just the strip. We replicate the strip via
+      # .pagedjs_page::before / ::after pseudo-elements with the extracted color.
+      header_bg = extract_chrome_bg(opts[:header_template])
+      footer_bg = extract_chrome_bg(opts[:footer_template])
+
+      header_html = transform_template(opts[:header_template])
+      footer_html = transform_template(opts[:footer_template])
+
+      html = +''
+      html << wrap_running(:header, header_html) if header_html && !header_html.empty?
+      html << wrap_running(:footer, footer_html) if footer_html && !footer_html.empty?
+
+      { css: build_css(opts, header_html, footer_html, header_bg, footer_bg), html: html }
+    end
+
+    private
+
+    def empty_result
+      { css: '', html: '' }
+    end
+
+    def wrap_running(kind, inner)
+      class_name = kind == :header ? HEADER_CLASS : FOOTER_CLASS
+      tag = kind == :header ? 'header' : 'footer'
+      %(<#{tag} class="#{class_name}">#{inner}</#{tag}>)
+    end
+
+    def build_css(opts, header_html, footer_html, header_bg, footer_bg)
+      pieces = []
+
+      page_decls = []
+      page_decls << "size: #{opts[:size]};" if opts[:size]
+      page_decls << "margin: #{opts[:margin]};" if opts[:margin]
+      page_decls << "@top-center { content: element(#{HEADER_RUNNING_NAME}); }" if header_html && !header_html.empty?
+      page_decls << "@bottom-center { content: element(#{FOOTER_RUNNING_NAME}); }" if footer_html && !footer_html.empty?
+      pieces << "@page { #{page_decls.join(' ')} }" unless page_decls.empty?
+
+      pieces << ".#{HEADER_CLASS} { position: running(#{HEADER_RUNNING_NAME}); }" if header_html && !header_html.empty?
+      pieces << ".#{FOOTER_CLASS} { position: running(#{FOOTER_RUNNING_NAME}); }" if footer_html && !footer_html.empty?
+
+      pieces << ".#{PAGE_NUMBER_CLASS}::after { content: counter(page); }"
+      pieces << ".#{TOTAL_PAGES_CLASS}::after { content: counter(pages); }"
+
+      sides = opts[:margin_sides] || {}
+
+      # Full-page-width chrome strips, sized by the page's top/bottom margins.
+      if header_bg && sides['top']
+        pieces << <<~CSS
+          .pagedjs_page { position: relative; }
+          .pagedjs_page::before {
+            content: "";
+            position: absolute;
+            top: 0; left: 0; right: 0;
+            height: #{sides['top']};
+            background: #{header_bg};
+            z-index: 0;
+            -webkit-print-color-adjust: exact;
+            print-color-adjust: exact;
+          }
+        CSS
+      end
+
+      if footer_bg && sides['bottom']
+        pieces << <<~CSS
+          .pagedjs_page::after {
+            content: "";
+            position: absolute;
+            bottom: 0; left: 0; right: 0;
+            height: #{sides['bottom']};
+            background: #{footer_bg};
+            z-index: 0;
+            -webkit-print-color-adjust: exact;
+            print-color-adjust: exact;
+          }
+        CSS
+      end
+
+      # Make the running content extend to the full page width by overflowing
+      # the @top-center / @bottom-center margin box on the left and right by
+      # the page's side margins. Restores the Puppeteer chrome's edge-to-edge
+      # padding semantics (e.g. `padding: 0.4cm 26px 0.6cm 26px` inside the
+      # template now positions content from page edges, not from inner content
+      # area). Also lifts the content above the chrome strip pseudo-elements.
+      if sides['left'] || sides['right']
+        left = sides['left'] || '0'
+        right = sides['right'] || '0'
+        pieces << <<~CSS
+          .pagedjs_margin-top-center > .pagedjs_margin-content > *,
+          .pagedjs_margin-bottom-center > .pagedjs_margin-content > * {
+            margin-left: -#{left};
+            margin-right: -#{right};
+            position: relative;
+            z-index: 1;
+          }
+        CSS
+      end
+
+      pieces.join("\n")
+    end
+
+    # Spawns Node to require() config.js and emit pdf_options as JSON.
+    # Returns { size:, margin:, header_template:, footer_template: }, all
+    # nil-safe. On any failure, returns {} and logs to stderr.
+    def read_pdf_options
+      return {} unless @style_pack.config && File.exist?(@style_pack.config)
+
+      stdout, stderr, status = Open3.capture3(
+        'node', '-e', NODE_EXTRACT_SCRIPT, @style_pack.config
+      )
+      unless status.success?
+        $stderr.puts "[sakusei-preview] could not read pdf_options from config.js: #{stderr.strip}"
+        return {}
+      end
+
+      raw = JSON.parse(stdout)
+      sides = raw['margin'].is_a?(Hash) ? raw['margin'] : nil
+      {
+        size: raw['format'],
+        margin: format_margin(sides),
+        margin_sides: sides,
+        header_template: raw['headerTemplate'],
+        footer_template: raw['footerTemplate']
+      }
+    rescue StandardError => e
+      $stderr.puts "[sakusei-preview] failed to extract chrome from config.js: #{e.message}"
+      {}
+    end
+
+    def format_margin(margin)
+      return nil unless margin.is_a?(Hash)
+      sides = %w[top right bottom left].map { |s| margin[s] || '0' }
+      sides.join(' ')
+    end
+
+    # Heuristic: Puppeteer chrome templates often use a position-fixed
+    # background div to color the chrome strip. Find the first such background
+    # color so we can replicate the strip via .pagedjs_page::before / ::after.
+    # Looks for either `.X-bg { ... background: <color>; ... }` in a <style>
+    # block, or `<div ... style="...background: <color>...">` with a *-bg class.
+    def extract_chrome_bg(template)
+      return nil unless template
+      if template =~ /<style\b[^>]*>[\s\S]*?\.\w+-bg\s*\{[^}]*?background:\s*([^;}]+?)\s*[;}]/m
+        return Regexp.last_match(1).strip
+      end
+      if template =~ /<div\b[^>]*class=["'][^"']*\b\w+-bg\b[^"']*["'][^>]*style=["'][^"']*background:\s*([^;"]+)/m
+        return Regexp.last_match(1).strip
+      end
+      nil
+    end
+
+    # Transform a Puppeteer chrome template (HTML string) into preview HTML.
+    def transform_template(raw)
+      return nil if raw.nil?
+      s = raw.to_s.dup
+      return nil if s.strip.empty?
+
+      strip_chrome_bg_markup!(s)
+      s.gsub!(/<!--.*?-->/m, '')
+      s.gsub!(/<span\s+class=["']pageNumber["']\s*>\s*<\/span>/i, %(<span class="#{PAGE_NUMBER_CLASS}"></span>))
+      s.gsub!(/<span\s+class=["']totalPages["']\s*>\s*<\/span>/i, %(<span class="#{TOTAL_PAGES_CLASS}"></span>))
+      s.gsub!(/<span\s+class=["']title["']\s*>\s*<\/span>/i, '')
+      s.gsub!(/<span\s+class=["']date["']\s*>\s*<\/span>/i, Date.today.strftime('%Y-%m-%d'))
+      s.gsub!(/<span\s+class=["']url["']\s*>\s*<\/span>/i, '')
+      rewrite_image_paths!(s)
+      s.strip!
+      s
+    end
+
+    # Remove Puppeteer-specific markup that we replicate via paged.js CSS
+    # (the <style> block defining .X-bg and the empty <div class="X-bg">).
+    # Leaving them in would cover the whole page in paged.js because
+    # `position: fixed` resolves against .pagedjs_page, not the chrome strip.
+    def strip_chrome_bg_markup!(html)
+      html.sub!(/<style\b[^>]*>[\s\S]*?\.\w+-bg\s*\{[\s\S]*?\}[\s\S]*?<\/style>/m, '')
+      html.gsub!(/<div\b[^>]*class=["'][^"']*\b\w+-bg\b[^"']*["'][^>]*>\s*<\/div>/m, '')
+    end
+
+    # Rewrite <img src="rel/path"> to <img src="/__pack/rel/path"> for any
+    # path that looks relative (no scheme, no leading slash). Data URIs and
+    # absolute URLs pass through.
+    def rewrite_image_paths!(html)
+      html.gsub!(/(<img\b[^>]*\bsrc=["'])([^"']+)(["'])/i) do
+        prefix = Regexp.last_match(1)
+        src = Regexp.last_match(2)
+        suffix = Regexp.last_match(3)
+        new_src = if src.match?(%r{\A(https?:|data:|/)}) then src
+                  else "/__pack/#{src}"
+                  end
+        "#{prefix}#{new_src}#{suffix}"
+      end
+    end
+  end
+end

data/lib/sakusei/preview_server.rb

@@ -0,0 +1,444 @@
+# frozen_string_literal: true
+
+require 'webrick'
+require 'listen'
+require_relative 'builder'
+
+module Sakusei
+  # Live-reload preview server. Watches a markdown source and its dependencies
+  # (style pack, Vue components, @include partials, images) and re-renders to
+  # styled HTML on change. Browser long-polls /__events to know when to update;
+  # updates apply incrementally via paged.js's Previewer API (no full reload).
+  class PreviewServer
+    DEFAULT_PORT = 4567
+    DEBOUNCE_SECONDS = 0.05
+    POLL_TIMEOUT_SECONDS = 30
+
+    PAGED_JS_CDN = 'https://unpkg.com/pagedjs/dist/paged.js'
+
+    PREVIEW_CSS = <<~CSS
+      html, body {
+        background: #2a2a2a;
+        margin: 0;
+        padding: 0;
+      }
+      .pagedjs_pages {
+        padding: 24px 0;
+      }
+      .pagedjs_page {
+        background: white;
+        margin: 24px auto !important;
+        box-shadow: 0 8px 32px rgba(0,0,0,0.55);
+      }
+      #__sakusei_render {
+        min-height: 100vh;
+      }
+      #__sakusei_render.no-paged {
+        max-width: 850px;
+        margin: 24px auto;
+        padding: 48px 64px;
+        background: white;
+        box-shadow: 0 8px 32px rgba(0,0,0,0.55);
+      }
+    CSS
+
+    PREVIEW_JS = <<~'JS'
+      (function() {
+        var version = window.__SAKUSEI_VERSION__ || 0;
+        var renderTarget = null;
+        var ready = false;
+
+        function fullReload() { window.location.reload(); }
+
+        function render(html) {
+          renderTarget.innerHTML = '';
+          renderTarget.classList.remove('no-paged');
+          if (typeof Paged === 'undefined' || !Paged.Previewer) {
+            renderTarget.classList.add('no-paged');
+            renderTarget.innerHTML = html;
+            return Promise.resolve();
+          }
+          var previewer = new Paged.Previewer();
+          return previewer.preview(html, undefined, renderTarget).catch(function(e) {
+            console.error('[sakusei-preview] paged.js failed:', e);
+            renderTarget.classList.add('no-paged');
+            renderTarget.innerHTML = html;
+          });
+        }
+
+        function init() {
+          var sourceHTML = document.body.innerHTML;
+          document.body.innerHTML = '';
+          renderTarget = document.createElement('div');
+          renderTarget.id = '__sakusei_render';
+          document.body.appendChild(renderTarget);
+          render(sourceHTML).then(function() {
+            ready = true;
+            poll();
+          });
+        }
+
+        function refresh(newVersion) {
+          fetch('/__content').then(function(r) {
+            if (!r.ok) throw new Error('content fetch failed');
+            return r.text();
+          }).then(function(html) {
+            var scrollY = window.scrollY;
+            version = newVersion;
+            return render(html).then(function() {
+              window.scrollTo(0, scrollY);
+              poll();
+            });
+          }).catch(function(e) {
+            console.warn('[sakusei-preview] partial update failed, reloading:', e);
+            fullReload();
+          });
+        }
+
+        function poll() {
+          if (!ready) return;
+          fetch('/__events?since=' + version).then(function(r) {
+            if (r.status === 200) {
+              return r.text().then(function(t) {
+                var v = parseInt(t, 10);
+                if (v > version) {
+                  refresh(v);
+                } else {
+                  poll();
+                }
+              });
+            }
+            setTimeout(poll, 50);
+          }).catch(function() {
+            setTimeout(poll, 1000);
+          });
+        }
+
+        if (document.readyState === 'loading') {
+          document.addEventListener('DOMContentLoaded', init);
+        } else {
+          init();
+        }
+      })();
+    JS
+
+    def initialize(source_file, options = {})
+      @source_file = File.expand_path(source_file)
+      raise Error, "File not found: #{source_file}" unless File.exist?(@source_file)
+
+      @options = options
+      @port = options[:port] || DEFAULT_PORT
+      @open_browser = options.fetch(:open, true)
+      @use_paged_js = options.fetch(:paged, true)
+
+      @source_dir = File.dirname(@source_file)
+      @lock = Mutex.new
+      @cv = ConditionVariable.new
+      @version = 0
+      @cached_html = nil
+      @cached_body = nil
+      @cached_error = nil
+      @style_pack_path = nil
+
+      @rebuild_lock = Mutex.new
+      @debounce_timer = nil
+      @shutting_down = false
+    end
+
+    def run
+      build_now(initial: true)
+      start_listeners
+      start_server
+    end
+
+    private
+
+    def build_now(initial: false, change_detected_at: nil)
+      build_started_at = Time.now
+      builder = Builder.new(@source_file, @options)
+      html, style_pack = builder.build_html
+      build_done_at = Time.now
+
+      chrome = style_pack ? PageChromeTranslator.new(style_pack).build : { css: '', html: '' }
+
+      @style_pack_path = style_pack&.path
+      body_inner = extract_body_inner(html)
+      @cached_body = "#{chrome[:html]}#{body_inner}"
+      @cached_html = inject_preview_chrome(html, chrome)
+      @cached_error = nil
+      bump_version
+
+      log_timing(initial: initial, change_detected_at: change_detected_at,
+                 build_started_at: build_started_at, build_done_at: build_done_at)
+    rescue => e
+      @cached_error = e
+      @cached_html = render_error_page(e)
+      @cached_body = error_body(e)
+      bump_version
+      $stderr.puts "[sakusei-preview] build error: #{e.message}"
+    end
+
+    def log_timing(initial:, change_detected_at:, build_started_at:, build_done_at:)
+      build_ms = ms(build_started_at, build_done_at)
+      msg = "[sakusei-preview] #{initial ? 'initial render' : 're-rendered'} (v#{@version}) — build #{build_ms}ms"
+      if change_detected_at
+        detected_ms = ms(change_detected_at, build_started_at)
+        total_ms = ms(change_detected_at, build_done_at)
+        msg += " · detected #{detected_ms}ms · total #{total_ms}ms"
+      end
+      $stderr.puts msg
+    end
+
+    def ms(t0, t1)
+      ((t1 - t0) * 1000).round
+    end
+
+    def bump_version
+      @lock.synchronize do
+        @version += 1
+        @cv.broadcast
+      end
+    end
+
+    def start_listeners
+      dirs = [@source_dir]
+      dirs << @style_pack_path if @style_pack_path && !path_within?(@style_pack_path, @source_dir)
+
+      @listener = Listen.to(*dirs, ignore: [/node_modules/, /\.git/, /\.DS_Store/, /\.pdf\z/]) do |modified, added, removed|
+        changed = (modified + added + removed).reject { |p| p.end_with?('.pdf') }
+        next if changed.empty?
+        schedule_rebuild(Time.now)
+      end
+      @listener.start
+      $stderr.puts "[sakusei-preview] watching: #{dirs.join(', ')}"
+    end
+
+    def schedule_rebuild(detected_at)
+      @rebuild_lock.synchronize do
+        @debounce_timer&.kill
+        @debounce_timer = Thread.new do
+          sleep DEBOUNCE_SECONDS
+          build_now(change_detected_at: detected_at)
+        end
+      end
+    end
+
+    def start_server
+      server = WEBrick::HTTPServer.new(
+        Port: @port,
+        BindAddress: '127.0.0.1',
+        Logger: WEBrick::Log.new(File::NULL),
+        AccessLog: []
+      )
+
+      server.mount_proc('/__events') { |req, res| handle_events(req, res) }
+      server.mount_proc('/__content') { |_req, res| serve_text(res, 'text/html; charset=utf-8', @cached_body || '') }
+      server.mount_proc('/__assets/preview.js') { |_req, res| serve_text(res, 'application/javascript', PREVIEW_JS) }
+      server.mount_proc('/__pack') { |req, res| handle_pack_asset(req, res) }
+      server.mount_proc('/') { |req, res| handle_root_or_static(req, res) }
+
+      shutdown_queue = Queue.new
+      # Trap handlers run in a constrained context (no Mutex#synchronize),
+      # so just enqueue intent and let the supervisor thread do the work.
+      %w[INT TERM].each do |sig|
+        trap(sig) { shutdown_queue.push(:stop) rescue nil }
+      end
+
+      Thread.new do
+        shutdown_queue.pop
+        $stderr.puts "\n[sakusei-preview] shutting down..."
+        @shutting_down = true
+        # Wake any pending long-poll connections so they return immediately
+        # instead of holding the server open for up to POLL_TIMEOUT_SECONDS.
+        @lock.synchronize { @cv.broadcast }
+        @debounce_timer&.kill
+        begin
+          @listener&.stop
+        rescue StandardError
+          # Listen may raise on stop if its threads are already torn down.
+        end
+        server.shutdown
+      end
+
+      url = "http://127.0.0.1:#{@port}/"
+      $stderr.puts "[sakusei-preview] serving #{url}"
+      open_in_browser(url) if @open_browser
+
+      server.start
+    end
+
+    def handle_events(req, res)
+      since = req.query['since'].to_i
+      @lock.synchronize do
+        return shutdown_response(res) if @shutting_down
+        if @version > since
+          respond_version(res)
+          return
+        end
+        @cv.wait(@lock, POLL_TIMEOUT_SECONDS)
+        if @shutting_down
+          shutdown_response(res)
+        elsif @version > since
+          respond_version(res)
+        else
+          res.status = 204
+          res.body = ''
+        end
+      end
+    end
+
+    def shutdown_response(res)
+      res.status = 503
+      res['Content-Type'] = 'text/plain'
+      res.body = 'shutting down'
+    end
+
+    def respond_version(res)
+      res.status = 200
+      res['Content-Type'] = 'text/plain'
+      res['Cache-Control'] = 'no-store'
+      res.body = @version.to_s
+    end
+
+    def handle_pack_asset(req, res)
+      unless @style_pack_path
+        res.status = 404
+        res.body = 'no style pack'
+        return
+      end
+
+      rel = req.path.sub(%r{\A/__pack/?}, '')
+      if rel.empty?
+        res.status = 404
+        res.body = 'not found'
+        return
+      end
+
+      candidate = File.expand_path(rel, @style_pack_path)
+      unless candidate.start_with?(File.expand_path(@style_pack_path) + File::SEPARATOR)
+        res.status = 403
+        res.body = 'forbidden'
+        return
+      end
+
+      if File.file?(candidate)
+        res.status = 200
+        res['Content-Type'] = WEBrick::HTTPUtils.mime_type(candidate, WEBrick::HTTPUtils::DefaultMimeTypes)
+        res['Cache-Control'] = 'no-store'
+        res.body = File.binread(candidate)
+      else
+        res.status = 404
+        res.body = 'not found'
+      end
+    end
+
+    def handle_root_or_static(req, res)
+      path = req.path
+      if path == '/' || path == ''
+        serve_text(res, 'text/html; charset=utf-8', @cached_html || '<p>building...</p>')
+        return
+      end
+
+      rel = path.sub(%r{\A/}, '')
+      candidate = File.expand_path(rel, @source_dir)
+      unless candidate.start_with?(File.expand_path(@source_dir) + File::SEPARATOR)
+        res.status = 403
+        res.body = 'forbidden'
+        return
+      end
+
+      if File.file?(candidate)
+        res['Content-Type'] = WEBrick::HTTPUtils.mime_type(candidate, WEBrick::HTTPUtils::DefaultMimeTypes)
+        res['Cache-Control'] = 'no-store'
+        res.body = File.binread(candidate)
+      else
+        res.status = 404
+        res.body = 'not found'
+      end
+    end
+
+    def serve_text(res, content_type, body)
+      res.status = 200
+      res['Content-Type'] = content_type
+      res['Cache-Control'] = 'no-store'
+      res.body = body
+    end
+
+    # Extract the inner HTML of <body>...</body>. Falls back to the original
+    # html if the regex doesn't match (e.g. md-to-pdf changes its output shape).
+    def extract_body_inner(html)
+      m = html.match(/<body[^>]*>(.*)<\/body>/m)
+      m ? m[1] : html
+    end
+
+    def inject_preview_chrome(html, chrome = { css: '', html: '' })
+      version_script = "<script>window.__SAKUSEI_VERSION__=#{@version + 1};</script>"
+      paged = @use_paged_js ? %(<script src="#{PAGED_JS_CDN}"></script>) : ''
+      preview_js = '<script src="/__assets/preview.js"></script>'
+      style_block = "<style>#{PREVIEW_CSS}\n#{chrome[:css]}</style>"
+
+      head_injection = "#{style_block}#{paged}"
+      body_open_injection = chrome[:html].to_s
+      body_close_injection = "#{version_script}#{preview_js}"
+
+      result = if html.include?('</head>')
+                 html.sub('</head>', "#{head_injection}</head>")
+               else
+                 head_injection + html
+               end
+
+      if (m = result.match(/<body[^>]*>/))
+        result = result.sub(m[0], "#{m[0]}#{body_open_injection}")
+      else
+        result = body_open_injection + result
+      end
+
+      if result.include?('</body>')
+        result.sub('</body>', "#{body_close_injection}</body>")
+      else
+        result + body_close_injection
+      end
+    end
+
+    def error_body(err)
+      msg = WEBrick::HTMLUtils.escape(err.message)
+      backtrace = WEBrick::HTMLUtils.escape((err.backtrace || []).first(20).join("\n"))
+      <<~HTML
+        <h1 style="color:#ff6b6b;">Build failed</h1>
+        <pre style="background:#000;color:#e0e0e0;padding:1rem;overflow:auto;">#{msg}</pre>
+        <h2 style="color:#ccc;">Backtrace</h2>
+        <pre style="background:#000;color:#e0e0e0;padding:1rem;overflow:auto;">#{backtrace}</pre>
+      HTML
+    end
+
+    def render_error_page(err)
+      version_script = "<script>window.__SAKUSEI_VERSION__=#{@version + 1};</script>"
+      <<~HTML
+        <!DOCTYPE html>
+        <html><head><meta charset="utf-8"><title>sakusei-preview error</title>
+        <style>
+          body { font-family: ui-monospace, Menlo, monospace; padding: 2rem; background:#1e1e1e; color:#e0e0e0; }
+          #{PREVIEW_CSS}
+        </style>
+        </head><body>
+        #{error_body(err)}
+        #{version_script}
+        <script src="/__assets/preview.js"></script>
+        </body></html>
+      HTML
+    end
+
+    def path_within?(child, parent)
+      File.expand_path(child).start_with?(File.expand_path(parent) + File::SEPARATOR)
+    end
+
+    def open_in_browser(url)
+      cmd = case RbConfig::CONFIG['host_os']
+            when /darwin/i then ['open', url]
+            when /linux/i then ['xdg-open', url]
+            when /mswin|mingw|cygwin/i then ['start', url]
+            end
+      system(*cmd) if cmd
+    end
+  end
+end

data/lib/sakusei/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Sakusei
-  VERSION = '0.4.0'
+  VERSION = '0.5.8'
 end

data/lib/sakusei.rb

@@ -15,6 +15,8 @@ require_relative 'sakusei/pdf_concat'
 require_relative 'sakusei/multi_file_builder'
 require_relative 'sakusei/style_preview'
 require_relative 'sakusei/vue_processor'
+require_relative 'sakusei/html_converter'
+require_relative 'sakusei/page_chrome_translator'
 
 module Sakusei
   class Error < StandardError; end

data/sakusei.gemspec

@@ -17,12 +17,14 @@ Gem::Specification.new do |spec|
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{\A(?:test|spec|features)/}) }
   end
   spec.bindir        = 'bin'
-  spec.executables   = ['sakusei']
+  spec.executables   = %w[sakusei sakusei-preview]
   spec.require_paths = ['lib']
 
   # Dependencies
   spec.add_dependency 'thor', '~> 1.2'
   spec.add_dependency 'erb', '~> 4.0'
+  spec.add_dependency 'listen', '~> 3.8'
+  spec.add_dependency 'webrick', '~> 1.8'
 
   spec.add_development_dependency 'minitest', '~> 5.0'
   spec.add_development_dependency 'rubocop', '~> 1.0'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sakusei
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.8
 platform: ruby
 authors:
 - Keith Rowell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-04-20 00:00:00.000000000 Z
+date: 2026-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -38,6 +38,34 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: listen
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.8'
+- !ruby/object:Gem::Dependency
+  name: webrick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.8'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -72,14 +100,19 @@ email:
 - keith@example.com
 executables:
 - sakusei
+- sakusei-preview
 extensions: []
 extra_rdoc_files: []
 files:
+- ".claude/settings.json"
 - ".gitignore"
+- CLAUDE.md
 - Gemfile
+- Gemfile.lock
 - README.md
 - Rakefile
 - bin/sakusei
+- bin/sakusei-preview
 - examples/getting-started-screenshot.png
 - examples/getting-started.md
 - examples/getting-started.pdf
@@ -89,13 +122,17 @@ files:
 - lib/sakusei.rb
 - lib/sakusei/builder.rb
 - lib/sakusei/cli.rb
+- lib/sakusei/converter_base.rb
 - lib/sakusei/erb_processor.rb
 - lib/sakusei/file_resolver.rb
 - lib/sakusei/heading_wrapper.rb
+- lib/sakusei/html_converter.rb
 - lib/sakusei/image_path_resolver.rb
 - lib/sakusei/md_to_pdf_converter.rb
 - lib/sakusei/multi_file_builder.rb
+- lib/sakusei/page_chrome_translator.rb
 - lib/sakusei/pdf_concat.rb
+- lib/sakusei/preview_server.rb
 - lib/sakusei/style_pack.rb
 - lib/sakusei/style_preview.rb
 - lib/sakusei/version.rb