Skip to content

feat(*): add a native macOS window for the Raven web UI - #1246

Open
hyi1233 wants to merge 12 commits into
EverMind-AI:mainfrom
hyi1233:desktop
Open

hyi1233 wants to merge 12 commits into
EverMind-AI:mainfrom
hyi1233:desktop

Conversation

@hyi1233

@hyi1233 hyi1233 commented Nov 10, 2026 •

Copy link
Copy Markdown

Summary

raven web already serves the whole UI, but it opens in a browser tab. This
adds a native macOS window around that same page, so Raven can be launched
from the Dock and kept separate from other tabs.

The app does not bundle a second frontend. On launch it runs
desktop/macos/scripts/launch.sh, which runs one command:

raven web --print-url

The CLI attaches to a running gateway, waits for one that is starting, or
starts a resident one, then prints the one-time /auth#<nonce> URL on stdout.
Progress and errors go to stderr, and the launcher never stops a gateway: an
empty probe can mean "still booting", so stopping there would kill the launch
it was trying to join. Closing the window quits the app but leaves the gateway
running.

The app marks itself as RavenShell in the user agent and implements the
desktop-shell bridge the web frontend already defines: the page lifts the
native splash with ready, asks for a fresh sign-in link with reauth after a
gateway restart, and reports theme, drag and zoom for the hidden title
bar. That bridge keeps an expired session inside the window instead of sending
the reader back to a terminal.

