Build macOS-first CodeGraphy desktop app

[joesobo]

Summary

Builds the first release-shaped macOS desktop app for Trello #275.

CodeGraphy for macOS is a local code navigator with a thin File and Folder hierarchy, a multi-language CodeMirror editor, and the existing WebGPU/WebAssembly Relationship Graph. A Tauri 2 Rust shell owns macOS integration and safe File I/O. A bundled Node 22.23.2 process calls Core for File Discovery, Tree-sitter analysis, Indexing, Graph Cache storage, graph state, and queries.

Architecture decision

• Use one @codegraphy-dev/graph-renderer package for all graph rendering ownership. Its root owns WebGPU drawing, camera geometry, and WebAssembly force/collision physics. Its /visuals subpath owns the Material Icon Theme matching, Node geometry, connection sizing, selection metrics, and force-control semantics shared by desktop and the VS Code Extension.
• Delete the private @codegraphy-dev/graph-visuals workspace package. /visuals is a renderer export, not a compatibility package or second runtime boundary. Keeping it as a subpath prevents host-only icon/default imports from evaluating the WebGPU/WASM entry.
• Keep Core as the only owner of File Discovery, Tree-sitter analysis, Indexing, the SQLite Graph Cache, graph state, and graph queries. Rust supervises Core, validates workspace/File boundaries, and performs safe local File operations.
• Keep desktop Graph View limited to File and Folder Nodes. The Extension retains its existing Symbol support.

Shipped on this draft

• Open any local workspace, switch through native Open Recent, and keep missing recent paths visible but unavailable.
• Browse and filter Files and Folders. Up, Down, Home, End, and Right open each newly focused File without moving focus into the editor.
• Coalesce rapid keyboard navigation to one active Rust File read plus one replaceable latest intent. A deterministic 20-File burst now performs two reads instead of 20. Hierarchy focus moves synchronously and repeated scroll work collapses to one animation frame, so released Arrow keys do not replay a queued navigation backlog.
• Open, edit, and save UTF-8 Files through a permission-preserving atomic replacement with external-edit conflict detection and dirty-edit confirmation.
• Load maintained CodeMirror language support by filename. Covered examples include TypeScript/TSX, JavaScript, Python, Rust, C/C++, Go, Java, JSON, YAML, HTML, CSS, Dockerfile, CMake, Markdown, and MDX.
• Provide Markdown Edit, Split, and Preview modes without coupling desktop to the Core Markdown plugin. Preview is lazy, debounced, blocks raw HTML/navigation, and is disabled for Markdown Files over 100,000 characters.
• Hide the File hierarchy and Relationship Graph independently for a code-focused view. Persist pane visibility and sizes as desktop-local interface data.
• Hide profiling by default. The Profile toggle reports File-request latency through two animation frames plus graph counts. It does not claim a CodeMirror-ready or GPU-frame-complete timestamp.
• Animate Zoom In, Zoom Out, and Fit to Screen through the renderer camera path. Pointer/wheel input cancels the transition; reduced-motion users get immediate updates.
• Reuse the Extension's Material colors, icons, geometry, selection treatment, labels, connection sizing, and force-control contract through @codegraphy-dev/graph-renderer/visuals.
• Support Node drag, hover, selection, pan/zoom, release, simulation wake, and settle through the existing renderer/simulation APIs. Graph force changes apply live without restarting Core or Indexing.
• Show live <N> Nodes · <M> Relationships counts. Background deselection does not close the editor File. Graph Settings includes Reset. Panes are resizable. Close File clears only the editor document.
• Reserve Core sidecar stdout for JSON protocol records and route plugin/Core diagnostics to stderr. Reuse the resident Indexing engine instead of running a second full Index.
• Query a Core-owned File/Folder projection for desktop. It avoids full Symbol/fact hydration while returning the same desktop Relationship Graph.
• Prewarm the bundled Core process during Tauri setup while retaining the existing lazy retry if startup fails.
• Add an honest website desktop chapter with the three-pane workbench, local Core and Graph Cache ownership, and a source-only action while production signing and notarization remain gated.

Large-workspace evidence

The original packaged monorepo failure was:

Core service returned invalid data: expected value at line 1 column 2

Godot plugin console.log output was corrupting the JSON Lines stdout protocol. The workspace has fewer than the 3,000 eligible-File budget; the limit was not the cause. The sidecar now reserves stdout for protocol messages and routes Core/plugin diagnostics to stderr.

The final staged app's bundled Core runtime opened the real CodeGraphy monorepo Graph Cache successfully in one resident process:

