[Bug/Critical] Epson printer quality options limited to default only — only "Normal" shown, 6 other options missing #180

New Issue

Closed

opened 2026-09-15 10:03:25 +01:00 by gronod · 3 comments

gronod commented 2026-09-15 10:03:25 +01:00

Owner

Copy Link

Copy Source

Summary

The Epson driver (e.g., Epson XP-55 Series) offers 7 quality options — Fast Economy (301), Economy (302), Normal (303), Draft (308), Fine (304), Quality (305), Best Quality (307) — but ICCery v2 Mac does not enumerate them: CupsService.capabilities(from:ppd:) performs no quality extraction at all, so only the driver default ("Normal" / 303) can ever apply.

Note: no quality picker exists in Stage 2 until #183 lands — the enumeration gap becomes user-visible once it does.

This same limitation isn't present in TargetPrint (ICCery-CPU) which doesn't restrict available quality settings and correctly shows all 7 options.

Root Cause Analysis

What lpoptions -l Actually Returns

EPIJ_Qual/Print Quality: 301 302 *303 308 304 305 307

All 7 options ARE present in the CUPS lpoptions -l output. The issue is not with CUPS — it's with ICCery v2 Mac's parsing code.

Where the Bug Lives

1. CupsService.capabilities(from:ppd:) (Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsService.swift:105-136) — the actual blocker

   • Only handles InputSlot/MediaSource, PageSize/MediaSize, and CupsParsers.mediaTypeKeys
   • No quality option extraction at all

2. No quality-key detection roster exists in CupsParsers

   • CupsOptionsFilter.relevantKeys (CupsOptionsFilter.swift:16-32) is a capture-relevance roster — it decides which -o options survive into captured cupsOptions, not which options get enumerated. EPIJ_Qual already survives isRelevant via the permissive non-com.* rule (CupsOptionsFilter.swift:44-52), so the roster is not the blocker — a new detection roster + extraction is
   • EPIJ_Quality (in relevantKeys, CupsOptionsFilter.swift:28) is a phantom/alias — real Epson PPDs use EPIJ_Qual. Keep EPIJ_Quality (harmless for capture); treat EPIJ_Qual as canonical in the new quality-key roster

3. Test fixture mismatch (Tests/ICCeryCoreTests/CupsParserTests.swift:33)

   • Uses cupsPrintQuality/cupsPrintQuality: Draft *Normal High (3 options)
   • Real Epson driver uses EPIJ_Qual with 7 options

Comparison with ICCery-CPU (TargetPrint)

ICCery-CPU correctly handles this in CUPSManager.discoverPPDOptions() (Sources/Printing/CUPSManager.swift:190-196):

let quality = discoverOptionChoices(
    in: ppdText,
    candidateKeywords: ["CNIJPrintQuality", "EPIJ_Qual", "cupsPrintQuality", "PrintQuality", "CNIJPrintMode2", "Quality", "StpQuality"],
    openUITargets: ["print quality", "quality"]
)

It includes EPIJ_Qual in candidate keywords AND scans *OpenUI translations.

PPD Evidence (Epson XP-55 Series)

/etc/cups/ppd/Epson_XP_55_Series.ppd:
*OpenUI *EPIJ_Qual/Print Quality: PickOne
*DefaultEPIJ_Qual: 303
*EPIJ_Qual 301/Fast Economy: ""
*EPIJ_Qual 302/Economy: ""
*EPIJ_Qual 303/Normal: ""
*EPIJ_Qual 308/Draft: ""
*EPIJ_Qual 304/Fine: ""
*EPIJ_Qual 305/Quality: ""
*EPIJ_Qual 307/Best Quality: ""

Proposed Fix Options

Option 1: Minimal Fix — quality extraction + detection roster

• Add quality option extraction to CupsService.capabilities() (or a new function) — this is the actual blocker
• Add a quality-key detection roster with EPIJ_Qual canonical, ordered vendor-first / weakest-last (OutputMode/Resolution last — Epson OutputMode is a colour-mode key, misdetect risk); EPIJ_Qual may also be added to CupsOptionsFilter.relevantKeys for explicitness (it already survives isRelevant)
• Allows existing lpoptions -l path to capture all quality options

Option 2: Full PPD Parsing (aligns with ICCery-CPU)

• Parse PPD directly for quality choices with human labels
• More accurate but adds complexity

Option 3: Hybrid Approach (Recommended)

• Use lpoptions -l for basic enumeration
• Add PPD parsing specifically for vendor-specific quality/media keys
• Matches ICCery-CPU's discoverOptionChoices approach

Acceptance Criteria

• All 7 Epson quality options appear in ICCery's quality UI — codes 301, 302, 303, 304, 305, 307, 308 (no 306 exists; 308 = Draft)
• Quality options display with human-readable labels (Fast Economy, Economy, Normal, Draft, Fine, Quality, Best Quality)
• Works for all Epson printers using EPIJ_Qual key
• Test fixture updated to reflect real EPIJ_Qual output

Dependencies

• Depends on: #183 (Stage 2 quality picker UI must exist before this bug fix can show all options)
• Blocks: #186 (printer properties dialog needs all quality options to pre-select)

References

• ICCery-CPU: Sources/Printing/CUPSManager.swift (discoverOptionChoices, optionDetails)
• ICCery v2 Mac: Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsOptionsFilter.swift
• ICCery v2 Mac: Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsService.swift
• ICCery v2 Mac: Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsParsers.swift
• Test: Tests/ICCeryCoreTests/CupsParserTests.swift

## Summary The Epson driver (e.g., Epson XP-55 Series) offers 7 quality options — Fast Economy (301), Economy (302), Normal (303), Draft (308), Fine (304), Quality (305), Best Quality (307) — but ICCery v2 Mac does not enumerate them: `CupsService.capabilities(from:ppd:)` performs **no quality extraction at all**, so only the driver default ("Normal" / 303) can ever apply. Note: no quality picker exists in Stage 2 until #183 lands — the enumeration gap becomes user-visible once it does. This same limitation isn't present in TargetPrint (ICCery-CPU) which doesn't restrict available quality settings and correctly shows all 7 options. ## Root Cause Analysis ### What `lpoptions -l` Actually Returns ``` EPIJ_Qual/Print Quality: 301 302 *303 308 304 305 307 ``` All 7 options ARE present in the CUPS `lpoptions -l` output. The issue is not with CUPS — it's with ICCery v2 Mac's parsing code. ### Where the Bug Lives 1. **`CupsService.capabilities(from:ppd:)`** (Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsService.swift:105-136) — **the actual blocker** - Only handles `InputSlot`/`MediaSource`, `PageSize`/`MediaSize`, and `CupsParsers.mediaTypeKeys` - No quality option extraction at all 2. **No quality-key detection roster exists in `CupsParsers`** - `CupsOptionsFilter.relevantKeys` (CupsOptionsFilter.swift:16-32) is a **capture-relevance** roster — it decides which `-o` options survive into captured `cupsOptions`, not which options get enumerated. `EPIJ_Qual` already survives `isRelevant` via the permissive non-`com.*` rule (CupsOptionsFilter.swift:44-52), so the roster is not the blocker — a new detection roster + extraction is - `EPIJ_Quality` (in `relevantKeys`, CupsOptionsFilter.swift:28) is a **phantom/alias** — real Epson PPDs use `EPIJ_Qual`. Keep `EPIJ_Quality` (harmless for capture); treat `EPIJ_Qual` as canonical in the new quality-key roster 3. **Test fixture mismatch** (Tests/ICCeryCoreTests/CupsParserTests.swift:33) - Uses `cupsPrintQuality/cupsPrintQuality: Draft *Normal High` (3 options) - Real Epson driver uses `EPIJ_Qual` with 7 options ### Comparison with ICCery-CPU (TargetPrint) ICCery-CPU correctly handles this in `CUPSManager.discoverPPDOptions()` (Sources/Printing/CUPSManager.swift:190-196): ```swift let quality = discoverOptionChoices( in: ppdText, candidateKeywords: ["CNIJPrintQuality", "EPIJ_Qual", "cupsPrintQuality", "PrintQuality", "CNIJPrintMode2", "Quality", "StpQuality"], openUITargets: ["print quality", "quality"] ) ``` It includes `EPIJ_Qual` in candidate keywords AND scans `*OpenUI` translations. ### PPD Evidence (Epson XP-55 Series) ``` /etc/cups/ppd/Epson_XP_55_Series.ppd: *OpenUI *EPIJ_Qual/Print Quality: PickOne *DefaultEPIJ_Qual: 303 *EPIJ_Qual 301/Fast Economy: "" *EPIJ_Qual 302/Economy: "" *EPIJ_Qual 303/Normal: "" *EPIJ_Qual 308/Draft: "" *EPIJ_Qual 304/Fine: "" *EPIJ_Qual 305/Quality: "" *EPIJ_Qual 307/Best Quality: "" ``` ## Proposed Fix Options ### Option 1: Minimal Fix — quality extraction + detection roster - Add quality option extraction to `CupsService.capabilities()` (or a new function) — this is the actual blocker - Add a quality-key detection roster with `EPIJ_Qual` canonical, ordered vendor-first / weakest-last (`OutputMode`/`Resolution` last — Epson `OutputMode` is a colour-mode key, misdetect risk); `EPIJ_Qual` may also be added to `CupsOptionsFilter.relevantKeys` for explicitness (it already survives `isRelevant`) - Allows existing `lpoptions -l` path to capture all quality options ### Option 2: Full PPD Parsing (aligns with ICCery-CPU) - Parse PPD directly for quality choices with human labels - More accurate but adds complexity ### Option 3: Hybrid Approach (Recommended) - Use `lpoptions -l` for basic enumeration - Add PPD parsing specifically for vendor-specific quality/media keys - Matches ICCery-CPU's `discoverOptionChoices` approach ## Acceptance Criteria - [x] All 7 Epson quality options appear in ICCery's quality UI — codes **301, 302, 303, 304, 305, 307, 308** (no 306 exists; 308 = Draft) - [ ] Quality options display with human-readable labels (Fast Economy, Economy, Normal, Draft, Fine, Quality, Best Quality) - [ ] Works for all Epson printers using `EPIJ_Qual` key - [ ] Test fixture updated to reflect real `EPIJ_Qual` output ## Dependencies - **Depends on:** #183 (Stage 2 quality picker UI must exist before this bug fix can show all options) - **Blocks:** #186 (printer properties dialog needs all quality options to pre-select) ## References - ICCery-CPU: `Sources/Printing/CUPSManager.swift` (discoverOptionChoices, optionDetails) - ICCery v2 Mac: `Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsOptionsFilter.swift` - ICCery v2 Mac: `Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsService.swift` - ICCery v2 Mac: `Packages/ICCeryCore/Sources/ICCeryCore/Print/CupsParsers.swift` - Test: `Tests/ICCeryCoreTests/CupsParserTests.swift`

gronod added the Kind/Bug

Priority

Critical

1

Project/ICCery-v2Bug/Backend labels 2026-09-15 10:03:25 +01:00

gronod referenced this issue 2026-09-15 10:20:29 +01:00

[Feature/Medium] Stage 2: Add paper size and print quality selection to printer details #183

gronod referenced this issue 2026-09-15 10:20:54 +01:00

[Bug/High] Printer properties dialog doesn't apply selected printer and settings from ICCery #186

gronod added this to the M11 — Printer settings completeness & dialog binding milestone 2026-09-15 11:58:22 +01:00

gronod added a new dependency 2026-09-15 12:37:27 +01:00

#183 [Feature/Medium] Stage 2: Add paper size and print quality selection to printer details

gronod added a new dependency 2026-09-15 12:37:28 +01:00

#186 [Bug/High] Printer properties dialog doesn't apply selected printer and settings from ICCery

gronod removed a dependency 2026-09-15 12:38:15 +01:00

#186 [Bug/High] Printer properties dialog doesn't apply selected printer and settings from ICCery

gronod removed a dependency 2026-09-15 12:38:15 +01:00

#183 [Feature/Medium] Stage 2: Add paper size and print quality selection to printer details

gronod added a new dependency 2026-09-15 12:44:08 +01:00

#183 [Feature/Medium] Stage 2: Add paper size and print quality selection to printer details

gronod added a new dependency 2026-09-15 12:44:09 +01:00

#186 [Bug/High] Printer properties dialog doesn't apply selected printer and settings from ICCery

gronod commented 2026-09-15 17:47:04 +01:00

Author

Owner

Copy Link

Copy Source

Planning errata (verified on develop@736fd08):

1. AC "(301–307)" — the seven codes are 301, 302, 303, 304, 305, 307, 308; no 306 exists and 308 (Draft) is included (matches the body's own lpoptions -l evidence: EPIJ_Qual/Print Quality: 301 302 *303 308 304 305 307).
2. RCA framing: CupsOptionsFilter.relevantKeys is a capture-relevance roster, not an enumeration roster — EPIJ_Qual already survives isRelevant via the permissive non-com.* rule (CupsOptionsFilter.swift:44–52). The actual blockers are: CupsService.capabilities(from:ppd:) has no quality extraction at all (CupsService.swift:105–136 handles InputSlot/MediaSource, PageSize/MediaSize, and mediaTypeKeys only), and no quality-key detection roster exists in CupsParsers.
3. "only 'Normal' shown in ICCery" — no quality picker exists in Stage 2 until #183 lands; the enumeration gap becomes user-visible only then.
4. EPIJ_Quality (in relevantKeys, CupsOptionsFilter.swift:28) is a phantom/alias — real Epson PPDs use EPIJ_Qual. Keep EPIJ_Quality (harmless for capture); treat EPIJ_Qual as canonical in the new quality-key roster.

Planning errata (verified on develop@736fd08): 1. AC "(301–307)" — the seven codes are **301, 302, 303, 304, 305, 307, 308**; no 306 exists and 308 (Draft) is included (matches the body's own `lpoptions -l` evidence: `EPIJ_Qual/Print Quality: 301 302 *303 308 304 305 307`). 2. RCA framing: `CupsOptionsFilter.relevantKeys` is a **capture-relevance** roster, not an enumeration roster — `EPIJ_Qual` already survives `isRelevant` via the permissive non-`com.*` rule (CupsOptionsFilter.swift:44–52). The actual blockers are: `CupsService.capabilities(from:ppd:)` has **no quality extraction at all** (CupsService.swift:105–136 handles InputSlot/MediaSource, PageSize/MediaSize, and mediaTypeKeys only), and no quality-key detection roster exists in `CupsParsers`. 3. "only 'Normal' shown in ICCery" — no quality picker exists in Stage 2 until #183 lands; the enumeration gap becomes user-visible only then. 4. `EPIJ_Quality` (in `relevantKeys`, CupsOptionsFilter.swift:28) is a phantom/alias — real Epson PPDs use `EPIJ_Qual`. Keep `EPIJ_Quality` (harmless for capture); treat `EPIJ_Qual` as canonical in the new quality-key roster.

gronod commented 2026-09-15 18:05:19 +01:00

Author

Owner

Copy Link

Copy Source

Errata above incorporated into the issue body — the ticket itself is now the corrected contract.

Errata above incorporated into the issue body — the ticket itself is now the corrected contract.

gronod referenced this issue 2026-09-15 18:07:16 +01:00

docs(m11): record printer-settings milestone tracking #191

gronod referenced this issue 2026-09-15 18:43:13 +01:00

feat(print): Stage 2 paper size + quality selection (#183) #193

gronod referenced this issue from a commit 2026-09-15 19:06:52 +01:00

fix(print): enumerate all EPIJ_Qual quality options (#180)

gronod referenced this issue 2026-09-15 19:07:10 +01:00

fix(print): enumerate all EPIJ_Qual quality options (#180) #194

gronod referenced this issue from a commit 2026-09-15 19:07:19 +01:00

Merge pull request 'fix(print): enumerate all EPIJ_Qual quality options (#180)' (#194) from feat/180-epson-qual-options into milestone/m11-print-settings

gronod commented 2026-09-15 21:44:17 +01:00

Author

Owner

Copy Link

Copy Source

Implementation landed in PR #194 at c9b423b on milestone/m11-print-settings.

Acceptance evidence:

• All 7 Epson EPIJ_Qual options appear in the quality UI — codes 301, 302, 303, 304, 305, 307, 308 in driver order (no sort) — recorded Epson XP-55 fixture EPIJ_Qual/Print Quality: 301 302 *303 308 304 305 307; UI test testQualityPickerListsAllSevenDriverOptions, core testCapabilitiesQualityEpsonDetection (CupsParserTests)
• Quality options display human-readable labels from the PPD (Fast Economy, Economy, Normal, Draft, Fine, Quality, Best Quality) with qualityDefault == "303" — testCapabilitiesQualityPpdLabels (CupsParserTests)
• Works for all Epson printers using EPIJ_Qual; EPIJ_Qual is canonical in the quality-key roster and is chosen over OutputMode/Resolution when both exist — testQualityKeyRosterOrder (CupsParserTests)
• Captured EPIJ_Qual= survives CupsOptionsFilter.filter and suppresses the derived emit — testKeepsQualityKeys (CupsOptionsFilterTests), testCapturedWinsQuality, testCapturedQualityCaseInsensitiveDedup (LpArgsTests)
• EPIJ_Quality retained as a harmless capture alias in relevantKeys (R16) — roster unchanged, covered by testKeepsRelevant
• Test fixture updated to reflect real EPIJ_Qual output — synthetic 3-option fixture replaced by the recorded XP-55 enumeration

Verification at milestone/m11-print-settings 6adbf99bd9:

• xcodebuild test -scheme ICCery -destination 'platform=macOS' -derivedDataPath build/DerivedData-m11-final ARCHS="$(uname -m)" CODE_SIGNING_ALLOWED=YES CODE_SIGN_IDENTITY='-' (x86_64): passed
• full host-arch ICCeryCoreTests: 483 passed, 0 failed
• full ICCeryUITests: 67 passed, 0 failed (genuine xctest pass summary; single allowed clean rerun consumed for an app-activation attach flake in run 1 — testAboutDialogShowsVersionAndBuildDate, no assertion failure)

Hardware item remains a milestone gate (not this issue's merge gate).
Closing manually only after code and tests are present on the milestone branch.

Implementation landed in PR #194 at c9b423b on milestone/m11-print-settings. Acceptance evidence: - [x] All 7 Epson `EPIJ_Qual` options appear in the quality UI — codes 301, 302, 303, 304, 305, 307, 308 in driver order (no sort) — recorded Epson XP-55 fixture `EPIJ_Qual/Print Quality: 301 302 *303 308 304 305 307`; UI test `testQualityPickerListsAllSevenDriverOptions`, core `testCapabilitiesQualityEpsonDetection` (CupsParserTests) - [x] Quality options display human-readable labels from the PPD (Fast Economy, Economy, Normal, Draft, Fine, Quality, Best Quality) with `qualityDefault == "303"` — `testCapabilitiesQualityPpdLabels` (CupsParserTests) - [x] Works for all Epson printers using `EPIJ_Qual`; `EPIJ_Qual` is canonical in the quality-key roster and is chosen over `OutputMode`/`Resolution` when both exist — `testQualityKeyRosterOrder` (CupsParserTests) - [x] Captured `EPIJ_Qual=` survives `CupsOptionsFilter.filter` and suppresses the derived emit — `testKeepsQualityKeys` (CupsOptionsFilterTests), `testCapturedWinsQuality`, `testCapturedQualityCaseInsensitiveDedup` (LpArgsTests) - [x] `EPIJ_Quality` retained as a harmless capture alias in `relevantKeys` (R16) — roster unchanged, covered by `testKeepsRelevant` - [x] Test fixture updated to reflect real `EPIJ_Qual` output — synthetic 3-option fixture replaced by the recorded XP-55 enumeration Verification at milestone/m11-print-settings 6adbf99bd9aaefd84a55a35442f1bd18bf8ab2c3: - `xcodebuild test -scheme ICCery -destination 'platform=macOS' -derivedDataPath build/DerivedData-m11-final ARCHS="$(uname -m)" CODE_SIGNING_ALLOWED=YES CODE_SIGN_IDENTITY='-'` (x86_64): passed - full host-arch ICCeryCoreTests: 483 passed, 0 failed - full ICCeryUITests: 67 passed, 0 failed (genuine xctest pass summary; single allowed clean rerun consumed for an app-activation attach flake in run 1 — `testAboutDialogShowsVersionAndBuildDate`, no assertion failure) Hardware item remains a milestone gate (not this issue's merge gate). Closing manually only after code and tests are present on the milestone branch.

gronod closed this issue 2026-09-15 21:44:21 +01:00

gronod referenced this issue 2026-09-15 22:26:04 +01:00

Milestone 11 — Printer settings completeness & dialog binding (#183, #180, #181, #186) #199

gronod referenced this issue from a commit 2026-09-16 00:12:02 +01:00

Merge pull request 'Milestone 11 — Printer settings completeness & dialog binding (#183, #180, #181, #186)' (#199) from milestone/m11-print-settings into develop

gronod referenced this issue 2026-09-16 01:48:17 +01:00

Milestone 11 — Printer settings completeness & dialog binding (#183, #180, #181, #186) #199

gronod referenced this issue 2026-09-22 19:37:25 +01:00

[Enhancement/Medium] Merge develop into main #221

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

main

docs/27-roadmap-candidates

develop

milestone/m13-print-ticket

feat/218-paper-source

feat/217-panel-ticket-restore

bugfix/211-print-output-flip

milestone/m12-native-spool

feat/202-airprint-detection

feat/201-native-print-operation

feat/201-raster-canvas

feat/201-ticket-capture

feat/201-pm-ticket-bridge

chore/m11-sync-develop

milestone/m11-print-settings

chore/m11-docs-hygiene

feat/186-panel-binding

feat/181-canon-media-locale

feat/180-epson-qual-options

feat/183-stage2-print-settings

chore/m11-tracking

docs/ui-interactive-map

v2.0.4-prerelease-docs27

v2.0.4

v2.0.3

v2.0.3-prerelease

v2.0.2

v2.0.1

v2.0.0

Labels

Clear labels

Bug/Architecture

Core / wizard / process infra defect

Bug/Backend

Argyll orchestration, file/data defect

Bug/DevOps

Build, packaging, CI defect

Bug/UI

Views, controls, dialogs defect

Compat/Breaking

Breaking change that won't be backward compatible

Feature/Architecture

Core / wizard / process infra

Feature/Backend

Argyll orchestration, file/data engines

Feature/DevOps

Build, packaging, CI

Feature/UI

Views, controls, dialogs

Kind/Bug

Something is not working

Kind/Documentation

Documentation changes

Kind/Enhancement

Improve existing functionality

Kind/Feature

New functionality

Kind/Security

This is security issue

Kind/Testing

Issue or pull request related to testing

Priority

Critical

1

The priority is critical

Priority

High

2

The priority is high

Priority

Low

4

The priority is low

Priority

Medium

3

The priority is medium

Project/ICCery-v2

ICCery v2 Mac rewrite

Reviewed

Confirmed

1

Issue has been confirmed

Reviewed

Duplicate

2

This issue or pull request already exists

Reviewed

Invalid

3

Invalid issue

Reviewed

Won't Fix

3

This issue won't be fixed

Status

Abandoned

3

Somebody has started to work on this but abandoned work

Status

Blocked

1

Something is blocking this issue or pull request

Status

Need More Info

2

Feedback is required to reproduce issue or to continue work

No labels Bug/Backend Kind/Bug

Priority

Critical

1

Project/ICCery-v2

Milestone

No items

No Milestone M11 — Printer settings completeness & dialog binding

Projects

Clear projects

No projects

Assignees

Clear assignees

gronod

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Blocks

#186 [Bug/High] Printer properties dialog doesn't apply selected printer and settings from ICCery

gronod/iccery-v2-mac

Depends on

#183 [Feature/Medium] Stage 2: Add paper size and print quality selection to printer details

gronod/iccery-v2-mac

Reference: gronod/iccery-v2-mac#180