91 lines
4.4 KiB
Markdown
91 lines
4.4 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
|
|
- 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.
|