sakusei 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d842e81bb78fb5e34d0750ee5f125b13b6a7b5dec236ce70547fcb44e6438ca
-  data.tar.gz: 6872dbd65f839bd5e3fb786bcbf8712310c03aa99332f6ff740901fc26275800
+  metadata.gz: 3c5167b69a1150bb93726449a31f46408381ae14f26c0034e472a3ce6b22ee3f
+  data.tar.gz: b2187d77e9222b69d927da57ed085cb876e7e0aa7e2c2f556bf4bbfc9e8bbc1b
 SHA512:
-  metadata.gz: 96c3e6db1059839c6bd8632c11789dfd6ec56af507b8f6ef754600dcee498be62fbad33b605cde5853fdb4734150a88ce53ba1bef863df09bf89e23c93c6e1c3
-  data.tar.gz: a784a67e5c4cfbda815f3f6b96c0cc2de177125ce42bf7cc941a27a901487bb5f67a04240530e0f94ee1cf31500b402d650dc3298765ddae8e19b6a88a46152e
+  metadata.gz: b15a0b12a135ce5eec0d4ab4afa9db615abac32405656456b15ac66d612a13fb8bcfaea564824be18d74a201a947f8ba4d21e5f40a591cf6c90c59589d8443f2
+  data.tar.gz: c9c3dcfa53b2fd665a614414cae22502d830e618c3018b32b00fe314ea5b200d91569483e0c31e5c095862e0999c03ae67d4a8e148b56e2a151007bec8ec6c50

data/.gitignore

@@ -2,3 +2,4 @@
 .DS_Store
 *.pdf
 node_modules/
+.worktrees/

data/lib/sakusei/builder.rb

@@ -3,7 +3,9 @@
 require_relative 'style_pack'
 require_relative 'file_resolver'
 require_relative 'erb_processor'
+require_relative 'image_path_resolver'
 require_relative 'vue_processor'
+require_relative 'heading_wrapper'
 require_relative 'md_to_pdf_converter'
 
 module Sakusei
@@ -16,28 +18,37 @@ module Sakusei
 
     def build
       # 1. Discover and load style pack
+      $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)
 
       # 4. Process Vue components (if available)
-      processed_content = process_vue(processed_content)
+      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
     end
 
     private
 
     def discover_style_pack
-      StylePack.discover(@source_dir, @options[:style])
+      StylePack.discover(@options[:source_dir] || @source_dir, @options[:style])
     end
 
     def resolve_files
@@ -45,15 +56,23 @@ module Sakusei
     end
 
     def process_erb(content)
-      ErbProcessor.new(content, @source_dir).process
+      ErbProcessor.new(content, @source_dir, source_file: @source_file).process
+    end
+
+    def resolve_image_paths(content)
+      ImagePathResolver.new(content, @source_dir).resolve
+    end
+
+    def process_vue(content, style_pack)
+      VueProcessor.new(content, @source_dir, style_pack: style_pack).process
     end
 
-    def process_vue(content)
-      VueProcessor.new(content, @source_dir).process
+    def wrap_headings(content)
+      HeadingWrapper.new(content).wrap
     end
 
     def convert_to_pdf(content, output_path, style_pack)
-      MdToPdfConverter.new(content, output_path, style_pack, @options).convert
+      MdToPdfConverter.new(content, output_path, style_pack, @options.merge(source_dir: @source_dir)).convert
     end
 
     def generate_output_path

data/lib/sakusei/cli.rb

@@ -65,7 +65,7 @@ module Sakusei
     def concat(*files)
       raise Error, 'No input files provided' if files.empty?
 
-      PdfConcat.new(files, options[:output]).concat
+      PdfConcatenator.new(files, options[:output]).concat
       say "PDFs concatenated: #{options[:output]}", :green
     rescue Error => e
       say_error e.message
@@ -92,6 +92,115 @@ module Sakusei
       exit 1
     end
 
