Wallpect

Privacy-first wallpaper preview and fitting for Apple devices.

Open Wallpect · 繁體中文（主要文件） · Documentation

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. The production app is deployed on Cloudflare Workers using the assets-only Static Assets mode. Image decoding, editing, preview, and export all happen inside your browser—there is no image upload endpoint, account, database, or third-party image analysis.

What you can do

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.

Highlights

• 47 distinct canvas configurations: 19 iPhone, 11 iPad, and 17 Mac/Apple-display configurations covering 191 named models from 2007–2026
• Devices with the same wallpaper canvas and obstruction geometry share one option; one search spans iPhone, iPad, and Mac model names, years, diagonals, and resolutions
• The desktop device browser stays compact after selection so composition controls remain in reach; the mobile device tab keeps the complete searchable catalogue visible
• Local PNG, JPEG, and WebP decoding, limited to 30 MB, 12,000 px on the longest edge, and 72 megapixels
• The bundled demo is synthetic project artwork with its content-authenticity provenance preserved; it contains no Apple product asset or user image
• The image card shows the active local thumbnail; replacing an image clears old composition histories for every device and orientation so a previous image's position is not reused accidentally
• Portrait and landscape compositions stored independently for each device
• Per-device/orientation undo and redo with grouped gestures, keyboard shortcuts, and one-pixel position nudging
• First-screen quick positioning to center an image or move it by 10% of the active canvas without entering X/Y values
• Contextual Content position controls expose useful left/centre/right or top/middle/bottom alignments when the image has room to move, bringing people, logos, or text into view without repeated dragging; every alignment remains undoable
• A live-value Precise controls disclosure keeps exact X/Y, one-pixel nudging, and rotation available without crowding the everyday adjustment flow
• Zoom, rotation, and export-quality tracks fill to the actual current value and expose the same value with its unit to assistive technology
• One-tap original-composition comparison without replacing edited values or export output
• Distraction-free focus preview that temporarily hides editing panels without changing the composition
• One-tap portrait/landscape switching directly on the preview, including while Adjust or focus preview remains active
• Mode-specific guide switches automatically open the matching Lock Screen/Desktop or Safe area preview so every change is immediately visible; the composition grid and device cutout remain mode-independent
• A mobile “More controls / More preview” switch for balancing long editing panels against the live preview, including compact 320 px-wide screens
• Mobile opens directly on Adjust and returns there after a local image or device is selected, avoiding repeated switches between a long catalogue and composition controls
• First-in-panel plain-language crop and source-pixel enlargement feedback on desktop and mobile, with undoable Show whole image and content-position actions for either preserving the whole source or choosing which part to show; solid, transparent, and blurred-extension choices remain nearby for uncovered areas
• Exact output and the primary download remain in the first desktop viewport at common MacBook heights; format, filename, and guide controls remain available under Export options
• 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

Try it

1. Open wallpect.k-y.cc.
2. Use the bundled sample or choose an image from your device. The image-card thumbnail confirms what is being edited. Choosing another image starts a fresh composition instead of reusing the previous image's offsets or undo history.
3. Select a device profile and orientation. On desktop, use Change to reopen the full device browser whenever needed. Mobile returns to Adjust after an image or device is selected; use the rotate action on the preview to switch orientation without leaving the current editing view.
4. Check the current crop and estimated enlargement at the start of Adjust. If important content is heavily cropped, use Show whole image for an undoable automatic fit or Content position to reveal the source's left/centre/right or top/middle/bottom without repeated dragging. Both use dimensions and shared rendering geometry only; they do not analyse the image. Choose the nearby solid, transparent, or blurred-extension background for uncovered areas. Use Quick position to center the image or move it in 10% steps when composing manually. Open Precise controls for exact X/Y values, one-pixel nudging, and rotation; its summary keeps the current values visible while folded. Drag and undo/redo remain directly available. On mobile, use More controls when a long panel needs space, compare the original framing, or enter focus preview as needed.
5. In Overlays, change Safe area, lock-screen, menu-bar, or Dock guides directly; Wallpect opens the matching preview mode so you can see the result immediately. The composition grid and device cutout stay in the current mode.
6. Use Download wallpaper below the exact output to keep the current format. Open Export options first when you need JPEG, WebP, a custom filename, or exported guides.

Your image and its thumbnail stay in browser memory and are released when the image is replaced or removed, the page is refreshed, or the page is closed. The enlargement estimate is calculated only from image dimensions, the selected canvas, and the shared rendering geometry; it does not inspect or transmit image pixels. Only the selected locale (wallpect:locale:v1) and up to four recent device identifiers (wallpect:recent-devices:v1) are saved in versioned localStorage. Normal requests for public site files still pass through Cloudflare, but they do not contain your selected image bytes.

The website provides directly accessible Traditional Chinese and English privacy, terms, disclaimer, and data-source notices. Maintenance and third-party source/API rules are documented in the Terms, Privacy, and Data Policy.

