zer0-image-generator 0.6.0 → 0.8.0

data/lib/zer0_image_generator/constants.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+# Port of the constants block of lib/zer0_image_generator/preview_generator.py
+# (the Python engine remains the oracle). Values here are reproduced BYTE FOR
+# BYTE: the palettes, composition variants and geometry feed the deterministic
+# `local` provider, whose output is committed under docs/samples and
+# docs/showcase — a changed literal silently re-skins every committed piece.
+# test/ruby/test_constants.rb diffs the whole table against the Python module.
+
+module Zer0ImageGenerator
+  # Built-in fallbacks — used only when a key is absent from _config.yml, env,
+  # and CLI. Claude orchestration (analysis + review) is on by default and
+  # degrades gracefully without a Claude credential.
+  #
+  # String keys, because the same table is indexed by keys read straight out of
+  # YAML; `resolve_settings` looks up DEFAULTS[cfg_key] with the config key.
+  DEFAULTS = {
+    "enabled" => true,
+    "provider" => "openai",
+    "model" => "", # empty → the active provider's default_model
+    "size" => "1536x1024",
+    "quality" => "auto",
+    "style" => "retro pixel art, 8-bit video game aesthetic, vibrant colors, " \
+               "nostalgic, clean pixel graphics",
+    "style_modifiers" => "pixelated, retro gaming style, CRT screen glow effect, " \
+                         "limited color palette",
+    "output_dir" => "assets/images/previews",
+    "assets_prefix" => "/assets",
+    "auto_prefix" => true,
+    "collections" => ["posts"].freeze, # or "auto": discover from Jekyll `collections:`
+    "collections_dir" => "",           # Jekyll's collections_dir (zer0-mistakes: "pages")
+    "front_matter_key" => "preview",   # jekyll-seo-tag users typically want "image"
+    "authors_file" => "_data/authors.yml", # "" disables author overrides
+    "prompt_engine" => "claude",       # claude analyzes the article; falls back to template
+    "review_engine" => "claude",       # claude vision-reviews the render; `none` disables
+    "claude_model" => "",              # empty → DEFAULT_CLAUDE_MODEL
+    "claude_effort" => "low",          # output_config.effort for brief/review calls
+                                       # (short creative tasks; "" sends no effort)
+    "rasterizer" => "auto"             # SVG→PNG tool for the SVG providers (local,
+                                       # claude): auto|rsvg|inkscape|magick|playwright
+                                       # |none. "none" is SVG-only mode — the vector
+                                       # banner IS the deliverable and no PNG is made.
+  }.freeze
+
+  # Enhance mode (OpenAI /v1/images/edits — see the OpenAI provider's `edit`).
+  ENHANCE_DEFAULTS = {
+    "model" => "gpt-image-2",
+    "quality" => "auto",
+    "fidelity" => "high",
+    "format" => "png"
+  }.freeze
+
+  DEFAULT_ENHANCE_PROMPT = "Improve this preview banner image: fix any misspelled, garbled, or " \
+                           "incorrect text so it reads clearly and accurately. Sharpen visual details " \
+                           "and improve composition while preserving the original art style, color " \
+                           "palette, and theme. Ensure the image is clean and professional."
+
+  # Anthropic wire constants — keep in sync with templates/deploy/chat-proxy/worker.js.
+  ANTHROPIC_API_URL = "https://api.anthropic.com/v1/messages"
+  ANTHROPIC_VERSION = "2023-06-01"
+  OAUTH_BETA = "oauth-2025-04-20"
+  # Claude Code OAuth tokens require the FIRST system block to identify as Claude
+  # Code, otherwise the API rejects the call with a misleading `rate_limit_error`.
+  CLAUDE_CODE_SYSTEM_PROMPT = "You are Claude Code, Anthropic's official CLI for Claude."
+  DEFAULT_CLAUDE_MODEL = "claude-opus-4-8"
+  CLAUDE_MAX_TOKENS = 16_000 # non-streaming ceiling; SVG banners fit comfortably
+
+  # Model-name prefix → provider family. Used to ignore a configured/author model
+  # that belongs to a different vendor than the active provider (never send a
+  # request that is guaranteed to 400).
+  #
+  # Insertion order is part of the contract: `model_family` returns the FIRST
+  # matching prefix, exactly as the Python dict iteration does.
+  MODEL_FAMILIES = {
+    "claude-" => "claude",
+    "gpt-image-" => "openai",
+    "dall-e-" => "openai",
+    "grok-" => "xai",
+    "stable-" => "stability",
+    "sd3" => "stability",
+    "gemini-" => "gemini",
+    "imagen-" => "gemini"
+  }.freeze
+
+  # Banner geometry for SVG-producing providers (claude, local).
+  SVG_WIDTH = 1536
+  SVG_HEIGHT = 1024
+
+  # Curated retro palettes: (sky/background, far, mid, near, accent, glow).
+  # Selected deterministically per slug so re-runs stay visually stable.
+  RETRO_PALETTES = [
+    ["#1a1a2e", "#16213e", "#0f3460", "#533483", "#e94560", "#f9ed69"].freeze,
+    ["#0d1b2a", "#1b263b", "#415a77", "#778da9", "#e0e1dd", "#ffb703"].freeze,
+    ["#2d132c", "#801336", "#c72c41", "#ee4540", "#f9d276", "#f4f4f4"].freeze,
+    ["#10002b", "#3c096c", "#7b2cbf", "#c77dff", "#e0aaff", "#72efdd"].freeze,
+    ["#001219", "#005f73", "#0a9396", "#94d2bd", "#e9d8a6", "#ee9b00"].freeze,
+    ["#03071e", "#370617", "#9d0208", "#dc2f02", "#f48c06", "#ffba08"].freeze,
+    ["#0b132b", "#1c2541", "#3a506b", "#5bc0be", "#6fffe9", "#ff6b6b"].freeze,
+    ["#232931", "#393e46", "#4ecca3", "#a5ecd7", "#eeeeee", "#f95959"].freeze,
+    ["#1f0a24", "#571089", "#ab51e3", "#f7aef8", "#b388eb", "#8093f1"].freeze,
+    ["#141e30", "#243b55", "#3c6382", "#82ccdd", "#f8c291", "#e55039"].freeze
+  ].freeze
+
+  COMPOSITION_VARIANTS = [
+    "a low horizon with a huge rising sun disk banded by scanlines",
+    "layered diagonal mountain silhouettes receding into haze",
+    "a vaporwave perspective grid floor vanishing toward the horizon",
+    "floating terraced islands with cascading pixel waterfalls",
+    "a night starfield with a large ringed planet arcing across the frame",
+    "a stepped city skyline of blocky towers with lit windows",
+    "rolling desert dunes with a lone monolith and long shadows",
+    "an ocean of chunky pixel waves under drifting square clouds"
+  ].freeze
+
+  # System prompt for Claude's ART-DIRECTOR role (prompt_engine: claude): read
+  # the article, then write the brief a raster image model will render. NOTE:
+  # "no text" matches the long-standing prompt rule of this feature — image
+  # models garble lettering.
+  #
+  # `.chomp` because Python's triple-quoted literal ends right after "kind." —
+  # a heredoc would otherwise append a newline the oracle never sends.
+  ART_DIRECTOR_SYSTEM = <<~PROMPT.chomp
+    You are an art director for a technical blog. You will be given an article
+    (title, description, tags, an excerpt) plus mandatory style directions. Your
+    job is to design ONE preview banner image and describe it to an AI image
+    model.
+
+    Respond with ONLY the image-generation prompt — no preamble, no quotes, no
+    markdown. One vivid paragraph of at most 130 words that:
+    - captures the article's actual SUBJECT as a concrete visual metaphor or
+      scene (specific objects, actions and spatial arrangement — never a generic
+      'technology background');
+    - specifies composition for a wide banner (what sits left/center/right,
+      foreground/background, focal point);
+    - weaves in the given art style and palette directions verbatim in spirit;
+    - states that the image must contain NO text, letters, words, numbers, logos
+      or UI copy of any kind.
+  PROMPT
+
+  # System prompt for Claude's REVIEWER role (review_engine: claude): look at
+  # the rendered image and decide whether it represents the article.
+  REVIEWER_SYSTEM = <<~PROMPT.chomp
+    You are reviewing an AI-generated blog preview banner against the article it
+    illustrates. Judge three things: (1) does the image clearly evoke the
+    article's actual subject, (2) does it follow the requested art style, and
+    (3) is it free of text/lettering artifacts and visual glitches.
+
+    Respond with ONLY a JSON object, no markdown fences:
+    {"verdict": "approve" | "revise",
+     "critique": "<one or two sentences on what is wrong or right>",
+     "revised_prompt": "<empty when approving; otherwise a complete replacement
+    image-generation prompt (max 130 words) that fixes the problems while keeping
+    the required style and the no-text rule>"}
+
+    Approve unless the image genuinely misrepresents the subject, breaks the
+    style, or contains text/glitches — minor taste differences are not grounds
+    for revision.
+  PROMPT
+
+  PNG_SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+
+  # Pause after each successful non-dry generation (Bash parity: polite pacing
+  # between paid API calls).
+  POST_GENERATION_SLEEP = 2.0
+
+  # Settings fields an override block (author preview: / collection_styles:)
+  # may replace per file.
+  OVERRIDE_KEYS = %w[style style_modifiers size quality model].freeze
+
+  class << self
+    # The Python module-global POST_GENERATION_SLEEP is rebindable and the test
+    # suite sets it to 0; a Ruby constant is not, so the *runtime* value lives
+    # here and the constant stays the immutable published default.
+    attr_accessor :post_generation_sleep
+  end
+  self.post_generation_sleep = POST_GENERATION_SLEEP
+end

data/lib/zer0_image_generator/content.rb

@@ -0,0 +1,379 @@
+# frozen_string_literal: true
+
+require "date"
+require "fileutils"
+require "yaml"
+
+module Zer0ImageGenerator
+  # A parsed content file. `categories` is the already-joined "a, b" string the
+  # prompt layer wants, not a list — the Python dataclass shipped it that way and
+  # callers depend on it.
+  ContentFile = Struct.new(:path, :title, :description, :categories, :preview,
+                           :author, :content, :front_matter)
+
+  # Front-matter layer: read a Jekyll content file, and — the dangerous half —
+  # write one key back into a file a human owns without disturbing a byte of
+  # anything else.
+  #
+  # Ported from lib/zer0_image_generator/preview_generator.py (the oracle).
+  # Several helpers below reimplement CPython string semantics rather than using
+  # the nearest Ruby method, because the nearest Ruby method is subtly different
+  # and this layer rewrites user source files.
+  module Content
+    # Front matter opens on the very first line; trailing spaces/tabs are
+    # tolerated because editors leave them and Jekyll accepts them.
+    FM_OPEN = /\A---[ \t]*\r?\n/.freeze
+    FM_CLOSE = /^---[ \t]*\r?$/.freeze
+
+    # CPython's `str.isspace()` set — verified identical to what `re`'s `\s`
+    # matches for str patterns, and to what `str.strip()` removes. Ruby's `\s`
+    # is ASCII-only and `[[:space:]]` follows Unicode White_Space (which excludes
+    # U+001C..U+001F), so neither is a drop-in substitute. Built from codepoints
+    # so the source stays ASCII; none of these characters are class-special.
+    PY_SPACE_CODEPOINTS = [
+      0x09, 0x0A, 0x0B, 0x0C, 0x0D, 0x1C, 0x1D, 0x1E, 0x1F, 0x20, 0x85, 0xA0,
+      0x1680, 0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007,
+      0x2008, 0x2009, 0x200A, 0x2028, 0x2029, 0x202F, 0x205F, 0x3000
+    ].freeze
+    PY_SPACE_CLASS = PY_SPACE_CODEPOINTS.map { |cp| cp.chr(Encoding::UTF_8) }.join.freeze
+    PY_SPACE = /[#{PY_SPACE_CLASS}]/.freeze
+
+    # `str.splitlines(keepends=True)` breaks on far more than `\n`: VT, FF, the
+    # C0 separators (but NOT U+001F, which isspace() counts yet splitlines does
+    # not), NEL, and the Unicode line/paragraph separators all end a line.
+    # `String#lines` only knows `\n`, which would merge two front-matter lines
+    # into one and put the new key in the wrong place.
+    PY_LINE_BREAK_CODEPOINTS = [
+      0x0A, 0x0B, 0x0C, 0x0D, 0x1C, 0x1D, 0x1E, 0x85, 0x2028, 0x2029
+    ].freeze
+    PY_LINE_BREAK = PY_LINE_BREAK_CODEPOINTS.map { |cp| cp.chr(Encoding::UTF_8) }.join.freeze
+    PY_SPLITLINES = /[^#{PY_LINE_BREAK}]*(?:\r\n|[#{PY_LINE_BREAK}])?/.freeze
+
+    # Offsets of the raw front-matter body between the opening and closing `---`
+    # fences: [fm_start, fm_end, fm_text], or nil when the file has none.
+    # Offsets are character indices, as in the oracle.
+    def self.split_front_matter(text)
+      open_match = FM_OPEN.match(text)
+      return nil unless open_match
+
+      fm_start = open_match.end(0)
+      close = FM_CLOSE.match(text, fm_start)
+      return nil unless close
+
+      [fm_start, close.begin(0), text[fm_start...close.begin(0)]]
+    end
+
+    def self.parse_front_matter(path, fm_key = "preview")
+      text = read_text(path)
+      return nil unless text
+
+      parts = split_front_matter(text)
+      unless parts
+        log(:debug, "No front matter found in: #{path}")
+        return nil
+      end
+      fm_end = parts[1]
+
+      begin
+        data = YAML.safe_load(parts[2], permitted_classes: [Date, Time], aliases: true)
+      rescue Psych::Exception => e
+        log(:warn, "Failed to parse YAML in #{path}: #{e.message}")
+        return nil
+      end
+      return nil unless data.is_a?(Hash)
+
+      categories = data.fetch("categories", [])
+      categories = [categories] if categories.is_a?(String)
+      categories = [] unless categories.is_a?(Array)
+
+      body_start = text.index("\n", fm_end)
+      body = body_start ? text[(body_start + 1)..] : ""
+
+      preview = data[fm_key]
+      ContentFile.new(
+        path.to_s,
+        py_str(truthy?(data["title"]) ? data["title"] : ""),
+        py_str(truthy?(data["description"]) ? data["description"] : ""),
+        categories.map { |c| py_str(c) }.join(", "),
+        preview.is_a?(String) ? preview : nil,
+        data["author"],
+        body,
+        data
+      )
+    end
+
+    # Set `<key>:` inside the front-matter block ONLY (first match).
+    #
+    # Replaces an existing `<key>:` line, else inserts after the first
+    # `description:` line, else after the first `title:` line. Everything outside
+    # the front-matter block is preserved byte-for-byte (the former sed/regex
+    # implementations operated file-wide and could corrupt body lines that start
+    # with the key). Writes a transient `.bak`, replaces atomically, removes the
+    # `.bak` on success — CI asserts no `.bak` survives a successful run.
+    def self.update_front_matter(path, preview_path, dry_run: false, key: "preview")
+      if dry_run
+        log(:info, "[DRY RUN] Would update #{key} in #{path} to: #{preview_path}")
+        return true
+      end
+
+      # Bytes round-trip: the newline-translating read used by parse_front_matter
+      # would silently rewrite a CRLF file as LF.
+      text = read_text(path, universal_newlines: false)
+      return false unless text
+
+      parts = split_front_matter(text)
+      unless parts
+        log(:warn, "No front matter block in #{path}; not updating")
+        return false
+      end
+      fm_start, fm_end, fm_text = parts
+
+      eol = fm_text.include?("\r\n") ? "\r\n" : "\n"
+      lines = splitlines(fm_text)
+
+      preview_idx = find_key(lines, "#{key}:")
+      if preview_idx != -1
+        line = lines[preview_idx]
+        line_eol = if line.end_with?("\r\n") then "\r\n"
+                   elsif line.end_with?("\n") then "\n"
+                   else ""
+                   end
+        lines[preview_idx] = "#{key}: #{preview_path}#{line_eol}"
+      else
+        anchor = find_key(lines, "description:")
+        anchor = find_key(lines, "title:") if anchor == -1
+        if anchor == -1
+          log(:warn, "No #{key}:/description:/title: anchor in #{path} front matter")
+          return false
+        end
+        insert_at = end_of_block(lines, anchor)
+        if !lines[anchor].end_with?("\n") && insert_at == anchor + 1
+          lines[anchor] += eol # anchor was the final unterminated line
+        end
+        lines.insert(insert_at, "#{key}: #{preview_path}#{eol}")
+      end
+
+      new_text = text[0, fm_start] + lines.join + text[fm_end..]
+      write_atomically(path, new_text) or return false
+
+      log(:success, "Updated front matter with #{key}: #{preview_path}")
+      true
+    end
+
+    # Slug identical to the historical Bash chain (trim before the 50-cut).
+    def self.generate_filename(title)
+      slug = title.downcase.gsub(/[^a-z0-9]/, "-")
+      slug = slug.gsub(/-+/, "-").sub(/\A-+/, "").sub(/-+\z/, "")
+      slug[0, 50]
+    end
+
+    # Front-matter path -> site-absolute path (/assets/... form) for existence
+    # checks. External URLs pass through unchanged.
+    def self.normalize_preview_path(preview, settings)
+      return preview if preview.nil? || preview.empty?
+      return preview if preview.start_with?("http://", "https://")
+
+      # Substring (not prefix) check is deliberate: it mirrors the Liquid
+      # `contains` logic in components/preview-image.html and content/seo.html —
+      # the engine's idea of "already prefixed" must match what the site renders.
+      if settings.auto_prefix && !preview.include?(settings.assets_prefix)
+        return "#{settings.assets_prefix}#{preview}"
+      end
+
+      preview
+    end
+
+    def self.check_preview_exists(preview, settings, root)
+      return false if preview.nil? || preview.empty?
+      # External URLs count as present (matches the Liquid component + SEO tags;
+      # the old Bash engine would silently regenerate over them).
+      return true if preview.start_with?("http://", "https://")
+
+      normalized = normalize_preview_path(preview, settings) || ""
+      clean = normalized.sub(%r{\A/+}, "")
+      [join_path(root, clean), join_path(root, "assets", clean)].any? { |p| File.file?(p) }
+    end
+
+    # The value written to front matter — WITHOUT the assets prefix (Liquid adds
+    # it): assets/images/previews -> /images/previews/<filename>.
+    def self.preview_front_matter_path(settings, filename)
+      out = strip_slashes(settings.output_dir)
+      prefix = strip_slashes(settings.assets_prefix)
+      if !prefix.empty? && (out == prefix || out.start_with?("#{prefix}/"))
+        out = strip_slashes(out[prefix.length..])
+      end
+      out.empty? ? "/#{filename}" : "/#{out}/#{filename}"
+    end
+
+    # Locate an existing preview image on disk (for --enhance).
+    def self.find_preview_image(preview, settings, root)
+      return nil if preview.nil? || preview.empty?
+      return nil if preview.start_with?("http://", "https://")
+
+      clean = preview.sub(%r{\A/+}, "")
+      candidates = [
+        join_path(root, clean),
+        join_path(root, "assets", clean),
+        join_path(root, settings.output_dir, File.basename(clean)),
+      ]
+      candidates.find { |candidate| File.file?(candidate) }
+    end
+
+    # pathlib's `/` operator, which is what the oracle joins with: empty and "."
+    # components are dropped, runs of slashes collapse, and an absolute
+    # component resets the path. `File.join` does none of that, and
+    # find_preview_image hands the joined string back to its caller.
+    def self.join_path(*parts)
+      absolute = false
+      segments = []
+      parts.each do |part|
+        str = part.to_s
+        if str.start_with?("/")
+          absolute = true
+          segments.clear
+        end
+        segments.concat(str.split("/").reject { |seg| seg.empty? || seg == "." })
+      end
+      joined = segments.join("/")
+      return "/#{joined}" if absolute
+
+      joined.empty? ? "." : joined
+    end
+
+    # --- CPython string semantics -------------------------------------------
+
+    # `str.splitlines(keepends=True)`.
+    def self.splitlines(text)
+      parts = text.scan(PY_SPLITLINES)
+      parts.pop if parts.last == "" # the scan always closes with an empty match
+      parts
+    end
+
+    # `re.sub(r"\s+", " ", text).strip()` — the excerpt normalizer shared with
+    # the prompt layer. Exposed because `String#strip` also eats NUL, which
+    # Python's does not, and because both `\s+` and the final strip must use the
+    # CPython whitespace set.
+    def self.collapse_whitespace(text)
+      collapsed = text.gsub(/[#{PY_SPACE_CLASS}]+/, " ")
+      # After collapsing, every whitespace run is a single ASCII space, so
+      # trimming leading/trailing spaces reproduces str.strip() exactly.
+      collapsed.sub(/\A +/, "").sub(/ +\z/, "")
+    end
+
+    # Python truthiness, which is what `data.get("title") or ""` tests.
+    def self.truthy?(value)
+      case value
+      when nil, false then false
+      when String, Array, Hash then !value.empty?
+      when Numeric then !value.zero?
+      else true
+      end
+    end
+
+    # Python's `str()` over the scalar shapes a YAML front-matter value can take.
+    # Containers and floats fall through to Ruby's #to_s, which formats
+    # differently from CPython's repr() — see DEVIATIONS in the port notes.
+    def self.py_str(value)
+      case value
+      when String then value
+      when true then "True"
+      when false then "False"
+      when nil then "None"
+      else value.to_s
+      end
+    end
+
+    # --- internals ------------------------------------------------------------
+
+    def self.strip_slashes(text)
+      text.sub(%r{\A/+}, "").sub(%r{/+\z}, "")
+    end
+    private_class_method :strip_slashes
+
+    def self.find_key(lines, prefix)
+      lines.index { |line| line.start_with?(prefix) } || -1
+    end
+    private_class_method :find_key
+
+    # Index just past a key line and any indented continuation lines
+    # (folded/literal scalars, nested maps).
+    def self.end_of_block(lines, idx)
+      j = idx + 1
+      while j < lines.length && (lines[j].start_with?(" ", "\t") || blank?(lines[j]))
+        # A blank line only continues the block if an indented line follows.
+        break if blank?(lines[j]) &&
+                 !(j + 1 < lines.length && lines[j + 1].start_with?(" ", "\t"))
+
+        j += 1
+      end
+      j
+    end
+    private_class_method :end_of_block
+
+    # `line.strip() == ""`: True when the line is empty or all-whitespace.
+    def self.blank?(line)
+      line.match?(/\A[#{PY_SPACE_CLASS}]*\z/)
+    end
+    private_class_method :blank?
+
+    # `Path.read_text(encoding="utf-8")` (universal newlines) or `read_bytes()
+    # .decode("utf-8")`. Both raise on unreadable/undecodable input; the oracle
+    # warns and returns None for either, so this returns nil.
+    def self.read_text(path, universal_newlines: true)
+      raw = begin
+        File.binread(path.to_s)
+      rescue SystemCallError, IOError => e
+        log(:warn, "Failed to read #{path}: #{e.message}")
+        return nil
+      end
+
+      text = raw.force_encoding(Encoding::UTF_8)
+      unless text.valid_encoding?
+        # Python raises UnicodeDecodeError here and the oracle handles it
+        # identically to an OSError.
+        log(:warn, "Failed to read #{path}: invalid UTF-8")
+        return nil
+      end
+
+      universal_newlines ? text.gsub(/\r\n?/, "\n") : text
+    end
+    private_class_method :read_text
+
+    # `.bak` then atomic rename. On failure the `.bak` is deliberately left
+    # behind (the oracle only unlinks the temp file) — it is the user's only
+    # copy if the rename tore.
+    def self.write_atomically(path, new_text)
+      target = path.to_s
+      backup = "#{target}.bak"
+      tmp = "#{target}.tmp~"
+      begin
+        FileUtils.cp(target, backup, preserve: true)
+        File.binwrite(tmp, new_text)
+        File.rename(tmp, target)
+        File.unlink(backup) if File.exist?(backup)
+      rescue SystemCallError, IOError => e
+        log(:warn, "Failed to update front matter in #{path}: #{e.message}")
+        File.unlink(tmp) if File.exist?(tmp)
+        return false
+      end
+      true
+    end
+    private_class_method :write_atomically
+
+    # The engine's shared logger lives in the `Zer0ImageGenerator::Logging`
+    # slice (info/warn/success/debug/step class methods, --verbose-gated debug).
+    # Route through it when present. Until it is loaded, warnings still have to
+    # reach a human — a silently-skipped front-matter write is the worst failure
+    # mode this file has — so fall back to stderr. `:debug` is dropped by the
+    # fallback because the shared logger gates it on --verbose (off by default).
+    def self.log(level, message)
+      logger = Zer0ImageGenerator.const_defined?(:Logging, false) ? Zer0ImageGenerator::Logging : nil
+      if logger.respond_to?(level)
+        logger.public_send(level, message)
+      elsif level != :debug
+        $stderr.puts("[#{level.to_s.upcase}] #{message}")
+      end
+    end
+    private_class_method :log
+  end
+end

data/lib/zer0_image_generator/engine.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Pure-Ruby entry point for the image engine.
+#
+# Deliberately separate from `lib/zer0-image-generator.rb`: that file is the
+# gem's Bundler entry point and conditionally pulls in Jekyll to register the
+# `jekyll preview-images` command. This file loads the engine and nothing else,
+# so the Rails app in `web/` (and any plain script) can drive the same code
+# without dragging Jekyll in.
+#
+# Stdlib only, by policy — the gem stays dependency-light, so anything required
+# here must ship with Ruby.
+
+require_relative "version"
+require_relative "support/py_random"
+
+module Zer0ImageGenerator
+  # Raised for engine-level failures that callers are expected to surface to a
+  # human — a missing credential, an unreadable site, a provider refusal.
+  class Error < StandardError; end
+end