ucode 0.1.1 → 0.2.1

data/lib/ucode/code_chart/extractor.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+require "ucode/error"
+require "ucode/glyphs/embedded_fonts/catalog"
+require "ucode/glyphs/embedded_fonts/renderer"
+require "ucode/glyphs/embedded_fonts/source"
+require "ucode/glyphs/resolver"
+require "ucode/glyphs/sources/pillar1_embedded_tounicode"
+require "ucode/glyphs/sources/tier1_real_font"
+
+module Ucode
+  module CodeChart
+    # Walks every assigned codepoint in a block and returns one
+    # {Result} per codepoint that any tier produced a glyph for.
+    #
+    # This is **not** a new extraction pipeline — it composes the
+    # existing {Ucode::Glyphs::Resolver} with per-block inputs
+    # (the block's Code Charts PDF + optionally Tier 1 and Pillar 3
+    # sources). The Resolver owns tier selection; the Extractor owns
+    # inputs.
+    #
+    # The REQ (R2) describes extraction via "locate the grid cell
+    # whose margin label matches the codepoint" — that was the v0.1
+    # retired approach (cell-border compositing). The current path
+    # is the embedded-font walk (Pillar 1, via {EmbeddedFonts::Catalog})
+    # with Pillar 2 (positional correlation) and Pillar 3 (Last Resort
+    # placeholders) as fallbacks.
+    #
+    # ## Tier selection
+    #
+    # Pillar 1 is always configured (the embedded font walk over the
+    # block's PDF). Tier 1 (real-font cmap) and Pillar 3 (Last
+    # Resort) are optional — the caller injects pre-built sources.
+    # This avoids forcing the Extractor to construct Last Resort
+    # eagerly, which would fail in environments where the UFO is
+    # not checked out.
+    class Extractor
+      # Result of extracting one codepoint.
+      Result = Struct.new(:codepoint, :svg, :tier, :provenance, keyword_init: true)
+
+      # @param block [Ucode::Models::Block] block whose assigned
+      #   codepoints will be extracted
+      # @param pdf_path [Pathname, String] path to the per-block
+      #   Code Charts PDF (downloaded by the caller; the Extractor
+      #   doesn't fetch)
+      # @param cache_dir [Pathname, String, nil] directory for
+      #   cached extracted font streams. nil = default
+      #   (data/pdf-fonts/ relative to the gem root).
+      # @param tier1_sources [Array<Ucode::Glyphs::Source>, nil]
+      #   optional Tier 1 sources (real-font cmap). nil = no Tier 1
+      # @param pillar3_source [Ucode::Glyphs::Source, nil] optional
+      #   Pillar 3 (Last Resort) source. nil = no Pillar 3 fallback.
+      #   Callers that want Last Resort placeholders inject the
+      #   pre-built source here.
+      def initialize(block:, pdf_path:, cache_dir: nil,
+                     tier1_sources: nil, pillar3_source: nil)
+        @block = block
+        @pdf_path = Pathname.new(pdf_path)
+        @cache_dir = cache_dir && Pathname.new(cache_dir)
+        @tier1_sources = tier1_sources || []
+        @pillar3_source = pillar3_source
+      end
+
+      # @return [Array<Result>] one Result per codepoint that any
+      #   tier produced a glyph for. Codepoints no tier can serve
+      #   are silently skipped (no Result yielded).
+      def extract
+        resolver = build_resolver
+        results = []
+        each_codepoint do |cp|
+          resolver_result = resolver.resolve(cp)
+          next unless resolver_result&.svg
+
+          results << Result.new(
+            codepoint: cp,
+            svg: resolver_result.svg,
+            tier: resolver_result.tier,
+            provenance: resolver_result.provenance,
+          )
+        end
+        results
+      end
+
+      private
+
+      # Yields every codepoint in the block's range in ascending
+      # order. We yield the whole range because the Resolver's
+      # tiers handle unassigned codepoints — Pillar 3 (when
+      # configured) maps every codepoint via its Format 13 cmap,
+      # so unassigned slots get a placeholder. With no Pillar 3
+      # injected, only assigned codepoints (those the embedded
+      # font actually covers) yield Results; the rest are silently
+      # skipped, satisfying the REQ's "skip unassigned codepoints".
+      def each_codepoint
+        return enum_for(:each_codepoint) unless block_given?
+
+        (@block.range_first..@block.range_last).each do |cp|
+          yield cp
+        end
+      end
+
+      def build_resolver
+        sources = @tier1_sources.dup
+        sources.concat(embedded_pillar_sources)
+        sources << @pillar3_source if @pillar3_source
+        order = sources.map(&:tier).uniq
+        Glyphs::Resolver.new(sources: sources, order: order)
+      end
+
+      def embedded_pillar_sources
+        embedded_source = Glyphs::EmbeddedFonts::Source.new(
+          pdf: @pdf_path, cache_dir: @cache_dir,
+        )
+        catalog = Glyphs::EmbeddedFonts::Catalog.new(embedded_source)
+        renderer = Glyphs::EmbeddedFonts::Renderer.new(catalog)
+        [Glyphs::Sources::Pillar1EmbeddedTounicode.new(renderer: renderer)]
+      end
+    end
+  end
+end