+    desc 'components [STYLE]', 'List available Vue components'
+    option :directory, aliases: '-d', default: '.', desc: 'Directory to search for style packs'
+    def components(style = nil)
+      pack = StylePack.discover(options[:directory], style)
+
+      say "\nAvailable Vue components:\n\n"
+
+      pack_components = pack.list_components
+      if pack_components.any?
+        say "  Style pack: #{pack.name}", :cyan
+        pack_components.each do |comp|
+          desc_str = comp[:description] || '(no description)'
+          say "  • #{comp[:name].ljust(18)} #{desc_str}"
+        end
+      else
+        say "  Style pack '#{pack.name}' has no Vue components.", :yellow
+      end
+
+      if style.nil?
+        local_components_dir = File.join(Dir.pwd, 'components')
+        if Dir.exist?(local_components_dir)
+          say ""
+          say "  Local (./components/)", :cyan
+          Dir.glob(File.join(local_components_dir, '*.vue')).sort.each do |file|
+            name = File.basename(file, '.vue')
+            desc_str = StylePack.extract_docs_description(file) || '(no description)'
+            say "  • #{name.ljust(18)} #{desc_str}"
+          end
+        end
+      end
+    rescue Error => e
+      say_error e.message
+      exit 1
+    end
+
+    desc 'component NAME', 'Show detailed information about a Vue component'
+    option :directory, aliases: '-d', default: '.', desc: 'Directory to search for style packs'
+    option :verbose, aliases: '-v', type: :boolean, default: false, desc: 'Show full component source code'
+    def component(name)
+      info = StylePack.find_component(options[:directory], name)
+
+      unless info
+        say_error "Component '#{name}' not found"
+        exit 1
+      end
+
+      say "\n"
+      say "═" * 60, :cyan
+      say "  #{info[:name]}", :cyan
+      say "═" * 60, :cyan
+      say "\n"
+
+      # Description
+      if info[:description]
+        say "📄 Description:"
+        say "   #{info[:description]}"
+        say "\n"
+      end
+
+      # Location
+      say "📁 Location:"
+      say "   #{info[:path]}", :cyan
+      say "   (in style pack: #{info[:pack_name]})"
+      say "\n"
+
+      # Props
+      if info[:props]&.any?
+        say "⚙️  Props:"
+        info[:props].each do |prop|
+          req_str = prop[:required] ? 'required' : 'optional'
+          default_str = prop[:default] ? " (default: #{prop[:default]})" : ""
+          type_str = prop[:type] ? " [#{prop[:type]}]" : ""
+          say "   • #{prop[:name]}#{type_str} - #{req_str}#{default_str}"
+        end
+        say "\n"
+      end
+
+      # Usage
+      say "📝 Usage:"
+      say "   #{info[:usage]}", :green
+      say "\n"
+
+      # Full documentation if available
+      if info[:full_description] && info[:full_description].lines.count > 1
+        say "📖 Documentation:"
+        info[:full_description].lines.each do |line|
+          say "   #{line.rstrip}"
+        end
+        say "\n"
+      end
+
+      # Full source option
+      if options[:verbose]
+        say "🔍 Template:"
+        say info[:template] || "(no template)"
+        say "\n"
+        say "🔍 Script:"
+        say info[:script] || "(no script)"
+        say "\n"
+        say "🔍 Style:"
+        say info[:style] || "(no style)"
+      else
+        say "💡 Use --verbose to see the full component source code"
+      end
+    rescue Error => e
+      say_error e.message
+      exit 1
+    end
+
     desc 'version', 'Show version'
     def version
       say "Sakusei #{Sakusei::VERSION}"
@@ -102,8 +211,8 @@ module Sakusei
 
     # Override dispatch to treat file paths as build commands
     def self.dispatch(meth, given_args, given_opts, config)
-      # If first arg is an existing file or glob pattern, treat it as a build command
-      if given_args.any? && file_arg?(given_args.first)
+      # If first arg is an existing file or glob pattern (and not a known subcommand), treat it as a build command
+      if given_args.any? && !all_commands.key?(given_args.first) && file_arg?(given_args.first)
         given_args.unshift('build')
       end
       super

data/lib/sakusei/erb_processor.rb

@@ -1,34 +1,42 @@
 # frozen_string_literal: true
 
 require 'erb'
+require 'json'
 
 module Sakusei
   # Processes ERB templates in markdown content
   class ErbProcessor
-    def initialize(content, base_dir)
+    def initialize(content, base_dir, source_file: nil)
       @content = content
       @base_dir = base_dir
+      @source_file = source_file
     end
 
     def process
       # Create a context object with helper methods
-      context = ErbContext.new(@base_dir)
+      context = ErbContext.new(@base_dir, source_file: @source_file)
 
-      # Process the ERB
+      # Process the ERB — setting filename makes require_relative resolve
+      # relative to the source document, not the working directory.
       erb = ERB.new(@content, trim_mode: '-')
-      erb.result(context.binding)
+      erb.filename = @source_file if @source_file
+      erb.result(context.template_binding)
     rescue StandardError => e
       raise Error, "ERB processing error: #{e.message}"
     end
 
     # Context object that provides helper methods for ERB templates
     class ErbContext
-      def initialize(base_dir)
+      def initialize(base_dir, source_file: nil)
         @base_dir = base_dir
+        @source_file = source_file
       end
 
-      def binding
-        ::Kernel.binding
+      # Returns the binding of this ErbContext instance so that ERB local
+      # variables (e.g. <% x = 1 %>) persist across the full template evaluation
+      # and helper methods (today, include_file, etc.) are callable as self.
+      def template_binding
+        binding
       end
 
       # Helper method to include file content directly
@@ -51,6 +59,68 @@ module Sakusei
       def sh(command)
         `#{command}`.chomp
       end
