breadkit-render 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3d7b06780f100a70e85853569136f7123912ce7708629d9d797f22190396c4f
-  data.tar.gz: beadb4b786adbe2b8250f0bc1a9fae04eab46eed4df6e011c0809cc5259070c3
+  metadata.gz: 1e7769bd0125dce1d2f251ecf06b67829dbf9b6759f5bdacad4b9a8355d6f8c1
+  data.tar.gz: 5c5e45131260ac0d96b4eb05cfedeced949232656944d8646c6ef136338f7c49
 SHA512:
-  metadata.gz: e69e57aec01703ba0d6bdf4fe1c74228ee1b68f2c4dfb92f8e4c063e7294f31a1c423696710e43619bbf4ad6bd16476108bba24edc7657808f04b14783459d53
-  data.tar.gz: 8faa7a544c38cbe3ac009b82588d2eb9357810eccd891c27dcbd4a396a3d3a6de116f795dee9a257fdcba78b7b14426047a2fd8d21a15ba05ed9d803047ad2f8
+  metadata.gz: 275e5ac4dcda42f55d7ebab5ee917abeda204022448bad366c87299d4fe82dae81db31d4fe6542a93307762fd0fe6442b311fedc8e4b404518dcaf7e7351f09f
+  data.tar.gz: d752e27594c7ee9f09ed823be0d0766c0246d2b68d0e7f16affd57a3791d59c346dbb6805d3d73b7b9bfdb40532b0b40bef7560f45138191c57dc4e6db37d228

data/.yamllint

