From cd23fce9b22440e88a1d0a7af7b0a778ceb37dd8 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:11:39 +0200
Subject: [PATCH 01/14] feat: persist per-printer label settings (tape size,
 colors)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Remember the tape size and foreground/background colors loaded in each
printer across visits, so they aren't re-selected every page load —
especially painful in kiosk / shared-tablet setups (issue #20).

Storage reuses the existing state file (LABELLE_STATE_FILE), but the
prior usb_power saver did an atomic *full-file* overwrite, which would
clobber a second writer's keys. Introduce server/state_store.py: the
single owner of that file, doing atomic read-modify-write of the whole
document under a shared lock so independent features each persist their
own slice safely. usb_power now routes through it (same on-disk shape
and path arg; ~20 fewer lines; all its tests still pass).

- server/printer_settings.py: get/save the persisted subset (tapeSizeMm,
  foregroundColor, backgroundColor) keyed by PrinterInfo.id under a
  "printers" namespace, validated server-side.
- API: GET/PUT /api/printers/<path:printer_id>/settings (ids carry
  spaces/colons, taken as a path segment).
- Client: usePrinterSettings applies a printer's saved subset on
  selection and writes the full subset back on change (apply and save
  are separated so they can't loop). effectivePrinterId falls back to
  the sole connected printer on Auto-select, so single-printer setups
  persist even though the selector is hidden.

Margins/justify/cutMark are deliberately out of scope (label
preferences, not physical printer state). v2 follow-ups (aliases,
presets, remember-last) extend this same per-printer map; the runtime
capability/status cluster is tracked in #38.

Tests: backend 247 pass, frontend 69 pass. Version 1.7.0 -> 1.8.0 (MINOR).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md                                  |  1 +
 client/src/components/SettingsBar.test.tsx | 67 ++++++++++++++++
 client/src/components/SettingsBar.tsx      | 40 ++++++----
 client/src/lib/api.test.ts                 | 63 +++++++++++++++
 client/src/lib/api.ts                      | 30 +++++++
 client/src/lib/printerSettings.test.ts     | 52 ++++++++++++
 client/src/lib/printerSettings.ts          | 41 ++++++++++
 client/src/state/usePrinterSettings.ts     | 56 +++++++++++++
 client/src/types/label.ts                  |  8 ++
 docs/ARCHITECTURE.md                       | 25 +++++-
 package.json                               |  2 +-
 server/app.py                              | 19 +++++
 server/printer_settings.py                 | 67 ++++++++++++++++
 server/state_store.py                      | 83 +++++++++++++++++++
 server/tests/test_app.py                   | 61 ++++++++++++++
 server/tests/test_printer_settings.py      | 93 ++++++++++++++++++++++
 server/tests/test_smoke.py                 |  2 +
 server/tests/test_state_store.py           | 88 ++++++++++++++++++++
 server/tests/test_usb_power.py             |  7 +-
 server/usb_power.py                        | 49 +++---------
 20 files changed, 796 insertions(+), 58 deletions(-)
 create mode 100644 client/src/lib/printerSettings.test.ts
 create mode 100644 client/src/lib/printerSettings.ts
 create mode 100644 client/src/state/usePrinterSettings.ts
 create mode 100644 server/printer_settings.py
 create mode 100644 server/state_store.py
 create mode 100644 server/tests/test_printer_settings.py
 create mode 100644 server/tests/test_state_store.py

diff --git a/README.md b/README.md
index 45dccd4..31e6fd0 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,7 @@ You can fight against AI usage or learn to embrace it as a new way of working. I
 - **Label settings** -- tape size, margins, minimum length, justify, foreground/background colors
 - **Per-widget font styles** -- each text widget can have its own font style, scale, frame, and alignment
 - **Multi-printer support** -- automatically detects all connected DYMO printers; select specific printer when multiple are available
+- **Per-printer settings** -- the tape size and colors loaded in each printer are remembered across visits, so you don't re-pick them every time (handy for kiosk / shared-tablet setups)
 - **Virtual printers** -- configure virtual printers that save labels as PNG images, JSON data, or both (great for testing, archiving, and development)
 - **Batch print** -- print multiple labels with variable content using `{{varname}}` placeholders, with a table to fill in values per row, configurable copies and pause time, SSE progress streaming, and cancellation support
 - **Cut mark** -- optional dotted column painted into the trailing margin between batch labels so you can tear/cut between them; uses the existing inter-label gap, no extra tape
diff --git a/client/src/components/SettingsBar.test.tsx b/client/src/components/SettingsBar.test.tsx
index 38d1436..d3e2433 100644
--- a/client/src/components/SettingsBar.test.tsx
+++ b/client/src/components/SettingsBar.test.tsx
@@ -15,9 +15,13 @@ vi.mock("../lib/api", () => ({
   }),
   powerOn: vi.fn(),
   powerOff: vi.fn(),
+  // usePrinterSettings (issue #20) runs inside SettingsBar.
+  fetchPrinterSettings: vi.fn().mockResolvedValue({}),
+  savePrinterSettings: vi.fn().mockResolvedValue(undefined),
 }));
 
 import { SettingsBar } from "./SettingsBar";
+import { fetchPrinterSettings, savePrinterSettings } from "../lib/api";
 import { useLabelStore } from "../state/useLabelStore";
 import type { PrinterInfo } from "../types/label";
 