+
+      # Resolves a relative image path (relative to the source document) to a
+      # file:// URI that Puppeteer can load during PDF generation.
+      #
+      # Usage in markdown:
+      #   <%= image_path('images/photo.jpg') %>
+      def image_path(relative_path)
+        full_path = File.expand_path(relative_path, @base_dir)
+        "file://#{full_path}"
+      end
+
+      # Extracts document headings as a JSON array for use with the Contents component.
+      # Only includes headings that appear after the Contents component tag in the file.
+      # Normalises heading depth relative to h2: h2 → level 1, h3 → level 2, etc.
+      #
+      # Usage:
+      #   <%= document_headings %>              # reads current source file
+      #   <%= document_headings('./other.md') %> # reads a specific file
+      def document_headings(path = nil)
+        target = path ? File.expand_path(path, @base_dir) : @source_file
+        return '[]' unless target && File.exist?(target)
+
+        items = []
+        past_contents = false
+
+        File.foreach(target) do |line|
+          line = line.chomp
+          past_contents = true if !past_contents && line.match?(/vue-component\s+name=["']Contents["']/)
+          next unless past_contents
+
+          m = line.match(/^(#+)\s+(.+)/)
+          next unless m
+
+          raw_level = m[1].length
+          next if raw_level < 2 # skip h1 document title
+
+          title = m[2].strip
+          items << { title: title, level: raw_level - 1, slug: slugify(title) }
+        end
+
+        items.to_json
+      end
+
+      private
+
+      # Slugify matching marked's Slugger.serialize (used by md-to-pdf v3).
+      # Mirrors the JS logic exactly so that href="#slug" in Contents links
+      # match the id="slug" attributes that marked puts on headings.
+      #
+      # marked source:
+      #   .toLowerCase().trim()
+      #   .replace(/<[!\/a-z].*?>/ig, '')          # strip html tags
+      #   .replace(/[\u2000-\u206F\u2E00-\u2E7F\'...]/g, '')  # remove punctuation
+      #   .replace(/\s/g, '-')                     # each space → hyphen (NOT \s+)
+      def slugify(title)
+        title
+          .downcase
+          .strip
+          .gsub(/<[!\/a-z].*?>/i, '')
+          .gsub(/[\u2000-\u206F\u2E00-\u2E7F\\'!"#$%&()*+,.\/:;<=>?@\[\]^`{|}~]/, '')
+          .gsub(/\s/, '-')
+      end
     end
   end
 end

data/lib/sakusei/heading_wrapper.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Sakusei
+  # Wraps each h2/h3 heading and its immediately following content block in a
+  # <div style="page-break-inside: avoid"> so that Chromium/Puppeteer keeps
+  # the heading glued to the content that follows it.
+  #
+  # Operates on the markdown string after ERB and Vue processing so that Vue
+  # component output (already rendered to HTML) is treated as a normal block.
+  # Raw HTML in the markdown (html: true) passes through md-to-pdf untouched.
+  class HeadingWrapper
+    HEADING_PATTERN = /\A[ \t]*(##|###) /
+
+    def initialize(content)
+      @content = content
+    end
+
+    def wrap
+      # Split on two-or-more blank lines to get top-level blocks.
+      # Preserve the separator length so rejoining is faithful.
+      blocks = @content.split(/(\n{2,})/)
+      # split with a capture group gives us [block, sep, block, sep, ...]
+      result = []
+      i = 0
+      while i < blocks.length
+        block = blocks[i]
+        sep   = blocks[i + 1] || "\n\n"
+
+        if heading_block?(block)
+          # Look ahead past the separator to the next content block
+          next_block = blocks[i + 2]
+          next_sep   = blocks[i + 3] || "\n\n"
+
+          if next_block && !heading_block?(next_block)
+            result << "<div style=\"page-break-inside: avoid\">\n\n#{block}#{sep}#{next_block}\n\n</div>"
+            result << next_sep
+            i += 4
+            next
+          end
+        end
+
+        result << block
+        result << sep
+        i += 2
+      end
+
+      result.join
+    end
+
+    private
+
+    def heading_block?(block)
+      return false unless block
+      block.match?(HEADING_PATTERN)
+    end
+  end
+end

data/lib/sakusei/image_path_resolver.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'base64'
+
+module Sakusei
+  # Embeds local images as base64 data URIs so that Puppeteer can render them
+  # regardless of HTTP server basedir or working directory. Runs after ERB
+  # processing so documents can use standard relative paths (e.g. images/foo.jpg)
+  # and remain previewable in any standard markdown viewer.
+  #
+  # Handles:
+  #   - Standard markdown images:  ![alt](images/foo.jpg)
+  #   - Vue component image props:  "image":"images/foo.jpg"
+  #
+  # Leaves http://, https://, data:, and missing files untouched.
+  class ImagePathResolver
+    SKIP_PATTERN = /\A(https?:|data:|\/\/)/i
+
+    MIME_TYPES = {
+      '.jpg'  => 'image/jpeg',
+      '.jpeg' => 'image/jpeg',
+      '.png'  => 'image/png',
+      '.gif'  => 'image/gif',
+      '.svg'  => 'image/svg+xml',
+      '.webp' => 'image/webp'
+    }.freeze
+
+    def initialize(content, base_dir)
+      @content  = content
+      @base_dir = base_dir
+    end
+
+    def resolve
+      content = resolve_markdown_images(@content)
+      content = resolve_component_image_props(content)
+      content
+    end
+
+    private
+
+    def to_data_uri(path)
+      return path if path.match?(SKIP_PATTERN)
+
+      full_path = path.start_with?('/') ? path : File.expand_path(path, @base_dir)
+      return path unless File.exist?(full_path)
+
+      ext  = File.extname(full_path).downcase
+      mime = MIME_TYPES[ext] || 'application/octet-stream'
+      data = Base64.strict_encode64(File.binread(full_path))
+      "data:#{mime};base64,#{data}"
+    end
+
+    def resolve_markdown_images(content)
+      content.gsub(/!\[([^\]]*)\]\(([^)]+)\)/) do
+        alt  = Regexp.last_match(1)
+        path = Regexp.last_match(2).strip
+        "![#{alt}](#{to_data_uri(path)})"
+      end
+    end
+
+    def resolve_component_image_props(content)
+      content.gsub(/"image"\s*:\s*"([^"]+)"/) do
+        path = Regexp.last_match(1)
+        "\"image\":\"#{to_data_uri(path)}\""
+      end
+    end
+  end
+end

data/lib/sakusei/md_to_pdf_converter.rb

@@ -1,36 +1,34 @@
 # frozen_string_literal: true
 
-require 'tempfile'
+require 'fileutils'
+require 'tmpdir'
 
 module Sakusei
   # Converts markdown content to PDF using md-to-pdf
   class MdToPdfConverter
     def initialize(content, output_path, style_pack, options = {})
-      @content = content
+      @content    = content
       @output_path = output_path
       @style_pack = style_pack
-      @options = options
+      @options    = options
+      @source_dir = options[:source_dir]
     end
 
     def convert
-      # Create temp directory for working files
       Dir.mktmpdir('sakusei') do |temp_dir|
-        # Write content to temp markdown file
+        # Write processed content to temp markdown file
         temp_md = File.join(temp_dir, 'input.md')
-        File.write(temp_md, @content)
+        File.write(temp_md, page_chrome_prefix + @content)
 
-        # Build md-to-pdf command
-        cmd = build_command(temp_md, temp_dir)
+        # Copy any local images into the temp dir, mirroring the relative structure,
+        # so md-to-pdf's HTTP server can serve them by their relative paths.
+        copy_images(temp_dir)
 
-        # Execute command
+        cmd = build_command(temp_md, temp_dir)
         result = system(cmd)
         raise Error, 'PDF conversion failed' unless result
 
-        # md-to-pdf outputs to input.pdf in the same directory
-        temp_pdf = File.join(temp_dir, 'input.pdf')
-
-        # Move to final destination
-        FileUtils.mv(temp_pdf, @output_path)
+        FileUtils.mv(File.join(temp_dir, 'input.pdf'), @output_path)
       end
 
       @output_path
@@ -38,31 +36,61 @@ module Sakusei
 
     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 file
       config = @options[:config] || @style_pack.config
       cmd << '--config-file' << config if config
 
-      # Stylesheets - base CSS first, then style pack CSS
-      # This allows style packs to override base styles
       stylesheets = [StylePack.base_stylesheet]
-
-      # Add style pack stylesheet if available
       pack_stylesheet = @options[:stylesheet] || @style_pack.stylesheet
       stylesheets << pack_stylesheet if pack_stylesheet
+      stylesheets.each { |s| cmd << '--stylesheet' << s }
 
-      stylesheets.each do |stylesheet|
-        cmd << '--stylesheet' << stylesheet
-      end
-
-      # Basedir for resolving relative paths
+      # 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
 
-      # Input file
       cmd << temp_path
-
       cmd.join(' ')
     end
   end

data/lib/sakusei/multi_file_builder.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'tempfile'
+
 module Sakusei
   # Builds multiple markdown files into a single PDF with consistent page numbering
   class MultiFileBuilder
@@ -18,8 +20,14 @@ module Sakusei
       # Process the combined content through the normal pipeline
       temp_file = create_temp_file(combined_content)
 
-      # Use standard Builder with the combined file
-      Builder.new(temp_file, @options.merge(base_dir: @base_dir)).build
+      # Derive output path from the first source file if not explicitly specified
+      output = @options[:output] || begin
+        first = @files.first
+        File.join(File.dirname(File.expand_path(first)), "#{File.basename(first, '.*')}.pdf")
+      end
+
+      # Use standard Builder with the combined file, pointing it at the real source dir
+      Builder.new(temp_file, @options.merge(source_dir: @base_dir, output: output)).build
     ensure
       File.delete(temp_file) if temp_file && File.exist?(temp_file)
     end

data/lib/sakusei/style_pack.rb

@@ -48,6 +48,159 @@ module Sakusei
       pack_path
     end
 
+    def components_dir
+      dir = File.join(@path, 'components')
+      Dir.exist?(dir) ? dir : nil
+    end
+
+    def list_components
+      return [] unless components_dir
+      Dir.glob(File.join(components_dir, '*.vue')).sort.map do |file|
+        {
+          name: File.basename(file, '.vue'),
+          description: self.class.extract_docs_description(file),
+          path: file
+        }
+      end
+    end
+
+    def self.extract_docs_description(file)
+      content = File.read(file)
+      match = content.match(/<docs>\s*\n\s*(.+)/)
+      match ? match[1].strip : nil
+    end
+
+    # Find a component by name across style packs and local directories
+    def self.find_component(start_dir, component_name)
+      # Search in style packs
+      sakusei_path = find_sakusei_dir(start_dir)
+      if sakusei_path
+        packs_dir = File.join(sakusei_path, STYLE_PACKS_DIR)
+        if Dir.exist?(packs_dir)
+          Dir.glob(File.join(packs_dir, '*')).select { |f| File.directory?(f) }.each do |pack_path|
+            component_file = File.join(pack_path, 'components', "#{component_name}.vue")
+            if File.exist?(component_file)
+              pack = new(pack_path)
+              return pack.extract_component_info(component_file)
+            end
+          end
+        end
+      end
+
+      # Search in local ./components directory
+      local_component = File.join(Dir.pwd, 'components', "#{component_name}.vue")
+      if File.exist?(local_component)
+        return extract_component_info(local_component, 'local')
+      end
+
+      # Search in default style pack
+      default_path = File.expand_path('../templates/default_style_pack', __dir__)
+      default_component = File.join(default_path, 'components', "#{component_name}.vue")
+      if File.exist?(default_component)
+        pack = new(default_path, 'default')
+        return pack.extract_component_info(default_component)
+      end
+
+      nil
+    end
+
+    # Extract full component information from a Vue file
+    def self.extract_component_info(file, pack_name = nil)
+      pack_name ||= File.basename(File.dirname(File.dirname(file)))
+      content = File.read(file)
+
+      # Extract docs section
+      docs_match = content.match(/<docs>(.+?)<\/docs>/m)
+      docs = docs_match ? docs_match[1].strip : nil
+
+      # Extract template section
+      template_match = content.match(/<template>(.+?)<\/template>/m)
+      template = template_match ? template_match[1].strip : nil
+
+      # Extract script section
+      script_match = content.match(/<script(?:\s+setup)?>(.+?)<\/script>/m)
+      script = script_match ? script_match[1].strip : nil
+
+      # Extract style section
+      style_match = content.match(/<style(?:\s+scoped)?>(.+?)<\/style>/m)
+      style = style_match ? style_match[1].strip : nil
+
+      # Parse props from script
+      props = parse_props(script) if script
+
+      # Generate usage example
+      usage = generate_usage(File.basename(file, '.vue'), props, template)
+
+      {
+        name: File.basename(file, '.vue'),
+        description: docs ? docs.lines.first&.strip : nil,
+        full_description: docs,
+        path: file,
+        pack_name: pack_name,
+        template: template,
+        script: script,
+        style: style,
+        props: props,
+        usage: usage
+      }
+    end
+
+    # Instance method wrapper for extract_component_info
+    def extract_component_info(file)
+      self.class.extract_component_info(file, @name)
+    end
+
+    private_class_method def self.parse_props(script)
+      props = []
+
+      # Match defineProps with object syntax
+      props_match = script.match(/defineProps\(\{(.+?)\}\)/m)
+      if props_match
+        props_block = props_match[1]
+        # Parse each property
+        props_block.scan(/(\w+):\s*\{([^}]+)\}/).each do |name, config|
+          prop = { name: name, required: false }
+          if config.include?('required: true')
+            prop[:required] = true
+          elsif config.include?('default:')
+            default_match = config.match(/default:\s*([^,\n]+)/)
+            prop[:default] = default_match[1].strip if default_match
+          end
+          if config.include?('type:')
+            type_match = config.match(/type:\s*(\w+)/)
+            prop[:type] = type_match[1] if type_match
+          end
+          props << prop
+        end
+      end
+
+      # Match defineProps with array syntax: defineProps(['name', 'other'])
+      array_match = script.match(/defineProps\(\[\s*([^\]]+)\s*\]\)/)
+      if array_match
+        array_match[1].scan(/['"]([^'"]+)['"]/).each do |name|
+          props << { name: name[0], required: true }
+        end
+      end
+
+      props
+    end
+
+    private_class_method def self.generate_usage(name, props, template)
+      return "<#{name} />" unless props&.any?
+
+      attrs = props.map do |prop|
+        if prop[:required]
+          "#{prop[:name]}=\"...\""
+        elsif prop[:default]
+          "#{prop[:name]}=\"#{prop[:default].gsub(/['"]/, '')}\""
+        else
+          "#{prop[:name]}=\"...\""
+        end
+      end
+
+      "<#{name} #{attrs.join(' ')} />"
+    end
+
     # List all available style packs
     def self.list_available(start_dir = '.')
       packs = []
