zer0-image-generator 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c105d9c5a9aab3c6b772c558fbf070788058e929a4ce846e9cbaa5da019e117d
-  data.tar.gz: '0597cbdb685887b2733b29123aee8704366d96b1bca6781395a7bccf760d3748'
+  metadata.gz: 15dc8c56843fbbebfe9e26afc0f48cb54cfc75cc8a9b938db40a0cd9f6cd389d
+  data.tar.gz: b7ab70a697bbc9161ec8ccc16dfced4fb4e560763ba020803c682e25a0803d0b
 SHA512:
-  metadata.gz: e791021d473f1b0b0246973a2e9dab6add20919b5c96b1e2df0806fa12269fd6ea3053ee20b3094dfa1aa365bcdb38ca5ea3e5f315116ff83fd073429aa40487
-  data.tar.gz: edd3c2fcad1bbe57e3b87bab8a30b168855865b4ab79a6fc215727d8cbc9a42467da587bde09217798c0eb7bd2b40552db67ca5217ab7de71f7e08bf41a36f0d
+  metadata.gz: 187f71882b0092c5d99c1df0b1685d941770bbc1dbaf62dfa330a9ec17433248423669327f6188a957b1a9ec31ece5b12b1e00f04c274828c17572d9a2a94952
+  data.tar.gz: 2db8e40e2698daba7d05ad47f3c981f608ad118841f3efcb21661616295d9b62f1d1a1788a2509ae7c45e1f538685f1baa6f7505a1b7702bc701fea9ad9ffcc3

data/CHANGELOG.md

