feat(ui): serve the upstream browser viewer (#298)

Port upstream v1.6.1's browser viewer as the codegraph-ui crate: a loopback server that answers the viewer API from an existing index (stats, search, node, source, file, routes, entry points, map, dead code, flow, screens, trails, and live updates over server-sent events) with upstream's wire shapes, limits, error codes and security boundary, serving the upstream ui/ frontend embedded in the binary, changed in one adapter line.
- Engine ports the routes need, all read-only: dead code, named-symbol flow, flow continuations, symbol lookup, type hierarchy, ICU-order collation and the viewer's aggregate store queries; WatchOptions::observe_only lets the live channel reuse the watcher without writing the index.
- codegraph ui (alias web), gated by CODEGRAPH_UI=1 exactly as upstream gates it.
- A UI CI job rebuilds the committed bundle and fails on any drift.
- Steps and screen navigation wait for their ports; docs/ui.md lists every difference from upstream.
No extraction, resolution or schema change; golden output is unchanged.

Author: sunerpy

.github/workflows/ci.yml

@@ -229,6 +229,29 @@ jobs:
           cargo test -p codegraph-extract --locked --test scan_symlinks
           cargo test -p codegraph-watch --locked symlink
 
+  ui:
+    name: UI
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    steps:
+      - name: Checkout
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Set up Node.js
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: ui/package-lock.json
+
+      # npm ci from the committed lockfile, svelte-check, the vitest suites, a
+      # production build, and a byte check that the embedded bundle under
+      # crates/codegraph-ui/viewer is exactly this build.
+      - name: Check, test and rebuild the viewer
+        run: make ui-check
+
   audit:
     name: Security Audit
     needs: workspace-version
@@ -306,7 +329,7 @@ jobs:
 
   ci-success:
     name: CI Success
-    needs: [workspace-version, linux, windows-clippy, windows-test, macos-watcher, audit]
+    needs: [workspace-version, linux, windows-clippy, windows-test, macos-watcher, ui, audit]
     if: always()
     runs-on: ubuntu-24.04
     timeout-minutes: 5

.gitignore

@@ -34,3 +34,6 @@ target/llvm-cov/
 .aws/*.local
 .aws/*.rendered.local.json
 .aws/pipeline.rendered*
+
+# The browser viewer's npm install (ui/); its build output is committed under crates/codegraph-ui/viewer/.
+node_modules/

.oxfmtignore

@@ -14,6 +14,10 @@ release-please-config.json
 docs/upstream-sync/UPSTREAM.md
 docs/upstream-sync/V1_5_COMMIT_MANIFEST.md
 
+# The selected viewer design, transcribed from the Penpot boards: its tables
+# are numeric specs read against the board exports, so their layout is frozen.
+docs/design/viewer-d.md
+
 # Golden artifacts are byte-compared by the equivalence/golden oracle tests
 # (include_str! / fs::read). Reformatting them breaks the test suite.
 reference/
@@ -40,6 +44,13 @@ KNOWN_DIFFS.md
 # Rust sources are formatted by `cargo fmt`.
 *.rs
 
+# The browser viewer is vendored from upstream colbymchenry/codegraph (ui/,
+# MIT, see ui/LICENSE) and keeps upstream's formatting so it stays diffable
+# against the release it was imported from; svelte-check and the UI tests are
+# its gate. Its committed build output is generated, not authored.
+ui/
+crates/codegraph-ui/viewer/
+
 # Build artifacts / vendored deps.
 target/
 dist/

AGENTS.md

@@ -71,18 +71,19 @@ or required by that guidance.
 The workspace members are declared in root `Cargo.toml`; that manifest is the
 authority when the list changes.
 
-| Crate                            | Owns                                                               |
-| -------------------------------- | ------------------------------------------------------------------ |
-| `codegraph-core`                 | shared types, config, IDs, file classification, logging            |
-| `codegraph-extract`              | language detection, tree-sitter/custom extraction, scan policy     |
-| `codegraph-store`                | SQLite schema/migrations, FTS5, persistence and queries            |
-| `codegraph-resolve`              | import/name resolution and framework resolvers                     |
-| `codegraph-graph`                | traversal, impact, search scoring and query parsing                |
-| `codegraph-mcp`                  | MCP schemas, rmcp transports, project resolution, tool rendering   |
-| `codegraph-watch`                | incremental synchronization and filesystem watching                |
-| `codegraph-daemon`               | shared process lifecycle, IPC, registries and detach behavior      |
-| `codegraph-cli` (`codegraph-rs`) | CLI, installer, orchestration and shipped binary                   |
-| `codegraph-bench`                | equivalence oracle and reproducible benchmark harness; not shipped |
+| Crate                            | Owns                                                                  |
+| -------------------------------- | --------------------------------------------------------------------- |
+| `codegraph-core`                 | shared types, config, IDs, file classification, logging               |
+| `codegraph-extract`              | language detection, tree-sitter/custom extraction, scan policy        |
+| `codegraph-store`                | SQLite schema/migrations, FTS5, persistence and queries               |
+| `codegraph-resolve`              | import/name resolution and framework resolvers                        |
+| `codegraph-graph`                | traversal, impact, search scoring and query parsing                   |
+| `codegraph-mcp`                  | MCP schemas, rmcp transports, project resolution, tool rendering      |
+| `codegraph-watch`                | incremental synchronization and filesystem watching                   |
+| `codegraph-daemon`               | shared process lifecycle, IPC, registries and detach behavior         |
+| `codegraph-ui`                   | browser viewer: loopback JSON API, live channel, embedded `ui/` build |
+| `codegraph-cli` (`codegraph-rs`) | CLI, installer, orchestration and shipped binary                      |
+| `codegraph-bench`                | equivalence oracle and reproducible benchmark harness; not shipped    |
 
 Keep dependency direction acyclic and lower layers independent of presentation.
 Extraction must not depend on store/graph. Query rendering must not leak into core
@@ -93,17 +94,18 @@ semantics. See [`docs/architecture.md`](docs/architecture.md) for the current gr
 Run the narrowest relevant tests while iterating, then the complete gate before
 handoff. Do not use a narrow test to claim a workspace-wide property.
 
-| Change                     | Minimum focused proof                                                  | Required documentation                                                       |
-| -------------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
-| extraction/language rules  | extractor tests; affected golden corpus; incremental/full equivalence  | `languages.md`, `grammar-manifest.md`, and golden recipe when behavior moves |
-| resolution/framework rules | resolver unit/integration tests; ambiguity negatives; affected golden  | `equivalence.md` or framework reference when public behavior moves           |
-| schema/migrations/store    | schema parity; migration replay; state/lease tests; golden equivalence | `data-model.md`                                                              |
-| graph/search               | graph/query tests; deterministic ordering and limit cases              | CLI/MCP docs for public output changes                                       |
-| MCP/protocol               | engine tests; structural MCP goldens; rmcp stdio/HTTP/version tests    | `mcp.md`                                                                     |
-| CLI/installer              | command tests; installer round trips; script contract fixtures         | `cli.md`, README only for landing-page behavior                              |
-| daemon/watch/concurrency   | lifecycle, lock, recovery, watcher and platform-focused tests          | architecture/CLI/MCP lifecycle sections                                      |
-| release/install/checksum   | shell/PowerShell fixtures, asset-name checks, archive smoke            | README install section and release workflow contract                         |
-| docs/community files       | `python3 scripts/docs-check.py`; formatter; link/anchor checks         | update the canonical page, not a duplicate summary                           |
+| Change                         | Minimum focused proof                                                                                        | Required documentation                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| extraction/language rules      | extractor tests; affected golden corpus; incremental/full equivalence                                        | `languages.md`, `grammar-manifest.md`, and golden recipe when behavior moves |
+| resolution/framework rules     | resolver unit/integration tests; ambiguity negatives; affected golden                                        | `equivalence.md` or framework reference when public behavior moves           |
+| schema/migrations/store        | schema parity; migration replay; state/lease tests; golden equivalence                                       | `data-model.md`                                                              |
+| graph/search                   | graph/query tests; deterministic ordering and limit cases                                                    | CLI/MCP docs for public output changes                                       |
+| MCP/protocol                   | engine tests; structural MCP goldens; rmcp stdio/HTTP/version tests                                          | `mcp.md`                                                                     |
+| CLI/installer                  | command tests; installer round trips; script contract fixtures                                               | `cli.md`, README only for landing-page behavior                              |
+| daemon/watch/concurrency       | lifecycle, lock, recovery, watcher and platform-focused tests                                                | architecture/CLI/MCP lifecycle sections                                      |
+| release/install/checksum       | shell/PowerShell fixtures, asset-name checks, archive smoke                                                  | README install section and release workflow contract                         |
+| viewer (`codegraph-ui`, `ui/`) | crate tests over indexed fixtures; `cli_ui`; `make ui-check` (rebuilds and byte-checks the committed bundle) | `ui.md`; `cli.md` for the command                                            |
+| docs/community files           | `python3 scripts/docs-check.py`; formatter; link/anchor checks                                               | update the canonical page, not a duplicate summary                           |
 
 If a change alters nodes, edges, reference resolution, file classification, or
 stored graph meaning, decide explicitly whether the extraction version must move.
@@ -136,7 +138,10 @@ The authoritative local/CI entry point is:
 make check
 ```
 
-`make ci` is a compatibility alias for the same complete gate. `make pre-ci` adds a package/unpack/execute smoke over the built release bytes.
+`make ci` is a compatibility alias for the same complete gate. `make pre-ci` adds the
+viewer frontend gate (`make ui-check`: `npm ci`, svelte-check, vitest, a production
+build, and a byte check of the committed bundle under `crates/codegraph-ui/viewer`)
+and a package/unpack/execute smoke over the built release bytes.
 It validates workspace-version consistency before any Cargo subprocess, required
 tool versions, Rust and repository-text formatting, workflow/shell linting,
 Clippy with warnings denied, locked tests, a locked release build, guardrails,

Cargo.lock

@@ -8,6 +8,7 @@ members = [
     "crates/codegraph-mcp",
     "crates/codegraph-daemon",
     "crates/codegraph-watch",
+    "crates/codegraph-ui",
     "crates/codegraph-cli",
     "crates/codegraph-bench",
 ]

Cargo.toml

@@ -15,7 +15,7 @@ OXFMT_ARGS := --no-error-on-unmatched-pattern --ignore-path .oxfmtignore .
 .PHONY: all build build-dev build-prod release release-target install uninstall \
         fmt fmt-rust fmt-oxfmt fmt-check fmt-rust-check fmt-oxfmt-check \
         tools-check workflow-lint docs-check workspace-version typecheck lint test guardrail script-tests archive-smoke \
-        check ci pre-ci hooks setup-hooks clean size-compare help \
+        check ci pre-ci ui ui-check hooks setup-hooks clean size-compare help \
         coverage coverage-html coverage-lcov coverage-open coverage-clean
 
 all: build
@@ -139,7 +139,23 @@ check:
 	@echo "All checks passed."
 
 ci: check
-pre-ci: check archive-smoke
+pre-ci: check ui-check archive-smoke
+
+# Rebuild the embedded viewer bundle (crates/codegraph-ui/viewer) from ui/.
+ui:
+	cd ui && npm ci && npm run build
+
+# The browser viewer's frontend (`ui/`, Node + npm): install from the lockfile,
+# type-check, test, rebuild, and require the committed bundle under
+# crates/codegraph-ui/viewer to be exactly that build. CI runs it as its own job.
+ui-check:
+	cd ui && npm ci && npm run check && npm test && npm run build
+	git diff --exit-code -- crates/codegraph-ui/viewer
+	@stale="$$(git status --porcelain --untracked-files=all -- crates/codegraph-ui/viewer)"; \
+		if [ -n "$$stale" ]; then \
+			echo "the committed viewer bundle is not this build; commit crates/codegraph-ui/viewer:"; \
+			echo "$$stale"; exit 1; \
+		fi
 
 archive-smoke:
 	bash scripts/smoke-release-archive.sh
@@ -189,7 +205,8 @@ help:
 	@printf '%s\n' \
 		'Targets:' \
 		'  check / ci           complete quality gate (ci is an alias)' \
-		'  pre-ci               complete gate plus local archive smoke' \
+		'  pre-ci               complete gate, viewer frontend, and local archive smoke' \
+		'  ui / ui-check        rebuild the viewer bundle / also check, test, and byte-check it' \
 		'  fmt / fmt-check       Rust plus repository text formatting' \
 		'  typecheck              locked cargo check for the workspace' \
 		'  lint / test / release locked Rust gates and shipped build' \

Makefile

@@ -291,6 +291,7 @@ make check
 - [`docs/architecture.md`](docs/architecture.md) — workspace and runtime design
 - [`docs/cli.md`](docs/cli.md) — complete command reference
 - [`docs/mcp.md`](docs/mcp.md) — MCP transports, tools, and clients
+- [`docs/ui.md`](docs/ui.md) — local browser viewer (preview, `CODEGRAPH_UI=1`)
 - [`docs/languages.md`](docs/languages.md) — language coverage and boundaries
 - [`docs/equivalence.md`](docs/equivalence.md) — deterministic golden contract
 - [`docs/upstream-sync/UPSTREAM.md`](docs/upstream-sync/UPSTREAM.md) — upstream ledger

README.md

@@ -25,6 +25,7 @@ codegraph-graph = { path = "../codegraph-graph" }
 codegraph-mcp = { path = "../codegraph-mcp" }
 codegraph-resolve = { path = "../codegraph-resolve" }
 codegraph-store = { path = "../codegraph-store" }
+codegraph-ui = { path = "../codegraph-ui" }
 codegraph-watch = { path = "../codegraph-watch" }
 serde = { workspace = true }
 serde_json = { workspace = true }