@@ -80,7 +233,7 @@ module Sakusei
 
       # Remove duplicates by name (closer packs take precedence)
       seen_names = Set.new
-      packs.reverse.select { |p| seen_names.add?(p[:name]) }.reverse
+      packs.select { |p| seen_names.add?(p[:name]) }
     end
 
     private
@@ -140,7 +293,11 @@ module Sakusei
     end
 
     def run
-      StylePack.init(@directory, @name)
+      pack_path = StylePack.init(@directory, @name)
+      $stderr.puts "Installing style pack dependencies for '#{@name}'..."
+      result = system('npm', 'install', '--prefix', pack_path)
+      raise Sakusei::Error, "npm install failed for style pack '#{@name}'. Check #{pack_path}." unless result
+      pack_path
     end
   end
 end

data/lib/sakusei/version.rb

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

data/lib/sakusei/vue_processor.rb

@@ -8,7 +8,8 @@ module Sakusei
   # Processes Vue components at build time using a single Node.js process per build.
   # Requires Node.js with @vue/server-renderer, @vue/compiler-sfc, and vue@3 installed.
   class VueProcessor
-    VUE_COMPONENT_PATTERN = /<vue-component\s+([^>]+)(?:\s*\/>|>(.*?)<\/vue-component>)/m
+    # Attribute values may contain > (e.g. HTML in slot-like props), so we match quoted strings properly
+    VUE_COMPONENT_PATTERN = /<vue-component((?:\s+[\w-]+=(?:"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'))*)\s*(?:\/>|>(.*?)<\/vue-component>)/m
 
     INSTALL_INSTRUCTIONS = <<~MSG
       Vue components detected but dependencies not found.
@@ -23,20 +24,27 @@ module Sakusei
         npm install @vue/server-renderer @vue/compiler-sfc vue@3
     MSG
 
-    def initialize(content, base_dir)
+    def initialize(content, base_dir, style_pack: nil)
       @content = content
       @base_dir = base_dir
+      @style_pack = style_pack
     end
 
     def process
       return @content unless vue_components_present?
+
+      ensure_style_pack_deps_installed
       raise Error, INSTALL_INSTRUCTIONS unless vue_renderer_available?
 
       jobs = []
       content_with_placeholders = first_pass(@content, jobs)
       return content_with_placeholders if jobs.empty?
 
+      content_with_placeholders = wrap_headings_with_placeholders(content_with_placeholders)
+
+      $stderr.puts "[sakusei] rendering #{jobs.length} Vue component(s)..."
       results = render_batch(jobs)
+      $stderr.puts "[sakusei] Vue components rendered"
       result_map = results.each_with_object({}) { |r, h| h[r['id']] = r }
 
       all_css = []
@@ -65,9 +73,20 @@ module Sakusei
     end
 
     def vue_renderer_available?
+      return true if style_pack_has_vue_renderer?
       self.class.available?
     end
 
+    def style_pack_has_vue_renderer?
+      return false unless @style_pack
+      nm = File.join(@style_pack.path, 'node_modules')
+      return false unless Dir.exist?(nm)
+      env = { 'NODE_PATH' => nm }
+      system(env, 'node', '-e',
+        "try{require('@vue/server-renderer');process.exit(0)}catch(e){process.exit(1)}",
+        %i[out err] => File::NULL)
+    end
+
     def self.vue_renderer_installed?
       check_cmd = "cd '#{Dir.pwd}' && node -e \"try { require('@vue/server-renderer'); require('@vue/compiler-sfc'); process.exit(0); } catch(e) { process.exit(1); }\" 2>/dev/null"
       system(check_cmd)
@@ -81,12 +100,15 @@ module Sakusei
         component_name = attrs.delete('name')
         component_file = find_component_file(component_name)
 
+        named = parse_named_slots(slot_content)
         id = jobs.length
         jobs << {
           'id' => id,
           'componentFile' => component_file || '',
           'props' => attrs,
-          'slotHtml' => slot_content ? markdown_to_html(slot_content.strip) : ''
+          'slotHtml' => named.any? ? '' : (slot_content ? markdown_to_html(slot_content.strip) : ''),
+          'namedSlots' => named,
+          'nodeModulesDir' => node_modules_dir_for(component_file)
         }
 
         "<!-- sakusei-vue-#{id} -->"
@@ -95,7 +117,8 @@ module Sakusei
 
     # Send all jobs to Node.js in one call via stdin/stdout.
     def render_batch(jobs)
-      stdout, stderr, status = Open3.capture3('node', vue_renderer_script, stdin_data: jobs.to_json)
+      env = renderer_env
+      stdout, stderr, status = Open3.capture3(env, 'node', vue_renderer_script, stdin_data: jobs.to_json)
       raise Error, "Vue renderer failed: #{stderr.strip}" unless status.success?
 
       JSON.parse(stdout)
@@ -103,13 +126,41 @@ module Sakusei
       raise Error, "Vue renderer returned invalid JSON: #{e.message}"
     end
 
+    def renderer_env
+      env = {}
+      if @style_pack
+        nm = File.join(@style_pack.path, 'node_modules')
+        env['NODE_PATH'] = nm if Dir.exist?(nm)
+      end
+      env
+    end
+
+    def node_modules_dir_for(component_file)
+      return nil if component_file.nil? || component_file.empty?
+
+      if @style_pack&.components_dir && component_file.start_with?(@style_pack.components_dir)
+        File.join(@style_pack.path, 'node_modules')
+      else
+        local_nm = File.join(@base_dir, 'node_modules')
+        Dir.exist?(local_nm) ? local_nm : nil
+      end
+    end
+
     def find_component_file(name)
-      possible_paths = [
+      local_paths = [
         File.join(@base_dir, 'components', "#{name}.vue"),
         File.join(@base_dir, "#{name}.vue"),
         File.join(@base_dir, 'vue_components', "#{name}.vue")
       ]
-      possible_paths.find { |p| File.exist?(p) }
+      local = local_paths.find { |p| File.exist?(p) }
+      return local if local
+
+      if @style_pack&.components_dir
+        pack_file = File.join(@style_pack.components_dir, "#{name}.vue")
+        return pack_file if File.exist?(pack_file)
+      end
+
+      nil
     end
 
     def vue_renderer_script
@@ -129,6 +180,42 @@ module Sakusei
       attrs
     end
 
+    def style_pack_needs_install?(style_pack)
+      return false unless style_pack&.components_dir
+      return false unless File.exist?(File.join(style_pack.path, 'package.json'))
+      !Dir.exist?(File.join(style_pack.path, 'node_modules'))
+    end
+
+    def ensure_style_pack_deps_installed
+      return unless style_pack_needs_install?(@style_pack)
+      $stderr.puts "Installing style pack dependencies for '#{@style_pack.name}'..."
+      result = system('npm', 'install', '--prefix', @style_pack.path)
+      raise Error, "npm install failed for style pack '#{@style_pack.name}'. Check #{@style_pack.path}." unless result
+    end
+
+    # Wrap a markdown heading immediately before a placeholder in a keep-together div.
+    # Converts the heading to HTML so marked doesn't process it inside the div block.
+    def wrap_headings_with_placeholders(content)
+      content.gsub(/^([#]{1,6}) ([^\n]+)\n+(<!-- sakusei-vue-\d+ -->)/) do
+        level = Regexp.last_match(1).length
+        text  = Regexp.last_match(2).strip
+        placeholder = Regexp.last_match(3)
+        "<div class=\"kdc-section\">\n<h#{level}>#{text}</h#{level}>\n\n#{placeholder}\n\n</div>"
+      end
+    end
+
+    # Extract <template #slotname>...</template> sections and convert their markdown to HTML.
+    # Returns a hash of { slot_name => html }. Empty hash if no named slots found.
+    def parse_named_slots(content)
+      return {} unless content
+
+      slots = {}
+      content.scan(/<template\s+#(\w+)>(.*?)<\/template>/m) do |name, slot_md|
+        slots[name] = markdown_to_html(slot_md.strip)
+      end
+      slots
+    end
+
     def markdown_to_html(markdown)
       return '' if markdown.nil? || markdown.empty?
 

data/lib/sakusei/vue_renderer.js

@@ -52,14 +52,18 @@ function esmToCjs(code) {
 }
 
 // Execute compiled CJS module code and return its exports
-function executeModule(code, filePath) {
+function executeModule(code, filePath, nodeModulesDir) {
   const patchedRequire = (id) => {
     if (id.endsWith('.vue')) {
       // Handle both relative and absolute .vue imports
       const abs = path.isAbsolute(id) ? id : path.resolve(path.dirname(filePath), id)
       const compiled = compiledCache.get(abs)
       if (!compiled) throw new Error(`Component not pre-compiled: ${abs}`)
-      return executeModule(compiled.code, abs)
+      return executeModule(compiled.code, abs, nodeModulesDir)
+    }
+    if (nodeModulesDir) {
+      const customRequire = Module.createRequire(path.join(nodeModulesDir, '_'))
+      return customRequire(id)
     }
     // Use the renderer's own require so CWD node_modules are on the search path
     return require(id)
@@ -146,7 +150,7 @@ async function preCompileImports(filePath, visited = new Set()) {
 
 // Compile and render a single job, injecting slotHtml at the template level
 async function renderJob(job) {
-  const { id, componentFile, props, slotHtml } = job
+  const { id, componentFile, props, slotHtml, namedSlots, nodeModulesDir } = job
 
   if (!componentFile || !fs.existsSync(componentFile)) {
     return { id, html: `<!-- Vue component not found: ${path.basename(componentFile || 'unknown')} -->`, css: '' }
@@ -161,8 +165,9 @@ async function renderJob(job) {
 
     let finalCode = base.code
 
-    // If slot content provided, recompile template with slot injected
-    if (slotHtml) {
+    // Recompile template with slot content injected (default and/or named slots)
+    const hasNamedSlots = namedSlots && Object.keys(namedSlots).length > 0
+    if (slotHtml || hasNamedSlots) {
       const source = fs.readFileSync(componentFile, 'utf-8')
       const { descriptor } = parse(source, { filename: componentFile })
       const idHash = crypto.createHash('md5').update(componentFile).digest('hex').slice(0, 8)
@@ -176,9 +181,23 @@ async function renderJob(job) {
         bindings = scriptResult.bindings
       }
 
-      const templateSource = (descriptor.template ? descriptor.template.content : '<div></div>')
-        .replace(/<slot\s*\/>/g, slotHtml)
-        .replace(/<slot>\s*<\/slot>/g, slotHtml)
+      let templateSource = descriptor.template ? descriptor.template.content : '<div></div>'
+
+      // Inject named slots: replace <slot name="X" /> and <slot name="X"></slot>
+      if (hasNamedSlots) {
+        for (const [name, html] of Object.entries(namedSlots)) {
+          templateSource = templateSource
+            .replace(new RegExp(`<slot\\s+name=["']${name}["']\\s*/>`, 'g'), html)
+            .replace(new RegExp(`<slot\\s+name=["']${name}["']>\\s*</slot>`, 'g'), html)
+        }
+      }
+
+      // Inject default slot
+      if (slotHtml) {
+        templateSource = templateSource
+          .replace(/<slot\s*\/>/g, slotHtml)
+          .replace(/<slot>\s*<\/slot>/g, slotHtml)
+      }
 
       const templateResult = compileTemplate({
         source: templateSource,
@@ -192,8 +211,17 @@ async function renderJob(job) {
       finalCode = `${scriptCode}\n${renderCode}\n__component__.ssrRender = ssrRender;\nmodule.exports = __component__;`
     }
 
-    const component = executeModule(finalCode, componentFile)
-    const app = createSSRApp(component, props)
+    const component = executeModule(finalCode, componentFile, nodeModulesDir)
+    // Auto-parse JSON-encoded prop values (arrays and objects passed as strings)
+    const parsedProps = {}
+    for (const [k, v] of Object.entries(props)) {
+      if (typeof v === 'string' && (v.startsWith('[') || v.startsWith('{'))) {
+        try { parsedProps[k] = JSON.parse(v) } catch { parsedProps[k] = v }
+      } else {
+        parsedProps[k] = v
+      }
+    }
+    const app = createSSRApp(component, parsedProps)
     const html = await renderToString(app)
 
     return { id, html, css: base.css || '' }

data/lib/templates/default_style_pack/.gitignore

@@ -0,0 +1 @@
+node_modules/

data/lib/templates/default_style_pack/components/HelloWorld.vue

@@ -0,0 +1,30 @@
+<docs>
+A simple greeting component. Replace or delete this example.
+
+Props:
+- name (optional): Name to greet. Defaults to "World".
+</docs>
+
+<template>
+  <div class="hello-world">
+    <p>Hello, {{ name }}!</p>
+  </div>
+</template>
+
+<script setup>
+const props = defineProps({
+  name: {
+    type: String,
+    default: 'World'
+  }
+})
+</script>
+
+<style scoped>
+.hello-world {
+  padding: 0.5em;
+  border: 1px solid #ccc;
+  border-radius: 4px;
+  display: inline-block;
+}
+</style>

data/lib/templates/default_style_pack/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "sakusei-style-pack",
+  "version": "1.0.0",
+  "private": true,
+  "dependencies": {
+    "@vue/compiler-sfc": "^3.5.0",
+    "@vue/server-renderer": "^3.5.0",
+    "vue": "^3.5.0"
+  }
+}

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sakusei
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Keith Rowell
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-27 00:00:00.000000000 Z
+date: 2026-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: thor
@@ -85,6 +85,8 @@ files:
 - lib/sakusei/cli.rb
 - lib/sakusei/erb_processor.rb
 - lib/sakusei/file_resolver.rb
+- lib/sakusei/heading_wrapper.rb
+- lib/sakusei/image_path_resolver.rb
 - lib/sakusei/md_to_pdf_converter.rb
 - lib/sakusei/multi_file_builder.rb
 - lib/sakusei/pdf_concat.rb
@@ -94,9 +96,12 @@ files:
 - lib/sakusei/vue_processor.rb
 - lib/sakusei/vue_renderer.js
 - lib/templates/base.css
+- lib/templates/default_style_pack/.gitignore
+- lib/templates/default_style_pack/components/HelloWorld.vue
 - lib/templates/default_style_pack/config.js
 - lib/templates/default_style_pack/footer.html
 - lib/templates/default_style_pack/header.html
+- lib/templates/default_style_pack/package.json
 - lib/templates/default_style_pack/style.css
 - sakusei.gemspec
 homepage: https://github.com/keithrowell/sakusei