@@ -5,6 +5,13 @@ 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.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)
+
+
+### Features
+
+* **svg:** adopt the svg-art-kit authoring loop (hook, lint, sweep, critic) ([#6](https://github.com/bamr87/zer0-image-generator/issues/6)) ([d45b28f](https://github.com/bamr87/zer0-image-generator/commit/d45b28f1a8192bc154f4f8c79f433769d4e95e12))
+
 ## [0.5.0](https://github.com/bamr87/zer0-image-generator/compare/zer0-image-generator-v0.4.0...zer0-image-generator/v0.5.0) (2026-07-15)
 
 

data/README.md

@@ -1,15 +1,10 @@
 # zer0-image-generator
 
-[![Test](https://github.com/bamr87/zer0-image-generator/actions/workflows/test.yml/badge.svg)](https://github.com/bamr87/zer0-image-generator/actions/workflows/test.yml)
-[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Test](https://github.com/bamr87/zer0-image-generator/actions/workflows/test.yml/badge.svg)](https://github.com/bamr87/zer0-image-generator/actions/workflows/test.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
 
-AI preview/social images for **any Jekyll site** — Claude directs and reviews,
-an image model renders, and your front matter gets wired up automatically.
+AI preview/social images for **any Jekyll site** — Claude directs and reviews, an image model renders, and your front matter gets wired up automatically.
 
-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**.
+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**.
 
 ## How it works
 
@@ -29,9 +24,7 @@ Each post/page without a preview goes through a three-stage pipeline:
 | gemini      | gemini-2.5-flash-image                     | `GEMINI_API_KEY`    |
 | local       | deterministic template SVG → PNG           | none (CI-safe)      |
 
-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.
+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.
 
 ## Install
 
@@ -44,8 +37,7 @@ group :jekyll_plugins do
 end
 ```
 
-Requires `python3` (3.9+) with PyYAML — the command checks and tells you if
-either is missing:
+Requires `python3` (3.9+) with PyYAML — the command checks and tells you if either is missing:
 
 ```bash
 python3 -m pip install pyyaml
@@ -61,8 +53,7 @@ bundle exec jekyll preview-images                  # generate them
 
 ### Standalone (no Ruby required)
 
-The engine is one dependency-light Python file. Copy it anywhere and run it
-from your site root:
+The engine is one dependency-light Python file. Copy it anywhere and run it from your site root:
 
 ```bash
 curl -o preview_generator.py \
@@ -72,8 +63,7 @@ python3 preview_generator.py --dry-run
 
 ## Configuration
 
-Everything lives under `preview_images:` in your `_config.yml`. Shown with
-defaults:
+Everything lives under `preview_images:` in your `_config.yml`. Shown with defaults:
 
 ```yaml
 preview_images:
@@ -101,13 +91,9 @@ preview_images:
   auto_prefix: true           # ... and it is re-added for existence checks
 ```
 
-Priority per file: author overrides → collection styles → CLI flags →
-environment variables → `_config.yml` → built-in defaults.
+Priority per file: author overrides → collection styles → CLI flags → environment variables → `_config.yml` → built-in defaults.
 
-Jekyll's own top-level `source:` key is honored automatically: on a site with
-`source: pages` (content, assets, and `_data` under `pages/`), every disk path
-above resolves inside `pages/` while front-matter values keep their site-URL
-form. No extra configuration needed.
+Jekyll's own top-level `source:` key is honored automatically: on a site with `source: pages` (content, assets, and `_data` under `pages/`), every disk path above resolves inside `pages/` while front-matter values keep their site-URL form. No extra configuration needed.
 
 ### Recipe: standard Jekyll site with jekyll-seo-tag
 
@@ -120,8 +106,7 @@ preview_images:
   authors_file: ''
 ```
 
-Generated front matter: `image: /assets/images/previews/my-post.png` — exactly
-what `jekyll-seo-tag` turns into `og:image`.
+Generated front matter: `image: /assets/images/previews/my-post.png` — exactly what `jekyll-seo-tag` turns into `og:image`.
 
 ### Recipe: zer0-mistakes theme
 
@@ -133,28 +118,38 @@ preview_images:
   # front_matter_key/preview + /assets prefixing are already the defaults
 ```
 
+### Recipe: children's book collections (drsai)
+
+The [drsai storybook platform](https://github.com/bamr87/drsai) publishes picture books through the zer0-mistakes `books` collection and uses this gem for each story's social/preview banner. Match the banner style to the book's illustration bible so cards and pages read as one book:
+
+```yaml
+preview_images:
+  provider: openai
+  collections: [books]
+  # each story's `preview` starts as its first illustration plate; this gem
+  # fills banners for pages that don't have one yet
+  style: >-
+    cozy warm digital watercolor storybook art, soft colored-pencil outlines,
+    rounded friendly shapes, sun-baked desert palette, gentle golden-hour light
+  style_modifiers: kid-friendly, never photorealistic, never dark or scary
+```
+
+Note the division of labor: this gem renders **one banner per page** keyed on front matter; the *in-story* illustration plates (several per story, tracked in each page's `illustrations:` list) are rendered by drsai's own `tools/generate_illustrations.py` against the same OpenAI credential.
+
 ### Batch performance
 
-The engine parallelizes **within one invocation** (4 workers by default, `-j N`
-to change). For many files, one collection run beats a loop of single-file
-runs — the loop pays process startup per file and never engages the pool:
+The engine parallelizes **within one invocation** (4 workers by default, `-j N` to change). For many files, one collection run beats a loop of single-file runs — the loop pays process startup per file and never engages the pool:
 
 ```bash
 bundle exec jekyll preview-images --collection posts --parallel 6   # ✓ parallel
 for f in ...; do jekyll preview-images -f "$f"; done                # ✗ serial
 ```
 
-Claude orchestration runs at `claude_effort: low` by default — right-sized for
-a short art brief and a render verdict. Raise it (or set `claude_model`) if you
-want deeper art direction at the cost of latency.
+Claude orchestration runs at `claude_effort: low` by default — right-sized for a short art brief and a render verdict. Raise it (or set `claude_model`) if you want deeper art direction at the cost of latency.
 
 ### Per-collection styles
 
-Give each collection its own visual identity — tutorials render differently
-from field notes, docs differently from reviews. Any of `style`,
-`style_modifiers`, `size`, `quality`, and `model` can be set per collection;
-everything else inherits the global config. A file's collection comes from its
-`_<name>` directory; author overrides still win over collection styles.
+Give each collection its own visual identity — tutorials render differently from field notes, docs differently from reviews. Any of `style`, `style_modifiers`, `size`, `quality`, and `model` can be set per collection; everything else inherits the global config. A file's collection comes from its `_<name>` directory; author overrides still win over collection styles.
 
 ```yaml
 preview_images:
@@ -171,8 +166,7 @@ preview_images:
 
 ### Per-author style overrides
 
-If `authors_file` points at a YAML map, an author's `preview:` block overrides
-`style`, `style_modifiers`, `size`, `quality`, and `model` for their pages:
+If `authors_file` points at a YAML map, an author's `preview:` block overrides `style`, `style_modifiers`, `size`, `quality`, and `model` for their pages:
 
 ```yaml
 # _data/authors.yml
@@ -184,8 +178,7 @@ cassandra:
 
 ## Credentials
 
-The renderer needs its own key (default: `OPENAI_API_KEY`). Claude
-orchestration accepts any ONE of, in order — it is optional:
+The renderer needs its own key (default: `OPENAI_API_KEY`). Claude orchestration accepts any ONE of, in order — it is optional:
 
 ```bash
 export CLAUDE_CODE_OAUTH_TOKEN="..."   # 1. from `claude setup-token` (Pro/Max)
@@ -194,14 +187,11 @@ export ANTHROPIC_API_KEY="..."         # 3. console.anthropic.com
 # 4. nothing — a logged-in `claude` CLI is used automatically
 ```
 
-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.
+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.
 
 ## 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):
+`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):
 
 ```text
 --dry-run --verbose --force --list-missing
@@ -214,9 +204,7 @@ globally, so use long forms there; the Python CLI keeps all short flags):
 --assets-prefix PREFIX  --no-auto-prefix            --batch N  --log-file FILE
 ```
 
-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.
+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.
 
 ## CI usage
 
@@ -228,28 +216,25 @@ The `local` provider rasterizes its SVG via the first available of
   run: bundle exec jekyll preview-images
 ```
 
-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).
+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).
 
 ## 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.
+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.
 
 ## Development
 
 ```bash
-python3 test/test_preview_generator.py      # 98 unit tests, zero network
+python3 test/test_preview_generator.py      # 108 unit tests, zero network
+python3 test/test_freesvg.py                # FreeSVG client/cache tests, network mocked
 python3 -m py_compile lib/zer0_image_generator/preview_generator.py
 gem build zer0-image-generator.gemspec
 cd test/fixture-site && bundle install
 bundle exec jekyll preview-images --dry-run # integration fixture
 ```
 
+When touching SVG code (the local template, sanitizer, rasterizer chain), use the authoring loop in [tools/svg/](tools/svg/README.md): a PostToolUse hook lints and rasterizes every `.svg` write so the agent sees what it drew, `banner-seed.py` sweeps the engine's real template across seeds into a contact sheet, and the `svg-critic` subagent keeps render/critique churn out of the main context. The [showcase](docs/showcase/README.md) walks the whole pipeline with the intermediate images each piece iterated through.
+
 Conventional Commits drive releases via release-please. One concern per PR.
 
 ## License

data/lib/zer0_image_generator/preview_generator.py

@@ -1295,8 +1295,11 @@ def render_local_svg(title: str, seed: int) -> str:
         return rng % max(bound, 1)
 
     w, h = SVG_WIDTH, SVG_HEIGHT
+    safe_title = title.replace("&", "&amp;").replace("<", "&lt;")
     parts = [
-        f'<svg xmlns="{SVG_NS}" viewBox="0 0 {w} {h}" width="{w}" height="{h}">',
+        f'<svg xmlns="{SVG_NS}" viewBox="0 0 {w} {h}" width="{w}" height="{h}" '
+        f'role="img">',
+        f'<title>Preview banner: {safe_title}</title>',
         f'<rect width="{w}" height="{h}" fill="{pal[0]}"/>',
     ]
     # Sky bands

data/lib/zer0_image_generator/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zer0-image-generator
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Amr Abdel
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-07-15 00:00:00.000000000 Z
+date: 2026-07-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll