---
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
- provides native app-level help/onboarding (not only in the web UI)
- can be packaged as a DMG

## Layout Standard
Use this layout for new projects:
- `web/src/` for web backend source (`app.py`, modules, requirements)
- `mac/src/` for Xcode project and SwiftUI shell sources
- `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.
- Use generic discovery:
  - discover `*.xcodeproj` under `mac/src`
  - discover scheme via `xcodebuild -list -json` (fallback to project name)
  - discover/create `EmbeddedBackend` folder under selected project sources
- Include all required web files/modules in build inputs.
- Default backend name should be stable (for example `WebBackend`) and configurable via env.

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.
- Resolve backend executable by checking both current and legacy names during migration.
- Add a native toolbar `Help` button that opens bundled help content in-app.

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.
- Add web-only fallback access to help/onboarding (for users not using the mac wrapper).

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.
- Use generic app bundle discovery for DMG defaults where possible.
- Standardize installer artifacts under `build/dmg/` (not repo root).
- Ensure `.gitignore` excludes generated artifacts (`build/`, `*.dmg`, temp `rw.*.dmg`).

7. Validate.
- Python syntax: `python -m py_compile` on web entrypoint.
- Tests: `PYTHONPATH=web/src pytest -q web/src/tests`.
- Xcode build: `xcodebuild ... build`.
- Runtime check: no external browser opens, webview loads locally, settings persist across relaunch.
- Verify help works in both modes:
  - native toolbar help popup in mac app
  - sidebar help fallback in web-only mode

## Required Deliverables
- Embedded backend build script
- macOS app host that launches backend + WKWebView
- Shared settings sync path
- Native help/onboarding popup + web fallback help entry
- README section for local build + DMG workflow
- Verified build commands and final artifact locations
- `.gitignore` updated for build/installer outputs

## 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.