Refresh rendered diagrams while watching circuit files

Author: ydah

README.md

@@ -218,6 +218,8 @@ across `--step` images. The breadboard and netlist views accept v2 JSON IR.
 - `--diff OLD NEW` creates a two-panel HTML viewer. Removed wires are red in
   the old view and added wires are green in the new view; matching wires use
   their normal colors.
+- `--watch -o diagram.svg circuit.bk.rb` renders immediately and updates the
+  file when a circuit or part file beside the input changes. Press Ctrl-C to stop.
 - `--print-template` makes a PDF with 2.54 mm hole spacing, the complete board,
   and the print palette. Print at 100% scale; the option fixes the output scale
   to 1 and requires `rsvg-convert`.
@@ -256,6 +258,7 @@ bkrender ../breadkit/examples/05_sensor_demo.bk.rb \
 | `--quality N` | `90` | JPEG and WebP quality. |
 | `--print-template` | off | Export a full-board PDF with physical hole spacing for 100% printing. |
 | `--static` | off | Omit SVG layer controls and scripts. |
+| `--watch` | off | Keep rendering to `-o PATH` when nearby circuit or part files change. |
 | `--force` | off | Draw resolved elements even when input has layout errors. |
 | `--render-timeout SECONDS` | 60 | Limit external raster conversion time. |
 

lib/breadkit/render/cli.rb

@@ -7,6 +7,7 @@ module Breadkit
   module Render
     class CLI
       def run(argv)
+        original_args = argv.dup
         options = { scale: 2.0, theme: "light", orientation: "portrait", color_by: "wire", crop: "auto", backend: "auto", quality: 90,
                     view: "breadboard", label_density: "full" }
         parser = OptionParser.new do |opts|
@@ -33,6 +34,7 @@ def run(argv)
           opts.on("--backend NAME", %w[auto rsvg vips magick]) { |value| options[:backend] = value }
           opts.on("--background COLOR") { |value| options[:background] = value }
           opts.on("--static") { options[:static] = true }
+          opts.on("--watch") { options[:watch] = true }
           opts.on("--quality N", Integer) { |value| options[:quality] = value }
           opts.on("--print-template") { options[:print_template] = true }
           opts.on("--render-timeout SECONDS", Float) { |value| options[:render_timeout] = value }
@@ -55,6 +57,11 @@ def run(argv)
         end
         raise ArgumentError, "--background is only supported for JPEG" if options[:background] && format != "jpeg"
         raise ArgumentError, "cannot write binary image data to a terminal; use -o PATH" if !%w[svg html].include?(format) && !options[:output] && $stdout.tty?
+        if options[:watch]
+          raise ArgumentError, "--watch requires -o PATH" unless options[:output]
+          original_args.delete_at(original_args.index("--watch"))
+          return watch(input, second_input, options[:annotations], options[:output], original_args)
+        end
         return render_diff(input, second_input, options, format) if options[:diff]
         circuit = Breadkit.load(input)
         circuit.diagnostics.each do |item|
@@ -103,6 +110,35 @@ def run(argv)
 
       private
 
+      def watch(input, second_input, annotations, output, args)
+        root = File.dirname(File.expand_path(input))
+        paths = [input, second_input, annotations].compact.map { |path| File.expand_path(path) }
+        snapshot = watch_snapshot(root, paths, output)
+        warn "bkrender: watching #{root}; press Ctrl-C to stop"
+        loop do
+          warn "bkrender: rendered #{output}" if run(args.dup).zero?
+          loop do
+            sleep 0.5
+            updated = watch_snapshot(root, paths, output)
+            next if updated == snapshot
+
+            snapshot = updated
+            break
+          end
+        end
+      end
+
+      def watch_snapshot(root, paths, output)
+        # ponytail: watch nearby circuit and part files; add dependency tracking if broad projects make scanning costly.
+        files = paths + Dir.glob(File.join(root, "**", "*.{bk.rb,yml,yaml,toml,json}"))
+        files.map { |path| File.expand_path(path) }.uniq.sort.reject { |path| path == File.expand_path(output) }.to_h do |path|
+          stat = File.stat(path)
+          [path, [stat.mtime.to_r, stat.size]]
+        rescue Errno::ENOENT
+          [path, nil]
+        end
+      end
+
       def validate_step_options(options, format)
         raise ArgumentError, "--step must be a positive integer" unless options[:step].positive?
         raise ArgumentError, "--step is unavailable in #{options[:view]} view" unless options[:view] == "breadboard"

spec/breadkit/render_spec.rb

@@ -598,6 +598,46 @@
 end
 
 RSpec.describe Breadkit::Render::CLI do
+  it "requires file output for watch and notices source changes" do
+    Dir.mktmpdir do |directory|
+      input = File.join(directory, "circuit.bk.rb")
+      included = File.join(directory, "parts.yml")
+      output = File.join(directory, "circuit.svg")
+      File.write(input, "board :mini\n")
+      File.write(included, "id: first\n")
+      cli = described_class.new
+      expect { expect(cli.run([input, "--watch"])).to eq(2) }.to output(/--watch requires -o PATH/).to_stderr
+      before = cli.send(:watch_snapshot, directory, [input], output)
+      File.write(included, "id: second\n")
+      after = cli.send(:watch_snapshot, directory, [input], output)
+      expect(after).not_to eq(before)
+      File.write(output, "generated")
+      expect(cli.send(:watch_snapshot, directory, [input], output)).to eq(after)
+    end
+  end
+
+  it "rerenders a watched file after it changes" do
+    Dir.mktmpdir do |directory|
+      input = File.join(directory, "circuit.bk.rb")
+      output = File.join(directory, "circuit.svg")
+      File.write(input, 'board :mini; resistor :R1, "330", pins: %w[a1 a3]')
+      ticks = 0
+      cli = described_class.new
+      allow(cli).to receive(:sleep) do
+        ticks += 1
+        if ticks == 1
+          File.write(input, 'board :mini; resistor :R2, "330", pins: %w[a1 a3]')
+        else
+          raise Interrupt
+        end
+      end
+
+      expect { cli.run([input, "--watch", "-o", output]) }.to raise_error(Interrupt)
+      expect(ticks).to eq(2)
+      expect(File.read(output)).to include('data-ref="R2"')
+    end
+  end
+
   it "passes label density to breadboard output and rejects it in netlist view" do
     Dir.mktmpdir do |directory|
       input = File.join(directory, "labels.bk.rb")