zer0-image-generator 0.6.0 → 0.8.0

data/lib/zer0_image_generator/svg/pixel_kit.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module Zer0ImageGenerator
+  module Svg
+    # Retro pixel-art SVG toolkit — a port of `tools/svg/pixelkit.py`, which
+    # stays the oracle. The style, codified:
+    #
+    # - Integer pixel grid. Every mark is an axis-aligned run of whole cells;
+    #   nothing lives off-grid, so nothing can be half a pixel wrong.
+    # - `shape-rendering="crispEdges"` on the root, so no engine anti-aliases
+    #   the art into mush.
+    # - Small palettes (6 tokens, engine-kin) declared once. Sprites are ASCII
+    #   maps, chars -> tokens.
+    # - Horizontal runs of same-colored cells merge into single <rect>s: a
+    #   64x48 scene stays a few KB instead of thousands of one-cell rects.
+    # - Optional CRT dressing (scanline veil + vignette bars).
+    #
+    # This is a LIBRARY the generator slices (invaders, pixelquest) build on, so
+    # both the API shape and the exact output bytes are contract. The committed
+    # scenes under `docs/samples/` and `docs/showcase/` were emitted through
+    # this code; the run-length merge in particular is output-shaping, and any
+    # difference there changes the SVG bytes.
+    module PixelKit
+      SVG_NS = "http://www.w3.org/2000/svg"
+
+      # [bg, shadow, low-mid, mid, accent, highlight] — same shape as the
+      # engine's RETRO_PALETTES rows so scenes read as kin to its banners.
+      PALETTES = {
+        "dusk" => ["#1a1423", "#3d2b3d", "#7a3045", "#f24236", "#f5a623", "#f7e8d3"],
+        "cyanic" => ["#0b132b", "#1c2541", "#1c7293", "#5bc0be", "#9fd8d6", "#e8f1f2"],
+        "moss" => ["#16211b", "#243b2a", "#3e6b48", "#6f9e6f", "#a3c9a8", "#e9edc9"],
+        "magma" => ["#120b16", "#2d1b2e", "#5c2a4a", "#b3324b", "#f2542d", "#ffd166"],
+      }.freeze
+
+      module_function
+
+      # Mirror each row left-to-right (classic invader symmetry). With
+      # shared_center the last column is the axis and is not doubled.
+      #
+      # Python slices `row[-2::-1]` (reverse minus last char) and `row[::-1]`
+      # (full reverse); the Ruby equivalents must agree on the empty and
+      # single-char rows, hence `row[0..-2]` rather than chopping by index.
+      def hmirror(half, shared_center: true)
+        half.map do |row|
+          tail = shared_center ? (row[0..-2] || "").reverse : row.reverse
+          row + tail
+        end
+      end
+    end
+
+    # A fixed-size integer cell grid. Colors are stored per cell and only
+    # collapsed into <rect> runs at serialization time (see #to_svg).
+    class Canvas
+      attr_reader :cols, :rows, :px, :bg
+
+      def initialize(cols, rows, px: 8, bg: "#000000")
+        @cols = cols
+        @rows = rows
+        @px = px
+        @bg = bg
+        @cells = {}
+      end
+
+      # Off-grid writes are silently ignored — the same clamp the oracle uses
+      # so blits and discs can run off the edge without special-casing callers.
+      def set(col, row, color)
+        return unless col >= 0 && col < @cols && row >= 0 && row < @rows
+
+        @cells[[col, row]] = color
+      end
+
+      def fill(col, row, width, height, color)
+        (row...(row + height)).each do |r|
+          (col...(col + width)).each do |c|
+            set(c, r, color)
+          end
+        end
+      end
+
+      # Stamp an ASCII sprite. '.' and ' ' are transparent; any other char must
+      # be in `colors`. A missing key is a typo in the sprite or its map, and
+      # like the oracle's `colors[ch]` it fails loudly (KeyError) rather than
+      # painting nothing and hiding the mistake.
+      def blit(art, colors, col, row)
+        art.each_with_index do |line, dr|
+          line.chars.each_with_index do |ch, dc|
+            next if ch == "." || ch == " "
+
+            set(col + dc, row + dr, colors.fetch(ch))
+          end
+        end
+      end
+
+      # Blocky pixel disc — the engine's celestial-body look on a grid. `r` may
+      # be fractional; Python's `int()` truncates toward zero, which Ruby's
+      # `Integer#to_i`/`Float#to_i` also does, so the row/col spans line up.
+      def disc(cx, cy, r, color)
+        rr = r * r
+        ((cy - r).to_i..(cy + r).to_i).each do |row|
+          ((cx - r).to_i..(cx + r).to_i).each do |col|
+            set(col, row, color) if (((col - cx)**2) + ((row - cy)**2)) <= rr
+          end
+        end
+      end
+
+      def to_svg(title, crt: false)
+        w = @cols * @px
+        h = @rows * @px
+        px = @px
+        safe = title.gsub("&", "&amp;").gsub("<", "&lt;")
+
+        parts = [
+          %(<svg xmlns="#{PixelKit::SVG_NS}" viewBox="0 0 #{w} #{h}" role="img" ) +
+            %(shape-rendering="crispEdges">),
+          "<title>#{safe}</title>",
+          %(<rect width="#{w}" height="#{h}" fill="#{@bg}"/>),
+        ]
+
+        (0...@rows).each do |row|
+          row_runs(row).each do |col, length, color|
+            parts << %(<rect x="#{col * px}" y="#{row * px}" width="#{length * px}" ) +
+                     %(height="#{px}" fill="#{color}"/>)
+          end
+        end
+
+        if crt
+          (0...h).step(6) do |y|
+            parts << %(<rect y="#{y}" width="#{w}" height="1" fill="#000" opacity="0.10"/>)
+          end
+          [0, h - px].each do |y|
+            parts << %(<rect y="#{y}" width="#{w}" height="#{px}" fill="#000" opacity="0.30"/>)
+          end
+        end
+
+        parts << "</svg>"
+        "#{parts.join("\n")}\n"
+      end
+
+      private
+
+      # Merge each row's horizontal runs of identical color into (start, length,
+      # color) tuples. The sentinel column at `@cols` flushes the final run; a
+      # cell whose color differs from the current run closes it and opens the
+      # next. This mirrors the oracle exactly because the emitted rect list —
+      # and therefore the byte output — depends on precisely where runs break.
+      def row_runs(row)
+        runs = []
+        start = nil
+        color = nil
+        (0..@cols).each do |col|
+          cell = @cells[[col, row]]
+          next unless cell != color || col == @cols
+
+          runs << [start, col - start, color] unless color.nil? || start.nil?
+          if cell.nil?
+            start = nil
+            color = nil
+          else
+            start = col
+            color = cell
+          end
+        end
+        runs
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/svg/rasterizer.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require "open3"
+require_relative "sanitizer" # for SVG_WIDTH / SVG_HEIGHT — export dimensions
+
+module Zer0ImageGenerator
+  module Svg
+    # SVG -> PNG through the first available external tool. Chain and order are
+    # a fidelity contract: rsvg-convert, then inkscape, then ImageMagick
+    # (magick then convert), then the vendored Playwright/Chromium helper.
+    module Rasterizer
+      PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b
+
+      class << self
+        # debug() output is VERBOSE-gated in the Python; warn() always prints.
+        # The real logging module lives outside this slice, so route through a
+        # minimal, explicit stderr sink here (see DEVIATIONS in the port notes).
+        attr_accessor :verbose
+      end
+      @verbose = false
+
+      module_function
+
+      def log_warn(msg)
+        warn("[WARNING] #{msg}") # Kernel#warn -> $stderr
+      end
+
+      def log_debug(msg)
+        warn("[DEBUG] #{msg}") if Rasterizer.verbose
+      end
+
+      # shutil.which equivalent, memoized like the Python's lru_cache: a batch
+      # of N files must not pay N x 4 PATH scans. Returns the resolved path or
+      # nil. Tool discovery is per-run stable, so the cache is never invalidated.
+      def which(tool)
+        @which_cache ||= {}
+        return @which_cache[tool] if @which_cache.key?(tool)
+
+        @which_cache[tool] = resolve_on_path(tool)
+      end
+
+      def resolve_on_path(tool)
+        # A name with a directory component is checked directly, not searched.
+        if tool.include?(File::SEPARATOR) ||
+           (File::ALT_SEPARATOR && tool.include?(File::ALT_SEPARATOR))
+          return executable_file?(tool) ? tool : nil
+        end
+
+        path = ENV["PATH"]
+        return nil if path.nil? || path.empty?
+
+        seen = {}
+        path.split(File::PATH_SEPARATOR).each do |dir|
+          next if dir.empty? || seen[dir]
+
+          seen[dir] = true
+          candidate = File.join(dir, tool)
+          return candidate if executable_file?(candidate)
+        end
+        nil
+      end
+
+      def executable_file?(path)
+        # os.access(X_OK) and not isdir: File.executable? is false for a
+        # missing path, and File.file? rules out directories.
+        File.file?(path) && File.executable?(path)
+      end
+
+      # Run a command with output captured and discarded; true on exit 0.
+      # Mirrors _run_quiet: swallows OSError/timeout as a false result (with a
+      # debug line) — explicitly, never a bare rescue.
+      def run_quiet(cmd, cwd: nil, timeout: 120)
+        opts = {}
+        opts[:chdir] = cwd.to_s if cwd
+        status = nil
+        stderr_bytes = "".b
+        begin
+          Open3.popen3(*cmd, opts) do |stdin, stdout, stderr, wait_thr|
+            stdin.close
+            # Drain both pipes on threads so a chatty child can't deadlock on a
+            # full pipe buffer while we wait.
+            out_reader = Thread.new { stdout.read }
+            err_reader = Thread.new { stderr.read }
+            if wait_thr.join(timeout).nil?
+              # subprocess.TimeoutExpired branch: kill, then report failure.
+              begin
+                Process.kill("KILL", wait_thr.pid)
+              rescue Errno::ESRCH
+                # Race: the child already exited between join and kill.
+              end
+              out_reader.join
+              err_reader.join
+              log_debug("rasterizer #{cmd[0]} failed: timeout after #{timeout}s")
+              return false
+            end
+            status = wait_thr.value
+            out_reader.join
+            stderr_bytes = err_reader.value.to_s
+          end
+        rescue SystemCallError => exc
+          # OSError family (e.g. the binary vanished between which() and spawn).
+          log_debug("rasterizer #{cmd[0]} failed: #{exc}")
+          return false
+        end
+
+        if status.exitstatus != 0
+          snippet = stderr_bytes.dup.force_encoding("UTF-8").scrub[0, 200]
+          log_debug("rasterizer #{cmd[0]} exit #{status.exitstatus}: #{snippet}")
+          return false
+        end
+        true
+      end
+
+      # Locate the vendored Playwright helper. Candidate order mirrors the
+      # Python: beside the engine (the gem layout, where it actually lives),
+      # then the theme/curl layouts.
+      def playwright_helper(project_root)
+        engine_dir = File.expand_path("..", __dir__) # .../lib/zer0_image_generator
+        candidates = [
+          File.join(engine_dir, "rasterize-svg.js"),
+          File.expand_path(File.join(engine_dir, "..", "dev", "rasterize-svg.js")),
+          File.join(project_root.to_s, "scripts", "dev", "rasterize-svg.js"),
+        ]
+        candidates.find { |c| File.file?(c) }
+      end
+
+      # SVG -> PNG through the first available tool. Returns the tool name used,
+      # or nil when nothing worked (caller keeps the .svg).
+      def rasterize_svg(svg_path, png_path, project_root, preference: "auto")
+        svg_path = svg_path.to_s
+        png_path = png_path.to_s
+        w = SVG_WIDTH
+        h = SVG_HEIGHT
+        helper = playwright_helper(project_root)
+
+        chain = [
+          ["rsvg", lambda {
+            which("rsvg-convert") && run_quiet(
+              ["rsvg-convert", "-w", w.to_s, "-h", h.to_s, "-o", png_path, svg_path]
+            )
+          }],
+          ["inkscape", lambda {
+            which("inkscape") && run_quiet(
+              ["inkscape", svg_path, "--export-type=png",
+               "--export-filename=#{png_path}", "-w", w.to_s, "-h", h.to_s]
+            )
+          }],
+          ["magick", lambda {
+            (which("magick") && run_quiet(
+              ["magick", svg_path, "-resize", "#{w}x#{h}", png_path]
+            )) ||
+              (which("convert") && run_quiet(
+                ["convert", svg_path, "-resize", "#{w}x#{h}", png_path]
+              ))
+          }],
+          ["playwright", lambda {
+            !helper.nil? && which("node") && run_quiet(
+              ["node", helper.to_s, svg_path, png_path, w.to_s, h.to_s],
+              cwd: project_root, timeout: 180
+            )
+          }],
+        ]
+
+        return nil if preference == "none"
+
+        if preference != "auto"
+          chain = chain.select { |entry| entry[0] == preference }
+          if chain.empty?
+            log_warn("Unknown rasterizer '#{preference}'")
+            return nil
+          end
+        end
+
+        chain.each do |name, attempt|
+          next unless attempt.call
+
+          begin
+            if File.file?(png_path) && File.binread(png_path)[0, 8] == PNG_SIGNATURE
+              log_debug("Rasterized with #{name}: #{File.basename(png_path)}")
+              return name
+            end
+          rescue SystemCallError
+            # OSError reading the file — fall through to unlink + next tool.
+          end
+          # png_path.unlink(missing_ok=True): drop a partial/invalid output.
+          begin
+            File.delete(png_path)
+          rescue Errno::ENOENT
+            # Already absent — nothing to remove.
+          end
+        end
+        nil
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/svg/sanitizer.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require "rexml/document"
+
+module Zer0ImageGenerator
+  # SVG toolkit — the sanitizer, deterministic local renderer and rasterizer
+  # chain ported from preview_generator.py's "SVG toolkit" section. The Python
+  # keeps these as module globals in one file; the Ruby port splits them across
+  # sanitizer.rb / local_renderer.rb / rasterizer.rb but they remain one
+  # namespace and share the geometry contract defined here.
+  module Svg
+    SVG_NS = "http://www.w3.org/2000/svg"
+    XLINK_NS = "http://www.w3.org/1999/xlink"
+
+    # Banner geometry for SVG-producing providers (claude, local). Every SVG
+    # is squashed into this frame by sanitize_svg, and the rasterizer exports
+    # at exactly these pixel dimensions. This is a shared cross-slice contract.
+    SVG_WIDTH = 1536
+    SVG_HEIGHT = 1024
+
+    # Raised when model-produced SVG is unusable (unparseable, wrong root,
+    # or carrying a rejected DOCTYPE/ENTITY). Mirrors Python's SvgError.
+    class SvgError < StandardError; end
+
+    module Sanitizer
+      # Elements deleted outright: active content (script/iframe/audio/video),
+      # the XML/HTML escape hatch (foreignObject) and raster payloads (<image>).
+      BANNED_SVG_ELEMENTS = %w[script foreignObject iframe audio video image].freeze
+
+      # url() references that are NOT #-local (i.e. not url(#id), url('#id') or
+      # url("#id")). Anything else — url(http://…), url(data:…) — is external
+      # and gets neutralized to "none". Case-insensitive, matches Python's
+      # re.compile(r"url\(\s*(?!#|'#|\"#)[^)]*\)", re.I).
+      URL_REF = /url\(\s*(?!#|'#|"#)[^)]*\)/i
+
+      # DOCTYPE/ENTITY sniff run on the RAW text before parsing. Entity
+      # declarations enable billion-laughs expansion and external-reference
+      # attacks; a legit banner SVG needs neither, so reject rather than clean.
+      DOCTYPE_RE = /<!\s*(DOCTYPE|ENTITY)/i
+
+      IMPORT_RE = /@import[^;]*;?/i
+
+      module_function
+
+      # Element/attribute local name — the part after "}" in a Clark-notation
+      # tag. REXML already exposes local names via #name, so this only exists
+      # for the raw-string comparisons that mirror Python's _localname.
+      def localname(tag)
+        i = tag.rindex("}")
+        i ? tag[(i + 1)..] : tag
+      end
+
+      # Neutralize a style/presentation value: drop @import rules, then rewrite
+      # every non-local url(...) to "none". Mirrors Python's _scrub_style_text —
+      # @import is stripped FIRST so a url() inside it is gone before URL_REF runs.
+      def scrub_style_text(value)
+        value = value.gsub(IMPORT_RE, "")
+        value.gsub(URL_REF, "none")
+      end
+
+      # Parse + sanitize model-produced SVG. Raises SvgError when unusable.
+      #
+      # Strips scripts/foreignObject/external references/event handlers; forces
+      # the banner viewBox/width/height. Returns [clean_svg, warnings].
+      #
+      # NOTE ON BYTE-IDENTITY: unlike render_local_svg, the sanitized *string*
+      # is intentionally NOT byte-identical to Python's ElementTree output —
+      # REXML and ElementTree serialize namespaces, attribute order and
+      # self-closing tags differently. The security contract is what must
+      # match: everything the Python strips, this strips, and the forced
+      # geometry is identical.
+      def sanitize_svg(svg_text)
+        warnings = []
+        if svg_text =~ DOCTYPE_RE
+          raise SvgError, "SVG contains a DOCTYPE/ENTITY declaration (rejected)"
+        end
+
+        begin
+          # REXML is more lenient about undeclared-prefix errors than
+          # ElementTree, but both reject malformed markup. Entity expansion is
+          # already precluded — DTDs were rejected above.
+          doc = REXML::Document.new(svg_text)
+        rescue REXML::ParseException => exc
+          raise SvgError, "SVG does not parse: #{exc.message}"
+        end
+
+        root = doc.root
+        raise SvgError, "SVG does not parse: no root element" if root.nil?
+        unless root.name == "svg"
+          raise SvgError, "Root element is <#{root.name}>, not <svg>"
+        end
+
+        scrub(root, warnings)
+
+        # Force banner geometry. add_attribute overwrites in place when the
+        # attribute already exists, matching ET's root.set().
+        root.add_attribute("viewBox", "0 0 #{SVG_WIDTH} #{SVG_HEIGHT}")
+        root.add_attribute("width", SVG_WIDTH.to_s)
+        root.add_attribute("height", SVG_HEIGHT.to_s)
+
+        # Serialize with no reformatting: the default formatter preserves the
+        # tree as-is (no pretty-print), which keeps text/whitespace intact.
+        out = +""
+        REXML::Formatters::Default.new.write(root, out)
+        [out, warnings]
+      end
+
+      # Depth-first scrub. Mirrors Python's nested scrub(): banned child
+      # elements are removed (and NOT recursed into), surviving children are
+      # recursed, then this element's attributes and <style> text are cleaned.
+      def scrub(element, warnings)
+        # Snapshot children — we mutate the tree while iterating. REXML's
+        # #elements yields only Element nodes (skips text/comments/CDATA),
+        # matching ElementTree's list(element).
+        element.elements.to_a.each do |child|
+          name = child.name
+          if BANNED_SVG_ELEMENTS.include?(name)
+            element.delete_element(child)
+            warnings << "removed <#{name}>"
+            next
+          end
+          scrub(child, warnings)
+        end
+
+        # REXML surfaces namespace declarations (xmlns, xmlns:*) as attributes
+        # too, which ElementTree does not — but they never match any removal
+        # condition (their local names aren't "on*"/"href", their values are
+        # namespace URIs), so processing them is behavior-equivalent.
+        element.attributes.each_attribute.to_a.each do |attr|
+          local = attr.name # REXML #name is already the local name
+          value = attr.value
+          if local.downcase.start_with?("on")
+            element.attributes.delete(attr)
+            warnings << "removed #{local} handler"
+          elsif local == "href" && !value.start_with?("#")
+            element.attributes.delete(attr)
+            warnings << "removed external href"
+          elsif value.downcase.include?("url(") || value.downcase.include?("@import")
+            # Covers style= AND presentation attributes (fill, stroke, filter,
+            # mask, clip-path, …) — url() must stay #-local.
+            cleaned = scrub_style_text(value)
+            if cleaned != value
+              element.attributes[attr.expanded_name] = cleaned
+              warnings << "scrubbed url() in #{local}"
+            end
+          end
+        end
+
+        if element.name == "style" && element.text
+          cleaned = scrub_style_text(element.text)
+          if cleaned != element.text
+            element.text = cleaned
+            warnings << "scrubbed <style> url()/@import"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zer0ImageGenerator
-  VERSION = "0.6.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zer0-image-generator
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-10-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -47,9 +47,50 @@ files:
 - LICENSE
 - README.md
 - lib/zer0-image-generator.rb
+- lib/zer0_image_generator/abc.rb
+- lib/zer0_image_generator/abc/style_pack.rb
+- lib/zer0_image_generator/all.rb
+- lib/zer0_image_generator/claude/client.rb
+- lib/zer0_image_generator/claude/orchestration.rb
+- lib/zer0_image_generator/cli.rb
 - lib/zer0_image_generator/command.rb
+- lib/zer0_image_generator/config.rb
+- lib/zer0_image_generator/constants.rb
+- lib/zer0_image_generator/content.rb
+- lib/zer0_image_generator/engine.rb
+- lib/zer0_image_generator/freesvg/cache.rb
+- lib/zer0_image_generator/freesvg/client.rb
+- lib/zer0_image_generator/http.rb
+- lib/zer0_image_generator/library.rb
+- lib/zer0_image_generator/logging.rb
 - lib/zer0_image_generator/preview_generator.py
+- lib/zer0_image_generator/prompt.rb
+- lib/zer0_image_generator/providers.rb
+- lib/zer0_image_generator/providers/base.rb
+- lib/zer0_image_generator/providers/gemini.rb
+- lib/zer0_image_generator/providers/local.rb
+- lib/zer0_image_generator/providers/openai.rb
+- lib/zer0_image_generator/providers/stability.rb
+- lib/zer0_image_generator/providers/xai.rb
+- lib/zer0_image_generator/providers/xai_auth.rb
 - lib/zer0_image_generator/rasterize-svg.js
+- lib/zer0_image_generator/runner.rb
+- lib/zer0_image_generator/settings.rb
+- lib/zer0_image_generator/stats.rb
+- lib/zer0_image_generator/support/py_random.rb
+- lib/zer0_image_generator/svg/banner_seed.rb
+- lib/zer0_image_generator/svg/generators/flowfield.rb
+- lib/zer0_image_generator/svg/generators/invaders.rb
+- lib/zer0_image_generator/svg/generators/lowpoly.rb
+- lib/zer0_image_generator/svg/generators/lsystem.rb
+- lib/zer0_image_generator/svg/generators/mandala.rb
+- lib/zer0_image_generator/svg/generators/pixelquest.rb
+- lib/zer0_image_generator/svg/generators/starmap.rb
+- lib/zer0_image_generator/svg/lint.rb
+- lib/zer0_image_generator/svg/local_renderer.rb
+- lib/zer0_image_generator/svg/pixel_kit.rb
+- lib/zer0_image_generator/svg/rasterizer.rb
+- lib/zer0_image_generator/svg/sanitizer.rb
 - lib/zer0_image_generator/version.rb
 homepage: https://github.com/bamr87/zer0-image-generator
 licenses: