maneshtrader/skills/macos-selfcontained-webapp/SKILL.md

name	description
macos-selfcontained-webapp	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.