fontico 0.1.0

data/lib/fontico/node_runner.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "fileutils"
+
+module Fontico
+  # Font assembly needs a toolchain the sprite does not. It is installed on
+  # demand into a cache directory and never touched unless a font target is
+  # actually built, so `targets: [sprite]` stays pure Ruby with no node at all.
+  class NodeRunner
+    class MissingNode < Fontico::Error; end
+    class ScriptFailed < Fontico::Error; end
+
+    SCRIPTS = File.expand_path("node", __dir__)
+
+    def initialize(cache_dir: nil)
+      @cache = cache_dir || File.join(Dir.home, ".cache", "fontico", "toolchain")
+    end
+
+    def available? = !which("node").nil?
+
+    def run(script, payload)
+      ensure_toolchain!
+      # Run from inside the cache: ESM resolves bare imports by walking up
+      # from the script's own directory, and ignores NODE_PATH entirely.
+      path = File.join(@cache, script)
+
+      out, err, status = Open3.capture3(
+        which("node"), path, stdin_data: JSON.dump(payload), chdir: @cache
+      )
+      raise ScriptFailed, "#{script}: #{err.strip.empty? ? "exited #{status.exitstatus}" : err.strip}" unless status.success?
+
+      JSON.parse(out)
+    end
+
+    private
+
+    def ensure_toolchain!
+      raise MissingNode, <<~MSG unless available?
+        Building a font target needs Node.js, which was not found on PATH.
+
+        The sprite target has no such requirement — remove `ttf` from
+        `targets:` in your manifest to build without it.
+      MSG
+
+      FileUtils.mkdir_p(@cache)
+      Dir[File.join(SCRIPTS, "*.mjs")].each { FileUtils.cp(_1, @cache) }
+      return if File.directory?(File.join(@cache, "node_modules"))
+
+      FileUtils.cp(File.join(SCRIPTS, "package.json"), @cache)
+      _, err, status = Open3.capture3(
+        which("npm"), "install", "--silent", "--no-audit", "--no-fund", chdir: @cache
+      )
+      raise ScriptFailed, "installing font toolchain into #{@cache}: #{err}" unless status.success?
+    end
+
+    def which(cmd)
+      ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).each do |dir|
+        exe = File.join(dir, cmd)
+        return exe if File.executable?(exe) && !File.directory?(exe)
+      end
+      nil
+    end
+  end
+end

data/lib/fontico/outliner.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Fontico
+  # Decides where each icon's *filled outline* comes from, which is the whole
+  # difficulty of the font target.
+  #
+  #   :fill    already filled geometry — used as-is (Material Symbols, flat
+  #            first-party exports, most Iconify sets)
+  #   :glyph   stroke-based, but the provider ships a font whose glyphs are
+  #            already expanded — extracted from there, losslessly (Lucide)
+  #   :none    stroke-based with no provider font — refused, loudly
+  #
+  # There is deliberately no raster-trace fallback. Both published JS
+  # expanders (svg-outline-stroke, oslllo-svg-fixer) run the artwork through
+  # potrace; corners round off and strokes wobble. Refusing beats shipping
+  # geometry that quietly stopped matching the sprite.
+  class Outliner
+    Unsupported = Class.new(Fontico::Error)
+
+    def initialize(runner: NodeRunner.new, cache_dir: nil)
+      @runner = runner
+      @cache = cache_dir || File.join(Dir.home, ".cache", "fontico", "fonts")
+    end
+
+    def self.stroke_based?(body)
+      body.match?(/stroke\s*=\s*['"](?!none)/) || body.match?(/stroke\s*:\s*(?!none)/)
+    end
+
+    def strategy_for(icon, body)
+      return :fill unless self.class.stroke_based?(body)
+      return :glyph if ProviderFonts.available?(icon.provider)
+
+      :none
+    end
+
+    # => { icon_name => path_data } for every :glyph icon, batched per provider
+    # so each provider font is downloaded and parsed once.
+    def outlines(pairs, size: 24)
+      by_provider = pairs.select { |icon, body| strategy_for(icon, body) == :glyph }
+                         .group_by { |icon, _| icon.provider }
+      return {} if by_provider.empty?
+
+      FileUtils.mkdir_p(@cache)
+      by_provider.each_with_object({}) do |(provider, group), out|
+        font, codepoints = ProviderFonts.fetch(provider, cache_dir: @cache)
+        result = @runner.run("extract_glyphs.mjs", {
+          fontPath: font, codepointsPath: codepoints, size: size,
+          names: group.map { |icon, _| icon.slug }.uniq
+        })
+
+        if result["missing"]&.any?
+          raise Unsupported, "#{provider} font has no glyph for: #{result["missing"].join(", ")}"
+        end
+
+        group.each { |icon, _| out[icon.name] = result.dig("glyphs", icon.slug) }
+      end
+    end
+
+    def refuse(unsupported)
+      names = unsupported.map { "#{_1.name} (#{_1.source})" }
+      raise Unsupported, <<~MSG
+        #{unsupported.size} icon(s) are stroke-based and their provider ships no
+        font to take outlines from, so they cannot become glyphs:
+
+          #{names.join("\n  ")}
+
+        A stroked path does not fail loudly in a font — it fills its centreline
+        and produces a solid blob. Options:
+
+          * outline the strokes at source (Path > Stroke to Path) for local icons
+          * pick the filled variant of the icon from its provider
+          * drop `ttf` from targets: and use the sprite, which renders strokes natively
+
+        Providers with extractable fonts: #{ProviderFonts.known.join(", ")}
+      MSG
+    end
+  end
+end

data/lib/fontico/prawn.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Fontico
+  # Icons in generated PDFs, from the same manifest as the web sprite.
+  #
+  # This is what the TTF target is actually for. Prawn reads TTF/OTF through
+  # ttfunk and cannot read woff2, so TTF is the right container — it is not a
+  # web font, and at this icon count the sprite beats one on the web anyway.
+  #
+  #   require "fontico/prawn"
+  #
+  #   Prawn::Document.generate("out.pdf") do |pdf|
+  #     pdf.fontico!                        # register the family once
+  #     pdf.icon "save", size: 18
+  #     pdf.text "#{pdf.glyph("mail")} hello", inline_format: false
+  #   end
+  module Prawn
+    FAMILY = "Fontico"
+
+    module DocumentExtensions
+      # Registers the built TTF as a font family. Call once per document.
+      def fontico!(family: FAMILY, path: Fontico.font_file)
+        unless File.exist?(path)
+          raise Fontico::Error,
+                "#{path} does not exist — add `ttf` to targets: and run rake fontico:build"
+        end
+
+        font_families.update(family => { normal: path })
+        self
+      end
+
+      # The glyph character for +name+, for interpolating into a text run.
+      # Wrap the run in font(Fontico::Prawn::FAMILY) so it renders.
+      def glyph(name) = Fontico.glyph(name)
+
+      # Draws one icon. Colour and size come from Prawn, exactly like text,
+      # because a glyph *is* text.
+      def icon(name, size: font_size, color: nil, family: FAMILY, **options)
+        if Fontico.lockfile.multicolor?(name.to_s)
+          raise Fontico::Error,
+                "#{name} is multicolour and is not in the font. Draw it with " \
+                "prawn-svg from the sprite source instead."
+        end
+
+        previous = fill_color
+        fill_color(color) if color
+        font(family, size: size) { text(Fontico.glyph(name), **options) }
+        fill_color(previous) if color
+        self
+      end
+
+      # Same, positioned — for letterheads and table cells.
+      def icon_at(name, at:, size: font_size, family: FAMILY)
+        font(family, size: size) { draw_text(Fontico.glyph(name), at: at) }
+        self
+      end
+    end
+  end
+end
+
+require "prawn"
+Prawn::Document.include(Fontico::Prawn::DocumentExtensions)

data/lib/fontico/preprocessor.rb

@@ -0,0 +1,238 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+
+module Fontico
+  # Normalises one SVG into a body fragment that is safe to merge with any
+  # other. Implements docs/icon-authoring.html section 01.
+  #
+  # Vendor icons arrive uniform; first-party exports do not. Everything here
+  # exists because a real Inkscape or Illustrator export breaks it.
+  class Preprocessor
+    # Editor state, document furniture, and anything executable.
+    DROP_ELEMENTS = %w[
+      script metadata foreignObject sodipodi:namedview
+      title desc inkscape:templateinfo
+    ].freeze
+
+    # Attributes that never survive: editor namespaces and event handlers.
+    DROP_ATTR_PREFIXES = %w[sodipodi: inkscape: serif: xml:space].freeze
+
+    # Attributes whose value may contain url(#id) and must be rewritten
+    # alongside the ids themselves.
+    URL_ATTRS = %w[
+      fill stroke clip-path mask filter style
+      marker-start marker-mid marker-end
+    ].freeze
+
+    COLOR_ATTRS = %w[fill stroke stop-color].freeze
+
+    Result = Struct.new(:body, :width, :height, :warnings, :multicolor, keyword_init: true)
+
+    def initialize(icon, size: 24)
+      @icon = icon
+      @size = size
+      @warnings = []
+    end
+
+    # +source+ is a whole SVG document (local files) or a body fragment
+    # (Iconify, which returns inner markup only).
+    def call(source, width: nil, height: nil)
+      doc = REXML::Document.new(wrap(source, width, height))
+      root = doc.root
+
+      vb_w, vb_h, min_x, min_y = viewbox_of(root, width, height)
+
+      strip_comments!(root)
+      strip_elements!(root)
+      strip_attributes!(root)
+      namespace_ids!(root)
+
+      # The manifest stays one line per icon: multicolor is detected, not
+      # declared, unless the author overrides it explicitly.
+      multicolor = @icon.multicolor.nil? ? distinct_colors(root).size > 1 : @icon.multicolor?
+      fold_colors!(root) unless multicolor
+      flag_hard_failures!(root)
+
+      Result.new(
+        body: refit(inner_markup(root), vb_w, vb_h, min_x, min_y),
+        width: @size, height: @size, warnings: @warnings, multicolor: multicolor
+      )
+    end
+
+    private
+
+    # A fragment carries no viewBox, so the dimensions supplied out of band
+    # are the only record of the grid it was drawn on and have to go on the
+    # wrapper. Assuming @size here silently cropped every provider that is
+    # not 24: arcticons (48) shipped as its own top-left quarter, game-icons
+    # (512) as a near-empty corner. lucide is 24, which is why it never showed.
+    def wrap(source, width = nil, height = nil)
+      return source if source.lstrip.start_with?("<svg", "<?xml", "<!DOCTYPE")
+
+      w = width.to_f.positive? ? width : @size
+      h = height.to_f.positive? ? height : @size
+      %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 #{w} #{h}">#{source}</svg>)
+    end
+
+    # Inkscape writes width="1024" alongside viewBox="0 0 270.93 270.93"; the
+    # viewBox is authoritative. Iconify supplies dimensions out of band.
+    def viewbox_of(root, width, height)
+      if (vb = root.attributes["viewBox"])
+        min_x, min_y, w, h = vb.split(/[\s,]+/).map(&:to_f)
+        return [w, h, min_x, min_y] if w.to_f.positive? && h.to_f.positive?
+      end
+
+      w = (width || root.attributes["width"]).to_f
+      h = (height || root.attributes["height"]).to_f
+      w = @size if w.zero?
+      h = @size if h.zero?
+      [w, h, 0.0, 0.0]
+    end
+
+    # Author notes are document furniture. Harmless in one file, but the
+    # sprite merges every body into one document, so they all ship together.
+    def strip_comments!(root)
+      REXML::XPath.each(root, "//comment()") { _1.parent&.delete(_1) }
+    end
+
+    def strip_elements!(root)
+      each_element(root) do |el|
+        el.parent&.delete_element(el) if DROP_ELEMENTS.include?(el.expanded_name)
+      end
+      # Empty <defs> and childless groups are pure noise in a merged sprite.
+      each_element(root) do |el|
+        next unless %w[defs g].include?(el.expanded_name)
+
+        el.parent&.delete_element(el) if el.elements.empty? && el.texts.join.strip.empty?
+      end
+    end
+
+    def strip_attributes!(root)
+      each_element(root) do |el|
+        el.attributes.each_attribute.to_a.each do |attr|
+          name = attr.expanded_name
+          drop = DROP_ATTR_PREFIXES.any? { name.start_with?(_1) } ||
+                 name.start_with?("on") ||
+                 name.start_with?("xmlns:") ||
+                 external_reference?(name, attr.value)
+          el.attributes.delete(name) if drop
+        end
+      end
+    end
+
+    def external_reference?(name, value)
+      return false unless %w[href xlink:href].include?(name)
+
+      !value.to_s.strip.start_with?("#")
+    end
+
+    # The collision fix. 34 of 40 sampled exports shared id="layer1"; without
+    # this, merging any two of them silently drops one definition.
+    def namespace_ids!(root)
+      prefix = @icon.key
+      seen = {}
+
+      each_element(root) do |el|
+        next unless (id = el.attributes["id"])
+
+        seen[id] = "#{prefix}__#{id}"
+        el.attributes["id"] = seen[id]
+      end
+      return if seen.empty?
+
+      each_element(root) do |el|
+        el.attributes.each_attribute.to_a.each do |attr|
+          next unless URL_ATTRS.include?(attr.name) || %w[href xlink:href].include?(attr.expanded_name)
+
+          value = attr.value.dup
+          seen.each do |old, new|
+            value.gsub!("url(##{old})", "url(##{new})")
+            value.gsub!(/\A##{Regexp.escape(old)}\z/, "##{new}")
+          end
+          el.attributes[attr.expanded_name] = value
+        end
+      end
+    end
+
+    # Anything that resolves to paint: literal colours plus gradient
+    # references, which are multicolour by construction.
+    def distinct_colors(root)
+      found = []
+      each_element(root) do |el|
+        COLOR_ATTRS.each do |name|
+          v = el.attributes[name].to_s.strip
+          found << v unless v.empty? || v == "none" || v == "currentColor"
+        end
+        next unless (style = el.attributes["style"])
+
+        style.scan(/\b(?:fill|stroke|stop-color)\s*:\s*([^;]+)/i) do
+          v = Regexp.last_match(1).strip
+          found << v unless v == "none" || v == "currentColor"
+        end
+      end
+      found.map { _1.start_with?("url(") ? "#{_1}-gradient" : _1.downcase }.uniq
+    end
+
+    def fold_colors!(root)
+      each_element(root) do |el|
+        COLOR_ATTRS.each do |name|
+          value = el.attributes[name]
+          next if value.nil? || value == "none" || value == "currentColor"
+
+          el.attributes[name] = "currentColor"
+        end
+
+        next unless (style = el.attributes["style"])
+
+        folded = style.gsub(/\b(fill|stroke|stop-color)\s*:\s*([^;]+)/i) do
+          $2.strip.casecmp("none").zero? ? "#{$1}:none" : "#{$1}:currentColor"
+        end
+        el.attributes["style"] = folded
+      end
+    end
+
+    # Section 03 of the spec: things no preprocessing can rescue. Surfaced as
+    # warnings so the build names the file instead of shipping something broken.
+    def flag_hard_failures!(root)
+      each_element(root) do |el|
+        case el.expanded_name
+        when "text", "tspan"
+          @warnings << "contains live <#{el.expanded_name}>; convert text to paths"
+        when "image"
+          @warnings << "embeds a raster <image>; redraw as vector"
+        when "filter"
+          @warnings << "uses a <filter>; effects do not survive font conversion"
+        end
+      end
+      @warnings.uniq!
+    end
+
+    # Fit any source box into the target box, centred, aspect preserved.
+    # fa6-solid is 512 with per-icon 576 overrides; bi declares no width at
+    # all. The pipeline cannot assume 24.
+    def refit(markup, w, h, min_x, min_y)
+      scale = @size.to_f / [w, h].max
+      return markup if (scale - 1.0).abs < 1e-9 && min_x.zero? && min_y.zero?
+
+      tx = (@size - (w * scale)) / 2.0
+      ty = (@size - (h * scale)) / 2.0
+      transform = "translate(#{fmt(tx)} #{fmt(ty)}) scale(#{fmt(scale)}) " \
+                  "translate(#{fmt(-min_x)} #{fmt(-min_y)})"
+      %(<g transform="#{transform}">#{markup}</g>)
+    end
+
+    def fmt(n) = format("%g", n.round(4))
+
+    def inner_markup(root)
+      out = +""
+      formatter = REXML::Formatters::Default.new
+      root.children.each { formatter.write(_1, out) }
+      out.strip
+    end
+
+    def each_element(root, &block)
+      root.elements.to_a("//*").each { block.call(_1) if _1.parent }
+    end
+  end
+end

data/lib/fontico/provider_fonts.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "zlib"
+require "rubygems/package"
+require "fileutils"
+
+module Fontico
+  # Providers that publish their own font alongside a name -> codepoint map.
+  #
+  # This is the only lossless source of outlines for a stroke-based set: the
+  # provider has already expanded the strokes for their font build. Every
+  # available JS expander traces a raster and visibly degrades the geometry.
+  module ProviderFonts
+    REGISTRY = {
+      "lucide" => {
+        package: "lucide-static",
+        version: "1.32.0",
+        font: "package/font/lucide.ttf",
+        codepoints: "package/font/codepoints.json"
+      }
+    }.freeze
+
+    module_function
+
+    def available?(provider) = REGISTRY.key?(provider)
+
+    def known = REGISTRY.keys
+
+    # Downloads and unpacks once into the cache; returns local paths.
+    def fetch(provider, cache_dir:)
+      spec = REGISTRY.fetch(provider) { raise Error, "no known font for provider #{provider}" }
+      dir = File.join(cache_dir, "#{spec[:package]}-#{spec[:version]}")
+      font = File.join(dir, File.basename(spec[:font]))
+      codepoints = File.join(dir, File.basename(spec[:codepoints]))
+      return [font, codepoints] if File.exist?(font) && File.exist?(codepoints)
+
+      FileUtils.mkdir_p(dir)
+      unpack(download(spec), spec, font, codepoints)
+      [font, codepoints]
+    end
+
+    def download(spec)
+      url = "https://registry.npmjs.org/#{spec[:package]}/-/#{spec[:package]}-#{spec[:version]}.tgz"
+      uri = URI(url)
+      res = Net::HTTP.get_response(uri)
+      res = Net::HTTP.get_response(URI(res["location"])) if res.is_a?(Net::HTTPRedirection)
+      raise Error, "downloading #{url}: HTTP #{res.code}" unless res.is_a?(Net::HTTPSuccess)
+
+      res.body
+    end
+
+    def unpack(tgz, spec, font_out, codepoints_out)
+      wanted = { spec[:font] => font_out, spec[:codepoints] => codepoints_out }
+      Gem::Package::TarReader.new(Zlib::GzipReader.new(StringIO.new(tgz))) do |tar|
+        tar.each do |entry|
+          dest = wanted[entry.full_name]
+          File.binwrite(dest, entry.read) if dest
+        end
+      end
+      missing = wanted.reject { File.exist?(_2) }.keys
+      raise Error, "#{spec[:package]} did not contain #{missing.join(", ")}" if missing.any?
+    end
+  end
+end

data/lib/fontico/railtie.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module Fontico
+  class Railtie < ::Rails::Railtie
+    initializer "fontico.helper" do
+      ActiveSupport.on_load(:action_view) { include Fontico::Helper }
+    end
+
+    initializer "fontico.root" do
+      Fontico.root = Rails.root.to_s
+    end
+
+    # Saving icons.yml — or a local SVG — rebuilds the artifacts and drops the
+    # memoized manifest, so a new icon is live on the next request with no
+    # restart and no rake. That memo is the only thing that ever needed one:
+    # this gem is not Zeitwerk's to reload, so @manifest outlives a code
+    # reload, while Propshaft re-digests the rebuilt sprite on its own in dev.
+    initializer "fontico.reloader" do |app|
+      next unless app.config.enable_reloading
+
+      watcher = app.config.file_watcher.new([Fontico.manifest_path], Railtie.local_dirs) do
+        Fontico.reset!
+        Fontico.rebuild!
+        # Recorded rather than raised: a save that half-breaks the manifest
+        # must not take down a page that draws none of the broken icons. The
+        # ones that do draw them raise, at the call site. See Fontico.check!.
+        Rails.logger.error("fontico: #{Fontico.build_error.message}") if Fontico.build_error
+      end
+
+      # Both halves are load-bearing: Rails runs to_run callbacks only when
+      # some registered reloader reports itself updated.
+      app.reloaders << watcher
+      app.reloader.to_run { watcher.execute_if_updated }
+    end
+
+    rake_tasks { load File.expand_path("../tasks/fontico.rake", __dir__) }
+
+    # First-party SVGs are sources too, and editing one has to re-preprocess.
+    # Asked of the manifest, but never at the cost of the boot: an icons.yml
+    # too broken to parse must still come up, because the watcher is what
+    # picks up the fix.
+    def self.local_dirs
+      path = begin
+        Fontico.manifest.local_path
+      rescue StandardError
+        Manifest::LOCAL_PATH
+      end
+      dir = File.join(Fontico.root, path)
+      File.directory?(dir) ? { dir => %w[svg] } : {}
+    end
+  end
+end