bridgetown-image-pipeline 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4b506abefc78cfff32c2485ca39d6cd789486ffde30b52060e9aee52a2333510
+  data.tar.gz: 5bf51dd415078908778245b62003e4e36417519bb134e174e470bb77573f2f8c
+SHA512:
+  metadata.gz: 8bd6e9145bf27b2ca0156ee67ce008bae9b3648d458baf7ec46adcbbddd34cc2e777c7436fee2a8882f8c90bb77954574e12149a937cd4d00290d5a7ab9001e3
+  data.tar.gz: 3d2cc00f6657d78ebf7c5777d6d28b8e1e46e116a500e991373c324d140c1c55f4b4ea9e28bfbace1d8d2f5b9c23249b4aa0e02e96633b4a2a1f1cbe08385f21

data/CHANGELOG.md

@@ -0,0 +1,49 @@
+# Changelog
+
+All notable changes to this gem are recorded in this file. The format is
+based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this
+project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-05-15
+
+Initial release. Extracted from
+[rubycentral/rubyconf-2026](https://github.com/rubycentral/rubyconf-2026)
+after six PRs of in-repo iteration (#97, #105, #106, #109, #110, #112).
+
+### Added
+
+- Build-time AVIF and WebP derivative generation via libvips at configurable
+  widths (defaults: 400, 600, 800, 1200, 1600).
+- `picture_tag(src, alt:, sizes:, priority:, **attrs)` ERB helper for
+  responsive `<picture>` elements.
+- `bg_image_block(src, breakpoint_only:, class_suffix:)` ERB helper that
+  emits an inline `<style>` block with `image-set(avif, webp)` declarations
+  plus Tailwind-breakpoint `@media` overrides.
+- `bg_image_class(src, class_suffix:)` ERB helper that returns the derived
+  CSS class name without a `<style>` block, for cases that need the class
+  in multiple places after emitting the block once.
+- `Inspector` (off by default) that walks rendered HTML and rewrites bare
+  `<img src="/images/...">` references into responsive `<picture>` tags.
+- Per-derivative cache under `.bridgetown-cache/image_pipeline/`, keyed by
+  source SHA1 + gem version + config fingerprint.
+- Configurable via initializer block:
+  ```ruby
+  init "bridgetown-image-pipeline" do
+    widths        [400, 800, 1600]
+    auto_rewrite  true
+  end
+  ```
+
+### Notes for adopters
+
+- `output_dir` defaults to `_bridgetown/image_pipeline` (under Bridgetown's
+  framework-reserved prefix). Override via `output_dir: "your/path"` if you
+  need to preserve URLs from a prior in-repo plugin layout.
+- `auto_rewrite` and `fail_on_missing` both default to `false` (conservative
+  defaults). Enable explicitly if you want the Inspector or strict
+  missing-manifest behaviour.
+
+[Unreleased]: https://github.com/beflagrant/bridgetown-image-pipeline/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/beflagrant/bridgetown-image-pipeline/releases/tag/v0.1.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Flagrant LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,241 @@
+# bridgetown-image-pipeline
+
+A Bridgetown 2.0+ plugin that pre-generates responsive **AVIF** and **WebP**
+image derivatives at multiple widths, plus ERB helpers for `<picture>`
+elements and CSS `image-set()` backgrounds.
+
+Used in production at [rubyconf.org](https://rubyconf.org) — homepage mobile
+Lighthouse perf score went from **0.47 → 0.93** after the bg-image migration.
+
+## Features
+
+- **Build-time derivative generation** via libvips. AVIF + WebP at configurable
+  widths (default: 400, 600, 800, 1200, 1600). Source-width-aware (no upscaling).
+- **`picture_tag` helper** — emits `<picture>` with `<source>` per format and
+  an `<img>` fallback with `srcset` + `sizes`.
+- **`bg_image_block` helper** — emits an inline `<style>` block with
+  `background-image: image-set(...)` rules for backgrounds. Tailwind-breakpoint
+  aware. Drop-in replacement for `bg-[url(...)]` utilities.
+- **`Inspector`** (optional, off by default) — rewrites bare `<img>` tags in
+  rendered HTML to wrap them in `<picture>` with the appropriate sources.
+- **Per-derivative cache** keyed by source SHA1 + gem version + config
+  fingerprint. Rebuilds skip unchanged sources.
+
+## Requirements
+
+- Ruby >= 3.2
+- Bridgetown >= 2.0, < 3.0
+- libvips with **HEIF/AVIF plugin** installed (see Installation below)
+
+## Installation
+
+Add to your site's `Gemfile`:
+
+```ruby
+gem "bridgetown-image-pipeline"
+```
+
+Then `bundle install`.
+
+### libvips with HEIF/AVIF support
+
+The plugin needs libvips compiled with HEIF support so it can encode AVIF.
+
+**macOS (Homebrew):**
+
+```sh
+brew install vips
+```
+
+**Ubuntu / Debian:**
+
+```sh
+sudo apt-get install libvips libvips-tools \
+  libheif1 libheif-dev libheif-plugin-aomenc libheif-plugin-libde265
+```
+
+**Verify the encoder works:**
+
+```sh
+vips --vips-config | tr ',' '\n' | grep -i heif
+vips black /tmp/_check.avif 16 16 && rm /tmp/_check.avif
+```
+
+Both lines should succeed. If the second fails with "cannot encode AVIF", the
+libheif AV1 encoder plugin (`libheif-plugin-aomenc` on Ubuntu) is missing.
+
+### Activate the plugin
+
+In `config/initializers.rb`:
+
+```ruby
+Bridgetown.configure do |config|
+  init "bridgetown-image-pipeline"
+end
+```
+
+Or with overrides:
+
+```ruby
+Bridgetown.configure do |config|
+  init "bridgetown-image-pipeline" do
+    widths        [400, 800, 1200, 1600]
+    auto_rewrite  true                          # enable the Inspector
+    output_dir    "_bridgetown/image_pipeline"  # default
+  end
+end
+```
+
+## Usage
+
+### `picture_tag` — responsive `<picture>` elements
+
+```erb
+<%= picture_tag "/images/hero.jpg",
+      alt: "Sandstone formations at sunset",
+      sizes: "(min-width: 1024px) 50vw, 100vw",
+      priority: true,
+      class: "w-full h-auto" %>
+```
+
+Renders:
+
+```html
+<picture>
+  <source type="image/avif" srcset="/_bridgetown/image_pipeline/hero-400.avif 400w, ..." sizes="...">
+  <source type="image/webp" srcset="/_bridgetown/image_pipeline/hero-400.webp 400w, ..." sizes="...">
+  <img src="/_bridgetown/image_pipeline/hero-1600.jpg"
+       srcset="..." sizes="..."
+       width="2400" height="1600"
+       alt="Sandstone formations at sunset"
+       loading="eager" decoding="async" fetchpriority="high"
+       class="w-full h-auto">
+</picture>
+```
+
+`priority: true` adds `loading="eager"` and `fetchpriority="high"`. Use for
+LCP candidates only.
+
+### `bg_image_block` — responsive CSS backgrounds
+
+For decorative `background-image` use cases. Emits an inline `<style>`
+block; the caller uses the returned class on the element:
+
+```erb
+<%= bg_image_block "/images/all-flora.jpg" %>
+<section class="bg-img-all-flora bg-cover p-6 lg:p-20">
+  ...
+</section>
+```
+
+Class names are derived from the source basename:
+`/images/all-flora.jpg` → `bg-img-all-flora`.
+
+**Breakpoint-only backgrounds** (replicates Tailwind's `lg:bg-[url(...)]`):
+
+```erb
+<%= bg_image_block "/images/hero.jpg", breakpoint_only: 1024 %>
+<section class="bg-img-hero bg-cover">  <!-- bg only shows >=1024px -->
+```
+
+**Same source in two contexts** (e.g. hero + decorative loop):
+
+```erb
+<%= bg_image_block "/images/flowers.png", class_suffix: "hero" %>
+<section class="bg-img-flowers-hero ...">
+
+<%= bg_image_block "/images/flowers.png" %>
+<div class="bg-img-flowers ...">
+```
+
+The `class_suffix:` kwarg keeps the two `<style>` blocks from colliding.
+
+### `bg_image_class` — class name only, no style block
+
+When you need to reference the class in multiple places after emitting the
+block once:
+
+```erb
+<%= bg_image_block "/images/flowers.png" %>
+<% klass = bg_image_class("/images/flowers.png") %>
+<section class="<%= klass %> ...">...</section>
+<aside class="<%= klass %> ...">...</aside>
+```
+
+### `Inspector` — auto-wrap bare `<img>` tags
+
+Off by default. Enable in your initializer:
+
+```ruby
+init "bridgetown-image-pipeline" do
+  auto_rewrite true
+end
+```
+
+When on, any rendered `<img src="/images/foo.jpg">` whose source is in the
+manifest is rewritten as a `<picture>` with the appropriate sources.
+Opt-out on a per-tag basis with `data-no-pipeline`:
+
+```html
+<img src="/images/exact-bytes-required.jpg" data-no-pipeline>
+```
+
+## Configuration
+
+All options, with defaults:
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `source_globs` | `["src/images/**/*.{jpg,jpeg,png}"]` | What to process. **Must live under `src/`** — public URLs are derived by stripping the `src/` prefix, so `src/images/foo.jpg` becomes `/images/foo.jpg` in `picture_tag` lookups. Sources outside `src/` are processed but unreachable from templates. |
+| `exclude` | `[]` | Glob patterns to skip |
+| `widths` | `[400, 600, 800, 1200, 1600]` | Derivative widths |
+| `formats` | `[:avif, :webp]` | Output formats (plus original) |
+| `output_dir` | `"_bridgetown/image_pipeline"` | Output path under `output/` |
+| `quality` | `{ avif: 65, webp: 88, jpeg: 88 }` | Per-format quality |
+| `auto_rewrite` | `false` | Enable the Inspector |
+| `fail_on_missing` | `false` | Raise vs. warn on missing manifest |
+| `breakpoints` | `{ 640 => 400, 768 => 600, 1024 => 800, 1280 => 1200 }` | Tailwind-style breakpoints for `bg_image_block` |
+| `default_width` | `1600` | Default tier for `bg_image_block`'s un-prefixed rule |
+
+## Gotcha: Tailwind v4 and `bg-[url(...)]` in docs
+
+Tailwind v4 auto-scans every file from the CSS entrypoint's parent dir up to
+the git root. If your repo has Markdown documentation that quotes raw
+Tailwind classes like `bg-[url(...)]` (e.g. in a README that explains a
+migration from the old utility to this plugin), Tailwind will pick those
+literal strings up and try to emit CSS rules for them. esbuild will then
+fail to resolve the `...` placeholder URL, breaking your build.
+
+Fix: add `@source not` directives to your Tailwind CSS:
+
+```css
+@import "tailwindcss";
+@source not "../../docs/**";
+@source not "../../test/**";
+```
+
+## Architecture
+
+See [`docs/INTERNALS.md`](docs/INTERNALS.md) for the design spec and
+[`docs/adr/`](docs/adr/) for the architecture decision records covering
+the helper API, output paths, defaults, and cache-key invariants.
+
+## Development
+
+```sh
+bin/setup
+bundle exec rake test
+bundle exec rake rubocop
+```
+
+CI runs against Ruby 3.2/3.3/3.4 × Bridgetown 2.0/edge.
+
+## License
+
+MIT — see [`LICENSE.txt`](LICENSE.txt).
+
+## Status
+
+Maintained by [Flagrant](https://beflagrant.com) for use in production at
+[rubyconf.org](https://rubyconf.org). No SLA. Issues and PRs welcome at
+[github.com/beflagrant/bridgetown-image-pipeline](https://github.com/beflagrant/bridgetown-image-pipeline).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]