From 081639fd45ecce7e570be810955a44e4dccf056e Mon Sep 17 00:00:00 2001
From: u8array <alexanderleinich1@gmail.com>
Date: Sat, 30 May 2026 22:24:40 +0200
Subject: [PATCH 1/4] chore(cleanup): post-printer-profile housekeeping
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Five themes folded into one commit:

1. designFile: require explicit \`schemaVersion\` (= 1) on the
   exported design-file JSON, drop the two legacy fallback shapes
   (pre-version pages-only + pre-multipage objects-only). The
   project is young; carrying those branches forward would mean
   a v1→v2 migration later having to dispatch over three shapes
   instead of one. Files saved by older builds now fail loud
   (invalid_schema) instead of silently upgrading.

2. Visual-regression re-framing: the text visual suite uploads
   PrintLabZPL-Bold.ttf to Labelary and registers the same TTF
   locally with @napi-rs/canvas, so both sides render with
   identical glyph data. The test measures Skia-vs-Labelary
   anti-aliasing drift, NOT firmware fidelity. Renamed and
   re-documented to reflect what it actually checks.

3. Comment trim across the printer-profile epic files
   (zplSetupScript, PrinterProfile, PrinterSettingsModal,
   pruneUndefined, useCopyToClipboard) — drop multi-paragraph
   module headers and per-field docstrings that restate the spec;
   keep firmware-quirk anchors (^TA padding, ^KN trim, ^SL three-
   shape), schema cross-field rule, live-clock mode rationale.
   ~120 lines of retroactive review-prose removed.

4. Dead-code: two locale keys orphaned by the modal refactor
   (\`output.setupScriptHeading\`, \`output.hiddenSecondaryHint\`)
   removed across all 32 locales; \`src/registry/_template.ts\`
   scaffold-only file removed (never imported, no value as
   documentation — contributors can copy any concrete registry
   entry instead).

5. API-surface trim: 8 internal-only exports demoted from
   \`export\` to local scope so the public module surface tracks
   what's actually consumed elsewhere — LabelaryError,
   partialLoss, AUTO_SNAP_TOLERANCE_DEG, GRAPHIC_EXT,
   LIGHT_COLORS, ROOT_CONTAINER, toCode128BRaw,
   commitRotatedSizeTransform.
---
 src/components/Canvas/bwipHelpers.ts          |   2 +-
 .../PrinterSettings/PrinterSettingsModal.tsx  |  57 ++-----
 src/components/Properties/useLayerDnd.ts      |   2 +-
 src/lib/designFile.test.ts                    |  50 +++---
 src/lib/designFile.ts                         |  53 +++----
 src/lib/importReport.ts                       |   2 +-
 src/lib/labelary.ts                           |   2 +-
 src/lib/lineConstrain.ts                      |   2 +-
 src/lib/pruneUndefined.ts                     |  14 +-
 src/lib/storagePath.ts                        |   2 +-
 src/lib/useColorScheme.ts                     |   2 +-
 src/lib/useCopyToClipboard.ts                 |  18 +--
 src/lib/zplSetupScript.ts                     | 150 ++++--------------
 src/locales/ar.ts                             |   2 -
 src/locales/bg.ts                             |   2 -
 src/locales/cs.ts                             |   2 -
 src/locales/da.ts                             |   2 -
 src/locales/de.ts                             |   2 -
 src/locales/el.ts                             |   2 -
 src/locales/en.ts                             |   2 -
 src/locales/es.ts                             |   2 -
 src/locales/et.ts                             |   2 -
 src/locales/fa.ts                             |   2 -
 src/locales/fi.ts                             |   2 -
 src/locales/fr.ts                             |   2 -
 src/locales/he.ts                             |   2 -
 src/locales/hr.ts                             |   2 -
 src/locales/hu.ts                             |   2 -
 src/locales/it.ts                             |   2 -
 src/locales/ja.ts                             |   2 -
 src/locales/ko.ts                             |   2 -
 src/locales/lt.ts                             |   2 -
 src/locales/lv.ts                             |   2 -
 src/locales/nl.ts                             |   2 -
 src/locales/no.ts                             |   2 -
 src/locales/pl.ts                             |   2 -
 src/locales/pt.ts                             |   2 -
 src/locales/ro.ts                             |   2 -
 src/locales/sk.ts                             |   2 -
 src/locales/sl.ts                             |   2 -
 src/locales/sr.ts                             |   2 -
 src/locales/sv.ts                             |   2 -
 src/locales/tr.ts                             |   2 -
 src/locales/zh-hans.ts                        |   2 -
 src/locales/zh-hant.ts                        |   2 -
 src/registry/_template.ts                     |  25 ---
 src/registry/transformHelpers.ts              |   2 +-
 src/test/textVisualRegression.test.ts         |  19 ++-
 src/types/PrinterProfile.ts                   |  40 ++---
 tests/fixtures/textTestCases.ts               |  14 +-
 50 files changed, 136 insertions(+), 384 deletions(-)
 delete mode 100644 src/registry/_template.ts

diff --git a/src/components/Canvas/bwipHelpers.ts b/src/components/Canvas/bwipHelpers.ts
index 3755d060..61f14e6e 100644
--- a/src/components/Canvas/bwipHelpers.ts
+++ b/src/components/Canvas/bwipHelpers.ts
@@ -267,7 +267,7 @@ export { eanCheckDigit, upceCheckDigit } from "../../lib/barcodeCheckDigits";
  * Code B here keeps the designer's module count in sync with Labelary.
  * Returns null for characters outside Code B range (ASCII 32–126).
  */
-export function toCode128BRaw(text: string): string | null {
+function toCode128BRaw(text: string): string | null {
   if (!text) return null;
   const parts = ["^104"]; // Start B
   for (const ch of text) {
diff --git a/src/components/PrinterSettings/PrinterSettingsModal.tsx b/src/components/PrinterSettings/PrinterSettingsModal.tsx
index a3032058..ec4df60e 100644
--- a/src/components/PrinterSettings/PrinterSettingsModal.tsx
+++ b/src/components/PrinterSettings/PrinterSettingsModal.tsx
@@ -15,11 +15,8 @@ import { PrintQualityTab } from "./PrintQualityTab";
 
 type TopTabId = 'perLabel' | 'setupScript';
 
-/** Sub-tab → top-tab assignment. `satisfies` makes TypeScript flag
- *  any `PrinterSettingsTab` literal that is added to the union but
- *  forgotten here — without this, a missing tab would silently
- *  default at runtime. This is the source of truth; rail groups
- *  below are derived from it. */
+/** Sub-tab → top-tab. `satisfies` flags any PrinterSettingsTab union
+ *  literal that gets added but forgotten here at compile time. */
 const TOP_TAB_OF = {
   mediaFeed: 'perLabel',
   printQuality: 'perLabel',
@@ -35,12 +32,6 @@ const TOP_TAB_LABEL_KEY = {
   setupScript: 'railGroupSetupScript',
 } as const satisfies Record<TopTabId, 'railGroupPerLabel' | 'railGroupSetupScript'>;
 
-/** Rail-tab order per top-tab, derived from TOP_TAB_OF so the source
- *  of truth stays the single literal map above. Iteration order over
- *  TOP_TAB_OF entries is insertion order, which is the desired rail
- *  order — keep entries in the map in the order the rail should show
- *  them. Seed is derived from TOP_TAB_ORDER so a new TopTabId added
- *  there can't silently produce `undefined.push(...)` at runtime. */
 const TABS_BY_TOP_TAB: Record<TopTabId, readonly PrinterSettingsTab[]> = (() => {
   const acc = Object.fromEntries(
     TOP_TAB_ORDER.map((id) => [id, [] as PrinterSettingsTab[]]),
@@ -51,9 +42,7 @@ const TABS_BY_TOP_TAB: Record<TopTabId, readonly PrinterSettingsTab[]> = (() =>
   return acc;
 })();
 
-/** Per-tab content registry. Tabs absent here render as disabled
- *  WIP rail entries; the rail prevents selection so the modal
- *  never has to handle a missing-component branch. */
+/** Tabs absent here render as disabled WIP rail entries. */
 const TAB_COMPONENTS: Partial<Record<PrinterSettingsTab, FC>> = {
   mediaFeed: MediaFeedTab,
   printQuality: PrintQualityTab,
@@ -62,21 +51,10 @@ const TAB_COMPONENTS: Partial<Record<PrinterSettingsTab, FC>> = {
   identity: IdentityTab,
 };
 
-/** Modal-box class kept as a constant rather than inline so the
- *  width / shadow tuning is named and stays consistent if other
- *  modals adopt the same shell. Fixed height (h-[600px]) so the
- *  modal does not resize when switching tabs of different field
- *  counts; the docked preview anchors at the bottom. `max-h-[85vh]`
- *  is a fallback cap for very short viewports. */
 const MODAL_BOX_CLS =
   "bg-surface border border-border rounded-lg shadow-2xl " +
   "w-[720px] max-w-[95vw] h-[600px] max-h-[85vh] flex flex-col overflow-hidden";
 
-/** Docked preview height. 160px = ~9 lines of mono ZPL at 13px/1.45
- *  plus the header strip and padding. Fixed (not collapsible) so the
- *  modal's vertical rhythm stays identical across top-tabs; the empty
- *  per-label state keeps the same height as the populated setup-script
- *  state. */
 const PREVIEW_HEIGHT = "h-40";
 
 export function PrinterSettingsModal() {
@@ -126,11 +104,8 @@ export function PrinterSettingsModal() {
       </header>
 
       <div
-        // Plain nav, not tablist. The rail below uses `aria-current`
-        // (page-style) navigation buttons; using `role="tablist"`
-        // here as well would force the rail into tab semantics too,
-        // and a single page with two different "tab" paradigms is
-        // worse than two plain navs.
+        // Plain nav (not role=tablist) so the strip + rail share one
+        // a11y paradigm.
         className="px-5 pt-3 border-b border-border flex gap-1"
         aria-label={t.printerSettings.title}
       >
@@ -210,10 +185,8 @@ export function PrinterSettingsModal() {
   );
 }
 
-/** Docked preview pane at the bottom of the modal, rendered only on
- *  the Setup-Script top-tab. Shows the freshly-generated script plus
- *  Copy + Send actions. Per-Label has no preview here because per-
- *  label ZPL still lives in the editor's main output panel. */
+/** Docked preview pane on the Setup-Script top-tab. Per-Label has no
+ *  preview here — its ZPL still lives in the editor's main output. */
 function PreviewDock({
   setupScript,
   printerProfile,
@@ -226,8 +199,7 @@ function PreviewDock({
   onSend: () => void;
 }) {
   const t = useT();
-  // Live-clock mode (useCurrentTimeForClock) needs the payload
-  // freshly generated at click-time, not the closured snapshot.
+  // Live-clock mode needs the payload generated at click-time.
   const { copy, copied } = useCopyToClipboard(() => generateSetupScript(printerProfile));
 
   const hasScript = !!setupScript;
@@ -239,21 +211,14 @@ function PreviewDock({
           {t.printerSettings.previewHeading}
         </span>
         <div className="flex items-center gap-3">
-          {/* Clear sits on the destructive side of a divider so the
-              red-hover affordance + spatial separation make a mis-
-              click into the adjacent primary (Send) much less
-              likely. Same muted resting state as Copy keeps the
-              header visually quiet until hover. */}
+          {/* Clear: separated from Send by a divider; red hover +
+              red focus-visible ring so destructive intent is visible
+              to both pointer and keyboard users. */}
           <button
             type="button"
             onClick={onClear}
             disabled={!hasScript}
             title={t.printerSettings.previewClear}
-            // Destructive intent: red hover AND a red focus ring so
-            // keyboard users see the same warning the mouse hover
-            // gives. Without the ring keyboard-tab onto Clear shows
-            // the default browser focus style — identical to Copy /
-            // Send next to it.
             className="flex items-center gap-1 font-mono text-[10px] text-muted hover:text-red-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-500/40 rounded disabled:opacity-25 disabled:cursor-not-allowed transition-colors"
           >
             <TrashIcon className="w-4 h-4" />
diff --git a/src/components/Properties/useLayerDnd.ts b/src/components/Properties/useLayerDnd.ts
index 246b6d98..9d1ca858 100644
--- a/src/components/Properties/useLayerDnd.ts
+++ b/src/components/Properties/useLayerDnd.ts
@@ -7,7 +7,7 @@ import { INDENT_STEP } from './layerLayout';
 
 /** Sentinel container id for the top-level objects list. Group containers
  *  use the group's own id, so the root needs a value that can't collide. */
-export const ROOT_CONTAINER = '__root__';
+const ROOT_CONTAINER = '__root__';
 
 /** Pixel bias subtracted from the cursor X before quantising to depth so a
  *  user has to drag a little before the target depth changes. Tuned to feel
diff --git a/src/lib/designFile.test.ts b/src/lib/designFile.test.ts
index e3108001..a668bdb5 100644
--- a/src/lib/designFile.test.ts
+++ b/src/lib/designFile.test.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { parseDesignFile, serializeDesign } from './designFile';
+import { parseDesignFile, serializeDesign, CURRENT_DESIGN_SCHEMA_VERSION } from './designFile';
 import type { LabelObject } from '../types/Group';
 import type { Variable } from '../types/Variable';
 
@@ -25,6 +25,15 @@ describe('serializeDesign', () => {
     expect(parsed.pages[0]?.objects).toHaveLength(1);
   });
 
+  it('writes the current schemaVersion field', () => {
+    const json = serializeDesign(
+      { widthMm: 100, heightMm: 60, dpmm: 8 },
+      [{ objects: SAMPLE_OBJECTS }],
+    );
+    const parsed = JSON.parse(json) as { schemaVersion: number };
+    expect(parsed.schemaVersion).toBe(CURRENT_DESIGN_SCHEMA_VERSION);
+  });
+
   it('serializes multiple pages', () => {
     const json = serializeDesign(
       { widthMm: 100, heightMm: 60, dpmm: 8 },
@@ -48,16 +57,27 @@ describe('parseDesignFile', () => {
     expect(result.value.pages[0]?.objects).toHaveLength(1);
   });
 
-  it('migrates legacy { label, objects } shape into a single page', () => {
-    const legacyJson = JSON.stringify({
+  it('rejects files without a schemaVersion field', () => {
+    const json = JSON.stringify({
       label: { widthMm: 100, heightMm: 60, dpmm: 8 },
-      objects: SAMPLE_OBJECTS,
+      pages: [{ objects: SAMPLE_OBJECTS }],
     });
-    const result = parseDesignFile(legacyJson);
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-    expect(result.value.pages).toHaveLength(1);
-    expect(result.value.pages[0]?.objects).toHaveLength(1);
+    const result = parseDesignFile(json);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toBe('invalid_schema');
+  });
+
+  it('rejects an unknown schemaVersion as invalid_schema', () => {
+    const futureJson = JSON.stringify({
+      schemaVersion: 999,
+      label: { widthMm: 100, heightMm: 60, dpmm: 8 },
+      pages: [{ objects: SAMPLE_OBJECTS }],
+    });
+    const result = parseDesignFile(futureJson);
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.error).toBe('invalid_schema');
   });
 
   it('returns parse_error for invalid JSON', () => {
@@ -195,18 +215,6 @@ describe('parseDesignFile', () => {
     expect(result.value.variables).toEqual([]);
   });
 
-  it('legacy { label, objects } shape loads with empty variables', () => {
-    const legacyJson = JSON.stringify({
-      label: { widthMm: 100, heightMm: 60, dpmm: 8 },
-      objects: SAMPLE_OBJECTS,
-    });
-    const result = parseDesignFile(legacyJson);
-    expect(result.ok).toBe(true);
-    if (!result.ok) return;
-    expect(result.value.variables).toEqual([]);
-    expect(result.value.csvMapping).toBeNull();
-  });
-
   it('roundtrips csvMapping when present', () => {
     const mapping = {
       bindings: { v1: 'SKU', v2: 'Quantity' },
diff --git a/src/lib/designFile.ts b/src/lib/designFile.ts
index 8e4c43a8..09009661 100644
--- a/src/lib/designFile.ts
+++ b/src/lib/designFile.ts
@@ -9,6 +9,13 @@ import {
 import type { LabelObject } from "../types/Group";
 import { ok, err, type Result } from "./result";
 
+/** Current design-file schema version. Bump when the persisted shape
+ *  changes in a way an older app cannot read. Add a vN schema +
+ *  migrator below and dispatch on `schemaVersion` in `parseDesignFile`.
+ *  The persist middleware in `labelStore` has its own independent
+ *  version for localStorage state — do not conflate. */
+export const CURRENT_DESIGN_SCHEMA_VERSION = 1;
+
 export type DesignFileError = "parse_error" | "invalid_schema";
 export interface DesignFilePage { objects: LabelObject[] }
 export interface DesignFile {
@@ -45,20 +52,14 @@ const labelObjectSchema: z.ZodType<unknown> = z.union([groupSchema, leafSchema])
 
 const pageSchema = z.object({ objects: z.array(labelObjectSchema) });
 
-const designFileSchema = z.object({
+const designFileV1Schema = z.object({
+  schemaVersion: z.literal(1),
   label: labelConfigSchema,
   pages: z.array(pageSchema),
-  // Optional so designs saved before the variables feature still load.
   variables: z.array(variableSchema).optional(),
-  // Optional: designs without a CSV import omit the field entirely.
   csvMapping: csvMappingSchema.optional(),
 });
 
-const legacyDesignFileSchema = z.object({
-  label: labelConfigSchema,
-  objects: z.array(labelObjectSchema),
-});
-
 export function parseDesignFile(text: string): Result<DesignFile, DesignFileError> {
   let json: unknown;
   try {
@@ -67,28 +68,13 @@ export function parseDesignFile(text: string): Result<DesignFile, DesignFileErro
     return err("parse_error");
   }
 
-  const current = designFileSchema.safeParse(json);
-  if (current.success) {
-    // LabelObject[] is a discriminated union with typed props; Zod cannot
-    // verify them without per-type schemas, so the cast here is intentional.
-    // The registry handles unknown prop shapes gracefully at runtime.
-    return ok({
-      label: current.data.label,
-      pages: current.data.pages as unknown as DesignFilePage[],
-      variables: current.data.variables ?? [],
-      csvMapping: current.data.csvMapping ?? null,
-    });
-  }
-
-  // Legacy: { label, objects } from before multi-page support.
-  // Wrapped into a single page so older designs keep loading.
-  const legacy = legacyDesignFileSchema.safeParse(json);
-  if (legacy.success) {
+  const v1 = designFileV1Schema.safeParse(json);
+  if (v1.success) {
     return ok({
-      label: legacy.data.label,
-      pages: [{ objects: legacy.data.objects as unknown as LabelObject[] }],
-      variables: [],
-      csvMapping: null,
+      label: v1.data.label,
+      pages: v1.data.pages as unknown as DesignFilePage[],
+      variables: v1.data.variables ?? [],
+      csvMapping: v1.data.csvMapping ?? null,
     });
   }
 
@@ -96,6 +82,7 @@ export function parseDesignFile(text: string): Result<DesignFile, DesignFileErro
 }
 
 interface SerializedDesign {
+  schemaVersion: number;
   label: LabelConfig;
   pages: DesignFilePage[];
   variables?: Variable[];
@@ -108,9 +95,11 @@ export function serializeDesign(
   variables: Variable[] = [],
   csvMapping: CsvMapping | null = null,
 ): string {
-  // Omit optional fields when empty so older versions of the app that
-  // lack them can keep round-tripping designs untouched.
-  const payload: SerializedDesign = { label, pages };
+  const payload: SerializedDesign = {
+    schemaVersion: CURRENT_DESIGN_SCHEMA_VERSION,
+    label,
+    pages,
+  };
   if (variables.length > 0) payload.variables = variables;
   if (csvMapping) payload.csvMapping = csvMapping;
   return JSON.stringify(payload, null, 2);
diff --git a/src/lib/importReport.ts b/src/lib/importReport.ts
index 3cd343b5..073c2f79 100644
--- a/src/lib/importReport.ts
+++ b/src/lib/importReport.ts
@@ -12,7 +12,7 @@ export interface ImportResult {
 }
 
 /** Returns the loss description for a partial command code, e.g. "^A@" → font face note. */
-export function partialLoss(cmd: string): string {
+function partialLoss(cmd: string): string {
   const key = cmd.slice(1);
   const entry = ZPL_COMMAND_MAP.get(key) ?? (key[0] === 'A' ? ZPL_COMMAND_MAP.get('A@') : undefined);
   return entry?.loss ?? 'imported with limitations';
diff --git a/src/lib/labelary.ts b/src/lib/labelary.ts
index 92df29ec..8bc47042 100644
--- a/src/lib/labelary.ts
+++ b/src/lib/labelary.ts
@@ -35,7 +35,7 @@ export function isDefaultLabelaryHost(): boolean {
   return host() === DEFAULT_HOST;
 }
 
-export class LabelaryError extends Error {
+class LabelaryError extends Error {
   readonly kind: 'api' | 'timeout' | 'network';
   constructor(kind: 'api' | 'timeout' | 'network', message: string) {
     super(message);
diff --git a/src/lib/lineConstrain.ts b/src/lib/lineConstrain.ts
index c8c0c542..9b7f6dae 100644
--- a/src/lib/lineConstrain.ts
+++ b/src/lib/lineConstrain.ts
@@ -16,7 +16,7 @@ export type ConstrainMode = "free" | "shift" | "autoSnap";
 
 /** Tolerance in degrees for `autoSnap` mode — below this distance from
  *  a 45° step the angle is snapped, above it the raw angle is kept. */
-export const AUTO_SNAP_TOLERANCE_DEG = 5;
+const AUTO_SNAP_TOLERANCE_DEG = 5;
 
 export interface LineGeometry {
   length: number;
diff --git a/src/lib/pruneUndefined.ts b/src/lib/pruneUndefined.ts
index 37a39f9d..e171bb47 100644
--- a/src/lib/pruneUndefined.ts
+++ b/src/lib/pruneUndefined.ts
@@ -1,14 +1,6 @@
-/** Strip own-enumerable keys whose value is `undefined`, returning a
- *  fresh object. Used at the boundary between sources that emit
- *  present-with-undefined keys (e.g. `Object.assign` of a parser
- *  result that explicitly cleared a field) and consumers that treat
- *  "field absent" as semantically different from "field present and
- *  undefined" (PrinterProfile in particular: absent = printer default,
- *  present-with-undefined would round-trip back into the persisted
- *  JSON and round through Zod as an unintended optional-write).
- *
- *  Pure, allocation-only (no mutation of input). Generic over the
- *  partial shape so callers don't have to re-assert the type. */
+/** Strip keys whose value is `undefined`, returning a fresh object.
+ *  PrinterProfile's "absent = printer default" semantics get corrupted
+ *  by present-with-undefined keys after a JSON round-trip. */
 export function pruneUndefined<T extends object>(input: Partial<T>): Partial<T> {
   const next: Record<string, unknown> = {};
   for (const [k, v] of Object.entries(input)) {
diff --git a/src/lib/storagePath.ts b/src/lib/storagePath.ts
index 4464765a..d4053218 100644
--- a/src/lib/storagePath.ts
+++ b/src/lib/storagePath.ts
@@ -38,7 +38,7 @@ export interface StoragePath {
 
 /** Extension paired with `^GF`-shaped graphic uploads. Zebra firmware
  *  persists `~DY{path},*,G,...` as `{path}.GRF` on the device. */
-export const GRAPHIC_EXT = "GRF";
+const GRAPHIC_EXT = "GRF";
 
 /**
  * Parse a `device:name` or `device:name.ext` storage path into structured
diff --git a/src/lib/useColorScheme.ts b/src/lib/useColorScheme.ts
index 2d47f18a..6a4619f1 100644
--- a/src/lib/useColorScheme.ts
+++ b/src/lib/useColorScheme.ts
@@ -37,7 +37,7 @@ export const DARK_COLORS: CanvasColors = {
   accent:         '#f59e0b',
 };
 
-export const LIGHT_COLORS: CanvasColors = {
+const LIGHT_COLORS: CanvasColors = {
   canvasBg:       '#e4e4e7',
   canvasDot:      '#dcdce0',
   gridLine:       '#a1a1aa',
diff --git a/src/lib/useCopyToClipboard.ts b/src/lib/useCopyToClipboard.ts
index a1ea9d6c..cd3540b1 100644
--- a/src/lib/useCopyToClipboard.ts
+++ b/src/lib/useCopyToClipboard.ts
@@ -2,16 +2,9 @@ import { useEffect, useRef, useState } from 'react';
 
 /** Copy-to-clipboard with a transient "copied" flag for button UI.
  *  `getPayload` is called at copy-time (not at hook-call-time) so
- *  live-generated content reflects the current state — needed for
- *  the Setup-Script live-clock mode where the emitted ^ST stamp
- *  must be "now at click", not "now at last render".
- *
- *  Holds the reset timer in a ref so two cases are handled cleanly:
- *  (1) a second copy click while the previous reset is still pending
- *  re-arms instead of letting the older timer flip the flag back
- *  mid-feedback; (2) the host component unmounting (e.g. modal
- *  close immediately after copy) cancels the timer in the effect
- *  cleanup so React doesn't run a stale setState on a dead tree. */
+ *  live-generated content reflects the current state — needed for the
+ *  Setup-Script live-clock mode where the emitted ^ST stamp must be
+ *  "now at click", not "now at last render". */
 export function useCopyToClipboard(getPayload: () => string, resetMs = 1500) {
   const [copied, setCopied] = useState(false);
   const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
@@ -19,9 +12,8 @@ export function useCopyToClipboard(getPayload: () => string, resetMs = 1500) {
   const copy = () => {
     const payload = getPayload();
     if (!payload) return;
-    // `navigator.clipboard` is undefined in non-secure contexts
-    // (plain HTTP, file://) and in some embedded WebViews. Bail
-    // out instead of throwing — the copy button is non-essential.
+    // navigator.clipboard is undefined in non-secure contexts
+    // (plain HTTP, file://) and in some embedded WebViews.
     if (!navigator.clipboard) return;
     navigator.clipboard.writeText(payload).then(() => {
       setCopied(true);
diff --git a/src/lib/zplSetupScript.ts b/src/lib/zplSetupScript.ts
index 76a4e200..a3886534 100644
--- a/src/lib/zplSetupScript.ts
+++ b/src/lib/zplSetupScript.ts
@@ -1,55 +1,15 @@
 import type { PrinterProfile } from '../types/PrinterProfile';
 import { formatRealtimeClockForZpl, toLocalIsoString } from './realtimeClock';
 
-/**
- * Generates the one-shot Setup-Script output for a printer profile.
- *
- * Separate from `generateZPL` because the commands this emits are
- * EEPROM-persistent printer state (~TA, ^JZ, ^JT, and the clock /
- * encoding / identity commands). Re-emitting them on every label
- * would wear the printer's flash; the Setup-Script is meant to be
- * sent once when the printer is provisioned, not on every print job.
- *
- * Per-label commands that *also* touch EEPROM (^MD, ^MT, ^MM, ^ML)
- * stay in `generateZPL` because they conceptually belong to "this
- * label's media setup". Instant-only commands (~SD) stay per-label
- * too — they don't write flash. The split is "should this value
- * change per print job" rather than "is the write persistent".
- *
- * Shape follows the Zebra-idiomatic split:
- *   - tilde-prefix commands (~TA) stand alone above the block
- *   - caret-prefix commands (^JZ, ^JT, …) live inside a wrapper
- *     `^XA…^XZ` block, since caret commands are only valid within
- *     a label definition
- *
- * Returns an empty string when no Setup-Script-relevant field is
- * set, so the UI can hide the output pane without a separate
- * "is anything to emit" predicate.
- *
- * Note on default-value emits (`~TA0`, `^JT0`, `^JZY`, `^KD0`):
- * these write the printer's documented default back to EEPROM and
- * could be skipped as "no-ops" to spare flash. The generator keeps
- * them anyway because (a) "user explicitly chose 0" is a legitimate
- * reset signal, and (b) the printer firmware may have been left in
- * a non-default state by an earlier script — emitting the default
- * is the only way to be sure the field actually lands there.
- * Skip-when-default would be silent wrong-state.
- */
+/** Generates the one-shot Setup-Script ZPL for a printer profile —
+ *  EEPROM-persistent state (~TA, ^JZ, ^JT, clock / encoding / identity)
+ *  meant to be sent once at provisioning, not on every print job.
+ *  Returns '' when no field is set so callers can hide the pane without
+ *  a separate predicate. Default-value emits (`~TA000`, `^JZY`, …) are
+ *  kept rather than skipped: emitting the documented default is the
+ *  only way to be sure the field actually lands there after an
+ *  earlier script left the printer in a non-default state. */
 
-/** Registry entry kinds.
- *
- *  `emit` entries own a real ZPL command. They take the full profile
- *  so the emitter handles its own undefined-check and any value-shape
- *  transformation (e.g. the ^ST datetime-to-positional split).
- *  Returning `null` skips the field, returning a string pushes it
- *  onto the relevant channel queue.
- *
- *  `foldedInto` entries are pure metadata — fields that don't emit a
- *  standalone command because they ride along on another field's
- *  emit (e.g. `printerDescription` is a positional param of `^KN`,
- *  `clockTolerance` is folded into `^SL` based on `clockMode`). The
- *  `target` is documentary and also lets the generator iteration
- *  cheaply skip these fields without calling a no-op closure. */
 type SetupScriptEntry =
   | {
       kind: 'emit';
@@ -61,21 +21,13 @@ type SetupScriptEntry =
       target: keyof PrinterProfile;
     };
 
-/** Single registry of all Setup-Script commands. Keys must be
- *  `keyof PrinterProfile` (enforced via `satisfies Partial<Record<…>>`)
- *  so a typo or a field renamed in the schema surfaces here. Adding
- *  a new Setup-Script command means one entry in this map — the
- *  if-chain in `generateSetupScript`, the no-leak test, and the
- *  exported `SETUP_SCRIPT_FIELDS` list all derive from it. */
 const SETUP_SCRIPT_EMITTERS = {
   tearOffAdjust: {
     kind: 'emit',
     channel: 'tilde',
-    // ~TA requires the magnitude to be exactly 3 digits per the Zebra
-    // spec: "if the number of characters is less than 3, the command
-    // is ignored." So `~TA5` is silently dropped by firmware; the
-    // correct form is `~TA005`. The sign (if any) sits OUTSIDE the
-    // 3-digit width: `~TA-050`, `~TA005`.
+    // Spec: "if the number of characters is less than 3, the command
+    // is ignored." `~TA5` is dropped by firmware; correct form is
+    // `~TA005`. Sign sits outside the 3-digit width.
     emit: (p) => {
       if (p.tearOffAdjust === undefined) return null;
       const v = p.tearOffAdjust;
@@ -97,14 +49,9 @@ const SETUP_SCRIPT_EMITTERS = {
   setRealtimeClock: {
     kind: 'emit',
     channel: 'block',
-    // Two paths share the ^ST slot: when `useCurrentTimeForClock`
-    // is on, the emit captures *now* at call-time (live mode —
-    // every export gets a fresh stamp, the Setup-Script is no
-    // longer reproducible but it actually "sets the clock"). When
-    // off, the stored ISO string is emitted verbatim (static mode
-    // — reproducible, but the user has to remember to set the
-    // value before sending). The live branch wins when both are
-    // set, so toggling the checkbox in the UI is unambiguous.
+    // Live mode (useCurrentTimeForClock) captures now() at emit-time
+    // and wins over the stored static value. Toggling the checkbox in
+    // the UI is therefore unambiguous regardless of stored ISO state.
     emit: (p) => {
       if (p.useCurrentTimeForClock) {
         const params = formatRealtimeClockForZpl(toLocalIsoString());
@@ -115,10 +62,7 @@ const SETUP_SCRIPT_EMITTERS = {
       return params !== null ? `^ST${params}` : null;
     },
   },
-  useCurrentTimeForClock: {
-    kind: 'foldedInto',
-    target: 'setRealtimeClock',
-  },
+  useCurrentTimeForClock: { kind: 'foldedInto', target: 'setRealtimeClock' },
   clockFormat: {
     kind: 'emit',
     channel: 'block',
@@ -142,80 +86,48 @@ const SETUP_SCRIPT_EMITTERS = {
   printerName: {
     kind: 'emit',
     channel: 'block',
-    // ^KN takes two positional params; description rides along
-    // only when set. The `printerDescription` registry entry below
-    // intentionally returns null on its own (it has no standalone
-    // ZPL command) — the description is folded in here so the
-    // ^KN emit stays a single line. Both values are `.trim()`ed
-    // on emit because the parser trims on import, and asymmetric
-    // whitespace would silently break the round-trip invariant.
     emit: (p) => {
       if (p.printerName === undefined) return null;
+      // Trim both halves: parser trims on import; asymmetric whitespace
+      // would break the round-trip invariant. Whitespace-only name
+      // drops the emit so the parser's "no name = no ^KN" rule holds.
       const name = p.printerName.trim();
-      // Schema's min(1) accepts whitespace-only strings; trimming
-      // to empty here drops the emit so the parser's "no name = no
-      // ^KN" round-trip rule holds. Without this guard, `^KN` (or
-      // `^KN,desc`) would emit and the parser would silently drop
-      // both fields on re-import.
       if (!name) return null;
       const desc = p.printerDescription?.trim();
       return desc ? `^KN${name},${desc}` : `^KN${name}`;
     },
   },
-  printerDescription: {
-    kind: 'foldedInto',
-    target: 'printerName',
-  },
+  printerDescription: { kind: 'foldedInto', target: 'printerName' },
   clockMode: {
     kind: 'emit',
     channel: 'block',
-    // ^SL has three value shapes in one positional slot: 'S', 'T',
-    // or numeric 1..999 (TOL with tolerance). Schema's cross-field
-    // refine guarantees that `mode === 'TOL'` always has a defined
-    // `clockTolerance`, so no fallback is needed here — a missing
-    // tolerance under TOL is unreachable through `parse`. Language
-    // rides along when set; if omitted, the printer keeps its
-    // current second-positional value.
+    // ^SL `a` slot is tri-shape: 'S', 'T', or numeric tolerance (TOL
+    // mode). Schema's cross-field refine guarantees TOL always has a
+    // defined clockTolerance, so no fallback needed.
     emit: (p) => {
       if (p.clockMode === undefined) return null;
-      const a = p.clockMode === 'TOL'
-        ? String(p.clockTolerance)
-        : p.clockMode;
+      const a = p.clockMode === 'TOL' ? String(p.clockTolerance) : p.clockMode;
       const b = p.clockLanguage;
       return b !== undefined ? `^SL${a},${b}` : `^SL${a}`;
     },
   },
-  clockTolerance: {
-    kind: 'foldedInto',
-    target: 'clockMode',
-  },
-  clockLanguage: {
-    // Language rides on ^SL's second positional. If language is set
-    // but mode is not, the printer would need a bare `^SL,<lang>`
-    // which the spec leaves implementation-defined — we drop instead
-    // of guessing. The fold target is `clockMode` because the emit
-    // path lives there even though `clockLanguage` is independently
-    // settable from the UI.
-    kind: 'foldedInto',
-    target: 'clockMode',
-  },
+  clockTolerance: { kind: 'foldedInto', target: 'clockMode' },
+  // Drop bare `^SL,<lang>` (mode unset): spec leaves the shape
+  // implementation-defined.
+  clockLanguage: { kind: 'foldedInto', target: 'clockMode' },
 } as const satisfies Partial<Record<keyof PrinterProfile, SetupScriptEntry>>;
 
 /** Public list of the PrinterProfile fields that flow through the
  *  Setup-Script generator. Derived from the registry so the two
- *  cannot drift. Consumers (test no-leak assertion, modal rail
- *  grouping) read this instead of hard-coding the list. */
+ *  cannot drift. */
 export const SETUP_SCRIPT_FIELDS = Object.keys(
   SETUP_SCRIPT_EMITTERS,
 ) as readonly SetupScriptField[];
 
 export type SetupScriptField = keyof typeof SETUP_SCRIPT_EMITTERS;
 
-/** Re-export the registry for tests that need to assert structural
- *  invariants (e.g. every foldedInto.target points at a kind:'emit'
- *  entry, never another foldedInto — that would create a fold chain
- *  with no actual emit producer). Kept module-internal-ish: not
- *  intended for runtime consumers, just the test boundary. */
+/** Test-only re-export so an invariant check can walk foldedInto
+ *  targets without re-implementing the registry shape. */
 export const __SETUP_SCRIPT_EMITTERS_FOR_TESTS = SETUP_SCRIPT_EMITTERS;
 
 export function generateSetupScript(profile: PrinterProfile): string {
@@ -224,8 +136,6 @@ export function generateSetupScript(profile: PrinterProfile): string {
 
   for (const field of SETUP_SCRIPT_FIELDS) {
     const e = SETUP_SCRIPT_EMITTERS[field];
-    // foldedInto entries don't emit on their own; their value rides
-    // along on the `target` field's emit. Skip without calling.
     if (e.kind !== 'emit') continue;
     const line = e.emit(profile);
     if (line === null) continue;
diff --git a/src/locales/ar.ts b/src/locales/ar.ts
index f014f997..d688b682 100644
--- a/src/locales/ar.ts
+++ b/src/locales/ar.ts
@@ -278,8 +278,6 @@ const ar = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script has content',
     copy: 'نسخ',
     copied: '✓ تم النسخ',
     noObjects: 'لا توجد عناصر على الملصق بعد',
diff --git a/src/locales/bg.ts b/src/locales/bg.ts
index a02f1dd6..04d349bb 100644
--- a/src/locales/bg.ts
+++ b/src/locales/bg.ts
@@ -278,8 +278,6 @@ const bg = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script съдържа данни',
     copy: 'Копирай',
     copied: '✓ Копирано',
     noObjects: 'Все още няма обекти върху етикета',
diff --git a/src/locales/cs.ts b/src/locales/cs.ts
index d33e819e..5c7e447f 100644
--- a/src/locales/cs.ts
+++ b/src/locales/cs.ts
@@ -278,8 +278,6 @@ const cs = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script obsahuje data',
     copy: 'Kopírovat',
     copied: '✓ Zkopírováno',
     noObjects: 'Na štítku zatím nejsou žádné objekty',
diff --git a/src/locales/da.ts b/src/locales/da.ts
index df989ebf..b9a3707e 100644
--- a/src/locales/da.ts
+++ b/src/locales/da.ts
@@ -278,8 +278,6 @@ const da = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script har indhold',
     copy: 'Kopiér',
     copied: '✓ Kopieret',
     noObjects: 'Ingen objekter på etiketten endnu',
diff --git a/src/locales/de.ts b/src/locales/de.ts
index 89e6b637..ae954ac7 100644
--- a/src/locales/de.ts
+++ b/src/locales/de.ts
@@ -299,8 +299,6 @@ const de = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup-Script',
-    hiddenSecondaryHint: 'Setup-Script enthält Inhalt',
     copy: 'Kopieren',
     copied: '✓ Kopiert',
     noObjects: 'Noch keine Objekte auf dem Etikett',
diff --git a/src/locales/el.ts b/src/locales/el.ts
index baaf8d45..fddad575 100644
--- a/src/locales/el.ts
+++ b/src/locales/el.ts
@@ -278,8 +278,6 @@ const el = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Το Setup Script περιέχει δεδομένα',
     copy: 'Αντιγραφή',
     copied: '✓ Αντιγράφηκε',
     noObjects: 'Δεν υπάρχουν ακόμη αντικείμενα στην ετικέτα',
diff --git a/src/locales/en.ts b/src/locales/en.ts
index fda30b27..bd01bc01 100644
--- a/src/locales/en.ts
+++ b/src/locales/en.ts
@@ -299,8 +299,6 @@ const en = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script has content',
     copy: 'Copy',
     copied: '✓ Copied',
     noObjects: 'No objects on the label yet',
diff --git a/src/locales/es.ts b/src/locales/es.ts
index 6a7fb913..a701fa8e 100644
--- a/src/locales/es.ts
+++ b/src/locales/es.ts
@@ -278,8 +278,6 @@ const es = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script tiene contenido',
     copy: 'Copiar',
     copied: '✓ Copiado',
     noObjects: 'Todavía no hay objetos en la etiqueta',
diff --git a/src/locales/et.ts b/src/locales/et.ts
index 17097e82..b410b1bf 100644
--- a/src/locales/et.ts
+++ b/src/locales/et.ts
@@ -278,8 +278,6 @@ const et = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script sisaldab andmeid',
     copy: 'Kopeeri',
     copied: '✓ Kopeeritud',
     noObjects: 'Sildil pole veel objekte',
diff --git a/src/locales/fa.ts b/src/locales/fa.ts
index 41bbcb8f..fd8f3058 100644
--- a/src/locales/fa.ts
+++ b/src/locales/fa.ts
@@ -278,8 +278,6 @@ const fa = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script has content',
     copy: 'کپی',
     copied: '✓ کپی شد',
     noObjects: 'هنوز هیچ شیئی روی برچسب نیست',
diff --git a/src/locales/fi.ts b/src/locales/fi.ts
index 7bbf7beb..91d6685c 100644
--- a/src/locales/fi.ts
+++ b/src/locales/fi.ts
@@ -278,8 +278,6 @@ const fi = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Skriptissä on sisältöä',
     copy: 'Kopioi',
     copied: '✓ Kopioitu',
     noObjects: 'Etiketillä ei ole vielä objekteja',
diff --git a/src/locales/fr.ts b/src/locales/fr.ts
index f83d5f9c..5fc1e526 100644
--- a/src/locales/fr.ts
+++ b/src/locales/fr.ts
@@ -278,8 +278,6 @@ const fr = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Le Setup Script contient des données',
     copy: 'Copier',
     copied: '✓ Copié',
     noObjects: "Pas encore d'objets sur l'étiquette",
diff --git a/src/locales/he.ts b/src/locales/he.ts
index 5c3b3648..3f015c26 100644
--- a/src/locales/he.ts
+++ b/src/locales/he.ts
@@ -278,8 +278,6 @@ const he = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script מכיל תוכן',
     copy: 'העתק',
     copied: '✓ הועתק',
     noObjects: 'אין אובייקטים על התווית עדיין',
diff --git a/src/locales/hr.ts b/src/locales/hr.ts
index 1e18d7a3..dee58e43 100644
--- a/src/locales/hr.ts
+++ b/src/locales/hr.ts
@@ -278,8 +278,6 @@ const hr = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script sadrži sadržaj',
     copy: 'Kopiraj',
     copied: '✓ Kopirano',
     noObjects: 'Nema objekata na naljepnici',
diff --git a/src/locales/hu.ts b/src/locales/hu.ts
index 1537d509..7ddfee41 100644
--- a/src/locales/hu.ts
+++ b/src/locales/hu.ts
@@ -278,8 +278,6 @@ const hu = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'A Setup Script tartalmaz adatokat',
     copy: 'Másolás',
     copied: '✓ Másolva',
     noObjects: 'Még nincsenek objektumok a címkén',
diff --git a/src/locales/it.ts b/src/locales/it.ts
index bbefd250..07612146 100644
--- a/src/locales/it.ts
+++ b/src/locales/it.ts
@@ -278,8 +278,6 @@ const it = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script contiene dati',
     copy: 'Copia',
     copied: '✓ Copiato',
     noObjects: "Nessun oggetto sull'etichetta",
diff --git a/src/locales/ja.ts b/src/locales/ja.ts
index 745a779e..3da5fe5a 100644
--- a/src/locales/ja.ts
+++ b/src/locales/ja.ts
@@ -278,8 +278,6 @@ const ja = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Scriptに内容があります',
     copy: 'コピー',
     copied: '✓ コピーしました',
     noObjects: 'ラベルにオブジェクトがありません',
diff --git a/src/locales/ko.ts b/src/locales/ko.ts
index 2ac6bd3a..7fe1571b 100644
--- a/src/locales/ko.ts
+++ b/src/locales/ko.ts
@@ -278,8 +278,6 @@ const ko = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script에 내용이 있습니다',
     copy: '복사',
     copied: '✓ 복사됨',
     noObjects: '레이블에 아직 개체가 없습니다',
diff --git a/src/locales/lt.ts b/src/locales/lt.ts
index 00720bc7..780be562 100644
--- a/src/locales/lt.ts
+++ b/src/locales/lt.ts
@@ -278,8 +278,6 @@ const lt = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script turi turinio',
     copy: 'Kopijuoti',
     copied: '✓ Nukopijuota',
     noObjects: 'Etiketėje dar nėra objektų',
diff --git a/src/locales/lv.ts b/src/locales/lv.ts
index 1c7600d6..1199cef2 100644
--- a/src/locales/lv.ts
+++ b/src/locales/lv.ts
@@ -278,8 +278,6 @@ const lv = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script satur saturu',
     copy: 'Kopēt',
     copied: '✓ Nokopēts',
     noObjects: 'Etiķetē vēl nav objektu',
diff --git a/src/locales/nl.ts b/src/locales/nl.ts
index 13132eef..f4be7fdb 100644
--- a/src/locales/nl.ts
+++ b/src/locales/nl.ts
@@ -278,8 +278,6 @@ const nl = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script bevat inhoud',
     copy: 'Kopiëren',
     copied: '✓ Gekopieerd',
     noObjects: 'Nog geen objecten op het etiket',
diff --git a/src/locales/no.ts b/src/locales/no.ts
index 8dd93fcd..5f47047e 100644
--- a/src/locales/no.ts
+++ b/src/locales/no.ts
@@ -278,8 +278,6 @@ const no = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script har innhold',
     copy: 'Kopier',
     copied: '✓ Kopiert',
     noObjects: 'Ingen objekter på etiketten ennå',
diff --git a/src/locales/pl.ts b/src/locales/pl.ts
index 5aedce90..fdf458ca 100644
--- a/src/locales/pl.ts
+++ b/src/locales/pl.ts
@@ -278,8 +278,6 @@ const pl = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script zawiera treść',
     copy: 'Kopiuj',
     copied: '✓ Skopiowano',
     noObjects: 'Brak obiektów na etykiecie',
diff --git a/src/locales/pt.ts b/src/locales/pt.ts
index 16c715cf..2ad32175 100644
--- a/src/locales/pt.ts
+++ b/src/locales/pt.ts
@@ -278,8 +278,6 @@ const pt = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script tem conteúdo',
     copy: 'Copiar',
     copied: '✓ Copiado',
     noObjects: 'Ainda não há objetos na etiqueta',
diff --git a/src/locales/ro.ts b/src/locales/ro.ts
index 93357d9d..fa6f75a8 100644
--- a/src/locales/ro.ts
+++ b/src/locales/ro.ts
@@ -278,8 +278,6 @@ const ro = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script conține conținut',
     copy: 'Copiați',
     copied: '✓ Copiat',
     noObjects: 'Nu există încă obiecte pe etichetă',
diff --git a/src/locales/sk.ts b/src/locales/sk.ts
index 9e1b73c8..f55144b5 100644
--- a/src/locales/sk.ts
+++ b/src/locales/sk.ts
@@ -278,8 +278,6 @@ const sk = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script obsahuje dáta',
     copy: 'Kopírovať',
     copied: '✓ Skopírované',
     noObjects: 'Na štítku zatiaľ nie sú žiadne objekty',
diff --git a/src/locales/sl.ts b/src/locales/sl.ts
index eb5af74a..7d1f5596 100644
--- a/src/locales/sl.ts
+++ b/src/locales/sl.ts
@@ -278,8 +278,6 @@ const sl = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script vsebuje vsebino',
     copy: 'Kopiraj',
     copied: '✓ Kopirano',
     noObjects: 'Na nalepki še ni predmetov',
diff --git a/src/locales/sr.ts b/src/locales/sr.ts
index 6568e167..8f002e38 100644
--- a/src/locales/sr.ts
+++ b/src/locales/sr.ts
@@ -278,8 +278,6 @@ const sr = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script sadrži sadržaj',
     copy: 'Kopiraj',
     copied: '✓ Kopirano',
     noObjects: 'Nema objekata na nalepnici',
diff --git a/src/locales/sv.ts b/src/locales/sv.ts
index 990be96af..73ddd58a 100644
--- a/src/locales/sv.ts
+++ b/src/locales/sv.ts
@@ -278,8 +278,6 @@ const sv = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script har innehåll',
     copy: 'Kopiera',
     copied: '✓ Kopierat',
     noObjects: 'Inga objekt på etiketten ännu',
diff --git a/src/locales/tr.ts b/src/locales/tr.ts
index de07edd2..c088194e 100644
--- a/src/locales/tr.ts
+++ b/src/locales/tr.ts
@@ -278,8 +278,6 @@ const tr = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script içerik içeriyor',
     copy: 'Kopyala',
     copied: '✓ Kopyalandı',
     noObjects: 'Etikette henüz nesne yok',
diff --git a/src/locales/zh-hans.ts b/src/locales/zh-hans.ts
index 327d54f6..dfc33304 100644
--- a/src/locales/zh-hans.ts
+++ b/src/locales/zh-hans.ts
@@ -278,8 +278,6 @@ const zhHans = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script 有内容',
     copy: '复制',
     copied: '✓ 已复制',
     noObjects: '标签上暂无对象',
diff --git a/src/locales/zh-hant.ts b/src/locales/zh-hant.ts
index 9aec6532..7e08a4f4 100644
--- a/src/locales/zh-hant.ts
+++ b/src/locales/zh-hant.ts
@@ -278,8 +278,6 @@ const zhHant = {
 
   output: {
     zplHeading: 'ZPL',
-    setupScriptHeading: 'Setup Script',
-    hiddenSecondaryHint: 'Setup Script 有內容',
     copy: '複製',
     copied: '✓ 已複製',
     noObjects: '標籤上尚無物件',
diff --git a/src/registry/_template.ts b/src/registry/_template.ts
deleted file mode 100644
index b84e7bd7..00000000
--- a/src/registry/_template.ts
+++ /dev/null
@@ -1,25 +0,0 @@
-// Template for new object types.
-// 1. Copy and rename this file (e.g. ean13.ts)
-// 2. Define the Props interface
-// 3. Implement ObjectTypeDefinition
-// 4. Add an entry in registry/index.ts
-
-import type { ObjectTypeDefinition } from '../types/ObjectType';
-
-interface TemplateProps {
-  content: string;
-}
-
-export const _template: ObjectTypeDefinition<TemplateProps> = {
-  label: 'Template',
-  icon: '?',
-  group: 'shape',
-  defaultProps: {
-    content: '',
-  },
-  defaultSize: { width: 200, height: 50 },
-  toZPL: (): string => {
-    return '';
-  },
-  PropertiesPanel: () => null,
-};
diff --git a/src/registry/transformHelpers.ts b/src/registry/transformHelpers.ts
index baf29739..c90bd4bc 100644
--- a/src/registry/transformHelpers.ts
+++ b/src/registry/transformHelpers.ts
@@ -73,7 +73,7 @@ export function commitRotatedWidthHeightTransform<
 
 /** Generic rotation-aware commit: scales an arbitrary numeric prop
  *  pair by `esx` / `esy`, rounds + snaps, clamps to min 1. */
-export function commitRotatedSizeTransform<
+function commitRotatedSizeTransform<
   P extends { rotation: "N" | "R" | "I" | "B" },
   XK extends keyof P,
   YK extends keyof P,
diff --git a/src/test/textVisualRegression.test.ts b/src/test/textVisualRegression.test.ts
index bc5417bb..987c4542 100644
--- a/src/test/textVisualRegression.test.ts
+++ b/src/test/textVisualRegression.test.ts
@@ -7,17 +7,20 @@ import { PNG } from 'pngjs';
 import { textTestCases } from '../../tests/fixtures/textTestCases';
 
 /**
- * Text rendering visual regression.
- *
- * Both sides load the SAME font (our PrintLabZPL-Bold.ttf):
+ * Renderer-pair stability check — Skia (@napi-rs/canvas) vs Labelary,
+ * with the SAME TTF loaded on both sides (PrintLabZPL-Bold.ttf):
  *   - Labelary uploaded it via /v1/fonts before generating the fixtures
  *     (see tests/scripts/fetch_labelary_text_fixtures.ts).
  *   - The local render here registers the TTF with @napi-rs/canvas.
  *
- * That removes glyph-design variance from the diff entirely. The
- * residual pixels are anti-aliasing edges between Labelary's renderer
- * and @napi-rs/canvas's renderer, which is small enough to flag real
- * regressions without flapping on noise.
+ * **This suite does NOT verify Zebra firmware fidelity.** Glyph data is
+ * identical on both sides by construction, and Labelary is itself a
+ * firmware simulator — substituting the font further removes the one
+ * thing Labelary contributed (its bundled Zebra-equivalent font metrics).
+ * What this catches: drift in our canvas font sizing / anchor math /
+ * fontSize-to-fontHeight conversion vs Labelary's renderer. What it
+ * does NOT catch: actual diff between the canvas preview and a label
+ * printed by physical Zebra hardware.
  *
  * Production uses `ZPL_FONT_HEIGHT_TO_CSS_RATIO = 1.0`, i.e. canvas
  * fontSize equals ZPL fontHeight directly. The test mirrors that so
@@ -47,7 +50,7 @@ if (!fs.existsSync(DIFF_DIR)) {
   fs.mkdirSync(DIFF_DIR, { recursive: true });
 }
 
-describe('Text Visual Regression — PrintLab ZPL on both sides', () => {
+describe('Text renderer-pair stability (Skia vs Labelary, shared TTF)', () => {
   beforeAll(() => {
     if (!fs.existsSync(FONT_PATH)) {
       throw new Error(`Font file missing at ${FONT_PATH}.`);
diff --git a/src/types/PrinterProfile.ts b/src/types/PrinterProfile.ts
index 4d812829..746da4f2 100644
--- a/src/types/PrinterProfile.ts
+++ b/src/types/PrinterProfile.ts
@@ -14,45 +14,28 @@ import {
   setupScriptSafeStringRegex,
 } from './ObjectType';
 
-/** Printer-installation profile: the EEPROM-persistent printer-state
- *  fields that previously lived on `labelConfig`. Separated out so:
- *   1. design files no longer leak Setup-Script values when shared
- *      (printer name, locale, etc. belong to the install, not the label),
- *   2. the data model matches the UX split between per-label and
- *      printer-wide configuration that Tab 1/2 vs Tab 3/4/5 of the
- *      Printer Settings modal already implies,
- *   3. a future multi-profile feature (one PrinterProfile per
- *      physical printer) has a clean schema to fan out over —
- *      currently the store keeps a single active profile. */
+/** Printer-installation profile: EEPROM-persistent printer-state
+ *  fields separated from `labelConfig` so design files don't leak
+ *  per-install values (printer name, locale, …) when shared.
+ *  Single profile today; the shape is ready to fan out into a
+ *  Record<id, PrinterProfile> when multi-profile lands. */
 export const printerProfileSchema = z.object({
-  /** ^JZ: reprint the previous label after a print error. */
   reprintAfterError: z.enum(['Y', 'N']).optional(),
-  /** ^JT: head-test interval (labels between printhead element tests). */
   headTestInterval: intInRange(HEAD_TEST_INTERVAL_RANGE).optional(),
-  /** ~TA: tear-off position adjustment in dot rows. */
   tearOffAdjust: intInRange(TEAR_OFF_ADJUST_RANGE).optional(),
-  /** ^ST: static set-clock value (HTML5 `datetime-local` string). */
   setRealtimeClock: z.string().regex(realtimeClockIsoRegex).optional(),
-  /** ^ST live-mode toggle: when true, generator captures the wall-clock
-   *  time at export-time and ignores `setRealtimeClock`. */
+  /** ^ST live-mode toggle: when true, generator captures wall-clock
+   *  at export-time and ignores `setRealtimeClock`. */
   useCurrentTimeForClock: z.boolean().optional(),
-  /** ^KD: clock-print format selector. */
   clockFormat: z.enum(CLOCK_FORMAT_VALUES).optional(),
-  /** ^SL `a`: clock mode (S / T / TOL). */
   clockMode: z.enum(CLOCK_MODE_VALUES).optional(),
-  /** ^SL `a` numeric form: tolerance in seconds when `clockMode === 'TOL'`. */
+  /** ^SL numeric tolerance; cross-field-bound to clockMode === 'TOL'. */
   clockTolerance: intInRange(CLOCK_TOLERANCE_RANGE).optional(),
-  /** ^SL `b`: clock-language code. */
   clockLanguage: z.enum(CLOCK_LANGUAGE_VALUES).optional(),
-  /** ^KL: printer-side display locale. */
   printerLocale: z.enum(PRINTER_LOCALE_VALUES).optional(),
-  /** ^SE: encoding-table file path on the printer. */
   encodingTable: z.string().min(1).regex(setupScriptSafeStringRegex).optional(),
-  /** ^SZ: ZPL mode selector. */
   zplMode: z.enum(ZPL_MODE_VALUES).optional(),
-  /** ^KN p1: friendly printer name (max 16 chars per spec). */
   printerName: z.string().min(1).max(PRINTER_NAME_MAX_LEN).regex(setupScriptSafeStringRegex).optional(),
-  /** ^KN p2: human-readable printer description. */
   printerDescription: z.string().min(1).regex(setupScriptSafeStringRegex).optional(),
 }).superRefine((p, ctx) => {
   if (p.clockTolerance !== undefined && p.clockMode !== 'TOL') {
@@ -73,11 +56,8 @@ export const printerProfileSchema = z.object({
 
 export type PrinterProfile = z.infer<typeof printerProfileSchema>;
 
-/** Fields owned by PrinterProfile. Derived from the schema so a new
- *  optional field added to `printerProfileSchema` is automatically
- *  picked up by the v4→v5 migration and the import loader — without
- *  the derivation a forgotten array entry would silently leak fresh
- *  fields into per-label state on rehydrate. */
+/** Derived from the schema so a new optional field is automatically
+ *  picked up by the v4→v5 migration and import loader. */
 export const PRINTER_PROFILE_FIELDS = Object.keys(
   printerProfileSchema.shape,
 ) as readonly (keyof PrinterProfile)[];
diff --git a/tests/fixtures/textTestCases.ts b/tests/fixtures/textTestCases.ts
index 33695598..cf601b1d 100644
--- a/tests/fixtures/textTestCases.ts
+++ b/tests/fixtures/textTestCases.ts
@@ -1,7 +1,8 @@
-/** Text-only visual regression cases. Compared against Labelary with our
- *  uploaded custom font (R:PRINTLAB.TTF) so both sides use the same
- *  glyph data — the residual diff is just anti-aliasing edge noise
- *  between Labelary's renderer and Skia/@napi-rs/canvas. */
+/** Text renderer-pair stability cases (NOT firmware fidelity — both
+ *  sides load the same TTF, so this measures Skia-vs-Labelary
+ *  rendering drift, not diff against printed Zebra output). See the
+ *  test header in src/test/textVisualRegression.test.ts for the full
+ *  framing. */
 export interface TextTestCase {
   /** Unique id; doubles as the PNG filename stem under tests/fixtures/
    *  labelary_text_images/. */
@@ -11,8 +12,9 @@ export interface TextTestCase {
   /** Character data passed to `^FD`. Keep to printable ASCII; the
    *  fixture renderer doesn't apply ^CI. */
   text: string;
-  /** ZPL rotation. Mostly N for the first batch; rotated cases will
-   *  come once we trust the unrotated baseline. */
+  /** ZPL rotation. Today all N; rotated cases (R / I / B) are a
+   *  follow-up — they exercise FO anchor math more than glyph
+   *  rendering, which is where the next regression class would land. */
   rotation: 'N' | 'R' | 'I' | 'B';
   /** ^FO origin within the 4x4 inch (812×812 px @ 8 dpmm) canvas the
    *  fetch script renders. Pick a value that keeps the rendered bbox

From e521d22133ebbb51ba14b0bc3f389dfedecd46b1 Mon Sep 17 00:00:00 2001
From: u8array <alexanderleinich1@gmail.com>
Date: Sat, 30 May 2026 22:25:27 +0200
Subject: [PATCH 2/4] refactor(types) + test: drop unjustified non-null
 assertions, add parser tripwires
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two themes:

1. Type-safety: 9 of the 30 lint warnings flagged unjustified \`!\`
   non-null assertions. Replaced with proper narrowing.
   - TemplateContentInput.tsx (8 sites) — extract a
     \`caretOffsetIn(editor, sel, which)\` helper that does the
     "Selection's anchor/focus Node | null after editor.contains()"
     narrowing once. Original code reached for \`!\` because
     TypeScript can't follow \`contains()\` as a narrowing.
   - contentEditableCaret.ts (2 sites) — \`el.parentNode!\` replaced
     with explicit \`if (!parent) return\` guards.
   - zplParser.ts:1625 — dropped one \`as unknown as Record<string,
     unknown>\` indirection. After \`lastObj.type === "text"\` narrowed,
     \`lastObj.props\` is already \`TextProps\`; the indirection was
     masking the discriminated union.

   Also demoted zplCommandSupport.ts internal exports
   (ZplCommandStatus, ZplCommandInfo, ZPL_COMMANDS) to non-exported
   and deleted the unused getCommandStatus() helper.

2. Parser pre-refactor tripwires for the upcoming pipeline split:
   - zplParser.test.ts: emits-one-finding-per-kind test now asserts
     source-order of finding.command. A split that collects
     unknowns / browser-limits in a separate post-pass would
     reorder these and break the assertion.
   - zplRoundtrip.test.ts: shipping-label round-trip now asserts no
     labelConfig key dropped between first parse and re-parse. A
     labelConfig fold running across blocks instead of per-block
     would drop keys here. Subset-check (not equality) because the
     generator legitimately gains widthMm/heightMm defaults.

1408 tests pass; 21 lint warnings remaining (down from 30).
---
 .../Properties/TemplateContentInput.tsx       | 63 ++++++++++---------
 src/lib/contentEditableCaret.ts               |  9 ++-
 src/lib/zplCommandSupport.ts                  | 18 +-----
 src/lib/zplParser.test.ts                     |  7 +++
 src/lib/zplParser.ts                          | 10 +--
 src/test/zplRoundtrip.test.ts                 | 15 +++++
 6 files changed, 71 insertions(+), 51 deletions(-)

diff --git a/src/components/Properties/TemplateContentInput.tsx b/src/components/Properties/TemplateContentInput.tsx
index 8430b649..60562362 100644
--- a/src/components/Properties/TemplateContentInput.tsx
+++ b/src/components/Properties/TemplateContentInput.tsx
@@ -22,6 +22,22 @@ import {
 } from "../../lib/contentEditableCaret";
 import type { Variable } from "../../types/Variable";
 
+/** Read a caret offset relative to `editor` from the live Selection's
+ *  anchor- or focus-node, returning `null` when the selection isn't
+ *  inside the editor. Encapsulates the "Node | null narrowing after
+ *  editor.contains()" dance that TypeScript can't follow. */
+function caretOffsetIn(
+  editor: HTMLElement,
+  sel: Selection | null,
+  which: 'anchor' | 'focus' = 'anchor',
+): number | null {
+  if (!sel || sel.rangeCount === 0) return null;
+  const node = which === 'anchor' ? sel.anchorNode : sel.focusNode;
+  const offset = which === 'anchor' ? sel.anchorOffset : sel.focusOffset;
+  if (!node || !editor.contains(node)) return null;
+  return getCaretOffset(editor, node, offset);
+}
+
 interface Props {
   value: string;
   onChange: (next: string) => void;
@@ -150,19 +166,18 @@ export function TemplateContentInput({
       if (editor.innerHTML === desired) return;
     }
     // Save caret offset within the editor before rebuild.
-    const sel = window.getSelection();
-    let caretOffset: number | null = null;
-    if (sel && sel.rangeCount > 0 && editor.contains(sel.anchorNode)) {
-      caretOffset = getCaretOffset(editor, sel.anchorNode!, sel.anchorOffset);
-    }
+    const caretOffset = caretOffsetIn(editor, window.getSelection());
     editor.innerHTML = segmentsToHTML(segments);
     if (caretOffset !== null && document.activeElement === editor) {
-      const pos = findCaretPosition(editor, caretOffset);
-      const range = document.createRange();
-      range.setStart(pos.node, pos.offset);
-      range.collapse(true);
-      sel!.removeAllRanges();
-      sel!.addRange(range);
+      const selAfter = window.getSelection();
+      if (selAfter) {
+        const pos = findCaretPosition(editor, caretOffset);
+        const range = document.createRange();
+        range.setStart(pos.node, pos.offset);
+        range.collapse(true);
+        selAfter.removeAllRanges();
+        selAfter.addRange(range);
+      }
     }
   }, [value, segments]);
 
@@ -234,22 +249,17 @@ export function TemplateContentInput({
 
   const getCaretOffsetInEditor = (): number => {
     const editor = editorRef.current;
-    const sel = window.getSelection();
-    if (!editor || !sel || sel.rangeCount === 0) return value.length;
-    if (!editor.contains(sel.anchorNode)) return value.length;
-    return getCaretOffset(editor, sel.anchorNode!, sel.anchorOffset);
+    if (!editor) return value.length;
+    return caretOffsetIn(editor, window.getSelection()) ?? value.length;
   };
 
   const insertMarker = (markerBody: string) => {
     const editor = editorRef.current;
     const marker = `«${markerBody}»`;
     const start = getCaretOffsetInEditor();
-    const end = (() => {
-      const sel = window.getSelection();
-      if (!editor || !sel || sel.rangeCount === 0) return start;
-      if (!editor.contains(sel.focusNode)) return start;
-      return getCaretOffset(editor, sel.focusNode!, sel.focusOffset);
-    })();
+    const end = editor
+      ? (caretOffsetIn(editor, window.getSelection(), 'focus') ?? start)
+      : start;
     const lo = Math.min(start, end);
     const hi = Math.max(start, end);
     const next = value.slice(0, lo) + marker + value.slice(hi);
@@ -281,12 +291,8 @@ export function TemplateContentInput({
      *  to caret at end-of-value for off-editor selections. */
     const selectionRange = (fallbackLen: number) => {
       const sel = window.getSelection();
-      const start = sel && editor.contains(sel.anchorNode)
-        ? getCaretOffset(editor, sel.anchorNode!, sel.anchorOffset)
-        : fallbackLen;
-      const end = sel && editor.contains(sel.focusNode)
-        ? getCaretOffset(editor, sel.focusNode!, sel.focusOffset)
-        : start;
+      const start = caretOffsetIn(editor, sel, 'anchor') ?? fallbackLen;
+      const end = caretOffsetIn(editor, sel, 'focus') ?? start;
       return { lo: Math.min(start, end), hi: Math.max(start, end) };
     };
     /** Browser-native undo/redo route through zundo (global Ctrl+Z),
@@ -303,7 +309,8 @@ export function TemplateContentInput({
       const { value } = stateRef.current;
       const sel = window.getSelection();
       if (!sel || sel.rangeCount === 0 || !sel.isCollapsed) return false;
-      const caret = getCaretOffset(editor, sel.anchorNode!, sel.anchorOffset);
+      const caret = caretOffsetIn(editor, sel);
+      if (caret === null) return false;
       const m = findAtomicMarker(value, caret, direction);
       if (!m) return false;
       commitInline(value.slice(0, m.start) + value.slice(m.end), m.start);
diff --git a/src/lib/contentEditableCaret.ts b/src/lib/contentEditableCaret.ts
index caa59f03..ecbcdd72 100644
--- a/src/lib/contentEditableCaret.ts
+++ b/src/lib/contentEditableCaret.ts
@@ -67,7 +67,8 @@ export function getCaretOffset(root: Node, node: Node, offset: number): number {
       }
       // Element node: count text from the first `offset` children, then stop.
       for (let i = 0; i < offset && i < n.childNodes.length; i += 1) {
-        visit(n.childNodes[i]!);
+        const child = n.childNodes[i];
+        if (child) visit(child);
       }
       found = true;
       return;
@@ -114,7 +115,8 @@ export function findCaretPosition(
     if (el.tagName === "BR") {
       if (remaining === 0) {
         // Caret right before the <br>: place it in the parent at the BR's index.
-        const parent = el.parentNode!;
+        const parent = el.parentNode;
+        if (!parent) return;
         const idx = Array.prototype.indexOf.call(parent.childNodes, el);
         result = { node: parent, offset: idx };
         return;
@@ -137,7 +139,8 @@ export function findCaretPosition(
           result = { node: next, offset: 0 };
           return;
         }
-        const parent = el.parentNode!;
+        const parent = el.parentNode;
+        if (!parent) return;
         const idx = Array.prototype.indexOf.call(parent.childNodes, el);
         result = { node: parent, offset: idx + 1 };
         return;
diff --git a/src/lib/zplCommandSupport.ts b/src/lib/zplCommandSupport.ts
index 33b5115d..0669cad7 100644
--- a/src/lib/zplCommandSupport.ts
+++ b/src/lib/zplCommandSupport.ts
@@ -7,14 +7,14 @@
  */
 
 /** Import fidelity when a ZPL command is parsed by this designer. */
-export type ZplCommandStatus =
+type ZplCommandStatus =
   | 'supported'      // Fully imported; no design information is lost
   | 'partial'        // Imported with known limitations (see ZplCommandInfo.loss)
   | 'structural'     // Carries no design content; correctly ignored (^XA, ^XZ, ^FX …)
   | 'browser-limit'  // Requires printer hardware / file storage; cannot be used in the browser
   | 'unsupported';   // Carries design information but not yet implemented
 
-export interface ZplCommandInfo {
+interface ZplCommandInfo {
   /** 2-character ZPL command code, uppercase, without the leading ^ or ~ */
   cmd: string;
   /** Brief description of what this ZPL command does */
@@ -25,7 +25,7 @@ export interface ZplCommandInfo {
   loss?: string;
 }
 
-export const ZPL_COMMANDS: readonly ZplCommandInfo[] = [
+const ZPL_COMMANDS: readonly ZplCommandInfo[] = [
   // ── Label layout ──────────────────────────────────────────────────────────
   { cmd: 'XA', status: 'structural', description: 'Start format (label start marker)' },
   { cmd: 'XZ', status: 'structural', description: 'End format / print label' },
@@ -184,15 +184,3 @@ export const ZPL_COMMANDS: readonly ZplCommandInfo[] = [
 export const ZPL_COMMAND_MAP: ReadonlyMap<string, ZplCommandInfo> =
   new Map(ZPL_COMMANDS.map((c) => [c.cmd, c]));
 
-/**
- * Returns the import status for a ZPL command token (2 uppercase chars).
- * Handles the special case of general ^A{x} bitmap-font commands.
- */
-export function getCommandStatus(cmd: string): ZplCommandStatus {
-  const upper = cmd.toUpperCase();
-  const entry = ZPL_COMMAND_MAP.get(upper);
-  if (entry) return entry.status;
-  // General ^A{font}{rotation} commands (A1–A9, AA–AZ except A0 which is explicit) — best-effort text
-  if (upper.length === 2 && upper[0] === 'A') return 'partial';
-  return 'unsupported';
-}
diff --git a/src/lib/zplParser.test.ts b/src/lib/zplParser.test.ts
index fcd1f362..dc6e2bf2 100644
--- a/src/lib/zplParser.test.ts
+++ b/src/lib/zplParser.test.ts
@@ -1313,6 +1313,13 @@ describe('parseZPL: importReport.findings', () => {
     expect(kinds).toContain('browserLimit');
     expect(kinds).toContain('unknown');
     expect(importReport.findings.every((f) => f.pageIndex === 0)).toBe(true);
+    // Tripwire: findings emit in source order. A pipeline split that
+    // collects unknowns / browser-limits in a separate pass would
+    // reorder these. Order: ^A@ (L1 partial) → ^IM (L1 browserLimit) →
+    // ^XX (L1 unknown).
+    expect(importReport.findings.map((f) => f.command)).toEqual([
+      '^A@', '^IMR:LOGO.GRF', '^XX99',
+    ]);
   });
 
   it('partial findings are deduplicated by command code', () => {
diff --git a/src/lib/zplParser.ts b/src/lib/zplParser.ts
index 6d42e054..2a03fc72 100644
--- a/src/lib/zplParser.ts
+++ b/src/lib/zplParser.ts
@@ -1622,17 +1622,17 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
       const snInc = int(p[1], 1);
       const lastObj = objects[objects.length - 1];
       if (lastObj && lastObj.type === "text") {
-        const tp = lastObj.props as unknown as Record<string, unknown>;
+        const tp = lastObj.props;
         const serialObj = makeObj(
           "serial",
           lastObj.x,
           lastObj.y,
           {
-            content: snStart || (tp["content"] as string) || "001",
+            content: snStart || tp.content || "001",
             increment: snInc,
-            fontHeight: (tp["fontHeight"] as number) ?? 30,
-            fontWidth: (tp["fontWidth"] as number) ?? 0,
-            rotation: (tp["rotation"] as SerialProps["rotation"]) ?? "N",
+            fontHeight: tp.fontHeight ?? 30,
+            fontWidth: tp.fontWidth ?? 0,
+            rotation: tp.rotation ?? "N",
             zplMode: "SN",
           } satisfies SerialProps,
           lastObj.positionType,
diff --git a/src/test/zplRoundtrip.test.ts b/src/test/zplRoundtrip.test.ts
index dff40522..8f1e53c2 100644
--- a/src/test/zplRoundtrip.test.ts
+++ b/src/test/zplRoundtrip.test.ts
@@ -46,6 +46,21 @@ describe('round-trip — shipping label', () => {
     expect(second.objects).toHaveLength(first.objects.length);
   });
 
+  it('tripwire: labelConfig keys from first parse survive the round-trip', () => {
+    // A pipeline split that runs the labelConfig / printerProfile fold
+    // in the wrong order — e.g. across-blocks post-aggregation instead
+    // of per-block — would drop keys here. (Second-parse may legitimately
+    // GAIN keys: the generator emits ^PW/^LL defaults that the raw ZPL
+    // didn't include. Subset-check captures the regression without
+    // fighting that asymmetry.)
+    const { first, second } = roundtrip(SHIPPING_ZPL);
+    const firstKeys = Object.keys(first.labelConfig);
+    const secondKeys = new Set(Object.keys(second.labelConfig));
+    for (const k of firstKeys) {
+      expect(secondKeys.has(k), `key "${k}" dropped during round-trip`).toBe(true);
+    }
+  });
+
   it('preserves object types in the same order', () => {
     const { first, second } = roundtrip(SHIPPING_ZPL);
     expect(second.objects.map((o) => o.type)).toEqual(first.objects.map((o) => o.type));

From 55bda8309e89826c57cac53a800ff2782d5253ed Mon Sep 17 00:00:00 2001
From: u8array <alexanderleinich1@gmail.com>
Date: Sat, 30 May 2026 19:53:14 +0200
Subject: [PATCH 3/4] refactor(arch): move text-layout helpers from
 components/Canvas to lib/labelGeometry
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Architecture epic #2 — Parser → Canvas decoupling.

The ZPL parser (a pure Domain module) imported \`zplAnchorToModel\`
and \`computeTextRenderMetrics\` from \`components/Canvas\`. Same for
\`registry/zplHelpers.ts\` and \`registry/text.tsx\`'s ZPL-emit path.
This made Domain code transitively depend on a folder named for UI.

The three files are in fact pure logic:
- textPositionTransforms.ts — anchor / FO / FT geometry, no DOM
- measureTextDots.ts — DOM-canvas measureText with non-DOM fallback
- textRenderMetrics.ts — combines the above + font helpers from lib/

None import Konva, React, or any Canvas-folder component. The
"Canvas/" location was historical (Konva renderer was their first
consumer); they belong in lib/ where every consumer can reach them
without crossing the UI boundary.

Move:
- src/components/Canvas/textPositionTransforms{,.test}.ts
- src/components/Canvas/textRenderMetrics.ts
- src/components/Canvas/measureTextDots.ts
  → src/lib/labelGeometry/

Importers updated:
- src/lib/zplParser.ts
- src/registry/text.tsx
- src/registry/zplHelpers.ts
- src/components/Canvas/KonvaObject.tsx (still uses them, now via lib path)

Single source of truth preserved (same module, just relocated).
Tests + build green; no behavior change.
---
 src/components/Canvas/KonvaObject.tsx                         | 4 ++--
 .../Canvas => lib/labelGeometry}/measureTextDots.ts           | 0
 .../labelGeometry}/textPositionTransforms.test.ts             | 0
 .../Canvas => lib/labelGeometry}/textPositionTransforms.ts    | 0
 .../Canvas => lib/labelGeometry}/textRenderMetrics.ts         | 4 ++--
 src/lib/zplParser.ts                                          | 4 ++--
 src/registry/text.tsx                                         | 2 +-
 src/registry/zplHelpers.ts                                    | 4 ++--
 8 files changed, 9 insertions(+), 9 deletions(-)
 rename src/{components/Canvas => lib/labelGeometry}/measureTextDots.ts (100%)
 rename src/{components/Canvas => lib/labelGeometry}/textPositionTransforms.test.ts (100%)
 rename src/{components/Canvas => lib/labelGeometry}/textPositionTransforms.ts (100%)
 rename src/{components/Canvas => lib/labelGeometry}/textRenderMetrics.ts (97%)

diff --git a/src/components/Canvas/KonvaObject.tsx b/src/components/Canvas/KonvaObject.tsx
index 482f81e4..b6394faa 100644
--- a/src/components/Canvas/KonvaObject.tsx
+++ b/src/components/Canvas/KonvaObject.tsx
@@ -11,8 +11,8 @@ import { reverseShapeStyle } from "./reverseShapeStyle";
 import { useColorScheme } from "../../lib/useColorScheme";
 import { useLabelStore } from "../../store/labelStore";
 import { applyBindingToObject, buildActiveCsvRow } from "../../lib/variableBinding";
-import { ZPL_FONT_HEIGHT_TO_CSS_RATIO } from "./textPositionTransforms";
-import { getTextRenderMetrics } from "./textRenderMetrics";
+import { ZPL_FONT_HEIGHT_TO_CSS_RATIO } from "../../lib/labelGeometry/textPositionTransforms";
+import { getTextRenderMetrics } from "../../lib/labelGeometry/textRenderMetrics";
 import { selectionHandlers, type KonvaObjectProps } from "./konvaObjectProps";
 import { DEFAULT_GS_SYMBOL_META, GS_SYMBOLS } from "../../registry/symbol";
 import { GS_SYMBOL_PATHS, GS_VECTOR_CODES, type GsVectorCode } from "../../registry/gsSymbolPaths";
diff --git a/src/components/Canvas/measureTextDots.ts b/src/lib/labelGeometry/measureTextDots.ts
similarity index 100%
rename from src/components/Canvas/measureTextDots.ts
rename to src/lib/labelGeometry/measureTextDots.ts
diff --git a/src/components/Canvas/textPositionTransforms.test.ts b/src/lib/labelGeometry/textPositionTransforms.test.ts
similarity index 100%
rename from src/components/Canvas/textPositionTransforms.test.ts
rename to src/lib/labelGeometry/textPositionTransforms.test.ts
diff --git a/src/components/Canvas/textPositionTransforms.ts b/src/lib/labelGeometry/textPositionTransforms.ts
similarity index 100%
rename from src/components/Canvas/textPositionTransforms.ts
rename to src/lib/labelGeometry/textPositionTransforms.ts
diff --git a/src/components/Canvas/textRenderMetrics.ts b/src/lib/labelGeometry/textRenderMetrics.ts
similarity index 97%
rename from src/components/Canvas/textRenderMetrics.ts
rename to src/lib/labelGeometry/textRenderMetrics.ts
index 343d830d..bcee3fe8 100644
--- a/src/components/Canvas/textRenderMetrics.ts
+++ b/src/lib/labelGeometry/textRenderMetrics.ts
@@ -1,5 +1,5 @@
-import { resolvePreviewFontName } from "../../lib/customFonts";
-import { getFontFamily } from "../../lib/fontCache";
+import { resolvePreviewFontName } from "../customFonts";
+import { getFontFamily } from "../fontCache";
 import type { LabelObject } from "../../types/Group";
 import type { LabelConfig } from "../../types/ObjectType";
 import { measureInkWidthPx } from "./measureTextDots";
diff --git a/src/lib/zplParser.ts b/src/lib/zplParser.ts
index 2a03fc72..a6d3d1ca 100644
--- a/src/lib/zplParser.ts
+++ b/src/lib/zplParser.ts
@@ -35,8 +35,8 @@ import {
   type ClockChars,
 } from "./fcTemplate";
 import { decodeFbContent } from "./fbContent";
-import { zplAnchorToModel } from "../components/Canvas/textPositionTransforms";
-import { computeTextRenderMetrics } from "../components/Canvas/textRenderMetrics";
+import { zplAnchorToModel } from "./labelGeometry/textPositionTransforms";
+import { computeTextRenderMetrics } from "./labelGeometry/textRenderMetrics";
 import type { LabelObject } from "../types/Group";
 import type { TextProps } from "../registry/text";
 import type { Code128Props } from "../registry/code128";
diff --git a/src/registry/text.tsx b/src/registry/text.tsx
index 705578a9..3539b2b8 100644
--- a/src/registry/text.tsx
+++ b/src/registry/text.tsx
@@ -3,7 +3,7 @@ import type { ObjectTypeDefinition } from "../types/ObjectType";
 import { useT } from "../lib/useT";
 import { buttonCls, inputCls, labelCls } from "../components/Properties/styles";
 import { textFieldPos, fdFieldFor, resolveFontCmd } from "./zplHelpers";
-import { getTextRenderMetrics } from "../components/Canvas/textRenderMetrics";
+import { getTextRenderMetrics } from "../lib/labelGeometry/textRenderMetrics";
 import type { LabelObject } from "../types/Group";
 import { effectiveScale } from "./transformHelpers";
 import { getFont, loadFontFile } from "../lib/fontCache";
diff --git a/src/registry/zplHelpers.ts b/src/registry/zplHelpers.ts
index 54c79ed1..bc14ae7f 100644
--- a/src/registry/zplHelpers.ts
+++ b/src/registry/zplHelpers.ts
@@ -1,8 +1,8 @@
 import type { LabelObjectBase, ZplEmitContext } from "../types/ObjectType";
 import { hasTemplateMarkers, markersToEmbeds } from "../lib/fnTemplate";
 import { hasClockMarkers, markersToTokens } from "../lib/fcTemplate";
-import { modelToZplAnchor } from "../components/Canvas/textPositionTransforms";
-import { getTextRenderMetrics } from "../components/Canvas/textRenderMetrics";
+import { modelToZplAnchor } from "../lib/labelGeometry/textPositionTransforms";
+import { getTextRenderMetrics } from "../lib/labelGeometry/textRenderMetrics";
 import type { LabelObject } from "../types/Group";
 
 /** Emit `^FT` or `^FO` depending on how the object was originally positioned. */

From 63bef7019f9db1ff9f45dc547d1b32843f362273 Mon Sep 17 00:00:00 2001
From: u8array <alexanderleinich1@gmail.com>
Date: Sat, 30 May 2026 22:26:32 +0200
Subject: [PATCH 4/4] refactor(arch): decompose zplParser monolith into
 pipeline subfolder
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Architecture epic #4 — split the 2466-LOC parser monolith into
focused modules under \`src/lib/zplParser/\`. Backward-compatible
re-exports keep \`import from "../lib/zplParser"\` working unchanged
across all 12 consumer test files (~362 tests) without import-path
updates.

Stage 1-2: pure functions out.
- types.ts (67 LOC) — ImportFinding{Kind}, ImportReport, ParsedZPL,
  Handler, DecodedGraphic, UploadedGraphic
- helpers.ts (117 LOC) — tokenize, int, inRange, strParam, makeObj,
  variableNameFromComment, ciToEncoding, getDecoder, decodeFH
- decoders/crc.ts (79 LOC) — crc16Xmodem, base64ToBytes,
  parseGfWrapper
- decoders/gfa.ts (139 LOC) — tryInflateZlib, gfaHexToBytes,
  decompressGFA, gfPayloadToBytes
- decoders/graphic.ts (65 LOC) — decodeGraphicToImage (the only
  decoder module that touches the DOM)

Stage 3 (partial): handler-family pattern proven across 3 cohesive
groups, each takes only the slice it actually mutates. Orchestrator
merges via \`Object.assign(handlers, createFamilyHandlers(...))\`.
- handlers/setupScript.ts (112 LOC) — JZ/JT/~TA/ST/KD/KL/SE/SZ/KN/SL,
  all printerProfile mutators
- handlers/labelConfig.ts (115 LOC) — PW/LL/PQ/MM/LS/PR/MD/MT/MN/
  ML/MF/XB/PO/PM/~SD, labelConfig + dpmm
- handlers/unsupported.ts (49 LOC) — 13 noops + 5 browser-limit
  factories (FL/HT/LF/IM/~DG), append-only sinks

Dependency graph stays strictly acyclic:
  types ─┐
  helpers┤
  crc ──→ gfa ──→ graphic ──→ zplParser.ts ──→ handlers/*
                                  ↑
                                  └─ orchestrator merges all

zplParser.ts shrinks 2466 → 1757 LOC (−709, −29%). 743 LOC moved
to 8 focused modules. No behavior change; 1408 tests pass.

Remaining work in epic #4 (out of scope here, eigene Session):
- ParserContext extraction (~520 LOC of closure-state move; the
  fundamental "context.ts" file the planner outlined as Stage 3)
- Per-family extraction of barcodes (~210), graphics (~280),
  fields (~380) — each needs ParserContext to land first
- flushField (~445 LOC, gravitational center of the closure-state)
---
 .../Properties/TemplateContentInput.tsx       |  13 +-
 src/lib/zplImportService.test.ts              |  15 +
 src/lib/zplParser.ts                          | 785 +-----------------
 src/lib/zplParser/decoders/constants.ts       |   2 +
 src/lib/zplParser/decoders/crc.ts             |  80 ++
 src/lib/zplParser/decoders/gfa.ts             | 140 ++++
 src/lib/zplParser/decoders/graphic.ts         |  64 ++
 src/lib/zplParser/handlers/labelConfig.ts     | 119 +++
 src/lib/zplParser/handlers/setupScript.ts     | 112 +++
 src/lib/zplParser/handlers/unsupported.ts     |  48 ++
 src/lib/zplParser/helpers.ts                  | 117 +++
 src/lib/zplParser/types.ts                    |  67 ++
 12 files changed, 808 insertions(+), 754 deletions(-)
 create mode 100644 src/lib/zplParser/decoders/constants.ts
 create mode 100644 src/lib/zplParser/decoders/crc.ts
 create mode 100644 src/lib/zplParser/decoders/gfa.ts
 create mode 100644 src/lib/zplParser/decoders/graphic.ts
 create mode 100644 src/lib/zplParser/handlers/labelConfig.ts
 create mode 100644 src/lib/zplParser/handlers/setupScript.ts
 create mode 100644 src/lib/zplParser/handlers/unsupported.ts
 create mode 100644 src/lib/zplParser/helpers.ts
 create mode 100644 src/lib/zplParser/types.ts

diff --git a/src/components/Properties/TemplateContentInput.tsx b/src/components/Properties/TemplateContentInput.tsx
index 60562362..03416e79 100644
--- a/src/components/Properties/TemplateContentInput.tsx
+++ b/src/components/Properties/TemplateContentInput.tsx
@@ -29,11 +29,11 @@ import type { Variable } from "../../types/Variable";
 function caretOffsetIn(
   editor: HTMLElement,
   sel: Selection | null,
-  which: 'anchor' | 'focus' = 'anchor',
+  which: "anchor" | "focus" = "anchor",
 ): number | null {
   if (!sel || sel.rangeCount === 0) return null;
-  const node = which === 'anchor' ? sel.anchorNode : sel.focusNode;
-  const offset = which === 'anchor' ? sel.anchorOffset : sel.focusOffset;
+  const node = which === "anchor" ? sel.anchorNode : sel.focusNode;
+  const offset = which === "anchor" ? sel.anchorOffset : sel.focusOffset;
   if (!node || !editor.contains(node)) return null;
   return getCaretOffset(editor, node, offset);
 }
@@ -258,7 +258,7 @@ export function TemplateContentInput({
     const marker = `«${markerBody}»`;
     const start = getCaretOffsetInEditor();
     const end = editor
-      ? (caretOffsetIn(editor, window.getSelection(), 'focus') ?? start)
+      ? (caretOffsetIn(editor, window.getSelection(), "focus") ?? start)
       : start;
     const lo = Math.min(start, end);
     const hi = Math.max(start, end);
@@ -291,8 +291,8 @@ export function TemplateContentInput({
      *  to caret at end-of-value for off-editor selections. */
     const selectionRange = (fallbackLen: number) => {
       const sel = window.getSelection();
-      const start = caretOffsetIn(editor, sel, 'anchor') ?? fallbackLen;
-      const end = caretOffsetIn(editor, sel, 'focus') ?? start;
+      const start = caretOffsetIn(editor, sel, "anchor") ?? fallbackLen;
+      const end = caretOffsetIn(editor, sel, "focus") ?? start;
       return { lo: Math.min(start, end), hi: Math.max(start, end) };
     };
     /** Browser-native undo/redo route through zundo (global Ctrl+Z),
@@ -373,7 +373,6 @@ export function TemplateContentInput({
       editor.removeEventListener("beforeinput", handler);
       editor.removeEventListener("paste", handlePaste);
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps
   }, []);
 
   const onInput = () => {
diff --git a/src/lib/zplImportService.test.ts b/src/lib/zplImportService.test.ts
index 3e23bb32..10229e85 100644
--- a/src/lib/zplImportService.test.ts
+++ b/src/lib/zplImportService.test.ts
@@ -99,4 +99,19 @@ describe('importZplText: findings.pageIndex', () => {
     expect(onPage1).toHaveLength(1);
     expect(onPage1[0]?.command).toBe('^A@');
   });
+
+  it('folds printerProfile across multiple ^XA blocks (last-write-wins per key, non-overlapping preserved)', () => {
+    // Block 1 sets reprintAfterError=N + setRealtimeClock.
+    // Block 2 overrides reprintAfterError to Y.
+    // Result must carry Y from block 2 AND the clock from block 1 —
+    // a per-block fold mid-pipeline; a refactor that collapsed the
+    // fold to one end-of-stream pass would lose one of the two.
+    const zpl = [
+      '^XA^JZN^ST05,20,2026,12,00,00^XZ',
+      '^XA^JZY^XZ',
+    ].join('\n');
+    const { printerProfile } = importZplText(zpl, 8);
+    expect(printerProfile.reprintAfterError).toBe('Y');
+    expect(printerProfile.setRealtimeClock).toBeDefined();
+  });
 });
diff --git a/src/lib/zplParser.ts b/src/lib/zplParser.ts
index a6d3d1ca..f2ce1af0 100644
--- a/src/lib/zplParser.ts
+++ b/src/lib/zplParser.ts
@@ -1,27 +1,5 @@
 import type { CustomFontMapping, LabelConfig } from "../types/ObjectType";
 import type { PrinterProfile } from "../types/PrinterProfile";
-import {
-  CLOCK_TOLERANCE_RANGE,
-  DARKNESS_INSTANT_RANGE,
-  DARKNESS_PERMANENT_RANGE,
-  HEAD_TEST_INTERVAL_RANGE,
-  MAX_LABEL_LENGTH_RANGE,
-  PRINTER_NAME_MAX_LEN,
-  SPEED_RANGE,
-  TEAR_OFF_ADJUST_RANGE,
-  isClockFormat,
-  isClockLanguage,
-  isMediaFeedMode,
-  isMediaMode,
-  isMediaTracking,
-  isMediaType,
-  isPrintOrientation,
-  isPrinterLocale,
-  isZplMode,
-  setupScriptUnsafeCharRegex,
-} from "../types/ObjectType";
-import { parseIntOrUndef } from "./inputParse";
-import { parseRealtimeClock } from "./realtimeClock";
 import {
   FN_NUMBER_MIN,
   FN_NUMBER_MAX,
@@ -59,523 +37,41 @@ import type { AztecProps } from "../registry/aztec";
 import type { MaxicodeProps } from "../registry/maxicode";
 import type { MicroPdf417Props } from "../registry/micropdf417";
 import type { CodablockProps } from "../registry/codablock";
-import { unzlibSync } from "fflate";
-import { putImage } from "./imageCache";
 import { formatStoragePath, parseStoragePath } from "./storagePath";
 import { loadFontBytesSync } from "./fontCache";
 import { ZPL_BUILTIN_FONT_LETTERS } from "./customFonts";
 import { GS1_DATABAR_DEFAULT_SEGMENTS } from "./gs1";
-
-export type ImportFindingKind = "partial" | "browserLimit" | "unknown";
-
-/**
- * One import finding. Created per-occurrence so each entry can be navigated
- * to its source page in the UI; cross-block dedup happens (if at all) in the
- * service layer that merges per-page parser runs.
- */
-export interface ImportFinding {
-  kind: ImportFindingKind;
-  /** Command token. For 'partial' the bare code (e.g. "^A@"); for
-   *  'browserLimit' / 'unknown' the full token including parameters
-   *  (e.g. "^IM,R:LOGO.GRF"). Matches the pre-finding-restructure
-   *  format so existing UI / format helpers keep working. */
-  command: string;
-  /** Page index this finding originated from. The parser doesn't know about
-   *  pages and emits 0; `zplImportService` overwrites it when it merges the
-   *  per-block parser results into a multi-page report. */
-  pageIndex: number;
-}
-
-/**
- * Categorised import report produced alongside the parsed objects.
- * `findings` is the source of truth; the three string buckets are derived
- * views kept for backward compatibility with existing parser tests and
- * the textual report formatter.
- */
-export interface ImportReport {
-  /** Per-block findings grouped by kind (partial, then browserLimit, then
-   *  unknown). Inside each group, entries are in encounter order; the
-   *  partial group is deduplicated by command code. The derived arrays
-   *  below offer a kind-filtered view. */
-  findings: ImportFinding[];
-  /** Commands that were imported with known loss (e.g. ^A@ → font face not available in browser).
-   *  An object WAS created; something about it is approximate. Deduplicated by command code. */
-  partial: string[];
-  /** Commands skipped because they require printer hardware or file storage
-   *  (e.g. ^IM, ~DG). No object was created for these. */
-  browserLimit: string[];
-  /** Commands that were not recognised at all. No object was created for these. */
-  unknown: string[];
-}
-
-export interface ParsedZPL {
-  labelConfig: Partial<LabelConfig>;
-  /** EEPROM-persistent printer-state extracted from any Setup-Script
-   *  commands in the stream (^JZ, ^JT, ~TA, ^ST, ^KD, ^SL, ^KL, ^SE,
-   *  ^SZ, ^KN). Distinct from `labelConfig` so import doesn't leak
-   *  per-installation state into the per-label design. Caller decides
-   *  whether to merge these into the active store profile or surface
-   *  them for user confirmation. */
-  printerProfile: Partial<PrinterProfile>;
-  objects: LabelObject[];
-  /** Template variables reconstructed from `^FN` slots. The parser creates
-   *  one entry per distinct fnNumber it sees and points every bound
-   *  object's `variableId` at the matching entry. Empty when no `^FN`
-   *  appeared in the block. */
-  variables: Variable[];
-  /** All commands that were not fully imported (browserLimit + unknown).
-   *  Kept for backward compatibility; prefer importReport for categorised access. */
-  skipped: string[];
-  /** Categorised breakdown of import fidelity */
-  importReport: ImportReport;
-}
-
-type Handler = (p: string[], rest: string) => void;
-
-// ZPL commands start with ^ or ~ followed by 2 characters
-function tokenize(zpl: string): { cmd: string; rest: string }[] {
-  const tokens: { cmd: string; rest: string }[] = [];
-  // Split on both ^ and ~ delimiters, preserving the delimiter type
-  const parts = zpl.split(/(?=[\^~])/);
-  for (const part of parts) {
-    if (part.length < 3) continue; // need delimiter + 2-char command
-    const delimiter = part[0];
-    if (delimiter !== "^" && delimiter !== "~") continue;
-    const cmd = part.slice(1, 3).toUpperCase();
-    const rest = part.slice(3);
-    tokens.push({ cmd, rest });
-  }
-  return tokens;
-}
-
-function int(s: string | undefined, fallback = 0): number {
-  const n = Number.parseInt(s ?? "", 10);
-  return Number.isNaN(n) ? fallback : n;
-}
-
-/** Tiny range helper for parser handlers that gate a value on a
- *  `*_RANGE` constant. Returns the value when in range, undefined
- *  otherwise — matches the parser's "silently drop invalid params"
- *  contract while removing the repetitive `>= R.min && <= R.max`
- *  shape from each ranged handler. */
-function inRange(v: number | undefined, r: { min: number; max: number }): number | undefined {
-  return v !== undefined && v >= r.min && v <= r.max ? v : undefined;
-}
-
-/** Normalised positional string param: trims surrounding whitespace
- *  (the tokenizer keeps trailing `\n` etc. on the last positional)
- *  and upper-cases for case-insensitive enum matches. Use for any
- *  multi-positional string-enum handler so each handler agrees on
- *  the same param-cleaning contract. */
-function strParam(s: string | undefined): string {
-  return (s ?? "").trim().toUpperCase();
-}
-
-function makeObj(
-  type: string,
-  x: number,
-  y: number,
-  props: unknown,
-  positionType?: "FO" | "FT",
-  comment?: string,
-): LabelObject {
-  return {
-    id: crypto.randomUUID(),
-    type,
-    x,
-    y,
-    rotation: 0,
-    positionType,
-    comment,
-    props,
-  } as unknown as LabelObject;
-}
-
-/** Derive a Variable name from a `^FX` comment that landed just before the
- *  `^FN`. Strips well-known annotation prefixes (`Field:`, `Variable:`,
- *  `Var:`) so a comment like "Field: Customer Name" becomes `Customer_Name`.
- *  Returns null when the comment is missing or sanitises to empty — the
- *  caller falls back to `field_{n}`. */
-function variableNameFromComment(comment: string | undefined): string | null {
-  if (!comment) return null;
-  const cleaned = comment
-    .replace(/^\s*(field|variable|var)\s*[:-]\s*/i, "")
-    .trim()
-    .replace(/\s+/g, "_");
-  return cleaned === "" ? null : cleaned;
-}
-
-
-/**
- * Map a ^CI N parameter to a TextDecoder label. Most labels printed by this
- * app use ^CI28 (UTF-8); ^CI27 is Windows-1252 (Zebra default for many EU
- * setups); legacy ^CI0..13 are 7-bit-ASCII-compatible code-page variants for
- * which Windows-1252 is a safe superset for the purposes of `^FH` decoding.
- * Unsupported encodings (multi-byte UTF-16/32 variants, code page 850, …)
- * fall back to UTF-8 with the command surfaced via importReport.partial.
- */
-function ciToEncoding(n: number): { label: string; supported: boolean } {
-  if (n === 28) return { label: "utf-8", supported: true };
-  if (n === 27) return { label: "windows-1252", supported: true };
-  if (n >= 0 && n <= 13) return { label: "windows-1252", supported: true };
-  return { label: "utf-8", supported: false };
-}
-
-const decoderCache = new Map<string, TextDecoder>();
-function getDecoder(label: string): TextDecoder {
-  let dec = decoderCache.get(label);
-  if (!dec) {
-    dec = new TextDecoder(label);
-    decoderCache.set(label, dec);
-  }
-  return dec;
-}
-
-/**
- * Decode ^FH hex escapes: replaces runs of {delimiter}XX with the string for
- * the byte sequence XX XX … under the active ^CI encoding. A single non-ASCII
- * glyph may span multiple escape pairs (e.g. `_C3_A4` → `ä` under UTF-8), so
- * we collect contiguous pairs into a Uint8Array and run one TextDecoder pass
- * per run. Invalid byte sequences become U+FFFD (decoder default).
- */
-function decodeFH(
-  text: string,
-  delimiter: string,
-  decoder: TextDecoder,
-): string {
-  const escaped = delimiter.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  const runRe = new RegExp(`(?:${escaped}[0-9A-Fa-f]{2})+`, "g");
-  const stride = delimiter.length + 2;
-  return text.replace(runRe, (run) => {
-    const bytes = new Uint8Array(run.length / stride);
-    for (let i = 0, b = 0; i < run.length; i += stride, b++) {
-      bytes[b] = parseInt(run.slice(i + delimiter.length, i + stride), 16);
-    }
-    return decoder.decode(bytes);
-  });
-}
+import {
+  tokenize,
+  int,
+  makeObj,
+  variableNameFromComment,
+  ciToEncoding,
+  getDecoder,
+  decodeFH,
+} from "./zplParser/helpers";
+import { decodeGraphicToImage } from "./zplParser/decoders/graphic";
+import { createLabelConfigHandlers } from "./zplParser/handlers/labelConfig";
+import { createSetupScriptHandlers } from "./zplParser/handlers/setupScript";
+import { createUnsupportedHandlers } from "./zplParser/handlers/unsupported";
+import type {
+  Handler,
+  UploadedGraphic,
+  ImportFinding,
+  ParsedZPL,
+} from "./zplParser/types";
+export type {
+  ImportFindingKind,
+  ImportFinding,
+  ImportReport,
+  ParsedZPL,
+} from "./zplParser/types";
 
 /** Characters of a `^GF`/`~DY` payload retained in browserLimit/skipped
  *  findings; rest is replaced with an ellipsis so a single multi-KB
  *  base64 blob doesn't drown out the import report. */
 const IMPORT_FINDING_PAYLOAD_LIMIT = 80;
 
-const CRC16_POLY = 0x1021;
-const CRC16_MSB_MASK = 0x8000; // 1 << 15
-const CRC16_MASK = 0xffff;
-const BITS_PER_BYTE = 8;
-
-/**
- * CRC-16/XMODEM (poly 0x1021, init 0x0000, no reflect, no xorout) —
- * Zebra's ZB64/ZB16 wrapper uses this variant. Computed over the base64
- * (or hex) payload between the `:B64:`/`:Z64:` prefix and the trailing
- * `:CRC` suffix. (Note: this is *not* CRC-16/CCITT-FALSE, which uses
- * init=0xFFFF — empirically verified against Labelary: payloads with the
- * XMODEM CRC are accepted, CCITT-FALSE CRC is rejected.)
- */
-function crc16Xmodem(s: string): number {
-  let crc = 0;
-  for (const ch of s) {
-    crc ^= ch.charCodeAt(0) << BITS_PER_BYTE;
-    for (let j = 0; j < BITS_PER_BYTE; j++) {
-      crc = (crc & CRC16_MSB_MASK)
-        ? ((crc << 1) ^ CRC16_POLY) & CRC16_MASK
-        : (crc << 1) & CRC16_MASK;
-    }
-  }
-  return crc;
-}
-
-type GfWrapperKind = "b64" | "z64";
-
-interface GfWrapperDecoded {
-  kind: GfWrapperKind;
-  /** Raw decoded bytes — for `:Z64:` this is still zlib-compressed. */
-  bytes: Uint8Array;
-  /** True if the trailing CRC matches the base64 payload. */
-  crcOk: boolean;
-}
-
-/** CRC-16 emitted as 4 uppercase hex chars in the `:B64:`/`:Z64:` trailer. */
-const CRC_HEX_DIGITS = 4;
-// \s in the base64 char class tolerates the line-break-every-N-chars
-// formatting that some ZPL generators apply to long ^GF payloads.
-const GF_WRAPPER_RE = new RegExp(
-  `^:(B64|Z64):([A-Za-z0-9+/=\\s]+):([0-9A-Fa-f]{${CRC_HEX_DIGITS}})$`,
-);
-
-/** Decode a base64 string to bytes; empty array on malformed input. */
-function base64ToBytes(b64: string): Uint8Array {
-  let bin: string;
-  try {
-    bin = atob(b64);
-  } catch {
-    return new Uint8Array(0);
-  }
-  const bytes = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
-  return bytes;
-}
-
-/**
- * Parse a `:B64:<base64>:<crc>` or `:Z64:<base64>:<crc>` wrapper. Returns
- * null if the payload doesn't carry a wrapper. Used inside `^GFA`/`^GFB`/
- * `^GFC` where Zebra firmware accepts the same envelope. The CRC is
- * computed over the base64 string (CRC-16/XMODEM) and surfaced as a flag
- * rather than a hard reject — printers tolerate mismatches, and we'd
- * rather render a slightly-suspect graphic than silently drop it.
- *
- * `payload.trim()` because real-world ZPL is often line-broken between
- * commands; the tokenizer keeps the trailing newline on `rest`, and an
- * un-trimmed regex with a `$` anchor would miss every wrapper-in-the-wild.
- */
-function parseGfWrapper(payload: string): GfWrapperDecoded | null {
-  const m = GF_WRAPPER_RE.exec(payload.trim());
-  if (!m) return null;
-  // atob and the CRC both fail on embedded whitespace — strip after match
-  // so the wrapper-form regex above can stay permissive for line-broken
-  // payloads but the downstream decoders see pure base64.
-  const b64 = (m[2] ?? "").replace(/\s/g, "");
-  const declaredCrc = parseInt(m[3] ?? "0", 16);
-  return {
-    kind: (m[1] ?? "").toLowerCase() as GfWrapperKind,
-    bytes: base64ToBytes(b64),
-    crcOk: crc16Xmodem(b64) === declaredCrc,
-  };
-}
-
-/**
- * Result of `gfPayloadToBytes`: the raw bitmap bytes (one row = N bytes,
- * each byte = 8 pixels, MSB first) plus the integrity flag for the
- * originating wrapper. `crcOk=false` is rendered with a fidelity caveat;
- * `null` from `gfPayloadToBytes` means the payload was undecodable.
- */
-interface GfPayloadDecoded {
-  data: Uint8Array;
-  crcOk: boolean;
-}
-
-/** Inflate `:Z64:` zlib payload; null on malformed deflate stream. */
-function tryInflateZlib(input: Uint8Array): Uint8Array | null {
-  try {
-    return unzlibSync(input);
-  } catch {
-    return null;
-  }
-}
-
-/** Decode the ASCII-hex output of `decompressGFA` into a packed byte array
- *  so all three GF code paths converge on the same `Uint8Array` shape.
- *  Indexed access + nibble shift instead of `parseInt(slice)` because the
- *  per-byte slice/parseInt pair is the dominant cost on multi-KB bitmaps. */
-function gfaHexToBytes(hex: string): Uint8Array {
-  const out = new Uint8Array(hex.length >> 1);
-  for (let i = 0; i < out.length; i++) {
-    const hi = parseInt(hex[i * 2] ?? "0", 16);
-    const lo = parseInt(hex[i * 2 + 1] ?? "0", 16);
-    out[i] = (hi << 4) | lo;
-  }
-  return out;
-}
-
-/**
- * Normalise a `^GF{A|B|C}` payload to packed bitmap bytes. Hides the
- * format / wrapper / compression dispatch from the command handler so the
- * latter can stay focused on positioning and pixel painting.
- *
- *  - `:B64:`/`:Z64:` wrapper → base64-decode (then zlib-inflate for Z64)
- *  - `format=A` without wrapper → existing RLE-hex path → bytes
- *  - `format=B`/`C` without wrapper → null (raw binary can't survive the
- *    text-based ZPL channel and the parser never sees intact bytes anyway)
- */
-function gfPayloadToBytes(
-  rawData: string,
-  format: "A" | "B" | "C",
-  bytesPerRow: number,
-): GfPayloadDecoded | null {
-  const wrapper = parseGfWrapper(rawData);
-  if (wrapper) {
-    const bytes =
-      wrapper.kind === "z64" ? tryInflateZlib(wrapper.bytes) : wrapper.bytes;
-    if (!bytes) return null;
-    return { data: bytes, crcOk: wrapper.crcOk };
-  }
-  if (format === "A") {
-    return { data: gfaHexToBytes(decompressGFA(rawData, bytesPerRow)), crcOk: true };
-  }
-  return null;
-}
-
-/** Outcome of decoding any GF-shaped graphic (^GF or ~DY graphic upload)
- *  into an image-cache entry. Common to both call sites so the per-handler
- *  code only needs to bind it to the right ZPL artifact (label object vs.
- *  preamble registration). */
-interface DecodedGraphic {
-  imageId: string;
-  widthDots: number;
-  heightDots: number;
-  /** Verbatim `^GF{format},total,data,bpr,DATA` reconstruction kept on the
-   *  image so round-trip emit can splice the same byte stream back into
-   *  either `^GF` (inline) or `~DY` (preamble) without re-encoding. */
-  gfaCache: string;
-  crcOk: boolean;
-}
-
-/** Entry in the `~DY → ^XG` lookup map: a graphic uploaded earlier in the
- *  stream, keyed by its full `device:stem.ext` path. Structurally a
- *  `DecodedGraphic` without the per-decode CRC flag — that lives on the
- *  partialCmds set instead of on every map entry. */
-type UploadedGraphic = Omit<DecodedGraphic, "crcOk">;
-
-/**
- * Decode a GF-shaped payload into an image-cache entry. Shared between the
- * `^GF` inline path and the `~DY` graphic-upload preamble; both have the
- * same payload shape and need the same decoded bitmap, canvas paint, and
- * cache write. Returns `null` when the payload can't be decoded (caller
- * surfaces as browserLimit).
- */
-function decodeGraphicToImage(
-  rawData: string,
-  format: "A" | "B" | "C",
-  bytesPerRow: number,
-  totalBytesHeader: string,
-  dataBytesHeader: string,
-  nameHint: string,
-): DecodedGraphic | null {
-  const decoded = gfPayloadToBytes(rawData, format, bytesPerRow);
-  if (!decoded) return null;
-  const widthDots = bytesPerRow * BITS_PER_BYTE;
-  const heightDots = Math.floor(decoded.data.length / bytesPerRow);
-  if (heightDots <= 0) return null;
-  const canvas = document.createElement("canvas");
-  canvas.width = widthDots;
-  canvas.height = heightDots;
-  const ctx = canvas.getContext("2d");
-  if (!ctx) throw new Error("Could not get 2d context");
-  const imgData = ctx.createImageData(widthDots, heightDots);
-  const pixels = imgData.data;
-  for (let row = 0; row < heightDots; row++) {
-    for (let byteIdx = 0; byteIdx < bytesPerRow; byteIdx++) {
-      const byte = decoded.data[row * bytesPerRow + byteIdx] ?? 0;
-      for (let bit = 0; bit < BITS_PER_BYTE; bit++) {
-        const px = byteIdx * BITS_PER_BYTE + bit;
-        const idx = (row * widthDots + px) * 4;
-        // ZPL ^GF: 1-bit = black (printed), 0-bit = transparent.
-        // ImageData starts zero-filled (rgba(0,0,0,0)), which is exactly
-        // the 0-bit case — only the 1-bit case needs a write.
-        if ((byte & (0x80 >> bit)) !== 0) {
-          pixels[idx + 3] = 255;
-        }
-      }
-    }
-  }
-  ctx.putImageData(imgData, 0, 0);
-  const imageId = crypto.randomUUID();
-  putImage({
-    id: imageId,
-    name: nameHint,
-    dataUrl: canvas.toDataURL("image/png"),
-    width: widthDots,
-    height: heightDots,
-  });
-  return {
-    imageId,
-    widthDots,
-    heightDots,
-    gfaCache: `^GF${format},${totalBytesHeader},${dataBytesHeader},${bytesPerRow},${rawData}`,
-    crcOk: decoded.crcOk,
-  };
-}
-
-/**
- * Decompress ZPL Alternative Data Compression used in ^GFA fields.
- *
- * Compression characters:
- *   G–Y (uppercase) → repeat next hex digit 1–19 times
- *   g–z (lowercase) → repeat next hex digit 20–400 times (multiples of 20)
- *   Combinable: e.g. hI0 = (40+3) × '0' = 43 zeros
- *   ,  → fill remainder of current row with '0'
- *   !  → fill remainder of current row with 'F'
- *   :  → repeat previous row
- */
-function decompressGFA(data: string, bytesPerRow: number): string {
-  const nibblesPerRow = bytesPerRow * 2;
-  const rows: string[] = [];
-  let currentRow = "";
-  let i = 0;
-
-  const isHex = (ch: string) => /[0-9A-Fa-f]/.test(ch);
-  const repeatCount = (ch: string): number => {
-    if (ch >= "G" && ch <= "Y") return ch.charCodeAt(0) - 70; // G=1 .. Y=19
-    if (ch >= "g" && ch <= "z") return (ch.charCodeAt(0) - 102) * 20; // g=20 .. z=400
-    return 0;
-  };
-  const isCompressChar = (ch: string) =>
-    (ch >= "G" && ch <= "Y") || (ch >= "g" && ch <= "z");
-
-  const pushRow = () => {
-    rows.push(currentRow.slice(0, nibblesPerRow).padEnd(nibblesPerRow, "0"));
-    currentRow = "";
-  };
-
-  while (i < data.length) {
-    const ch = data[i] ?? "";
-
-    if (ch === ",") {
-      // Fill rest of row with '0', complete row
-      pushRow();
-      i++;
-    } else if (ch === "!") {
-      // Fill rest of row with 'F', complete row
-      currentRow = currentRow.padEnd(nibblesPerRow, "F");
-      rows.push(currentRow.slice(0, nibblesPerRow));
-      currentRow = "";
-      i++;
-    } else if (ch === ":") {
-      // Repeat previous row
-      rows.push(
-        rows.length > 0
-          ? (rows[rows.length - 1] ?? "0".repeat(nibblesPerRow))
-          : "0".repeat(nibblesPerRow),
-      );
-      i++;
-    } else if (isCompressChar(ch)) {
-      // Accumulate repeat count (lowercase + uppercase can combine)
-      let count = repeatCount(ch);
-      i++;
-      while (i < data.length && isCompressChar(data[i] ?? "")) {
-        count += repeatCount(data[i] ?? "");
-        i++;
-      }
-      // Next character is the hex digit to repeat
-      const nextCh = data[i] ?? "";
-      if (i < data.length && isHex(nextCh)) {
-        currentRow += nextCh.repeat(count);
-        i++;
-      }
-    } else if (isHex(ch)) {
-      currentRow += ch;
-      i++;
-    } else {
-      // Skip whitespace / unknown
-      i++;
-    }
-
-    // If row is complete, push it
-    if (currentRow.length >= nibblesPerRow) {
-      rows.push(currentRow.slice(0, nibblesPerRow));
-      currentRow = currentRow.slice(nibblesPerRow);
-    }
-  }
-
-  // Handle any remaining partial row
-  if (currentRow.length > 0) {
-    pushRow();
-  }
-
-  return rows.join("");
-}
-
 export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
   const tokens = tokenize(zpl);
   const objects: LabelObject[] = [];
@@ -1268,7 +764,6 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
   };
 
   // ── Command handler map ────────────────────────────────────────────────────
-  const noop: Handler = () => void 0;
   const resetComment: Handler = (_, rest) => {
     pendingComment = rest.trim() || undefined;
   };
@@ -1280,13 +775,6 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
     if (!next) return;
     pendingComment = pendingComment ? `${pendingComment}\n${next}` : next;
   };
-  const mkBrowserLimit =
-    (prefix: string, delimiter = "^"): Handler =>
-    (_, rest) => {
-      const tok = `${delimiter}${prefix}${rest}`;
-      skipped.push(tok);
-      browserLimit.push(tok);
-    };
 
   const readRotation = (raw: string | undefined): ZplRotation =>
     raw && isZplRotation(raw) ? raw : "N";
@@ -1389,14 +877,7 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
 
   const handlers: Record<string, Handler> = {
     // ── Label dimensions ────────────────────────────────────────────────────
-    PW(_, rest) {
-      const dots = int(rest);
-      if (dots > 0) labelConfig.widthMm = Math.round((dots / dpmm) * 10) / 10;
-    },
-    LL(_, rest) {
-      const dots = int(rest);
-      if (dots > 0) labelConfig.heightMm = Math.round((dots / dpmm) * 10) / 10;
-    },
+    // PW / LL — extracted to handlers/labelConfig.ts (need dpmm).
 
     // ── Field origin ────────────────────────────────────────────────────────
     FO(p) {
@@ -1926,190 +1407,11 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
     },
 
     // ── Label print settings ────────────────────────────────────────────────
-    PQ(p) {
-      const qty = int(p[0], 0);
-      if (qty > 0) labelConfig.printQuantity = qty;
-      // ^PQ q,p,r,o — preserve extended params when present.
-      if (p.length > 1) {
-        const pause = int(p[1], 0);
-        if (pause >= 0 && pause <= 99999999) labelConfig.pauseCount = pause;
-      }
-      if (p.length > 2) {
-        const reps = int(p[2], 0);
-        if (reps >= 0 && reps <= 99999999) labelConfig.replicates = reps;
-      }
-      if (p.length > 3) {
-        const o = (p[3] ?? "").toUpperCase();
-        if (o === "Y" || o === "N") labelConfig.overridePauseCount = o;
-      }
-    },
-    MM(_, rest) {
-      // `.trim()` before `[0]` so a stray leading whitespace in the
-      // input (rare but seen with hand-edited ZPL) does not eat the
-      // mode character. Applies to all single-char enum handlers
-      // below (MT / PO / PM / KD).
-      const mode = (rest.trim()[0] ?? "").toUpperCase();
-      if (isMediaMode(mode)) labelConfig.mediaMode = mode;
-    },
-    LS(_, rest) {
-      const shift = int(rest, 0);
-      if (shift !== 0) labelConfig.labelShift = shift;
-    },
-    PR(p) {
-      const print = inRange(parseIntOrUndef(p[0]), SPEED_RANGE);
-      if (print !== undefined) labelConfig.printSpeed = print;
-      const slew = inRange(parseIntOrUndef(p[1]), SPEED_RANGE);
-      if (slew !== undefined) labelConfig.slewSpeed = slew;
-      const bf = inRange(parseIntOrUndef(p[2]), SPEED_RANGE);
-      if (bf !== undefined) labelConfig.backfeedSpeed = bf;
-    },
-    MD(_, rest) {
-      const v = inRange(parseIntOrUndef(rest), DARKNESS_PERMANENT_RANGE);
-      if (v !== undefined) labelConfig.darkness = v;
-    },
-    MT(_, rest) {
-      const mt = (rest.trim()[0] ?? "").toUpperCase();
-      if (isMediaType(mt)) labelConfig.mediaType = mt;
-    },
-    MN(p) {
-      // ^MNa,b — b is an optional black-mark offset for W/M modes,
-      // which we don't model. Reading p[0] instead of the raw rest
-      // string keeps `^MNY,10` from being mis-read as the single
-      // token "Y,10" and silently dropped.
-      const v = strParam(p[0]);
-      if (isMediaTracking(v)) labelConfig.mediaTracking = v;
-    },
-    ML(p) {
-      const v = inRange(parseIntOrUndef(p[0]), MAX_LABEL_LENGTH_RANGE);
-      if (v !== undefined) labelConfig.maxLabelLength = v;
-    },
-    MF(p) {
-      const p1 = strParam(p[0]);
-      const p2 = strParam(p[1]);
-      if (isMediaFeedMode(p1)) labelConfig.mediaFeedPowerUp = p1;
-      if (isMediaFeedMode(p2)) labelConfig.mediaFeedHeadClose = p2;
-    },
-    XB() {
-      labelConfig.suppressBackfeed = true;
-    },
-    JZ(p) {
-      const v = strParam(p[0]);
-      if (v === "Y" || v === "N") printerProfile.reprintAfterError = v;
-    },
-    JT(p) {
-      const v = inRange(parseIntOrUndef(p[0]), HEAD_TEST_INTERVAL_RANGE);
-      if (v !== undefined) printerProfile.headTestInterval = v;
-    },
-    // ~TA reads p[0] (not the raw rest string) so trailing tokens
-    // from a streamed ZPL chunk (e.g. `~TA10^XA…`) don't leak into
-    // the parsed value. The tokeniser strips the leading tilde, so
-    // a plain ~TA-30 still resolves p[0] to "-30".
-    TA(p) {
-      const v = inRange(parseIntOrUndef(p[0]), TEAR_OFF_ADJUST_RANGE);
-      if (v !== undefined) printerProfile.tearOffAdjust = v;
-    },
-    PO(_, rest) {
-      const po = (rest.trim()[0] ?? "").toUpperCase();
-      if (isPrintOrientation(po)) labelConfig.printOrientation = po;
-    },
-    PM(_, rest) {
-      const m = (rest.trim()[0] ?? "").toUpperCase();
-      if (m === "Y" || m === "N") labelConfig.mirror = m;
-    },
-    // ~SD — instant darkness set (00..30). Tilde-prefix; the tokenizer
-    // drops the delimiter, so we accept this as the canonical SD handler.
-    SD(_, rest) {
-      const v = inRange(parseIntOrUndef(rest), DARKNESS_INSTANT_RANGE);
-      if (v !== undefined) labelConfig.instantDarkness = v;
-    },
-    // ^ST MM,DD,YYYY,HH,MM,SS — set real-time clock. Delegates the
-    // shape + range validation to the shared `realtimeClock` helper
-    // so the parser and generator cannot drift on round-trip. Invalid
-    // / partial / impossible inputs are silently dropped, matching
-    // the parser's existing contract.
-    ST(p) {
-      const iso = parseRealtimeClock(p);
-      if (iso !== null) printerProfile.setRealtimeClock = iso;
-    },
-    // ^KD <format-code>. Reads only the first char of `rest`, so
-    // `^KD2,foo` parses as `clockFormat: '2'` and the trailing junk
-    // is dropped. Matches the parser's lenient contract elsewhere
-    // (PO / PM / MT take the same first-char approach).
-    KD(_, rest) {
-      const v = rest.trim()[0] ?? "";
-      if (isClockFormat(v)) printerProfile.clockFormat = v;
-    },
-    // ^KL <locale-code>. Two- or three-char alpha code (see
-    // PRINTER_LOCALE_VALUES). `rest` may contain trailing newline /
-    // tokens from the streamed ZPL; trim and uppercase before the
-    // guard check.
-    KL(_, rest) {
-      const v = rest.trim().toUpperCase();
-      if (isPrinterLocale(v)) printerProfile.printerLocale = v;
-    },
-    // ^SE <file-path>. Free string per spec; trim to drop any
-    // streaming whitespace but otherwise preserve the value as-is
-    // because the firmware path syntax is user-supplied. The
-    // dangerous-char check mirrors the schema regex so an imported
-    // ZPL that smuggled a ^/~ / newline into the path cannot land
-    // in the store and be re-emitted as an injected command.
-    SE(_, rest) {
-      const v = rest.trim();
-      if (v && !setupScriptUnsafeCharRegex.test(v)) printerProfile.encodingTable = v;
-    },
-    // ^SZ <mode>. Single digit '1' or '2'; same first-char-trim
-    // pattern as KD / KL.
-    SZ(_, rest) {
-      const v = rest.trim()[0] ?? "";
-      if (isZplMode(v)) printerProfile.zplMode = v;
-    },
-    // ^KN <name>,<description>. Both parts free strings; the
-    // injection-guard regex mirrors the schema so an imported
-    // ZPL cannot smuggle command-introducer chars into either
-    // field. Name length cap stays per spec.
-    KN(p) {
-      const name = (p[0] ?? "").trim();
-      if (!name || name.length > PRINTER_NAME_MAX_LEN) return;
-      if (setupScriptUnsafeCharRegex.test(name)) return;
-      printerProfile.printerName = name;
-      const desc = (p[1] ?? "").trim();
-      if (desc && !setupScriptUnsafeCharRegex.test(desc)) {
-        printerProfile.printerDescription = desc;
-      }
-    },
-    // ^SL `a`,`b` — Set Mode and Language for ^FC clock fields.
-    // The `a` slot accepts three shapes: 'S' (Start-Time), 'T'
-    // (Time-Now), or numeric 1..999 (Time-Now with tolerance
-    // seconds). The schema models the three shapes as two
-    // fields (clockMode enum + clockTolerance numeric); the
-    // parser fans the wire value out into both.
-    SL(p) {
-      const a = strParam(p[0]);
-      if (a === "S" || a === "T") {
-        printerProfile.clockMode = a;
-        // Clear any tolerance left over from a previous ^SL parse —
-        // schema's cross-field rule forbids `tolerance && mode !== 'TOL'`,
-        // and the parser writes raw values without re-running the
-        // schema, so a stale tolerance from an earlier ^SL60,1 would
-        // make the persisted state un-saveable. `delete` rather than
-        // `= undefined` so the returned ParsedZPL doesn't carry the
-        // key as present-with-undefined (which leaks across the
-        // import-service fold as a misleading "clear" signal).
-        delete printerProfile.clockTolerance;
-      } else {
-        const tol = inRange(parseIntOrUndef(a), CLOCK_TOLERANCE_RANGE);
-        if (tol !== undefined) {
-          printerProfile.clockMode = "TOL";
-          printerProfile.clockTolerance = tol;
-        }
-      }
-      // Language only when the mode parse landed — orphan language
-      // (mode invalid, b valid) would be write-only state (emit
-      // gated on mode anchor, parser would silently re-drop).
-      if (printerProfile.clockMode === undefined) return;
-      const b = strParam(p[1]);
-      if (isClockLanguage(b)) printerProfile.clockLanguage = b;
-    },
+    // PQ / MM / LS / PR / MD / MT / MN / ML / MF / XB / PO / PM / ~SD
+    // extracted to handlers/labelConfig.ts; merged below at the literal end.
+    //
+    // JZ / JT / TA / ST / KD / KL / SE / SZ / KN / SL — Setup-Script
+    // handlers extracted to handlers/setupScript.ts; merged below too.
 
     // ^CW {alias},{path} — register an alias for a printer-resident font.
     // Subsequent ^A{alias} fields resolve to {path} via the fontAliases
@@ -2259,9 +1561,6 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
     },
 
     // ── Browser-limit: printer-specific features ────────────────────────────
-    FL: mkBrowserLimit("FL"), // font link — links fonts on printer storage
-    HT: mkBrowserLimit("HT"), // head test — diagnostic for print head
-    LF: mkBrowserLimit("LF"), // list fonts — queries printer for installed fonts
     GS(p) {
       // ^GS{rotation},{height},{width} — selects the internal-font
       // legal-symbol glyph (^FD picks which: A=®, B=©, C=™, D=UL, E=CSA).
@@ -2270,8 +1569,6 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
       symH = int(p[1], 30);
       symW = int(p[2], symH);
     },
-    IM: mkBrowserLimit("IM"), // image reference — references image stored on printer
-    DG: mkBrowserLimit("DG", "~"), // ~DG stores a graphic on the printer (tilde prefix)
 
     // ── TrueType font / text block ──────────────────────────────────────────
     // ^A@{rotation},{height},{width},{drive}:{font} — TrueType font reference
@@ -2348,7 +1645,6 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
       pendingFn = n;
       pendingFnComment = pendingComment;
     },
-    FV: noop, // field variable — supplies data for ^FN at print time
     FC: (p) => {
       // ^FC<a>,<b>,<c>: redefine clock chars. Missing/empty slots
       // keep their current value (Zebra spec: defaults persist when
@@ -2369,20 +1665,15 @@ export function parseZPL(zpl: string, dpmm = 8): ParsedZPL {
       const c = p[0]?.[0];
       embedChar = c && c !== "^" && c !== "~" ? c : "#";
     },
-    FM: noop, // multiple field origin locations
-    FP: noop, // field parameter — per-character text direction
-    JA: noop, // applicator / configuration recall
-    JM: noop, // darkness / print settings
-    JC: noop, // calibrate
-    JD: noop, // disable head-cleaning
-    JE: noop, // enable head-cleaning
-    JI: noop, // initialize printer
-    JR: noop, // restore factory defaults
-    JS: noop, // change darkness
-    JU: noop, // update firmware
-    PP: noop, // presentation position
+    // FV / FM / FP / JA / JM / JC / JD / JE / JI / JR / JS / JU / PP —
+    // noops; FL / HT / LF / IM / ~DG — browser-limit factories. All
+    // extracted to handlers/unsupported.ts.
   };
 
+  Object.assign(handlers, createSetupScriptHandlers(printerProfile));
+  Object.assign(handlers, createLabelConfigHandlers(labelConfig, dpmm));
+  Object.assign(handlers, createUnsupportedHandlers({ skipped, browserLimit }));
+
   // ── Main dispatch loop ─────────────────────────────────────────────────────
   for (const { cmd, rest } of tokens) {
     const p = rest.split(",");
diff --git a/src/lib/zplParser/decoders/constants.ts b/src/lib/zplParser/decoders/constants.ts
new file mode 100644
index 00000000..bb9b3aa2
--- /dev/null
+++ b/src/lib/zplParser/decoders/constants.ts
@@ -0,0 +1,2 @@
+/** Shared low-level constants used across the GF/CRC/graphic decoders. */
+export const BITS_PER_BYTE = 8;
diff --git a/src/lib/zplParser/decoders/crc.ts b/src/lib/zplParser/decoders/crc.ts
new file mode 100644
index 00000000..041630b9
--- /dev/null
+++ b/src/lib/zplParser/decoders/crc.ts
@@ -0,0 +1,80 @@
+import { BITS_PER_BYTE } from "./constants";
+
+const CRC16_POLY = 0x1021;
+const CRC16_MSB_MASK = 0x8000;
+const CRC16_MASK = 0xffff;
+
+/**
+ * CRC-16/XMODEM (poly 0x1021, init 0x0000, no reflect, no xorout) —
+ * Zebra's ZB64/ZB16 wrapper uses this variant. Computed over the
+ * base64 (or hex) payload between the `:B64:`/`:Z64:` prefix and the
+ * trailing `:CRC` suffix. (Note: this is *not* CRC-16/CCITT-FALSE,
+ * which uses init=0xFFFF — empirically verified against Labelary.)
+ */
+function crc16Xmodem(s: string): number {
+  let crc = 0;
+  for (const ch of s) {
+    crc ^= ch.charCodeAt(0) << BITS_PER_BYTE;
+    for (let j = 0; j < BITS_PER_BYTE; j++) {
+      crc = (crc & CRC16_MSB_MASK)
+        ? ((crc << 1) ^ CRC16_POLY) & CRC16_MASK
+        : (crc << 1) & CRC16_MASK;
+    }
+  }
+  return crc;
+}
+
+type GfWrapperKind = "b64" | "z64";
+
+export interface GfWrapperDecoded {
+  kind: GfWrapperKind;
+  /** Raw decoded bytes — for `:Z64:` this is still zlib-compressed. */
+  bytes: Uint8Array;
+  /** True if the trailing CRC matches the base64 payload. */
+  crcOk: boolean;
+}
+
+const CRC_HEX_DIGITS = 4;
+// \s in the base64 char class tolerates the line-break-every-N-chars
+// formatting that some ZPL generators apply to long ^GF payloads.
+const GF_WRAPPER_RE = new RegExp(
+  `^:(B64|Z64):([A-Za-z0-9+/=\\s]+):([0-9A-Fa-f]{${CRC_HEX_DIGITS}})$`,
+);
+
+/** Decode a base64 string to bytes; empty array on malformed input. */
+function base64ToBytes(b64: string): Uint8Array {
+  let bin: string;
+  try {
+    bin = atob(b64);
+  } catch {
+    return new Uint8Array(0);
+  }
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
+
+/**
+ * Parse a `:B64:<base64>:<crc>` or `:Z64:<base64>:<crc>` wrapper.
+ * Returns null if the payload doesn't carry a wrapper. CRC mismatches
+ * are surfaced as a flag rather than a hard reject — printers tolerate
+ * mismatches, and we'd rather render a slightly-suspect graphic than
+ * silently drop it.
+ *
+ * `payload.trim()` because real-world ZPL is often line-broken between
+ * commands; the tokenizer keeps the trailing newline on `rest`.
+ */
+export function parseGfWrapper(payload: string): GfWrapperDecoded | null {
+  const m = GF_WRAPPER_RE.exec(payload.trim());
+  if (!m) return null;
+  // atob and the CRC both fail on embedded whitespace — strip after
+  // match so the regex stays permissive but downstream decoders see
+  // pure base64.
+  const b64 = (m[2] ?? "").replace(/\s/g, "");
+  const declaredCrc = parseInt(m[3] ?? "0", 16);
+  return {
+    kind: (m[1] ?? "").toLowerCase() as GfWrapperKind,
+    bytes: base64ToBytes(b64),
+    crcOk: crc16Xmodem(b64) === declaredCrc,
+  };
+}
diff --git a/src/lib/zplParser/decoders/gfa.ts b/src/lib/zplParser/decoders/gfa.ts
new file mode 100644
index 00000000..4b789ca6
--- /dev/null
+++ b/src/lib/zplParser/decoders/gfa.ts
@@ -0,0 +1,140 @@
+import { unzlibSync } from "fflate";
+import { parseGfWrapper } from "./crc";
+
+/** Inflate `:Z64:` zlib payload; null on malformed deflate stream. */
+function tryInflateZlib(input: Uint8Array): Uint8Array | null {
+  try {
+    return unzlibSync(input);
+  } catch {
+    return null;
+  }
+}
+
+/** Decode the ASCII-hex output of `decompressGFA` into a packed byte array
+ *  so all three GF code paths converge on the same `Uint8Array` shape.
+ *  Indexed access + nibble shift instead of `parseInt(slice)` because the
+ *  per-byte slice/parseInt pair is the dominant cost on multi-KB bitmaps. */
+function gfaHexToBytes(hex: string): Uint8Array {
+  const out = new Uint8Array(hex.length >> 1);
+  for (let i = 0; i < out.length; i++) {
+    const hi = parseInt(hex[i * 2] ?? "0", 16);
+    const lo = parseInt(hex[i * 2 + 1] ?? "0", 16);
+    out[i] = (hi << 4) | lo;
+  }
+  return out;
+}
+
+interface GfPayloadDecoded {
+  data: Uint8Array;
+  crcOk: boolean;
+}
+
+/**
+ * Normalise a `^GF{A|B|C}` payload to packed bitmap bytes. Hides the
+ * format / wrapper / compression dispatch from the command handler so
+ * the latter can stay focused on positioning and pixel painting.
+ *
+ *  - `:B64:`/`:Z64:` wrapper → base64-decode (then zlib-inflate for Z64)
+ *  - `format=A` without wrapper → existing RLE-hex path → bytes
+ *  - `format=B`/`C` without wrapper → null (raw binary can't survive the
+ *    text-based ZPL channel and the parser never sees intact bytes anyway)
+ */
+export function gfPayloadToBytes(
+  rawData: string,
+  format: "A" | "B" | "C",
+  bytesPerRow: number,
+): GfPayloadDecoded | null {
+  const wrapper = parseGfWrapper(rawData);
+  if (wrapper) {
+    const bytes =
+      wrapper.kind === "z64" ? tryInflateZlib(wrapper.bytes) : wrapper.bytes;
+    if (!bytes) return null;
+    return { data: bytes, crcOk: wrapper.crcOk };
+  }
+  if (format === "A") {
+    return { data: gfaHexToBytes(decompressGFA(rawData, bytesPerRow)), crcOk: true };
+  }
+  return null;
+}
+
+const HEX_RE = /[0-9A-Fa-f]/;
+const isHex = (ch: string) => HEX_RE.test(ch);
+const isCompressChar = (ch: string) =>
+  (ch >= "G" && ch <= "Y") || (ch >= "g" && ch <= "z");
+const repeatCount = (ch: string): number => {
+  if (ch >= "G" && ch <= "Y") return ch.charCodeAt(0) - 70; // G=1 .. Y=19
+  if (ch >= "g" && ch <= "z") return (ch.charCodeAt(0) - 102) * 20; // g=20 .. z=400
+  return 0;
+};
+
+/**
+ * Decompress ZPL Alternative Data Compression used in ^GFA fields.
+ *
+ * Compression characters:
+ *   G–Y (uppercase) → repeat next hex digit 1–19 times
+ *   g–z (lowercase) → repeat next hex digit 20–400 times (multiples of 20)
+ *   Combinable: e.g. hI0 = (40+3) × '0' = 43 zeros
+ *   ,  → fill remainder of current row with '0'
+ *   !  → fill remainder of current row with 'F'
+ *   :  → repeat previous row
+ */
+function decompressGFA(data: string, bytesPerRow: number): string {
+  const nibblesPerRow = bytesPerRow * 2;
+  const rows: string[] = [];
+  let currentRow = "";
+  let i = 0;
+
+  const pushRow = () => {
+    rows.push(currentRow.slice(0, nibblesPerRow).padEnd(nibblesPerRow, "0"));
+    currentRow = "";
+  };
+
+  while (i < data.length) {
+    const ch = data[i] ?? "";
+
+    if (ch === ",") {
+      pushRow();
+      i++;
+    } else if (ch === "!") {
+      currentRow = currentRow.padEnd(nibblesPerRow, "F");
+      rows.push(currentRow.slice(0, nibblesPerRow));
+      currentRow = "";
+      i++;
+    } else if (ch === ":") {
+      rows.push(
+        rows.length > 0
+          ? (rows[rows.length - 1] ?? "0".repeat(nibblesPerRow))
+          : "0".repeat(nibblesPerRow),
+      );
+      i++;
+    } else if (isCompressChar(ch)) {
+      let count = repeatCount(ch);
+      i++;
+      while (i < data.length && isCompressChar(data[i] ?? "")) {
+        count += repeatCount(data[i] ?? "");
+        i++;
+      }
+      const nextCh = data[i] ?? "";
+      if (i < data.length && isHex(nextCh)) {
+        currentRow += nextCh.repeat(count);
+        i++;
+      }
+    } else if (isHex(ch)) {
+      currentRow += ch;
+      i++;
+    } else {
+      i++;
+    }
+
+    if (currentRow.length >= nibblesPerRow) {
+      rows.push(currentRow.slice(0, nibblesPerRow));
+      currentRow = currentRow.slice(nibblesPerRow);
+    }
+  }
+
+  if (currentRow.length > 0) {
+    pushRow();
+  }
+
+  return rows.join("");
+}
diff --git a/src/lib/zplParser/decoders/graphic.ts b/src/lib/zplParser/decoders/graphic.ts
new file mode 100644
index 00000000..5cff2bc4
--- /dev/null
+++ b/src/lib/zplParser/decoders/graphic.ts
@@ -0,0 +1,64 @@
+import { putImage } from "../../imageCache";
+import { BITS_PER_BYTE } from "./constants";
+import { gfPayloadToBytes } from "./gfa";
+import type { DecodedGraphic } from "../types";
+
+/**
+ * Decode a GF-shaped payload into an image-cache entry. Shared between
+ * the `^GF` inline path and the `~DY` graphic-upload preamble; both
+ * have the same payload shape and need the same decoded bitmap, canvas
+ * paint, and cache write. Returns `null` when the payload can't be
+ * decoded (caller surfaces as browserLimit).
+ */
+export function decodeGraphicToImage(
+  rawData: string,
+  format: "A" | "B" | "C",
+  bytesPerRow: number,
+  totalBytesHeader: string,
+  dataBytesHeader: string,
+  nameHint: string,
+): DecodedGraphic | null {
+  const decoded = gfPayloadToBytes(rawData, format, bytesPerRow);
+  if (!decoded) return null;
+  const widthDots = bytesPerRow * BITS_PER_BYTE;
+  const heightDots = Math.floor(decoded.data.length / bytesPerRow);
+  if (heightDots <= 0) return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = widthDots;
+  canvas.height = heightDots;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("Could not get 2d context");
+  const imgData = ctx.createImageData(widthDots, heightDots);
+  const pixels = imgData.data;
+  for (let row = 0; row < heightDots; row++) {
+    for (let byteIdx = 0; byteIdx < bytesPerRow; byteIdx++) {
+      const byte = decoded.data[row * bytesPerRow + byteIdx] ?? 0;
+      for (let bit = 0; bit < BITS_PER_BYTE; bit++) {
+        const px = byteIdx * BITS_PER_BYTE + bit;
+        const idx = (row * widthDots + px) * 4;
+        // ZPL ^GF: 1-bit = black (printed), 0-bit = transparent.
+        // ImageData starts zero-filled (rgba(0,0,0,0)) — only the
+        // 1-bit case needs a write.
+        if ((byte & (0x80 >> bit)) !== 0) {
+          pixels[idx + 3] = 255;
+        }
+      }
+    }
+  }
+  ctx.putImageData(imgData, 0, 0);
+  const imageId = crypto.randomUUID();
+  putImage({
+    id: imageId,
+    name: nameHint,
+    dataUrl: canvas.toDataURL("image/png"),
+    width: widthDots,
+    height: heightDots,
+  });
+  return {
+    imageId,
+    widthDots,
+    heightDots,
+    gfaCache: `^GF${format},${totalBytesHeader},${dataBytesHeader},${bytesPerRow},${rawData}`,
+    crcOk: decoded.crcOk,
+  };
+}
diff --git a/src/lib/zplParser/handlers/labelConfig.ts b/src/lib/zplParser/handlers/labelConfig.ts
new file mode 100644
index 00000000..5ad8eb38
--- /dev/null
+++ b/src/lib/zplParser/handlers/labelConfig.ts
@@ -0,0 +1,119 @@
+import type { LabelConfig } from "../../../types/ObjectType";
+import {
+  DARKNESS_INSTANT_RANGE,
+  DARKNESS_PERMANENT_RANGE,
+  MAX_LABEL_LENGTH_RANGE,
+  SPEED_RANGE,
+  isMediaFeedMode,
+  isMediaMode,
+  isMediaTracking,
+  isMediaType,
+  isPrintOrientation,
+} from "../../../types/ObjectType";
+import { parseIntOrUndef } from "../../inputParse";
+import { inRange, int, strParam } from "../helpers";
+import type { Handler } from "../types";
+
+/** ^PQ extended params (pauseCount, replicates) — Zebra spec caps at
+ *  8 digits / 99,999,999 per slot. */
+const PQ_EXT_MAX = 99_999_999;
+
+/** Per-label media + print-quality handlers — every entry mutates
+ *  only the `labelConfig` slice. ^PW / ^LL (dots → mm using `dpmm`),
+ *  ^PQ / ^MM / ^LS / ^PR / ^MD / ^MT / ^MN / ^ML / ^MF / ^XB / ^PO /
+ *  ^PM / ~SD. */
+export function createLabelConfigHandlers(
+  labelConfig: Partial<LabelConfig>,
+  dpmm: number,
+): Record<string, Handler> {
+  return {
+    PW(_, rest) {
+      const dots = int(rest);
+      if (dots > 0) labelConfig.widthMm = Math.round((dots / dpmm) * 10) / 10;
+    },
+    LL(_, rest) {
+      const dots = int(rest);
+      if (dots > 0) labelConfig.heightMm = Math.round((dots / dpmm) * 10) / 10;
+    },
+    PQ(p) {
+      const qty = int(p[0], 0);
+      if (qty > 0) labelConfig.printQuantity = qty;
+      // ^PQ q,p,r,o — preserve extended params when present.
+      if (p.length > 1) {
+        const pause = int(p[1], 0);
+        if (pause >= 0 && pause <= PQ_EXT_MAX) labelConfig.pauseCount = pause;
+      }
+      if (p.length > 2) {
+        const reps = int(p[2], 0);
+        if (reps >= 0 && reps <= PQ_EXT_MAX) labelConfig.replicates = reps;
+      }
+      if (p.length > 3) {
+        const o = (p[3] ?? "").toUpperCase();
+        if (o === "Y" || o === "N") labelConfig.overridePauseCount = o;
+      }
+    },
+    MM(_, rest) {
+      // `.trim()` before `[0]` so a stray leading whitespace in the
+      // input (rare but seen with hand-edited ZPL) does not eat the
+      // mode character. Applies to all single-char enum handlers
+      // below (MT / PO / PM).
+      const mode = (rest.trim()[0] ?? "").toUpperCase();
+      if (isMediaMode(mode)) labelConfig.mediaMode = mode;
+    },
+    LS(_, rest) {
+      const shift = int(rest, 0);
+      if (shift !== 0) labelConfig.labelShift = shift;
+    },
+    PR(p) {
+      const print = inRange(parseIntOrUndef(p[0]), SPEED_RANGE);
+      if (print !== undefined) labelConfig.printSpeed = print;
+      const slew = inRange(parseIntOrUndef(p[1]), SPEED_RANGE);
+      if (slew !== undefined) labelConfig.slewSpeed = slew;
+      const bf = inRange(parseIntOrUndef(p[2]), SPEED_RANGE);
+      if (bf !== undefined) labelConfig.backfeedSpeed = bf;
+    },
+    MD(_, rest) {
+      const v = inRange(parseIntOrUndef(rest), DARKNESS_PERMANENT_RANGE);
+      if (v !== undefined) labelConfig.darkness = v;
+    },
+    MT(_, rest) {
+      const mt = (rest.trim()[0] ?? "").toUpperCase();
+      if (isMediaType(mt)) labelConfig.mediaType = mt;
+    },
+    MN(p) {
+      // ^MNa,b — b is an optional black-mark offset for W/M modes,
+      // which we don't model. Reading p[0] instead of the raw rest
+      // string keeps `^MNY,10` from being mis-read as the single
+      // token "Y,10" and silently dropped.
+      const v = strParam(p[0]);
+      if (isMediaTracking(v)) labelConfig.mediaTracking = v;
+    },
+    ML(p) {
+      const v = inRange(parseIntOrUndef(p[0]), MAX_LABEL_LENGTH_RANGE);
+      if (v !== undefined) labelConfig.maxLabelLength = v;
+    },
+    MF(p) {
+      const p1 = strParam(p[0]);
+      const p2 = strParam(p[1]);
+      if (isMediaFeedMode(p1)) labelConfig.mediaFeedPowerUp = p1;
+      if (isMediaFeedMode(p2)) labelConfig.mediaFeedHeadClose = p2;
+    },
+    XB() {
+      labelConfig.suppressBackfeed = true;
+    },
+    PO(_, rest) {
+      const po = (rest.trim()[0] ?? "").toUpperCase();
+      if (isPrintOrientation(po)) labelConfig.printOrientation = po;
+    },
+    PM(_, rest) {
+      const m = (rest.trim()[0] ?? "").toUpperCase();
+      if (m === "Y" || m === "N") labelConfig.mirror = m;
+    },
+    // ~SD — instant darkness set (00..30). Tilde-prefix; the tokenizer
+    // drops the delimiter, so this is the canonical SD handler.
+    SD(_, rest) {
+      const v = inRange(parseIntOrUndef(rest), DARKNESS_INSTANT_RANGE);
+      if (v !== undefined) labelConfig.instantDarkness = v;
+    },
+  };
+}
diff --git a/src/lib/zplParser/handlers/setupScript.ts b/src/lib/zplParser/handlers/setupScript.ts
new file mode 100644
index 00000000..b7dd9dc5
--- /dev/null
+++ b/src/lib/zplParser/handlers/setupScript.ts
@@ -0,0 +1,112 @@
+import type { PrinterProfile } from "../../../types/PrinterProfile";
+import {
+  CLOCK_TOLERANCE_RANGE,
+  HEAD_TEST_INTERVAL_RANGE,
+  PRINTER_NAME_MAX_LEN,
+  TEAR_OFF_ADJUST_RANGE,
+  isClockFormat,
+  isClockLanguage,
+  isPrinterLocale,
+  isZplMode,
+  setupScriptUnsafeCharRegex,
+} from "../../../types/ObjectType";
+import { parseIntOrUndef } from "../../inputParse";
+import { parseRealtimeClock } from "../../realtimeClock";
+import { inRange, strParam } from "../helpers";
+import type { Handler } from "../types";
+
+/** Handlers for the 10 Setup-Script commands (^JZ, ^JT, ~TA, ^ST,
+ *  ^KD, ^KL, ^SE, ^SZ, ^KN, ^SL). All write to the shared
+ *  `printerProfile` slice — no other parser state is touched, so
+ *  the family takes only that one reference. First handler-family
+ *  extracted under epic #4; same pattern will apply to barcodes /
+ *  graphics / fields / printer-state once `ParserContext` lands. */
+export function createSetupScriptHandlers(
+  printerProfile: Partial<PrinterProfile>,
+): Record<string, Handler> {
+  return {
+    JZ(p) {
+      const v = strParam(p[0]);
+      if (v === "Y" || v === "N") printerProfile.reprintAfterError = v;
+    },
+    JT(p) {
+      const v = inRange(parseIntOrUndef(p[0]), HEAD_TEST_INTERVAL_RANGE);
+      if (v !== undefined) printerProfile.headTestInterval = v;
+    },
+    // ~TA reads p[0] (not the raw rest string) so trailing tokens
+    // from a streamed ZPL chunk (e.g. `~TA10^XA…`) don't leak into
+    // the parsed value.
+    TA(p) {
+      const v = inRange(parseIntOrUndef(p[0]), TEAR_OFF_ADJUST_RANGE);
+      if (v !== undefined) printerProfile.tearOffAdjust = v;
+    },
+    // ^ST MM,DD,YYYY,HH,MM,SS — set real-time clock. Delegates shape +
+    // range validation to the shared `realtimeClock` helper so parser
+    // and generator cannot drift on round-trip.
+    ST(p) {
+      const iso = parseRealtimeClock(p);
+      if (iso !== null) printerProfile.setRealtimeClock = iso;
+    },
+    // ^KD: reads only the first char of `rest`; matches the parser's
+    // lenient first-char approach (PO / PM / MT do the same).
+    KD(_, rest) {
+      const v = rest.trim()[0] ?? "";
+      if (isClockFormat(v)) printerProfile.clockFormat = v;
+    },
+    KL(_, rest) {
+      const v = rest.trim().toUpperCase();
+      if (isPrinterLocale(v)) printerProfile.printerLocale = v;
+    },
+    // ^SE: free-string path; dangerous-char check mirrors the schema
+    // regex so an imported ZPL cannot smuggle ^/~/newline into the
+    // path and re-emit as an injected command.
+    SE(_, rest) {
+      const v = rest.trim();
+      if (v && !setupScriptUnsafeCharRegex.test(v)) printerProfile.encodingTable = v;
+    },
+    SZ(_, rest) {
+      const v = rest.trim()[0] ?? "";
+      if (isZplMode(v)) printerProfile.zplMode = v;
+    },
+    // ^KN <name>,<description>. Both parts free strings; the injection
+    // guard mirrors the schema. Name length cap stays per spec.
+    KN(p) {
+      const name = (p[0] ?? "").trim();
+      if (!name || name.length > PRINTER_NAME_MAX_LEN) return;
+      if (setupScriptUnsafeCharRegex.test(name)) return;
+      printerProfile.printerName = name;
+      const desc = (p[1] ?? "").trim();
+      if (desc && !setupScriptUnsafeCharRegex.test(desc)) {
+        printerProfile.printerDescription = desc;
+      }
+    },
+    // ^SL `a`,`b` — Set Mode and Language for ^FC clock fields.
+    // `a` is tri-shape: 'S' / 'T' / numeric 1..999 (TOL with
+    // tolerance). Parser fans the wire value out into clockMode +
+    // clockTolerance per schema's cross-field rule.
+    SL(p) {
+      const a = strParam(p[0]);
+      if (a === "S" || a === "T") {
+        printerProfile.clockMode = a;
+        // Clear stale tolerance from a previous ^SL parse — schema
+        // forbids `tolerance && mode !== 'TOL'`, and the parser
+        // writes raw values without re-running the schema. `delete`
+        // rather than `= undefined` so the returned ParsedZPL doesn't
+        // carry a present-with-undefined key that would leak across
+        // the import-service fold as a misleading "clear" signal.
+        delete printerProfile.clockTolerance;
+      } else {
+        const tol = inRange(parseIntOrUndef(a), CLOCK_TOLERANCE_RANGE);
+        if (tol !== undefined) {
+          printerProfile.clockMode = "TOL";
+          printerProfile.clockTolerance = tol;
+        }
+      }
+      // Language only when the mode parse landed — orphan language
+      // would be write-only state.
+      if (printerProfile.clockMode === undefined) return;
+      const b = strParam(p[1]);
+      if (isClockLanguage(b)) printerProfile.clockLanguage = b;
+    },
+  };
+}
diff --git a/src/lib/zplParser/handlers/unsupported.ts b/src/lib/zplParser/handlers/unsupported.ts
new file mode 100644
index 00000000..1164f892
--- /dev/null
+++ b/src/lib/zplParser/handlers/unsupported.ts
@@ -0,0 +1,48 @@
+import type { Handler } from "../types";
+
+/** Handlers for commands the parser intentionally ignores or surfaces
+ *  as "needs printer hardware".
+ *
+ *  - **noops** (FV, FM, FP, JA, JM, JC, JD, JE, JI, JR, JS, JU, PP):
+ *    parsed and dropped. They have no design impact in a browser-only
+ *    editor; consuming them keeps the dispatch map exhaustive so the
+ *    final "unknown command" fallback doesn't fire.
+ *  - **browser-limit** (FL, HT, LF, IM, ~DG): commands that need
+ *    printer-resident storage / hardware. Recorded into the
+ *    `browserLimit` finding bucket so the import report can surface
+ *    them as "not loaded but intentionally skipped". */
+export function createUnsupportedHandlers(
+  { skipped, browserLimit }: { skipped: string[]; browserLimit: string[] },
+): Record<string, Handler> {
+  const noop: Handler = () => void 0;
+  const mkBrowserLimit =
+    (prefix: string, delimiter = "^"): Handler =>
+    (_, rest) => {
+      const tok = `${delimiter}${prefix}${rest}`;
+      skipped.push(tok);
+      browserLimit.push(tok);
+    };
+
+  return {
+    // Noops — present in stream, no design impact.
+    FV: noop,
+    FM: noop,
+    FP: noop,
+    JA: noop,
+    JM: noop,
+    JC: noop,
+    JD: noop,
+    JE: noop,
+    JI: noop,
+    JR: noop,
+    JS: noop,
+    JU: noop,
+    PP: noop,
+    // Browser-limit factories — surface as "not loaded" findings.
+    FL: mkBrowserLimit("FL"),
+    HT: mkBrowserLimit("HT"),
+    LF: mkBrowserLimit("LF"),
+    IM: mkBrowserLimit("IM"),
+    DG: mkBrowserLimit("DG", "~"),
+  };
+}
diff --git a/src/lib/zplParser/helpers.ts b/src/lib/zplParser/helpers.ts
new file mode 100644
index 00000000..db5cde66
--- /dev/null
+++ b/src/lib/zplParser/helpers.ts
@@ -0,0 +1,117 @@
+import type { LabelObject } from "../../types/Group";
+
+// ZPL commands start with ^ or ~ followed by 2 characters
+export function tokenize(zpl: string): { cmd: string; rest: string }[] {
+  const tokens: { cmd: string; rest: string }[] = [];
+  // Split on both ^ and ~ delimiters, preserving the delimiter type.
+  const parts = zpl.split(/(?=[\^~])/);
+  for (const part of parts) {
+    if (part.length < 3) continue;
+    const delimiter = part[0];
+    if (delimiter !== "^" && delimiter !== "~") continue;
+    const cmd = part.slice(1, 3).toUpperCase();
+    const rest = part.slice(3);
+    tokens.push({ cmd, rest });
+  }
+  return tokens;
+}
+
+export function int(s: string | undefined, fallback = 0): number {
+  const n = Number.parseInt(s ?? "", 10);
+  return Number.isNaN(n) ? fallback : n;
+}
+
+/** Returns the value when in range, undefined otherwise — matches the
+ *  parser's "silently drop invalid params" contract while removing the
+ *  repetitive `>= R.min && <= R.max` shape from each ranged handler. */
+export function inRange(v: number | undefined, r: { min: number; max: number }): number | undefined {
+  return v !== undefined && v >= r.min && v <= r.max ? v : undefined;
+}
+
+/** Trims surrounding whitespace (tokenizer keeps trailing `\n` etc. on
+ *  the last positional) and upper-cases for case-insensitive enum
+ *  matches. */
+export function strParam(s: string | undefined): string {
+  return (s ?? "").trim().toUpperCase();
+}
+
+export function makeObj(
+  type: string,
+  x: number,
+  y: number,
+  props: unknown,
+  positionType?: "FO" | "FT",
+  comment?: string,
+): LabelObject {
+  return {
+    id: crypto.randomUUID(),
+    type,
+    x,
+    y,
+    rotation: 0,
+    positionType,
+    comment,
+    props,
+  } as unknown as LabelObject;
+}
+
+/** Derive a Variable name from a `^FX` comment that landed just before
+ *  the `^FN`. Strips well-known prefixes (`Field:`, `Variable:`, `Var:`)
+ *  so "Field: Customer Name" becomes `Customer_Name`. Returns null when
+ *  the comment is missing or sanitises to empty. */
+export function variableNameFromComment(comment: string | undefined): string | null {
+  if (!comment) return null;
+  const cleaned = comment
+    .replace(/^\s*(field|variable|var)\s*[:-]\s*/i, "")
+    .trim()
+    .replace(/\s+/g, "_");
+  return cleaned === "" ? null : cleaned;
+}
+
+/**
+ * Map a ^CI N parameter to a TextDecoder label. ^CI28 = UTF-8;
+ * ^CI27 = Windows-1252; legacy ^CI0..13 are 7-bit-ASCII-compatible
+ * code-page variants for which Windows-1252 is a safe superset for `^FH`
+ * decoding. Unsupported encodings fall back to UTF-8 with the command
+ * surfaced via importReport.partial.
+ */
+export function ciToEncoding(n: number): { label: string; supported: boolean } {
+  if (n === 28) return { label: "utf-8", supported: true };
+  if (n === 27) return { label: "windows-1252", supported: true };
+  if (n >= 0 && n <= 13) return { label: "windows-1252", supported: true };
+  return { label: "utf-8", supported: false };
+}
+
+const decoderCache = new Map<string, TextDecoder>();
+export function getDecoder(label: string): TextDecoder {
+  let dec = decoderCache.get(label);
+  if (!dec) {
+    dec = new TextDecoder(label);
+    decoderCache.set(label, dec);
+  }
+  return dec;
+}
+
+/**
+ * Decode ^FH hex escapes: replaces runs of {delimiter}XX with the string
+ * for the byte sequence under the active ^CI encoding. A single non-ASCII
+ * glyph may span multiple pairs (e.g. `_C3_A4` → `ä` under UTF-8), so
+ * contiguous pairs collect into a Uint8Array for one TextDecoder pass.
+ * Invalid byte sequences become U+FFFD.
+ */
+export function decodeFH(
+  text: string,
+  delimiter: string,
+  decoder: TextDecoder,
+): string {
+  const escaped = delimiter.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const runRe = new RegExp(`(?:${escaped}[0-9A-Fa-f]{2})+`, "g");
+  const stride = delimiter.length + 2;
+  return text.replace(runRe, (run) => {
+    const bytes = new Uint8Array(run.length / stride);
+    for (let i = 0, b = 0; i < run.length; i += stride, b++) {
+      bytes[b] = parseInt(run.slice(i + delimiter.length, i + stride), 16);
+    }
+    return decoder.decode(bytes);
+  });
+}
diff --git a/src/lib/zplParser/types.ts b/src/lib/zplParser/types.ts
new file mode 100644
index 00000000..c27f1181
--- /dev/null
+++ b/src/lib/zplParser/types.ts
@@ -0,0 +1,67 @@
+import type { LabelConfig } from "../../types/ObjectType";
+import type { LabelObject } from "../../types/Group";
+import type { Variable } from "../../types/Variable";
+import type { PrinterProfile } from "../../types/PrinterProfile";
+
+export type ImportFindingKind = "partial" | "browserLimit" | "unknown";
+
+/**
+ * One import finding. Created per-occurrence so each entry can be navigated
+ * to its source page in the UI; cross-block dedup happens (if at all) in the
+ * service layer that merges per-page parser runs.
+ */
+export interface ImportFinding {
+  kind: ImportFindingKind;
+  /** Command token. For 'partial' the bare code (e.g. "^A@"); for
+   *  'browserLimit' / 'unknown' the full token including parameters
+   *  (e.g. "^IM,R:LOGO.GRF"). */
+  command: string;
+  /** Page index this finding originated from. The parser doesn't know about
+   *  pages and emits 0; `zplImportService` overwrites it when it merges the
+   *  per-block parser results into a multi-page report. */
+  pageIndex: number;
+}
+
+export interface ImportReport {
+  findings: ImportFinding[];
+  /** Commands imported with known loss. Deduplicated by command code. */
+  partial: string[];
+  /** Commands skipped because they require printer hardware or file storage. */
+  browserLimit: string[];
+  /** Commands not recognised at all. */
+  unknown: string[];
+}
+
+export interface ParsedZPL {
+  labelConfig: Partial<LabelConfig>;
+  /** EEPROM-persistent printer-state extracted from any Setup-Script
+   *  commands in the stream (^JZ, ^JT, ~TA, ^ST, ^KD, ^SL, ^KL, ^SE,
+   *  ^SZ, ^KN). Caller decides whether to merge into the active profile. */
+  printerProfile: Partial<PrinterProfile>;
+  objects: LabelObject[];
+  /** Template variables reconstructed from `^FN` slots. */
+  variables: Variable[];
+  /** Commands not fully imported (browserLimit + unknown). Prefer
+   *  importReport for categorised access. */
+  skipped: string[];
+  importReport: ImportReport;
+}
+
+export type Handler = (p: string[], rest: string) => void;
+
+/** Result of decoding any GF-shaped graphic into an image-cache entry. */
+export interface DecodedGraphic {
+  imageId: string;
+  widthDots: number;
+  heightDots: number;
+  /** Verbatim `^GF{format},total,data,bpr,DATA` reconstruction kept on
+   *  the image so round-trip emit can splice the same byte stream back
+   *  into either `^GF` (inline) or `~DY` (preamble) without re-encoding. */
+  gfaCache: string;
+  crcOk: boolean;
+}
+
+/** Entry in the `~DY → ^XG` lookup map: a graphic uploaded earlier in the
+ *  stream. Structurally a `DecodedGraphic` without the per-decode CRC flag —
+ *  that lives on the partialCmds set instead of on every map entry. */
+export type UploadedGraphic = Omit<DecodedGraphic, "crcOk">;