feat(export): PDF export rendered by the preview renderer

Author: u8array

README.md

@@ -82,7 +82,8 @@ The **ZPL** panel at the bottom shows the generated ZPL, **Copy** puts it on the
 
 - **File → Export ZPL:** saves a `.zpl` file, or `.prn` where the save dialog offers file types
 - **File → Send to Zebra Printer:** opens the send dialog. It sends over the network, through the Zebra Browser Print agent in the browser, or through the system spooler or USB on desktop.
-- **File → Print as Image (browser):** opens the Labelary preview, then the browser print dialog
+- **File → Export PDF:** saves one PDF page per label page, rendered by the preview renderer. With the renderer off it holds the current page only. A batch PDF holds one page per data row.
+- **File → Print as Image (browser):** opens the rendered label, then the browser print dialog
 
 ### 5. Save the design
 

packages/core/src/lib/pdfWriter.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { unzlibSync } from "fflate";
+import { writePdf, type PdfPage } from "./pdfWriter";
+
+const latin1 = (bytes: Uint8Array): string => Array.from(bytes, (b) => String.fromCharCode(b)).join("");
+
+const page = (fill: number): PdfPage => ({ widthMm: 50, heightMm: 30, width: 16, height: 8, mono: new Uint8Array(16).fill(fill) });
+
+describe("writePdf", () => {
+  it("lays out catalog, pages, info and one image per page with a cross-reference table whose offsets land on each object", () => {
+    const pdf = writePdf([page(0xff), page(0x0f)], { producer: "ZPLab", subject: "Rendered with a test" });
+    const text = latin1(pdf);
+    expect(text.startsWith("%PDF-1.4\n")).toBe(true);
+    expect(text.endsWith("%%EOF\n")).toBe(true);
+    expect(text).toContain("/Count 2");
+    expect(text).toContain("/MediaBox [0 0 141.73 85.04]");
+    expect(text).toContain("/Producer (ZPLab) /Subject (Rendered with a test)");
+    const xrefAt = Number(/startxref\n(\d+)\n%%EOF/.exec(text)![1]);
+    expect(text.slice(xrefAt, xrefAt + 4)).toBe("xref");
+    const entries = text.slice(xrefAt).split("\n").slice(2, 12);
+    expect(entries).toHaveLength(10);
+    entries.slice(1).forEach((entry, i) => {
+      const offset = Number(entry.slice(0, 10));
+      expect(text.slice(offset).startsWith(`${i + 1} 0 obj\n`)).toBe(true);
+    });
+  });
+
+  it("stores every stream with its exact length and the rows inverted for DeviceGray", () => {
+    const pdf = writePdf([page(0xf0)], { producer: "ZPLab" });
+    const text = latin1(pdf);
+    const streams = [...text.matchAll(/\/Length (\d+) >>\nstream\n/g)];
+    expect(streams).toHaveLength(2);
+    for (const m of streams) {
+      const start = m.index! + m[0].length;
+      expect(text.slice(start + Number(m[1]), start + Number(m[1]) + 10)).toBe("\nendstream");
+    }
+    const image = streams[0]!;
+    const start = image.index! + image[0].length;
+    const bytes = pdf.slice(start, start + Number(image[1]));
+    expect([...unzlibSync(bytes)]).toEqual(new Array(16).fill(0x0f));
+    expect(text).toContain("q 141.73 0 0 85.04 0 0 cm /Im0 Do Q");
+  });
+
+  it("escapes ASCII metadata, carries other scripts as UTF-16 and refuses what it cannot lay out", () => {
+    const text = latin1(writePdf([page(0)], { producer: "ZP(L)ab\\", title: "Étiquette", subject: "ラベル" }));
+    expect(text).toContain("/Producer (ZP\\(L\\)ab\\\\)");
+    expect(text).toContain("/Title <FEFF00C9007400690071007500650074007400650>".slice(0, 20));
+    expect(text).toContain("/Subject <FEFF30E930D930EB>");
+    expect(() => writePdf([], { producer: "ZPLab" })).toThrow();
+    expect(() => writePdf([{ ...page(0), mono: new Uint8Array(15) }], { producer: "ZPLab" })).toThrow();
+    expect(() => writePdf([{ ...page(0), width: 0 }], { producer: "ZPLab" })).toThrow();
+  });
+});

packages/core/src/lib/pdfWriter.ts

@@ -0,0 +1,104 @@
+import { zlibSync } from 'fflate';
+
+/** One label as a 1-bit raster: `height` rows of `ceil(width / 8)` bytes, a set bit prints black, like ^GF. */
+export interface PdfPage {
+  widthMm: number;
+  heightMm: number;
+  width: number;
+  height: number;
+  mono: Uint8Array;
+}
+
+export interface PdfMeta {
+  producer: string;
+  title?: string;
+  subject?: string;
+}
+
+const PT_PER_MM = 72 / 25.4;
+const encoder = new TextEncoder();
+
+/** A text string: escaped ASCII when that suffices, else UTF-16BE with a byte-order mark as a hex string. */
+function literal(text: string): string {
+  if (/^[\x20-\x7e]*$/.test(text)) return `(${text.replace(/[\\()]/g, (c) => `\\${c}`)})`;
+  const units: string[] = ['FEFF'];
+  for (let i = 0; i < text.length; i++) units.push(text.charCodeAt(i).toString(16).toUpperCase().padStart(4, '0'));
+  return `<${units.join('')}>`;
+}
+
+function pt(mm: number): string {
+  return (Math.round(mm * PT_PER_MM * 100) / 100).toString();
+}
+
+/** DeviceGray reads a set bit as white, so the rows flip before they are written. */
+function invert(mono: Uint8Array): Uint8Array {
+  const out = new Uint8Array(mono.length);
+  for (let i = 0; i < mono.length; i++) out[i] = ~(mono[i] ?? 0) & 0xff;
+  return out;
+}
+
+/** A minimal PDF 1.4 with one Flate-compressed 1-bit image per page and a cross-reference table with exact byte offsets. */
+export function writePdf(pages: readonly PdfPage[], meta: PdfMeta): Uint8Array {
+  if (pages.length === 0) throw new Error('a PDF needs at least one page');
+  for (const p of pages) {
+    if (!(p.width > 0) || !(p.height > 0)) throw new Error('a page needs a width and a height in dots');
+    if (p.mono.length !== Math.ceil(p.width / 8) * p.height) throw new Error('raster length does not match its dimensions');
+  }
+  const chunks: Uint8Array[] = [];
+  const offsets: number[] = [];
+  let length = 0;
+  const push = (bytes: Uint8Array): void => {
+    chunks.push(bytes);
+    length += bytes.length;
+  };
+  const text = (s: string): void => push(encoder.encode(s));
+  const object = (n: number, body: string, stream?: Uint8Array): void => {
+    offsets[n] = length;
+    text(`${n} 0 obj\n${body}\n`);
+    if (stream) {
+      text('stream\n');
+      push(stream);
+      text('\nendstream\n');
+    }
+    text('endobj\n');
+  };
+
+  // Binary comment after the header, so transfer tools treat the file as binary.
+  push(new Uint8Array([0x25, 0x50, 0x44, 0x46, 0x2d, 0x31, 0x2e, 0x34, 0x0a, 0x25, 0xe2, 0xe3, 0xcf, 0xd3, 0x0a]));
+  const firstPage = 4;
+  const pageIds = pages.map((_, i) => firstPage + i * 3);
+  object(1, '<< /Type /Catalog /Pages 2 0 R >>');
+  object(2, `<< /Type /Pages /Kids [${pageIds.map((id) => `${id} 0 R`).join(' ')}] /Count ${pages.length} >>`);
+  const info = [`/Producer ${literal(meta.producer)}`, meta.title === undefined ? '' : `/Title ${literal(meta.title)}`, meta.subject === undefined ? '' : `/Subject ${literal(meta.subject)}`]
+    .filter((s) => s !== '')
+    .join(' ');
+  object(3, `<< ${info} >>`);
+  pages.forEach((page, i) => {
+    const id = firstPage + i * 3;
+    const w = pt(page.widthMm);
+    const h = pt(page.heightMm);
+    object(id, `<< /Type /Page /Parent 2 0 R /MediaBox [0 0 ${w} ${h}] /Resources << /XObject << /Im0 ${id + 1} 0 R >> >> /Contents ${id + 2} 0 R >>`);
+    const image = zlibSync(invert(page.mono));
+    object(
+      id + 1,
+      `<< /Type /XObject /Subtype /Image /Width ${page.width} /Height ${page.height} /ColorSpace /DeviceGray /BitsPerComponent 1 /Filter /FlateDecode /Length ${image.length} >>`,
+      image,
+    );
+    const content = encoder.encode(`q ${w} 0 0 ${h} 0 0 cm /Im0 Do Q`);
+    object(id + 2, `<< /Length ${content.length} >>`, content);
+  });
+
+  const count = firstPage + pages.length * 3;
+  const xref = length;
+  text(`xref\n0 ${count}\n0000000000 65535 f \n`);
+  for (let n = 1; n < count; n++) text(`${String(offsets[n]).padStart(10, '0')} 00000 n \n`);
+  text(`trailer\n<< /Size ${count} /Root 1 0 R /Info 3 0 R >>\nstartxref\n${xref}\n%%EOF\n`);
+
+  const out = new Uint8Array(length);
+  let at = 0;
+  for (const c of chunks) {
+    out.set(c, at);
+    at += c.length;
+  }
+  return out;
+}

src/components/AppShell.tsx

@@ -42,7 +42,7 @@ import {
   MoonIcon,
   GlobeAltIcon,
 } from "@heroicons/react/16/solid";
-import { useLabelStore, useHistory, selectLabelaryNoticeRequired, selectEditorFrozen, selectSourceEditing, selectSourceEditDirty, selectDocumentEmits, selectBatchPrintCount } from "../store/labelStore";
+import { useLabelStore, useHistory, selectLabelaryNoticeRequired, selectEffectivePreviewProvider, selectEditorFrozen, selectSourceEditing, selectSourceEditDirty, selectDocumentEmits, selectBatchPrintCount } from "../store/labelStore";
 import { datasetTimestamp } from "@zplab/core/types/DataSource";
 import { isCurrentDataContext, settleDatasetReplace } from "../store/datasetActions";
 import { ConfirmDialog } from "./ui/ConfirmDialog";
@@ -54,6 +54,8 @@ import { isDesktopShell, isMacDesktop } from "../lib/platform";
 import { acceptAttr, DESIGN_FILTER, CSV_FILTER } from "../lib/fileDialogs";
 import { openExternal, REPO_URL } from "../lib/openExternal";
 import { LabelaryNoticeModal } from "./Output/LabelaryNoticeModal";
+import { PdfExportDialog } from "./Output/PdfExportDialog";
+import { usePdfExport } from "../hooks/usePdfExport";
 import { PrinterSettingsModal } from "./PrinterSettings/PrinterSettingsModal";
 import { Gs1ContentModal } from "./Barcode/Gs1ContentModal";
 import { ContentBuilderModal } from "./Barcode/ContentBuilderModal";
@@ -106,6 +108,8 @@ const MENU_ICONS: Partial<Record<MenuItemId, ComponentType<SVGProps<SVGSVGElemen
   settings: Cog6ToothIcon,
   exportZpl: ArrowDownTrayIcon,
   exportBatch: ArrowDownTrayIcon,
+  exportPdf: ArrowDownTrayIcon,
+  exportBatchPdf: ArrowDownTrayIcon,
   openDesign: FolderOpenIcon,
   saveDesign: DocumentArrowDownIcon,
   importCsv: TableCellsIcon,
@@ -135,9 +139,12 @@ export function AppShell() {
   const restoreReplacedDesign = useLabelStore((s) => s.restoreReplacedDesign);
   const dismissReplacedDesign = useLabelStore((s) => s.dismissReplacedDesign);
   const sourceEditDirty = useLabelStore(selectSourceEditDirty);
-  const labelaryEnabled = useLabelStore((s) => s.thirdParty.labelary);
   const noticeRequired = useLabelStore(selectLabelaryNoticeRequired);
-  const [showPrintNotice, setShowPrintNotice] = useState(false);
+  const renderer = useLabelStore(selectEffectivePreviewProvider);
+  const pageCount = useLabelStore((s) => s.pages.length);
+  // The Labelary notice gates every Labelary render, so the action waits here until the user continues.
+  const [afterNotice, setAfterNotice] = useState<(() => void) | null>(null);
+  const withNotice = (action: () => void) => (renderer === "labelary" && noticeRequired ? setAfterNotice(() => action) : action());
   const appUpdate = useLabelStore((s) => s.appUpdate);
   const checkForAppUpdate = useLabelStore((s) => s.checkForAppUpdate);
   const installAppUpdate = useLabelStore((s) => s.installAppUpdate);
@@ -205,6 +212,9 @@ export function AppShell() {
   // timestamp is unique per import/fetch, so it also catches re-loading the
   // same file or table (which a name key would miss).
   const datasetKey = useLabelStore((s) => s.dataset && datasetTimestamp(s.dataset.source));
+  // Imperative handle to the canvas: live render bboxes for the properties panel and the label capture for print and PDF.
+  const canvasRef = useRef<LabelCanvasHandle>(null);
+  const { progress: pdfProgress, exportPdf, exportBatchPdf, cancel: cancelPdfExport } = usePdfExport(canvasRef);
   const {
     showZplImport,
     openZplImport,
@@ -218,7 +228,7 @@ export function AppShell() {
     canBatchExport,
     batchRowCount,
     handlePrint,
-  } = useZplImportExport();
+  } = useZplImportExport(canvasRef);
   const outputPanel = useOutputPanel(OUTPUT_DEFAULT_H, sourceEditing);
   const leftPanel = useCollapsiblePanel("zpl-panel-left");
   const rightPanel = useCollapsiblePanel("zpl-panel-right");
@@ -233,7 +243,8 @@ export function AppShell() {
     batchRowCount,
     batchPrintCount,
     connectDataWizard: isDesktopShell,
-    labelaryEnabled,
+    canBatchPdf: renderer !== "none",
+    pdfCurrentPageOnly: renderer === "none" && pageCount > 1,
     canUndo,
     canRedo,
     // On macOS quit lives in the app submenu (Cmd+Q), not the File section.
@@ -246,24 +257,20 @@ export function AppShell() {
     settings: () => setPrinterSettingsTab("appSettings"),
     exportZpl: handleDownload,
     exportBatch: handleExportBatch,
+    exportPdf: () => withNotice(exportPdf),
+    exportBatchPdf: () => withNotice(exportBatchPdf),
     openDesign: handleOpen,
     saveDesign: handleSave,
     importCsv: openCsvPicker,
     connectData: openConnectWizard,
-    // Print routes through Labelary; clicking before the notice has been
-    // acknowledged opens the disclosure first, then prints.
-    print: () => (noticeRequired ? setShowPrintNotice(true) : void handlePrint()),
+    print: () => withNotice(() => void handlePrint()),
     sendToZebra: openZebraPrint,
     undo: () => undo(),
     redo: () => redo(),
     github: () => openExternal(REPO_URL),
     // Desktop-only item (includeQuit); never reached on web.
     quit: () => void quitApp(),
   };
-  // Imperative handle to the canvas for actions PropertiesPanel needs live
-  // render bboxes for (e.g. align-to-label centring).
-  const canvasRef = useRef<LabelCanvasHandle>(null);
-
   return (
     <div className="flex flex-col h-screen overflow-hidden bg-bg text-text font-sans">
       <SourceShadowSync />
@@ -595,15 +602,16 @@ export function AppShell() {
       {showZebraPrint && (
         <PrintToZebraDialog zpl={currentZpl()} onClose={closeZebraPrint} />
       )}
-      {showPrintNotice && (
+      {afterNotice && (
         <LabelaryNoticeModal
-          onClose={() => setShowPrintNotice(false)}
+          onClose={() => setAfterNotice(null)}
           onContinue={() => {
-            setShowPrintNotice(false);
-            handlePrint();
+            setAfterNotice(null);
+            afterNotice();
           }}
         />
       )}
+      {pdfProgress && <PdfExportDialog progress={pdfProgress} onCancel={cancelPdfExport} />}
       <PrinterSettingsModal />
       <Gs1ContentModal />
       <ContentBuilderModal />

src/components/Canvas/BarcodeObject.tsx

@@ -8,7 +8,7 @@ import { barcodeFtAnchorOffset, qrPrintsAsGraphic, rightAnchorShiftDots } from "
 import { qrByHeight } from "@zplab/core/registry/qrcode";
 import { useColorScheme, CANVAS_WARNING } from "../../hooks/useColorScheme";
 import { useFontCacheVersion } from "../../hooks/useFontCacheVersion";
-import { selectionHandlers, useBlankFieldWarns, PLACEHOLDER_DASH, PLACEHOLDER_STROKE_PX, type KonvaObjectProps } from "./konvaObjectProps";
+import { selectionHandlers, useBlankFieldWarns, CAPTURE_CHROME, PLACEHOLDER_DASH, PLACEHOLDER_STROKE_PX, type KonvaObjectProps } from "./konvaObjectProps";
 import { setMeasuredBounds, clearMeasuredBounds } from "../../lib/measuredBoundsCache";
 import {
   getDisplaySize,
@@ -82,6 +82,7 @@ export function StateFrame({
 }) {
   return (
     <Shape
+      name={CAPTURE_CHROME}
       listening={false}
       sceneFunc={(ctx) => {
         // Scale by the inherited alpha (a plain Rect would); the drop ghost
@@ -447,7 +448,7 @@ export function BarcodeObject({
           onDragMove={handleDragMove}
           onDragEnd={handleDragEnd}
         >
-          <Group x={innerTr.x} y={innerTr.y} rotation={innerTr.rotation}>
+          <Group x={innerTr.x} y={innerTr.y} rotation={innerTr.rotation} name={showSample ? CAPTURE_CHROME : undefined}>
             <KImage
               x={ub.barLeftPx}
               y={ub.barTopPx}
@@ -512,7 +513,7 @@ export function BarcodeObject({
         onDragMove={handleDragMove}
         onDragEnd={handleDragEnd}
       >
-        <Group x={defaultInnerTr.x} y={defaultInnerTr.y} rotation={defaultInnerTr.rotation}>
+        <Group x={defaultInnerTr.x} y={defaultInnerTr.y} rotation={defaultInnerTr.rotation} name={showSample ? CAPTURE_CHROME : undefined}>
           <KImage
             x={ub.barLeftPx}
             y={ub.barTopPx}

src/components/Canvas/KonvaObject.tsx

@@ -133,6 +133,7 @@ function PlaceholderRect({
   return (
     <Rect
       key={fontVersion}
+      name={CAPTURE_CHROME}
       x={x}
       y={y}
       width={width}