kyeunga25 · kyeunga25 · Jul 15, 2026 · Jul 15, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to Wallpect are recorded in this file. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.1.0 - 2026-07-16
+
+### Added
+
+- Privacy-first browser-only wallpaper composition and exact-resolution PNG, JPEG, and WebP export.
+- 74 Apple display profiles: 27 iPhone, 20 iPad, and 27 Mac/display profiles.
+- Complete requested coverage for iPhone 13 and later, iPad models introduced in 2021 or later, and Macs with built-in displays introduced in 2021 or later, current through July 2026.
+- Traditional Chinese, Simplified Chinese, and English interfaces.
+- Desktop and mobile editor layouts, device search, recent devices, orientation controls, safe-area guides, and system-overlay previews.
+- Automated unit, integration, browser, privacy, and exact-output checks.
+- MIT license, contribution guide, bilingual project documentation, and Cloudflare Pages deployment configuration.
+
+### Changed
+
+- Device previews now use profile-specific screen corner geometry and distinguish MacBook laptop frames from desktop Mac/display frames.
+- The device picker now exposes model year, diagonal size, physical resolution, accuracy level, category counts, and searchable profile metadata.
+- Apple device sources and review dates were refreshed on 2026-07-16.
+
+### Security
+
+- Uploaded images remain in browser memory and are not sent to an upload API or analytics service.
+- Local secrets, credentials, build output, browser reports, and editor/OS metadata are excluded from version control.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,89 @@
+# Contributing to Wallpect
+
+[繁體中文](#繁體中文) · [English](#english)
+
+## 繁體中文
+
+感謝你協助改善 Wallpect。請讓每個 issue 或 pull request 專注於一項清楚的問題，並說明對用戶可見的影響。
+
+### 開始之前
+
+- 使用 Node.js 22 或更新版本。
+- 執行 `npm ci` 安裝鎖定版本的依賴。
+- 不要加入圖片上傳 API、圖片分析、帳戶追蹤或其他把用戶圖片傳離瀏覽器的功能。
+- 預覽與匯出必須共用相同的變換及渲染計算。
+- 裝置資料必須位於 `src/data/devices`，不要寫入 UI 元件。
+- 推算或估算的設定檔資料不得標示為 `verified`。
+
+### 開發流程
+
+1. 建立範圍清晰的分支及變更。
+2. 為行為修正或新邏輯加入相應測試。
+3. 修改裝置設定檔時，提供來源、檢查日期、證據類型及準確度等級。
+4. 不要提交私人桌布、Apple 專有素材、憑證、環境檔或建置產物。
+5. 執行以下檢查：
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+涉及完整編輯流程、響應式版面或瀏覽器行為時，亦應執行：
+
+```bash
+npm run test:e2e
+```
+
+### Pull request 清單
+
+- 清楚說明問題、處理方式及用戶影響。
+- 列出已執行的測試及結果。
+- UI 變更附上不含私人圖片的前後畫面。
+- 裝置資料變更連結到可靠來源，並依照[準確度政策](docs/ACCURACY_POLICY.md)標示資料。
+- 確認上傳圖片仍只留在瀏覽器中。
+
+一般錯誤或功能建議可使用 GitHub Issues。涉及未公開漏洞或可能洩露資料的問題，請勿在公開 issue 中附上敏感細節。
+
+## English
+
+Thank you for helping improve Wallpect. Keep each issue or pull request focused on one clear problem, and explain the user-visible impact.
+
+### Before you start
+
+- Use Node.js 22 or newer.
+- Run `npm ci` to install the locked dependency versions.
+- Do not add image upload APIs, image analytics, account tracking, or any feature that sends a user's image out of the browser.
+- Preview and export must share the same transform and rendering calculations.
+- Keep device data in `src/data/devices`, outside UI components.
+- Never label derived or estimated profile data as `verified`.
+
+### Development workflow
+
+1. Create a focused branch and change set.
+2. Add tests for behavior fixes or new logic.
+3. For device profiles, include sources, review dates, evidence types, and accuracy levels.
+4. Do not commit private wallpapers, proprietary Apple assets, credentials, environment files, or generated build output.
+5. Run the core checks:
+
+```bash
+npm run lint
+npm test
+npm run build
+```
+
+Also run the end-to-end suite when changing the complete editor flow, responsive layout, or browser behavior:
+
+```bash
+npm run test:e2e
+```
+
+### Pull request checklist
+
+- Explain the problem, approach, and user impact.
+- List the tests run and their results.
+- Include before/after images for UI changes, without private imagery.
+- Link device-data changes to reliable sources and follow the [accuracy policy](docs/ACCURACY_POLICY.md).
+- Confirm that uploaded image content still stays in the browser.
+
+Use GitHub Issues for ordinary bugs and feature requests. Do not place sensitive details in a public issue when reporting an undisclosed vulnerability or possible data exposure.
diff --git a/LICENSE b/LICENSE
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kyeunga25
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,127 +1,117 @@
+<div align="center">
+
 # Wallpect
 
-Wallpect 是一個以隱私為優先的桌布預覽與適配工具。
+**Privacy-first wallpaper preview and fitting for Apple devices.**
 
-上傳圖片、選擇 Apple 裝置設定檔，即可檢查精確解析度、長寬比、裁切範圍、開孔與安全區域覆疊，並以目標裝置的解析度匯出桌布。介面首次載入時預設使用繁體中文，也可切換至簡體中文或英文；語言偏好只會儲存在瀏覽器本機。
+[Open Wallpect](https://wallpect.k-y.cc) · [繁體中文](README.zh-Hant.md) · [Documentation](#documentation)
 
-## 設計原則
+[![CI](https://github.com/kyeunga25/wallpect/actions/workflows/ci.yml/badge.svg)](https://github.com/kyeunga25/wallpect/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-2563eb.svg)](LICENSE)
+[![Live app](https://img.shields.io/badge/Live-wallpect.k--y.cc-16a34a.svg)](https://wallpect.k-y.cc)
 
-- 圖片只留在瀏覽器中
-- 精確的輸出尺寸
-- 以資料驅動裝置設定檔
-- 預覽與匯出共用相同的渲染邏輯
-- 清楚標示資料準確度
+</div>
 
-## MVP 已包含功能
+![Wallpect desktop workspace showing an iPhone wallpaper preview and export controls](docs/screenshots/wallpect-desktop.png)
 
-- 12 個代表性 iPhone、5 個 iPad，以及 6 個 Mac／顯示器設定檔
-- 在本機解碼 PNG、JPEG 與 WebP，安全限制為 30 MB／最長邊 12,000 px
-- 直接拖曳、雙指或滾動縮放、鍵盤微調、數值平移、旋轉，以及填滿／完整顯示
-- 純色、透明與模糊延伸背景
-- 純桌布、鎖定畫面／桌面與安全區域預覽模式
-- 以資料驅動的開孔、安全區域、鎖定畫面、選單列與 Dock 覆疊
-- 每部支援裝置分別保存直向／橫向構圖
-- 以 Canvas 匯出精確解析度的 PNG、JPEG 與 WebP
-- 響應式桌面與流動版工作區
-- 預設繁體中文，並可切換簡體中文或英文；偏好設定保存在本機
-- 首次載入正式版本後可離線快取應用程式外殼
+Wallpect helps you compose an image for a selected Apple device, inspect likely system obstructions, and export it at the profile's exact pixel dimensions. Image decoding, editing, preview, and export all happen inside your browser—there is no image upload endpoint, account, or third-party image analysis.
 
-## 本機開發
+## What you can do
 
-需求：Node.js 22 或以上版本，以及 npm。
+| Inspect                                                                         | Compose                                                                          | Export                                                                           |
+| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| Check aspect ratio, cutouts, Safe Area, Lock Screen, menu bar, and Dock guides. | Drag, zoom, pan, rotate, fill, fit, or extend an image against a device preview. | Download PNG, JPEG, or WebP at the selected profile's physical pixel dimensions. |
 
-```bash
-npm install
-npm run dev
-```
+### Highlights
 
-品質檢查：
+- 74 profiles: 27 iPhone, 20 iPad, and 27 Mac/display profiles, covering every requested display family introduced from 2021 through July 2026
+- Local PNG, JPEG, and WebP decoding with file, dimension, and pixel-count limits
+- Portrait and landscape compositions stored independently for each device
+- Solid, transparent, or blurred-extension backgrounds
+- Shared transform and Canvas rendering calculations for preview and export
+- Responsive desktop and mobile workspaces
+- Traditional Chinese by default, with Simplified Chinese and English options
+- Offline app-shell caching after the first production visit
+- Explicit accuracy levels for published, derived, and estimated device data
 
-```bash
-npm run lint
-npm test
-npm run build
-npm run test:e2e
-```
-
-端對端測試涵蓋 Chromium、WebKit、本機安裝的 Microsoft Edge，以及 Firefox。
+## Try it
 
-## 架構
-
-```text
-src/components     UI 面板與裝置預覽介面
-src/state          編輯器狀態、各裝置的構圖變換與偏好設定
-src/core           適配、變換、驗證、Canvas 渲染與匯出邏輯
-src/data/devices   資料驅動的 Apple 裝置設定檔
-src/i18n           預設語言、偏好保存與介面翻譯
-src/types          領域模型
-tests/unit         計算與資料驗證測試
-tests/integration  元件互動測試
-tests/e2e          從上傳至匯出的 Playwright 流程
-```
+1. Open [wallpect.k-y.cc](https://wallpect.k-y.cc).
+2. Use the bundled sample or choose an image from your device.
+3. Select a device profile and orientation.
+4. Adjust the composition and enable the guides you want to inspect.
+5. Choose PNG, JPEG, or WebP and export at the displayed resolution.
 
-預覽與匯出均會呼叫 `renderWallpaper`。平移值會儲存為目標畫布的標準化比例，因此縮小的預覽與完整解析度匯出可保持相同構圖。
+Your image stays in browser memory and is released when it is replaced or the page is closed. Only preferences such as the recent device identifier may be saved in `localStorage`.
 
-## 私隱與限制
+<p align="center">
+  <img src="docs/screenshots/wallpect-mobile.png" width="320" alt="Wallpect mobile workspace showing the device selector and wallpaper preview">
+</p>
 
-上傳圖片的像素、名稱與 Canvas 資料不會傳送到伺服器。最近使用的裝置識別碼可能儲存在 `localStorage`；圖片與 object URL 只存在記憶體中，在圖片被取代或頁面關閉時釋放。
+## Accuracy, by design
 
-Wallpect 會按所選設定檔輸出精確像素尺寸，但 iOS、iPadOS 與 macOS 仍可能套用系統層級的縮放、延伸桌布、透視、景深或填滿效果。
+Wallpect separates published display facts from geometry that must be measured or derived:
 
-Wallpect 是獨立工具，與 Apple Inc. 無關，亦未獲其背書。
+- The selected profile defines the export pixel dimensions and aspect ratio.
+- Device frames and system overlays are composition guides, not official Apple renderings.
+- Profiles declare an accuracy level; the initial data set is intentionally marked `high`, not `verified`, because much of the obstruction geometry is derived.
+- iOS, iPadOS, and macOS may still apply system-level zoom, extension, depth, or fill behavior.
 
-## 安全控制
+See the [accuracy policy](docs/ACCURACY_POLICY.md) for the complete definition and reporting requirements.
 
-- 沒有圖片上傳端點、帳號系統、分析服務或第三方圖片處理
-- 圖片進入編輯器前會驗證 MIME、檔案大小、最長邊與總像素數
-- Cloudflare Pages 使用嚴格的 Content Security Policy 與瀏覽器權限政策
-- 同源 Service Worker 快取只使用 Wallpect 專屬快取名稱
-- 正式版本停用 source map
-- Git 會排除本機環境檔、憑證、證書、建置輸出與測試產物
+## Local development
 
-## 部署
+Requirements: Node.js 22 or newer and npm.
 
-專案已設定使用 Cloudflare Pages：
+```bash
+git clone https://github.com/kyeunga25/wallpect.git
+cd wallpect
+npm ci
+npm run dev
+```
 
-- 建置指令：`npm run build`
-- 輸出目錄：`dist`
-- 預定正式網域：`wallpect.k-y.cc`
-- 預定開發網域：`dev.wallpect.k-y.cc`
+Run the core quality checks:
 
-請參閱 [部署指南](docs/DEPLOYMENT.md)、[裝置設定檔指南](docs/DEVICE_PROFILE_GUIDE.md)、[準確度政策](docs/ACCURACY_POLICY.md)，以及已使用中文撰寫的[產品需求與實作計劃](docs/WALLPECT_PRODUCT_REQUIREMENTS_AND_IMPLEMENTATION_PLAN.md)。
+```bash
+npm run lint
+npm test
+npm run build
+```
 
----
+The Playwright suite additionally covers Chromium, WebKit, Microsoft Edge, and Firefox:
 
-## English
+```bash
+npm run test:e2e
+```
 
-Wallpect is a privacy-first wallpaper preview and fitting tool.
+## Architecture
 
-Upload an image, select an Apple device profile, inspect its exact resolution, aspect ratio, crop area, cutout, and safe-area overlays, then export a wallpaper at the target device resolution. The interface defaults to Traditional Chinese on first load and can be switched to Simplified Chinese or English; the preference stays in the browser.
+| Path               | Responsibility                                                |
+| ------------------ | ------------------------------------------------------------- |
+| `src/components`   | Editor panels, controls, and device preview UI                |
+| `src/state`        | Editor state, per-device transforms, and preferences          |
+| `src/core`         | Fitting, transforms, validation, Canvas rendering, and export |
+| `src/data/devices` | Data-driven Apple device profiles outside the UI              |
+| `src/i18n`         | Locale selection, persistence, and translations               |
+| `tests`            | Unit, integration, and end-to-end coverage                    |
 
-### Principles
+Preview and export both call `renderWallpaper`. Pan offsets use the target canvas's normalized coordinate space, so a scaled preview and full-resolution export preserve the same composition.
 
-- Images stay in the browser
-- Exact output dimensions
-- Device profiles are data-driven
-- Preview and export share the same rendering logic
-- Accuracy levels are disclosed
+## Documentation
 
-### Local development
+- [Accuracy policy](docs/ACCURACY_POLICY.md)
+- [Device profile guide](docs/DEVICE_PROFILE_GUIDE.md)
+- [Deployment guide](docs/DEPLOYMENT.md)
+- [Product requirements and implementation plan](docs/WALLPECT_PRODUCT_REQUIREMENTS_AND_IMPLEMENTATION_PLAN.md)
+- [Implementation checklist](TODO.md)
+- [Changelog](CHANGELOG.md)
 
-Requirements: Node.js 22+ and npm.
+## Contributing
 
-```bash
-npm install
-npm run dev
-```
+Issues and focused pull requests are welcome. Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing device data, rendering behavior, or privacy-sensitive code.
 
-Quality checks:
+## License and disclaimer
 
-```bash
-npm run lint
-npm test
-npm run build
-npm run test:e2e
-```
+Wallpect is available under the [MIT License](LICENSE).
 
-The end-to-end suite covers Chromium, WebKit, the locally installed Microsoft Edge, and Firefox. See the Chinese sections above for the complete feature, architecture, privacy, security, and deployment reference.
+Wallpect is an independent tool. It is not affiliated with or endorsed by Apple Inc. Apple product names are used only to identify compatible device profiles.