docs: add human-oriented CONTRIBUTING.md (repo map, FFI notes, gotchas, release & tap auto-sync workflow)

CONTRIBUTING.md

@@ -0,0 +1,200 @@
+# Contributing to PodTui
+
+This file is written **for humans**. If you're an AI agent or LLM working in
+this repo, read [AGENTS.md](AGENTS.md) instead — it has the machine-oriented
+build/test/lint contract and code-style rules. Both describe the same project;
+CONTRIBUTING.md focuses on *understanding* and *navigating* the codebase.
+
+PodTui is a keyboard-first, yazi-style terminal podcast client. TypeScript +
+[OpenTUI](https://github.com/opentui/opentui) on top, [Bun](https://bun.sh)
+as the runtime and toolchain.
+
+---
+
+## Quick start
+
+```bash
+brew install bun          # or: curl -fsSL https://bun.sh/install | bash
+git clone git@github.com:mikefreno/podtui.git
+cd podtui
+
+bun install               # install JS dependencies
+make native               # build libcavacore.dylib from the vendored C source
+bun run dev               # launch with hot reload (alias: make dev)
+```
+
+The app is a TUI — it expects a real terminal (kitty, iTerm2, WezTerm, tmux,
+…). It will not render in a plain captured `bash` session.
+
+## What each command does
+
+| Command            | Purpose                                                                  |
+|--------------------|--------------------------------------------------------------------------|
+| `bun install`      | Install JS dependencies                                                  |
+| `make native`      | Compile `cava/cavacore.c` → `src/native/libcavacore.<dylib\|so>`          |
+| `bun run dev`      | Run with hot reload                                                       |
+| `bun run start`    | Run once (no watch)                                                       |
+| `bun test`         | Run the test suite (see [Testing](#testing))                              |
+| `make lint`        | Type-check with `bun tsc --noEmit`                                        |
+| `bun run build`    | Bundle JS into `dist/` + copy native libs (the `podtui` npm script path)  |
+| `make dist`        | Compile the standalone binary + make the current platform's tarball       |
+| `make clean`       | Remove `dist/`                                                             |
+
+> Note: `package.json` also has a `lint` script that points at a
+> `lint.ts` file that doesn't exist. Use `make lint` (real type-checking).
+
+## Repository layout
+
+```
+src/
+  api/          Network + XML/RSS — client.ts, rss-parser.ts
+  components/   Reusable UI pieces: Shell, Navigation, YaziPaneRow, TabPanel…
+  config/       App config: keybinds.jsonc, shortcuts, auth
+  constants/    Static tables (sync formats, themes)
+  context/      Solid contexts: KeybindContext, NavigationContext, ThemeContext
+  hooks/        useAudio, useMultimediaKeys, useCachedData
+  native/       FFI glue + the built libcavacore.{dylib,so}
+  pages/        App screens: Feed, MyShows, Discover, Search, Player, Settings
+  stores/       Zustand stores — app, feed, audio-nav, search, auth, progress…
+  styles/       theme.css
+  themes/       catppuccin, gruvbox, nord, tokyo schemes + schema.json
+  types/        All shared interfaces (podcast, episode, feed, settings…)
+  ui/           Modal-adjacent UI: command.tsx, dialog.tsx, toast.tsx
+  utils/        Parser/persistence/audio helpers (audio-player, config-dir…)
+scripts/
+  build-cavacore.sh   C → shared lib; finds libfftw3.a on macOS & Debian
+  tui-harness.tsx     Headless harness for scripted interaction (see below)
+cava/                 Vendored cavacore C source (MIT, from karlstav/cava)
+tests/                bun test suite + cavacore smoke test
+dist/                 Build output (JS bundle + libs + tarballs)
+```
+
+## Native libraries: how the FFI layer works
+
+PodTui loads **two** native libraries at runtime:
+
+1. **libopentui** — the OpenTUI renderer (shipped inside the
+   `@opentui/core-<platform>-<arch>` npm packages, copied to `dist/` by
+   `build.ts`).
+2. **libcavacore** — the audio spectrum renderer, built from C. The source is
+   vendored under `cava/` (it must stay committed — every CI runner builds it).
+   `libfftw3` is needed to build it:
+   - macOS: `brew install fftw`
+   - Debian/Ubuntu: `apt-get install libfftw3-dev`
+   (CI installs it for you; locally run `make native`.)
+
+**Critical sibling rule**: both libraries are loaded *relative to the binary*,
+so `podtui`, `libopentui.*` and `libcavacore.*` must sit in the **same
+directory**. Never move a single binary out of the tarball. The Homebrew
+formula keeps all three in `libexec/` and exposes only a `podtui` symlink.
+
+Cavacore smoke test: `bun tests/cavacore-smoke.ts`
+(FFI-calls `cava_init` / `cava_execute` / `cava_destroy` and prints results).
+
+## Gotchas (read before touching anything)
+
+1. **Never add a top-level `preload` to `bunfig.toml`.**
+   A compiled PodTui binary's embedded runtime reads the *launching process's*
+   CWD `bunfig.toml`, and a `preload` entry points at a module the standalone
+   can't resolve (`@opentui/solid/preload`) → the binary dies at startup with
+   `preload not found`. This is why `bunfig.toml` has **no** top-level
+   `preload`; dev-mode preloading happens via explicit `--preload` flags in
+   `package.json`. The `[test]` section *does* keep a preload — that only
+   affects `bun test`.
+
+2. **Smoke-test the compiled binary from a bunfig-free dir.**
+   Because of (1), `./dist/podtui --version` run from the repo root launched
+   inside CI would fail. CI always unpacks the tarball into a `mktemp` dir
+   before booting. Do the same when testing a release build locally.
+
+3. **Homebrew's dylib-repair warning is benign.**
+   `brew install` may print “load commands do not fit in the header … needs
+   `-headerpad`” for a prebuilt dylib. The app dlopens the libs by path, so
+   the warning is cosmetic; installs complete and the app boots.
+
+4. **`make lint` is the truth, not the `package.json` scripts.**
+   The repo's ESLint wiring is stale; `make lint` runs the real
+   type-check and is what CI treats as the clean bar.
+
+## Testing
+
+```bash
+bun test                # full suite   (54 tests across 6 files today)
+```
+
+The suite covers the keyboard/nav model, keybind dispatch, and the yazi pane
+logic; plus `tests/cavacore-smoke.ts` asserting the native lib exports.
+
+For scripted end-to-end interaction there's a **headless harness**,
+`scripts/tui-harness.tsx`: each invocation snapshot-rebuilds the app state
+into a sandboxed `.harness/` config dir, replays the saved action log
+(`.harness/actions.json`), executes one more key/action passed on the CLI, and
+prints the resulting frame + a style summary — all without a real terminal.
+Audio is a no-op during those snapshots. The last frame lands in
+`.harness/last-frame.{json,txt}` for inspection.
+
+## Releasing
+
+Releases are built and published from **tags**; CI does the heavy lifting.
+
+### Steps
+
+1. Bump `VERSION` in `src/index.tsx` (e.g. `0.1.0` → `0.2.0`). Commit and push.
+2. Tag and push:
+
+   ```bash
+   git tag -a v0.2.0 -m 'PodTUI v0.2.0' && git push gh v0.2.0
+   ```
+
+3. CI (`.github/workflows/release.yml`) runs four builds in parallel,
+   each producing `podtui-<platform>-<arch>.tar.gz`:
+
+   | Runner              | Platform/Arch |
+   |---------------------|---------------|
+   | `ubuntu-latest`     | linux-x64     |
+   | `ubuntu-24.04-arm`  | linux-arm64   |
+   | `macos-15-intel`    | darwin-x64    |
+   | `macos-14`          | darwin-arm64  |
+
+   Each runner: installs deps → installs fftw → `scripts/build-cavacore.sh`
+   → `make dist` → smoke-boots the binary from a temp dir → uploads the
+   tarball. (`macos-15-intel` matters: GitHub's `macos-latest` is arm64 now.)
+
+4. A release is auto-created with all 4 tarballs attached. `brew` never
+   sees the new version: the **tap self-updates**: the
+   `mikefreno/homebrew-podtui` repo has a scheduled workflow (hourly) that
+   polls GitHub releases, and when a new tag appears, rewrites
+   `Formula/podtui.rb` (URLs + arm64/x64 `sha256`) and pushes it — no
+   secrets. See `scripts/sync-formula.sh` in that repo for the logic. Local
+   test: `brew install mikefreno/podtui/podtui`.
+
+### Manual fallback
+
+If you ever need to sync the tap by hand (or before the hourly job runs):
+
+```bash
+cd <clone of mikefreno/homebrew-podtui>
+./scripts/sync-formula.sh 0.2.0
+git commit -am 'podtui 0.2.0' && git push
+```
+
+### Local release build
+
+```bash
+make dist          # builds the binary + tarball for THIS machine only
+```
+
+Bun cannot cross-compile — the other platforms come from CI.
+
+---
+
+## Open items / things to sort out
+
+- **LICENSE**: `README.md` says "TBD — choose and document a license before
+  the first release". Pick one (MIT/BSD-3) and add `LICENSE` + update the
+  README footer.
+- **Native libs in `dist/` still need committing?** No — they're built from
+  sources kept in the repo (`cava/`, `node_modules/@opentui/core-*`). Only
+  `src/native/libcavacore.dylib` is a committed binary artifact; macOS arm64
+  ships from it directly until a full rebuild replaces it. On other hosts the
+  `make native` build is required — see `scripts/build-cavacore.sh`.

notes.md

@@ -1,7 +0,0 @@
-- [x] Audio play can survive quit out
-- [x] Discover tab does not move highlight on jk, only moves a star, My Feeds tab
-moves nothing, other tabs(and main tab panel) are the correct pattern
-- [x] Weird focus colors happen at times, the search panel does not get the correct pane
-border color when focused for instance
-- [x] Feed tab needs to fully drop the depth 1 panel - its effectively a duplication
-of My Shows - Just immediately go into the full list

src/pages/Search/SearchPage.tsx

@@ -25,6 +25,7 @@ import {
 	onCleanup,
 } from "solid-js";
 import { useSearchStore } from "@/stores/search";
+import { useFeedStore } from "@/stores/feed";
 import { format } from "date-fns";
 import { useTheme } from "@/context/ThemeContext";
 import {
@@ -44,6 +45,7 @@ export const SearchPaneCount = 1;
 
 function SearchPage() {
 	const searchStore = useSearchStore();
+	const feedStore = useFeedStore();
 	const [inputValue, setInputValue] = createSignal("");
 	const { theme } = useTheme();
 	const muted = () => theme.muted || theme.text;
@@ -127,6 +129,8 @@ function SearchPage() {
 	};
 
 	const handleSubscribe = (result: SearchResult) => {
+		// Actually add the feed to the feed store, then mark the result subscribed
+		feedStore.addFeed(result.podcast, result.sourceId).catch(() => {});
 		searchStore.markSubscribed(result.podcast.id);
 	};
 

src/stores/discover.ts

@@ -3,13 +3,14 @@
  * Manages trending/popular podcasts and category filtering
  */
 
-import { createSignal } from "solid-js"
+import { createSignal } from "solid-js";
-import type { Podcast } from "../types/podcast"
+import type { Podcast } from "../types/podcast";
+import { useFeedStore } from "./feed";
 
 export interface DiscoverCategory {
-  id: string
+	id: string;
-  name: string
+	name: string;
-  icon: string
+	icon: string;
 }
 
 export const DISCOVER_CATEGORIES: DiscoverCategory[] = [
@@ -24,14 +25,15 @@ export const DISCOVER_CATEGORIES: DiscoverCategory[] = [
 	{ id: "sports", name: "Sports", icon: "#" },
 	{ id: "true-crime", name: "True Crime", icon: "%" },
 	{ id: "arts", name: "Arts", icon: "@" },
-]
+];
 
 /** Mock trending podcasts */
 const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-1",
 		title: "AI Today",
-    description: "The latest developments in artificial intelligence, machine learning, and their impact on society.",
+		description:
+			"The latest developments in artificial intelligence, machine learning, and their impact on society.",
 		feedUrl: "https://example.com/aitoday.rss",
 		author: "Tech Futures",
 		categories: ["Technology", "Science"],
@@ -42,7 +44,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-2",
 		title: "The History Hour",
-    description: "Fascinating stories from history that shaped our world today.",
+		description:
+			"Fascinating stories from history that shaped our world today.",
 		feedUrl: "https://example.com/historyhour.rss",
 		author: "History Channel",
 		categories: ["Education", "History"],
@@ -52,7 +55,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-3",
 		title: "Comedy Gold",
-    description: "Weekly stand-up comedy, sketches, and hilarious conversations.",
+		description:
+			"Weekly stand-up comedy, sketches, and hilarious conversations.",
 		feedUrl: "https://example.com/comedygold.rss",
 		author: "Laugh Factory",
 		categories: ["Comedy", "Entertainment"],
@@ -72,7 +76,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-5",
 		title: "Science Weekly",
-    description: "Breaking science news and in-depth analysis of the latest research.",
+		description:
+			"Breaking science news and in-depth analysis of the latest research.",
 		feedUrl: "https://example.com/scienceweekly.rss",
 		author: "Science Network",
 		categories: ["Science", "Education"],
@@ -82,7 +87,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-6",
 		title: "True Crime Files",
-    description: "Investigative journalism into real criminal cases and unsolved mysteries.",
+		description:
+			"Investigative journalism into real criminal cases and unsolved mysteries.",
 		feedUrl: "https://example.com/truecrime.rss",
 		author: "Crime Network",
 		categories: ["True Crime", "Documentary"],
@@ -92,7 +98,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-7",
 		title: "Wellness Journey",
-    description: "Tips for mental and physical health, meditation, and mindful living.",
+		description:
+			"Tips for mental and physical health, meditation, and mindful living.",
 		feedUrl: "https://example.com/wellness.rss",
 		author: "Health Media",
 		categories: ["Health", "Self-Help"],
@@ -102,7 +109,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-8",
 		title: "Sports Talk Live",
-    description: "Live commentary, analysis, and interviews from the world of sports.",
+		description:
+			"Live commentary, analysis, and interviews from the world of sports.",
 		feedUrl: "https://example.com/sportstalk.rss",
 		author: "Sports Network",
 		categories: ["Sports", "News"],
@@ -112,7 +120,8 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-9",
 		title: "Creative Minds",
-    description: "Interviews with artists, designers, and creative professionals.",
+		description:
+			"Interviews with artists, designers, and creative professionals.",
 		feedUrl: "https://example.com/creativeminds.rss",
 		author: "Arts Weekly",
 		categories: ["Arts", "Culture"],
@@ -122,70 +131,81 @@ const TRENDING_PODCASTS: Podcast[] = [
 	{
 		id: "trend-10",
 		title: "Dev Talk",
-    description: "Software development, programming tutorials, and tech career advice.",
+		description:
+			"Software development, programming tutorials, and tech career advice.",
 		feedUrl: "https://example.com/devtalk.rss",
 		author: "Code Academy",
 		categories: ["Technology", "Education"],
 		lastUpdated: new Date(),
 		isSubscribed: true,
 	},
-]
+];
 
 /** Create discover store */
 export function createDiscoverStore() {
-  const [selectedCategory, setSelectedCategory] = createSignal<string>("all")
+	const [selectedCategory, setSelectedCategory] = createSignal<string>("all");
-  const [isLoading, setIsLoading] = createSignal(false)
+	const [isLoading, setIsLoading] = createSignal(false);
-  const [podcasts, setPodcasts] = createSignal<Podcast[]>(TRENDING_PODCASTS)
+	const [podcasts, setPodcasts] = createSignal<Podcast[]>(TRENDING_PODCASTS);
 
 	/** Get filtered podcasts by category */
 	const filteredPodcasts = () => {
-    const category = selectedCategory()
+		const category = selectedCategory();
 		if (category === "all") {
-      return podcasts()
+			return podcasts();
 		}
 
 		return podcasts().filter((p) => {
-      const cats = p.categories?.map((c) => c.toLowerCase()) ?? []
+			const cats = p.categories?.map((c) => c.toLowerCase()) ?? [];
-      return cats.some((c) => c.includes(category.toLowerCase().replace("-", " ")))
+			return cats.some((c) =>
-    })
+				c.includes(category.toLowerCase().replace("-", " ")),
-  }
+			);
+		});
+	};
 
 	/** Subscribe to a podcast */
 	const subscribe = (podcastId: string) => {
-    setPodcasts((prev) =>
+		const podcast = podcasts().find((p) => p.id === podcastId);
-      prev.map((p) =>
+		if (podcast) {
-        p.id === podcastId ? { ...p, isSubscribed: true } : p
+			// Actually add the feed to the feed store
-      )
+			const feedStore = useFeedStore();
-    )
+			feedStore.addFeed(podcast, "discover").catch(() => {});
 		}
+		setPodcasts((prev) =>
+			prev.map((p) => (p.id === podcastId ? { ...p, isSubscribed: true } : p)),
+		);
+	};
 
 	/** Unsubscribe from a podcast */
 	const unsubscribe = (podcastId: string) => {
-    setPodcasts((prev) =>
+		const podcast = podcasts().find((p) => p.id === podcastId);
-      prev.map((p) =>
+		if (podcast) {
-        p.id === podcastId ? { ...p, isSubscribed: false } : p
+			// Remove the feed from the feed store
-      )
+			const feedStore = useFeedStore();
-    )
+			feedStore.removeFeedByUrl(podcast.feedUrl);
 		}
+		setPodcasts((prev) =>
+			prev.map((p) => (p.id === podcastId ? { ...p, isSubscribed: false } : p)),
+		);
+	};
 
 	/** Toggle subscription */
 	const toggleSubscription = (podcastId: string) => {
-    const podcast = podcasts().find((p) => p.id === podcastId)
+		const podcast = podcasts().find((p) => p.id === podcastId);
 		if (podcast?.isSubscribed) {
-      unsubscribe(podcastId)
+			unsubscribe(podcastId);
 		} else {
-      subscribe(podcastId)
+			subscribe(podcastId);
-    }
 		}
+	};
 
 	/** Refresh trending podcasts (mock) */
 	const refresh = async () => {
-    setIsLoading(true)
+		setIsLoading(true);
 		// Simulate network delay
-    await new Promise((r) => setTimeout(r, 500))
+		await new Promise((r) => setTimeout(r, 500));
 		// In real app, would fetch from API
-    setIsLoading(false)
+		setIsLoading(false);
-  }
+	};
 
 	return {
 		// State
@@ -201,15 +221,15 @@ export function createDiscoverStore() {
 		unsubscribe,
 		toggleSubscription,
 		refresh,
-  }
+	};
 }
 
 /** Singleton discover store */