@@ -31,6 +35,7 @@ afterEach(() => {
 });
 
 beforeEach(() => {
+  vi.clearAllMocks();
   // Reset store to defaults
   useLabelStore.setState({
     availablePrinters: [],
@@ -124,6 +129,68 @@ describe("SettingsBar printer selector", () => {
   });
 });
 
+describe("SettingsBar per-printer settings persistence (issue #20)", () => {
+  it("applies saved settings when a printer is selected", async () => {
+    vi.mocked(fetchPrinterSettings).mockResolvedValueOnce({ tapeSizeMm: 6 });
+    useLabelStore.setState({
+      availablePrinters: twoPrinters,
+      settings: { ...useLabelStore.getState().settings, printerId: "usb:1" },
+    });
+    render(<SettingsBar />);
+
+    await waitFor(() => {
+      expect(useLabelStore.getState().settings.tapeSizeMm).toBe(6);
+    });
+    expect(fetchPrinterSettings).toHaveBeenCalledWith("usb:1");
+  });
+
+  it("persists the full subset when the tape size changes", async () => {
+    useLabelStore.setState({
+      availablePrinters: twoPrinters,
+      settings: { ...useLabelStore.getState().settings, printerId: "usb:1" },
+    });
+    render(<SettingsBar />);
+    screen.getByText("Settings").click();
+
+    const tapeSelect = screen.getByDisplayValue("12");
+    await userEvent.selectOptions(tapeSelect, "19");
+
+    expect(savePrinterSettings).toHaveBeenCalledWith("usb:1", {
+      tapeSizeMm: 19,
+      foregroundColor: "black",
+      backgroundColor: "white",
+    });
+  });
+
+  it("uses the single connected printer even on Auto-select", async () => {
+    useLabelStore.setState({
+      availablePrinters: [twoPrinters[0]!],
+      settings: { ...useLabelStore.getState().settings, printerId: undefined },
+    });
+    render(<SettingsBar />);
+
+    await waitFor(() => {
+      expect(fetchPrinterSettings).toHaveBeenCalledWith("usb:1");
+    });
+  });
+
+  it("does not persist on Auto-select with multiple printers", async () => {
+    useLabelStore.setState({
+      availablePrinters: twoPrinters,
+      settings: { ...useLabelStore.getState().settings, printerId: undefined },
+    });
+    render(<SettingsBar />);
+    screen.getByText("Settings").click();
+
+    const tapeSelect = screen.getByDisplayValue("12");
+    await userEvent.selectOptions(tapeSelect, "19");
+
+    expect(savePrinterSettings).not.toHaveBeenCalled();
+    // Ambiguous which printer the server picks, so we don't read either.
+    expect(fetchPrinterSettings).not.toHaveBeenCalled();
+  });
+});
+
 describe("SettingsBar power toggle visibility", () => {
   it("shows the power toggle when a real USB printer is selected", async () => {
     useLabelStore.setState({
diff --git a/client/src/components/SettingsBar.tsx b/client/src/components/SettingsBar.tsx
index b4a16c7..1f548a2 100644
--- a/client/src/components/SettingsBar.tsx
+++ b/client/src/components/SettingsBar.tsx
@@ -1,4 +1,5 @@
 import { useLabelStore } from "../state/useLabelStore";
+import { usePrinterSettings } from "../state/usePrinterSettings";
 import { TAPE_SIZES, LABEL_COLORS } from "../lib/constants";
 import { fetchPrinters } from "../lib/api";
 import type { TapeSize, Alignment, LabelColor } from "../types/label";
@@ -12,6 +13,10 @@ export function SettingsBar() {
   const setAvailablePrinters = useLabelStore((s) => s.setAvailablePrinters);
   const [isRefreshing, setIsRefreshing] = useState(false);
 
+  // Per-printer settings persistence (issue #20): applies saved tape/color
+  // for the selected printer, and `persist` saves user changes to those.
+  const { persist } = usePrinterSettings();
+
   const handleRefreshPrinters = async () => {
     setIsRefreshing(true);
     try {
@@ -24,13 +29,10 @@ export function SettingsBar() {
     }
   };
 
-  // Only show printer selector if multiple printers are detected
-  // TODO: Future improvements for multi-printer UI:
-  // - Show printer status indicators (online/offline)
-  // - Display tape type/color/width for each printer
-  // - Allow users to set friendly aliases for printers
-  // - Remember last selected printer per user
-  // - Support printer-specific preset configurations
+  // Only show printer selector if multiple printers are detected.
+  // Tape size + colors now persist per printer (issue #20); the rest of
+  // the multi-printer UI cluster (status indicators, capability-aware tape
+  // display, aliases, presets) is tracked in #38.
   const showPrinterSelector = availablePrinters.length > 1;
 
   // Hide the USB power toggle when a virtual printer is selected —
@@ -83,9 +85,11 @@ export function SettingsBar() {
         <select
           className="input w-20"
           value={settings.tapeSizeMm}
-          onChange={(e) =>
-            update({ tapeSizeMm: Number(e.target.value) as TapeSize })
-          }
+          onChange={(e) => {
+            const tapeSizeMm = Number(e.target.value) as TapeSize;
+            update({ tapeSizeMm });
+            persist({ tapeSizeMm });
+          }}
         >
           {TAPE_SIZES.map((s) => (
             <option key={s} value={s}>
@@ -133,9 +137,11 @@ export function SettingsBar() {
         <select
           className="input w-24"
           value={settings.foregroundColor}
-          onChange={(e) =>
-            update({ foregroundColor: e.target.value as LabelColor })
-          }
+          onChange={(e) => {
+            const foregroundColor = e.target.value as LabelColor;
+            update({ foregroundColor });
+            persist({ foregroundColor });
+          }}
         >
           {LABEL_COLORS.map((c) => (
             <option key={c} value={c}>
@@ -149,9 +155,11 @@ export function SettingsBar() {
         <select
           className="input w-24"
           value={settings.backgroundColor}
-          onChange={(e) =>
-            update({ backgroundColor: e.target.value as LabelColor })
-          }
+          onChange={(e) => {
+            const backgroundColor = e.target.value as LabelColor;
+            update({ backgroundColor });
+            persist({ backgroundColor });
+          }}
         >
           {LABEL_COLORS.map((c) => (
             <option key={c} value={c}>
diff --git a/client/src/lib/api.test.ts b/client/src/lib/api.test.ts
index a7c5094..04b9150 100644
--- a/client/src/lib/api.test.ts
+++ b/client/src/lib/api.test.ts
@@ -7,6 +7,8 @@ import {
   printLabel,
   fetchServerPreview,
   uploadImage,
+  fetchPrinterSettings,
+  savePrinterSettings,
 } from "./api";
 import type { LabelWidget, LabelSettings } from "../types/label";
 
@@ -255,3 +257,64 @@ describe("uploadImage", () => {
     await expect(uploadImage(file)).rejects.toThrow("No file provided");
   });
 });
+
+describe("fetchPrinterSettings", () => {
+  it("GETs the URL-encoded printer id and returns the settings", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ settings: { tapeSizeMm: 19 } }),
+    });
+
+    const result = await fetchPrinterSettings("Bus 001 Device 005: ID 0922:1234");
+
+    expect(result).toEqual({ tapeSizeMm: 19 });
+    expect(mockFetch).toHaveBeenCalledWith(
+      "/api/printers/Bus%20001%20Device%20005%3A%20ID%200922%3A1234/settings",
+    );
+  });
+
+  it("returns {} when the server reports no saved settings", async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      json: async () => ({ settings: {} }),
+    });
+    expect(await fetchPrinterSettings("usb:1")).toEqual({});
+  });
+
+  it("throws on a non-ok response", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false });
+    await expect(fetchPrinterSettings("usb:1")).rejects.toThrow();
+  });
+});
+
+describe("savePrinterSettings", () => {
+  it("PUTs the settings as JSON to the encoded id", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: true, json: async () => ({}) });
+
+    await savePrinterSettings("virtual:Office", {
+      tapeSizeMm: 12,
+      foregroundColor: "black",
+      backgroundColor: "white",
+    });
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      "/api/printers/virtual%3AOffice/settings",
+      {
+        method: "PUT",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          tapeSizeMm: 12,
+          foregroundColor: "black",
+          backgroundColor: "white",
+        }),
+      },
+    );
+  });
+
+  it("throws on a non-ok response", async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false });
+    await expect(
+      savePrinterSettings("usb:1", { tapeSizeMm: 12 }),
+    ).rejects.toThrow();
+  });
+});
diff --git a/client/src/lib/api.ts b/client/src/lib/api.ts
index f220c99..82e79b7 100644
--- a/client/src/lib/api.ts
+++ b/client/src/lib/api.ts
@@ -3,6 +3,7 @@ import type {
   LabelSettings,
   PrinterInfo,
   PowerStatus,
+  PersistedPrinterSettings,
 } from "../types/label";
 
 interface PrintResponse {
@@ -189,3 +190,32 @@ export async function powerOff(): Promise<PowerStatus> {
   const res = await fetch("/api/power/off", { method: "POST" });
   return _readPowerResponse(res);
 }
+
+// Per-printer label settings (issue #20): the long-lived "what tape/colors
+// are loaded" subset, persisted server-side keyed by printer id. Printer
+// ids contain spaces and colons, so encode the whole segment.
+export async function fetchPrinterSettings(
+  printerId: string,
+): Promise<PersistedPrinterSettings> {
+  const res = await fetch(
+    `/api/printers/${encodeURIComponent(printerId)}/settings`,
+  );
+  if (!res.ok) throw new Error("Failed to fetch printer settings");
+  const data = (await res.json()) as { settings?: PersistedPrinterSettings };
+  return data.settings ?? {};
+}
+
+export async function savePrinterSettings(
+  printerId: string,
+  settings: PersistedPrinterSettings,
+): Promise<void> {
+  const res = await fetch(
+    `/api/printers/${encodeURIComponent(printerId)}/settings`,
+    {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(settings),
+    },
+  );
+  if (!res.ok) throw new Error("Failed to save printer settings");
+}
diff --git a/client/src/lib/printerSettings.test.ts b/client/src/lib/printerSettings.test.ts
new file mode 100644
index 0000000..e1479e2
--- /dev/null
+++ b/client/src/lib/printerSettings.test.ts
@@ -0,0 +1,52 @@
+import { describe, it, expect } from "vitest";
+import { effectivePrinterId, pickPersisted } from "./printerSettings";
+import type { LabelSettings, PrinterInfo } from "../types/label";
+
+const printer = (id: string): PrinterInfo => ({
+  id,
+  name: id,
+  vendorProductId: "0922:1002",
+});
+
+describe("effectivePrinterId", () => {
+  it("returns the explicit selection when set", () => {
+    expect(effectivePrinterId("usb:2", [printer("usb:1"), printer("usb:2")])).toBe(
+      "usb:2",
+    );
+  });
+
+  it("falls back to the sole printer on Auto-select", () => {
+    expect(effectivePrinterId(undefined, [printer("usb:1")])).toBe("usb:1");
+  });
+
+  it("is undefined on Auto-select with multiple printers", () => {
+    expect(
+      effectivePrinterId(undefined, [printer("usb:1"), printer("usb:2")]),
+    ).toBeUndefined();
+  });
+
+  it("is undefined on Auto-select with no printers", () => {
+    expect(effectivePrinterId(undefined, [])).toBeUndefined();
+  });
+});
+
+describe("pickPersisted", () => {
+  it("keeps only the per-printer-persisted keys", () => {
+    const settings: LabelSettings = {
+      tapeSizeMm: 19,
+      marginPx: 56,
+      minLengthMm: 0,
+      justify: "center",
+      foregroundColor: "white",
+      backgroundColor: "blue",
+      showMargins: true,
+      cutMark: true,
+      printerId: "usb:1",
+    };
+    expect(pickPersisted(settings)).toEqual({
+      tapeSizeMm: 19,
+      foregroundColor: "white",
+      backgroundColor: "blue",
+    });
+  });
+});
diff --git a/client/src/lib/printerSettings.ts b/client/src/lib/printerSettings.ts
new file mode 100644
index 0000000..9038c8c
--- /dev/null
+++ b/client/src/lib/printerSettings.ts
@@ -0,0 +1,41 @@
+import type {
+  LabelSettings,
+  PersistedPrinterSettings,
+  PrinterInfo,
+} from "../types/label";
+
+// The settings keys persisted per printer. Single source of truth for
+// pickPersisted; the server validates the same set (printer_settings.py).
+export const PERSISTED_PRINTER_KEYS = [
+  "tapeSizeMm",
+  "foregroundColor",
+  "backgroundColor",
+] as const;
+
+/**
+ * Which printer to persist settings against.
+ *
+ * - An explicit selection always wins.
+ * - With no selection ("Auto-select") but exactly one printer connected,
+ *   that printer is unambiguous, so kiosk/single-printer setups still get
+ *   persistence even though the UI hides the selector.
+ * - With multiple printers and no selection we can't know which one the
+ *   server will auto-pick, so we persist nothing (undefined).
+ */
+export function effectivePrinterId(
+  selectedId: string | undefined,
+  printers: PrinterInfo[],
+): string | undefined {
+  if (selectedId) return selectedId;
+  if (printers.length === 1) return printers[0]!.id;
+  return undefined;
+}
+
+/** Extract just the per-printer-persisted subset from full label settings. */
+export function pickPersisted(settings: LabelSettings): PersistedPrinterSettings {
+  return {
+    tapeSizeMm: settings.tapeSizeMm,
+    foregroundColor: settings.foregroundColor,
+    backgroundColor: settings.backgroundColor,
+  };
+}
diff --git a/client/src/state/usePrinterSettings.ts b/client/src/state/usePrinterSettings.ts
new file mode 100644
index 0000000..ab14b65
--- /dev/null
+++ b/client/src/state/usePrinterSettings.ts
@@ -0,0 +1,56 @@
+import { useEffect } from "react";
+import { useLabelStore } from "./useLabelStore";
+import { fetchPrinterSettings, savePrinterSettings } from "../lib/api";
+import {
+  effectivePrinterId,
+  pickPersisted,
+} from "../lib/printerSettings";
+import type { PersistedPrinterSettings } from "../types/label";
+
+/**
+ * Wires per-printer settings persistence (issue #20) in two directions:
+ *
+ * - **Apply on select:** whenever the effective printer changes, fetch its
+ *   saved subset and apply it to the store.
+ * - **Save on change:** `persist(patch)` writes the full current subset for
+ *   the effective printer. Callers invoke it from user-driven onChange only,
+ *   so applying-from-server never loops back into a save.
+ *
+ * Each save sends the whole subset (not just the changed field) so the
+ * server's wholesale-per-printer write never drops a previously saved value.
+ */
+export function usePrinterSettings(): {
+  persist: (patch: PersistedPrinterSettings) => void;
+} {
+  const settings = useLabelStore((s) => s.settings);
+  const availablePrinters = useLabelStore((s) => s.availablePrinters);
+  const updateSettings = useLabelStore((s) => s.updateSettings);
+
+  const printerId = effectivePrinterId(settings.printerId, availablePrinters);
+
+  useEffect(() => {
+    if (!printerId) return;
+    let cancelled = false;
+    fetchPrinterSettings(printerId)
+      .then((saved) => {
+        if (!cancelled && Object.keys(saved).length > 0) updateSettings(saved);
+      })
+      .catch((error) => {
+        console.error("Failed to load printer settings:", error);
+      });
+    return () => {
+      cancelled = true;
+    };
+  }, [printerId, updateSettings]);
+
+  const persist = (patch: PersistedPrinterSettings) => {
+    if (!printerId) return;
+    savePrinterSettings(printerId, { ...pickPersisted(settings), ...patch }).catch(
+      (error) => {
+        console.error("Failed to save printer settings:", error);
+      },
+    );
+  };
+
+  return { persist };
+}
diff --git a/client/src/types/label.ts b/client/src/types/label.ts
index a6b7b9c..3274ff8 100644
--- a/client/src/types/label.ts
+++ b/client/src/types/label.ts
@@ -107,3 +107,11 @@ export interface LabelSettings {
   cutMark: boolean;
   printerId?: string; // Optional printer ID for multi-printer setups
 }
+
+// The subset of LabelSettings persisted per printer (issue #20): the
+// physical "what tape/colors are loaded" properties. Partial because a
+// printer may only have some of them saved. Kept narrow on purpose —
+// margins/justify/cutMark are label preferences, not printer state.
+export type PersistedPrinterSettings = Partial<
+  Pick<LabelSettings, "tapeSizeMm" | "foregroundColor" | "backgroundColor">
+>;
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 5f32964..fe68ddc 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -141,6 +141,27 @@ The backend supports two types of printers:
 
 **Output Filename Format (virtual printers):** `label_YYYYMMDD_HHMMSS_uuid.png`
 
+### Persistent State (`state_store.py`)
+
+A single JSON file (`LABELLE_STATE_FILE`, default `/app/output/.labelle/state.json`,
+inside the already-mounted output volume) holds the small bits of state that
+must survive container restarts. `state_store.py` owns it and is the only writer:
+every write is an atomic read-modify-write of the whole document under a shared
+lock, so independent features can each persist their slice without clobbering
+the others.
+
+Current slices:
+- **USB power** (`usb_power.py`): top-level `hub`/`port` — the last known
+  controllable port, so power-on still works after the device has been powered
+  off and dropped off the USB tree.
+- **Per-printer settings** (`printer_settings.py`): a `printers` map keyed by
+  `PrinterInfo.id`, storing the long-lived tape size + foreground/background
+  colors loaded in each printer (issue #20). Validated server-side; the client
+  applies a printer's saved subset on selection and writes back on change. The
+  "effective printer" is the explicit selection, or the sole printer when on
+  Auto-select — so single-printer kiosks persist too. v2 follow-ups (aliases,
+  presets, remember-last) are expected to extend this same per-printer map.
+
 ### Request Flow
 
 ```
@@ -343,11 +364,13 @@ Uncomment the output volume mount in `compose.yaml` to access saved labels on th
 TODOs documented in code comments:
 
 **Backend (app.py, label_builder.py):**
-- Per-printer settings persistence (tape size, margins, color)
 - Printer status/health checks (online/offline, tape level)
 - Printer list caching to reduce USB scans
 - Printer capability detection (supported tape sizes, colors)
 
+(Per-printer tape-size/color persistence shipped in v1.8.0 — see "Per-printer
+settings" below. The remaining three are tracked in issue #38.)
+
 **Frontend (SettingsBar.tsx):**
 - Printer status indicators in UI
 - Display tape type/color/width for each printer
diff --git a/package.json b/package.json
index d486818..3cfff0d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "labelle-web",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "private": true,
   "description": "Web interface for labelle DYMO label printers",
   "scripts": {
diff --git a/server/app.py b/server/app.py
index 285adaa..fbfe04b 100644
--- a/server/app.py
+++ b/server/app.py
@@ -47,6 +47,7 @@
 from werkzeug.utils import secure_filename
 
 import power_save
+import printer_settings
 import usb_power
 from label_builder import paint_cut_mark_in_trailing_margin, preview_label, render_payload
 from printer_service import list_printers, print_bitmap, print_label
@@ -210,6 +211,24 @@ def api_printers():
     return jsonify(printers=list_printers())
 
 
+# Per-printer label settings (issue #20). Printer ids contain spaces and
+# colons (e.g. "Bus 001 Device 005: ID 0922:1234", "virtual:Office"), so
+# the client URL-encodes them and we take the whole segment via <path:>.
+@app.route("/api/printers/<path:printer_id>/settings", methods=["GET"])
+def api_get_printer_settings(printer_id):
+    return jsonify(settings=printer_settings.get_settings(printer_id))
+
+
+@app.route("/api/printers/<path:printer_id>/settings", methods=["PUT"])
+def api_put_printer_settings(printer_id):
+    body = request.get_json(silent=True) or {}
+    try:
+        saved = printer_settings.save_settings(printer_id, body)
+    except ValueError as e:
+        return jsonify(status="error", message=str(e)), 400
+    return jsonify(status="success", settings=saved)
+
+
 def _printer_port_or_404():
     port = usb_power.find_or_recall_printer_port()
     if port is None:
diff --git a/server/printer_settings.py b/server/printer_settings.py
new file mode 100644
index 0000000..900a1c0
--- /dev/null
+++ b/server/printer_settings.py
@@ -0,0 +1,67 @@
+"""Per-printer label settings persistence (issue #20).
+
+The physical tape loaded in a printer — its width and colors — is a
+long-lived property of *that printer*, not a per-label choice. We save
+the subset the user picks, keyed by printer id, so it isn't re-selected
+on every visit (especially painful in kiosk / shared-tablet setups).
+
+Keyed by `PrinterInfo.id`: the USB id string for real printers
+(`Bus 001 Device 005: ID 0922:1234`) or `virtual:<name>` for virtual
+ones — both stable across reboots. State rides in the shared state file
+under a "printers" namespace alongside the USB power cache.
+
+Out of scope (see issue #20): batch row data (lives in the label JSON),
+and recovering settings for a disconnected printer (we just keep the
+entry and restore it when the printer reappears).
+
+v2 follow-ups (aliases, remember-last, presets) are expected to extend
+this same per-printer store — keep the shape easy to grow.
+"""
+
+import state_store
+
+# The subset we persist, with their allowed values. Deliberately the
+# "physical printer state" minimum from issue #20 — margin/justify/cutMark
+# are arguably label preferences and are left out until that's decided.
+_VALID_TAPE_SIZES = {6, 9, 12, 19}
+_VALID_COLORS = {"white", "black", "yellow", "blue", "red", "green"}
+
+_PERSISTED_KEYS = ("tapeSizeMm", "foregroundColor", "backgroundColor")
+
+_PRINTERS_KEY = "printers"
+
+
+def _validate(settings: dict) -> None:
+    if not isinstance(settings, dict):
+        raise ValueError("settings must be an object")
+    unknown = set(settings) - set(_PERSISTED_KEYS)
+    if unknown:
+        raise ValueError(f"Unknown printer setting(s): {sorted(unknown)}")
+    if "tapeSizeMm" in settings and settings["tapeSizeMm"] not in _VALID_TAPE_SIZES:
+        raise ValueError(f"Invalid tapeSizeMm: {settings['tapeSizeMm']!r}")
+    for key in ("foregroundColor", "backgroundColor"):
+        if key in settings and settings[key] not in _VALID_COLORS:
+            raise ValueError(f"Invalid {key}: {settings[key]!r}")
+
+
+def get_settings(printer_id: str, path=None) -> dict:
+    """Return the saved subset for a printer, or {} if none saved."""
+    printers = state_store.read_all(path).get(_PRINTERS_KEY, {})
+    entry = printers.get(printer_id)
+    return entry if isinstance(entry, dict) else {}
+
+
+def save_settings(printer_id: str, settings: dict, path=None) -> dict:
+    """Validate and persist the subset for a printer. Returns it.
+
+    The write replaces that printer's entry wholesale (not a deep-merge);
+    the client always sends the full current subset.
+    """
+    if not printer_id:
+        raise ValueError("printer_id must be non-empty")
+    _validate(settings)
+    state_store.update(
+        lambda d: d.setdefault(_PRINTERS_KEY, {}).__setitem__(printer_id, settings),
+        path,
+    )
+    return settings
diff --git a/server/state_store.py b/server/state_store.py
new file mode 100644
index 0000000..68f49ec
--- /dev/null
+++ b/server/state_store.py
@@ -0,0 +1,83 @@
+"""Shared owner of the on-disk JSON state file (LABELLE_STATE_FILE).
+
+Several features persist a little long-lived state across container
+restarts — the USB power feature caches the printer's (hub, port), and
+per-printer label settings live here too (issue #20). They all share one
+file so the standard deployment needs only the single `/app/output`
+volume that's already mounted.
+
+Sharing one file means a writer touching its own slice must not drop
+another feature's slice. So every write is a read-modify-write of the
+whole document under a process-wide lock, and `update()` hands the
+mutator the full dict to edit in place. Writes are atomic-on-POSIX
+(serialize to a sibling `.tmp`, then `os.replace`), so a crash or a
+concurrent writer leaves the file fully old or fully new, never torn.
+
+Best-effort by design: a write failure (read-only fs, missing mount,
+permissions) only loses cross-restart memory, it never breaks runtime.
+"""
+
+import json
+import logging
+import os
+import threading
+from pathlib import Path
+from typing import Callable
+
+logger = logging.getLogger(__name__)
+
+# Default lives inside the Docker output mount, already a persistent
+# volume in the standard deployment — avoids requiring a new mount just
+# for this state. Tests pass an explicit path.
+STATE_FILE = Path(
+    os.environ.get("LABELLE_STATE_FILE", "/app/output/.labelle/state.json")
+)
+
+# Serializes read-modify-write across all callers. waitress serves on
+# multiple threads, and two features writing different slices of the same
+# file would otherwise interleave their read/write and lose one update.
+_lock = threading.Lock()
+
+
+def read_all(path: Path | None = None) -> dict:
+    """Return the whole state document as a dict; {} if absent/corrupt.
+
+    A missing file is the normal first-run state. A corrupt or
+    wrong-shaped file is logged once and treated as empty rather than
+    crashing callers — the worst case is that prior state is forgotten.
+    """
+    if path is None:
+        path = STATE_FILE
+    try:
+        data = json.loads(path.read_text())
+    except FileNotFoundError:
+        return {}
+    except (OSError, json.JSONDecodeError) as e:
+        logger.warning("Could not read state file %s: %s", path, e)
+        return {}
+    if isinstance(data, dict):
+        return data
+    logger.warning("Ignoring state file %s: top level is not an object", path)
+    return {}
+
+
+def update(mutator: Callable[[dict], None], path: Path | None = None) -> dict:
+    """Atomically read-modify-write the state file under the shared lock.
+
+    `mutator` receives the full document and edits it in place. Returns
+    the resulting document. Write failures are swallowed (best-effort);
+    the in-memory result is still returned so callers see their change.
+    """
+    if path is None:
+        path = STATE_FILE
+    with _lock:
+        data = read_all(path)
+        mutator(data)
+        try:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            tmp = path.with_suffix(path.suffix + ".tmp")
+            tmp.write_text(json.dumps(data))
+            tmp.replace(path)
+        except OSError as e:
+            logger.warning("Could not write state file %s: %s", path, e)
+        return data
diff --git a/server/tests/test_app.py b/server/tests/test_app.py
index db1819f..72cf178 100644
--- a/server/tests/test_app.py
+++ b/server/tests/test_app.py
@@ -498,3 +498,64 @@ def test_returns_500_when_print_raises(self, mock_print, client):
 
         assert resp.status_code == 500
         assert "Printer on fire" in resp.get_json()["message"]
+
+
+class TestPrinterSettingsEndpoints:
+    """GET/PUT /api/printers/<id>/settings — per-printer settings (issue #20)."""
+
+    @pytest.fixture
+    def state_file(self, tmp_path, monkeypatch):
+        import state_store
+
+        path = tmp_path / "state.json"
+        monkeypatch.setattr(state_store, "STATE_FILE", path)
+        return path
+
+    def test_get_returns_empty_when_unsaved(self, client, state_file):
+        resp = client.get("/api/printers/virtual:Test_Printer/settings")
+        assert resp.status_code == 200
+        assert resp.get_json() == {"settings": {}}
+
+    def test_put_then_get_round_trips(self, client, state_file):
+        body = {"tapeSizeMm": 19, "foregroundColor": "white", "backgroundColor": "blue"}
+        put = client.put(
+            "/api/printers/virtual:Test_Printer/settings",
+            data=json.dumps(body),
+            content_type="application/json",
+        )
+        assert put.status_code == 200
+        assert put.get_json()["settings"] == body
+
+        got = client.get("/api/printers/virtual:Test_Printer/settings")
+        assert got.get_json() == {"settings": body}
+
+    def test_put_invalid_value_returns_400(self, client, state_file):
+        resp = client.put(
+            "/api/printers/virtual:Test_Printer/settings",
+            data=json.dumps({"tapeSizeMm": 13}),
+            content_type="application/json",
+        )
+        assert resp.status_code == 400
+        assert resp.get_json()["status"] == "error"
+
+    def test_put_unknown_key_returns_400(self, client, state_file):
+        resp = client.put(
+            "/api/printers/virtual:Test_Printer/settings",
+            data=json.dumps({"marginPx": 10}),
+            content_type="application/json",
+        )
+        assert resp.status_code == 400
+
+    def test_ids_with_spaces_and_colons_round_trip(self, client, state_file):
+        # Real USB ids look like "Bus 001 Device 005: ID 0922:1234".
+        from urllib.parse import quote
+
+        printer_id = "Bus 001 Device 005: ID 0922:1234"
+        encoded = quote(printer_id, safe="")
+        client.put(
+            f"/api/printers/{encoded}/settings",
+            data=json.dumps({"tapeSizeMm": 6}),
+            content_type="application/json",
+        )
+        got = client.get(f"/api/printers/{encoded}/settings")
+        assert got.get_json() == {"settings": {"tapeSizeMm": 6}}
diff --git a/server/tests/test_printer_settings.py b/server/tests/test_printer_settings.py
new file mode 100644
index 0000000..1aea9e0
--- /dev/null
+++ b/server/tests/test_printer_settings.py
@@ -0,0 +1,93 @@
+"""Tests for per-printer label settings persistence.
+
+Stores the long-lived "what tape/colors are loaded in this printer"
+subset, keyed by printer id, in the shared state file. See issue #20.
+"""
+
+import pytest
+
+import printer_settings
+import usb_power
+
+
+class TestGet:
+    def test_returns_empty_dict_when_printer_unknown(self, tmp_path):
+        p = tmp_path / "state.json"
+        assert printer_settings.get_settings("Bus 001 Device 005", p) == {}
+
+    def test_round_trips_a_saved_subset(self, tmp_path):
+        p = tmp_path / "state.json"
+        printer_settings.save_settings(
+            "virtual:Office",
+            {"tapeSizeMm": 19, "foregroundColor": "white", "backgroundColor": "blue"},
+            p,
+        )
+        assert printer_settings.get_settings("virtual:Office", p) == {
+            "tapeSizeMm": 19,
+            "foregroundColor": "white",
+            "backgroundColor": "blue",
+        }
+
+    def test_settings_are_isolated_per_printer(self, tmp_path):
+        p = tmp_path / "state.json"
+        printer_settings.save_settings("a", {"tapeSizeMm": 6}, p)
+        printer_settings.save_settings("b", {"tapeSizeMm": 19}, p)
+        assert printer_settings.get_settings("a", p) == {"tapeSizeMm": 6}
+        assert printer_settings.get_settings("b", p) == {"tapeSizeMm": 19}
+
+
+class TestSaveValidation:
+    def test_rejects_unknown_key(self, tmp_path):
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("a", {"marginPx": 10}, p)
+
+    def test_rejects_invalid_tape_size(self, tmp_path):
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("a", {"tapeSizeMm": 13}, p)
+
+    def test_rejects_invalid_color(self, tmp_path):
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("a", {"foregroundColor": "magenta"}, p)
+
+    def test_rejects_empty_printer_id(self, tmp_path):
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("", {"tapeSizeMm": 12}, p)
+
+    def test_rejects_non_dict_body(self, tmp_path):
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("a", ["tapeSizeMm"], p)
+
+    def test_partial_subset_is_allowed(self, tmp_path):
+        """User may have only ever changed the tape size; persist just that."""
+        p = tmp_path / "state.json"
+        printer_settings.save_settings("a", {"tapeSizeMm": 9}, p)
+        assert printer_settings.get_settings("a", p) == {"tapeSizeMm": 9}
+
+    def test_save_replaces_prior_subset(self, tmp_path):
+        p = tmp_path / "state.json"
+        printer_settings.save_settings("a", {"tapeSizeMm": 9}, p)
+        printer_settings.save_settings("a", {"foregroundColor": "red"}, p)
+        # Latest write wins wholesale for that printer; not a deep-merge.
+        assert printer_settings.get_settings("a", p) == {"foregroundColor": "red"}
+
+
+class TestCoexistenceWithUsbPower:
+    def test_saving_settings_preserves_usb_power_state(self, tmp_path):
+        """The two features share one file; neither may clobber the other."""
+        p = tmp_path / "state.json"
+        usb_power._save_state("1-1", 3, p)
+        printer_settings.save_settings("a", {"tapeSizeMm": 12}, p)
+        assert usb_power._load_state(p) == ("1-1", 3)
+        assert printer_settings.get_settings("a", p) == {"tapeSizeMm": 12}
+
+    def test_usb_power_save_preserves_printer_settings(self, tmp_path):
+        p = tmp_path / "state.json"
+        printer_settings.save_settings("a", {"tapeSizeMm": 12}, p)
+        usb_power._save_state("2-4", 7, p)
+        assert printer_settings.get_settings("a", p) == {"tapeSizeMm": 12}
+        assert usb_power._load_state(p) == ("2-4", 7)
diff --git a/server/tests/test_smoke.py b/server/tests/test_smoke.py
index 18f44a2..1b4f40c 100644
--- a/server/tests/test_smoke.py
+++ b/server/tests/test_smoke.py
@@ -16,6 +16,8 @@
     "label_builder",
     "power_save",
     "printer_service",
+    "printer_settings",
+    "state_store",
     "usb_power",
     "virtual_printer",
 ]
diff --git a/server/tests/test_state_store.py b/server/tests/test_state_store.py
new file mode 100644
index 0000000..00087b0
--- /dev/null
+++ b/server/tests/test_state_store.py
@@ -0,0 +1,88 @@
+"""Tests for the shared JSON state store backing LABELLE_STATE_FILE.
+
+state_store is the single owner of the on-disk state file. Both the USB
+power feature (hub/port cache) and per-printer settings persistence write
+through it, so its read-modify-write must preserve keys it doesn't know
+about and be safe under concurrent callers.
+"""
+
+import json
+import threading
+
+import state_store
+
+
+class TestReadAll:
+    def test_returns_empty_dict_when_file_missing(self, tmp_path):
+        assert state_store.read_all(tmp_path / "absent.json") == {}
+
+    def test_returns_parsed_dict_when_valid(self, tmp_path):
+        p = tmp_path / "state.json"
+        p.write_text(json.dumps({"hub": "1-1", "port": 3}))
+        assert state_store.read_all(p) == {"hub": "1-1", "port": 3}
+
+    def test_returns_empty_dict_when_corrupt(self, tmp_path):
+        p = tmp_path / "state.json"
+        p.write_text("{not json")
+        assert state_store.read_all(p) == {}
+
+    def test_returns_empty_dict_when_top_level_not_object(self, tmp_path):
+        p = tmp_path / "state.json"
+        p.write_text(json.dumps([1, 2, 3]))
+        assert state_store.read_all(p) == {}
+
+
+class TestUpdate:
+    def test_persists_mutation(self, tmp_path):
+        p = tmp_path / "state.json"
+        state_store.update(lambda d: d.update(hub="2-4", port=7), p)
+        assert state_store.read_all(p) == {"hub": "2-4", "port": 7}
+
+    def test_preserves_unrelated_keys(self, tmp_path):
+        """A writer touching one key must not drop another writer's keys."""
+        p = tmp_path / "state.json"
+        state_store.update(lambda d: d.update(hub="1-1", port=3), p)
+        state_store.update(
+            lambda d: d.setdefault("printers", {}).__setitem__("p1", {"tapeSizeMm": 12}),
+            p,
+        )
+        data = state_store.read_all(p)
+        assert data["hub"] == "1-1"
+        assert data["port"] == 3
+        assert data["printers"]["p1"] == {"tapeSizeMm": 12}
+
+    def test_creates_parent_dirs(self, tmp_path):
+        p = tmp_path / "nested" / "dir" / "state.json"
+        state_store.update(lambda d: d.update(hub="1-1", port=3), p)
+        assert p.exists()
+
+    def test_swallows_write_errors(self, tmp_path):
+        # Parent is a file, so mkdir/replace fail; update must not raise.
+        blocker = tmp_path / "blocker"
+        blocker.write_text("x")
+        bad_path = blocker / "state.json"
+        state_store.update(lambda d: d.update(hub="1-1", port=3), bad_path)
+
+    def test_returns_resulting_data(self, tmp_path):
+        p = tmp_path / "state.json"
+        result = state_store.update(lambda d: d.update(hub="1-1", port=3), p)
+        assert result == {"hub": "1-1", "port": 3}
+
+    def test_concurrent_updates_do_not_lose_writes(self, tmp_path):
+        """Read-modify-write under the lock must not drop interleaved writes."""
+        p = tmp_path / "state.json"
+        state_store.update(lambda d: d.setdefault("printers", {}), p)
+
+        def writer(key):
+            state_store.update(
+                lambda d: d["printers"].__setitem__(key, {"tapeSizeMm": 12}), p
+            )
+
+        threads = [threading.Thread(target=writer, args=(f"p{i}",)) for i in range(20)]
+        for t in threads:
+            t.start()
+        for t in threads:
+            t.join()
+
+        printers = state_store.read_all(p)["printers"]
+        assert set(printers) == {f"p{i}" for i in range(20)}
diff --git a/server/tests/test_usb_power.py b/server/tests/test_usb_power.py
index d0da6a9..954296e 100644
--- a/server/tests/test_usb_power.py
+++ b/server/tests/test_usb_power.py
@@ -2,6 +2,7 @@
 
 import pytest
 
+import state_store
 import usb_power
 
 
@@ -226,21 +227,21 @@ def test_find_or_recall_persists_new_discovery_to_disk(
         self, mock_run, tmp_path, monkeypatch
     ):
         state_file = tmp_path / "state.json"
-        monkeypatch.setattr(usb_power, "_STATE_FILE", state_file)
+        monkeypatch.setattr(state_store, "STATE_FILE", state_file)
         usb_power._last_known_port = None
 
         mock_run.return_value = _result(UHUBCTL_DEFAULT_OUTPUT)
         usb_power.find_or_recall_printer_port()
 
         # Read it back through `_load_state()` with no arg so it
-        # resolves the same monkeypatched `_STATE_FILE`.
+        # resolves the same monkeypatched default state file.
         assert usb_power._load_state() == ("1-1", 3)
 
     def test_find_or_recall_does_not_rewrite_unchanged_value(
         self, mock_run, tmp_path, monkeypatch
     ):
         state_file = tmp_path / "state.json"
-        monkeypatch.setattr(usb_power, "_STATE_FILE", state_file)
+        monkeypatch.setattr(state_store, "STATE_FILE", state_file)
         usb_power._last_known_port = ("1-1", 3)
 
         mock_run.return_value = _result(UHUBCTL_DEFAULT_OUTPUT)
diff --git a/server/usb_power.py b/server/usb_power.py
index 0036afe..055dc29 100644
--- a/server/usb_power.py
+++ b/server/usb_power.py
@@ -8,7 +8,6 @@
 2.0 hub on hector.
 """
 
-import json
 import logging
 import os
 import re
@@ -17,6 +16,8 @@
 
 import usb.backend.libusb1
 
+import state_store
+
 logger = logging.getLogger(__name__)
 
 UHUBCTL_BIN = os.environ.get("UHUBCTL_BIN", "uhubctl")
@@ -156,57 +157,31 @@ def power_off(hub: str, port: int) -> None:
     # power/status`) rather than libusb-based device enumeration.
 
 
-# Path where `_last_known_port` is persisted across container restarts.
-# Default lives inside the Docker output mount, which is already a
-# persistent volume in the standard deployment — avoids requiring a
-# new volume mount just for this state. Tests pass an explicit path.
-_STATE_FILE = Path(
-    os.environ.get("LABELLE_STATE_FILE", "/app/output/.labelle/state.json")
-)
+# The (hub, port) cache is persisted across container restarts as the
+# top-level "hub"/"port" keys of the shared state file. We go through
+# state_store (rather than writing the file directly) so that saving the
+# port doesn't clobber the per-printer settings that share the file —
+# state_store does a read-modify-write of the whole document under a
+# shared lock. See server/state_store.py and printer_settings.py.
 
 
 def _load_state(path: Path | None = None) -> tuple[str, int] | None:
     """Read a previously-saved (hub, port) from disk, or None if absent/invalid."""
-    if path is None:
-        path = _STATE_FILE
-    try:
-        data = json.loads(path.read_text())
-    except FileNotFoundError:
-        return None
-    except (OSError, json.JSONDecodeError) as e:
-        logger.warning("Could not load printer port state from %s: %s", path, e)
-        return None
+    data = state_store.read_all(path)
     hub = data.get("hub")
     port = data.get("port")
     if isinstance(hub, str) and isinstance(port, int):
         return hub, port
-    logger.warning(
-        "Ignoring printer port state from %s: unexpected shape %r", path, data
-    )
     return None
 
 
 def _save_state(hub: str, port: int, path: Path | None = None) -> None:
     """Persist (hub, port) so a container restart can recover the cache.
 
-    Best-effort: a write failure (read-only fs, missing volume mount,
-    permissions) only loses cross-restart memory, never breaks runtime.
-
-    Writes are atomic-on-POSIX: serialize to a sibling `.tmp` file
-    first, then `os.replace()` over the target. A process interrupted
-    mid-write (or another thread writing concurrently) leaves the
-    target either fully old or fully new, never a torn JSON that
-    `_load_state` would have to discard.
+    Best-effort and atomic — see state_store.update. Merges into the
+    shared document so sibling keys (e.g. per-printer settings) survive.
     """
-    if path is None:
-        path = _STATE_FILE
-    try:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        tmp = path.with_suffix(path.suffix + ".tmp")
-        tmp.write_text(json.dumps({"hub": hub, "port": port}))
-        tmp.replace(path)
-    except OSError as e:
-        logger.warning("Could not save printer port state to %s: %s", path, e)
+    state_store.update(lambda d: d.update(hub=hub, port=port), path)
 
 
 # Module-global, intentionally unlocked. waitress serves requests on

From 443d6cba0d6d3b07d6f302ed313eeb49e5da3fc0 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:26:14 +0200
Subject: [PATCH 02/14] fix: harden printer_settings against a corrupt
 "printers" shape

A hand-edited or corrupt state file could carry a non-dict "printers"
value (e.g. "printers": []). get_settings then raised AttributeError on
.get() (500 on GET), and save_settings' setdefault returned the non-dict
so __setitem__ raised (500 on PUT). Treat a non-dict "printers" as empty
on read, and replace it on write. Adds regression tests.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/printer_settings.py            | 17 ++++++++++++-----
 server/tests/test_printer_settings.py | 16 ++++++++++++++++
 2 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/server/printer_settings.py b/server/printer_settings.py
index 900a1c0..968f9f6 100644
--- a/server/printer_settings.py
+++ b/server/printer_settings.py
@@ -46,7 +46,9 @@ def _validate(settings: dict) -> None:
 
 def get_settings(printer_id: str, path=None) -> dict:
     """Return the saved subset for a printer, or {} if none saved."""
-    printers = state_store.read_all(path).get(_PRINTERS_KEY, {})
+    printers = state_store.read_all(path).get(_PRINTERS_KEY)
+    if not isinstance(printers, dict):
+        return {}
     entry = printers.get(printer_id)
     return entry if isinstance(entry, dict) else {}
 
@@ -60,8 +62,13 @@ def save_settings(printer_id: str, settings: dict, path=None) -> dict:
     if not printer_id:
         raise ValueError("printer_id must be non-empty")
     _validate(settings)
-    state_store.update(
-        lambda d: d.setdefault(_PRINTERS_KEY, {}).__setitem__(printer_id, settings),
-        path,
-    )
+
+    def mutate(d: dict) -> None:
+        # A corrupt/hand-edited file may carry a non-dict "printers"; replace
+        # it rather than letting __setitem__ raise and fail the write.
+        if not isinstance(d.get(_PRINTERS_KEY), dict):
+            d[_PRINTERS_KEY] = {}
+        d[_PRINTERS_KEY][printer_id] = settings
+
+    state_store.update(mutate, path)
     return settings
diff --git a/server/tests/test_printer_settings.py b/server/tests/test_printer_settings.py
index 1aea9e0..f97a060 100644
--- a/server/tests/test_printer_settings.py
+++ b/server/tests/test_printer_settings.py
@@ -7,6 +7,7 @@
 import pytest
 
 import printer_settings
+import state_store
 import usb_power
 
 
@@ -36,6 +37,21 @@ def test_settings_are_isolated_per_printer(self, tmp_path):
         assert printer_settings.get_settings("b", p) == {"tapeSizeMm": 19}
 
 
+class TestCorruptState:
+    """A hand-edited or corrupt state file must not crash get/save."""
+
+    def test_get_returns_empty_when_printers_is_not_a_dict(self, tmp_path):
+        p = tmp_path / "state.json"
+        state_store.update(lambda d: d.__setitem__("printers", []), p)
+        assert printer_settings.get_settings("a", p) == {}
+
+    def test_save_replaces_non_dict_printers(self, tmp_path):
+        p = tmp_path / "state.json"
+        state_store.update(lambda d: d.__setitem__("printers", "garbage"), p)
+        printer_settings.save_settings("a", {"tapeSizeMm": 12}, p)
+        assert printer_settings.get_settings("a", p) == {"tapeSizeMm": 12}
+
+
 class TestSaveValidation:
     def test_rejects_unknown_key(self, tmp_path):
         p = tmp_path / "state.json"

From dd5626e8b77081febc1af6727bdc158bca3ec7ac Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:26:14 +0200
Subject: [PATCH 03/14] fix: persist live store state, not the render closure

persist() built the full per-printer subset from the settings captured
in the current render. Consecutive user edits can fire before a
re-render, so the other fields could be sent stale and overwrite a
just-changed value server-side. Read useLabelStore.getState() at call
time instead.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/state/usePrinterSettings.ts | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/client/src/state/usePrinterSettings.ts b/client/src/state/usePrinterSettings.ts
index ab14b65..93368e1 100644
--- a/client/src/state/usePrinterSettings.ts
+++ b/client/src/state/usePrinterSettings.ts
@@ -45,7 +45,11 @@ export function usePrinterSettings(): {
 
   const persist = (patch: PersistedPrinterSettings) => {
     if (!printerId) return;
-    savePrinterSettings(printerId, { ...pickPersisted(settings), ...patch }).catch(
+    // Read the live store rather than the `settings` captured in this render:
+    // consecutive user edits can fire before a re-render, and the full subset
+    // we send must reflect the latest values, not stale ones.
+    const current = useLabelStore.getState().settings;
+    savePrinterSettings(printerId, { ...pickPersisted(current), ...patch }).catch(
       (error) => {
         console.error("Failed to save printer settings:", error);
       },

From 95d3f3b9eba41c6f666817fc7429834929351454 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:26:15 +0200
Subject: [PATCH 04/14] docs: correct read_all logging wording; trim README
 feature line
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

read_all logs on every read of a corrupt file, not once — drop the
"once" wording and note the file is overwritten cleanly on next write.
Also trim the per-printer-settings README line per review.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md             | 2 +-
 server/state_store.py | 5 +++--
 2 files changed, 4 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 31e6fd0..92754e2 100644
--- a/README.md
+++ b/README.md
@@ -28,7 +28,7 @@ You can fight against AI usage or learn to embrace it as a new way of working. I
 - **Label settings** -- tape size, margins, minimum length, justify, foreground/background colors
 - **Per-widget font styles** -- each text widget can have its own font style, scale, frame, and alignment
 - **Multi-printer support** -- automatically detects all connected DYMO printers; select specific printer when multiple are available
-- **Per-printer settings** -- the tape size and colors loaded in each printer are remembered across visits, so you don't re-pick them every time (handy for kiosk / shared-tablet setups)
+- **Per-printer settings** -- the tape size and colors loaded in each printer are remembered across visits, so you don't re-pick them every time
 - **Virtual printers** -- configure virtual printers that save labels as PNG images, JSON data, or both (great for testing, archiving, and development)
 - **Batch print** -- print multiple labels with variable content using `{{varname}}` placeholders, with a table to fill in values per row, configurable copies and pause time, SSE progress streaming, and cancellation support
 - **Cut mark** -- optional dotted column painted into the trailing margin between batch labels so you can tear/cut between them; uses the existing inter-label gap, no extra tape
diff --git a/server/state_store.py b/server/state_store.py
index 68f49ec..9359af5 100644
--- a/server/state_store.py
+++ b/server/state_store.py
@@ -43,8 +43,9 @@ def read_all(path: Path | None = None) -> dict:
     """Return the whole state document as a dict; {} if absent/corrupt.
 
     A missing file is the normal first-run state. A corrupt or
-    wrong-shaped file is logged once and treated as empty rather than
-    crashing callers — the worst case is that prior state is forgotten.
+    wrong-shaped file is logged and treated as empty rather than
+    crashing callers — the worst case is that prior state is forgotten
+    (and overwritten cleanly on the next write).
     """
     if path is None:
         path = STATE_FILE

From a7aebf88343f96b0d94e330256d62771e9d05c9f Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:41:55 +0200
Subject: [PATCH 05/14] test: guard state_store as the sole owner of the state
 file

Source-introspection check (same idiom as the module-manifest guard):
LABELLE_STATE_FILE may be referenced only by state_store.py, so every
feature persists via read_all/update and writes stay atomic and
non-clobbering. Fails loudly if direct state-file access is reintroduced
(as the pre-refactor usb_power saver had). Also registers the new
/api/printers/<id>/settings route in the route smoke-check.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/tests/test_smoke.py | 26 ++++++++++++++++++++++++++
 1 file changed, 26 insertions(+)

diff --git a/server/tests/test_smoke.py b/server/tests/test_smoke.py
index 1b4f40c..97706e6 100644
--- a/server/tests/test_smoke.py
+++ b/server/tests/test_smoke.py
@@ -61,6 +61,31 @@ def test_no_stale_entries(self):
         )
 
 
+class TestStateFileOwnership:
+    """state_store.py is the single owner of the on-disk state file."""
+
+    def test_only_state_store_references_the_state_file(self):
+        """Every other feature must persist via state_store.read_all/update
+        so writes stay atomic and non-clobbering. Reaching for
+        LABELLE_STATE_FILE elsewhere is how the pre-refactor usb_power saver
+        introduced full-file overwrites — guard against reintroducing it.
+
+        Catches the realistic regression (a new feature grabbing the env
+        var); a hand-hardcoded path would slip through, which is an
+        acceptable trade for a zero-false-positive check.
+        """
+        server_dir = Path(__file__).resolve().parent.parent
+        offenders = [
+            f.name
+            for f in server_dir.glob("*.py")
+            if f.name != "state_store.py" and "LABELLE_STATE_FILE" in f.read_text()
+        ]
+        assert not offenders, (
+            f"{offenders} reference LABELLE_STATE_FILE directly; "
+            "go through state_store.read_all/update instead."
+        )
+
+
 class TestFlaskApp:
     """The Flask app must create and register expected routes."""
 
@@ -76,6 +101,7 @@ def test_app_creates(self):
             "/api/print",
             "/api/preview",
             "/api/printers",
+            "/api/printers/<path:printer_id>/settings",
             "/api/upload-image",
             "/api/uploads/<filename>",
             "/api/health",

From 7610f891717342a7e115ecf97f38d4fb6e44387b Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:48:45 +0200
Subject: [PATCH 06/14] fix: reject non-JSON PUT body instead of clearing
 printer settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

PUT /api/printers/<id>/settings used get_json(silent=True) or {}, so a
malformed or non-JSON body coerced to {} — which passed validation and
overwrote the printer's saved settings with an empty dict. Reject a
non-dict body with 400 so an accidental bad request can't silently wipe
persisted state.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/app.py            |  6 +++++-
 server/tests/test_app.py | 17 +++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

diff --git a/server/app.py b/server/app.py
index fbfe04b..9cbb107 100644
--- a/server/app.py
+++ b/server/app.py
@@ -221,7 +221,11 @@ def api_get_printer_settings(printer_id):
 
 @app.route("/api/printers/<path:printer_id>/settings", methods=["PUT"])
 def api_put_printer_settings(printer_id):
-    body = request.get_json(silent=True) or {}
+    body = request.get_json(silent=True)
+    if not isinstance(body, dict):
+        # Reject malformed/non-JSON bodies rather than letting them coerce to
+        # {} and silently wipe the printer's saved settings.
+        return jsonify(status="error", message="Request body must be a JSON object"), 400
     try:
         saved = printer_settings.save_settings(printer_id, body)
     except ValueError as e:
diff --git a/server/tests/test_app.py b/server/tests/test_app.py
index 72cf178..8c361f6 100644
--- a/server/tests/test_app.py
+++ b/server/tests/test_app.py
@@ -546,6 +546,23 @@ def test_put_unknown_key_returns_400(self, client, state_file):
         )
         assert resp.status_code == 400
 
+    def test_put_non_json_body_returns_400_without_clearing(self, client, state_file):
+        # Seed a saved value, then send a malformed PUT.
+        client.put(
+            "/api/printers/virtual:Test_Printer/settings",
+            data=json.dumps({"tapeSizeMm": 19}),
+            content_type="application/json",
+        )
+        resp = client.put(
+            "/api/printers/virtual:Test_Printer/settings",
+            data="not json",
+            content_type="text/plain",
+        )
+        assert resp.status_code == 400
+        # The previously-saved value must survive — not be wiped to {}.
+        got = client.get("/api/printers/virtual:Test_Printer/settings")
+        assert got.get_json() == {"settings": {"tapeSizeMm": 19}}
+
     def test_ids_with_spaces_and_colons_round_trip(self, client, state_file):
         # Real USB ids look like "Bus 001 Device 005: ID 0922:1234".
         from urllib.parse import quote

From 4f54e588483ec372007c9f90b8226785c209f23a Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 20:48:45 +0200
Subject: [PATCH 07/14] fix: read-side robustness for the printer settings
 store

A corrupt or hand-edited state file shouldn't crash or serve junk:
- get_settings sanitizes each entry to known keys with allowed values
  (the read-side mirror of the write-time _validate), so out-of-range or
  unknown values are dropped rather than handed to the client.
- state_store.read_all now also catches UnicodeDecodeError (a ValueError,
  not OSError), so a non-UTF8 file is treated as empty per the docstring
  instead of raising.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/printer_settings.py            | 40 +++++++++++++++++++++------
 server/state_store.py                 |  5 +++-
 server/tests/test_printer_settings.py | 14 ++++++++++
 server/tests/test_state_store.py      |  6 ++++
 4 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/server/printer_settings.py b/server/printer_settings.py
index 968f9f6..0c9559f 100644
--- a/server/printer_settings.py
+++ b/server/printer_settings.py
@@ -26,7 +26,15 @@
 _VALID_TAPE_SIZES = {6, 9, 12, 19}
 _VALID_COLORS = {"white", "black", "yellow", "blue", "red", "green"}
 
-_PERSISTED_KEYS = ("tapeSizeMm", "foregroundColor", "backgroundColor")
+# Allowed values per persisted key. Single source of truth for both
+# _validate (raise on write) and _sanitize (drop on read).
+_ALLOWED_VALUES = {
+    "tapeSizeMm": _VALID_TAPE_SIZES,
+    "foregroundColor": _VALID_COLORS,
+    "backgroundColor": _VALID_COLORS,
+}
+
+_PERSISTED_KEYS = tuple(_ALLOWED_VALUES)
 
 _PRINTERS_KEY = "printers"
 
@@ -37,20 +45,36 @@ def _validate(settings: dict) -> None:
     unknown = set(settings) - set(_PERSISTED_KEYS)
     if unknown:
         raise ValueError(f"Unknown printer setting(s): {sorted(unknown)}")
-    if "tapeSizeMm" in settings and settings["tapeSizeMm"] not in _VALID_TAPE_SIZES:
-        raise ValueError(f"Invalid tapeSizeMm: {settings['tapeSizeMm']!r}")
-    for key in ("foregroundColor", "backgroundColor"):
-        if key in settings and settings[key] not in _VALID_COLORS:
-            raise ValueError(f"Invalid {key}: {settings[key]!r}")
+    for key, value in settings.items():
+        if value not in _ALLOWED_VALUES[key]:
+            raise ValueError(f"Invalid {key}: {value!r}")
+
+
+def _sanitize(entry: dict) -> dict:
+    """Best-effort filter to known keys with allowed values; never raises.
+
+    Used on read so a hand-edited/corrupt state file can't serve unknown
+    keys or out-of-range values back to the client. The mirror of
+    _validate, which raises on the same conditions at write time.
+    """
+    return {
+        key: value
+        for key, value in entry.items()
+        if key in _ALLOWED_VALUES and value in _ALLOWED_VALUES[key]
+    }
 
 
 def get_settings(printer_id: str, path=None) -> dict:
-    """Return the saved subset for a printer, or {} if none saved."""
+    """Return the saved subset for a printer, or {} if none saved.
+
+    Sanitizes on read so a corrupt/hand-edited file yields only valid
+    values, consistent with the validation enforced at write time.
+    """
     printers = state_store.read_all(path).get(_PRINTERS_KEY)
     if not isinstance(printers, dict):
         return {}
     entry = printers.get(printer_id)
-    return entry if isinstance(entry, dict) else {}
+    return _sanitize(entry) if isinstance(entry, dict) else {}
 
 
 def save_settings(printer_id: str, settings: dict, path=None) -> dict:
diff --git a/server/state_store.py b/server/state_store.py
index 9359af5..e0651ee 100644
--- a/server/state_store.py
+++ b/server/state_store.py
@@ -53,7 +53,10 @@ def read_all(path: Path | None = None) -> dict:
         data = json.loads(path.read_text())
     except FileNotFoundError:
         return {}
-    except (OSError, json.JSONDecodeError) as e:
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError) as e:
+        # UnicodeDecodeError (non-UTF8 bytes) is a ValueError, not an
+        # OSError — catch it explicitly so a corrupt file is treated as
+        # empty rather than crashing the caller.
         logger.warning("Could not read state file %s: %s", path, e)
         return {}
     if isinstance(data, dict):
diff --git a/server/tests/test_printer_settings.py b/server/tests/test_printer_settings.py
index f97a060..081d604 100644
--- a/server/tests/test_printer_settings.py
+++ b/server/tests/test_printer_settings.py
@@ -51,6 +51,20 @@ def test_save_replaces_non_dict_printers(self, tmp_path):
         printer_settings.save_settings("a", {"tapeSizeMm": 12}, p)
         assert printer_settings.get_settings("a", p) == {"tapeSizeMm": 12}
 
+    def test_get_sanitizes_unknown_keys_and_invalid_values(self, tmp_path):
+        """A hand-edited entry must not serve junk back to the client."""
+        p = tmp_path / "state.json"
+        state_store.update(
+            lambda d: d.__setitem__(
+                "printers",
+                {"a": {"tapeSizeMm": 999, "foregroundColor": "red", "evil": "x"}},
+            ),
+            p,
+        )
+        # tapeSizeMm 999 (out of range) and the unknown key are dropped;
+        # the valid foregroundColor survives.
+        assert printer_settings.get_settings("a", p) == {"foregroundColor": "red"}
+
 
 class TestSaveValidation:
     def test_rejects_unknown_key(self, tmp_path):
diff --git a/server/tests/test_state_store.py b/server/tests/test_state_store.py
index 00087b0..11456cc 100644
--- a/server/tests/test_state_store.py
+++ b/server/tests/test_state_store.py
@@ -31,6 +31,12 @@ def test_returns_empty_dict_when_top_level_not_object(self, tmp_path):
         p.write_text(json.dumps([1, 2, 3]))
         assert state_store.read_all(p) == {}
 
+    def test_returns_empty_dict_on_non_utf8_bytes(self, tmp_path):
+        # Non-UTF8 bytes raise UnicodeDecodeError (a ValueError, not OSError).
+        p = tmp_path / "state.json"
+        p.write_bytes(b"\xff\xfe\x00garbage")
+        assert state_store.read_all(p) == {}
+
 
 class TestUpdate:
     def test_persists_mutation(self, tmp_path):

From 0ea9df576daf38dd907de149cbba397bff9485b7 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 22:27:34 +0200
Subject: [PATCH 08/14] fix: keep state_store.update best-effort on
 serialization errors
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

update() documented writes as best-effort but only caught OSError, so a
non-JSON-serializable value (a feature accidentally writing e.g. a set)
would raise TypeError from json.dumps and crash the caller's actual
operation. Catch serialization errors (TypeError/ValueError) too —
logged and swallowed like I/O errors — so persisting state never breaks
the request. Prior on-disk state is left intact (the bad write never
lands). Also drops a stray issue-#20 mention from the docstring.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/state_store.py            | 11 +++++++----
 server/tests/test_state_store.py |  8 ++++++++
 2 files changed, 15 insertions(+), 4 deletions(-)

diff --git a/server/state_store.py b/server/state_store.py
index e0651ee..86f5484 100644
--- a/server/state_store.py
+++ b/server/state_store.py
@@ -2,7 +2,7 @@
 
 Several features persist a little long-lived state across container
 restarts — the USB power feature caches the printer's (hub, port), and
-per-printer label settings live here too (issue #20). They all share one
+per-printer label settings live here too. They all share one
 file so the standard deployment needs only the single `/app/output`
 volume that's already mounted.
 
@@ -69,8 +69,11 @@ def update(mutator: Callable[[dict], None], path: Path | None = None) -> dict:
     """Atomically read-modify-write the state file under the shared lock.
 
     `mutator` receives the full document and edits it in place. Returns
-    the resulting document. Write failures are swallowed (best-effort);
-    the in-memory result is still returned so callers see their change.
+    the resulting document. Failures are swallowed (best-effort) — both
+    I/O errors and JSON serialization errors (a non-serializable value
+    written by a feature) — so persisting state never crashes the caller's
+    actual operation. The in-memory result is still returned so callers
+    see their change even when the write didn't land.
     """
     if path is None:
         path = STATE_FILE
@@ -82,6 +85,6 @@ def update(mutator: Callable[[dict], None], path: Path | None = None) -> dict:
             tmp = path.with_suffix(path.suffix + ".tmp")
             tmp.write_text(json.dumps(data))
             tmp.replace(path)
-        except OSError as e:
+        except (OSError, TypeError, ValueError) as e:
             logger.warning("Could not write state file %s: %s", path, e)
         return data
diff --git a/server/tests/test_state_store.py b/server/tests/test_state_store.py
index 11456cc..4385b28 100644
--- a/server/tests/test_state_store.py
+++ b/server/tests/test_state_store.py
@@ -69,6 +69,14 @@ def test_swallows_write_errors(self, tmp_path):
         bad_path = blocker / "state.json"
         state_store.update(lambda d: d.update(hub="1-1", port=3), bad_path)
 
+    def test_swallows_serialization_errors(self, tmp_path):
+        # A non-JSON-serializable value must not crash the caller, and must
+        # leave any prior on-disk state intact (the bad write never lands).
+        p = tmp_path / "state.json"
+        state_store.update(lambda d: d.update(hub="1-1", port=3), p)
+        state_store.update(lambda d: d.update(bad={1, 2, 3}), p)  # set → TypeError
+        assert state_store.read_all(p) == {"hub": "1-1", "port": 3}
+
     def test_returns_resulting_data(self, tmp_path):
         p = tmp_path / "state.json"
         result = state_store.update(lambda d: d.update(hub="1-1", port=3), p)

From 769a1db1de403784f521ffed5c56ea03176e8975 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 22:27:34 +0200
Subject: [PATCH 09/14] fix: warn on an invalid persisted hub/port shape

The pre-refactor _load_state warned when the state file had hub/port
with the wrong types; routing through state_store.read_all made it
silent (read_all only logs missing/corrupt-JSON files). Restore the
warning for a present-but-invalid shape, staying quiet on the normal
"no saved port yet" case (e.g. a file holding only printer settings).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/tests/test_usb_power.py | 16 ++++++++++++++++
 server/usb_power.py            |  7 +++++++
 2 files changed, 23 insertions(+)

diff --git a/server/tests/test_usb_power.py b/server/tests/test_usb_power.py
index 954296e..6888cc6 100644
--- a/server/tests/test_usb_power.py
+++ b/server/tests/test_usb_power.py
@@ -205,6 +205,22 @@ def test_load_state_returns_none_when_shape_wrong(self, tmp_path):
         p.write_text('{"hub": "1-1", "port": "3"}')
         assert usb_power._load_state(p) is None
 
+    def test_load_state_warns_on_invalid_shape(self, tmp_path, caplog):
+        p = tmp_path / "state.json"
+        p.write_text('{"hub": "1-1", "port": "3"}')
+        with caplog.at_level("WARNING"):
+            assert usb_power._load_state(p) is None
+        assert any("unexpected shape" in r.message for r in caplog.records)
+
+    def test_load_state_quiet_when_no_saved_port(self, tmp_path, caplog):
+        # A file with other features' keys but no hub/port is the normal
+        # case — must not warn.
+        p = tmp_path / "state.json"
+        p.write_text('{"printers": {"a": {"tapeSizeMm": 12}}}')
+        with caplog.at_level("WARNING"):
+            assert usb_power._load_state(p) is None
+        assert not any("unexpected shape" in r.message for r in caplog.records)
+
     def test_save_state_writes_round_trippable_json(self, tmp_path):
         p = tmp_path / "state.json"
         usb_power._save_state("2-4", 7, p)
diff --git a/server/usb_power.py b/server/usb_power.py
index 055dc29..fd22698 100644
--- a/server/usb_power.py
+++ b/server/usb_power.py
@@ -172,6 +172,13 @@ def _load_state(path: Path | None = None) -> tuple[str, int] | None:
     port = data.get("port")
     if isinstance(hub, str) and isinstance(port, int):
         return hub, port
+    # Quiet on the normal "no saved port yet" case, but warn if the keys
+    # are present with the wrong types — that's a corrupt state file worth
+    # surfacing (state_store.read_all only logs missing/corrupt-JSON files).
+    if hub is not None or port is not None:
+        logger.warning(
+            "Ignoring saved printer port: unexpected shape hub=%r port=%r", hub, port
+        )
     return None
 
 

From 9504acf355571d67a34373e0fb2bf325010dffc9 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Fri, 12 Jun 2026 22:27:34 +0200
Subject: [PATCH 10/14] chore: trim over-referenced issue #20 mentions to one
 canonical pointer

The PR sprinkled "(issue #20)" across many files where it added no
context once the feature exists. Keep a single canonical reference in
the printer_settings.py module docstring (where the why/scope lives) and
drop the rest from comments, type defs, tests, and ARCHITECTURE.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/components/SettingsBar.test.tsx | 4 ++--
 client/src/components/SettingsBar.tsx      | 4 ++--
 client/src/lib/api.ts                      | 2 +-
 client/src/state/usePrinterSettings.ts     | 2 +-
 client/src/types/label.ts                  | 2 +-
 docs/ARCHITECTURE.md                       | 2 +-
 server/app.py                              | 2 +-
 server/printer_settings.py                 | 4 ++--
 server/tests/test_app.py                   | 2 +-
 server/tests/test_printer_settings.py      | 2 +-
 10 files changed, 13 insertions(+), 13 deletions(-)

diff --git a/client/src/components/SettingsBar.test.tsx b/client/src/components/SettingsBar.test.tsx
index d3e2433..1b6d0ac 100644
--- a/client/src/components/SettingsBar.test.tsx
+++ b/client/src/components/SettingsBar.test.tsx
@@ -15,7 +15,7 @@ vi.mock("../lib/api", () => ({
   }),
   powerOn: vi.fn(),
   powerOff: vi.fn(),
-  // usePrinterSettings (issue #20) runs inside SettingsBar.
+  // usePrinterSettings runs inside SettingsBar.
   fetchPrinterSettings: vi.fn().mockResolvedValue({}),
   savePrinterSettings: vi.fn().mockResolvedValue(undefined),
 }));
@@ -129,7 +129,7 @@ describe("SettingsBar printer selector", () => {
   });
 });
 
-describe("SettingsBar per-printer settings persistence (issue #20)", () => {
+describe("SettingsBar per-printer settings persistence", () => {
   it("applies saved settings when a printer is selected", async () => {
     vi.mocked(fetchPrinterSettings).mockResolvedValueOnce({ tapeSizeMm: 6 });
     useLabelStore.setState({
diff --git a/client/src/components/SettingsBar.tsx b/client/src/components/SettingsBar.tsx
index 1f548a2..bd9b1f1 100644
--- a/client/src/components/SettingsBar.tsx
+++ b/client/src/components/SettingsBar.tsx
@@ -13,7 +13,7 @@ export function SettingsBar() {
   const setAvailablePrinters = useLabelStore((s) => s.setAvailablePrinters);
   const [isRefreshing, setIsRefreshing] = useState(false);
 
-  // Per-printer settings persistence (issue #20): applies saved tape/color
+  // Per-printer settings persistence: applies saved tape/color
   // for the selected printer, and `persist` saves user changes to those.
   const { persist } = usePrinterSettings();
 
@@ -30,7 +30,7 @@ export function SettingsBar() {
   };
 
   // Only show printer selector if multiple printers are detected.
-  // Tape size + colors now persist per printer (issue #20); the rest of
+  // Tape size + colors now persist per printer; the rest of
   // the multi-printer UI cluster (status indicators, capability-aware tape
   // display, aliases, presets) is tracked in #38.
   const showPrinterSelector = availablePrinters.length > 1;
diff --git a/client/src/lib/api.ts b/client/src/lib/api.ts
index 82e79b7..1be70c0 100644
--- a/client/src/lib/api.ts
+++ b/client/src/lib/api.ts
@@ -191,7 +191,7 @@ export async function powerOff(): Promise<PowerStatus> {
   return _readPowerResponse(res);
 }
 
-// Per-printer label settings (issue #20): the long-lived "what tape/colors
+// Per-printer label settings: the long-lived "what tape/colors
 // are loaded" subset, persisted server-side keyed by printer id. Printer
 // ids contain spaces and colons, so encode the whole segment.
 export async function fetchPrinterSettings(
diff --git a/client/src/state/usePrinterSettings.ts b/client/src/state/usePrinterSettings.ts
index 93368e1..501acd5 100644
--- a/client/src/state/usePrinterSettings.ts
+++ b/client/src/state/usePrinterSettings.ts
@@ -8,7 +8,7 @@ import {
 import type { PersistedPrinterSettings } from "../types/label";
 
 /**
- * Wires per-printer settings persistence (issue #20) in two directions:
+ * Wires per-printer settings persistence in two directions:
  *
  * - **Apply on select:** whenever the effective printer changes, fetch its
  *   saved subset and apply it to the store.
diff --git a/client/src/types/label.ts b/client/src/types/label.ts
index 3274ff8..3a18e16 100644
--- a/client/src/types/label.ts
+++ b/client/src/types/label.ts
@@ -108,7 +108,7 @@ export interface LabelSettings {
   printerId?: string; // Optional printer ID for multi-printer setups
 }
 
-// The subset of LabelSettings persisted per printer (issue #20): the
+// The subset of LabelSettings persisted per printer: the
 // physical "what tape/colors are loaded" properties. Partial because a
 // printer may only have some of them saved. Kept narrow on purpose —
 // margins/justify/cutMark are label preferences, not printer state.
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index fe68ddc..eaf53dd 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -156,7 +156,7 @@ Current slices:
   off and dropped off the USB tree.
 - **Per-printer settings** (`printer_settings.py`): a `printers` map keyed by
   `PrinterInfo.id`, storing the long-lived tape size + foreground/background
-  colors loaded in each printer (issue #20). Validated server-side; the client
+  colors loaded in each printer. Validated server-side; the client
   applies a printer's saved subset on selection and writes back on change. The
   "effective printer" is the explicit selection, or the sole printer when on
   Auto-select — so single-printer kiosks persist too. v2 follow-ups (aliases,
diff --git a/server/app.py b/server/app.py
index 9cbb107..b66a234 100644
--- a/server/app.py
+++ b/server/app.py
@@ -211,7 +211,7 @@ def api_printers():
     return jsonify(printers=list_printers())
 
 
-# Per-printer label settings (issue #20). Printer ids contain spaces and
+# Per-printer label settings. Printer ids contain spaces and
 # colons (e.g. "Bus 001 Device 005: ID 0922:1234", "virtual:Office"), so
 # the client URL-encodes them and we take the whole segment via <path:>.
 @app.route("/api/printers/<path:printer_id>/settings", methods=["GET"])
diff --git a/server/printer_settings.py b/server/printer_settings.py
index 0c9559f..e1c07d2 100644
--- a/server/printer_settings.py
+++ b/server/printer_settings.py
@@ -10,7 +10,7 @@
 ones — both stable across reboots. State rides in the shared state file
 under a "printers" namespace alongside the USB power cache.
 
-Out of scope (see issue #20): batch row data (lives in the label JSON),
+Out of scope: batch row data (lives in the label JSON),
 and recovering settings for a disconnected printer (we just keep the
 entry and restore it when the printer reappears).
 
@@ -21,7 +21,7 @@
 import state_store
 
 # The subset we persist, with their allowed values. Deliberately the
-# "physical printer state" minimum from issue #20 — margin/justify/cutMark
+# "physical printer state" minimum — margin/justify/cutMark
 # are arguably label preferences and are left out until that's decided.
 _VALID_TAPE_SIZES = {6, 9, 12, 19}
 _VALID_COLORS = {"white", "black", "yellow", "blue", "red", "green"}
diff --git a/server/tests/test_app.py b/server/tests/test_app.py
index 8c361f6..cc1c64f 100644
--- a/server/tests/test_app.py
+++ b/server/tests/test_app.py
@@ -501,7 +501,7 @@ def test_returns_500_when_print_raises(self, mock_print, client):
 
 
 class TestPrinterSettingsEndpoints:
-    """GET/PUT /api/printers/<id>/settings — per-printer settings (issue #20)."""
+    """GET/PUT /api/printers/<id>/settings — per-printer settings."""
 
     @pytest.fixture
     def state_file(self, tmp_path, monkeypatch):
diff --git a/server/tests/test_printer_settings.py b/server/tests/test_printer_settings.py
index 081d604..2148408 100644
--- a/server/tests/test_printer_settings.py
+++ b/server/tests/test_printer_settings.py
@@ -1,7 +1,7 @@
 """Tests for per-printer label settings persistence.
 
 Stores the long-lived "what tape/colors are loaded in this printer"
-subset, keyed by printer id, in the shared state file. See issue #20.
+subset, keyed by printer id, in the shared state file.
 """
 
 import pytest

From 941b461cc513341aedbeea49c778c81d1d57ae50 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Sat, 13 Jun 2026 10:18:23 +0200
Subject: [PATCH 11/14] feat: gate per-printer settings on load; strip
 printerId from exports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Closes the apply/save races surfaced in review of the per-printer
settings flow:

- Block the persisted controls (tape/fg/bg) until the effective printer's
  settings resolve — before the printer list loads and while the fetch is
  in flight. A late-arriving fetch can no longer revert a concurrent edit,
  and edits made before the list loads aren't lost. A fetch error (or a
  failed /api/printers) unlocks gracefully with defaults rather than
  locking forever. Adds availablePrintersLoaded to the store and a
  `loading` flag from usePrinterSettings; SettingsBar disables the three
  controls and shows a brief hint while loading.
- Strip printerId from exported label files (it's a local serial/virtual
  id, not portable content, and leaked the local printer identity);
  loadLabel keeps the printer you're currently on rather than adopting the
  file's. Fixes a loaded label clobbering its own tape/colors, the privacy
  leak, and the absent-printer selector state.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/App.tsx                         |  5 ++-
 client/src/components/SettingsBar.test.tsx | 47 +++++++++++++++++++++-
 client/src/components/SettingsBar.tsx      | 17 ++++++--
 client/src/lib/labelFile.test.ts           | 26 ++++++++++++
 client/src/lib/labelFile.ts                |  9 ++++-
 client/src/state/useLabelStore.test.ts     | 32 +++++++++++++++
 client/src/state/useLabelStore.ts          | 17 +++++++-
 client/src/state/usePrinterSettings.ts     | 31 ++++++++++++--
 docs/ARCHITECTURE.md                       | 17 ++++++--
 9 files changed, 185 insertions(+), 16 deletions(-)
 create mode 100644 client/src/lib/labelFile.test.ts

diff --git a/client/src/App.tsx b/client/src/App.tsx
index 8f11008..f7c167c 100644
--- a/client/src/App.tsx
+++ b/client/src/App.tsx
@@ -21,7 +21,10 @@ export default function App() {
         setAvailablePrinters(printers);
       } catch (error) {
         console.error("Failed to load printers:", error);
-        // Silently fail - UI will work without printer list
+        // Mark the fetch as settled (with no printers) so the per-printer
+        // settings gate lifts — otherwise the persisted controls would stay
+        // disabled forever when /api/printers is unreachable.
+        setAvailablePrinters([]);
       }
     };
     loadPrinters();
diff --git a/client/src/components/SettingsBar.test.tsx b/client/src/components/SettingsBar.test.tsx
index 1b6d0ac..62cc295 100644
--- a/client/src/components/SettingsBar.test.tsx
+++ b/client/src/components/SettingsBar.test.tsx
@@ -36,9 +36,11 @@ afterEach(() => {
 
 beforeEach(() => {
   vi.clearAllMocks();
-  // Reset store to defaults
+  // Reset store to defaults. availablePrintersLoaded: true so the persisted
+  // controls aren't gated off in tests that don't exercise the loading gate.
   useLabelStore.setState({
     availablePrinters: [],
+    availablePrintersLoaded: true,
     settings: {
       tapeSizeMm: 12,
       marginPx: 56,
@@ -153,6 +155,8 @@ describe("SettingsBar per-printer settings persistence", () => {
     screen.getByText("Settings").click();
 
     const tapeSelect = screen.getByDisplayValue("12");
+    // The control is gated until the printer's settings resolve.
+    await waitFor(() => expect(tapeSelect).not.toBeDisabled());
     await userEvent.selectOptions(tapeSelect, "19");
 
     expect(savePrinterSettings).toHaveBeenCalledWith("usb:1", {
@@ -162,6 +166,47 @@ describe("SettingsBar per-printer settings persistence", () => {
     });
   });
 
+  it("disables persisted controls until the printer list loads", () => {
+    useLabelStore.setState({ availablePrinters: [], availablePrintersLoaded: false });
+    render(<SettingsBar />);
+    screen.getByText("Settings").click();
+    expect(screen.getByDisplayValue("12")).toBeDisabled();
+  });
+
+  it("disables then re-enables persisted controls around the settings fetch", async () => {
+    // A never-resolving fetch keeps the control gated.
+    let resolve!: (v: Record<string, never>) => void;
+    vi.mocked(fetchPrinterSettings).mockReturnValueOnce(
+      new Promise((r) => {
+        resolve = r;
+      }),
+    );
+    useLabelStore.setState({
+      availablePrinters: twoPrinters,
+      settings: { ...useLabelStore.getState().settings, printerId: "usb:1" },
+    });
+    render(<SettingsBar />);
+    screen.getByText("Settings").click();
+
+    const tapeSelect = screen.getByDisplayValue("12");
+    await waitFor(() => expect(tapeSelect).toBeDisabled());
+    resolve({});
+    await waitFor(() => expect(tapeSelect).not.toBeDisabled());
+  });
+
+  it("re-enables controls (graceful unlock) when the settings fetch errors", async () => {
+    vi.mocked(fetchPrinterSettings).mockRejectedValueOnce(new Error("Pi down"));
+    useLabelStore.setState({
+      availablePrinters: twoPrinters,
+      settings: { ...useLabelStore.getState().settings, printerId: "usb:1" },
+    });
+    render(<SettingsBar />);
+    screen.getByText("Settings").click();
+
+    const tapeSelect = screen.getByDisplayValue("12");
+    await waitFor(() => expect(tapeSelect).not.toBeDisabled());
+  });
+
   it("uses the single connected printer even on Auto-select", async () => {
     useLabelStore.setState({
       availablePrinters: [twoPrinters[0]!],
diff --git a/client/src/components/SettingsBar.tsx b/client/src/components/SettingsBar.tsx
index bd9b1f1..fc12203 100644
--- a/client/src/components/SettingsBar.tsx
+++ b/client/src/components/SettingsBar.tsx
@@ -13,9 +13,11 @@ export function SettingsBar() {
   const setAvailablePrinters = useLabelStore((s) => s.setAvailablePrinters);
   const [isRefreshing, setIsRefreshing] = useState(false);
 
-  // Per-printer settings persistence: applies saved tape/color
-  // for the selected printer, and `persist` saves user changes to those.
-  const { persist } = usePrinterSettings();
+  // Per-printer settings persistence: applies saved tape/color for the
+  // selected printer, and `persist` saves user changes to those. `loading`
+  // is true until those settings resolve — we disable the persisted controls
+  // until then so a late-arriving fetch can't clobber an edit.
+  const { persist, loading: settingsLoading } = usePrinterSettings();
 
   const handleRefreshPrinters = async () => {
     setIsRefreshing(true);
@@ -81,10 +83,17 @@ export function SettingsBar() {
 
       {!selectedIsVirtual && <PowerToggle />}
 
+      {settingsLoading && (
+        <span className="text-xs text-gray-500 italic">
+          Loading printer settings…
+        </span>
+      )}
+
       <Field label="Tape (mm)">
         <select
           className="input w-20"
           value={settings.tapeSizeMm}
+          disabled={settingsLoading}
           onChange={(e) => {
             const tapeSizeMm = Number(e.target.value) as TapeSize;
             update({ tapeSizeMm });
@@ -137,6 +146,7 @@ export function SettingsBar() {
         <select
           className="input w-24"
           value={settings.foregroundColor}
+          disabled={settingsLoading}
           onChange={(e) => {
             const foregroundColor = e.target.value as LabelColor;
             update({ foregroundColor });
@@ -155,6 +165,7 @@ export function SettingsBar() {
         <select
           className="input w-24"
           value={settings.backgroundColor}
+          disabled={settingsLoading}
           onChange={(e) => {
             const backgroundColor = e.target.value as LabelColor;
             update({ backgroundColor });
diff --git a/client/src/lib/labelFile.test.ts b/client/src/lib/labelFile.test.ts
new file mode 100644
index 0000000..c81d3c5
--- /dev/null
+++ b/client/src/lib/labelFile.test.ts
@@ -0,0 +1,26 @@
+import { describe, it, expect } from "vitest";
+import { exportLabel } from "./labelFile";
+import type { LabelWidget, LabelSettings } from "../types/label";
+
+const settings: LabelSettings = {
+  tapeSizeMm: 12,
+  marginPx: 56,
+  minLengthMm: 0,
+  justify: "center",
+  foregroundColor: "black",
+  backgroundColor: "white",
+  showMargins: false,
+  cutMark: false,
+  printerId: "serial:ABC123",
+};
+
+describe("exportLabel", () => {
+  it("omits printerId from the exported settings", async () => {
+    // printerId is environment-specific (local serial / virtual id), not
+    // portable label content, and shouldn't leak into a shared file.
+    const widgets: LabelWidget[] = [{ id: "1", type: "qr", content: "x" }];
+    const json = JSON.parse(await exportLabel(widgets, settings));
+    expect("printerId" in json.settings).toBe(false);
+    expect(json.settings.tapeSizeMm).toBe(12);
+  });
+});
diff --git a/client/src/lib/labelFile.ts b/client/src/lib/labelFile.ts
index dfc33b3..aadd7ac 100644
--- a/client/src/lib/labelFile.ts
+++ b/client/src/lib/labelFile.ts
@@ -68,7 +68,14 @@ export async function exportLabel(
     }
   }
 
-  const data: LabelFile = { version: 2, settings, widgets: exportWidgets };
+  // Omit printerId: it's environment-specific (a USB serial / local virtual
+  // id), not portable label content, and would otherwise leak the local
+  // printer identity into shared files. JSON.stringify drops the undefined.
+  const data: LabelFile = {
+    version: 2,
+    settings: { ...settings, printerId: undefined },
+    widgets: exportWidgets,
+  };
 
   // Export the batch block whenever the user has touched anything in the
   // panel (rows with values, or non-default copies/pause). Batch mode is
diff --git a/client/src/state/useLabelStore.test.ts b/client/src/state/useLabelStore.test.ts
index 1ff49d9..95ea7b6 100644
--- a/client/src/state/useLabelStore.test.ts
+++ b/client/src/state/useLabelStore.test.ts
@@ -132,6 +132,14 @@ describe("Printers", () => {
     useLabelStore.getState().setAvailablePrinters(printers);
     expect(useLabelStore.getState().availablePrinters).toEqual(printers);
   });
+
+  it("setAvailablePrinters marks the list as loaded", () => {
+    // The per-printer settings gate keys off this; App also calls
+    // setAvailablePrinters([]) on fetch error so the gate still lifts.
+    useLabelStore.setState({ availablePrintersLoaded: false });
+    useLabelStore.getState().setAvailablePrinters([]);
+    expect(useLabelStore.getState().availablePrintersLoaded).toBe(true);
+  });
 });
 
 describe("Load", () => {
@@ -155,6 +163,30 @@ describe("Load", () => {
     expect(useLabelStore.getState().widgets).toEqual(widgets);
     expect(useLabelStore.getState().settings).toEqual(settings);
   });
+
+  it("loadLabel keeps the current printer selection", () => {
+    // Importing a label loads its design content but must not reassign the
+    // printer you're on (its printerId is stripped on export anyway).
+    useLabelStore.setState({
+      settings: { ...useLabelStore.getState().settings, printerId: "serial:ME" },
+    });
+    const settings: LabelSettings = {
+      tapeSizeMm: 6,
+      marginPx: 20,
+      minLengthMm: 10,
+      justify: "left",
+      foregroundColor: "blue",
+      backgroundColor: "yellow",
+      showMargins: true,
+      cutMark: false,
+      printerId: "serial:OTHER",
+    };
+
+    useLabelStore.getState().loadLabel([], settings);
+
+    expect(useLabelStore.getState().settings.printerId).toBe("serial:ME");
+    expect(useLabelStore.getState().settings.tapeSizeMm).toBe(6);
+  });
 });
 
 describe("Variable rename in batch rows", () => {
diff --git a/client/src/state/useLabelStore.ts b/client/src/state/useLabelStore.ts
index ea5d8e6..6d36c56 100644
--- a/client/src/state/useLabelStore.ts
+++ b/client/src/state/useLabelStore.ts
@@ -30,6 +30,10 @@ interface LabelStore {
   widgets: LabelWidget[];
   settings: LabelSettings;
   availablePrinters: PrinterInfo[];
+  // Whether the initial /api/printers fetch has settled. Distinguishes
+  // "not fetched yet" from "fetched, none found" so per-printer settings
+  // can hold edits until the effective printer's settings are known.
+  availablePrintersLoaded: boolean;
   batch: BatchState;
 
   addTextWidget: () => string;
@@ -77,6 +81,7 @@ export const useLabelStore = create<LabelStore>((set) => ({
   },
 
   availablePrinters: [],
+  availablePrintersLoaded: false,
 
   batch: defaultBatch(),
 
@@ -222,7 +227,8 @@ export const useLabelStore = create<LabelStore>((set) => ({
   updateSettings: (patch) =>
     set((s) => ({ settings: { ...s.settings, ...patch } })),
 
-  setAvailablePrinters: (printers) => set({ availablePrinters: printers }),
+  setAvailablePrinters: (printers) =>
+    set({ availablePrinters: printers, availablePrintersLoaded: true }),
 
   updateBatch: (patch) =>
     set((s) => ({ batch: { ...s.batch, ...patch } })),
@@ -262,5 +268,12 @@ export const useLabelStore = create<LabelStore>((set) => ({
     }),
 
   loadLabel: (widgets, settings, batch) =>
-    set({ widgets, settings, batch: batch ?? defaultBatch() }),
+    // Keep the currently-selected printer; a label file describes design
+    // content (tape/colors/widgets), not which printer you're on. Its
+    // printerId is stripped on export and ignored here regardless.
+    set((s) => ({
+      widgets,
+      settings: { ...settings, printerId: s.settings.printerId },
+      batch: batch ?? defaultBatch(),
+    })),
 }));
diff --git a/client/src/state/usePrinterSettings.ts b/client/src/state/usePrinterSettings.ts
index 501acd5..e11874c 100644
--- a/client/src/state/usePrinterSettings.ts
+++ b/client/src/state/usePrinterSettings.ts
@@ -1,4 +1,4 @@
-import { useEffect } from "react";
+import { useEffect, useState } from "react";
 import { useLabelStore } from "./useLabelStore";
 import { fetchPrinterSettings, savePrinterSettings } from "../lib/api";
 import {
@@ -18,31 +18,54 @@ import type { PersistedPrinterSettings } from "../types/label";
  *
  * Each save sends the whole subset (not just the changed field) so the
  * server's wholesale-per-printer write never drops a previously saved value.
+ *
+ * Returns `loading`: true from app start until the effective printer's
+ * settings have resolved (or there is no effective printer). Callers disable
+ * the persisted controls while it's true, which closes two races: a slow
+ * apply-fetch reverting a concurrent edit, and edits made before the printer
+ * list resolves being lost. On a fetch error it clears (graceful unlock —
+ * keep defaults, don't persist) so the UI never locks permanently.
  */
 export function usePrinterSettings(): {
   persist: (patch: PersistedPrinterSettings) => void;
+  loading: boolean;
 } {
   const settings = useLabelStore((s) => s.settings);
   const availablePrinters = useLabelStore((s) => s.availablePrinters);
+  const availablePrintersLoaded = useLabelStore((s) => s.availablePrintersLoaded);
   const updateSettings = useLabelStore((s) => s.updateSettings);
 
   const printerId = effectivePrinterId(settings.printerId, availablePrinters);
+  const [settingsLoading, setSettingsLoading] = useState(false);
 
   useEffect(() => {
-    if (!printerId) return;
+    if (!printerId) {
+      setSettingsLoading(false);
+      return;
+    }
     let cancelled = false;
+    setSettingsLoading(true);
     fetchPrinterSettings(printerId)
       .then((saved) => {
         if (!cancelled && Object.keys(saved).length > 0) updateSettings(saved);
       })
       .catch((error) => {
-        console.error("Failed to load printer settings:", error);
+        if (!cancelled) console.error("Failed to load printer settings:", error);
+      })
+      .finally(() => {
+        if (!cancelled) setSettingsLoading(false);
       });
     return () => {
       cancelled = true;
     };
   }, [printerId, updateSettings]);
 
+  // Block edits to persisted fields until we know what they should be:
+  // before the printer list loads, and while the chosen printer's settings
+  // are being fetched.
+  const loading =
+    !availablePrintersLoaded || (printerId !== undefined && settingsLoading);
+
   const persist = (patch: PersistedPrinterSettings) => {
     if (!printerId) return;
     // Read the live store rather than the `settings` captured in this render:
@@ -56,5 +79,5 @@ export function usePrinterSettings(): {
     );
   };
 
-  return { persist };
+  return { persist, loading };
 }
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 1cd5f71..6437e11 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -160,10 +160,19 @@ Current slices:
 - **Per-printer settings** (`printer_settings.py`): a `printers` map keyed by
   `PrinterInfo.id`, storing the long-lived tape size + foreground/background
   colors loaded in each printer. Validated server-side; the client
-  applies a printer's saved subset on selection and writes back on change. The
-  "effective printer" is the explicit selection, or the sole printer when on
-  Auto-select — so single-printer kiosks persist too. v2 follow-ups (aliases,
-  presets, remember-last) are expected to extend this same per-printer map.
+  applies a printer's saved subset on selection and writes back on change
+  (`usePrinterSettings`). The "effective printer" is the explicit selection,
+  or the sole printer when on Auto-select — so single-printer kiosks persist
+  too. v2 follow-ups (aliases, presets, remember-last) are expected to extend
+  this same per-printer map.
+
+  The persisted controls (tape/colors) are **disabled until the effective
+  printer's settings have resolved** — before the printer list loads and while
+  the fetch is in flight — so a late-arriving fetch can't revert an edit and
+  pre-load edits aren't lost; a fetch error unlocks them (keep defaults). And
+  `printerId` is **stripped from exported label files** (it's a local
+  serial/virtual id, not portable content); importing a label keeps the
+  printer you're currently on.
 
 ### Request Flow
 

From 6f760db8649ec8b4cafc7529c78b271f067d23b0 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Sat, 13 Jun 2026 10:44:47 +0200
Subject: [PATCH 12/14] fix: reset per-printer fields to defaults for an
 unconfigured printer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The apply effect only applied fetched settings when non-empty
(`Object.keys(saved).length > 0`), so selecting a printer with no saved
settings left the *previous* printer's tape/colors in place instead of
resetting — breaking per-printer isolation (found in manual testing on
the Pi: a printer inherited another's 19mm white/blue). Always set the
persisted fields to saved-where-present, defaults-otherwise. Extract
DEFAULT_SETTINGS in the store as the single source for those defaults.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/components/SettingsBar.test.tsx | 24 +++++++++++++++++++++
 client/src/state/useLabelStore.ts          | 25 +++++++++++++---------
 client/src/state/usePrinterSettings.ts     |  9 ++++++--
 3 files changed, 46 insertions(+), 12 deletions(-)

diff --git a/client/src/components/SettingsBar.test.tsx b/client/src/components/SettingsBar.test.tsx
index 62cc295..dcf1b09 100644
--- a/client/src/components/SettingsBar.test.tsx
+++ b/client/src/components/SettingsBar.test.tsx
@@ -146,6 +146,30 @@ describe("SettingsBar per-printer settings persistence", () => {
     expect(fetchPrinterSettings).toHaveBeenCalledWith("usb:1");
   });
 
+  it("resets persisted fields to defaults for an unconfigured printer", async () => {
+    // Regression: switching to a printer with no saved settings must reset
+    // tape/colors to defaults, not inherit the previous printer's values.
+    vi.mocked(fetchPrinterSettings).mockResolvedValueOnce({});
+    useLabelStore.setState({
+      availablePrinters: twoPrinters,
+      settings: {
+        ...useLabelStore.getState().settings,
+        printerId: "usb:1",
+        tapeSizeMm: 19,
+        foregroundColor: "white",
+        backgroundColor: "blue",
+      },
+    });
+    render(<SettingsBar />);
+
+    await waitFor(() => {
+      const s = useLabelStore.getState().settings;
+      expect(s.tapeSizeMm).toBe(12);
+      expect(s.foregroundColor).toBe("black");
+      expect(s.backgroundColor).toBe("white");
+    });
+  });
+
   it("persists the full subset when the tape size changes", async () => {
     useLabelStore.setState({
       availablePrinters: twoPrinters,
diff --git a/client/src/state/useLabelStore.ts b/client/src/state/useLabelStore.ts
index 6d36c56..239103d 100644
--- a/client/src/state/useLabelStore.ts
+++ b/client/src/state/useLabelStore.ts
@@ -56,6 +56,20 @@ interface LabelStore {
   ) => void;
 }
 
+// Default label settings — single source of truth for the store's initial
+// state and for resetting per-printer-persisted fields when a selected
+// printer has no saved settings (so it doesn't inherit the previous one's).
+export const DEFAULT_SETTINGS: LabelSettings = {
+  tapeSizeMm: 12,
+  marginPx: DEFAULT_MARGIN_PX,
+  minLengthMm: 0,
+  justify: "center",
+  foregroundColor: "black",
+  backgroundColor: "white",
+  showMargins: false,
+  cutMark: false,
+};
+
 export const useLabelStore = create<LabelStore>((set) => ({
   widgets: [
     {
@@ -69,16 +83,7 @@ export const useLabelStore = create<LabelStore>((set) => ({
     } satisfies TextWidget,
   ],
 
-  settings: {
-    tapeSizeMm: 12,
-    marginPx: DEFAULT_MARGIN_PX,
-    minLengthMm: 0,
-    justify: "center",
-    foregroundColor: "black",
-    backgroundColor: "white",
-    showMargins: false,
-    cutMark: false,
-  },
+  settings: { ...DEFAULT_SETTINGS },
 
   availablePrinters: [],
   availablePrintersLoaded: false,
diff --git a/client/src/state/usePrinterSettings.ts b/client/src/state/usePrinterSettings.ts
index e11874c..f2def52 100644
--- a/client/src/state/usePrinterSettings.ts
+++ b/client/src/state/usePrinterSettings.ts
@@ -1,5 +1,5 @@
 import { useEffect, useState } from "react";
-import { useLabelStore } from "./useLabelStore";
+import { useLabelStore, DEFAULT_SETTINGS } from "./useLabelStore";
 import { fetchPrinterSettings, savePrinterSettings } from "../lib/api";
 import {
   effectivePrinterId,
@@ -47,7 +47,12 @@ export function usePrinterSettings(): {
     setSettingsLoading(true);
     fetchPrinterSettings(printerId)
       .then((saved) => {
-        if (!cancelled && Object.keys(saved).length > 0) updateSettings(saved);
+        // Always set the persisted fields: saved values where present, else
+        // defaults. A printer with no saved settings must reset to defaults,
+        // not inherit the previously-selected printer's tape/colors.
+        if (!cancelled) {
+          updateSettings({ ...pickPersisted(DEFAULT_SETTINGS), ...saved });
+        }
       })
       .catch((error) => {
         if (!cancelled) console.error("Failed to load printer settings:", error);

From 29639dc287e7a503b98b2be66c8ad68164b7f3d1 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Sat, 13 Jun 2026 11:52:51 +0200
Subject: [PATCH 13/14] fix: harden printer settings validation against
 malformed input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Unhashable values (e.g. a client sends {"tapeSizeMm": [12]}, or a list
  is in a hand-edited state file) made `value in <set>` raise TypeError —
  a 500 on PUT and a crash in get_settings on read. Treat unhashable as
  invalid via a hashable-safe membership helper used by both _validate
  (raise) and _sanitize (drop).
- save_settings only checked printer_id non-empty. Require a string and
  cap its length (256), so the unauthenticated API can't bloat the shared
  state file with absurdly long keys. (Broader spam-many-ids abuse is
  inherent to the LAN-trusted, unauthenticated API — out of scope here.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 server/printer_settings.py            | 25 +++++++++++++++++++++----
 server/tests/test_printer_settings.py | 25 +++++++++++++++++++++++++
 2 files changed, 46 insertions(+), 4 deletions(-)

diff --git a/server/printer_settings.py b/server/printer_settings.py
index e1c07d2..acb1292 100644
--- a/server/printer_settings.py
+++ b/server/printer_settings.py
@@ -38,6 +38,21 @@
 
 _PRINTERS_KEY = "printers"
 
+# Cap the persisted printer-id length. Real ids are short (a USB id string
+# or "serial:"/"virtual:" + name); this just stops an unauthenticated client
+# from bloating the shared state file with absurdly long keys.
+_MAX_PRINTER_ID_LEN = 256
+
+
+def _is_allowed(key: str, value) -> bool:
+    """Whether `value` is permitted for `key`. Unhashable values (a list or
+    dict from a malformed request / hand-edited file) are simply not allowed,
+    rather than raising TypeError from the set-membership check."""
+    try:
+        return value in _ALLOWED_VALUES[key]
+    except TypeError:
+        return False
+
 
 def _validate(settings: dict) -> None:
     if not isinstance(settings, dict):
@@ -46,7 +61,7 @@ def _validate(settings: dict) -> None:
     if unknown:
         raise ValueError(f"Unknown printer setting(s): {sorted(unknown)}")
     for key, value in settings.items():
-        if value not in _ALLOWED_VALUES[key]:
+        if not _is_allowed(key, value):
             raise ValueError(f"Invalid {key}: {value!r}")
 
 
@@ -60,7 +75,7 @@ def _sanitize(entry: dict) -> dict:
     return {
         key: value
         for key, value in entry.items()
-        if key in _ALLOWED_VALUES and value in _ALLOWED_VALUES[key]
+        if key in _ALLOWED_VALUES and _is_allowed(key, value)
     }
 
 
@@ -83,8 +98,10 @@ def save_settings(printer_id: str, settings: dict, path=None) -> dict:
     The write replaces that printer's entry wholesale (not a deep-merge);
     the client always sends the full current subset.
     """
-    if not printer_id:
-        raise ValueError("printer_id must be non-empty")
+    if not isinstance(printer_id, str) or not printer_id:
+        raise ValueError("printer_id must be a non-empty string")
+    if len(printer_id) > _MAX_PRINTER_ID_LEN:
+        raise ValueError(f"printer_id too long (max {_MAX_PRINTER_ID_LEN} chars)")
     _validate(settings)
 
     def mutate(d: dict) -> None:
diff --git a/server/tests/test_printer_settings.py b/server/tests/test_printer_settings.py
index 2148408..82431da 100644
--- a/server/tests/test_printer_settings.py
+++ b/server/tests/test_printer_settings.py
@@ -65,6 +65,18 @@ def test_get_sanitizes_unknown_keys_and_invalid_values(self, tmp_path):
         # the valid foregroundColor survives.
         assert printer_settings.get_settings("a", p) == {"foregroundColor": "red"}
 
+    def test_get_drops_unhashable_value_without_crashing(self, tmp_path):
+        # A list value in a hand-edited file must be dropped on read, not
+        # crash the GET with TypeError from the set-membership check.
+        p = tmp_path / "state.json"
+        state_store.update(
+            lambda d: d.__setitem__(
+                "printers", {"a": {"tapeSizeMm": [12], "foregroundColor": "red"}}
+            ),
+            p,
+        )
+        assert printer_settings.get_settings("a", p) == {"foregroundColor": "red"}
+
 
 class TestSaveValidation:
     def test_rejects_unknown_key(self, tmp_path):
@@ -92,6 +104,19 @@ def test_rejects_non_dict_body(self, tmp_path):
         with pytest.raises(ValueError):
             printer_settings.save_settings("a", ["tapeSizeMm"], p)
 
+    def test_rejects_unhashable_value_without_crashing(self, tmp_path):
+        # An unhashable value must raise ValueError (→ 400), not TypeError.
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("a", {"tapeSizeMm": [12]}, p)
+
+    def test_rejects_non_string_or_overlong_printer_id(self, tmp_path):
+        p = tmp_path / "state.json"
+        with pytest.raises(ValueError):
+            printer_settings.save_settings(123, {"tapeSizeMm": 12}, p)
+        with pytest.raises(ValueError):
+            printer_settings.save_settings("x" * 257, {"tapeSizeMm": 12}, p)
+
     def test_partial_subset_is_allowed(self, tmp_path):
         """User may have only ever changed the tape size; persist just that."""
         p = tmp_path / "state.json"

From a7b2246defe139a986aafcfba4c8294671888994 Mon Sep 17 00:00:00 2001
From: Rudi Szabo <szrudi@gmail.com>
Date: Sat, 13 Jun 2026 12:12:26 +0200
Subject: [PATCH 14/14] refactor: derive pickPersisted from
 PERSISTED_PRINTER_KEYS

pickPersisted hard-coded the three fields while PERSISTED_PRINTER_KEYS
right above it is documented as the single source of truth. Build the
subset from that list so the two can't drift. (Per Copilot review.)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 client/src/lib/printerSettings.ts | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/client/src/lib/printerSettings.ts b/client/src/lib/printerSettings.ts
index 9038c8c..8f8066c 100644
--- a/client/src/lib/printerSettings.ts
+++ b/client/src/lib/printerSettings.ts
@@ -31,11 +31,10 @@ export function effectivePrinterId(
   return undefined;
 }
 
-/** Extract just the per-printer-persisted subset from full label settings. */
+/** Extract just the per-printer-persisted subset from full label settings.
+ *  Derived from PERSISTED_PRINTER_KEYS so it can't drift from that list. */
 export function pickPersisted(settings: LabelSettings): PersistedPrinterSettings {
-  return {
-    tapeSizeMm: settings.tapeSizeMm,
-    foregroundColor: settings.foregroundColor,
-    backgroundColor: settings.backgroundColor,
-  };
+  return Object.fromEntries(
+    PERSISTED_PRINTER_KEYS.map((key) => [key, settings[key]]),
+  ) as PersistedPrinterSettings;
 }