---
name: macos-selfcontained-webapp
description: "Build or refactor a project so a web app runs as a self-contained macOS app: embedded local backend binary + SwiftUI/WKWebView shell + packaging scripts. Use when a user has web logic and wants no external browser, no separate web-code install, local execution from inside .app, and repeatable DMG packaging."
---

# macOS Self-Contained Web App

## Outcome
Deliver one installable macOS app that:
- launches an embedded backend executable from app resources
- opens the web UI only inside `WKWebView`
- persists settings locally and supports native-to-web sync
- can be packaged as a DMG

## Layout Standard
Use this layout for new projects:
- `web/` for web backend source (`app.py`, modules, requirements)
- `mac/<AppName>Mac/` for Xcode project and SwiftUI shell
- `scripts/` for build and packaging automation
- `docs/` for architecture and onboarding docs

For existing repos, avoid destructive renames unless explicitly requested. Add compatibility paths or migration commits in small steps.

Detailed naming guidance: `references/layout-and-naming.md`

## Workflow
1. Inventory existing architecture.
- Identify backend entrypoint, runtime dependencies, and static/resource files.
- Confirm current launch mode and where browser auto-open is happening.

2. Create embedded backend launcher.
- Add a thin launcher (`backend_embedded_launcher.py` or equivalent) that starts the web server on `127.0.0.1` and reads port from env (for example `MANESH_TRADER_PORT`).
- Ensure browser auto-open is disabled.

3. Build backend into a single executable.
- Add `scripts/build_embedded_backend.sh` that compiles backend into a one-file executable and copies it into the mac target resource folder.
- Include all required web files/modules in build inputs.

4. Implement SwiftUI host shell.
- Use `@Observable` host state (no `ObservableObject`/Combine).
- Start/stop backend process, detect available local port, and handle retries.
- Render URL in `WKWebView` only.
- Keep app responsive when backend fails and surface actionable status.

5. Define settings sync contract.
- Use shared settings file (for example `~/.<app>/settings.json`) as source of truth.
- Normalize settings both in web app and native app.
- Pass effective settings via URL query params on launch/reload/restart.
- Keep onboarding limited to starter fields; preserve advanced fields.

6. Automate packaging.
- Add `scripts/build_selfcontained_mac_app.sh` to build embedded backend then Xcode app.
- Add `scripts/create_installer_dmg.sh` for distributable DMG.

7. Validate.
- Python syntax: `python -m py_compile` on web entrypoint.
- Xcode build: `xcodebuild ... build`.
- Runtime check: no external browser opens, webview loads locally, settings persist across relaunch.

## Required Deliverables
- Embedded backend build script
- macOS app host that launches backend + WKWebView
- Shared settings sync path
- README section for local build + DMG workflow
- Verified build commands and final artifact locations

## References
- Layout and migration rules: `references/layout-and-naming.md`
- Implementation blueprint and command templates: `references/implementation-blueprint.md`

## Bundled Script
Use `scripts/scaffold_web_mac_layout.sh` to create a new standardized folder skeleton for fresh projects.