zer0-image-generator 0.6.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15dc8c56843fbbebfe9e26afc0f48cb54cfc75cc8a9b938db40a0cd9f6cd389d
-  data.tar.gz: b7ab70a697bbc9161ec8ccc16dfced4fb4e560763ba020803c682e25a0803d0b
+  metadata.gz: 94ef9be8acf2f3c67c09f13a916886b5cb902677a949948833ee75bf11da456b
+  data.tar.gz: 67da956c8c22361911764a8103a62a3075c615ea8ecde4145e1cf61a39152489
 SHA512:
-  metadata.gz: 187f71882b0092c5d99c1df0b1685d941770bbc1dbaf62dfa330a9ec17433248423669327f6188a957b1a9ec31ece5b12b1e00f04c274828c17572d9a2a94952
-  data.tar.gz: 2db8e40e2698daba7d05ad47f3c981f608ad118841f3efcb21661616295d9b62f1d1a1788a2509ae7c45e1f538685f1baa6f7505a1b7702bc701fea9ad9ffcc3
+  metadata.gz: 81cdf3446d4352ec701b51a85e7051df57ae891a6cd2f22803cb5a383350076b7d4afc52a676c181bc5eb5832cbe99b0fd557c84732b03de945050a888d92403
+  data.tar.gz: a6687659e49d06b6b32cfb6c1e077ff625e014f88cef5e3be3d20c131720d59808370fc436d9f1d74d548b9679c05bf0fa4ffe3c3faaed22c49ca057be081460

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0](https://github.com/bamr87/zer0-image-generator/compare/zer0-image-generator/v0.7.0...zer0-image-generator/v0.8.0) (2026-10-03)
+
+
+### Features
+
+* **config:** make `rasterizer` a site-level knob (SVG-only mode) ([9f53375](https://github.com/bamr87/zer0-image-generator/commit/9f53375dbefb2a3d1dfc5eddab0801378b2949e6))
+* **local:** content-aware SVG banners + site-level `rasterizer` knob ([2bddc3f](https://github.com/bamr87/zer0-image-generator/commit/2bddc3f57dbd3926a180d5eb241087f202fd0fcb))
+* **local:** content-aware SVG banners instead of one recoloured skyline ([dc0b4bb](https://github.com/bamr87/zer0-image-generator/commit/dc0b4bb2a9b177614d1aa0c765726b8fcc779bf2))
+* **providers:** capability ladder — auto, claude SVG, shared collection default ([55da59f](https://github.com/bamr87/zer0-image-generator/commit/55da59f48b03eb205209cd70d88751a1f75bfab1))
+* **providers:** capability ladder — auto, Claude-authored SVG, shared collection default ([0088a94](https://github.com/bamr87/zer0-image-generator/commit/0088a949d3308c956a3a035dd03a12b33c424bd4))
+* **providers:** Grok OAuth for the xAI renderer, API key as the fallback ([#19](https://github.com/bamr87/zer0-image-generator/issues/19)) ([c57e527](https://github.com/bamr87/zer0-image-generator/commit/c57e52799aa744110f1ce093a0bfb542ff971b0e))
+
+## [0.7.0](https://github.com/bamr87/zer0-image-generator/compare/zer0-image-generator/v0.6.0...zer0-image-generator/v0.7.0) (2026-07-24)
+
+
+### Features
+
+* **abc:** ABC alphabet-book illustration plugin ([b817ffd](https://github.com/bamr87/zer0-image-generator/commit/b817ffd83ef3728933cd4bd70b8a66cc16543599))
+* Dockerized Rails control panel + pure-Ruby engine port ([#8](https://github.com/bamr87/zer0-image-generator/issues/8)) ([a03ff9d](https://github.com/bamr87/zer0-image-generator/commit/a03ff9d0e37aee29c32e5e696d8cf04bfdeb2075))
+
 ## [0.6.0](https://github.com/bamr87/zer0-image-generator/compare/zer0-image-generator/v0.5.0...zer0-image-generator/v0.6.0) (2026-07-23)
 
 

data/README.md

@@ -6,6 +6,19 @@ AI preview/social images for **any Jekyll site** — Claude directs and reviews,
 
 Extracted from the [zer0-mistakes](https://github.com/bamr87/zer0-mistakes) theme's consolidated engine and generalized: every theme-specific assumption is now a config knob with zer0-compatible defaults, so the theme and this plugin stay **separate but portable**.
 
+Three ways to drive it: the `jekyll preview-images` **Gem/CLI**, the standalone **Python engine**, and a **web app** ([web/](web/README.md)) — a Dockerized Rails control panel that runs a pure-Ruby port of the engine ([lib/zer0_image_generator/](lib/zer0_image_generator/), pinned byte-for-byte against the Python original), so all three share one behavior. In the browser you can:
+
+- register sites, edit their `preview_images:` config, and run generation with a
+  live-streaming log;
+- **forge a standalone image** — Claude directs the art (via a Claude Code OAuth
+token), a renderer produces it, Claude reviews it, and you can process any version further with OpenAI;
+- drive the `tools/svg/` generators from knob forms and browse the example
+  library.
+
+```bash
+SITES_DIR=/path/to/your/jekyll/sites docker compose up --build   # → localhost:3000
+```
+
 ## How it works
 
 Each post/page without a preview goes through a three-stage pipeline:
@@ -19,10 +32,13 @@ Each post/page without a preview goes through a three-stage pipeline:
 | provider    | renderer                                   | credential          |
 | ----------- | ------------------------------------------ | ------------------- |
 | **openai** (default) | gpt-image-2 / dall-e-3 (+ `--enhance`) | `OPENAI_API_KEY`    |
-| xai         | grok-2-image                               | `XAI_API_KEY`       |
+| xai         | grok-2-image                               | Grok OAuth token or `XAI_API_KEY` |
 | stability   | Stable Diffusion XL                        | `STABILITY_API_KEY` |
 | gemini      | gemini-2.5-flash-image                     | `GEMINI_API_KEY`    |
-| local       | deterministic template SVG → PNG           | none (CI-safe)      |
+| local       | content-aware deterministic SVG per page   | none (CI-safe)      |
+| **claude**  | Claude AUTHORS the banner as SVG           | Claude credential   |
+| **default** | one shared SVG per collection/section      | none (the floor)    |
+| **auto**    | picks the best rung below                  | whatever is wired   |
 
 Claude never renders pixels (the Anthropic API has no image endpoint); without a Claude credential the analyze/review stages degrade gracefully to a template prompt and the renderer still runs.
 
@@ -80,6 +96,9 @@ preview_images:
   claude_effort: low          # output_config.effort for the brief/review calls
                               # (low = fastest, right-sized for short briefs;
                               #  high = deepest; '' sends no effort parameter)
+  rasterizer: auto            # SVG→PNG tool for the SVG providers (local,
+                              # claude): auto | rsvg | inkscape | magick |
+                              # playwright | none. `none` = SVG-only (below).
   # --- portability knobs (the zer0-isms, now configurable) ---
   collections: [posts]        # list of collections, or 'auto' to discover
                               # them from Jekyll's own `collections:` map
@@ -189,6 +208,31 @@ export ANTHROPIC_API_KEY="..."         # 3. console.anthropic.com
 
 Keys are read from the environment or a git-ignored `.env` at the site root. On a Claude Pro/Max subscription the orchestration costs nothing extra; only the renderer bills per image.
 
+### Grok OAuth (xAI renderer)
+
+`--provider xai` accepts a **Grok OAuth access token** as well as an API key, and tries them in that order — so a SuperGrok / X Premium+ login can render banners without a console.x.ai key:
+
+```bash
+export XAI_OAUTH_TOKEN="..."           # 1. an OAuth access token (GROK_OAUTH_TOKEN also works)
+#    …or a credentials file from a Grok login — ~/.grok/auth.json by default,
+#    or set XAI_OAUTH_CREDENTIALS / GROK_OAUTH_CREDENTIALS to point elsewhere
+export XAI_API_KEY="..."               # 2. console.x.ai — and the automatic fallback
+```
+
+Both are `Authorization: Bearer` credentials on the same endpoint, which is what makes the fallback real rather than cosmetic: **if the OAuth token is expired or the API rejects it (401/403) and an `XAI_API_KEY` is present, the same request is retried with the key** and the page still renders. A token whose recorded expiry has already passed is skipped without spending a request at all. Other failures (a 500, a bad prompt) are *not* credential problems, so they never burn the fallback.
+
+The engine only ever *reads* a token — it does not mint or refresh one, and never writes to the credentials file, because xAI publishes neither a device-code endpoint nor a public client id. Re-run your Grok login when a token expires.
+
+| variable | effect |
+| --- | --- |
+| `XAI_OAUTH_TOKEN` / `GROK_OAUTH_TOKEN` | OAuth access token, tried first |
+| `XAI_OAUTH_CREDENTIALS` / `GROK_OAUTH_CREDENTIALS` | explicit path to a Grok credentials JSON (wins outright over `~/.grok/auth.json`) |
+| `XAI_API_KEY` | API key — the fallback rung |
+| `XAI_AUTH` | `auto` (default), `oauth` or `api_key` — pin one rung |
+| `XAI_BASE_URL` | override `https://api.x.ai/v1` |
+
+The run's config banner names the credential it picked (`xai auth: XAI_OAUTH_TOKEN (Grok OAuth token), falling back to XAI_API_KEY (xAI API key)`), and a fallback mid-run is logged as a warning — a silent swap would hide a token that has quietly stopped working.
+
 ## CLI reference
 
 `jekyll preview-images` exposes the engine's flags (Jekyll claims `-s/-d/-p` globally, so use long forms there; the Python CLI keeps all short flags):
@@ -204,8 +248,54 @@ Keys are read from the environment or a git-ignored `.env` at the site root. On
 --assets-prefix PREFIX  --no-auto-prefix            --batch N  --log-file FILE
 ```
 
+### `provider: auto` — the capability ladder
+
+Set `provider: auto` and the engine uses the best renderer the environment can actually reach:
+
+1. **A raster image API** (`OPENAI_API_KEY` / `XAI_API_KEY` or a Grok OAuth token / `STABILITY_API_KEY` / `GEMINI_API_KEY`). If a Claude credential is *also* present, `prompt_engine: claude` has Claude write the art brief that renderer works from, and vision-review the result — the full three-stage pipeline.
+2. **A Claude credential alone** → the `claude` provider, where Claude *authors* the banner as SVG. Claude cannot render pixels, but vector markup is the one image format a language model can emit directly, so this is genuine per-article art with no image-model spend. Output goes through the same sanitizer as every other SVG, so a model that emits a `<script>`, a remote `href`, or a raster `data:` payload gets it stripped rather than committed.
+3. **Nothing wired** → the `default` provider: **one shared banner per collection/section**.
+
+Why a shared default rather than per-page procedural art: with no credential anywhere, generating a distinct composition per page produces N near-identical images under N names — 91 flow fields differing only by palette read as one picture repeated, and cost 91 files to say so. The floor is honest about that instead. Pages never touched by an image model share one deliberate banner for their section, and the repo carries one file per section rather than one per page.
+
+Auto requires a real Claude *credential* (`CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_AUTH_TOKEN` / `ANTHROPIC_API_KEY`) to leave rung 3 — deliberately not the same test as `AnthropicClient.available()`, which also accepts a `claude` binary on `PATH`. An installed CLI is not proof of a working login, and promoting an unauthenticated machine off the default rung would fail every page at generation time instead of quietly shipping the shared banner. An explicit `--provider claude` still rides the CLI, because that is a human asserting it works.
+
+An explicitly configured provider is always honored as written; only `auto` walks the ladder.
+
+### Content-aware local banners
+
+The `local` renderer does not draw one template in six colours. It reads the page's own context — its **section**, **tags**, **title**, **description** and **body** — and picks both the composition and the palette from it, so a shell hack and a narrative essay do not come out looking like siblings.
+
+| composition | reads as | selected by |
+| --- | --- | --- |
+| `circuit` | orthogonal traces, pads, vias, chips | `hacks`, shell/docker/git/ci vocabulary |
+| `pixelscene` | pixel-art side-scroller | `tools`, reviews, editors, games |
+| `flowfield` | streamlines through a noise field | `field-notes`, essays, AI/automation |
+| `lowpoly` | faceted gradient field | `docs`, guides, architecture, schemas |
+| `starfield` | constellations over layered ridges | security, secrets, audits, exploration |
+
+Fields are **weighted, not pooled**: a section name is a deliberate editorial choice and tags and titles are hand-written, so they carry most of the signal, while the long incidental body is capped. Matching is on whole words — a bare substring test fires `ci` inside "de**ci**sion" and drags an entire dev blog toward one look. With no keyword hit anywhere the seed picks, so every page still gets art.
+
+Determinism is unchanged and remains a hard contract: the same article renders the same bytes on both engines. The seed comes from the article's **content** rather than its filename, so retitling or re-tagging a piece re-rolls its art — and two posts whose filenames merely sort next to each other no longer come out kin.
+
+Every composition is authored at the banner frame (1536×1024), so the sanitizer's forced `viewBox` is a no-op rather than a squash, and each emits `role="img"` plus a `<title>`.
+
 The `local` provider rasterizes its SVG via the first available of `rsvg-convert` (`brew install librsvg` / `apt install librsvg2-bin`), `inkscape`, ImageMagick, or a vendored Playwright helper.
 
+### SVG-only sites
+
+`rasterizer: none` makes the vector banner the deliverable: the SVG providers (`local`, `claude`) write the sanitized `.svg`, skip rasterization entirely, and stamp `preview: /assets/images/previews/<slug>.svg` into front matter. No PNG is produced and none is expected — the engine says "SVG-only mode" instead of nagging about a missing librsvg.
+
+```yaml
+preview_images:
+  provider: local             # the deterministic, key-free SVG renderer
+  rasterizer: none            # ... and keep its output as SVG
+```
+
+It is a site-level policy, so it belongs in `_config.yml` — every entry point (the `jekyll preview-images` CLI, a bare `python3 preview_generator.py`, the web app, CI) picks it up with no per-invocation flag. `--rasterizer` and `IMAGE_RASTERIZER` still override it for a one-off run.
+
+Banners land at roughly 10–15 KB each instead of 1–2 MB, they diff as text in review, and they scale to any viewport. The trade-off: some social-card scrapers still prefer a raster `og:image`, so keep `rasterizer: auto` if link-preview cards matter more than repository weight.
+
 ## CI usage
 
 ```yaml
@@ -218,6 +308,20 @@ The `local` provider rasterizes its SVG via the first available of `rsvg-convert
 
 Generation is script-driven on demand — it is never part of `jekyll build` (builds stay fast, deterministic, and secret-free; GitHub Pages safe mode is irrelevant to it).
 
+## ABC alphabet-book plugin
+
+Beyond one-banner-per-page previews, this gem is the **illustration plugin** for the fleet's children's-book pipeline: it owns the art-style catalog and composes one text-free plate per alphabet letter of a toddler ABC book. The [zer0-CMS](https://github.com/bamr87/zer0-CMS) Rails wizard picks an `art_style` and emits an *ABC Book Spec*; [drsai](https://github.com/bamr87/drsai) ships it into the `books` collection and renders each letter's prompt.
+
+```ruby
+require "zer0_image_generator/abc"
+Zer0ImageGenerator::Abc::StylePack.default.render_prompt(
+  letter: "A", word: "Automation",
+  subject: "a friendly robot arm stacking soft blocks",
+  style: "isometric-tech-toy")
+```
+
+The style catalog (`lib/zer0_image_generator/abc/art_styles.yml`) is the source of truth shared, by vendored copy, with zer0-CMS and the theme. See [docs/abc-plugin.md](docs/abc-plugin.md).
+
 ## Relationship to zer0-mistakes
 
 The [zer0-mistakes](https://github.com/bamr87/zer0-mistakes) theme renders `preview:` values with a pure-Liquid include (GitHub-Pages-safe, no plugin needed) and currently vendors this engine at `scripts/lib/preview_generator.py`. This repo is the portable home: the theme is expected to consume the gem (or curl the engine from here) in a follow-up, so there is exactly ONE engine.

data/lib/zer0_image_generator/abc/style_pack.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Zer0ImageGenerator
+  # ABC / alphabet-book illustration support.
+  #
+  # This module is the plugin seam by which the fleet's content engine
+  # (zer0-CMS) and publisher (drsai) drive THIS gem to illustrate children's
+  # ABC books. It is deliberately self-contained and ADDITIVE: it requires
+  # nothing from the byte-identity engine port (constants.rb / prompt.rb /
+  # runner.rb) and changes none of it, so the deterministic `local` provider
+  # and every committed sample stay bit-for-bit unchanged.
+  #
+  # It owns two things:
+  #   * the art-style catalog (art_styles.yml) — the SOURCE OF TRUTH shared,
+  #     by vendored copy, with zer0-CMS and the zer0-mistakes theme; and
+  #   * StylePack, which composes one raster prompt per alphabet letter from a
+  #     style id + a few knobs, in a way that is stable and reproducible.
+  #
+  # The composed prompt is text-free by contract (the big letter is HTML
+  # typography in the theme), so raster models never garble spelling.
+  module Abc
+    CATALOG_PATH = File.join(__dir__, "art_styles.yml")
+
+    class UnknownStyle < StandardError; end
+
+    # Loads and indexes art_styles.yml. Frozen after load; cheap to keep one
+    # shared instance via .default, or build your own for a custom catalog.
+    class StylePack
+      attr_reader :version, :styles, :palettes, :backgrounds, :lettering,
+                  :moods, :safety_suffix
+
+      def self.default
+        @default ||= from_file(CATALOG_PATH)
+      end
+
+      def self.from_file(path)
+        new(YAML.safe_load_file(path))
+      end
+
+      def initialize(catalog)
+        @version       = catalog.fetch("version", 1)
+        @styles        = index(catalog.fetch("styles"))
+        options        = catalog.fetch("options", {})
+        @palettes      = index(options.fetch("palettes", []))
+        @backgrounds   = index(options.fetch("backgrounds", []))
+        @lettering     = index(options.fetch("lettering", []))
+        @moods         = index(options.fetch("moods", []))
+        @safety_suffix = squish(catalog.fetch("safety_suffix", ""))
+        freeze
+      end
+
+      # All selectable style ids, sorted — handy for a wizard's menu.
+      def style_ids
+        @styles.keys.sort
+      end
+
+      def style(id)
+        @styles[id.to_s] || raise(UnknownStyle, "unknown ABC art style: #{id.inspect} " \
+                                                 "(known: #{style_ids.join(', ')})")
+      end
+
+      def style?(id)
+        @styles.key?(id.to_s)
+      end
+
+      # Compose the raster prompt for a single letter.
+      #
+      #   letter  — "A".."Z" (rendered by the theme, never drawn into the art)
+      #   word    — the concept the letter stands for, e.g. "Automation"
+      #   subject — a concrete, drawable scene for the word, e.g.
+      #             "a friendly robot arm stacking blocks"
+      #   style   — a style id from the catalog (String/Symbol)
+      #   palette:/background:/mood: — option ids; nil falls back to the
+      #             style's defaults (palette) or a sensible default.
+      #
+      # Returns a single-line String prompt. Deterministic: same inputs → same
+      # bytes, so committed books re-render identically.
+      def render_prompt(letter:, word:, subject:, style:, palette: nil,
+                        background: "plain", mood: "playful")
+        sty = style(style)
+        palette_id = palette || sty["default_palette"]
+
+        parts = [
+          squish(sty.fetch("prompt")),
+          fragment(@backgrounds, background),
+          fragment(@palettes, palette_id),
+          "Subject: #{subject.to_s.strip}, standing for the word " \
+          "#{word.to_s.strip.upcase} (letter #{letter.to_s.strip.upcase}).",
+          fragment(@moods, mood),
+          @safety_suffix
+        ].compact.reject(&:empty?)
+
+        squish(parts.join(". ").gsub(/\.\s*\./, ".").strip)
+      end
+
+      # The default HTML lettering hint for a style (theme consumes this).
+      def lettering_for(style_id)
+        style(style_id)["default_lettering"]
+      end
+
+      # A compact, serialisable description of the whole catalog — what a
+      # wizard renders as its style/option menus.
+      def to_menu
+        {
+          "version" => @version,
+          "styles" => @styles.values.map do |s|
+            s.slice("id", "name", "summary", "default_palette",
+                    "default_lettering", "best_for")
+          end,
+          "palettes"    => menu_of(@palettes),
+          "backgrounds" => menu_of(@backgrounds),
+          "lettering"   => menu_of(@lettering),
+          "moods"       => menu_of(@moods)
+        }
+      end
+
+      private
+
+      def index(list)
+        list.each_with_object({}) { |item, acc| acc[item.fetch("id")] = item }.freeze
+      end
+
+      def menu_of(hash)
+        hash.values.map { |v| v.slice("id", "name") }
+      end
+
+      def fragment(catalog, id)
+        return nil if id.nil?
+
+        entry = catalog[id.to_s]
+        return nil if entry.nil?
+
+        frag = entry["fragment"]
+        frag.nil? ? nil : squish(frag)
+      end
+
+      # Collapse folded-YAML newlines / runs of whitespace into single spaces.
+      def squish(text)
+        text.to_s.gsub(/\s+/, " ").strip
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/abc.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require_relative "abc/style_pack"
+
+module Zer0ImageGenerator
+  module Abc
+    # High-level plugin entry point: turn an ABC Book Spec (the JSON/YAML the
+    # zer0-CMS engine emits and drsai ships) into concrete render work, using
+    # the shared art-style catalog for prompt composition.
+    #
+    # This is what makes zer0-image-generator "a plugin" of the pipeline: the
+    # content engine owns WHAT each letter means; this gem owns HOW it looks and
+    # how it renders. Both sides agree on the StylePack catalog and the spec
+    # shape below.
+    module Plugin
+      module_function
+
+      # A single unit of render work — mirrors drsai's tools Job so either the
+      # Python illustrator or this gem's Runner can consume a plan.
+      RenderJob = Struct.new(:letter, :word, :prompt, :out_path, :size, keyword_init: true)
+
+      # Landscape by default reads well for a big centred subject on a card.
+      DEFAULT_SIZE = "1024x1024"
+
+      # Compose a prompt for every letter in `book`, mutating a copy of its
+      # `alphabet` entries to carry a `prompt` (only where one is absent so
+      # hand-authored overrides win). Returns the updated book hash.
+      #
+      # `book` is an ABC Book Spec hash with at least:
+      #   "art_style"  => catalog style id
+      #   "palette"/"background"/"mood" => option ids (optional)
+      #   "alphabet"   => [ { "letter", "word", "subject", "prompt"? }, ... ]
+      def compose_prompts(book, pack: StylePack.default)
+        style      = book.fetch("art_style")
+        palette    = book["palette"]
+        background = book["background"] || "plain"
+        mood       = book["mood"] || "playful"
+
+        alphabet = Array(book["alphabet"]).map do |entry|
+          e = entry.dup
+          if e["prompt"].nil? || e["prompt"].to_s.strip.empty?
+            e["prompt"] = pack.render_prompt(
+              letter: e.fetch("letter"), word: e.fetch("word"),
+              subject: e.fetch("subject"), style: style,
+              palette: palette, background: background, mood: mood
+            )
+          end
+          e
+        end
+
+        book.merge("alphabet" => alphabet)
+      end
+
+      # Build the list of RenderJobs for the letters that still need art.
+      # `root` resolves each entry's leading-slash `image` path; a job is only
+      # emitted when the target file does not already exist (idempotent, like
+      # the drsai illustrator).
+      def build_plan(book, root:, size: DEFAULT_SIZE, pack: StylePack.default)
+        composed = compose_prompts(book, pack: pack)
+        Array(composed["alphabet"]).filter_map do |entry|
+          image = entry["image"]
+          next if image.nil? || image.to_s.empty?
+
+          out = File.join(root.to_s, image.to_s.sub(%r{\A/}, ""))
+          next if File.exist?(out)
+
+          RenderJob.new(
+            letter: entry["letter"], word: entry["word"],
+            prompt: entry["prompt"], out_path: out, size: size
+          )
+        end
+      end
+    end
+  end
+end

data/lib/zer0_image_generator/all.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# Loads the entire engine in dependency order.
+#
+# The individual files require only their immediate collaborators, so that a
+# single slice (a generator, the sanitizer) can be pulled in on its own. This
+# file is the "give me everything" entry point the CLI and the Rails app use,
+# where the whole pipeline — config, settings, providers, Claude, the runner —
+# has to be present at once.
+#
+# Stdlib only, by policy.
+
+require_relative "engine"          # version + PyRandom + Error
+require_relative "logging"
+require_relative "stats"
+require_relative "constants"
+require_relative "config"
+require_relative "settings"
+require_relative "content"
+require_relative "prompt"
+require_relative "http"
+require_relative "claude/client"
+require_relative "claude/orchestration"
+require_relative "svg/sanitizer"
+require_relative "svg/local_renderer"
+require_relative "svg/rasterizer"
+require_relative "svg/lint"
+require_relative "svg/pixel_kit"
+require_relative "providers"
+require_relative "runner"
+require_relative "cli"
+
+# ABC / alphabet-book plugin — additive and self-contained (touches none of the
+# byte-identity engine above). Loaded here so the Rails web app and CLI can
+# compose per-letter prompts for the fleet's children's-book pipeline.
+require_relative "abc"
+
+# The parametric SVG generators are optional for a preview run but always wanted
+# by the studio, so load them here too.
+Dir[File.join(__dir__, "svg", "generators", "*.rb")].sort.each { |file| require file }
+require_relative "svg/banner_seed"
+
+# The example library and FreeSVG sourcing are auxiliary features (library
+# browsing, external sourcing) with no role in the generation pipeline, so they
+# are required on demand by the code that uses them (see
+# Zer0ImageGenerator.load_sourcing) rather than pulled into every load.
+
+module Zer0ImageGenerator
+  # Load the on-demand sourcing + library modules. Separate from the core so a
+  # preview run or a studio render never depends on the FreeSVG client being
+  # present; called by the library/freesvg web controllers before they use it.
+  def self.load_sourcing
+    require_relative "library"
+    require_relative "freesvg/cache"
+    require_relative "freesvg/client"
+  end
+end