From f56b9099d6d50f91b8dcb5ad122dda644e8aa69d Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:41:31 +0200 Subject: [PATCH 1/8] release: bump version to 0.19.0 --- package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/package.json b/package.json index 7a675b2..cc0dac5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "openmockup-studio", - "version": "0.18.4", + "version": "0.19.0", "private": true, "type": "module", "engines": { From 7bee59a79d4ee07d5ca16ae3ef38020f4c7c0c46 Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:41:49 +0200 Subject: [PATCH 2/8] release: allow controlled release branch publishing --- .github/workflows/release.yml | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 64ac0bb..b6888cc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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 $env:GITHUB_SHA ` + --title "OpenMockup Studio $env:RELEASE_TAG" ` + --generate-notes From bf574d36b6c53f0ddf238c14df13b0cf5674c605 Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:42:39 +0200 Subject: [PATCH 3/8] docs: prepare 0.19.0 changelog --- CHANGELOG.md | 44 ++++++++++++++++++++++++++++---------------- 1 file changed, 28 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 7c2ef38..dfe90d5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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. From 241dc6419e32e27a54dd74c0ce2bc06ffd40fbd8 Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:42:49 +0200 Subject: [PATCH 4/8] docs: mark perspective and Windows releases complete --- docs/ROADMAP.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 6585566..d8984a1 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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? From 15c01e2f293f1c49ef12fde5a543102f6b444b42 Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:44:26 +0200 Subject: [PATCH 5/8] docs: promote portable Windows release --- README.md | 47 ++++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index cb562a1..fe357a7 100644 --- a/README.md +++ b/README.md @@ -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,8 +25,10 @@ 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. @@ -34,25 +36,26 @@ OpenMockup Studio is built for Etsy, WooCommerce, marketplace sellers, artists, ### 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 From 28df079509e14696caee2474400f2586396b19ab Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:44:55 +0200 Subject: [PATCH 6/8] release: always tag the main branch --- .github/workflows/release.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b6888cc..ce70865 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -104,6 +104,6 @@ jobs: "OpenMockup-Studio-Windows-x64.zip" ` "OpenMockup-Studio-Windows-x64.zip.sha256" ` --repo $env:GITHUB_REPOSITORY ` - --target $env:GITHUB_SHA ` + --target main ` --title "OpenMockup Studio $env:RELEASE_TAG" ` --generate-notes From 8d63ef1d6393a4b9472f27705b0d2af7d520ad17 Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:45:47 +0200 Subject: [PATCH 7/8] docs: add release checklist --- docs/RELEASING.md | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 docs/RELEASING.md diff --git a/docs/RELEASING.md b/docs/RELEASING.md new file mode 100644 index 0000000..1591c65 --- /dev/null +++ b/docs/RELEASING.md @@ -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. From a2c9fe605bf73076027d953f74873abd14c66753 Mon Sep 17 00:00:00 2001 From: SLP-DEV1 Date: Thu, 27 Aug 2026 01:47:12 +0200 Subject: [PATCH 8/8] ci: verify release branches before publishing --- .github/workflows/ci.yml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 7cce099..609a9bc 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,7 +2,9 @@ name: CI on: push: - branches: [main] + branches: + - main + - "release/**" pull_request: permissions: