73 lines
3.3 KiB
Markdown
73 lines
3.3 KiB
Markdown
---
|
|
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.
|