# Direct Mac Application

The direct Mac application is for users who download ZoneGaze Matrix, install it, and open it like a normal macOS app. Users do not need to clone this repository or run `npm` commands.

Related docs:

- [Platform application guides](README.md)
- [Software manual](../manual/software-manual.md)
- [Core feature guide](../features/zonegaze-flow-core-features.md)
- [Feature coverage matrix](../features/feature-coverage-matrix.md)

## What The Mac App Includes

The packaged app is an Electron shell with product name `ZoneGaze Matrix`, app id `com.zonegaze.matrix`, primary deep-link scheme `zonegaze-matrix://`, and legacy-compatible scheme `zonegaze-flow://`.

It provides:

- direct DMG install for Apple Silicon and Intel Macs;
- bundled ZoneGaze Matrix runtime shell, CLI shim, and web UI assets;
- local runtime start/adopt/stop/restart starting from `127.0.0.1:3484` with automatic fallback to the next free runtime port;
- adjacent port detection for `3485` through `3489` and dev/preview port detection for `4217` and `4173`;
- runtime health validation using the ZoneGaze Flow page title before attaching;
- Matrix dashboard, tray controls, menus, multiple windows, restored window state, and crash/disconnect recovery;
- local OAuth callback relay through `zonegaze-matrix://oauth/callback` and legacy `zonegaze-flow://oauth/callback`;
- PATH enrichment for GUI launches so common Homebrew and system binaries are visible to agents.

Source of truth:

- [Desktop package config](../../platforms/desktop/package.json)
- [Electron builder config](../../platforms/desktop/electron-builder.yml)
- [Desktop main process](../../platforms/desktop/src/main.ts)
- [Runtime orchestrator](../../platforms/desktop/src/runtime-orchestrator.ts)
- [Desktop server controller](../../platforms/desktop/src/desktop-server-controller.ts)
- [Tray controller](../../platforms/desktop/src/tray-controller.ts)
- [App menu](../../platforms/desktop/src/app-menu.ts)
- [Protocol handler](../../platforms/desktop/src/protocol-handler.ts)
- [Runtime environment policy](../../platforms/desktop/src/runtime-child-env.ts)

## Download And Install

1. Download the Mac DMG from the trusted project release or distribution channel.
2. Choose the artifact matching the Mac CPU:
   - Apple Silicon: `ZoneGaze Matrix-<version>-arm64.dmg`
   - Intel: `ZoneGaze Matrix-<version>-x64.dmg`
3. Open the DMG.
4. Drag `ZoneGaze Matrix.app` into `/Applications`.
5. Open `ZoneGaze Matrix` from Applications, Spotlight, or Finder.

If macOS blocks a downloaded app, verify that the DMG came from the trusted distribution channel before following the normal macOS security prompt.

## First Run

1. Open the app. It starts or attaches to the local runtime, then opens the ZoneGaze Matrix dashboard directly.
2. If the runtime cannot be started or attached, the app falls back to a recovery screen with a restart action.
3. Add or select the Git project you want ZoneGaze Matrix to manage.
4. Configure a supported agent in Settings.
5. Create a task, start it, review the output, then commit, open a PR, move to Done, or use the card's overflow (⋯) menu to archive/remove.

Screenshot: [open Mac application dashboard](../assets/screenshots/mac-desktop-dashboard.png)

![Mac application-only screenshot showing the ZoneGaze Matrix Electron dashboard and window chrome](../assets/screenshots/mac-desktop-dashboard.png)

Current install/launch screenshot: [open current Mac installed app board](../assets/screenshots/mac-install-launch-current.png)

![Current installed Mac app showing ZoneGaze Matrix running inside the Electron window](../assets/screenshots/mac-install-launch-current.png)

Current install/launch video: [open current Mac install/launch recording](../assets/videos/zonegaze-flow-mac-install-launch-current.webm)

![Current ZoneGaze Matrix Mac install and launch recording](../assets/videos/zonegaze-flow-mac-install-launch-current.webm)