Measurement	Result
Bundled process ready / read-settings response	273.7 ms
First cached monorepo open response	696.4 ms
Second cached monorepo open response	560.2 ms
File/Folder Nodes	3,556
Relationships	10,432
Previous packaged warm File switching median	29.0 ms
Previous packaged warm File switching p95	53.0 ms
Rapid selection host reads before fix	20
Rapid selection host reads after fix	2 (active + final)
Pending hierarchy scroll frames after fix	1

The user's packaged-app report of approximately 200 ms per File and several seconds of continued movement after Arrow release exposed an unbounded queue: every key event started a Rust read and scheduled another focus/scroll frame. The new queue has at most one active read and one replaceable latest request. The deterministic burst test proves bounded work, but a fresh human-perceived packaged timing is still required because the user revoked GUI/mouse automation. The prior 29.0 ms median / 53.0 ms p95 visual checkpoint predates this queue fix. The Profile timer starts before the Rust request and ends after two animation frames; it is not an editor-ready or GPU-completion measurement.

Verification

Current source checkpoint: 4646c1b98.

• pnpm install --frozen-lockfile passed from this worktree.
• React Doctor: 92/100 with no remaining actionable findings in the changed scope.
• TURBO_FORCE=true pnpm run typecheck: 18/18 tasks, 0 cached.
• pnpm run lint: 18/18 tasks passed.
• Desktop Vitest: 75/75 tests passed.
• Graph renderer Vitest, including the folded visual contract: 282/282 tests passed.
• Extension Vitest in isolation: 1,058/1,058 files and 5,661/5,661 tests passed.
• TURBO_FORCE=true pnpm --filter @codegraphy-dev/extension typecheck passed. It now includes the Extension E2E moduleResolution: node compiler boundary.
• TURBO_FORCE=true pnpm --filter @codegraphy-dev/extension run build:vscode passed: 10/10 build tasks, 0 cached, followed by the E2E compiler step.
• The renderer package resolves /visuals to source inside the workspace and to dist/visuals/index.d.ts in the packed npm manifest. This fixes the prior CI Playwright/VSIX resolution failure at the package boundary without aliases or consumer workarounds.
• Release tests: 50/50 passed.
• Rust format/check/tests passed; 6 Rust tests passed.
• pnpm --filter @codegraphy-dev/desktop build:bundle:ad-hoc built the app and DMG.
• pnpm --filter @codegraphy-dev/desktop check:bundle verified both artifacts, their nested code, the arm64 Node 22.23.2 Core runtime, and the 174 MiB runtime budget.
• /Users/poleski/Desktop/CodeGraphy.app is the final ad-hoc bundle. The previous exact target was not running and was moved to Trash before replacement. The staged app was not launched or controlled.
• CI run 31202269755 passed all 36 required jobs on the current head.
• No docs/research file is included in this PR.

Visual proof

Large-workspace action proof from the previous packaged checkpoint:

Focused graph/workspace interaction proof:

Previous packaged warm timing evidence:

Keyboard-only switching proof from the previous packaged checkpoint:

Website desktop chapter at 1346 × 980:

The interaction GIFs predate the final bounded-navigation fix. They remain useful for product behavior, but they are not presented as proof of the new queue timing.

Release status and external gate

Do not publish the current ad-hoc build. Production release remains externally gated:

1. Review and merge this PR.
2. Configure the protected desktop-release environment with APPLE_CERTIFICATE, APPLE_CERTIFICATE_PASSWORD, APPLE_API_KEY_P8, APPLE_API_KEY, and APPLE_API_ISSUER.
3. Run Desktop release from main with tag desktop-v0.1.0. The workflow must use Xcode 26, Developer ID sign all nested code, notarize and staple the app and DMG, rerun verification, and upload only to a draft GitHub release.
4. Install the draft DMG on a clean Apple Silicon Mac running macOS 26. Repeat the documented open/edit/save/Relationship Graph acceptance check, then publish the draft manually.
5. Enable the website download only after that verified release exists.

Intel Macs, macOS 25 and earlier, and a non-WebGPU renderer path are outside this release.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4646c1b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 6 packages

Name	Type
@codegraphy-dev/graph-renderer	Minor
@codegraphy-dev/core	Patch
@codegraphy-dev/extension	Patch
@codegraphy-dev/tldraw	Patch
@codegraphy-dev/desktop	Patch
@codegraphy/web	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
codegraphy	Ready	Preview	Aug 7, 2026 5:27pm