SLP-DEV1 · SLP-DEV1 · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026 · Aug 26, 2026
@@ -2,7 +2,9 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches:
+      - main
+      - "release/**"
   pull_request:
 
 permissions:

@@ -2,8 +2,8 @@ name: Release
 
 on:
   push:
-    tags:
-      - "v*"
+    branches:
+      - "release/v*"
 
 permissions:
   contents: write
@@ -28,14 +28,16 @@ jobs:
       - name: Verify project
         run: npm run check
 
-      - name: Verify tag matches package version
+      - name: Resolve and verify release version
         shell: pwsh
         run: |
           $package = Get-Content package.json -Raw | ConvertFrom-Json
-          $expectedTag = "v$($package.version)"
-          if ($env:GITHUB_REF_NAME -ne $expectedTag) {
-            throw "Release tag $env:GITHUB_REF_NAME does not match package.json version $expectedTag"
+          $releaseTag = "v$($package.version)"
+          $expectedBranch = "release/$releaseTag"
+          if ($env:GITHUB_REF_NAME -ne $expectedBranch) {
+            throw "Release branch $env:GITHUB_REF_NAME does not match package.json version $expectedBranch"
           }
+          "RELEASE_TAG=$releaseTag" | Out-File -FilePath $env:GITHUB_ENV -Encoding utf8 -Append
 
       - name: Assemble portable Windows package
         shell: pwsh
@@ -92,10 +94,16 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
-          gh release create $env:GITHUB_REF_NAME `
+          gh release view $env:RELEASE_TAG --repo $env:GITHUB_REPOSITORY *> $null
+          if ($LASTEXITCODE -eq 0) {
+            throw "Release $env:RELEASE_TAG already exists. Refusing to overwrite it."
+          }
+          $global:LASTEXITCODE = 0
+
+          gh release create $env:RELEASE_TAG `
             "OpenMockup-Studio-Windows-x64.zip" `
             "OpenMockup-Studio-Windows-x64.zip.sha256" `
             --repo $env:GITHUB_REPOSITORY `
-            --title "OpenMockup Studio $env:GITHUB_REF_NAME" `
-            --generate-notes `
-            --verify-tag
+            --target main `
+            --title "OpenMockup Studio $env:RELEASE_TAG" `
+            --generate-notes
@@ -2,31 +2,43 @@
 
 All notable user-facing changes to OpenMockup Studio should be documented here.
 
-The project follows a lightweight changelog format. Until formal releases are published regularly, the `Unreleased` section is the source of truth for upcoming changes.
+The project follows a lightweight changelog format.
 
 ## Unreleased
 
-### Repository and contributor experience
+## 0.19.0 - 2026-08-27
 
-- Refreshed the README around the batch-mockup use case and faster onboarding.
-- Added a single `npm run check` quality gate used locally and in CI.
-- Added contribution, security, architecture, roadmap, issue, and pull-request guidance.
-- Grouped GitHub Actions dependency updates to reduce maintenance noise.
-- Deferred automatic major React and TypeScript upgrades until they can be tested as dedicated migrations.
+### Editing and demo
+
+- Added the zero-install GitHub Pages demo for PNG, JPG, and WebP mockups.
+- Added a one-click sample project with original MIT-licensed demo artwork.
+- Added true four-corner perspective warping for flat image mockups, with draggable corner handles and matching batch-export geometry.
+- Fixed Fill Slot / cover rendering so artwork is clipped to the selected placement area in preview and export.
+- Fixed Auto Preview so switching designs cannot leave a previous design visible as the current preview.
 
-### Browser demo
+### Export reliability
 
-- Added a zero-install GitHub Pages deployment for PNG, JPG, and WebP mockups.
-- Added a dedicated `demo` build that uses the repository subpath correctly and omits the PSD design-server plugin.
-- Disabled PSD selection in the public demo and added an explicit link to the full local version.
-- Added the demo build to CI so static hosting regressions are caught before merge.
+- Made ZIP output collision-safe: duplicate filenames now receive deterministic numeric suffixes instead of silently replacing successful renders.
+- Made archive collision handling case-insensitive and kept the export report aligned with final ZIP paths.
 
-### Reliability
+### PSD and PSB reliability
 
-- Added a bounded Photopea initialization wait so PSD mode fails clearly instead of hanging forever when Photopea cannot load.
+- Added a bounded Photopea initialization wait with clear failure handling.
 - Made Photopea startup waits terminate cleanly when the client is destroyed.
-- Corrected `dev:public` guidance to explain that OpenMockup stays on localhost while the Cloudflare URL is only used as Photopea's public asset base.
+- Corrected public-development guidance so the local UI and temporary asset endpoint are described accurately.
+- Fixed PSB Additional Layer Information parsing to use Adobe's key-specific 4-byte and 8-byte tagged-block length rules.
+
+### Windows distribution
 
-### Application metadata
+- Added a self-contained Windows x64 release package with a portable runtime and locked dependencies.
+- Added one-click launchers for flat-image mode and PSD mode.
+- Added the PSD-mode helper binary to the portable package.
+- Added SHA-256 checksums for downloadable Windows release ZIPs.
 
+### Repository and contributor experience
+
+- Refreshed the README around the batch-mockup use case and faster onboarding.
+- Added a single npm run check quality gate used locally and in CI.
+- Added contribution, security, architecture, roadmap, issue, and pull-request guidance.
+- Grouped GitHub Actions dependency updates to reduce maintenance noise.
 - Improved page title and social/SEO metadata for hosted deployments.
@@ -4,15 +4,15 @@
 
 [![CI](https://github.com/SLP-DEV1/OpenMockup-Studio/actions/workflows/ci.yml/badge.svg)](https://github.com/SLP-DEV1/OpenMockup-Studio/actions/workflows/ci.yml)
 [![Demo](https://img.shields.io/badge/Try%20the%20demo-GitHub%20Pages-222222?logo=github)](https://slp-dev1.github.io/OpenMockup-Studio/)
+[![Windows Release](https://img.shields.io/badge/Windows-Portable%20Download-0078D4?logo=windows)](https://github.com/SLP-DEV1/OpenMockup-Studio/releases/latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
-[![Node.js 20.19+](https://img.shields.io/badge/Node.js-20.19%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
 [![Made with React](https://img.shields.io/badge/React-TypeScript-61DAFB?logo=react&logoColor=white)](https://react.dev/)
 
 **Free · local-first · no account · no subscription**
 
 ### [▶ Try OpenMockup Studio in your browser](https://slp-dev1.github.io/OpenMockup-Studio/)
 
-The public demo needs no installation and supports PNG, JPG, and WebP mockups. Files stay in the browser. PSD Smart Objects require the local version because that workflow uses Photopea and a temporary asset endpoint.
+The public demo needs no installation and supports PNG, JPG, and WebP mockups. Click **Try sample project** to see it working immediately. Files stay in the browser. PSD Smart Objects require the local version because that workflow uses Photopea and a temporary asset endpoint.
 
 ![OpenMockup Studio interface](docs/screenshot.png)
 
@@ -25,34 +25,37 @@ OpenMockup Studio is built for Etsy, WooCommerce, marketplace sellers, artists,
 - **Batch-first:** create every mockup/design combination in one run.
 - **PSD Smart Object support:** automate compatible PSD templates through Photopea.
 - **Flat image support:** use PNG, JPG, and WebP mockups directly in the browser.
-- **Visual placement editor:** move, scale, rotate, anchor, fit, and adjust opacity.
+- **4-corner perspective:** warp artwork onto angled signs, frames, screens, packaging, and other surfaces.
+- **Visual placement editor:** move, scale, rotate, anchor, fit, adjust opacity, or drag perspective corners.
 - **Marketplace-ready exports:** crop, resize, watermark, rename, convert, and ZIP results.
+- **Collision-safe batches:** duplicate output names are preserved automatically instead of being overwritten.
 - **Local-first workflow:** flat-image rendering stays in your browser.
 - **Self-hostable:** no account or hosted service is required.
 
 ## Quick start
 
 ### Zero-install browser demo
 
-Open the [GitHub Pages demo](https://slp-dev1.github.io/OpenMockup-Studio/) and add a PNG, JPG, or WebP mockup plus one or more designs. Preview and batch export work directly in the browser.
+Open the [GitHub Pages demo](https://slp-dev1.github.io/OpenMockup-Studio/) and click **Try sample project**, or add your own PNG, JPG, or WebP mockup plus one or more designs. Preview, perspective editing, and batch export work directly in the browser.
 
-The demo intentionally disables PSD uploads. Use the local version below for PSD Smart Objects.
+The demo intentionally disables PSD uploads. Use the Windows package or developer setup below for PSD Smart Objects.
 
-### Windows: full local version
+### Windows: portable release — recommended
 
-1. [Download the repository as a ZIP](https://github.com/SLP-DEV1/OpenMockup-Studio/archive/refs/heads/main.zip) and extract it.
-2. Install [Node.js 20.19+](https://nodejs.org/).
-3. Double-click the launcher you need:
+1. Open [GitHub Releases](https://github.com/SLP-DEV1/OpenMockup-Studio/releases/latest).
+2. Download `OpenMockup-Studio-Windows-x64.zip` and optionally its `.sha256` checksum.
+3. Extract the ZIP.
+4. Double-click the launcher you need:
 
 | Launcher | Use it for |
 | --- | --- |
-| `start-local.bat` | PNG, JPG, and WebP mockups; fully local app server |
-| `start.bat` | PSD mode with Photopea and a temporary HTTPS asset tunnel |
-| `stop.bat` | Stop the local server and tunnel |
+| `start-openmockup.bat` | PNG, JPG, and WebP mockups; local image-mode server |
+| `start-openmockup-psd.bat` | PSD mode with Photopea and the bundled temporary asset tunnel helper |
+| `stop.bat` | Stop a remaining local server/tunnel process |
 
-The app opens at `http://127.0.0.1:5173`. Keep the launcher window open while you work.
+The portable package includes its own runtime, dependencies, and PSD-mode tunnel helper. **You do not need to install Node.js, npm, or cloudflared.** The app opens at `http://127.0.0.1:5173`; keep the launcher window open while you work.
 
-### Developers
+### Developers / source install
 
 ```bash
 git clone https://github.com/SLP-DEV1/OpenMockup-Studio.git
@@ -61,7 +64,7 @@ npm ci
 npm run dev
 ```
 
-For PSD support with a temporary Cloudflare Tunnel, install `cloudflared` and run:
+Source development requires Node.js 20.19+ (Node 22 recommended). For PSD support with a temporary Cloudflare Tunnel, install `cloudflared` and run:
 
 ```bash
 npm run dev:public
@@ -72,7 +75,7 @@ npm run dev:public
 1. Add one or more PSD, PNG, JPG, or WebP mockups.
 2. Add your PNG, JPG, or WebP designs.
 3. Select a mockup and a design.
-4. Adjust placement, scale, rotation, fit, and opacity.
+4. Adjust placement, scale, rotation, fit, opacity, or enable 4-corner perspective for flat-image mockups.
 5. Preview the result.
 6. Export all combinations as a ZIP.
 
@@ -82,6 +85,7 @@ npm run dev:public
 | --- | ---: | ---: |
 | PNG/JPG/WebP mockups | Yes | — |
 | PSD Smart Objects | — | Yes |
+| 4-corner perspective | Yes | — |
 | Rendering | Browser Canvas | Photopea iframe |
 | Public asset URL needed | No | Yes |
 | Batch ZIP export | Yes | Yes |
@@ -92,7 +96,7 @@ npm run dev:public
 
 Flat image rendering stays in the browser. That includes the public GitHub Pages demo: there is no upload backend in the static demo build.
 
-PSD mode is different: Photopea must be able to download the selected design from a public HTTPS address. `start.bat` / `npm run dev:public` creates a temporary Cloudflare Tunnel for that asset flow.
+PSD mode is different: Photopea must be able to download the selected design from a public HTTPS address. `start-openmockup-psd.bat`, `start.bat`, or `npm run dev:public` creates a temporary Cloudflare Tunnel for that asset flow. The OpenMockup UI itself remains on localhost.
 
 Do not use PSD mode for confidential assets unless you understand and accept this data flow. OpenMockup Studio is not affiliated with Photopea.
 
@@ -130,23 +134,24 @@ Example environment variables are documented in [`.env.example`](.env.example).
 
 ## Troubleshooting PSD mode
 
-**Photopea cannot fetch the design:** use `start.bat` or `npm run dev:public`; localhost-only asset URLs are not reachable by Photopea.
+**Photopea cannot fetch the design:** use `start-openmockup-psd.bat`, `start.bat`, or `npm run dev:public`; localhost-only asset URLs are not reachable by Photopea.
 
-**A `trycloudflare.com` address expired:** open the app at `http://127.0.0.1:5173`, run `stop.bat`, then start PSD mode again to create a new temporary tunnel.
+**A `trycloudflare.com` address expired:** open the app at `http://127.0.0.1:5173`, stop the previous process, then start PSD mode again to create a new temporary tunnel.
 
-**A Smart Object is not detected:** verify that the PSD really contains a Smart Object, unlock unusual nested layers where possible, and simplify highly unusual PSD structures before retrying.
+**A Smart Object is not detected:** verify that the PSD/PSB really contains a Smart Object, unlock unusual nested layers where possible, and simplify highly unusual document structures before retrying.
 
 PSD batches run serially to keep the Photopea session stable.
 
 ## Project health
 
-The repository uses strict TypeScript checks, Vitest, production and demo builds in GitHub Actions, and Dependabot. Core placement, naming, mockup, persistence, cache, and export behavior has automated coverage.
+The repository uses strict TypeScript checks, Vitest, production and demo builds in GitHub Actions, Dependabot, and versioned Windows release builds with SHA-256 checksums. Core placement, perspective, naming, mockup, persistence, cache, PSB parsing, and export behavior has automated coverage.
 
 - [Roadmap](docs/ROADMAP.md)
 - [Architecture](docs/ARCHITECTURE.md)
 - [Contributing](CONTRIBUTING.md)
 - [Security policy](SECURITY.md)
 - [Changelog](CHANGELOG.md)
+- [Releases](https://github.com/SLP-DEV1/OpenMockup-Studio/releases)
 
 ## Contributing
 

@@ -0,0 +1,15 @@
+# Releasing OpenMockup Studio
+
+OpenMockup Studio publishes portable Windows builds from a protected release branch convention.
+
+## Release checklist
+
+1. Update `package.json` to the intended semantic version.
+2. Move user-facing changes from `Unreleased` into a dated changelog section.
+3. Run `npm ci` and `npm run check` through the pull-request CI.
+4. Merge the release-preparation pull request into `main` only when CI is green.
+5. Create a branch named `release/vX.Y.Z` from the final `main` commit.
+6. The Release workflow verifies that the branch name matches `package.json`, runs the full checks again, builds the portable Windows x64 ZIP, creates its SHA-256 checksum, and publishes tag `vX.Y.Z` against `main`.
+7. Verify both downloadable assets on the GitHub Release before closing the release issue.
+
+The workflow refuses to overwrite an existing release tag.
@@ -11,7 +11,7 @@ The roadmap is ordered by expected user value and by the technical foundation ea
 
 ## Editing and realism
 
-- [ ] Four-point perspective transforms for flat image mockups
+- [x] Four-point perspective transforms for flat image mockups
 - [ ] Reusable masks for PNG, JPG, and WebP mockups
 - [ ] Shadow, highlight, and blend-mode controls
 - [ ] Drag-and-drop design ordering and per-product placement defaults
@@ -27,7 +27,7 @@ The roadmap is ordered by expected user value and by the technical foundation ea
 
 - [ ] Authenticated self-hosted asset service with rate limits
 - [x] Static image-mode demo deployment via GitHub Pages
-- [ ] Versioned releases and downloadable Windows packages
+- [x] Versioned releases and downloadable Windows packages
 - [ ] Optional shared presets for hosted deployments
 
 ## Want to help?

@@ -1,6 +1,6 @@
 {
   "name": "openmockup-studio",
-  "version": "0.18.4",
+  "version": "0.19.0",
   "private": true,
   "type": "module",
   "engines": {