## Dashboard, Tray, And Menus

The app opens the Matrix dashboard directly after it starts or attaches to the runtime. If the runtime stops or cannot be reached, the recovery screen can restart the managed runtime or wait for an external local runtime to become healthy.

The tray (menu-bar) menu exposes:

- Open ZoneGaze Matrix.
- Open in Browser.
- New Window.
- Start Server.
- Stop Server.
- Restart Server.
- Refresh Server Status.
- Quit ZoneGaze Matrix.

The app menu exposes app, File, Edit, View, Window, and Help menus. File includes New Window. View includes reload and zoom controls when the runtime is ready. Window lists visible windows and supports normal macOS window behavior.

## Windows And Recovery

The desktop shell supports multiple ZoneGaze Matrix windows. It restores safe runtime paths, persists window state, hides windows on close on macOS, and stops the owned runtime when the app quits.

Renderer load failures are handled by probing the runtime. If the runtime is unhealthy, the app shows its disconnected screen. If the runtime is healthy, the app offers retry. Renderer crashes reload the last safe local route when possible.

The orchestrator prevents app nap while it owns a runtime, watches attached external runtimes, and avoids attaching to unrelated localhost services by checking the body for the ZoneGaze Flow runtime title.

## Deep Links And Local URL Security

The app registers `zonegaze-matrix://` and keeps `zonegaze-flow://` as a legacy-compatible scheme. It recognizes OAuth callback links at `zonegaze-matrix://oauth/callback` and `zonegaze-flow://oauth/callback`, then queues or relays them to the runtime so provider auth can finish inside the app.

The desktop window only restores safe local runtime paths. External HTTP(S) links are opened in the operating system browser. Non-HTTP(S) paths are rejected for runtime restoration.

## Agents And Requirements

The direct app removes the need to run `npx zonegaze-flow`, but coding agents still need credentials or binaries:

- Native ZoneGaze Flow/Cline needs provider, model, API key, OAuth, or device auth setup.
- CLI agents must be installed where the desktop runtime can find them.
- The app appends common macOS tool paths such as `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, and `/bin` to `PATH`.

## Input Process Output Result Evidence

Video: [open Mac full workflow](../assets/videos/zonegaze-flow-mac-full-workflow.webm)

![ZoneGaze Matrix Mac full workflow video](../assets/videos/zonegaze-flow-mac-full-workflow.webm)

This Mac recording is a real app interaction recording. It shows the direct Mac app surface and ZoneGaze Flow workflow features including work item creation, detail panel navigation, filters, sort controls, archive/deleted/removed views, Git history, terminal toggle, and settings sections.

Current install/launch evidence:

- [Current Mac installed app screenshot](../assets/screenshots/mac-install-launch-current.png)
- [Current Mac install/launch video](../assets/videos/zonegaze-flow-mac-install-launch-current.webm)

Core workflow output evidence is shared with all launch paths:

- [Core working demo video](../assets/videos/zonegaze-flow-core-working-demo.webm)
- [Produced website result](../assets/screenshots/core-produced-website-result-page.png)

## Update

For direct Mac installs, update by installing a newer DMG from the same trusted distribution channel. You do not need to pull this repository or run development commands.

If an in-app update notice references an npm or CLI install command, treat that as CLI-package guidance. A direct Mac app should be updated by replacing the app bundle with the newer packaged app.

## Troubleshooting

- If the dashboard says the server is stopped, choose **Start Server**.
- If the app reports a blocked or failed server, use **Restart Server** or refresh diagnostics.
- If another process owns `127.0.0.1:3484`, the app starts the bundled runtime on the next free runtime port and adopts an existing process only when it is a healthy ZoneGaze runtime.
- If a CLI agent is not detected, install that agent in a standard path or configure native ZoneGaze/Cline in Settings.
- If the dashboard loads but runtime buttons throw `window.desktop` errors in a local build, rebuild/package through the desktop build path that creates the preload bridge rather than using a raw TypeScript build.
