WIP: feat(renderer): align a fitted ZPL barcode inside its fit box; justified font 0 text blocks #11

2026-11-11T17:08:14Z

james.maes commented

2026-11-11 17:08:14 +00:00

Draft. Do not merge before one label has been printed on a Zebra printer (see "Not verified").

Why

Greater Goods Forge's Echo prints GS1-128 labels through qqq-zpl-scene/1. A fitted barcode's size depends on its data, so a scene cannot centre it by position. The fitted raster always sat at the box origin, and an align on a barcode element was read and ignored (published scenes already carry "align":"center" expecting it to work). Printer font text had no justification either.

What

barcode with fit: optional align (left, center, right) and valign (top, middle, bottom) place the fitted raster inside the fit box. Absent, it stays at the origin, so scenes without them print exactly as before. Either field without fit, or another word, refuses with INVALID_BARCODE_FIT_PROFILE.
text: optional align, blockWidth, maxLines make a justified block. Each line is one font 0 field in a one-line ^FB block. The renderer breaks lines itself (at a space, or before an opening parenthesis), so the printer never wraps or hyphenates. Text without these fields is the single field it always was.
renderer/README.md documents both.

Behaviour change to know about

A published scene that already has "align":"center" on a fitted barcode starts being centred inside its box once a worker with this change is deployed. That is the evident intent of those scenes, but it is a visible change on the label.

Tests

./mvnw -B -pl renderer -am verify: 180 tests, 0 failures (6 new in ZplAlignmentTest), 0 Checkstyle violations. The new tests decode the emitted graphic field and check, on 4 x 1 in stock at 203 and 300 dpi, that the bars leave equal blank width on both sides (within one dot) for short, typical and long GS1-128 values at the largest whole-dot module; that the default stays at the origin; that the value is one centred block below the bars and inside the label; that a long value breaks before an application identifier onto a second line; and the refusals.

Not verified

Nothing was printed. ^FB centring by the printer's own font 0 (including the trailing \&) is standard ZPL II but has not been seen on a ZT231 or ZT411.
The line bound is blockWidth / width characters, the same font-width bound the single field already uses; it assumes no font 0 glyph is wider than the width parameter.
Only the renderer module was built; the reactor's other modules do not depend on this code path.

Release route

Worker change only (renderer/): it reaches a deployment as a new qqq-document-renderer image and the qqq-remote-renderer service image built on it, then the image pins in the deployment repository. No Forge dependency pin needs it.

🤖 Generated with Claude Code

Draft. Do not merge before one label has been printed on a Zebra printer (see "Not verified"). ## Why Greater Goods Forge's Echo prints GS1-128 labels through `qqq-zpl-scene/1`. A fitted barcode's size depends on its data, so a scene cannot centre it by position. The fitted raster always sat at the box origin, and an `align` on a barcode element was read and ignored (published scenes already carry `"align":"center"` expecting it to work). Printer font `text` had no justification either. ## What - `barcode` with `fit`: optional `align` (`left`, `center`, `right`) and `valign` (`top`, `middle`, `bottom`) place the fitted raster inside the fit box. Absent, it stays at the origin, so scenes without them print exactly as before. Either field without `fit`, or another word, refuses with `INVALID_BARCODE_FIT_PROFILE`. - `text`: optional `align`, `blockWidth`, `maxLines` make a justified block. Each line is one font 0 field in a one-line `^FB` block. The renderer breaks lines itself (at a space, or before an opening parenthesis), so the printer never wraps or hyphenates. Text without these fields is the single field it always was. - `renderer/README.md` documents both. ## Behaviour change to know about A published scene that already has `"align":"center"` on a fitted barcode starts being centred inside its box once a worker with this change is deployed. That is the evident intent of those scenes, but it is a visible change on the label. ## Tests `./mvnw -B -pl renderer -am verify`: 180 tests, 0 failures (6 new in `ZplAlignmentTest`), 0 Checkstyle violations. The new tests decode the emitted graphic field and check, on 4 x 1 in stock at 203 and 300 dpi, that the bars leave equal blank width on both sides (within one dot) for short, typical and long GS1-128 values at the largest whole-dot module; that the default stays at the origin; that the value is one centred block below the bars and inside the label; that a long value breaks before an application identifier onto a second line; and the refusals. ## Not verified - Nothing was printed. `^FB` centring by the printer's own font 0 (including the trailing `\&`) is standard ZPL II but has not been seen on a ZT231 or ZT411. - The line bound is `blockWidth / width` characters, the same font-width bound the single field already uses; it assumes no font 0 glyph is wider than the width parameter. - Only the renderer module was built; the reactor's other modules do not depend on this code path. ## Release route Worker change only (`renderer/`): it reaches a deployment as a new `qqq-document-renderer` image and the `qqq-remote-renderer` service image built on it, then the image pins in the deployment repository. No Forge dependency pin needs it. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

james.maes added 1 commit 2026-11-11 17:08:14 +00:00

feat(renderer): align a fitted ZPL barcode inside its fit box; justified font 0 text blocks

maven / build (push) Successful in 11m47s

Details

build / maven (push) Successful in 11m47s

Details

65344f5981

A fitted barcode's size depends on its data, so a scene cannot centre it by
position: until now the fitted raster always sat at the box origin and an
"align" on a barcode element was read and ignored.

- barcode with fit: optional align (left, center, right) and valign (top,
  middle, bottom) place the fitted raster inside the fit box. Absent, the
  raster stays at the origin, so published scenes print as before.
- text: optional align, blockWidth and maxLines make a justified block. Each
  line is one font 0 field in a one-line ^FB block; the renderer breaks lines
  itself (at a space, or before an opening parenthesis) so the printer never
  wraps or hyphenates. Text without these fields is unchanged.

Renderer module verify: 180 tests (6 new in ZplAlignmentTest), 0 Checkstyle
violations. Printer-side ^FB justification is not yet qualified on hardware.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>

All checks were successful

maven / build (push) Successful in 11m47s

Details

build / maven (push) Successful in 11m47s

Details

You are not authorized to merge this pull request.

This pull request can be merged automatically.

This branch is out-of-date with the base branch

This pull request is marked as a work in progress.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin feat/zpl-barcode-align:feat/zpl-barcode-align

git checkout feat/zpl-barcode-align

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: QRun-IO/qbit-document-generation#11