data/lib/ucode/code_chart/provenance.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "digest"
+require "time"
+
+require "ucode/version"
+
+module Ucode
+  module CodeChart
+    # Per-codepoint provenance value object — every field the REQ
+    # (R5) requires in the sidecar JSON next to each extracted SVG.
+    #
+    # Single source of truth for the provenance schema: the
+    # {Sidecar} writer reads this Struct, the Writer constructs it.
+    # Adding a field is one place to change.
+    #
+    # `extractor_version` reads from `Ucode::VERSION` at construction
+    # so the field stays in sync with the gem's version bump — single
+    # source of truth.
+    #
+    # `extracted_at` is the extraction event timestamp (UTC ISO8601),
+    # not the file-write timestamp.
+    Provenance = Struct.new(
+      :codepoint,
+      :block,
+      :source_pdf_url,
+      :source_pdf_sha256,
+      :ucd_version,
+      :extracted_at,
+      :extractor_version,
+      keyword_init: true,
+    )
+
+    # Computes the source PDF's URL from a block name and first
+    # codepoint. Mirrors the per-block URL convention in
+    # {Ucode::Fetch::CodeCharts}: 4-digit hex for BMP, 6-digit for
+    # supplementary planes.
+    #
+    # @param block_first_cp [Integer]
+    # @return [String]
+    def self.code_chart_url(block_first_cp)
+      width = block_first_cp > 0xFFFF ? 6 : 4
+      slug = block_first_cp.to_s(16).upcase.rjust(width, "0")
+      "#{Ucode.configuration.charts_base_url}/U#{slug}.pdf"
+    end
+
+    # Builds a Provenance from the inputs the {Writer} has on hand
+    # (block, codepoint, ucd_version, pdf_path). Computes the PDF
+    # hash + URL once. The `extracted_at` timestamp is fixed at
+    # call time so re-running the same block produces identical
+    # provenance JSON for unchanged codepoints.
+    #
+    # @param block [Ucode::Models::Block]
+    # @param codepoint [Integer]
+    # @param ucd_version [String]
+    # @param pdf_path [Pathname, String]
+    # @param now [Time, nil] override for tests
+    # @return [Provenance]
+    def self.build(block:, codepoint:, ucd_version:, pdf_path:, now: nil)
+      path = Pathname.new(pdf_path)
+      Provenance.new(
+        codepoint: format("U+%04X", codepoint),
+        block: block.id,
+        source_pdf_url: code_chart_url(block.range_first),
+        source_pdf_sha256: sha256_of(path),
+        ucd_version: ucd_version,
+        extracted_at: (now || Time.now.utc).iso8601,
+        extractor_version: Ucode::VERSION,
+      )
+    end
+
+    # @param path [Pathname]
+    # @return [String] hex digest, "" when the path doesn't exist
+    #   (callers can decide how to handle a missing hash)
+    def self.sha256_of(path)
+      return "" unless path.exist?
+
+      Digest::SHA256.file(path).hexdigest
+    end
+  end
+end

