zpl_renderer 0.1.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b9d98e662dece76d83d75273549dc7cea4326b6f49a4dddc351f6e8a925ab3cd
+  data.tar.gz: 22544d0cc68b30c89eba29762898eb6fede5eaf6317bd3d1373a1dd55c59e5b3
+SHA512:
+  metadata.gz: 9e160e478a204168f49cd191c0275f8b2537cadd164161e185814778517f7d968b56a92409701a9dfbf51356d2536bf4e5d228701eb65fb1af5aa9c082398258
+  data.tar.gz: e7afe50cff6da9eb11371dbdf9a0b64ff36642305091220d92a0d79d1468bbea4328bed8ed075bf8ef58b0afe49e39b8ca7ae01f4e506753b42c368313032303

data/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.2
+
+- Fix right-edge fields being cut off when `^PW` is narrower than the canvas
+  (rotated serials at `^FO788` / `^FO791` under `^PW800`)
+- Add `clip_to_print_width` option for printer-accurate clipping
+- Decode PNG pixels in specs to regression-test right-edge clipping
+- Keep fixtures synthetic only; do not commit real customer ZPL
+
+## 0.1.1
+
+- Sanitize malformed `^FO...,--` coordinates using last section-divider Y
+- Add synthetic carrier return/outbound fixture with barcode decode coverage
+
+## 0.1.0
+
+- Initial offline ZPL to PNG/PDF renderer for Ruby 3.1+
+- Bundled Rust renderer based on labelize
+- Code 128, Code 39, EAN-13, QR, and related shipping-label barcode support
+- Strict compatibility validation and scanability warnings
+- Independent ZXing-based decode helper for CI/QA
+- CLI: `zpl-render`

data/COMPATIBILITY.md

@@ -0,0 +1,64 @@
+# ZPL Compatibility Matrix (v0.1)
+
+`zpl_renderer` targets **common shipping-label ZPL** at **203 / 300 / 600 DPI**.
+It is offline and does not claim bit-identical output with every Zebra firmware,
+installed font, or graphics store.
+
+## Supported commands
+
+| Category | Commands |
+|---|---|
+| Label control | `^XA` `^XZ` `^PW` `^PO` `^LH` `^LR` `^CI` `^MU` `^PR` `^PQ` `^JM` `^MD` `^MN` `^MT` `^PM` |
+| Text / fonts | `^FO` `^FT` `^FD` `^FS` `^A` `^CF` `^FB` `^FR` `^FH` `^FN` `^FW` `^FV` |
+| Barcodes | `^BC` `^BE` `^B2` `^B3` `^B7` `^BO` `^BX` `^BQ` `^BD` `^BY` |
+| Graphics | `^GB` `^GC` `^GD` `^GF` `^GS` `~DG` `^IL` `^XG` |
+| Stored formats | `^DF` `^XF` |
+
+## Barcode scanability guidance
+
+| DPI | Recommended `^BY` module width | QR magnification (`^BQ` 3rd param) |
+|---|---|---|
+| 203 (8 dpmm) | >= 2 dots | >= 2 (prefer 4-6) |
+| 300 (12 dpmm) | >= 3 dots | >= 3 (prefer 5-8) |
+| 600 (24 dpmm) | >= 4 dots | >= 4 (prefer 6-10) |
+
+Leave quiet zones around barcodes. Avoid clipping symbols with tight `^PW`/`^LL`
+or overlapping reverse fields (`^FR`).
+
+## Strict mode
+
+By default `strict: true`:
+
+- missing `^XA` / `^XZ` raises
+- empty barcode `^FD` data raises
+- known unsupported RFID / wireless / advanced commands raise
+
+Set `strict: false` to render best-effort and collect warnings via
+`ZplRenderer.validate`.
+
+## Explicitly unsupported (first release)
+
+RFID (`^RF` family), wireless/config (`^W*`), advanced serialization helpers
+beyond common shipping usage, and printer-private extensions.
+
+## Accuracy contract
+
+1. Rendered barcode/QR payloads must decode with an independent ZXing engine.
+2. PDF page size equals the requested physical label size.
+3. PNG dimensions equal `ceil(mm * dpmm)` for width and height.
+4. Pixel-perfect printer firmware matching is **not** guaranteed.
+
+## Carrier ZPL sanitization
+
+Before render/validate, the gem rewrites known carrier quirks:
+
+- `^FO464,--^GB2,126,2` becomes `^FO464,<last-section-divider-y>`
+  when a prior full-width horizontal rule exists; otherwise Y falls back to `0`.
+- A `^PW` narrower than the requested canvas is widened to the canvas width, and
+  `^LH` is shifted by the same centering offset the engine would have applied.
+  Without this, fields near the right edge (carrier templates often put rotated
+  serials at `^FO788` / `^FO791` under `^PW800`) are clipped off an 813-dot
+  4 inch canvas. Pass `clip_to_print_width: true` to keep printer-accurate
+  clipping instead. Labels using `^POI` are left untouched.
+
+Use `ZplRenderer.sanitize(zpl, canvas_dots: 813)` to inspect repairs without rendering.