@@ -0,0 +1,16 @@
+extends: default
+ignore: |
+  build/
+  node_modules/
+  runtime/build/
+  tmp/
+  **/*.dSYM/**
+
+rules:
+  comments:
+    min-spaces-from-content: 1
+  document-start: disable
+  line-length:
+    max: 200
+  truthy:
+    check-keys: false

data/CHANGELOG.md

@@ -1,7 +1,37 @@
 # Changelog
 
-## Unreleased
+## 0.2.0 — 2026-09-28
 
-## 0.1.0 — 2026-09-27
+### Breadboard diagrams
 
-- Initial release.
+- Draw custom left and right rail strips vertically and center rails horizontally, including named boards; show rail-mounted parts as logical edge pin maps at their declared holes.
+- Show DIP functional pin names in SVG hover titles and optional printed legends; draw TO-92 transistors, trimmer potentiometers, model-specific seven-segment displays, and RGB LEDs.
+- Render safe custom SVG part bodies from `render.svg` fragments in part YAML.
+- Add optional right-angle routes around component bodies, flat jumper styling, a colorblind palette, validated custom palettes, and embedded fonts. `--color-by net` overrides declared wire colors.
+- Highlight the exact routes reported by short-circuit annotations; mark on-board pins and offboard module targets in lint annotations, and outline large nets instead of circling every hole.
+- Reduce SVG hole markup with reusable shapes and show the hole ID and net on occupied or connected hole hover.
+- Add `--focus` and `--highlight-net` to emphasize selected components and nets.
+- Fall back to visible colors for invalid wire and LED colors.
+
+### Viewers and assembly guides
+
+- Add a standalone HTML viewer with zoom, pan, layer controls, and net hover. Resolve named switch states directly and reject viewers that exceed the 256-state budget.
+- Add `--state` and `--layer` for selected switch states and static layer output; hide markers and net labels from omitted layers.
+- Add `--diff OLD NEW` with colored added and removed wires in a two-panel HTML viewer.
+- Export printable assembly guides with bills of materials and staged diagrams, excluding nonphysical annotation wires.
+- Reload watched HTML after successful changes.
+
+### Image export
+
+- Add optional headless Chrome PNG rendering with checked output dimensions, an optional `resvg` PNG backend, and `--render-timeout` for external raster conversion.
+- Export APNG animations from assembly steps or switch states with configurable frame timing; reject switch animations above the 256-frame budget.
+- Provide a source-built container image with librsvg and Noto fonts.
+
+### Compatibility and diagnostics
+
+- Require Breadkit 0.2.x.
+- Show all circuit diagnostics on stderr, including warnings and errors when `--force` is used.
+
+## 0.1.0 — 2026-09-26
+
+- Initial release.

data/Dockerfile

@@ -0,0 +1,21 @@
+FROM ruby:4.0-slim-bookworm
+
+RUN apt-get update \
+    && apt-get install -y --no-install-recommends build-essential ca-certificates git librsvg2-bin fonts-noto-cjk fontconfig \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY breadkit/ /opt/breadkit/
+COPY breadkit-render/ /opt/breadkit-render/
+WORKDIR /opt/breadkit-render
+
+RUN printf "source 'https://rubygems.org'\ngem 'breadkit', path: '/opt/breadkit'\ngem 'breadkit-render', path: '/opt/breadkit-render'\n" > Gemfile.container \
+    && BUNDLE_GEMFILE=/opt/breadkit-render/Gemfile.container bundle install \
+    && BUNDLE_GEMFILE=/opt/breadkit-render/Gemfile.container bundle exec ruby exe/bkrender --version \
+    && fc-match 'Noto Sans CJK JP' \
+    && printf 'board :mini\n' > /tmp/smoke.bk.rb \
+    && BUNDLE_GEMFILE=/opt/breadkit-render/Gemfile.container bundle exec ruby exe/bkrender /tmp/smoke.bk.rb -o /tmp/smoke.png \
+    && ruby -e 'abort "PNG smoke check failed" unless File.binread("/tmp/smoke.png").start_with?("\x89PNG".b)'
+
+ENV BUNDLE_GEMFILE=/opt/breadkit-render/Gemfile.container
+WORKDIR /work
+ENTRYPOINT ["bundle", "exec", "ruby", "/opt/breadkit-render/exe/bkrender"]

data/Dockerfile.dockerignore

@@ -0,0 +1,15 @@
+**
+!breadkit/
+!breadkit/breadkit.gemspec
+!breadkit/lib/
+!breadkit/lib/**
+!breadkit/data/
+!breadkit/data/**
+!breadkit/schema/
+!breadkit/schema/**
+!breadkit-render/
+!breadkit-render/breadkit-render.gemspec
+!breadkit-render/lib/
+!breadkit-render/lib/**
+!breadkit-render/exe/
+!breadkit-render/exe/**

data/README.md

@@ -1,58 +1,80 @@
-# breadkit-render
+<p align="center">
+  <img src="site/favicon.svg" width="72" height="72" alt="">
+</p>
 
-Project site: https://breadkit.github.io/breadkit-render/
+<h1 align="center">breadkit-render</h1>
 
-`bkrender` turns a Breadkit DSL or resolved IR JSON file into a standalone SVG diagram. Breadkit DSL input is executable Ruby; only render files you trust. IR JSON is the data-only alternative.
+<p align="center">
+  <strong>Turn breadboard circuits into clear, shareable diagrams.</strong>
+</p>
 
-Install `breadkit-render` directly; RubyGems installs its compatible `breadkit` core dependency. Shared circuit examples are in the [breadkit repository](https://github.com/breadkit/breadkit/tree/main/examples).
+<p align="center">
+  <a href="https://rubygems.org/gems/breadkit-render"><img src="https://img.shields.io/gem/v/breadkit-render.svg" alt="RubyGems version"></a>
+  <a href="https://github.com/breadkit/breadkit-render/actions/workflows/ci.yml"><img src="https://github.com/breadkit/breadkit-render/actions/workflows/ci.yml/badge.svg" alt="CI status"></a>
+  <img src="https://img.shields.io/badge/Ruby-%3E%3D%203.3-CC342D.svg" alt="Ruby 3.3 or newer">
+  <a href="LICENSE.txt"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
+</p>
+
+`bkrender` turns [Breadkit](https://github.com/breadkit/breadkit) circuits into
+breadboard, schematic, and netlist views. Export SVG, HTML, images, PDF, or
+animated assembly steps.
+
+<p align="center">
+  <img src="site/images/sensor-demo.png" width="800" alt="RP2040 sensor circuit on a full-size breadboard with OLED, two SHT31 modules, switches, and IR modules">
+</p>
+
+<p align="center">
+  <a href="https://breadkit.github.io/breadkit-render/images/sensor-demo.svg">Open the interactive sensor demo</a>
+</p>
+
+## Quick start
+
+Install with Ruby 3.3 or newer:
 
 ```sh
-bkrender circuit.bk.rb -o circuit.svg --show-nets --legend
-bkrender circuit.bk.rb -o circuit.png --scale 3 --theme light
-bkrender circuit.bk.rb -o circuit.svg --orientation landscape
-bkrender circuit.bk.rb -o circuit.svg --rail-pattern '+--+'
-bkrender circuit.bk.rb --format svg > circuit.svg
+gem install breadkit-render
+bkrender circuit.bk.rb --theme dark -o circuit.svg
 ```
 
-## Example output
+This README follows main (0.2.0), which requires Breadkit core 0.2.x. If the
+published gems are older, use sibling source checkouts:
 
-Generated from the shared [RP2040 sensor demo](https://github.com/breadkit/breadkit/blob/main/examples/05_sensor_demo.bk.rb). It uses the full-size 830-point board model. The image crops to the used area: the controller occupies rows 1–20, with switches and IR connections below and OLED/SHT31 modules beside it.
-
-Rendered with `bkrender ../breadkit/examples/05_sensor_demo.bk.rb -o docs/images/sensor-demo.png --crop auto --rail-pattern '+--+' --scale 2`:
+```sh
+git clone https://github.com/breadkit/breadkit.git
+git clone https://github.com/breadkit/breadkit-render.git
+cd breadkit-render
+bundle install
+bundle exec ruby exe/bkrender ../breadkit/examples/01_led_button.bk.rb -o circuit.svg
+```
 
-<img src="docs/images/sensor-demo.png" alt="RP2040 sensor demo on a full-size breadboard with OLED, two SHT31 modules, two switches, and IR receiver and emitter wiring" width="800">
+SVG works without a conversion backend. PNG, JPEG, WebP, PDF, and APNG need a
+supported backend; see the [format and backend reference](docs/REFERENCE.md#raster-backends).
 
-[Open the interactive SVG](docs/images/sensor-demo.svg). Its layer tabs isolate power, I2C, switches, IR, and the optional 5 V emitter wiring. The 5 V view is a dashed, visual-only alternative: remove the emitter's 3.3 V rail wire before applying it.
+## Choose a view
 
-The shared example defines the board and IR connectors in the breadkit repository's [`examples/parts`](https://github.com/breadkit/breadkit/tree/main/examples/parts). Pin `type:` values such as `power`, `ground`, `clock`, `data`, `address`, and `interrupt` color the markers. `offboard` modules use a neutral surface color; connected pin names are emphasized, unused pins are muted, and `address:` text is shown on the module. Assign `layer:` to wires and components to create matching interactive views. `route: :edge` routes long wires outside the board and separates wires that would otherwise overlap.
+```sh
+bkrender circuit.bk.rb --view schematic -o schematic.svg
+bkrender circuit.bk.rb --view netlist -o netlist.svg
+bkrender circuit.bk.rb -o circuit.html
+```
 
-Resistors use four color bands by default. Set `bands: 5` on a resistor for three significant digits and a 1% brown tolerance band.
+The default breadboard view shows physical placement. The schematic groups
+pins by electrical connection; the netlist lists resolved nets. HTML adds
+interactive inspection. See the [full command reference](docs/REFERENCE.md)
+for layers, rail patterns, themes, annotations, assembly guides, animations,
+and output options.
 
-## Options
+The [sensor demo source](https://github.com/breadkit/breadkit/blob/main/examples/05_sensor_demo.bk.rb)
+uses an RP2040, OLED, two SHT31 modules, switches, and IR modules. Its 5 V
+emitter layer is an alternative: disconnect the emitter's 3.3 V wire before
+using it. Keep the receiver at 3.3 V.
 
-| Option | Default | Description |
-| --- | --- | --- |
-| `-o, --output PATH` | stdout | Write to a file; `.svg`, `.png`, `.jpg`, and `.jpeg` select the format. |
-| `-f, --format FORMAT` | inferred or `svg` | `svg`, `png`, or `jpeg`. Conflicting extensions are errors. |
-| `--scale N` | `2` | Raster output scale. |
-| `--theme NAME` | `light` | `light`, `dark`, or `print`. |
-| `--orientation NAME` | `portrait` | `portrait` for a readable vertical board; `landscape` for a wide view. |
-| `--rail-pattern PATTERN` | board layout | Assign `+`/`-` to the four rails in portrait order: left outer, left inner, right inner, right outer. Accepted patterns: `+--+`, `+-+-`, `-+-+`, `-++-`. Rail connections move with their assigned polarity. |
-| `--color-by MODE` | `wire` | Use declared wire colors or deterministic net colors. |
-| `--show-nets` | off | Add net labels to the diagram. |
-| `--legend` | off | Add the title, connected net names, and representative wire colors. |
-| `--crop MODE` | `auto` | `auto` crops to circuit content; `none` shows the full board. |
-| `--annotations FILE` | none | Overlay offenses from `bklint --format json`. |
-| `--backend NAME` | `auto` | Raster backend: `rsvg`, `vips`, or `magick`. |
-| `--background COLOR` | white | JPEG background: basic CSS color name, `#RGB`, or `#RRGGBB`. PNG and SVG reject this option. |
-| `--quality N` | `90` | JPEG quality. |
-| `--static` | off | Omit SVG layer controls and embedded scripts. |
-| `--force` | off | Draw resolved elements even when the input has layout errors. |
+Ruby DSL files execute code; render only files you trust. JSON IR is data-only.
 
-## Raster backends
+## Development
 
-SVG is rendered without extra dependencies. PNG uses the first available backend in the order `rsvg-convert`, `ruby-vips`, ImageMagick. JPEG uses `ruby-vips` or ImageMagick and is flattened onto the configured background. Install `librsvg` (`brew install librsvg` or `apt install librsvg2-bin`) or ImageMagick for raster output. `ruby-vips` also needs a libvips build with SVG support.
+From the sibling checkout above, run `bundle exec rake` for the local checks.
 
-Connected breadboard holes and physically occupied holes use different markers. LED colors accept CSS color names and hexadecimal colors such as `#6d5af0`.
+## License
 
-The SVG uses a system font stack including Noto Sans JP. Rasterized Japanese labels need a Japanese font installed in the environment.
+[MIT](LICENSE.txt).

data/docs/REFERENCE.md

@@ -0,0 +1,115 @@
+# breadkit-render reference
+
+Start with the [README](../README.md) for installation and the first SVG.
+Run `bkrender --help` for the complete option list.
+
+## Views and formats
+
+The default breadboard view shows physical placement and jumper routes.
+`--view schematic` draws components and their resolved net connections;
+`--view netlist` groups terminals by net. These electrical views do not show
+physical jumper positions. They accept SVG, PNG, JPEG, WebP, and PDF, but not
+HTML or breadboard-only controls.
+
+<p align="center">
+  <img src="images/led-schematic.png" width="700" alt="Schematic showing a USB supply, switch, resistor, and LED connected by named nets">
+</p>
+
+<p align="center">
+  <img src="images/led-netlist.png" width="700" alt="Netlist view grouping component terminals by resolved net">
+</p>
+
+Output format follows the extension passed to `-o`. SVG requires no external
+converter; `--format svg` also writes to standard output. Breadboard HTML
+pairs the breadboard and schematic with zoom, pan, layer controls, net
+highlighting, and switch-state selection.
+
+```sh
+bkrender circuit.bk.rb --theme dark -o circuit.svg
+bkrender circuit.bk.rb -o circuit.html
+bkrender circuit.bk.rb --view schematic -o schematic.svg
+bkrender circuit.bk.rb --view netlist -o netlist.svg
+```
+
+## Breadboard controls
+
+| Option | Effect |
+| --- | --- |
+| `--rail-pattern '+--+'` | Set left outer, left inner, right inner, and right outer rail polarities. Also accepts `+-+-`, `-+-+`, and `-++-`. |
+| `--orientation landscape`, `--crop none` | Arrange named boards side by side or show the complete board. |
+| `--theme dark`, `--theme colorblind` | Choose a built-in palette; `colorblind` is breadboard-only. `--color-by net` colors wires by resolved net. |
+| `--label-density compact`, `--legend` | Reduce body labels or print a pin legend. |
+| `--wire-routing auto`, `--wire-style flat` | Route on-board wires around bodies or use thin jumper lines. |
+| `--state SW1`, `--layer "2 I2C"` | Show selected switch connectivity or one named visual layer. |
+| `--focus R1`, `--highlight-net VCC` | Emphasize a part or a resolved net. |
+| `--annotations lint.json` | Draw targets from `bklint --format json`. |
+| `--diff old.bk.rb new.bk.rb -o changes.html` | Compare added and removed wires in an HTML viewer. |
+
+`--rail-pattern` applies to one unnamed breadboard; named-board circuits
+use each board's own rail definition. A circuit's `layer:` values group
+components and wires for SVG and HTML. `--watch -o diagram.html circuit.bk.rb`
+updates output when the input or a nearby part file changes, and reloads an
+open HTML viewer after a successful render.
+
+A custom JSON palette inherits a built-in theme:
+
+```json
+{"base":"dark","colors":{"board":"#17251f","text":"#f3f8f4"}}
+```
+
+Pass it with `--theme-file palette.json` for breadboard output. Values are
+six-digit hexadecimal colors. `--font-file font.woff2` embeds a licensed font
+in a standalone SVG.
+
+## Assembly and print output
+
+Numbered `step` blocks in the [Breadkit DSL](https://github.com/breadkit/breadkit/blob/main/docs/dsl.md#assembly-steps)
+mark assembly stages. Declarations outside steps appear in every stage.
+
+```sh
+bkrender circuit.bk.rb --step 1 -o step-1.svg
+bkrender circuit.bk.rb --assembly-guide -o guide.html
+bkrender circuit.bk.rb --animate steps --frame-delay 800 -o assembly.apng
+bkrender circuit.bk.rb --print-template -o template.pdf
+```
+
+An assembly guide needs at least one step. APNG needs at least two frames;
+`--animate states` uses switch states and rejects more than 256 frames.
+`--print-template` uses 2.54 mm hole spacing and must be printed at 100%;
+it requires `rsvg-convert`.
+
+## Custom part bodies
+
+A part definition can draw a small SVG fragment around its placed pins:
+
+```yaml
+render:
+  shape: generic
+  fill: "#304050"
+  svg: '<circle cx="0" cy="0" r="5" fill="{{fill}}"/>'
+```
+
+The available variables are `{{ref}}`, `{{value}}`, `{{fill}}`,
+`{{stroke}}`, and `{{text_color}}`. Basic SVG shapes, paths, groups, and
+text are allowed; scripts, event handlers, URLs, styles, and external
+references are rejected. Physical leads and pins remain visible.
+
+## Raster backends
+
+PNG and APNG use the first available backend: `rsvg-convert`, `resvg`,
+`ruby-vips`, ImageMagick, then Chrome. JPEG and WebP use `ruby-vips` or
+ImageMagick. PDF requires `rsvg-convert` and retains vector content. Install
+librsvg with `brew install librsvg` or `apt install librsvg2-bin` for PDF.
+Choose a backend with `--backend NAME`; `--render-timeout SECONDS` limits
+external conversion. `--scale` sets raster size.
+
+The [container image](https://github.com/breadkit/breadkit-render/pkgs/container/breadkit-render)
+includes Ruby, Breadkit core, librsvg, and Noto fonts:
+
+```sh
+docker run --rm -v "$PWD:/work" ghcr.io/breadkit/breadkit-render:main \
+  circuit.bk.rb --theme dark -o circuit.png
+```
+
+Pin a `sha-<render commit>` image tag for reproducible output. Ruby DSL
+files execute code; render only files you trust. JSON IR is data-only.

data/lib/breadkit/render/apng_encoder.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+require "zlib"
+
+module Breadkit
+  module Render
+    class ApngEncoder
+      SIGNATURE = "\x89PNG\r\n\x1a\n".b.freeze
+
+      def encode(images, delay_ms: 800)
+        raise Error, "APNG requires at least two frames" unless images.length >= 2
+        raise Error, "frame delay must be 1..65535 milliseconds" unless delay_ms.is_a?(Integer) && delay_ms.between?(1, 65_535)
+
+        frames = images.map { |image| parse_png(image) }
+        header, prelude = frames.first.values_at(:header, :prelude)
+        unless frames.all? { |frame| frame[:header] == header && frame[:palette] == frames.first[:palette] }
+          raise Error, "APNG frames need matching dimensions and color format"
+        end
+
+        width, height = header.unpack("N2")
+        output = SIGNATURE + png_chunk("IHDR", header) + prelude.join + png_chunk("acTL", [frames.length, 0].pack("N2"))
+        sequence = 0
+        frames.each_with_index do |frame, index|
+          control = [sequence, width, height, 0, 0, delay_ms, 1000, 0, 0].pack("N5n2C2")
+          output << png_chunk("fcTL", control)
+          sequence += 1
+          frame[:data].each do |data|
+            output << if index.zero?
+              png_chunk("IDAT", data)
+            else
+              chunk = png_chunk("fdAT", [sequence].pack("N") + data)
+              sequence += 1
+              chunk
+            end
+          end
+        end
+        output << png_chunk("IEND", "".b)
+      end
+
+      private
+
+      def parse_png(image)
+        raise Error, "invalid PNG frame" unless image.start_with?(SIGNATURE)
+
+        position = SIGNATURE.bytesize
+        chunks = []
+        while position + 12 <= image.bytesize
+          length = image.byteslice(position, 4).unpack1("N")
+          finish = position + length + 12
+          raise Error, "invalid PNG frame" if finish > image.bytesize
+
+          type = image.byteslice(position + 4, 4)
+          data = image.byteslice(position + 8, length)
+          crc = image.byteslice(finish - 4, 4).unpack1("N")
+          raise Error, "invalid PNG frame checksum" unless crc == Zlib.crc32(type + data)
+
+          chunks << [type, data]
+          position = finish
+          break if type == "IEND"
+        end
+        raise Error, "invalid PNG frame" unless position == image.bytesize && chunks.first&.first == "IHDR" &&
+                                                  chunks.first.last.bytesize == 13 && chunks.last&.first == "IEND"
+
+        first_data = chunks.index { |type, _| type == "IDAT" }
+        raise Error, "PNG frame has no image data" unless first_data
+        prelude = chunks[1...first_data]
+        raise Error, "already animated PNG frames are unsupported" if chunks.any? { |type, _| %w[acTL fcTL fdAT].include?(type) }
+
+        { header: chunks.first.last, prelude: prelude.map { |type, data| png_chunk(type, data) },
+          palette: prelude.select { |type, _| %w[PLTE tRNS].include?(type) },
+          data: chunks.filter_map { |type, data| data if type == "IDAT" } }
+      end
+
+      def png_chunk(type, data)
+        [data.bytesize].pack("N") + type + data + [Zlib.crc32(type + data)].pack("N")
+      end
+    end
+  end
+end