-let discoverStoreInstance: ReturnType<typeof createDiscoverStore> | null = null
+let discoverStoreInstance: ReturnType<typeof createDiscoverStore> | null = null;
 
 export function useDiscoverStore() {
 	if (!discoverStoreInstance) {
-    discoverStoreInstance = createDiscoverStore()
+		discoverStoreInstance = createDiscoverStore();
 	}
-  return discoverStoreInstance
+	return discoverStoreInstance;
 }

src/stores/feed.ts

@@ -7,8 +7,8 @@ import { createSignal } from "solid-js";
 import { FeedVisibility } from "../types/feed";
 import type { Feed, FeedFilter, FeedSortField } from "../types/feed";
 import type { Podcast } from "../types/podcast";
-import type { Episode, EpisodeStatus } from "../types/episode";
+import type { Episode } from "../types/episode";
-import type { PodcastSource, SourceType } from "../types/source";
+import type { PodcastSource } from "../types/source";
 import { DEFAULT_SOURCES } from "../types/source";
 import { parseRSSFeed } from "../api/rss-parser";
 import {
@@ -69,7 +69,11 @@ export function createFeedStore() {
 			result = result.filter((feed) => feed.visibility === f.visibility);
 		} else if (f.visibility === "all") {
 			// Only show private feeds if authenticated
-      result = result.filter((feed) => feed.visibility === FeedVisibility.PUBLIC || authStore.isAuthenticated);
+			result = result.filter(
+				(feed) =>
+					feed.visibility === FeedVisibility.PUBLIC ||
+					authStore.isAuthenticated,
+			);
 		}
 
 		// Filter by source
@@ -184,12 +188,22 @@ export function createFeedStore() {
 		}
 	};
 