data/lib/ucode/code_chart/sidecar.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+require "ucode/repo/atomic_writes"
+
+module Ucode
+  module CodeChart
+    # Writes a {Provenance} to disk as the sidecar JSON next to its
+    # corresponding SVG.
+    #
+    # Path: `<output_root>/<codepoint>.json` — colocated with the
+    # SVG so a downstream consumer can find both files by a single
+    # directory listing.
+    #
+    # Idempotent via {Ucode::Repo::AtomicWrites#write_atomic}: a
+    # re-write of byte-identical content is a no-op (no temp-file
+    # rename). Provenance JSON is canonical (sorted keys via Ruby's
+    # stdlib JSON), so the byte-equality test is sound.
+    class Sidecar
+      include Ucode::Repo::AtomicWrites
+
+      # @param output_root [Pathname, String] directory the SVG +
+      #   sidecar live in. Parent directories are created on demand.
+      def initialize(output_root:)
+        @output_root = Pathname.new(output_root)
+      end
+
+      # @param provenance [Ucode::CodeChart::Provenance]
+      # @return [Pathname] the written sidecar path
+      def write(provenance)
+        path = path_for(provenance)
+        payload = JSON.pretty_generate(provenance.to_h) + "\n"
+        write_atomic(path, payload)
+        path
+      end
+
+      # @param codepoint_id [String] e.g. "U+10920"
+      # @return [Pathname] the would-be path for a sidecar
+      def path_for_id(codepoint_id)
+        @output_root.join("#{codepoint_id}.json")
+      end
+
+      private
+
+      def path_for(provenance)
+        path_for_id(provenance.codepoint)
+      end
+    end
+  end
+end

data/lib/ucode/code_chart/writer.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+require "digest"
+require "pathname"
+
+require "ucode/code_chart/extractor"
+require "ucode/code_chart/provenance"
+require "ucode/code_chart/sidecar"
+require "ucode/error"
+require "ucode/version_resolver"
+
+module Ucode
+  module CodeChart
+    # Orchestrates extraction + provenance sidecar writing for one
+    # block. The Writer is the **only thing that touches disk** in the
+    # CodeChart namespace; everything else is composition.
+    #
+    # Output layout (per block):
+    #
+    #     <output_root>/<block_id>/<U+XXXX>.svg
+    #     <output_root>/<block_id>/<U+XXXX>.json   # provenance sidecar
+    #
+    # One folder per block keeps each block's output self-contained
+    # and discoverable — a downstream consumer (fontisan) can iterate
+    # a block's folder without scanning the whole tree.
+    #
+    # Idempotent: re-running `write` on the same inputs produces
+    # byte-identical files (SVGs via content check; sidecars via
+    # {Ucode::Repo::AtomicWrites#write_atomic}'s canonical-JSON
+    # byte-equality). The {Summary} tally distinguishes "first run"
+    # writes from no-op re-writes.
+    class Writer
+      # Per-block run summary. Returned from {#write}.
+      Summary = Struct.new(
+        :block,
+        :codepoints_extracted,
+        :svgs_written,
+        :sidecars_written,
+        :pdf_sha256,
+        keyword_init: true,
+      )
+
+      # @param output_root [Pathname, String] parent directory. The
+      #   `<block_id>/` subdirectory is created inside it.
+      # @param pdf_path [Pathname, String] Code Charts PDF (already
+      #   downloaded by the caller; Writer doesn't fetch).
+      # @param ucd_version [String, nil] UCD version to stamp on
+      #   provenance. nil = resolved via {VersionResolver.resolve(nil)}.
+      # @param cache_dir [Pathname, String, nil] font-stream cache
+      #   directory for the EmbeddedFonts::Source.
+      # @param now [Time, nil] timestamp override (for tests).
+      # @param pillar3_source, tier1_sources: forwarded to the Extractor.
+      def initialize(output_root:, pdf_path:, ucd_version: nil,
+                     cache_dir: nil, now: nil,
+                     pillar3_source: nil, tier1_sources: nil)
+        @output_root = Pathname.new(output_root)
+        @pdf_path = Pathname.new(pdf_path)
+        @ucd_version = ucd_version || VersionResolver.resolve(nil)
+        @cache_dir = cache_dir && Pathname.new(cache_dir)
+        @now = now
+        @pillar3_source = pillar3_source
+        @tier1_sources = tier1_sources
+      end
+
+      # Extracts every codepoint in `block` and writes `<block_id>/<cp>.svg`
+      # + `<block_id>/<cp>.json` under `@output_root`. Returns a
+      # {Summary} tally.
+      #
+      # @param block [Ucode::Models::Block]
+      # @return [Summary]
+      def write(block)
+        block_dir = @output_root.join(block.id)
+        block_dir.mkpath
+
+        pdf_sha = CodeChart.sha256_of(@pdf_path)
+
+        sidecar = Sidecar.new(output_root: block_dir)
+        extractor = Extractor.new(
+          block: block,
+          pdf_path: @pdf_path,
+          cache_dir: @cache_dir,
+          pillar3_source: @pillar3_source,
+          tier1_sources: @tier1_sources,
+        )
+
+        results = extractor.extract
+        svgs = 0
+        sidecars = 0
+        results.each do |result|
+          write_svg(block_dir, result)
+          svgs += 1
+          provenance = CodeChart.build(
+            block: block, codepoint: result.codepoint,
+            ucd_version: @ucd_version, pdf_path: @pdf_path,
+            now: @now,
+          )
+          sidecar.write(provenance)
+          sidecars += 1
+        end
+
+        Summary.new(
+          block: block.id,
+          codepoints_extracted: results.size,
+          svgs_written: svgs,
+          sidecars_written: sidecars,
+          pdf_sha256: pdf_sha,
+        )
+      end
+
+      private
+
+      # Writes one SVG, skipping the write when the existing content
+      # is byte-identical (so mtime is preserved on idempotent
+      # re-runs — the Sidecar uses `Repo::AtomicWrites` for the same
+      # reason but at a different layer).
+      def write_svg(block_dir, result)
+        path = block_dir.join("#{format_cp(result.codepoint)}.svg")
+        return if path.exist? && path.read == result.svg
+
+        path.write(result.svg)
+      end
+
+      def format_cp(codepoint)
+        "U+#{codepoint.to_s(16).upcase.rjust(4, '0')}"
+      end
+    end
+  end
+end

