1. A length too long for any stock is a named refusal. Length.parse narrowed the micrometres to an int before it applied the 2 m limit, so "84600in" or "99999in" threw ArithmeticException: the opaque RENDER_FAILED, and an error instead of a REFUSED answer when collecting. The limit is now compared in long before narrowing, so it is SCENE_INVALID at the pointer of the length. 2. The printable area holds a box of its own size at every resolution. It was floor(far edge) less ceil(near margin), which can be one dot smaller than a box of the stated printable width: 100 mm stock with 3 mm margins and a 94 mm box fitted at 203 and 600 dpi and was refused at 300. It is now floor((W - L - R) x dpi) by floor((H - T - B) x dpi), the rounding of a box size, starting at ceil(L x dpi), ceil(T x dpi), moved back one dot where it would otherwise pass the page edge. New golden case `margins` with fractional-dot margins; the three existing goldens at 600 dpi are regenerated (the area grew by one dot each way; 203 and 300 unchanged). 3. The version 2 mutation campaign accepts only a Refusal (the package's own invariants are IllegalArgumentExceptions too) and renders about one input in four, reading the label back and comparing with validation. It found nothing at 20000 or 100000 iterations for either seed. 4. A refused answer carries no label bytes: with COLLECT and an error the answer had base64 of a label with elements missing. Scene2.render answers no label for a refused scene and the answer has no document fields. This changes the wire contract of section B.1 of the design, which records it. 5. One scene may paint sixteen times its printable area, an overlap counted each time, counted before any ink and in validation too. The element that would pass it is SCENE_INVALID with measured.paintedPercent against limit.paintedPercent 1600. 1000 fills of a 64 million dot canvas were 8 GB of byte writes; the worst scene is now 128 MB. 6. The README states what changed in the version 1 answer envelope in 0.2.0 (diagnostics on every answer; SCENE_INVALID with detail where unreadable JSON and a missing or unknown schema were RENDER_FAILED) and what the bridge must handle. The version 1 ZPL bytes are unchanged. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Isolated document renderer
This standalone Java CLI renders user-authored PDF layouts and typed ZPL label scenes. It has no QQQ classes, database access, storage credentials, HTTP service, or script broker. The application authorizes and supplies exact retained asset bytes and prepared JSON context. User templates must run in a separately qualified disposable sandbox; never add this renderer to the application JVM as an in-process fallback.
mvnw.cmd -B verify builds the CLI, runs Checkstyle and fixture tests, and copies runtime JARs into target/lib. target/qbit-document-renderer-0.1.0-SNAPSHOT.jar is the entry point. Java compilation targets 21 with selected warnings as errors. The container entry requires Java 21.0.13 and QQQ_RENDERER_MODE=container; the environment marker is only an accidental-use guard. It does not establish isolation. No renderer image or runtime is qualified yet; see qualification.json.
Source build
The PDF output dependency is a separately built, narrowly patched OpenHTML
module under com.kingsrook.thirdparty:openhtmltopdf-pdfbox:<family revision> (upstream 1.1.105 + QQQ patch p1).
Build it from the retained source into an isolated Maven repository before a
local renderer build; use that same repository with -Dmaven.repo.local=....
See the source build instructions.
Use clean verify when changing this dependency so target/lib cannot retain
the old output-module JAR. Docker builds the source and runs its fifteen vendor
regressions before compiling the renderer. Existing sealed image evidence does
not qualify this new dependency; the exact-image background corpus must pass.
Protocol
One UTF-8 JSON object followed by a newline enters stdin, and one JSON response followed by a newline exits stdout. No worker connection is reused. The host must enforce deadline, cgroup limits, input/output bounds, cancellation, container ownership and durable cleanup. The request is limited to 16 MiB before parsing; duplicate keys, trailing JSON, overlong strings and excessive nesting are rejected.
{
"protocol": "qbit-document-renderer/1",
"requestId": "generation-attempt-id",
"operation": "RENDER",
"format": "PDF",
"source": "<h1>${title}</h1>",
"stock": {
"widthMicrons": 101600, "heightMicrons": 152400,
"topMicrons": 5000, "rightMicrons": 5000,
"bottomMicrons": 5000, "leftMicrons": 5000, "dpi": 203
},
"context": { "title": "Packing slip" },
"assets": [],
"maximumBytes": 20971520
}
operation is RENDER, VALIDATE, or CATALOG. A catalog request needs only protocol, requestId and operation and returns versioned barcode IDs and typed option metadata. VALIDATE compiles PDF template syntax or checks the ZPL scene structure plus asset identity. It does not evaluate arbitrary context, certify future layout fit, or promise that every source option will render with every record. Production publication should also render representative fixtures inside the qualified boundary.
A successful render returns protocol, requestId, outcome: "OK", rendererVersion: "qqq-renderer-0.2.0", catalogVersion: "qqq-barcodes-9", mediaType, base64, SHA-256, decoded byte length, pageCount and diagnostics (a list, empty except for a version 2 scene). Validation returns no document bytes. Errors return outcome: "ERROR", code: "RENDER_FAILED"; no source/context or exception stack is included. A version 2 scene refusal returns its own code and one diagnostic as detail (see "ZPL scene 2").
Renderer 0.2.0 adds, all optional: "targetDpi" (203, 300 or 600; the resolution a version 2 scene is rendered at, by default the stock's dpi; a version 1 scene with a target other than its stock's dpi is refused as TARGET_REQUIRES_SCENE_2) and "diagnostics": "COLLECT" (keep every element's refusal instead of stopping at the first; the outcome is then REFUSED when there is at least one, and the answer carries the diagnostics and no document: no mediaType, base64, sha256, length or pageCount, so a host that looks for base64 without reading the outcome finds nothing to print). The operations INSPECT_ASSET and UPGRADE_SCENE are routed and answer UNSUPPORTED_OPERATION until their packages exist. A host bridge that accepts only qqq-renderer-0.1.0 does not accept these answers: upgrade the host library before the image. The host must independently check request identity, response shape, decoded size/hash, format policy, successful process termination and container removal. Worker-reported metadata is untrusted. An external parent must not persist raw stderr containing dependency diagnostics.
Compatibility of version 1 answers. The ZPL bytes of a version 1 scene are unchanged; the corpus in src/test/resources/compat-v1 holds them byte for byte. The answer envelope around them changed in two ways in 0.2.0, for a request a 0.1.0 host already sends. Every OK answer gains diagnostics: []: six fields for VALIDATE and eleven for RENDER, where there were five and ten. And a ZPL source that is not readable JSON, has no schema or has an unknown schema now answers code: "SCENE_INVALID" with a detail diagnostic (pointer "", or /schema), where 0.1.0 answered the opaque RENDER_FAILED. Every other version 1 refusal keeps its code. Nothing in a released host depended on RENDER_FAILED for those three cases: it is not a GenerationPorts.FailureCode, so bridges/renderer rejects such an answer as WORKER_ERROR_REJECTED, exactly as it rejects every 0.2.0 answer today (it accepts only qqq-renderer-0.1.0 and the exact 0.1.0 field counts). The bridge that accepts 0.2.0 must take the extra diagnostics field, detail on an error, the REFUSED outcome, and SCENE_INVALID and the other diagnostic codes as failure codes.
PDF authoring
PDF sources use FreeMarker 2.3.35 with enforced HTML autoescaping. Plain JSON objects, lists and scalars are the root model. Includes have no loader content, locale lookup is disabled, Java bean wrapping/API access and class construction are disabled. These are defense-in-depth settings; FreeMarker is not a hostile-code sandbox. Complex record/API logic belongs in the separate published TypeScript context script.
Layouts support the OpenHTMLtoPDF paged CSS model: physical stock sizes, margins, tables, repeating headers/footers, page breaks, absolute positioning, borders, images and retained TrueType fonts. This is a CSS 2.1-oriented print renderer, not a browser; flex/grid, JavaScript, SVG, OpenType/CFF fonts, interactive forms and active links are not supported. Every output page must match the stock's dimensions. Images and fonts are resolved exclusively from this invocation's manifest; unknown resources fail the job. CSS does not gain filesystem or network URL access.
<style>
body { font-family: UserFont; font-size: 10pt; }
table { width: 100%; border-collapse: collapse; }
td { border: 1px solid #ccc; padding: 4mm; }
</style>
<h1>Order ${order.id}</h1>
<img src="asset:logo">
<table>
<#list items as item>
<tr><td>${item.name}</td><td>${item.quantity}</td></tr>
</#list>
</table>
<qqq-barcode type="code128" value="${order.id}" scale="2" quiet="12"></qqq-barcode>
Barcode elements must be explicitly closed and empty; self-closing custom HTML tags can absorb following content and are rejected when that happens. Their dimensions are set from bitmap pixels and stock DPI, preserving integer module scale at the selected print resolution. Authors can position them but should not apply CSS transforms that distort bars. Optional options is a JSON object encoded as an HTML attribute, for example options='{"mode":"MICRO"}' for PDF417. Human-readable captions are ordinary author-controlled text.
Assets contain name, sha256, mediaType, and base64. Names are local identifiers, not paths. Allowed media are PNG, JPEG and TrueType (font/ttf). Fonts also require fontFamily and optionally fontWeight (100–900) and fontStyle (normal/italic). The host obtains bytes through authorized retained-file APIs, checks the pinned file version/hash, and supplies them offline. Font usage rights remain part of asset intake. Raw SVG, external fonts and image URLs are rejected.
ZPL authoring
ZPL sources are JSON scenes with schema qqq-zpl-scene/1, not raw ZPL templates. There is no raw-command escape hatch. Coordinates and sizes are integer printer dots, and stock DPI is 203, 300 or 600.
{
"schema": "qqq-zpl-scene/1",
"elements": [
{"type":"text","x":20,"y":20,"width":12,"height":24,"valuePath":"/order/id"},
{"type":"box","x":20,"y":60,"width":500,"height":2,"thickness":2},
{"type":"image","x":20,"y":90,"asset":"logo"},
{"type":"barcode","x":20,"y":150,"symbology":"qr","scale":4,"quiet":4,"value":"SHIPMENT-17"}
]
}
Text/barcodes require exactly one literal value or JSON Pointer valuePath; only scalar values are accepted. Barcode options is the same typed object as PDF. Boxes provide outlines or lines. Images print at their supplied pixel dimensions; preprocess retained assets to the intended printer resolution. Existing text uses the printer's font 0 with explicit width/height. The additive rasterText element renders dynamic record text using one exact retained TrueType face, without installing fonts on the printer or host:
{"type":"rasterText","x":20,"y":250,"fontAsset":"headingItalic","fontSize":32,"width":500,"height":120,"valuePath":"/record/customerName","align":"left","rotation":0,"threshold":128}
The fontAsset must name a supplied font/ttf asset. Choose the actual regular/bold/italic asset; this path does not synthesize a face or search installed fonts. All size and position units are integer printer dots. fontSize is 1–999. width and height are the unrotated layout box, each 1–4096 and at most 4,000,000 pixels together. rotation is clockwise 0, 90, 180 or 270; x/y locate the rotated box's top-left, and the complete final box must fit the stock. align is left, center or right; its default is left. Optional lineHeight is the baseline interval in dots (1–4096); omission uses the font's rounded-up line metrics. Small explicit intervals can intentionally overlap lines. Text automatically wraps using Java's supported shaping/bidirectional layout and the chosen physical face. Explicit LF starts a new line; other control characters and unpaired surrogates are rejected. There is no universal script/locale guarantee: missing glyphs are refused, and representative language/font fixtures remain required.
Text is limited to 1,024 UTF-8 bytes and 128 laid-out lines per element. Empty text yields a white box even at 1×1; spaces and explicit blank lines consume line metrics and must fit. Logical advance, line descent and actual shaped ink/pixel bounds are checked before drawing; overflow is an error, never truncation. Black antialiased glyphs on white are binarized using threshold (1–254, default128) before the existing graphic writer; no color commands are added. See the rasterText schema. Unknown properties on this element fail closed to catch misspelled layout controls.
Before any text font/raster allocation, the scene is bounded to 64 rasterText elements and 16,000,000 total unrotated raster pixels. Rendering additionally resolves all dynamic values and checks their combined 16 KiB UTF-8 limit before any such allocation. VALIDATE checks static layout/assets and literal text but cannot certify dynamic values, glyph coverage or future fit; render representative record fixtures before publication. Decoded fonts are cached only within one invocation. The new path requires a renderer image containing this implementation; sealed catalog4 image evidence predates it and does not qualify the addition.
Only ^XA, ^XZ, ^PW, ^LL, ^LH, ^CI28, ^FO, ^A0N, ^FH_, ^FD, ^FS, ^GB and ^GFA are generated. Text is fully hex-encoded UTF-8, so ^, ~ and _ in record values cannot become new commands. Barcode/image raster fields use fixed uppercase hex and split below the 99,999-byte field limit. Placement uses overflow-safe bounds checks. No stored formats, downloads, network commands, persistent settings, cuts or resets are emitted. The printing boundary still needs independent output grammar enforcement because a compromised worker must not be trusted to report safe printer bytes.
ZPL scene 2
A source with schema qqq-zpl-scene/2 is a layout in physical units that renders at 203, 300 or 600 dpi. The worker chooses the code path from schema alone: version 1 is unchanged and frozen, and any other source is refused as SCENE_INVALID. The schema is schema/zpl-scene-2.schema.json; the design is docs/design/LABEL-LAYOUT-FONTS-PREVIEW.md.
{
"schema": "qqq-zpl-scene/2",
"design": { "width": "4in", "height": "1in" },
"elements": [
{ "id": "frame", "type": "box", "thickness": "0.5pt" },
{ "id": "panel", "type": "group", "anchor": "center", "width": "50%", "height": "60%", "children": [
{ "id": "mark", "type": "box", "anchor": "bottom-right", "x": "1mm", "y": "1mm", "width": "6mm", "height": "3mm", "fill": true } ] },
{ "id": "rule", "type": "box", "anchor": "bottom-center", "y": "2mm", "width": "80%", "height": "0.2mm", "thickness": "0.2mm" }
],
"overrides": [ { "when": { "dpi": [203] }, "set": { "frame": { "thickness": "1dot" } } } ]
}
- Lengths are strings of a number (up to three decimals) and a unit:
mm,in,pt(1/72 in),%(of the container's width forxandwidth, of its height foryandheight) anddot. The most a length may be is 2 m (2000mm,78.74in,5669.292pt),32000dotor100%; anything longer, up to the largest number the syntax can write, isSCENE_INVALIDat its pointer. A physical length becomes whole micrometres, then dots at the render target: a position to the nearest dot, a box width or height rounded down, a thickness to the nearest dot and never less than one. Adotlength outside an override raises the warningDEVICE_UNIT_USED. - Coordinates start at the top left of the printable area, the stock less its margins. In dots the printable area is
floor((width - left - right) x dpi)wide andfloor((height - top - bottom) x dpi)high, which is how a box size is rounded, and it starts atceil(left x dpi),ceil(top x dpi), moved back by one dot where it would otherwise pass the page edge. So a box of exactly the printable width and height fits at 203, 300 and 600 dpi alike. No ink is ever a whole dot inside a margin; the right and bottom edges may pass theirs by a fraction of a dot (less than 0.125 mm at 203 dpi).designstates the stock the layout was drawn for; the request's stock must match it within 0.5 mm on each side (STOCK_MISMATCH). - Every element has a unique
id([A-Za-z][A-Za-z0-9_-]{0,31}), atype, ananchor(one of nine points, defaulttop-left: the same point of the box is placed on that point of its container),xandy(distances inward from the anchored edge; on a centred axis a shift that may be negative),widthandheight(omitted: the rest of the container), andalignandvalign(where content sits in the box). boxhasthicknessand optionalfill; a line is a box whose width or height is its thickness.grouphaschildren, placed relative to its box; groups nest four deep. A scene holds at most 1000 elements, and its elements may paint at most sixteen times its printable area in all, an overlap counted each time: a filled box counts its area, an outline its four bars, a group nothing. The element that would pass that is refused asSCENE_INVALIDat its pointer, with its box andmeasured.paintedPercentagainstlimit.paintedPercentof 1600. A real label paints less than twice its area; the limit holds the worst scene to sixteen fills of the canvas where 1000 were possible.text,barcodeandimageare parsed and placed by renderer0.2.0and then refused asRENDERER_TOO_OLD, with the box they would have had, until their packages are in the renderer.overridesreplace properties of declared elements at the listed resolutions and are the only place a scene may depend on resolution. They are checked for all three resolutions whatever the request's target.samplesare accepted and ignored by rendering.- Output. The whole label is composed on one 1-bit canvas and emitted as uncompressed
^GFAfields: rows are cut into bands wherever eight or more blank rows separate ink, each band is trimmed to its inked columns, and a band is continued in a further field at 99,999 bytes. Only^XA,^PW,^LL,^LH,^CI28,^FO,^GFA,^FSand^XZare emitted. - Diagnostics. A refusal is one diagnostic:
code,severity, theelementid, the element'sboxin dots from the top left of the printable area, andmeasuredandlimitas named integers.SCENE_INVALIDalso carriespointer, the JSON pointer of the offending place. A diagnostic names only an id the scene declares and points only through schema property names, array indexes and declared ids, so no record value, sample or unknown property name can leave the worker in one. A stock the printer language cannot address stays the opaqueRENDER_FAILED, as for version 1.
{ "code": "ELEMENT_OUTSIDE_PRINTABLE_AREA", "severity": "ERROR", "element": "mark", "box": [719, 0, 79, 39],
"measured": { "bottomDots": 39, "leftDots": 719, "rightDots": 798, "topDots": 0 },
"limit": { "bottomDots": 155, "leftDots": 0, "rightDots": 764, "topDots": 0 } }
Limits
Sources: 262,144 characters. Context: depth 16, 10,000 nodes, 65,536 characters per string, 262,144 aggregate text characters. Stock: 1 mm–2 m, valid margins, 72–1200 DPI (ZPL additionally bounds width to 9,999 dots and height to 32,000). Assets: 100 entries, 2 MiB each, 8 MiB aggregate; image dimensions ≤4096 and ≤4 million pixels. Expanded HTML: 2 million characters and 20,000 elements. PDF pages: 1–500, checked after rendering. Output: caller limit, hard maximum 100 MiB; normal host default is 20 MiB. ZPL: 1,000 elements; a version 2 scene paints at most 16 times its printable area. Barcodes: 4,000-character payload, scale 1–16, bounded quiet zones, ≤4 million pixels.
The PDF engine and font/image decoders can consume resources before post-render limits fire. A qualified container's independent CPU/memory/PID/wall limits remain mandatory for both validation and rendering. These ceilings are not performance guarantees; load testing and font/locale/large-batch qualification remain outstanding.
Barcode coverage
Catalog qqq-barcodes-9 offers 71 stable IDs: the 47 concrete OkapiBarcode 0.5.7 encoder families plus Han Xin, rMQR, DotCode and Ultracode through the pinned Zint 2.16.0 provider, and the attributed Code 93i and Co-op 2 of 5 encoders. This is a finite explicit catalog, not a claim to encode every standard. See BARCODES.md and the CATALOG response for modes and typed options; physical fitting (BARCODE-FIT.md) covers 13 default-option profiles and every other ID reports fit unsupported. Every family has a pinned upstream codeword/pattern vector and raster test; common variants also have independent ZXing decoding. A 4×6 PDF QR fixture is decoded after rasterization at 203 DPI.
This coverage means all encoder families in the pinned library, not every symbology ever invented or every possible library option. Physical verification on actual printers/scanners, carrier/GS1 application rules, grading and every mode/option combination remain separate qualification work. No equivalence substitution occurs for unsupported IDs.