data/LICENSE.txt

@@ -0,0 +1,24 @@
+MIT License
+
+Copyright (c) 2026 Waqas
+
+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.
+
+This gem bundles a renderer that depends on the MIT-licensed labelize project
+(https://github.com/GOODBOY008/labelize).

data/README.md

@@ -0,0 +1,147 @@
+# zpl_renderer
+
+Offline ZPL to PNG/PDF renderer for Ruby and Rails.
+
+Add the gem, render labels, and get barcodes/QR codes that scanners can decode.
+No Labelary account, no network calls, no printer hardware required.
+
+## Install
+
+```ruby
+# Gemfile
+gem "zpl_renderer"
+```
+
+```bash
+bundle install
+```
+
+Precompiled renderer binaries ship for common platforms (Linux/macOS/Windows).
+If your platform is missing a binary, build it once:
+
+```bash
+cd renderer && cargo build --release
+bundle exec rake build_renderer
+```
+
+Or point to a binary explicitly:
+
+```bash
+export ZPL_RENDERER_BINARY=/absolute/path/to/zpl-renderer
+```
+
+## Quick start
+
+```ruby
+require "zpl_renderer"
+
+zpl = <<~ZPL
+  ^XA
+  ^FO50,50^A0N,40,40^FDHello^FS
+  ^FO50,120^BY3
+  ^BCN,100,Y,N,N
+  ^FDTRACK123456789^FS
+  ^FO50,280^BQN,2,6
+  ^FDQA,https://example.com/track/ABC123^FS
+  ^XZ
+ZPL
+
+png = ZplRenderer.render(zpl, format: :png, width: 4, height: 6, dpi: 203)
+File.binwrite("label.png", png)
+
+pdf = ZplRenderer.render(zpl, format: :pdf, width: 4, height: 6, dpi: 300)
+File.binwrite("label.pdf", pdf)
+```
+
+### Rails
+
+```ruby
+png = ZplRenderer.render(@label.zpl, format: :png, width: 4, height: 6, dpi: 203)
+send_data png,
+          type: ZplRenderer.content_type(:png),
+          disposition: "inline",
+          filename: "label.png"
+```
+
+See [`examples/rails_controller.rb`](examples/rails_controller.rb).
+
+### CLI
+
+```bash
+zpl-render label.zpl -o label.png --dpi 203 --width 4 --height 6
+zpl-render label.zpl -o label.pdf --format pdf --dpi 300
+zpl-render --validate-only label.zpl
+```
+
+## Options
+
+| Option | Default | Notes |
+|---|---|---|
+| `format` | `:png` | `:png` or `:pdf` |
+| `width` / `height` | `4` / `6` | Inches by default |
+| `unit` | `:inches` | `:inches` or `:mm` |
+| `dpi` | `203` | `203`, `300`, or `600` |
+| `dpmm` | derived | `8`, `12`, or `24` (overrides `dpi`) |
+| `index` | `0` | Multi-label `^XA...^XZ` selection |
+| `timeout` | `30` | Seconds |
+| `strict` | `true` | Raise on unsupported commands |
+| `clip_to_print_width` | `false` | Emulate printer `^PW` clipping instead of widening |
+
+Canvas size is printer-dot accurate: `ceil(mm * dpmm)`.
+
+## Accuracy and barcodes
+
+This gem targets **common shipping-label ZPL**, not every Zebra firmware quirk.
+
+Supported first-release command set and barcode guidance live in
+[`COMPATIBILITY.md`](COMPATIBILITY.md).
+
+Carrier quirks are sanitized automatically before render: bad field origins such
+as `^FO464,--`, and `^PW` values narrower than the canvas that would clip
+rotated text at the right edge. Inspect repairs with
+`ZplRenderer.sanitize(zpl, canvas_dots: 813)`.
+
+Barcode/QR payloads are independently verified in CI with a ZXing-based decoder:
+
+```ruby
+hits = ZplRenderer.decode_png(png)
+hits.map(&:text)
+# => ["TRACK123456789", "https://example.com/track/ABC123"]
+```
+
+### Scanner tips
+
+- Prefer `^BY3` (or wider) at 203 DPI
+- Prefer QR magnification `>= 4` for handheld scanners
+- Keep quiet zones clear of text/graphics
+- Avoid clipping barcodes with tiny `^PW` / label widths
+
+## Development
+
+```bash
+bundle install
+source "$HOME/.cargo/env"   # if needed
+bundle exec rake build_renderer
+bundle exec rake golden
+bundle exec rspec
+cd renderer && cargo test
+```
+
+Fixtures under `spec/fixtures/` must stay synthetic. Do not commit real customer
+or production ZPL/PNG samples.
+
+## Packaging
+
+```bash
+bundle exec rake build_renderer
+gem build zpl_renderer.gemspec
+```
+
+Platform CI builds native binaries for Linux/macOS/Windows and packages them under
+`vendor/bin/<rust-triple>/`.
+
+Publishing to RubyGems is intentional and separate from local gem builds.
+
+## License
+
+MIT. Renderer engine depends on [labelize](https://github.com/GOODBOY008/labelize) (MIT).

data/exe/zpl-render

@@ -0,0 +1,95 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../lib/zpl_renderer"
+
+options = {
+  format: :png,
+  width: 4.0,
+  height: 6.0,
+  dpi: 203,
+  index: 0,
+  unit: :inches,
+  strict: true,
+  output: nil
+}
+
+parser = OptionParser.new do |opts|
+  opts.banner = "Usage: zpl-render [options] [INPUT.zpl]"
+
+  opts.on("-o", "--output PATH", "Output file (default: stdout for bytes, or INPUT.png/pdf)") do |v|
+    options[:output] = v
+  end
+  opts.on("-f", "--format FORMAT", "png or pdf (default: png)") do |v|
+    options[:format] = v.to_sym
+  end
+  opts.on("-w", "--width N", Float, "Label width (default: 4)") { |v| options[:width] = v }
+  opts.on("-H", "--height N", Float, "Label height (default: 6)") { |v| options[:height] = v }
+  opts.on("--dpi N", Integer, "203, 300, or 600 (default: 203)") { |v| options[:dpi] = v }
+  opts.on("--dpmm N", Integer, "8, 12, or 24 (overrides --dpi)") { |v| options[:dpmm] = v }
+  opts.on("--index N", Integer, "Label index for multi-label ZPL (default: 0)") { |v| options[:index] = v }
+  opts.on("--unit UNIT", "inches or mm (default: inches)") { |v| options[:unit] = v.to_sym }
+  opts.on("--[no-]strict", "Raise on unsupported commands (default: true)") { |v| options[:strict] = v }
+  opts.on("-V", "--validate-only", "Validate ZPL and exit") { options[:validate_only] = true }
+  opts.on("-v", "--version", "Print version") do
+    puts "zpl_renderer #{ZplRenderer::VERSION}"
+    exit 0
+  end
+  opts.on("--help", "Show help") do
+    puts opts
+    exit 0
+  end
+end
+
+parser.parse!
+
+input_path = ARGV.shift
+zpl =
+  if input_path
+    File.read(input_path)
+  elsif !$stdin.tty?
+    $stdin.read
+  else
+    warn parser.help
+    exit 1
+  end
+
+render_kwargs = {
+  format: options[:format],
+  width: options[:width],
+  height: options[:height],
+  dpi: options[:dpi],
+  index: options[:index],
+  unit: options[:unit],
+  strict: options[:strict]
+}
+render_kwargs[:dpmm] = options[:dpmm] if options[:dpmm]
+
+if options[:validate_only]
+  result = ZplRenderer.validate(zpl, **render_kwargs)
+  result.warnings.each { |w| warn "warning: #{w}" }
+  if result.ok?
+    puts "OK"
+    exit 0
+  else
+    result.errors.each { |e| warn "error: #{e}" }
+    exit 2
+  end
+end
+
+bytes = ZplRenderer.render(zpl, **render_kwargs)
+
+output = options[:output]
+if output.nil? && input_path
+  ext = options[:format] == :pdf ? ".pdf" : ".png"
+  output = input_path.sub(/\.[^.]+\z/, "") + ext
+end
+
+if output
+  File.binwrite(output, bytes)
+  warn "Wrote #{output} (#{bytes.bytesize} bytes)"
+else
+  $stdout.binmode
+  $stdout.write(bytes)
+end

data/lib/zpl_renderer/binary.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "rbconfig"
+
+module ZplRenderer
+  # Locates the bundled zpl-renderer native binary for the current platform.
+  module Binary
+    module_function
+
+    BINARY_NAME = "zpl-renderer"
+
+    def path
+      candidates.find { |candidate| File.file?(candidate) && File.executable?(candidate) } ||
+        raise(BinaryMissingError, missing_message)
+    end
+
+    def platform_triple
+      case RUBY_PLATFORM
+      when /x86_64-linux-musl/ then "x86_64-unknown-linux-musl"
+      when /aarch64-linux-musl|arm64-linux-musl/ then "aarch64-unknown-linux-musl"
+      when /x86_64-linux/ then "x86_64-unknown-linux-gnu"
+      when /aarch64-linux|arm64-linux/ then "aarch64-unknown-linux-gnu"
+      when /x86_64-darwin/ then "x86_64-apple-darwin"
+      when /arm64-darwin|aarch64-darwin/ then "aarch64-apple-darwin"
+      when /x64-mingw|x86_64-mingw|x64-mswin|x86_64-mswin/ then "x86_64-pc-windows-msvc"
+      else
+        RUBY_PLATFORM
+      end
+    end
+
+    def candidates
+      root = File.expand_path("../..", __dir__)
+      name = windows? ? "#{BINARY_NAME}.exe" : BINARY_NAME
+      triple = platform_triple
+
+      [
+        ENV["ZPL_RENDERER_BINARY"],
+        File.join(root, "vendor", "bin", triple, name),
+        File.join(root, "vendor", "bin", name),
+        File.join(root, "renderer", "target", "release", name),
+        File.join(root, "renderer", "target", "debug", name)
+      ].compact
+    end
+
+    def windows?
+      !!(RUBY_PLATFORM =~ /mswin|mingw|cygwin/)
+    end
+
+    def missing_message
+      <<~MSG
+        Could not find the zpl-renderer binary for #{platform_triple}.
+
+        Tried:
+        #{candidates.map { |c| "  - #{c}" }.join("\n")}
+
+        Build it with:
+          cd renderer && cargo build --release
+
+        Or set ZPL_RENDERER_BINARY to an absolute path.
+      MSG
+    end
+  end
+end

data/lib/zpl_renderer/decoder.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module ZplRenderer
+  # Independent barcode/QR decoder used by tests and optional QA hooks.
+  class Decoder
+    Hit = Struct.new(:symbology, :text, keyword_init: true)
+
+    def initialize(binary_path: nil)
+      @binary_path = binary_path
+    end
+
+    def decode_png(png_bytes)
+      stdout, stderr, status = Open3.capture3(
+        binary_path,
+        "--decode",
+        stdin_data: png_bytes,
+        binmode: true
+      )
+
+      unless status.success?
+        message = stderr.to_s.strip
+        message = "decode failed with status #{status.exitstatus}" if message.empty?
+        raise RenderError, message
+      end
+
+      JSON.parse(stdout).map do |row|
+        Hit.new(symbology: row.fetch("format"), text: row.fetch("text"))
+      end
+    rescue Errno::ENOENT
+      raise BinaryMissingError, Binary.missing_message
+    end
+
+    private
+
+    def binary_path
+      @binary_path || Binary.path
+    end
+  end
+end

data/lib/zpl_renderer/engine.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "timeout"
+
+module ZplRenderer
+  # Invokes the offline Rust renderer binary over stdin/stdout.
+  class Engine
+    PROTOCOL_VERSION = 1
+
+    def initialize(binary_path: nil)
+      @binary_path = binary_path
+    end
+
+    def render(zpl, options)
+      request = JSON.generate(
+        protocol: PROTOCOL_VERSION,
+        zpl: zpl.to_s,
+        format: options.format.to_s,
+        width_mm: options.width_mm,
+        height_mm: options.height_mm,
+        dpmm: options.dpmm,
+        index: options.index
+      )
+
+      stdout = +"".b
+      stderr = +"".b
+      status = nil
+
+      begin
+        Timeout.timeout(options.timeout) do
+          Open3.popen3(binary_path, "--json") do |stdin, out, err, wait_thr|
+            stdin.binmode
+            out.binmode
+            err.binmode
+
+            stdin.write(request)
+            stdin.close
+
+            stdout = out.read
+            stderr = err.read
+            status = wait_thr.value
+          end
+        end
+      rescue Timeout::Error
+        raise TimeoutError, "render timed out after #{options.timeout}s"
+      rescue Errno::ENOENT
+        raise BinaryMissingError, Binary.missing_message
+      end
+
+      unless status&.success?
+        message = stderr.to_s.strip
+        message = "renderer exited with status #{status&.exitstatus}" if message.empty?
+        raise_for_message!(message)
+      end
+
+      if stdout.bytesize > options.max_output_bytes
+        raise OutputTooLargeError,
+              "output is #{stdout.bytesize} bytes; max_output_bytes=#{options.max_output_bytes}"
+      end
+
+      stdout
+    end
+
+    private
+
+    def binary_path
+      @binary_path || Binary.path
+    end
+
+    def raise_for_message!(message)
+      case message
+      when /unsupported|not supported/i
+        raise UnsupportedCommandError, message
+      when /barcode|invalid data|checksum/i
+        raise InvalidBarcodeError, message
+      when /timeout/i
+        raise TimeoutError, message
+      when /index out of range|no labels/i
+        raise RenderError, message
+      else
+        raise RenderError, message
+      end
+    end
+  end
+end

data/lib/zpl_renderer/errors.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module ZplRenderer
+  class Error < StandardError; end
+
+  class ConfigurationError < Error; end
+  class ValidationError < Error; end
+  class UnsupportedCommandError < ValidationError; end
+  class InvalidBarcodeError < ValidationError; end
+  class RenderError < Error; end
+  class TimeoutError < RenderError; end
+  class BinaryMissingError < RenderError; end
+  class OutputTooLargeError < RenderError; end
+end