+	/** Check if a feed with this URL already exists */
+	const hasFeedByUrl = (feedUrl: string): boolean => {
+		return feeds().some((f) => f.podcast.feedUrl === feedUrl);
+	};
+
 	/** Add a new feed and auto-fetch latest 20 episodes */
 	const addFeed = async (
 		podcast: Podcast,
 		sourceId: string,
 		visibility: FeedVisibility = FeedVisibility.PUBLIC,
-  ) => {
+	): Promise<Feed | null> => {
+		// Guard: don't add a feed we already have (matched by feedUrl)
+		if (hasFeedByUrl(podcast.feedUrl)) {
+			return feeds().find((f) => f.podcast.feedUrl === podcast.feedUrl) ?? null;
+		}
+
 		const feedId = crypto.randomUUID();
 		const episodes = await fetchEpisodes(
 			podcast.feedUrl,
@@ -300,6 +314,20 @@ export function createFeedStore() {
 		});
 	};
 
+	/** Remove a feed by its RSS URL (for sources that match by URL, not ID) */
+	const removeFeedByUrl = (feedUrl: string) => {
+		const feed = feeds().find((f) => f.podcast.feedUrl === feedUrl);
+		if (feed) {
+			fullEpisodeCache.delete(feed.id);
+			episodeLoadCount.delete(feed.id);
+			setFeeds((prev) => {
+				const updated = prev.filter((f) => f.podcast.feedUrl !== feedUrl);
+				saveFeeds(updated);
+				return updated;
+			});
+		}
+	};
+
 	/** Update a feed */
 	const updateFeed = (feedId: string, updates: Partial<Feed>) => {
 		setFeeds((prev) => {
@@ -470,7 +498,9 @@ export function createFeedStore() {
 		setFilter,
 		setSelectedFeedId,
 		addFeed,
+		hasFeedByUrl,
 		removeFeed,
+		removeFeedByUrl,
 		updateFeed,
 		togglePinned,
 		refreshFeed,