Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ CI (`.github/workflows/pr-checks.yml`) only runs the frontend build and the back
- **The server never reads the visitor's filesystem.** The browser reads picked files and POSTs `{root, files: [{path, content}]}` to `/api/analyze`. `analyze_path()` and the disk walk in `analyzer.py` exist for the CLI only.
- **The wire format is a two-sided contract.** Backend `FunctionInfo.to_dict()` (`backend/languages/base.py`) emits camelCase; `frontend/src/types.ts` mirrors it by hand. Change one, change the other.
- **`SKIP_DIRS` is duplicated** in `backend/languages/base.py` and `frontend/src/localFiles.ts`. Keep them in sync.
- **The theme is applied in two places.** The inline script in `frontend/index.html` sets `data-theme` before first paint, and `frontend/src/theme.ts` owns it afterwards. They share the storage key and the resolution rules; keep them in sync. Colors belong in the tokens at the top of `index.css`, never as literals (the function card header and the language badge text are the deliberately theme-independent surfaces).
- **Paths must be relative to the picked folder's contents**, with the folder's own name stripped (`localFiles.ts`). Module-name derivation and import resolution in the plugins depend on it.
- **Vocabulary lives in `CONTEXT.md`; use its terms.** The code hasn't caught up on two of them: **File mode** is still `"folder"` in the code (`OrgMode`, `FolderFrame`, `layoutFolderGraph`), and **Trace up / Trace down** is still `showFlow`. Don't rename these as a drive-by; use the glossary term in prose and the code name in code.
- Function and file ids are namespaced by file path so languages can't collide when merged.
Expand Down
14 changes: 14 additions & 0 deletions CONTEXT.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,17 @@ _Avoid_: Folder mode
**Explorer**:
The sidebar's nested tree of the loaded files, each with a small language icon.
_Avoid_: File browser, file list

### Appearance

**Theme**:
The overall appearance of the app: either the **Dark theme** or the **Light theme**. The Dark theme is the original look. "Mode" is not used here because Flow mode and File mode already own that word.
_Avoid_: Color mode, dark mode (as the name of the setting), skin

**Theme preference**:
The user's choice of Theme: **System**, **Light** or **Dark**. It is System until the user picks otherwise, and it is remembered between visits.
_Avoid_: Theme setting, theme mode

**System theme**:
The Theme the user's operating system currently asks for. It decides what the app shows only while the Theme preference is System, and the app follows it as it changes. If the system asks for nothing, the Dark theme applies.
_Avoid_: Auto theme, OS theme
2 changes: 2 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ The goal is to make the flow of a codebase visible instead of jumping between fi
- Follow a function's flow upward (its callers) or downward (what it calls) with one click.
- Auto arrange the graph two ways: by call order (flow mode) or grouped by file (folder mode, draggable as a group).
- Search and a VS Code style file explorer for quick navigation, with a small language icon next to each file.
- A Dark and a Light theme. The topbar toggle cycles System, Light and Dark; System follows the OS and is the default.

### Supported languages

Expand Down Expand Up @@ -73,6 +74,7 @@ sample_rust_project/ Rust demo fixture used for manual testing
- `components/LanguageIcon.tsx`: the small per-file language badge shown in the Explorer.
- `languages.ts`: the frontend's mirror of the backend's language registry - id, label, extensions, icon color per language. Adding a language to the backend also means adding one entry here.
- `api.ts`, `types.ts`, `colors.ts`: fetch wrapper, wire format types, and per file color hashing.
- `theme.ts`, `components/ThemeToggle.tsx`: the theme preference (System, Light or Dark), the System theme tracking, and the topbar toggle. The resolved theme is set as `data-theme` on `<html>`, and every color in `index.css` is a token that the Light theme overrides.

The frontend only talks to the backend over HTTP, with no browser-only file APIs, so it can later be wrapped in an Electron or Tauri shell without changes.

Expand Down
15 changes: 15 additions & 0 deletions frontend/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,22 @@
<meta charset="UTF-8" />
<link rel="icon" type="image/png" href="/favicon.png" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="color-scheme" content="dark light" />
<title>Function Viewer</title>
<script>
// Apply the Theme before first paint so a reload never flashes the wrong one.
// Keep the storage key and the resolution rules in sync with src/theme.ts.
(function () {
var preference = null;
try {
preference = localStorage.getItem("fv-theme-preference");
} catch (e) {}
var theme = "dark";
if (preference === "light" || preference === "dark") theme = preference;
else if (window.matchMedia && window.matchMedia("(prefers-color-scheme: light)").matches) theme = "light";
document.documentElement.setAttribute("data-theme", theme);
})();
</script>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
Expand Down
10 changes: 7 additions & 3 deletions frontend/src/components/GraphCanvas.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -25,8 +25,10 @@ import {
type Point,
} from "../layout";
import { useViewer, type OrgMode } from "../store";
import { selectTheme, useTheme } from "../theme";
import { FolderFrame, type FolderFrameType } from "./FolderFrame";
import { FunctionNode, type FunctionNodeType } from "./FunctionNode";
import { ThemeToggle } from "./ThemeToggle";

const nodeTypes = { function: FunctionNode, folder: FolderFrame };

Expand All @@ -40,6 +42,7 @@ export function GraphCanvas() {
const focusRequest = useViewer((s) => s.focusRequest);
const layoutEpoch = useViewer((s) => s.layoutEpoch);
const layoutMode = useViewer((s) => s.layoutMode);
const theme = useTheme(selectTheme);

const [nodes, setNodes] = useState<Node[]>([]);
const [hoveredId, setHoveredId] = useState<string | null>(null);
Expand Down Expand Up @@ -397,6 +400,7 @@ export function GraphCanvas() {
>
⛶ Fit view
</button>
<ThemeToggle />
</div>
</div>
{graph && visible.size === 0 && (
Expand Down Expand Up @@ -431,8 +435,10 @@ export function GraphCanvas() {
proOptions={{ hideAttribution: true }}
nodesConnectable={false}
deleteKeyCode={null}
colorMode={theme}
>
<Background variant={BackgroundVariant.Dots} gap={26} size={1.6} color="#1b2634" />
{/* dot grid, minimap background and mask take their colors from the theme tokens (see .react-flow in index.css) */}
<Background variant={BackgroundVariant.Dots} gap={26} size={1.6} />
<MiniMap
pannable
zoomable
Expand All @@ -441,8 +447,6 @@ export function GraphCanvas() {
? "transparent"
: fileColor((n as FunctionNodeType).data.fn.file)
}
maskColor="rgba(6, 10, 15, 0.75)"
bgColor="#0d1219"
/>
</ReactFlow>
</div>
Expand Down
22 changes: 22 additions & 0 deletions frontend/src/components/ThemeToggle.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
import { nextPreference, selectTheme, useTheme, type ThemePreference } from "../theme";

const GLYPHS: Record<ThemePreference, string> = { system: "◐", light: "☀", dark: "☾" };
const NAMES: Record<ThemePreference, string> = { system: "System", light: "Light", dark: "Dark" };

export function ThemeToggle() {
const preference = useTheme((s) => s.preference);
const theme = useTheme(selectTheme);
const cycle = useTheme((s) => s.cycle);

const current = preference === "system" ? `System (currently ${NAMES[theme]})` : NAMES[preference];

return (
<button
className="btn theme-toggle"
title={`Theme: ${current}. Click for ${NAMES[nextPreference(preference)]}.`}
onClick={cycle}
>
{GLYPHS[preference]} {NAMES[preference]}
</button>
);
}
Loading
Loading