Accuracy, by design

Wallpect separates published display facts from geometry that must be measured or derived:

• 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 for the complete definition and reporting requirements.

Technology stack

Layer	Technology	Purpose
UI and application	React 19, strict TypeScript 5, Vite 8	Typed single-page application compiled to static assets
Browser image runtime	Canvas 2D, File/Blob APIs, Object URLs	Local decode, composition, preview, and export
Interface assets	Lucide React	Open-source interface icons
Hosting	Cloudflare Workers Static Assets and Wrangler 4	Assets-only edge delivery, SPA fallback, previews, and deploys
Offline shell	Service Worker and Cache Storage	Same-origin app-shell fallback after the first online visit
Quality	ESLint, Prettier, Vitest, Testing Library, and Playwright	Static checks and unit, integration, and browser testing
Automation	GitHub Actions and Cloudflare Workers Builds	Read-only CI checks plus branch previews and production builds

The current deployment has no SSR, Worker request handler, runtime API, authentication, analytics, database, object-storage binding, or runtime AI model. Exact dependency versions are locked in package-lock.json, while package.json is the readable source of truth for scripts and direct dependencies.

Local development

Requirements: Node.js 22 or newer and npm.

git clone https://github.com/kyeunga25/wallpect.git
cd wallpect
npm ci
npm run dev

Run the core quality checks. npm run check includes lint, unit/integration tests, a strict production build, and the raw build-size budget:

npm run check
npm run format:check
npm run worker:check

The Playwright suite builds the app and starts a production-mode local preview on port 4174. It covers Chromium, WebKit, Microsoft Edge, and Firefox:

npm run test:e2e

Set PLAYWRIGHT_BASE_URL to run the same browser matrix against a deployed Workers preview or the production app.

Deployment, self-hosting, and releases

Wallpect is deployed as an assets-only Cloudflare Worker with Static Assets. The Worker owns wallpect.k-y.cc as a Custom Domain. A push to main triggers a production Workers Build; non-production branches create preview versions without changing production traffic. Production rollback uses Workers version history; no Cloudflare Pages project is required.

You can self-deploy a fork to your own Cloudflare account without a database, storage binding, AI key, or runtime secret:

1. Fork or clone the repository and install Node.js 22 or newer.

2. Before the first deploy, edit wrangler.toml: choose a Worker name in your own account, and remove the checked-in [[routes]] block for a workers.dev deployment or replace it with a Custom Domain that you control.

3. Install and validate the locked project:

   npm ci
   npm run check
   npm run format:check
   npm run worker:check

4. Authenticate locally and deploy the static build:

   npx wrangler login
   npm run worker:deploy

5. Run the browser suite against the URL returned by Wrangler:

   PLAYWRIGHT_BASE_URL=https://<your-worker-url> npm run test:e2e

Wrangler credentials stay outside the repository. Never add API tokens, account or zone identifiers, deployment IDs, private domains, production data, local paths, logs, or screenshots containing private content to source control. The checked-in configuration explicitly disables Wrangler usage metrics, deployment dependency metadata instrumentation, and Worker observability. The deployment and self-hosting guide contains the safe configuration template, Workers Builds setup, Custom Domain steps, validation checklist, and rollback procedure. The release guide covers the versioned release workflow.

Architecture

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

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. Composition check derives the visible area from those same image dimensions, canvas dimensions, and transforms without creating another rendering state.

See the architecture document for the runtime boundary, local-data lifecycle, storage migration, offline behavior, and verification invariants.

Documentation

• Accuracy policy
• Architecture
• Device profile guide
• Deployment and self-hosting guide
• Release guide
• Legal, privacy, and data policy
• Security policy
• Production third-party licence notices
• Changelog

Contributing

Issues and focused pull requests are welcome. Read CONTRIBUTING.md before changing device data, rendering behavior, or privacy-sensitive code.

License and disclaimer

Wallpect is available under the MIT License. Third-party code included in the production browser bundle is listed with its applicable licence text in the third-party notices.

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.

Device specifications are manually curated from linked public manufacturer support pages. Wallpect does not use an Apple or third-party device-data API at runtime and does not scrape or mirror Apple website content. See the Terms, Privacy, and Data Policy for the detailed limitations and data-governance gate.

Technology and source references

• Web and platform technology: React, TypeScript, Vite, the browser Canvas API and Service Worker API, plus Cloudflare Workers Static Assets and Wrangler.
• Device references: Each profile records credential-free links to public Apple Support pages. The evidence levels, review rules, and correction process are documented in the accuracy policy and device profile guide.
• Privacy and legal references: Public guidance includes the Cloudflare Privacy Policy, Apple Website Terms of Use, and Apple trademark and copyright guidelines. Their application to Wallpect is summarized in the legal, privacy, and data policy.
• Licensing: Wallpect's source is released under the MIT License. Third-party packages and referenced content remain subject to their own licences and terms; a link is a source citation, not an endorsement or transfer of rights.