# LabelTender Qt Desktop Shell Design

## Goal

Wrap the existing static LabelTender frontend in a Qt desktop shell for UOS/deepin so the app can:

- open and save `.lblt` project files via native dialogs
- enumerate system printers
- submit print jobs to the system printing stack instead of browser `window.print()`
- package as a Debian `.deb`

The first validation target is Brother PT-P900W, while keeping the printing path generic through CUPS and installed system drivers.

## Constraints

- Keep the current frontend editing experience and data model.
- Do not rewrite the editor as native Qt widgets/QML.
- Do not implement Brother private printer protocols in-app.
- Preserve the current `.lblt` project format.
- Keep a browser/static fallback path where practical.

## Architecture

### Frontend

The existing `index.html`, `static/`, and `icons/` assets remain the renderer layer. The frontend continues to own:

- canvas editing
- preview generation
- print settings UI
- project serialization
- PDF export

### Desktop Bridge

A new JS bridge layer normalizes desktop capabilities behind a single object exposed as `window.qtBridge`. Frontend code will call bridge methods for:

- window control
- native file open/save
- recent files based on local paths
- printer enumeration
- direct system print submission

### Qt Shell

A Qt WebEngine app loads the local frontend, exposes a `QWebChannel` bridge object, and handles:

- native dialogs
- file I/O
- settings persistence
- printer discovery
- print job submission

### Print Backend

The frontend generates rasterized print pages as PNG data plus page metadata. Qt receives those pages and prints them via `QPrinter`, `QPainter`, and the system print stack. This avoids browser `window.print()` and avoids depending on Qt-side PDF rendering modules.

## Printing Flow

1. User opens the existing print modal in the frontend.
2. If the Qt bridge exists, the frontend requests the available system printers.
3. The frontend prefers printers whose names include `Brother` or `PT-P900W`.
4. On print, the frontend renders print pages to page-sized PNG images.
5. The frontend sends the print job payload to Qt through `QWebChannel`.
6. Qt configures `QPrinter` for the selected printer and custom page size.
7. Qt draws each PNG page onto the printer device and submits the job.
8. The OS routes the job through CUPS and the installed printer driver.

If direct system printing fails, the frontend still keeps PDF export as a fallback.

## File Flow

The current browser File System Access API usage will be replaced with bridge calls:

- open project via native open dialog
- save project via native save dialog
- save print PDF via native save dialog
- recent files stored as filesystem paths in Qt settings

The `.lblt` payload remains gzip-compressed JSON so existing project files stay compatible.

## Debian Packaging

The repo will gain a CMake-based Qt project with CPack Debian packaging. The package will install:

- the desktop executable
- frontend assets under `/opt/labelnova`
- a `.desktop` launcher
- an application icon

Runtime printing still depends on system printer setup and installed drivers on UOS/deepin.

## Verification Scope

Primary verification target:

- app loads local frontend inside Qt shell
- native open/save works
- printer list is visible in the print modal
- print submission no longer uses browser `window.print()`

Environment-dependent verification:

- actual Qt build requires Qt WebEngine/WebChannel/PrintSupport development packages
- actual Brother PT-P900W printing requires system printer setup on the target machine