The Swift app, build script and launcher live under desktop/macos/.
raven web --print-url is additive, and a macOS CI job typechecks the Swift
sources whenever desktop/** changes. build.sh refuses a
RAVEN_DESKTOP_APP that is not a .app path and fails when codesign fails.

Type

  • Feature

Verification

Python:

uv run pytest tests/test_cli_serve_commands.py tests/test_desktop_macos_launcher.py -q
# 217 passed
uv run pytest tests/test_rpc_system.py -k supervised_gateway_not_a_bare_serve -q
# 1 passed

Swift and the bundle (macOS, Xcode Command Line Tools):

/usr/bin/swiftc -typecheck -framework Cocoa -framework WebKit desktop/macos/RavenDesktop.swift
/usr/bin/swiftc -typecheck -framework Cocoa -framework WebKit desktop/macos/render_svg.swift
RAVEN_DESKTOP_APP=/tmp/Raven.app ./build.sh
# both typechecks exit 0; the build compiles, renders the icon, assembles and
# ad-hoc signs the bundle

End to end with an isolated home and a built page:

/tmp/Raven.app/Contents/Resources/scripts/launch.sh
# stdout: http://127.0.0.1:18793/auth#<nonce>
# stderr: empty

Two launchers started at the same time against a fresh home both printed a URL
for the same gateway, and raven web --stop in that home then stopped it; the
gateway that was still starting was not signalled.

Repository gates over the PR range (af6e607d..HEAD):

uv run python -m scripts.check_commit_messages af6e607d..HEAD
uv run python -m scripts.check_source_language af6e607d..HEAD
uv run python -m scripts.check_large_files af6e607d..HEAD
uv run python -m scripts.check_soul_legacy af6e607d..HEAD

All four exit 0.

  • Relevant tests pass locally
  • Relevant lint / type checks pass locally
  • User-facing docs are updated (desktop/macos/README.md)

Risk

  • Security impact considered: the window loads only http://127.0.0.1,
    http://localhost or http://[::1], over the gateway's own one-time auth
    URL, and hands external links to the system browser. NSAllowsLocalNetworking
    is set for the local page. The app stores no credentials itself; WebKit
    persists the gateway's HttpOnly session cookie in its default data store, as
    a browser tab does, which keeps the window signed in across launches.
  • Backward compatibility considered: raven web --print-url is a new,
    opt-in mode; the existing raven web paths keep their output and browser
    behavior. The desktop sources are additive, and the gateway process is
    untouched apart from the new flag. --print-url refuses to combine with
    --stop, --foreground or --supervise, so no existing mode changes shape.
  • Rollback path is clear: revert the PR. The CLI flag is additive and the
    desktop bundle is self-contained under desktop/macos/.

Known limits: the app is ad hoc signed rather than notarized, so Gatekeeper may
require Right-click -> Open on a new machine. It assumes the gateway keeps
serving /auth#<nonce>; if that contract changes, raven web --print-url and
launch.sh change together. A Finder-launched app does not inherit a shell
profile, so provider keys or a custom RAVEN_HOME exported from .zshrc do
not reach a gateway it starts.

Related Issues

N/A

@LivXue

LivXue commented Nov 10, 2026

Copy link
Copy Markdown
Member

Windows compatibility review — PR #1246, reviewed at a5a7327c206becf016a5ed4551ec5b17f9df3764

Scope: the full diff, 6 new files, all under desktop/macos/ (a Swift WKWebView app, build.sh, launch.sh, an SVG-to-icns renderer, README and .gitignore); nothing in the existing tree changes.

Windows-specific findings: none. Checks:

  • The addition is inert on Windows: nothing under raven/, ui-web/, scripts/, tests/ or .github/workflows/ references desktop/ (grep over those trees at this head finds no hits), so no test, gate or workflow picks the new files up on any platform.
  • Packaging is unaffected: the wheel packages raven and the sdist includes raven/, bridge/, hatch_build.py, README.md, LICENSE — desktop/ is in neither, so no Windows install changes.
  • The shell scripts are not a CRLF hazard for Windows checkouts: .gitattributes at this base carries * text=auto eol=lf, so desktop/macos/scripts/launch.sh and build.sh land as LF even under core.autocrlf=true, and a Windows edit committed from this repo stays LF (the classic "bash script breaks on the Mac after a Windows round-trip" case).
  • The new README's instructions are macOS-specific by title and content; a Windows reader is not pointed at a command that would run here.
  • The repository's own portability gates pass over the range: python scripts/check_source_language.py af6e607d..a5a7327c → exit 0; python scripts/check_large_files.py af6e607d..a5a7327c → exit 0.

Verification (native Windows 11 10.0.26300, python 3.12.13, detached worktree D:\tmp\rv-1246 at the head, raven.__file__ confirmed):

  • check_source_language.py and check_large_files.py over the PR range → both exit 0 (commands above).
  • File-level scan for desktop references in tests/, scripts/, .github/, pyproject.toml → no hits.

Coverage gaps: the Swift build and the macOS window itself cannot be exercised on this host, and are out of scope for a Windows review; the Node runtime on this host is currently crashing (see the separate reviews this run), so no JS checks were relevant or run.

@LivXue

LivXue commented Nov 11, 2026

Copy link
Copy Markdown
Member

This PR adds a native macOS window around the existing raven web UI: a small WKWebView app under desktop/macos/, a launcher that reuses or starts the resident gateway and hands the window a one-time /auth#<nonce> URL, and a build script that assembles and ad-hoc signs the bundle. The direction is right: it reuses the shipped frontend instead of duplicating it, touches no existing file, and keeps the gateway running when the window closes.

This is a review conclusion, not a rejection. I found three things that should be addressed before merge, and a few smaller notes below them.

  1. The app does not implement the desktop-shell protocol the frontend already defines. ui-web/src/app/connection.ts:29-32 identifies a shell by RavenShell in the user agent; connection.ts:41-46 posts {type:'ready'}; connection.ts:48-72 posts {type:'reauth'} when the session cookie no longer matches a restarted gateway; ui-web/src/app/boot.ts:67-72 removes the page splash and expects a native overlay when that UA is present; ui-web/src/state/look.ts:22-24 posts the theme, and ui-web/src/state/shellWindow.ts:1-9 posts drag/zoom for a hidden title bar. RavenDesktop.swift:94-107, 118-135, and 231-240 contain no WKUserContentController, no WKScriptMessageHandler, and no customUserAgent, so the page runs as a plain browser. After a gateway restart or self-upgrade the cookie is stale, authFail() takes the browser branch, and the user sees gui.auth.stale ("The service is running but this tab's sign-in expired - get a fresh link with: raven web", ui-tui/src/i18n/messages.generated.ts:469) or gui.upg.reauth (ui-web/src/app/updates.ts:322). The desktop user is sent back to a terminal even though the app already has reconnect() and the page has a way to ask for it. Please add a raven script message handler and a RavenShell user agent; handle ready (native overlay) and reauth (call reconnect()), and optionally theme, drag, and zoom. If the intended scope is a browser-like window rather than a shell, that is a valid design choice, but it should be documented and the terminal-oriented message should be corrected; the frontend comments name "the app" as the intended host, so implementing the contract is the better fit. I have not exercised the WKWebView flow on macOS, so the exact screen is unverified; the flow above is from the frontend code.

  2. desktop/macos/scripts/launch.sh:48-51 stops a gateway it did not start. The script treats an empty page_url as "no gateway" and runs raven web --stop. Empty also means "gateway still starting": serve.json is written only after the server is bound (raven/cli/serve_commands.py:495), _attached_url() reads that record and returns None when it is absent (serve_commands.py:649-677, 732-742), and the supervisor writes web.json before the gateway starts (serve_commands.py:1099). A raven web that is still booting therefore has a live supervisor and no serve record, and the launcher kills it. raven web itself would wait up to 150 seconds (_ATTACH_PATIENCE_S, serve_commands.py:1502) instead of restarting; a healthy gateway that misses the 2-second attach probe (serve_commands.py:705) has the same exposure. I exercised the launcher's control flow: with no URL it runs web --stop and then web, so opening the app while a first raven web is still booting, or launching the app twice, can stop the first gateway. Please let raven web own the wait. The cleanest direction is a public raven web --print-url that reuses _web's logic and does not open a browser; the launcher would call that one command, which also removes the private _attached_url import at launch.sh:39. A smaller fix is to wait first and only --stop after the CLI reports "alive but not answering" or the recorded pid is dead. Note that --stop can also stop a standalone raven serve recorded in serve.json (_stop_resident reads _read_serve_pid), so the blast radius is wider than the supervisor this app starts.

  3. There are no tests for the new behavior. CONTRIBUTING.md:48 asks for tests on behavior changes. CI cannot catch this: .github/workflows has no macOS runner, and nothing under desktop/ is referenced by raven/, scripts/, tests/, .github/, ui-web/, or pyproject.toml, so the Swift app is never compiled and the shell scripts are never executed. The untested surface is launch.sh's attach/start/failure branches and the booting-gateway case, RavenDesktop.swift's window, navigation, auth exchange and reconnect, build.sh, render_svg.swift, and the end-to-end WKWebView flow. The lowest-cost additions are a pytest for launch.sh with a fake raven CLI (the existing Ubuntu CI can run it) covering the three branches, and a swiftc -typecheck job on a macOS runner gated to desktop/** changes. The manual macOS 14/15 run in the PR body is useful, but CI cannot repeat it. The macOS build and the WKWebView auth exchange are unverified on my side; the shell control flow is the part I could exercise.

A few smaller things worth a look, not blocking:

  • RavenDesktop.swift:131 points the error page at ~/.raven/logs/, but the raven web supervisor log is ~/.raven/web.log (serve_commands.py:818-821), and launch.sh:52 discards the command's output, so the actual reason (for example "No page is built") is lost.
  • RavenDesktop.swift:95 uses WKWebsiteDataStore.default(), which persists the gateway's HttpOnly session cookie (30-day max-age, raven/rpc/transports/ws.py:109, 301-307). The PR body's "No credentials are stored by the app" should be reworded: the app stores none itself, but WebKit does.
  • build.sh:46 runs rm -rf "$APP" on an unvalidated RAVEN_DESKTOP_APP, and build.sh:76 swallows codesign failures, so the script can print "done" for an unsigned bundle.
  • launch.sh:12-16: RAVEN_HOME is assigned but never exported or used, and BROWSER=/usr/bin/true is exported into the resident gateway and everything it starts. Also, a Finder-launched app does not inherit the login shell's environment, so provider keys or a custom RAVEN_HOME set in .zshrc will not reach a gateway started by the app; this at least deserves a line in the README.

This review was read-only; I did not change code or push anything. Happy to look at a revision. If the maintainers want to waive the test requirement for a macOS-only add-on, that is a reasonable call to discuss.

@LivXue

LivXue commented Nov 16, 2026

Copy link
Copy Markdown
Member

Windows compatibility review — fcd509cce8

Reviewed at head fcd509cce8f7f860ee20a7da1d76efc239d85772 (base e604b4455e). Scope: the full base-to-head diff — raven/cli/serve_commands.py, the new desktop/macos/ tree (RavenDesktop.swift, build.sh, render_svg.swift, scripts/launch.sh), .github/workflows/desktop.yml, and the three test files — with the CLI flag read against its _spawn_supervisor / _await_attach / supervise_from_argv callers.

No Windows compatibility issue found.

The macOS app itself is out of scope for this host (Swift/Cocoa, swiftc -typecheck on macos-latest), but the half that ships in the Raven CLI is platform-neutral and was exercised here:

  • _web(print_url=...) only routes messages: say() sends to stdout when not printing a URL and to stderr when it is, and _await_attach(err=True) moves its slow notice off stdout. typer.echo is the same call on every platform; nothing touches paths, shells, or file modes.
  • The flag's mutual exclusion works from a real CLI invocation on this host (--print-url plus each of --stop / --foreground / --supervise): rc=2, stdout empty, the reason on stderr each time.
  • The POSIX launcher (desktop/macos/scripts/launch.sh) actually runs under Git Bash here against a fake raven CLI: rc=0, prints the URL it was given, and invokes the CLI with exactly web --print-url. It is macOS-only by design (#!/bin/sh, ~/Applications bundle, Cocoa), so it is not wired into any Windows path.

One observation, not a defect: the new option's help text reads "Print the one-time sign-in URL on stdout and open nothing (for native windows)". In a repository that is under active Windows-compatibility work, "native windows" reads as the operating system at first glance; it means native app windows (the macOS shell). Rewording to "for the native desktop app" would avoid that, but nothing depends on it.

Verification (native Windows host, Python 3.12.13, shared venv, detached worktree pinned to the head):

  • PYTHONPATH=<head tree> python -S runner.py tests/test_cli_serve_commands.py -q → 184 passed, 29 skipped (the skips are all "process groups and SIGKILL are POSIX"). Without that PYTHONPATH the one test that re-imports raven in a fresh interpreter sees the installed editable tree instead of the worktree and fails; that is a harness artefact of this box, not the PR — the same test passes with the tree on PYTHONPATH.
  • python -S runner.py tests/test_desktop_macos_launcher.py -q → 4 skipped under a plain invocation ("the launcher is a POSIX shell script", by an os.name == "nt" guard); the launcher was instead driven by hand under Git Bash as described above.
  • tests/test_rpc_system.py was not re-run wholesale; its one-line change is an assertion matching the new keyword argument and was exercised through the serve suite's supervise_from_argv cases.

Coverage gaps: I did not launch a real gateway through --print-url (it would start a resident supervisor on this machine), so the end-to-end "stdout is the URL and only the URL" path is verified by code reading plus the mocked tests, not by starting one. The Swift sources were not compiled — no macOS host.

@LivXue

LivXue commented Nov 17, 2026

Copy link
Copy Markdown
Member

Windows compatibility review — 25d85831b5

Reviewed at head 25d85831b52db14a4a3b9506c4eecb62791c64a8 (base e604b4455e; follows the fcd509cce8 reviewed last round). Scope: the diff since that head — one line in raven/cli/serve_commands.py — plus a re-check of the option's wiring and of anything that consumed the old string.

No Windows compatibility issue found.

The change is the rewording I suggested last round: the --print-url help text no longer reads "(for native windows)", which invited a reading as the operating system, and now says "(for the native desktop app)". Nothing in the repository matched the old string (the only native windows hit is an unrelated test fixture description), so no doc, test or script needed updating, and the flag's behaviour is untouched.

Verification (native Windows host, Python 3.12.13, shared venv, detached worktree pinned to the head):

  • PYTHONPATH=<head tree> python -S runner.py tests/test_cli_serve_commands.py -q → 184 passed, 29 skipped (all skips are "process groups and SIGKILL are POSIX").

Coverage gaps: unchanged from the previous round — the Swift sources were not compiled (no macOS host), and a real gateway was not launched through --print-url, so the stdout-is-the-URL path is verified by the mocked tests rather than end to end.

@LivXue

LivXue commented Nov 17, 2026

Copy link
Copy Markdown
Member

Blocking: 1 finding needs correction before this revision can merge; it is described below because this PR has no raven/agent files to anchor an inline note on.

Scope: this PR changes no files under raven/agent/** (0 of 13), so the review zone is empty and no inline note can be filed -- the fence refuses paths outside it. I read the full diff (13 files, +1328 -17) and the frontend contracts the new window depends on; the findings below are disclosed from that read, not filed against the fence.

What this PR does: a native macOS window (desktop/macos/) around the existing raven web UI -- a Swift WKWebView app, a launcher that asks the installed CLI for the one-time /auth# URL, a build script, and an additive raven web --print-url mode. It also implements the desktop-shell bridge the page already defines (RavenShell user agent; ready, reauth, theme, drag, zoom) and adds a macOS typecheck job plus a navigation self-test.

Confirmed findings:

  • F1 (Blocker), desktop/macos/RavenDesktop.swift: the app does not implement the WKUIDelegate open-panel method, and on macOS that disables file uploads in a WKWebView. Apple documents that file uploads are disabled on macOS when webView(_:runOpenPanelWith:initiatedByFrame:completionHandler:) is not implemented; the app implements only the alert and confirm JS panels. Four page sites are affected: the composer's "+ -> upload a file" (ui-web/src/features/composer/mount.tsx:158-176, run from ui-web/src/chrome/PlusMenu.tsx), the subagent instance attach button (ui-web/src/features/subagents/SubagentsPage.tsx:608-612), the knowledge base Add file / Add folder (ui-web/src/features/knowledge/KnowledgePage.tsx:687-705, where the folder path relies on webkitdirectory), and the rail's package import dialog (ui-web/src/features/imported/store.ts:183-193). A click opens no panel and reports no error. Evidence: code-reading -- this host has no macOS to reproduce on, so the behavior rests on Apple's documented default plus the delegate list in the source. Remedy direction: conform to WKUIDelegate and present an NSOpenPanel from the runOpenPanelWith callback, honoring the parameters' multiple-selection and directory flags and calling the completion handler with the chosen URLs or nil.

  • F2 (Nonblocking), .github/workflows/desktop.yml: the Swift/TS bridge contract (the raven handler name and the ready, reauth, theme, drag, zoom messages) is maintained by hand on both sides with no cross-language check, and the macOS job's paths filter covers only desktop/** and the workflow itself. A ui-web change to the contract never triggers that job, and a Swift-side rename still typechecks. Losing ready leaves the native splash up forever, so the window stays on "Starting Raven..." even though the page loaded; losing reauth sends a restarted gateway's stale session back to the terminal banner. Evidence: code-reading.

  • F3 (Nonblocking, docs), desktop/macos/README.md: "No existing upstream file is modified" is no longer true. This PR also changes raven/cli/serve_commands.py, commitlint.config.cjs, docs-site/docs/repo-layout.md, three test files and a workflow, so the sentence now misleads a reader into expecting a purely additive branch. Evidence: code-reading.

  • F4 (Nonblocking, docs), docs-site/docs/repo-layout.zh.md: the English page gained the desktop/ line (repo-layout.md:13) but the paired Chinese page did not. Evidence: code-reading.

Verification:

  • At head 05d1bda, in a detached worktree (raven.file confirmed from that tree):
    • PYTHONPATH=. python -m pytest tests/test_desktop_macos_launcher.py tests/test_scope_canon.py -q -> 6 passed
    • PYTHONPATH=. python -m pytest tests/test_cli_serve_commands.py -k "PrintUrl or print_url" -q -> 7 passed
    • PYTHONPATH=. python -m pytest tests/test_rpc_system.py -k supervised_gateway_not_a_bare_serve -q -> 1 passed
  • Repository gates over e604b44..05d1bda: check_commit_messages, check_source_language, check_large_files, check_soul_legacy -> all exit 0.
  • CI: 23 checks pass, including swift typecheck.
  • Not run: a real raven web --print-url against a live gateway (it would start a resident supervisor on this machine), and any macOS GUI path (no macOS host). The launch-to-window flow and the file-input failure are therefore code-reading, not reproduced.

Checked and deliberately not reported: the previous round's three blockers are addressed -- the shell bridge is implemented and matches the page (connection.ts, look.ts, shellWindow.ts), the launcher no longer stops a gateway and calls only raven web --print-url, and the launcher/print-url tests plus the macOS typecheck job exist. The initial URL's scheme-only check is still safe because the navigation policy routes non-local http(s) URLs to the system browser; the "::1" entry in localHosts is unreachable because the CLI mints only 127.0.0.1 URLs; saveLocation does not sanitize the suggested filename, but downloads are local-only and the gateway already runs as the reader; render_svg.swift's KVC background switch and leftover temp directory are build-time only; commands.md lists only two raven web examples, so omitting --print-url matches that page's style.

@LivXue LivXue left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

F1 (Blocker), desktop/macos/RavenDesktop.swift: the app does not implement the WKUIDelegate open-panel method, and on macOS that disables file uploads in a WKWebView. Apple documents that file uploads are disabled on macOS when webView(_:runOpenPanelWith:initiatedByFrame:completionHandler:) is not implemented; the app implements only the alert and confirm JS panels. Four page sites are affected: the composer's "+ -> upload a file" (ui-web/src/features/composer/mount.tsx:158-176, run from ui-web/src/chrome/PlusMenu.tsx), the subagent instance attach button (ui-web/src/features/subagents/SubagentsPage.tsx:608-612), the knowledge base Add file / Add folder (ui-web/src/features/knowledge/KnowledgePage.tsx:687-705, where the folder path relies on webkitdirectory), and the rail's package import dialog (ui-web/src/features/imported/store.ts:183-193). A click opens no panel and reports no error. Evidence: code-reading -- this host has no macOS to reproduce on, so the behavior rests on Apple's documented default plus the delegate list in the source. Remedy direction: conform to WKUIDelegate and present an NSOpenPanel from the runOpenPanelWith callback, honoring the parameters' multiple-selection and directory flags and calling the completion handler with the chosen URLs or nil.

@LivXue

LivXue commented Nov 17, 2026

Copy link
Copy Markdown
Member

Windows compatibility review — ead6899021

Reviewed at head ead68990216e0a26066c5c2fe89387325bf62b55 (base e604b4455e; this head follows 25d85831b5, reviewed last round). Scope: the diff since that head — desktop/macos/RavenDesktop.swift (+340), the new tests/test_desktop_shell_contract.py, .github/workflows/desktop.yml, commitlint.config.cjs, the README/repo-layout docs — plus the existing macOS launcher and the CLI half already reviewed.

No Windows compatibility issue found.

Everything this head adds is Swift or a static check over it. The one piece that runs on this host is the new tests/test_desktop_shell_contract.py, and it is a pure literal cross-check (regex over the Swift switch, the page's postMessage types and the user-agent token) with no path handling beyond Path(__file__).parent.parent and read_text(encoding="utf-8") — no separators, no platform branches, and both PAGE_SIDES are repo-relative, so it resolves on Windows exactly as on Linux. It passed here (3 passed). The navigation policy itself is exercised by RAVEN_DESKTOP_SELFTEST=1, which the CI job runs after compiling the Swift source on macos-latest; nothing on the Windows side executes it. desktop added to the commitlint scope list is a string list and the workflow paths: filters are GitHub-side globs, both platform-neutral.

Verification (native Windows host, Python 3.12.13, shared venv, detached worktree pinned to the head):

  • python -S runner.py tests/test_desktop_shell_contract.py tests/test_desktop_macos_launcher.py -q → 3 passed, 4 skipped (the skips are the launcher's os.name == "nt" guard, unchanged).

Coverage gaps: unchanged from the earlier rounds — the Swift sources were not compiled (no macOS host), and a real gateway was not launched through --print-url; the navigation matrix is verified by Swift's self-test in CI, which this host cannot run.

星耀羽翼 and others added 12 commits November 18, 2026 01:24
The app runs scripts/launch.sh to make sure 'raven web' is up, reads the
one-time auth URL from the gateway, and loads it into a WKWebView. BROWSER is
pointed at /usr/bin/true so no browser tab opens alongside the window.

launch.sh resolves the CLI from PATH (with a ~/.local/bin fallback for Finder
launches), reads its shebang for the interpreter, and takes the page port from
the gateway's own state. No user names, home directories or ports are baked in.

build.sh compiles the Swift source, renders the mark already shipped in
ui-web/src/assets/ into an .icns, assembles the bundle and signs it ad hoc.
Everything lives under desktop/macos/; no upstream file is changed.
`raven web --print-url` makes sure the gateway is up and prints the
one-time sign-in URL on stdout, with progress and errors on stderr. It
opens no browser and refuses `--stop`, `--foreground` and `--supervise`,
so a caller can read stdout as the whole answer.

The desktop launcher will use it to leave the gateway lifecycle to the
CLI instead of probing and stopping a gateway itself.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
The page already expects a native host: it keys shell-only paths off
`RavenShell` in the user agent, posts `ready` to lift the native splash,
asks for `reauth` after a gateway restart, and reports theme, drag and
zoom for the hidden title bar. The app now implements that bridge, hides
its title bar so the page's header band is the drag surface, and shows a
native splash until the page is painted.

The launcher no longer probes and stops gateways. It calls
`raven web --print-url`, which waits for a starting gateway instead of
killing it, and the error page points at `~/.raven/web.log` with the
launcher's own stderr.

`build.sh` refuses a `RAVEN_DESKTOP_APP` that is not a `.app` path and
stops claiming success when codesign fails.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
No existing job compiles the Swift app, so a broken window could merge
unseen. A macOS runner now typechecks both sources whenever `desktop/**`
changes; it needs no simulator, signing identity or GUI.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
`supervise_from_argv` hands `_web` the same keyword set as the command
does, and the new option rides along as False. This was the one place
outside the CLI tests that spelled the set out.

Co-authored-by: Claude (claude-fable-5) <noreply@anthropic.com>
The help text said "for native windows", which reads as the Windows OS in a repository that reviews Windows compatibility. It now names the macOS desktop app the mode exists for.

Co-authored-by: Claude (deepseek-flash) <noreply@anthropic.com>
…file

A delivered file is a <a download> link, and WebKit reports it as a normal navigation with shouldPerformDownload set. The delegate allowed everything, so clicking download replaced the window with the file itself and the page's script context went with it -- the reader was left staring at the file with no way back. target=_blank had the same shape: createWebViewWith loaded it into the main view, so 'open in a new tab' navigated Raven away from itself.

Navigation decisions now come from a NavigationPolicy value: a download becomes a WKDownload saved to Downloads (a second copy of the same name does not overwrite the first), a response the gateway marks as an attachment becomes a download even when the click did not say so, and a new-window request gets a real child window beside the main one. Back and Forward join the File menu because the window has no browser toolbar.

A preview window shares the app's delegates, so the title, the error page, the reconnect path and the script bridge are now scoped to the main web view instead of reacting to a child's load.

RAVEN_DESKTOP_SELFTEST=1 runs the navigation matrix without a window, a gateway or a click; the macOS job runs it after the typecheck.

Co-authored-by: Claude (deepseek-flash) <noreply@anthropic.com>
commitlint.config.cjs already scopes a change that lives wholly in a top-level tree outside raven/ by that tree, and the desktop/ tree this PR adds is exactly that case -- but the list never learned the name. The scope enum rejected fix(desktop), so the message gate failed on a branch whose only offence was naming a directory that exists.

The repo-layout page gains the matching Key directories line, which is the page the config's comment points readers at.

Co-authored-by: Claude (deepseek-flash) <noreply@anthropic.com>
On macOS a WKWebView has no file panel of its own: unless the app answers webView(_:runOpenPanelWithParameters:initiatedByFrame:completionHandler:), clicking a file input opens nothing and reports no error. The window implemented the alert and confirm panels only, so four page sites were inert -- the composer's upload, a subagent's attach button, the knowledge base's add-file and add-folder, and the package import dialog.

The panel now honours the parameters WebKit passes: multiple selection when the input asks for it, and directories when the input is a webkitdirectory picker. Cancelling answers nil, which is what the page expects for 'no file chosen'.

The self-test checks that the delegate still implements the method, because the failure mode is silence.
The message names, the handler name and the user-agent token are written twice -- once in Swift, once in TypeScript -- and each half typechecks on its own, so a rename on either side stays invisible until a reader meets it in the app. A lost ready leaves the native splash up forever; a lost reauth sends a restarted gateway's stale session back to a terminal banner.

The test reads both trees and fails when the sets drift apart. It is static, so it runs on the Ubuntu shards that already run the rest of the suite rather than waiting for a macOS runner.

The desktop workflow also watches the page's half of the bridge now, so a change to connection.ts, look.ts or shellWindow.ts builds the window as well.
…ages

The README still promised that no existing upstream file is modified. The branch has since grown a --print-url mode in the CLI, a commit scope, and the CI job that typechecks the window, so the sentence sent a reader looking for a purely additive change that is not there.

The Chinese repo-layout page also gains the desktop/ line the English one already had; the two pages are paired, and a reader on one should not see a different tree than a reader on the other.
The compiler inherited the host deployment target, so a build on a newer macOS produced a binary with minos 26.0 even though the bundle declared macOS 12.0 support. Both build paths and the Desktop workflow now compile for the declared version, and CI inspects the resulting Mach-O load command.

The regression test keeps the script, plist, and workflow versions aligned.
@LivXue

LivXue commented Nov 17, 2026

Copy link
Copy Markdown
Member

Windows compatibility review — 6ec61705da

Reviewed at head 6ec61705dac1db4727f5169687112dec28abf292 (base a639935478; this head follows ead6899021, reviewed last round, and adds the deployment-target work: desktop/macos/build.sh, render_svg.swift, the CI steps, and tests/test_desktop_macos_build.py). Scope: the PR's own diff against its base (16 files, +1516/-17), with the new static test and the serve suite run here.

No Windows compatibility issue found.

The new tests/test_desktop_macos_build.py is the only new Windows-executable piece, and it is a pure static check: it reads build.sh and desktop.yml with read_text(encoding="utf-8") and matches line-anchored regexes (deployment target, LSMinimumSystemVersion, every swiftc invocation carrying -target). Universal-newline decoding means a CRLF checkout here matches the same anchors as CI's LF tree, and it passed. build.sh and render_svg.swift are macOS shell/Swift that this host never runs; the --print-url CLI half was covered in earlier rounds and its suite still passes (186 passed).

Verification (native Windows host, Python 3.12.13, shared venv, detached worktree pinned to the head):

  • python -S runner.py tests/test_desktop_macos_build.py tests/test_desktop_shell_contract.py tests/test_desktop_macos_launcher.py -q → 5 passed, 4 skipped (the skips are the launcher's os.name == "nt" guard)
  • PYTHONPATH=<head tree> python -S runner.py tests/test_cli_serve_commands.py -q → 186 passed, 29 skipped
  • python -S runner.py tests/test_rpc_system.py -q → 79 passed

Coverage gaps: no macOS host, so the Swift sources were not compiled and the deployment-target claim is verified by the static test plus the CI job's vtool -show-build step, not by a local build; the launcher remains unexecuted here (skipped as POSIX-only shell).

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants