goodboy008/labelize/fix-zpl-render

Fix ZPL Rendering — Auto-Learn from Official Docs

Purpose

Systematically diagnose rendering mismatches in labelize by:

1. Identifying which ZPL command(s) cause the visual difference
2. Fetching the official Zebra spec for those commands
3. Comparing spec behavior with labelize implementation
4. Applying the fix

Critical Rule — Fix Rendering Code, Never Tests

DO NOT modify diff tests, golden test infrastructure, reference images, tolerance thresholds (to hide regressions), or test comparison logic to make diffs pass. The goal is to improve rendering accuracy, not to weaken the test harness.

DO fix the root cause in rendering code and logic:

• Parsers: src/parsers/
• Elements: src/elements/
• Barcode encoders: src/barcodes/
• Renderer / drawing: src/drawers/
• Font handling: src/assets/

Threshold updates in docs/DIFF_THRESHOLDS.md are only allowed after a rendering fix genuinely lowers the diff percentage — set the new tolerance slightly above the new measured diff, never raise it to paper over a regression.

When to Use

• A golden test exceeds its diff threshold
• Visual inspection shows wrong barcode, text position, or graphic
• A new ZPL label renders incorrectly
• Need to reduce diff percentage for a specific label

Procedure

Phase 1: Identify the Problem

1. Get the label source — Read the ZPL file from testdata/labels/<name>.zpl or testdata/unit/<name>.zpl
2. Check current diff — Look up the label in docs/DIFF_THRESHOLDS.md for the current diff percentage and known cause
3. Run the golden test for the specific label:

``bash cargo test --test e2e -- <label_name> --nocapture ``

1. Inspect the diff image — Check testdata/diffs/<name>.png to see which pixels differ (red = mismatch)
2. Parse the ZPL — Read through the .zpl file and list every ZPL command used

Phase 2: Learn from Official Docs

1. For each suspect command, fetch the official Zebra documentation:

`` https://docs.zebra.com/us/en/printers/software/zpl-pg/c-zpl-zpl-commands/r-zpl-<slug>.html ``

Use the #tool:fetch_webpage tool. Common command slugs:

1. Extract from the doc:

• Exact parameter order, types, and default values
• Parameter interaction rules (e.g., "if omitted, uses value set by ^BY")
• Coordinate system details (top-left vs baseline, dot units)
• Any special behavior notes

1. For field interactions, also fetch:

`` https://docs.zebra.com/us/en/printers/software/zpl-pg/r-zpl-interactions-field-interactions.html ``

Phase 3: Compare with Implementation

1. Find the parser code — Search in src/parsers/zpl_parser.rs for the command prefix
2. Find the element struct — Check src/elements/<relevant_element>.rs
3. Find the renderer code — Check src/drawers/renderer.rs for how the element is drawn
4. For barcodes — Also check src/barcodes/<barcode_type>.rs for encoding logic

1. Compare systematically:

Phase 4: Fix and Verify

1. Implement the fix — Edit the parser, element, renderer, or barcode encoder as needed
2. Run the specific test:

``bash cargo test --test e2e -- <label_name> --nocapture ``

1. Run all tests to check for regressions:

``bash cargo test ``

1. Update threshold — If the diff improved, update docs/DIFF_THRESHOLDS.md with the new percentage

Diagnostic Patterns

Common Root Causes

Known High-Diff Labels and Focus Areas

References

• ZPL Command Index
• Field Interactions
• Fonts and Barcodes
• Diff Thresholds
• Rendering behavior and evidence