data/lib/ucode/code_chart.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Ucode
+  # CodeChart — per-codepoint SVG glyph extraction from Unicode Code
+  # Charts PDFs.
+  #
+  # The "Code Chart donor" use case (essenfont consumer): for blocks
+  # where no OFL real-font covers the glyphs (Sidetic in Unicode 17,
+  # Egyptian Hieroglyphs Extended-B), the only canonical source is
+  # the Unicode Consortium's Code Chart PDF. This namespace turns one
+  # such PDF into a tree of standalone SVG files plus provenance
+  # sidecar JSON.
+  #
+  # ## Architecture (MECE)
+  #
+  # Every concern has exactly one home:
+  #
+  #   * **Block metadata** (range + assigned codepoints) — Parsers::Blocks
+  #   * **PDF download + cache** — Fetch::CodeCharts + Glyphs::PdfFetcher
+  #   * **PDF object-graph walk + font extraction** — Glyphs::EmbeddedFonts::*
+  #   * **Tier selection (Pillar 1 / 2 / 3)** — Glyphs::Resolver
+  #   * **SVG conversion + y-flip + viewBox** — Glyphs::EmbeddedFonts::Svg
+  #   * **Provenance schema** — CodeChart::Provenance (this namespace)
+  #   * **Sidecar JSON write** — CodeChart::Sidecar (this namespace)
+  #   * **Per-block orchestration + idempotent disk write** — CodeChart::Writer
+  #   * **CLI dispatch** — Cli::CodeChartCmd
+  #
+  # CodeChart::* is the feature-facing namespace. It does not
+  # implement extraction, font parsing, or PDF I/O — it composes
+  # the existing infrastructure. Replacing the implementation
+  # (e.g. a future pure-Ruby PDF parser per ADR-0001) does not
+  # change the public API.
+  module CodeChart
+    autoload :Extractor, "ucode/code_chart/extractor"
+    autoload :Provenance, "ucode/code_chart/provenance"
+    autoload :Sidecar, "ucode/code_chart/sidecar"
+    autoload :Writer, "ucode/code_chart/writer"
+  end
+end

data/lib/ucode/commands/audit.rb

@@ -14,7 +14,6 @@ module Ucode
       autoload :LibraryCommand,    "ucode/commands/audit/library_command"
       autoload :CompareCommand,    "ucode/commands/audit/compare_command"
       autoload :BrowserCommand,    "ucode/commands/audit/browser_command"
-      autoload :ReferenceBuilder,  "ucode/commands/audit/reference_builder"
     end
   end
 end

data/lib/ucode/commands/build.rb

@@ -11,6 +11,10 @@ module Ucode
     # parse → (optional) glyphs → (optional) site. Resumable: each step
     # is idempotent and safe to re-run.
     #
+    # Resolves the version intent once at the top and threads the
+    # resolved string through every sub-command. See Candidate 4 of the
+    # 2026-06-29 architecture review.
+    #
     # **Glyph step is opt-in as of v0.1** because the SVG cell extractor
     # is still experimental. Pass `include_glyphs: true` to enable it;
     # otherwise the glyphs step is recorded as skipped.

data/lib/ucode/commands/canonical_build.rb

