pasteup 0.1.0__tar.gz → 0.2.0__tar.gz

{pasteup-0.1.0 → pasteup-0.2.0}/CHANGELOG.md

@@ -7,6 +7,31 @@ All notable changes to Pasteup are recorded here. The format follows
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-10-16
+
+### Added
+- **Browse…** beside the folder field opens a folder browser, so a folder can be
+  picked instead of typed. It opens at the folder in the field, or at your home
+  folder, says how many images the folder you're in holds, and scans the one
+  you choose. Typing or pasting a path still works.
+  (`POST /api/jobs/browse-folder`)
+- Upscaled images, from a tile of their own in step 3: every image of a bundle,
+  or of each picked bundle, made 2x, 3x or 4x bigger and saved in an
+  `Upscaled` folder as a PNG, which keeps any transparency, and a JPG on
+  white. (`POST /api/jobs/upscale-images`, `POST /api/jobs/upscale-images-batch`)
+
+### Fixed
+- Hidden files are no longer counted as images. A Mac writes a hidden `._`
+  file beside the files it copies to an exFAT or FAT32 drive or to some network
+  shares, so such a bundle could scan as twice its size, and making sheets then
+  reported the extra files as unreadable.
+- Hidden folders, such as the `.Spotlight-V100` and `.Trashes` a Mac keeps on
+  those drives, and the `__MACOSX` folder left by unpacking a zip made on a
+  Mac, are no longer offered as bundles. Covers no longer take images from
+  them, nor from a `---Created---` folder inside the bundle.
+- After a scan or making images, keyboard focus returns to the button that
+  started it, instead of falling back to the top of the page.
+
 ## [0.1.0] - 2026-10-16
 
 The first release on PyPI.
@@ -29,5 +54,6 @@ The first release on PyPI.
   already running and moves to a free port when another program has 8000.
   `pasteup --shortcut` makes a double-click launcher.
 
-[Unreleased]: https://github.com/ftymoshchuk/pasteup/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/ftymoshchuk/pasteup/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/ftymoshchuk/pasteup/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/ftymoshchuk/pasteup/releases/tag/v0.1.0

{pasteup-0.1.0 → pasteup-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pasteup
-Version: 0.1.0
+Version: 0.2.0
 Summary: Turn a folder of clip art into listing images: preview sheets, cover collages and preview videos.
 Project-URL: Source, https://github.com/ftymoshchuk/pasteup
 Project-URL: Issues, https://github.com/ftymoshchuk/pasteup/issues
@@ -50,6 +50,8 @@ publishing: cut out by hand and pasted onto a layout board.
   main image.
 - **Preview video:** an MP4 slideshow of the sheets, exactly as long as you ask
   (Etsy's listing videos run 5 to 15 s).
+- **Upscaled images:** every image made 2x, 3x or 4x bigger, saved in an
+  `Upscaled` folder as a PNG, which keeps any transparency, and a JPG on white.
 - **Clean-up:** transparent PNGs land on white instead of black, phone photos
   are turned upright, and near-white backgrounds can be removed.
 - **Batch mode:** process every bundle folder under a parent folder in one go.
@@ -73,6 +75,21 @@ it without installing anything: `uvx pasteup`.
 For changes not released yet, install from GitHub instead:
 `pipx install git+https://github.com/ftymoshchuk/pasteup.git`.
 
+### No pipx yet?
+Install pipx once (or uv, which needs nothing else), then open a new terminal
+window so the command is found:
+
+- **macOS:** `brew install pipx`, then `pipx ensurepath`. Without
+  [Homebrew](https://brew.sh), install uv instead:
+  `curl -LsSf https://astral.sh/uv/install.sh | sh`
+- **Windows:** `py -m pip install --user pipx`, then `py -m pipx ensurepath`.
+  Or install uv from PowerShell:
+  `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`
+- **Linux:** `sudo apt install pipx` (Debian, Ubuntu) or `sudo dnf install pipx`
+  (Fedora), then `pipx ensurepath`.
+
+Then run `pipx install pasteup`, or `uv tool install pasteup` if you chose uv.
+
 ## Run
 ```bash
 pasteup
@@ -135,7 +152,8 @@ PyPI trusts `release.yml` running in this repository's `pypi` environment.
 Project layout:
 - `src/pasteup/main.py`: the FastAPI app
 - `src/pasteup/routes/`: the page and the `/api/jobs` endpoints
-- `src/pasteup/services/`: scanning, page composition, collages, export, video
+- `src/pasteup/services/`: scanning and browsing folders, page composition,
+  collages, export, video
 - `src/pasteup/models/`: request and response schemas
 - `src/pasteup/templates/` and `src/pasteup/static/`: the UI
 - `src/pasteup/cli.py`: the `pasteup` command; `shortcut.py` makes its launchers
@@ -152,6 +170,12 @@ Input scan supports the following image extensions (case-insensitive):
 
 Notes:
 - Folder scan is **non-recursive** (only files directly inside the selected folder).
+- Hidden files, whose names start with a dot, are skipped. Most are the `._`
+  files a Mac writes beside the files it copies to an exFAT or FAT32 drive or
+  to some network shares: they carry the image's extension but hold no image.
+- Hidden folders, `__MACOSX` (left by unpacking a zip made on a Mac) and
+  `---Created---` are never offered as bundles, and covers don't look inside
+  them.
 - Export output format supports `PNG` and `JPG`.
 
 ---
@@ -170,12 +194,15 @@ Default UI values:
 - `background_tolerance`: `240`
 - `background_feather`: `1`
 - `include_partial_page`: `false`
+- upscaling `scale`: `2` (also `3` or `4`)
 
 Behavior defaults:
 - Scan sample size: first `5` files (`sample_files`) in sorted order.
 - Images per page: `12` (fixed 4x3).
 - Export naming: `page_001`, `page_002`, ...
 - Export conflict handling: never overwrite existing `page_###`; continue at next index.
+- Upscaled images keep their image's name, in `Upscaled/PNG` and `Upscaled/JPG`,
+  so upscaling again replaces the files the last run made.
 
 ---
 
@@ -187,7 +214,7 @@ Health check endpoint.
 
 **Response**
 ```json
-{"status": "ok", "app": "pasteup", "version": "0.1.0"}
+{"status": "ok", "app": "pasteup", "version": "0.2.0"}
 ```
 
 ### `POST /api/jobs/scan-folder`
@@ -205,8 +232,40 @@ Validates a folder and scans for supported image files.
 - `image_count` (int): number of supported files found.
 - `sample_files` (list[str]): up to 5 sorted sample filenames.
 - `estimated_pages` (int): `image_count // 12` (whole pages only).
+- `available_subfolders` (list): when the folder has no images of its own, the
+  folders inside it, each with `display_name` and `full_path`, for picking one
+  bundle or listing many. Hidden folders, `__MACOSX` and `---Created---` are
+  left out. Empty when the folder has images.
 - `message` (str): summary or error detail.
 
+### `POST /api/jobs/browse-folder`
+Lists the folders inside a folder, for the folder browser behind **Browse…**. A
+page can't read the path of a folder picked with the browser's own file
+chooser, so the UI browses through this instead.
+
+**Request body**
+```json
+{
+  "folder_path": "~/Pictures"
+}
+```
+A blank `folder_path` lists the home folder.
+
+**Response fields**
+- `path` (str): the folder listed. One that does not exist or cannot be opened
+  gives way to the nearest folder above it that can, and `message` says why.
+- `parent_path` (str | null): the folder above it; `null` at the top of a drive.
+- `breadcrumbs` (list): `name` and `path` of each folder from the top of the
+  drive down to this one.
+- `folders` (list): `name` and `path` of each folder inside, sorted, leaving
+  out hidden folders, `__MACOSX` and `---Created---`.
+- `image_count` (int): supported images directly inside, counted as
+  `scan-folder` counts them.
+- `places` (list): shortcuts: the home folder, its Desktop, Documents,
+  Downloads and Pictures folders when it has them, and each drive on Windows.
+- `message` (str): empty unless a different folder was listed than the one
+  asked for.
+
 ### `POST /api/jobs/scan-selected-batch-folders`
 Validates selected batch subfolders under a scanned parent folder and reports which selected folders are ready for generation.
 
@@ -292,6 +351,7 @@ and the response message gives ffmpeg's error.
 - `output_files` (list[str]): generated file paths
 - `output_path` (str): normalized output folder path
 - `images_dropped` (int): trailing images left out because they did not fill a page
+- `images_skipped` (int): files that could not be read as images
 - `backgrounds_cleaned` (int): images whose background was cleaned
 - `page_geometry` (str): resolved page size, e.g. `3000x2400px (10.00x8.00in at 300 DPI)`
 - `video_file` (str | null), `video_created` (bool): the preview video, when requested
@@ -324,13 +384,139 @@ Used by the UI in **Many bundles** mode. Iterates bundle folders under a parent
 - `bundle_results` (list): per-folder generation summaries
 - `message` (str): batch generation summary
 
+### `POST /api/jobs/generate-cover-collage`
+Makes one cover image for a folder: its images arranged in one of three layouts.
+
+**Request body**
+```json
+{
+  "folder_path": "/path/to/images",
+  "output_path": "/path/to/output",
+  "page_width": 3000,
+  "page_height": 3000,
+  "format": "JPG",
+  "collage_template": "randomized-grid",
+  "selected_cover_images": ["cover001.jpg", "cover002.png"]
+}
+```
+- `collage_template` (`randomized-grid` | `feature-spread` | `center-stage`,
+  default `randomized-grid`): the layout.
+- `image_fit` (`cover` | `contain`, default `cover`): `cover` fills each tile
+  and crops the overflow; `contain` fits the whole image and leaves margins.
+- `selected_cover_images` (list of file names, optional): use only these files.
+  Names must match exactly, extension included; when none of them match, the
+  request fails and says so.
+- The output quality fields above apply too.
+
+**Response fields**
+- `success` (bool)
+- `total_images` (int): images in the collage
+- `pages_generated` (int)
+- `output_files` (list[str]): the cover's file path
+- `output_path` (str)
+- `page_geometry` (str): resolved page size
+- `message` (str)
+
+### `POST /api/jobs/generate-cover-collage-batch`
+Makes one cover per bundle folder, as `/generate-all-folders` does for sheets.
+
+**Request body**
+```json
+{
+  "parent_folder_path": "/path/to/parent-folder",
+  "created_output_root_path": "/path/to/created-output-root",
+  "selected_subfolders": ["/path/to/parent-folder/bundle-a", "/path/to/parent-folder/bundle-b"],
+  "page_width": 3000,
+  "page_height": 3000,
+  "format": "JPG",
+  "collage_template": "feature-spread"
+}
+```
+`collage_template`, `image_fit` and the output quality fields work as for
+`/generate-cover-collage`.
+
+**Response fields**
+- `success` (bool)
+- `created_output_root_path` (str)
+- `processed_folders`, `selected_folders`, `total_detected_folders`,
+  `generated_folders` (int): as for `/generate-all-folders`
+- `bundle_results` (list): per bundle, `folder_name`, `success`,
+  `pages_generated`, `total_images`, `output_path`, `output_files` and `message`
+- `message` (str)
+
+### `POST /api/jobs/upscale-images`
+Makes every image of a folder bigger, saving each as a PNG and as a JPG in an
+`Upscaled` folder inside `output_path`: `Upscaled/PNG/<name>.png` and
+`Upscaled/JPG/<name>.jpg`. The PNG keeps any transparency; the JPG is
+flattened onto white. Images are resampled with Lanczos, which keeps edges
+smooth but adds no detail.
+
+**Request body**
+```json
+{
+  "folder_path": "/path/to/images",
+  "output_path": "/path/to/output",
+  "scale": 2,
+  "dpi": 300
+}
+```
+- `scale` (`2` | `3` | `4`, default `2`): how many times bigger each side becomes.
+- `dpi` (int, 1-1200, default `300`): stamped into every file.
+- Each file keeps its image's name, so upscaling again replaces what the last
+  run made.
+- Files sharing a name in different formats, such as `art.png` and `art.jpg`,
+  would be saved over each other, so one gives both formats: PNG first, then
+  WebP, then JPG.
+- Upscaled images are capped at 100 megapixels; an image that would pass that
+  is left out and named in the response.
+
+**Response fields**
+- `success` (bool): whether any image was upscaled
+- `scale` (int)
+- `total_images` (int): images upscaled
+- `output_path` (str): the `Upscaled` folder
+- `png_folder`, `jpg_folder` (str): the two folders inside it
+- `output_files` (list[str]): every file written
+- `images_skipped` (int): files that could not be read as images
+- `too_large_files` (list[str]): images left out for passing the cap
+- `same_name_files` (list[str]): files left out for sharing a name with the
+  image that was used
+- `message` (str)
+
+### `POST /api/jobs/upscale-images-batch`
+Upscales each selected bundle into `<created_output_root_path>/<bundle>/Upscaled`.
+
+**Request body**
+```json
+{
+  "parent_folder_path": "/path/to/parent-folder",
+  "created_output_root_path": "/path/to/created-output-root",
+  "selected_subfolders": ["/path/to/parent-folder/bundle-a", "/path/to/parent-folder/bundle-b"],
+  "scale": 4,
+  "dpi": 300
+}
+```
+
+**Response fields**
+- `success` (bool)
+- `created_output_root_path` (str)
+- `processed_folders`, `selected_folders`, `total_detected_folders`,
+  `generated_folders` (int): as for `/generate-all-folders`
+- `scale` (int)
+- `bundle_results` (list): per bundle, `folder_name`, `success`,
+  `total_images`, `output_path`, `images_skipped`, `too_large_files`,
+  `same_name_files` and `message`
+- `message` (str)
+
 ---
 
 ## Using the app
-1. Run `pasteup` and open `http://127.0.0.1:8000/`.
+1. Run `pasteup`; it opens in your browser.
 2. **Pick your clip art.** Choose **One bundle** (a folder of images) or **Many
-   bundles** (a folder with one folder inside per bundle), enter the folder and
-   click **Scan folder**. Results go in a `---Created---` folder next to it.
+   bundles** (a folder with one folder inside per bundle), then click
+   **Browse…**: open folders until you're in the right one, and **Use this
+   folder** scans it. Or type or paste its path and click **Scan folder**.
+   Results go in a `---Created---` folder next to it.
    - One bundle: **Folder check** says how many images it found and how many
      full sheets of 12 they make. If the folder holds only other folders, pick
      one under **Choose folders**.
@@ -338,8 +524,8 @@ Used by the UI in **Many bundles** mode. Iterates bundle folders under a parent
      Untick any you want to skip. A bundle that fails its check can be unticked,
      or fixed and checked again with **Check selected bundles**.
 3. **Set up the page.** Size, units, DPI and format apply to sheets and covers
-   alike. **Clean up white backgrounds** can make near-white backgrounds pure
-   white or transparent.
+   alike, and DPI to upscaled images too. **Clean up white backgrounds** can
+   make near-white backgrounds pure white or transparent.
 4. **Make your images.**
    - **Preview sheets:** every image, 12 to a page (`POST /api/jobs/generate`,
      or `POST /api/jobs/generate-all-folders` for many bundles), optionally with a
@@ -348,6 +534,10 @@ Used by the UI in **Many bundles** mode. Iterates bundle folders under a parent
      (`POST /api/jobs/generate-cover-collage`, or
      `POST /api/jobs/generate-cover-collage-batch`). **Only use certain images**
      limits it to the files you name.
+   - **Upscaled images:** every image 2x, 3x or 4x bigger, as a PNG and a JPG
+     in an `Upscaled` folder (`POST /api/jobs/upscale-images`, or
+     `POST /api/jobs/upscale-images-batch`). It runs on its own, with no
+     sheets or cover needed.
 5. **Your files** lists what was made and where it was saved; **Copy** puts a
    path on the clipboard.
 
@@ -360,27 +550,20 @@ Used by the UI in **Many bundles** mode. Iterates bundle folders under a parent
 - Trailing images that do not fill a complete page are left out by default; the
   response reports how many. Set `include_partial_page: true` to render that final
   page with its unused cells left white.
-
----
-
-## Acceptance Checklist (MVP Scope)
-- [ ] App runs locally with FastAPI and serves UI.
-- [ ] Folder scan validates path and reports supported image count.
-- [ ] Supported file types: JPG/JPEG/PNG/WEBP.
-- [ ] Estimated pages computed using fixed 12 images/page.
-- [ ] Generation creates fixed 4x3 grids with centered, aspect-preserving fit.
-- [ ] Transparent PNGs composite onto white rather than black.
-- [ ] Exports carry DPI metadata so the page has a real physical size.
-- [ ] Background cleaning only touches near-white areas connected to the border.
-- [ ] Output exports as PNG or JPG.
-- [ ] Exports use sequential naming (`page_###`) and avoid overwriting existing files.
-- [ ] API returns clear success/error messages for scan and generation.
-- [ ] UI supports end-to-end flow: input paths → scan → generate.
+- Upscaling resamples each image: edges stay smooth, but no detail is added,
+  so at 4x clip art looks soft. AI upscalers can invent detail; Pasteup has
+  none built in.
 
 ---
 
 ## Troubleshooting
 
+### `pasteup` runs an old version
+An earlier `pip install` of Pasteup can come first on your PATH. List every
+copy with `type -a pasteup` (macOS, Linux) or `where pasteup` (Windows), and
+remove the old one with `pip uninstall pasteup` in the environment it belongs
+to. `pasteup --version` then shows the version pipx or uv installed.
+
 ### Transparent PNGs used to come out with a black background
 Fixed. Transparent areas are composited onto the page's white rather than having
 the alpha channel dropped, which is what left `(0, 0, 0)` showing through. This
@@ -440,7 +623,7 @@ Symptoms:
 Fixes:
 - Confirm files are directly in the selected folder (non-recursive scan).
 - Confirm extensions are supported.
-- Check that files are not hidden/system placeholders.
+- Check the files aren't hidden: names starting with a dot are skipped.
 
 ### Permission errors
 Symptoms:
@@ -452,6 +635,12 @@ Fixes:
 - Verify write permission on output folder.
 - Try a user-owned directory (for example inside your home directory).
 
+### "Pasteup isn't allowed to open" Desktop, Documents or Downloads on a Mac
+macOS asks before a program reads these folders, and Pasteup reads them as the
+terminal app it runs in (Terminal, for the `pasteup --shortcut` launcher). If
+that was refused, turn the folder on for your terminal app under **System
+Settings › Privacy & Security › Files and Folders**, then restart Pasteup.
+
 ---
 
 ## How images are loaded