wani 0.1.8

data/lib/wani/cli.rb

@@ -0,0 +1,134 @@
+require "optparse"
+require "fileutils"
+require_relative "../wani"
+
+module Wani
+  class CLI
+    def initialize(out: $stdout, err: $stderr, font_manager: nil)
+      @out, @err = out, err
+      @font_manager = font_manager
+    end
+
+    def run(arguments)
+      args = arguments.dup
+      command = args.shift
+      case command
+      when "new" then create(args)
+      when "font" then font(args)
+      when "serve" then serve(args)
+      when "check" then check(args)
+      when "--version", "-v" then @out.puts(VERSION); 0
+      when nil, "--help", "-h", "help" then @out.puts("Usage: wani new DIRECTORY | serve [FILE] [--bind ADDRESS] [--port PORT] | check [FILE] | font add SOURCE | font list | font remove ID"); 0
+      else raise ArgumentError, "Unknown command: #{command}"
+      end
+    rescue ArgumentError, OptionParser::ParseError, SystemCallError => error
+      @err.puts "wani: #{error.message}"
+      1
+    end
+
+    private
+
+    def font(args)
+      require_relative "fonts/manager"
+      manager = @font_manager || Fonts::Manager.new
+      action = args.shift
+      case action
+      when "add"
+        raise ArgumentError, "Usage: wani font add SOURCE" unless args.length == 1
+        entry = with_font_progress { manager.add(args.first) }
+        @out.puts "Installed #{entry['family']} (#{entry['version']}); set font in Markdown to apply it."
+      when "list"
+        raise ArgumentError, "Usage: wani font list" unless args.empty?
+        @out.puts "ID\tFamily\tVersion\tVariable"
+        manager.list.each { |id, entry| @out.puts [id, entry['family'], entry['version'], entry['variable']].join("\t") }
+      when "remove"
+        raise ArgumentError, "Usage: wani font remove ID" unless args.length == 1
+        manager.remove(args.first, confirm: ->(files) {
+          @err.puts "Warning: font is used by #{files.join(', ')}"
+          next false unless $stdin.tty?
+          @err.print "Remove this font? [y/N] "
+          $stdin.gets&.strip&.downcase == "y"
+        })
+        @out.puts "Removed #{args.first}"
+      else
+        raise ArgumentError, "Usage: wani font add SOURCE | list | remove ID"
+      end
+      0
+    end
+
+    def with_font_progress
+      message = "Downloading font"
+      if @err.tty?
+        @err.print "\r#{message}.  "
+        @err.flush
+        animation = Thread.new do
+          dots = 1
+          loop do
+            sleep 0.3
+            dots = dots % 3 + 1
+            @err.print "\r#{message}#{('.' * dots).ljust(3)}"
+            @err.flush
+          end
+        end
+      else
+        @err.puts "#{message}..."
+        @err.flush
+      end
+      yield
+    ensure
+      if animation
+        animation.kill
+        animation.join
+        @err.print "\r#{' ' * (message.length + 3)}\r"
+        @err.flush
+      end
+    end
+
+    def create(args)
+      raise ArgumentError, "Usage: wani new DIRECTORY" unless args.length == 1
+      destination = File.expand_path(args.first)
+      Dir.mkdir(destination) # Atomic refusal, including existing directories and symlinks.
+      FileUtils.cp_r(File.join(ROOT, "templates/images"), File.join(destination, "images"))
+      FileUtils.cp(File.join(ROOT, "templates/slides.md"), File.join(destination, "slides.md"))
+      @out.puts "Created #{args.first}. Run: cd #{args.first} && wani serve"
+      0
+    end
+
+    def serve(args)
+      options = { bind: "127.0.0.1", port: 8000, out: @out }
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: wani serve [FILE] [--bind ADDRESS] [--port PORT]"
+        opts.on("-b", "--bind ADDRESS") { |value| options[:bind] = value }
+        opts.on("-p", "--port PORT", Integer) { |value| options[:port] = value }
+      end
+      parser.parse!(args)
+      raise ArgumentError, parser.banner if args.length > 1
+      raise ArgumentError, "Port must be between 0 and 65535" unless (0..65535).cover?(options[:port])
+      raise ArgumentError, "Browser assets missing; run bundle exec rake build:wasm before gem build" unless File.file?(File.join(ROOT, "assets/wani.wasm"))
+      require_relative "server/http_server"
+      Server::HTTPServer.new(args.first || "slides.md", **options).start
+      0
+    end
+
+    def check(args)
+      require_relative "core/parser"
+      require_relative "core/validator"
+      raise ArgumentError, "Usage: wani check [FILE]" if args.length > 1
+      file = File.expand_path(args.first || "slides.md")
+      presentation = Core::Parser.new.parse(File.read(file, encoding: "UTF-8"))
+      issues = Core::Validator.new.validate(presentation, base_dir: File.dirname(file))
+      if (name = presentation.fonts["default"])
+        require_relative "fonts/manager"
+        unless Core::Fonts.resolve(Fonts::Manager.new(File.dirname(file)).list, name)
+          issues << Core::Diagnostic.new(severity: :warning, message: "Unregistered font: #{name}; using fallback")
+        end
+      end
+      issues.each { |issue| @out.puts "#{issue.severity}: #{issue.slide ? "slide #{issue.slide}: " : ""}#{issue.message}" }
+      @out.puts "#{presentation.slides.length} slides; #{issues.length} diagnostics"
+      issues.any? { |issue| issue.severity == :error } ? 1 : 0
+    rescue Core::Parser::Error => error
+      @err.puts "error: #{error.message}"
+      1
+    end
+  end
+end

data/lib/wani/core/fonts.rb

@@ -0,0 +1,49 @@
+require "yaml"
+
+module Wani
+  module Core
+    module Fonts
+      ID = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+      module_function
+
+      def settings(value, config = {})
+        settings = {}
+        unless value.nil?
+          raise ArgumentError, "font must be a non-empty font name or ID" unless value.is_a?(String) && !value.strip.empty? && !value.match?(/[\x00-\x1f]/)
+          settings["default"] = value.strip
+        end
+        %w[title-weight body-weight].each do |key|
+          next unless config.key?(key)
+          weight = config[key]
+          raise ArgumentError, "#{key} must be an integer from 1 to 1000" unless weight.is_a?(Integer) && (1..1000).cover?(weight)
+          settings[key] = weight
+        end
+        settings
+      end
+
+      def registry(source)
+        data = YAML.safe_load(source, aliases: false) || {}
+        raise ArgumentError, "Invalid font registry" unless data.is_a?(Hash)
+        fonts = data.fetch("fonts", {})
+        raise ArgumentError, "Invalid font registry" unless fonts.is_a?(Hash)
+        fonts.each do |id, entry|
+          raise ArgumentError, "Invalid font registration" unless id.is_a?(String) && ID.match?(id) && entry.is_a?(Hash)
+          %w[family css_family version].each do |key|
+            raise ArgumentError, "Invalid font #{key}" unless entry[key].is_a?(String) && !entry[key].empty?
+          end
+          raise ArgumentError, "Invalid managed files" unless entry["files"].is_a?(Array) && entry["files"].all? { |path| path.is_a?(String) }
+          paths = [entry["stylesheet"], entry["license"], *entry.fetch("files", [])]
+          raise ArgumentError, "Invalid font files" unless paths.all? { |path| path.is_a?(String) && path.match?(%r{\Afonts/#{Regexp.escape(id)}/(?:font\.css|LICENSE|files/[a-zA-Z0-9_-]+\.woff2)\z}) }
+          raise ArgumentError, "Missing managed font files" unless paths.first(2).all? { |path| entry.fetch("files", []).include?(path) }
+        end
+        fonts
+      rescue Psych::Exception, NoMethodError, TypeError
+        raise ArgumentError, "Invalid font registry"
+      end
+
+      def resolve(fonts, name)
+        fonts[name] || fonts.values.find { |entry| entry["family"].casecmp?(name) }
+      end
+    end
+  end
+end

data/lib/wani/core/parser.rb

@@ -0,0 +1,127 @@
+require "yaml"
+require "kramdown"
+require "kramdown-parser-gfm"
+require_relative "presentation"
+require_relative "fonts"
+require_relative "safe_html"
+
+module Wani
+  module Core
+    class Parser
+      class Error < StandardError; end
+
+      def parse(source)
+        raise Error, "Markdown must be valid UTF-8" unless source.valid_encoding?
+        lines = source.delete_prefix("\uFEFF").gsub("\r\n", "\n").lines
+        config, lines = front_matter(lines)
+        diagnostics = []
+        chunks = split_slides(lines, diagnostics)
+        slides = chunks.each_with_index.map do |chunk, index|
+          number = index + 1
+          warn = ->(message) { diagnostics << Diagnostic.new(severity: :warning, message: message, slide: number) }
+          warn.call("Empty slide between separators") if chunk.strip.empty? && chunks.length > 1
+          document = markdown(chunk)
+          metadata = { "notes" => [], "page-footnote" => [] }
+          extract_metadata(document.root, metadata)
+          notes = metadata.fetch("notes")
+          page_footnotes = metadata.fetch("page-footnote")
+          warn.call("Multiple notes blocks combined") if notes.length > 1
+          warn.call("Multiple page-footnote blocks: the last value is used") if page_footnotes.length > 1
+          headings = walk(document.root).select { |node| node.type == :header }
+          warn.call("Additional heading: only the first heading is the slide title") if headings.length > 1
+          title = headings.first
+          raise Error, "Slide #{number}: title is empty" if title && plain(title).strip.empty?
+          remove(document.root, title) if title
+          renderer = SafeHTML.new(&warn)
+          note_roots = notes.map { |text| markdown(text).root }
+          Slide.new(number: number, title: title ? plain(title) : "", html: renderer.render(document.root),
+            page_footnote: page_footnotes.empty? ? "" : page_footnotes.last.strip,
+            notes_html: note_roots.map { |root| renderer.render(root) }.join,
+            images: ([document.root] + note_roots).flat_map { |root| walk(root).select { |node| node.type == :img && SafeHTML.safe_url?(node.attr['src'], image: true) }.map { |node| node.attr['src'] } }.uniq)
+        end
+        Presentation.new(fonts: Fonts.settings(config["font"], config), slides: slides, time_limit: config.fetch("time_limit", 5), diagnostics: diagnostics.uniq { |item| item.to_h })
+      rescue Encoding::CompatibilityError, ArgumentError => error
+        raise Error, "Invalid Markdown: #{error.message}"
+      end
+
+      private
+
+      def front_matter(lines)
+        return [{}, lines] unless lines.first&.strip == "---"
+        ending = (1...lines.length).find { |index| lines[index].strip == "---" }
+        raise Error, "Unclosed Front Matter" unless ending
+        config = YAML.safe_load(lines[1...ending].join, permitted_classes: [], permitted_symbols: [], aliases: false) || {}
+        raise Error, "Front Matter must be a mapping" unless config.is_a?(Hash)
+        if config.key?("time_limit")
+          limit = config["time_limit"]
+          raise Error, "time_limit must be a finite non-negative number of minutes" unless limit.is_a?(Numeric) && limit.finite? && limit >= 0 && (limit * 60_000).finite?
+        end
+        [config, lines[(ending + 1)..]]
+      rescue Psych::Exception
+        raise Error, "Invalid or unsafe YAML in Front Matter"
+      end
+
+      def split_slides(lines, diagnostics)
+        chunks = [+""]
+        fence = nil
+        comment = false
+        lines.each do |line|
+          if comment
+            comment = false if line.include?("-->")
+          elsif fence
+            fence = nil if line.match?(/\A {0,3}#{Regexp.escape(fence[0])}{#{fence.length},}[ \t]*\n?\z/)
+          elsif (match = line.match(/\A {0,3}(`{3,}|~{3,})/))
+            fence = match[1]
+          elsif line.match?(/\A {0,3}<!--/)
+            comment = !line.include?("-->")
+          elsif line.match?(/\A {0,3}---[ \t]*\n?\z/)
+            chunks << +""
+            next
+          elsif line.match?(/\A {0,3}[#]{1,6}[ \t]*\n?\z/)
+            raise Error, "Slide #{chunks.length}: title is empty"
+          end
+          chunks.last << line
+        end
+        raise Error, "Unclosed comment or notes block" if comment
+        diagnostics << Diagnostic.new(severity: :warning, message: "Unclosed code fence", slide: chunks.length) if fence
+        chunks
+      end
+
+      def markdown(text)
+        Kramdown::Document.new(text, input: "GFM", syntax_highlighter: nil)
+      end
+
+      def extract_metadata(node, metadata)
+        node.children.delete_if do |child|
+          if child.type == :xml_comment && child.value.match?(/\A<!--\s*(notes|page-footnote):/)
+            match = child.value.match(/\A<!--\s*(notes|page-footnote):\s*(.*?)-->\s*\z/m)
+            raise Error, "Invalid slide metadata block" unless match
+            metadata.fetch(match[1]) << match[2]
+            true
+          else
+            extract_metadata(child, metadata)
+            false
+          end
+        end
+      end
+
+      def walk(node)
+        [node] + node.children.flat_map { |child| walk(child) }
+      end
+
+      def remove(node, target)
+        node.children.delete(target)
+        node.children.each { |child| remove(child, target) }
+      end
+
+      def plain(node)
+        case node.type
+        when :text, :codespan then node.value
+        when :entity then node.value.char
+        when :smart_quote then SafeHTML::QUOTES.fetch(node.value, "")
+        else node.children.map { |child| plain(child) }.join
+        end
+      end
+    end
+  end
+end

data/lib/wani/core/presentation.rb

@@ -0,0 +1,15 @@
+module Wani
+  module Core
+    Diagnostic = Struct.new(:severity, :message, :slide, keyword_init: true) do
+      def to_h
+        { severity: severity.to_s, message: message, slide: slide }
+      end
+    end
+    Slide = Struct.new(:number, :title, :html, :notes_html, :images, :page_footnote, keyword_init: true)
+    Presentation = Struct.new(:slides, :time_limit, :diagnostics, :fonts, keyword_init: true) do
+      def to_h
+        { slides: slides.map(&:to_h), time_limit: time_limit, diagnostics: diagnostics.map(&:to_h) }.tap { |data| data[:fonts] = fonts unless fonts.nil? || fonts.empty? }
+      end
+    end
+  end
+end

data/lib/wani/core/safe_html.rb

@@ -0,0 +1,74 @@
+module Wani
+  module Core
+    # Emit only known Markdown elements; never forward raw HTML or arbitrary attributes.
+    class SafeHTML
+      TAGS = { p: "p", em: "em", strong: "strong", ul: "ul", ol: "ol", li: "li", blockquote: "blockquote", header: "h2", table: "table", thead: "thead", tbody: "tbody", tr: "tr", th: "th", td: "td", del: "del" }.freeze
+      QUOTES = { lsquo: "‘", rsquo: "’", ldquo: "“", rdquo: "”" }.freeze
+      def self.escape(value)
+        value.to_s.gsub(/[&<>"']/) { |character| { "&" => "&amp;", "<" => "&lt;", ">" => "&gt;", '"' => "&quot;", "'" => "&#39;" }.fetch(character) }
+      end
+
+      def self.safe_url?(value, image: false)
+        return false unless value.is_a?(String) && !value.empty?
+        return false if value.match?(/[\x00-\x20\x7f\\]/) || value.start_with?("//")
+        return false if value.match?(/&(?:#\d+|#x[0-9a-f]+|[a-z]+);/i)
+        scheme = value[/\A([^\/:?#]+):/, 1]
+        !scheme || (image ? %w[http https] : %w[http https mailto]).include?(scheme.downcase)
+      end
+
+      def initialize(&diagnostic)
+        @diagnostic = diagnostic || ->(_message) {}
+      end
+
+      def render(node)
+        body = node.children.map { |child| render(child) }.join
+        tag = TAGS[node.type]
+        return "<#{tag}>#{body}</#{tag}>" if tag
+        case node.type
+        when :root then body
+        when :text then self.class.escape(node.value)
+        when :codespan then "<code>#{self.class.escape(node.value)}</code>"
+        when :codeblock then codeblock(node)
+        when :a
+          if self.class.safe_url?(node.attr["href"])
+            "<a href=\"#{self.class.escape(node.attr['href'])}\" rel=\"noopener noreferrer\">#{body}</a>"
+          else
+            @diagnostic.call("Unsafe link URL removed")
+            body
+          end
+        when :img
+          if self.class.safe_url?(node.attr["src"], image: true)
+            "<img src=\"#{self.class.escape(node.attr['src'])}\" alt=\"#{self.class.escape(node.attr['alt'])}\">"
+          else
+            @diagnostic.call("Unsafe image URL removed")
+            self.class.escape(node.attr["alt"])
+          end
+        when :br then "<br>"
+        when :hr then "<hr>"
+        when :entity then self.class.escape(node.value.char)
+        when :smart_quote then QUOTES.fetch(node.value, "")
+        when :html_element, :xml_pi
+          @diagnostic.call("Raw HTML removed")
+          ""
+        when :xml_comment then ""
+        else body
+        end
+      end
+
+      private
+
+      def codeblock(node)
+        language = node.options[:lang]
+        if language && !language.empty?
+          require "rouge"
+          lexer = Rouge::Lexer.find(language)
+          if lexer
+            html = Rouge::Formatters::HTML.new.format(lexer.new.lex(node.value))
+            return "<pre class=\"highlight\"><code>#{html}</code></pre>"
+          end
+        end
+        "<pre><code>#{self.class.escape(node.value)}</code></pre>"
+      end
+    end
+  end
+end

data/lib/wani/core/validator.rb

@@ -0,0 +1,31 @@
+require "uri"
+require_relative "presentation"
+module Wani
+  module Core
+    class Validator
+      EXTENSIONS = %w[.png .jpg .jpeg .webp .svg].freeze
+      def validate(presentation, base_dir:)
+        diagnostics = presentation.diagnostics.dup
+        presentation.slides.each do |slide|
+          slide.images.each do |url|
+            next if url.match?(/\Ahttps?:/i)
+            path = url.split(/[?#]/, 2).first
+            decoded = URI::RFC2396_PARSER.unescape(path)
+            file = File.expand_path(decoded, base_dir)
+            message = if !EXTENSIONS.include?(File.extname(path).downcase)
+                        "Unsupported image type: #{url}"
+                      elsif !File.file?(file)
+                        "Missing image: #{url}"
+                      elsif !File.realpath(file).start_with?(File.realpath(base_dir) + File::SEPARATOR)
+                        "Image is outside the public Markdown directory: #{url}"
+                      end
+            diagnostics << Diagnostic.new(severity: :error, message: message, slide: slide.number) if message
+          rescue ArgumentError, SystemCallError
+            diagnostics << Diagnostic.new(severity: :error, message: "Invalid image path: #{url}", slide: slide.number)
+          end
+        end
+        diagnostics
+      end
+    end
+  end
+end

data/lib/wani/fonts/http.rb

@@ -0,0 +1,45 @@
+require "net/http"
+require "uri"
+require "timeout"
+
+module Wani
+  module Fonts
+    class Error < ArgumentError; end
+
+    class HTTP
+      MAX_BYTES = 32 * 1024 * 1024
+      def get(url, redirects: 3)
+        uri = URI.parse(url)
+        valid = uri.scheme == "https" && uri.port == 443 && !uri.userinfo && !uri.fragment && !uri.query
+        valid &&= case uri.host
+                  when "api.fontsource.org" then uri.path.match?(%r{\A/v1/(?:fonts|version)(?:/[a-z0-9-]+)?\z})
+                  when "cdn.jsdelivr.net" then uri.path.match?(%r{\A/npm/@fontsource(?:-variable)?/[a-z0-9-]+@\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?/(?:package\.json|metadata\.json|LICENSE|[a-z0-9-]+\.css|files/[a-zA-Z0-9_-]+\.woff2)\z})
+                  else false
+                  end
+        raise Error, "Untrusted Fontsource URL: #{url}" unless valid
+        Timeout.timeout(60) do
+          Net::HTTP.start(uri.host, uri.port, use_ssl: true, open_timeout: 10, read_timeout: 20, write_timeout: 20) do |http|
+            http.request(Net::HTTP::Get.new(uri.request_uri, "Accept-Encoding" => "identity")) do |response|
+              if response.is_a?(Net::HTTPRedirection)
+                raise Error, "Too many redirects" if redirects.zero?
+                return get(URI.join(url, response.fetch("location")).to_s, redirects: redirects - 1)
+              end
+              raise Error, "Fontsource HTTP #{response.code}: #{url}" unless response.is_a?(Net::HTTPSuccess)
+              expected = response["content-length"]&.to_i
+              raise Error, "Download exceeds size limit" if expected && expected > MAX_BYTES
+              body = +"".b
+              response.read_body do |part|
+                body << part
+                raise Error, "Download exceeds size limit" if body.bytesize > MAX_BYTES
+              end
+              raise Error, "Incomplete download: #{url}" if body.empty? || (expected && expected != body.bytesize)
+              return body
+            end
+          end
+        end
+      rescue URI::InvalidURIError, SocketError, IOError, SystemCallError, Timeout::Error, Net::HTTPError, OpenSSL::SSL::SSLError => error
+        raise Error, "Fontsource download failed: #{error.message}"
+      end
+    end
+  end
+end

data/lib/wani/fonts/manager.rb

@@ -0,0 +1,190 @@
+require "json"
+require "digest"
+require "fileutils"
+require "tmpdir"
+require "tempfile"
+require_relative "http"
+require_relative "../core/fonts"
+require_relative "../core/parser"
+
+module Wani
+  module Fonts
+    class Manager
+      def initialize(root = Dir.pwd, http: HTTP.new)
+        @root, @http = File.realpath(root), http
+      end
+
+      def list
+        path = safe_path(".wani/fonts.yml")
+        File.exist?(path) ? Core::Fonts.registry(File.read(path)) : {}
+      end
+
+      def add(source)
+        locked do
+          @bytes = 0
+          id = identify(source)
+          fonts = list
+          raise Error, "Font already installed: #{id}" if fonts.key?(id)
+          meta = json("https://api.fontsource.org/v1/fonts/#{id}")
+          raise Error, "Font metadata mismatch" unless meta.is_a?(Hash) && meta["id"] == id && meta["family"].is_a?(String)
+          raise Error, "Font already installed: #{meta['family']}" if Core::Fonts.resolve(fonts, meta['family'])
+          raise Error, "Invalid font styles" unless meta["styles"].is_a?(Array) && !meta["styles"].empty? && (meta["styles"] - %w[normal italic]).empty?
+          raise Error, "Invalid font weights" unless meta["weights"].is_a?(Array) && meta["weights"].all? { |weight| weight.is_a?(Numeric) }
+          versions = json("https://api.fontsource.org/v1/version/#{id}")
+          variable = meta["variable"] == true && versions["latestVariable"].is_a?(String)
+          version = versions.fetch(variable ? "latestVariable" : "latest")
+          raise Error, "Invalid package version" unless version.is_a?(String) && version.match?(/\A\d+\.\d+\.\d+(?:-[a-zA-Z0-9.-]+)?\z/)
+          package = "@fontsource#{variable ? '-variable' : ''}/#{id}"
+          base = "https://cdn.jsdelivr.net/npm/#{package}@#{version}/"
+          manifest = json(base + "package.json")
+          raise Error, "Package/version mismatch" unless manifest["name"] == package && manifest["version"] == version
+          raise Error, "Package has no license information" unless manifest["license"].is_a?(String) && !manifest["license"].empty?
+          weights = [400, 700] & meta.fetch("weights").map(&:to_i)
+          raise Error, "Font has neither weight 400 nor 700" if weights.empty?
+          css_names = variable ? meta.fetch("styles").map { |style| style == "normal" ? "index.css" : "wght-#{style}.css" } : weights.product(meta.fetch("styles")).map { |weight, style| "#{weight}#{style == 'normal' ? '' : "-#{style}"}.css" }
+          css = css_names.map { |name| download(base + name).force_encoding("UTF-8") }.join("\n")
+          raise Error, "Invalid font CSS" unless css.valid_encoding? && !css.match?(/@import/i)
+          # Retain all faces and unicode ranges, dropping only the WOFF fallback source.
+          css = css.gsub(/src\s*:\s*([^;]+);/i) do
+            sources = Regexp.last_match(1).scan(/url\(\s*['"]?(\.\/files\/[a-zA-Z0-9_-]+\.woff2)['"]?\s*\)\s*format\(['"]woff2(?:-variations)?['"]\)/).flatten
+            raise Error, "CSS face has no supported WOFF2 source" if sources.empty?
+            "src: url('#{sources.first}') format('woff2');"
+          end
+          urls = css.scan(/url\(([^)]+)\)/i).flatten.map { |url| url.strip.delete_prefix("'").delete_suffix("'") }
+          raise Error, "Invalid CSS font URLs" if urls.empty? || urls.any? { |url| !url.match?(%r{\A\./files/[a-zA-Z0-9_-]+\.woff2\z}) }
+          families = css.scan(/font-family:\s*['"]([^'"]+)['"]\s*;/).flatten.uniq
+          raise Error, "Unexpected CSS font family" unless families.length == 1 && [meta['family'], "#{meta['family']} Variable"].include?(families.first)
+          destination = safe_path("fonts/#{id}")
+          raise Error, "Destination already exists: fonts/#{id}" if File.exist?(destination)
+          FileUtils.mkdir_p(safe_path("fonts"))
+          Dir.mktmpdir(".wani-font-", @root) do |temporary|
+            stage = File.join(temporary, "font")
+            FileUtils.mkdir_p("#{stage}/files")
+            File.write("#{stage}/font.css", css)
+            urls.uniq.each do |url|
+              data = download(base + url.delete_prefix("./"))
+              raise Error, "Invalid or incomplete WOFF2: #{url}" unless data.bytesize >= 48 && data.start_with?("wOF2") && data.byteslice(8, 4).unpack1("N") == data.bytesize
+              File.binwrite(File.join(stage, url), data)
+            end
+            license = download(base + "LICENSE").force_encoding("UTF-8")
+            raise Error, "Invalid license document" unless license.valid_encoding? && license.length >= 100 && !license.match?(/<\s*(?:!doctype|html)/i)
+            File.write("#{stage}/LICENSE", license)
+            files = Dir.glob("#{stage}/**/*").select { |path| File.file?(path) }.to_h { |path| ["fonts/#{id}/#{path.delete_prefix(stage + '/')}", Digest::SHA256.file(path).hexdigest] }
+            entry = { "family" => meta["family"], "css_family" => families.first, "source" => "fontsource", "fontsource_id" => id, "version" => version, "package" => package, "stylesheet" => "fonts/#{id}/font.css", "license" => "fonts/#{id}/LICENSE", "license_type" => manifest["license"], "variable" => variable, "weights" => weights, "styles" => meta["styles"], "subsets" => meta["subsets"], "files" => files.keys, "sha256" => files }
+            File.rename(stage, destination)
+            begin
+              save(fonts.merge(id => entry))
+            rescue Exception
+              FileUtils.remove_entry(destination)
+              raise
+            end
+            entry
+          end
+        end
+      rescue KeyError, JSON::ParserError => error
+        raise Error, "Invalid Fontsource response: #{error.message}"
+      end
+
+      def remove(id, confirm: nil)
+        raise Error, "Invalid font ID" unless Core::Fonts::ID.match?(id)
+        locked do
+          fonts = list
+          entry = fonts.fetch(id) { raise Error, "Font not installed: #{id}" }
+          used = Dir.glob(File.join(@root, "**/*.{md,markdown}")).select do |file|
+            next false if File.symlink?(file) || !File.realpath(file).start_with?(@root + "/")
+            name = Core::Parser.new.parse(File.read(file, encoding: "UTF-8")).fonts["default"]
+            name && Core::Fonts.resolve(fonts, name) == entry
+          rescue Core::Parser::Error
+            true # A malformed document cannot establish that removal is safe.
+          end
+          raise Error, "Font is used by Markdown: #{used.join(', ')}; removal cancelled" if !used.empty? && !(confirm && confirm.call(used))
+          paths = entry.fetch("files").map { |relative| [relative, safe_path(relative)] }
+          paths.each do |relative, path|
+            next unless File.exist?(path)
+            raise Error, "Managed file was changed; refusing removal: #{relative}" unless entry.fetch("sha256", {})[relative] == Digest::SHA256.file(path).hexdigest
+          end
+          # Move only tracked files aside; restore them if committing the registry fails.
+          Dir.mktmpdir(".wani-remove-", @root) do |stage|
+            moved = []
+            begin
+              paths.each_with_index do |(_relative, path), index|
+                next unless File.exist?(path)
+                backup = File.join(stage, index.to_s)
+                File.rename(path, backup)
+                moved << [path, backup]
+              end
+              save(fonts.reject { |key, _| key == id })
+            rescue Exception
+              moved.reverse_each { |path, backup| File.rename(backup, path) }
+              raise
+            end
+          end
+          ["fonts/#{id}/files", "fonts/#{id}"].each do |relative|
+            path = safe_path(relative)
+            Dir.rmdir(path) if File.directory?(path) && Dir.empty?(path)
+          end
+        end
+      end
+
+      private
+
+      def identify(source)
+        if source.match?(%r{[:/\\]})
+          uri = URI.parse(source)
+          raise Error, "Use an official https://fontsource.org/fonts/ID URL" unless uri.scheme == "https" && uri.host == "fontsource.org" && uri.port == 443 && !uri.userinfo && !uri.query && !uri.fragment && uri.path.match?(%r{\A/fonts/[a-z0-9]+(?:-[a-z0-9]+)*/?\z})
+          return uri.path.split('/').last
+        end
+        candidates = json("https://api.fontsource.org/v1/fonts")
+        raise Error, "Invalid font catalog" unless candidates.is_a?(Array) && candidates.all? { |item| item.is_a?(Hash) && item['family'].is_a?(String) && item['id'].is_a?(String) }
+        matches = candidates.select { |item| item['id'] == source || item.fetch('family').casecmp?(source) }
+        matches = candidates.select { |item| item.fetch('family').downcase.include?(source.downcase) } if matches.empty?
+        raise Error, "Font not found: #{source}" if matches.empty?
+        raise Error, "Ambiguous font; specify an ID: #{matches.map { |item| item['id'] }.join(', ')}" unless matches.length == 1
+        id = matches.first.fetch('id')
+        raise Error, "Invalid Fontsource ID" unless Core::Fonts::ID.match?(id)
+        id
+      rescue URI::InvalidURIError
+        raise Error, "Invalid Fontsource URL"
+      end
+
+      def download(url)
+        body = @http.get(url)
+        @bytes += body.bytesize
+        raise Error, "Font exceeds 256 MiB installation limit" if @bytes > 256 * 1024 * 1024
+        body
+      end
+
+      def json(url)
+        JSON.parse(download(url))
+      end
+
+      def safe_path(relative)
+        current = @root
+        relative.split('/').each do |part|
+          raise Error, "Unsafe project path" if part == '..' || part == '.' || part.empty?
+          current = File.join(current, part)
+          raise Error, "Symlinks are not allowed in managed font paths: #{relative}" if File.symlink?(current)
+        end
+        current
+      end
+
+      def locked
+        FileUtils.mkdir_p(safe_path(".wani"))
+        File.open(safe_path(".wani/fonts.lock"), File::RDWR | File::CREAT, 0o600) do |lock|
+          lock.flock(File::LOCK_EX)
+          yield
+        end
+      end
+
+      def save(fonts)
+        path = safe_path(".wani/fonts.yml")
+        Tempfile.create(["fonts-", ".yml"], safe_path(".wani")) do |temporary|
+          temporary.write(YAML.dump("fonts" => fonts))
+          temporary.flush
+          temporary.fsync
+          File.rename(temporary.path, path)
+        end
+      end
+    end
+  end
+end