@@ -39,7 +39,7 @@ module Ucode
     # Missing pre-conditions cause silent fallthrough to lower tiers;
     # the build report's `by_tier` totals surface what ran.
     class CanonicalBuildCommand
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param output_root [String, Pathname]
       # @param source_config_path [String, Pathname, nil] override the
       #   Tier 1 font config YAML; nil uses the default
@@ -54,9 +54,8 @@ module Ucode
       #   true. nil skips the block_coverage check.
       # @return [Hash] { version:, codepoint_count:, report_path:,
       #   validation_report_path:, validation_passed: }
-      def call(version_intent, output_root:, source_config_path: nil,
+      def call(version, output_root:, source_config_path: nil,
                resolver: nil, validate: true, baseline: nil)
-        version = VersionResolver.resolve(version_intent)
         root = Pathname.new(output_root)
 
         resolved_resolver = resolver || build_resolver(version, source_config_path)

data/lib/ucode/commands/fetch.rb

@@ -5,7 +5,7 @@ require "pathname"
 require "ucode/cache"
 require "ucode/fetch"
 require "ucode/glyphs/source_config"
-require "ucode/version_resolver"
+require "ucode/parsers"
 
 module Ucode
   module Commands
@@ -13,40 +13,38 @@ module Ucode
     # per-version cache, plus the specialist Tier 1 fonts referenced by
     # the curated source config.
     #
-    # Thin shell over `Ucode::Fetch::*`. The command layer's job is to
-    # resolve the version intent and format the result; the fetcher does
-    # the network I/O.
+    # Thin shell over `Ucode::Fetch::*`. The command takes a resolved
+    # version string; CLI callers resolve via {VersionResolver.resolve}
+    # once and thread it through. See Candidate 4 of the 2026-06-29
+    # architecture review.
     class FetchCommand
       DEFAULT_SPECIALIST_FONTS_MANIFEST =
         Ucode::Glyphs::SourceConfig::DEFAULT_PATH.dirname.join("specialist_fonts.yml")
       private_constant :DEFAULT_SPECIALIST_FONTS_MANIFEST
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param force [Boolean]
       # @return [Hash] { version:, ucd_dir: }
-      def fetch_ucd(version_intent, force: false)
-        version = VersionResolver.resolve(version_intent)
+      def fetch_ucd(version, force: false)
         Cache.ensure_version_dir!(version)
         path = Fetch::UcdZip.call(version, force: force)
         { version: version, ucd_dir: path }
       end
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param force [Boolean]
       # @return [Hash] { version:, unihan_dir: }
-      def fetch_unihan(version_intent, force: false)
-        version = VersionResolver.resolve(version_intent)
+      def fetch_unihan(version, force: false)
         Cache.ensure_version_dir!(version)
         path = Fetch::UnihanZip.call(version, force: force)
         { version: version, unihan_dir: path }
       end
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param block_first_cps [Array<Integer>, nil] nil = all known blocks
       # @param force [Boolean]
       # @return [Hash] { version:, downloaded: }
-      def fetch_charts(version_intent, block_first_cps: nil, force: false)
-        version = VersionResolver.resolve(version_intent)
+      def fetch_charts(version, block_first_cps: nil, force: false)
         Cache.ensure_version_dir!(version)
 
         cps = block_first_cps || default_block_first_cps(version)
@@ -95,4 +93,4 @@ module Ucode
       end
     end
   end
-end
+end

data/lib/ucode/commands/glyphs.rb

@@ -1,19 +1,16 @@
 # frozen_string_literal: true
 
 require "pathname"
-require "set"
 
-require "ucode/cache"
 require "ucode/glyphs"
-require "ucode/parsers"
-require "ucode/version_resolver"
 
 module Ucode
   module Commands
     # `ucode glyphs` — extract per-codepoint SVGs from Code Charts PDFs.
-    # Builds block specs from the cached Blocks.txt + per-block PDFs (or
-    # monolith fallback), then drains them through the Glyphs::Writer
-    # worker pool.
+    # Thin Thor-facing wrapper around {Ucode::Glyphs::Pipeline}:
+    # opt-in gate + experimental warning live here; the pipeline
+    # assembly (block loading, fetcher, per-block specs) lives in
+    # {Ucode::Glyphs::Pipeline}.
     #
     # **Status (v0.1): EXPERIMENTAL.** The cell-extraction pipeline
     # currently includes cell-border decorations alongside the actual
@@ -23,16 +20,16 @@ module Ucode
     # pipeline can be iterated on without churning the CLI surface, but
     # callers MUST opt in via `include_glyphs: true` (CLI: `--include-glyphs`)
     # and will receive a printed warning. Tracked for v0.2.
+    #
+    # Takes a resolved version string; CLI callers resolve via
+    # {VersionResolver.resolve} once and thread it through. See
+    # Candidate 4 of the 2026-06-29 architecture review.
     class GlyphsCommand
       ExperimentalWarning = "ucode glyphs is experimental in v0.1: " \
                             "extracted SVGs include cell-border decorations " \
                             "alongside the character outline."
       private_constant :ExperimentalWarning
 
-      MonolithPath = "CodeCharts.pdf"
-      PageMapCache = "data/codecharts_page_map.json"
-      private_constant :MonolithPath, :PageMapCache
-
       class << self
         # @return [String] the experimental-status banner. Exposed so the
         #   CLI and BuildCommand surface the same message verbatim.
@@ -41,7 +38,7 @@ module Ucode
         end
       end
 
-      # @param version_intent [nil, :default, :latest, String]
+      # @param version [String] resolved UCD version
       # @param output_root [String, Pathname]
       # @param block_filter [Array<String>, nil] block ids to limit to;
       #   nil = every block
@@ -55,75 +52,36 @@ module Ucode
       #   written here exactly once before work begins.
       # @return [Hash] aggregated Writer tally + version, or a `skipped`
       #   payload when opt-in is false.
-      def call(version_intent, output_root:,
-               block_filter: nil, force: false, monolith_path: MonolithPath,
+      def call(version, output_root:,
+               block_filter: nil, force: false,
+               monolith_path: Glyphs::Pipeline::DEFAULT_MONOLITH_PATH,
                include_glyphs: false, warn: nil)
-        return skipped(version_intent) unless include_glyphs
+        return skipped(version) unless include_glyphs
 
         warn&.puts(ExperimentalWarning)
-        version = VersionResolver.resolve(version_intent)
-        root = Pathname.new(output_root)
 
-        blocks = load_blocks(version, block_filter)
-        fetcher = build_fetcher(version, monolith_path, blocks)
-        specs = blocks.map { |block| spec_for(block, fetcher, force) }.compact
+        pipeline = Glyphs::Pipeline.new(
+          version: version,
+          block_filter: block_filter,
+          monolith_path: monolith_path,
+        )
+        specs = pipeline.build_specs(force: force)
 
-        writer = Glyphs::Writer.new(output_root: root,
-                                     parallel_workers: workers)
+        writer = Glyphs::Writer.new(
+          output_root: Pathname.new(output_root),
+          parallel_workers: workers,
+        )
         tally = writer.write_all(specs)
         tally.merge(version: version, block_count: specs.size)
       end
 
       private
 
-      def load_blocks(version, block_filter)
-        ucd_dir = Cache.ucd_dir(version)
-        path = ucd_dir.join("Blocks.txt")
-        return [] unless path.exist?
-
-        all = Parsers::Blocks.each_record(path).to_a
-        return all unless block_filter && !block_filter.empty?
-
-        filter_set = block_filter.to_set
-        all.select { |block| filter_set.include?(block.id) }
-      end
-
-      def build_fetcher(version, monolith_path, blocks)
-        monolith = Pathname.new(monolith_path)
-        monolith = monolith.exist? ? monolith : nil
-        Glyphs::PdfFetcher.new(
-          version,
-          monolith_path: monolith,
-          blocks: blocks,
-          page_map_cache: PageMapCache,
-        )
-      end
-
-      def spec_for(block, fetcher, force)
-        pdf_path = fetcher.fetch(block_first_cp: block.range_first, force: force)
-        return nil unless pdf_path
-
-        { block: block, pdf_path: pdf_path, page_map: page_map_for(block) }
-      end
-
-      # Heuristic page map: per-block PDFs are page 1 = title, page 2 =
-      # first chart page starting at the block's first codepoint. True for
-      # most BMP blocks; multi-page blocks (CJK) need a richer resolver.
-      # Mismatches yield placeholder SVGs only — never wrong glyphs.
-      def page_map_for(block)
-        { 2 => block.range_first }
-      end
-
       def workers
         Ucode.configuration.parallel_workers
       end
 
-      def skipped(version_intent)
-        version = begin
-          VersionResolver.resolve(version_intent)
-        rescue UnknownVersionError
-          version_intent
-        end
+      def skipped(version)
         {
           version: version,
           skipped: true,
@@ -133,4 +91,4 @@ module Ucode
       end
     end
   end
-end
+end