diff --git a/README.md b/README.md
index 793217c..efd259a 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # vod frog
 
-A whimsical, frog-themed video player for VODs from [stream.place](https://stream.place), a decentralized video streaming service built on the AT Protocol. Inspired by the playful, hand-crafted feel of late 90s / early 2000s web design.
+vod frog, frog with the vods, i take the frogs on the vod. i vod on the frogs.
+
+svelte app, fair amount of claude code work was done here but i've looked through it and most of it seems reasonable. please submit pull requests for anything sus!! 
 
 ## Running
 
@@ -56,7 +58,7 @@ src/
 
 ## Design
 
-Videos are fetched from across the AT Protocol network via the [UFOs API](https://ufos-api.microcosm.blue), which indexes all `place.stream.video` records. Playback uses HLS via [hls.js](https://github.com/video-dev/hls.js/).
+Videos are fetched from across the AT Protocol network via the [UFOs API](https://ufos-api.microcosm.blue) (TODO: REPLACE THIS WITH A QUICKSLICE INSTANCE, UFOS DOES NOT ACTUALLY INDEX 100% OF THE DATA), which indexes all `place.stream.video` records. Playback uses HLS via [hls.js](https://github.com/video-dev/hls.js/).
 
 Each video card gets a unique wavy border generated from layered sine waves, seeded by the record's key. Cards are offset with random rotation (±5°) and position jitter (±30px) for an organic, hand-placed feel. The wavy borders use a CSS `clip-path: polygon()` for content masking and an SVG path for the visible stroke, both derived from the same control points.
 
diff --git a/src/lib/VideoCard.svelte b/src/lib/VideoCard.svelte
index c015a99..fc7e106 100644
--- a/src/lib/VideoCard.svelte
+++ b/src/lib/VideoCard.svelte
@@ -1,3 +1,15 @@
+<!--
+	VideoCard: A single video entry in the grid.
+
+	Features:
+	- Wavy green border (outer) with wavy blue border (inner thumbnail)
+	- Thumbnail loaded from the creator's PDS via livestream record
+	- Hover scrub preview: creates a hidden <video> element, seeks it on mousemove,
+	  and draws frames to a canvas overlaid on the thumbnail
+	- Hopping frog sprite follows the scrub position
+	- Creator name links to their profile page
+	- Card position is jittered (rotation + translate) seeded by the creator DID
+-->
 <script lang="ts">
 	import { onMount, onDestroy } from 'svelte';
 	import Hls from 'hls.js';
@@ -23,7 +35,8 @@
 	const offsets = getCardOffsets(video.value.creator);
 	const cardStyle = `transform: rotate(${offsets.rotation}deg) translate(${offsets.translateX}px, ${offsets.translateY}px);`;
 
-	// Scrub state
+	// Scrub preview state — an offscreen video element is created on hover
+	// and seeked as the user moves their mouse across the thumbnail
 	let thumbEl: HTMLDivElement | undefined = $state();
 	let canvasEl: HTMLCanvasElement | undefined = $state();
 	let scrubbing = $state(false);
@@ -32,11 +45,11 @@
 	let scrubLoading = $state(false);
 	let hasFrame = $state(false);
 
-	let scrubVideo: HTMLVideoElement | null = null;
-	let hls: Hls | null = null;
-	let videoDuration = 0;
-	let seeking = false;
-	let pendingSeek: number | null = null;
+	let scrubVideo: HTMLVideoElement | null = null;  // Hidden video element for scrub preview
+	let hls: Hls | null = null;                     // hls.js instance for the scrub video
+	let videoDuration = 0;                           // Total duration in seconds
+	let seeking = false;                             // True while a seek is in progress
+	let pendingSeek: number | null = null;           // Queued seek time if we're already seeking
 
 	onMount(() => {
 		resolveHandle(video.value.creator).then((h) => (creatorHandle = h));
@@ -45,6 +58,7 @@
 
 	onDestroy(destroyScrub);
 
+	/** Create a hidden video element and attach hls.js to enable scrub preview */
 	function initScrub() {
 		if (scrubVideo) return;
 		scrubLoading = true;
@@ -98,6 +112,7 @@
 		if (seeking) pendingSeek = targetTime; else doSeek(targetTime);
 	}
 
+	/** Draw the current scrub video frame onto the visible canvas */
 	function drawFrame() {
 		if (!scrubVideo || !canvasEl) return;
 		const vw = scrubVideo.videoWidth, vh = scrubVideo.videoHeight;
diff --git a/src/lib/VideoPlayer.svelte b/src/lib/VideoPlayer.svelte
index 10e718e..48042cd 100644
--- a/src/lib/VideoPlayer.svelte
+++ b/src/lib/VideoPlayer.svelte
@@ -3,6 +3,7 @@
     import Hls from "hls.js";
     import WavyBorder from "./WavyBorder.svelte";
 
+    // HLS video source URL (m3u8 playlist)
     let { src }: { src: string } = $props();
 
     let videoEl: HTMLVideoElement | undefined = $state();
@@ -14,7 +15,8 @@
     let currentTime = $state(0);
     let duration = $state(0);
 
-    // Frog scrub state
+    // Frog scrub bar — the frog's position along the bar represents playback progress.
+    // Users can click the bar or grab the frog to seek.
     let scrubBarEl: HTMLDivElement | undefined = $state();
     let isScrubbing = $state(false);
     let scrubProgress = $state(0);
@@ -93,8 +95,9 @@
             );
     });
 
-    let lastHopProgress = 0;
+    let lastHopProgress = 0; // Track progress to trigger frog hops at intervals
 
+    /** Sync scrub position with playback, and animate the frog hopping */
     function onTimeUpdate() {
         if (!videoEl || isScrubbing) return;
         currentTime = videoEl.currentTime;
@@ -139,7 +142,7 @@
         isFullscreen = !!document.fullscreenElement;
     }
 
-    // Scrub bar — clicking the track or dragging the frog
+    /** Calculate seek position from a mouse event on the scrub bar */
     function scrubFromEvent(e: MouseEvent) {
         if (!scrubBarEl) return;
         const rect = scrubBarEl.getBoundingClientRect();
@@ -165,8 +168,9 @@
         }
     }
 
-    let wasPlayingBeforeScrub = false;
+    let wasPlayingBeforeScrub = false; // Resume playback after scrub if it was playing
 
+    /** Start scrubbing — pause video to prevent buffering issues (especially Firefox) */
     function onScrubDown(e: MouseEvent) {
         e.preventDefault();
         isScrubbing = true;
@@ -177,6 +181,7 @@
         window.addEventListener("mouseup", onScrubUp);
     }
 
+    /** Start scrubbing by grabbing the frog sprite directly */
     function onFrogDown(e: MouseEvent) {
         e.preventDefault();
         e.stopPropagation();
@@ -213,6 +218,7 @@
         return () => window.removeEventListener('keydown', onKeyDown);
     });
 
+    /** Show controls on mouse activity, auto-hide after 2.5s of inactivity during playback */
     function onMouseActivity() {
         showControls = true;
         if (hideTimeout) clearTimeout(hideTimeout);
diff --git a/src/lib/WavyBorder.svelte b/src/lib/WavyBorder.svelte
index afa4dc2..28a0f51 100644
--- a/src/lib/WavyBorder.svelte
+++ b/src/lib/WavyBorder.svelte
@@ -1,3 +1,11 @@
+<!--
+	WavyBorder: A procedurally generated wobbly rectangular border.
+
+	The shape is built from layered sine waves along each edge, seeded by a string
+	so every instance is unique but deterministic. The content is clipped to the
+	wavy shape using a CSS polygon, while the visible outline is rendered as an
+	SVG path on top. Both are derived from the same control points to stay aligned.
+-->
 <script lang="ts">
 	import { seededRandom } from './theme';
 
@@ -17,10 +25,15 @@
 	// Convert the points to a CSS polygon for clipping
 	const clipPolygon = `polygon(${pts.map(([x, y]) => `${x.toFixed(2)}% ${y.toFixed(2)}%`).join(', ')})`;
 
+	/**
+	 * Generate the wavy shape for this border.
+	 * Returns both the SVG bezier path (for the stroke) and densely sampled
+	 * polygon points (for the CSS clip-path). All coordinates are in 0-100 space.
+	 */
 	function generateWavyShape(s: string): { pts: [number, number][]; svgPath: string } {
-		const margin = 1;
-		const amp = 2.5;
-		const segs = 16;
+		const margin = 1;   // % inset from the element edges
+		const amp = 2.5;     // % max wobble amplitude
+		const segs = 16;     // control points per edge
 
 		// Edges 0=top, 1=right, 2=bottom, 3=left
 		// Vertical edges (1,3) get lower frequency since they're often shorter in wide boxes
@@ -36,6 +49,7 @@
 			};
 		});
 
+		/** Compute the perpendicular wobble offset at position t along an edge */
 		function wobble(edgeIdx: number, t: number): number {
 			const p = edgeParams[edgeIdx];
 			const w1 = Math.sin(t * p.freq1 * Math.PI * 2 + p.phase1) * amp * 0.7;
diff --git a/src/lib/WavyCircle.svelte b/src/lib/WavyCircle.svelte
index 2812a89..b09611a 100644
--- a/src/lib/WavyCircle.svelte
+++ b/src/lib/WavyCircle.svelte
@@ -1,3 +1,7 @@
+<!--
+	WavyCircle: A procedurally generated wobbly circular border for avatars.
+	Uses radial sine waves to create an organic blob shape, seeded by a string.
+-->
 <script lang="ts">
 	import { seededRandom } from './theme';
 
diff --git a/src/lib/api.ts b/src/lib/api.ts
index 428c92e..f80224d 100644
--- a/src/lib/api.ts
+++ b/src/lib/api.ts
@@ -1,8 +1,18 @@
+/**
+ * AT Protocol API client for fetching videos, resolving handles/profiles,
+ * and looking up thumbnails across the network.
+ */
+
+/** The AT Protocol lexicon collection for stream.place videos */
 export const COLLECTION = 'place.stream.video';
+/** HLS playlist endpoint — takes an at:// URI and returns an m3u8 manifest */
 export const PLAYBACK_BASE =
 	'https://vod-beta.stream.place/xrpc/place.stream.playback.getVideoPlaylist';
+
+/** UFOs API — indexes all AT Protocol records across the network */
 export const UFOS_API = 'https://ufos-api.microcosm.blue';
 
+/** A video record in our normalized format, with an at:// URI */
 export interface VideoRecord {
 	uri: string;
 	cid: string;
@@ -25,6 +35,7 @@ export interface VideoRecord {
 	};
 }
 
+/** Raw record shape from the UFOs API */
 interface UfosRecord {
 	did: string;
 	collection: string;
@@ -49,8 +60,10 @@ export interface ListRecordsResponse {
 	cursor?: string;
 }
 
+/** In-memory cache — the UFOs API returns all records at once, so we fetch once and paginate client-side */
 let allVideosCache: VideoRecord[] | null = null;
 
+/** Fetch all place.stream.video records from across the AT Protocol network */
 export async function fetchAllVideos(): Promise<VideoRecord[]> {
 	if (allVideosCache) return allVideosCache;
 
@@ -71,6 +84,7 @@ export async function fetchAllVideos(): Promise<VideoRecord[]> {
 	return allVideosCache;
 }
 
+/** Return a page of videos from the cached full list */
 export async function listVideos(page = 0, pageSize = 9): Promise<{ records: VideoRecord[]; hasMore: boolean }> {
 	const all = await fetchAllVideos();
 	const start = page * pageSize;
@@ -78,10 +92,12 @@ export async function listVideos(page = 0, pageSize = 9): Promise<{ records: Vid
 	return { records, hasMore: start + pageSize < all.length };
 }
 
+/** Build an HLS playlist URL from an at:// video URI */
 export function getPlaylistUrl(uri: string): string {
 	return `${PLAYBACK_BASE}?uri=${encodeURIComponent(uri)}`;
 }
 
+/** Format nanosecond duration to human-readable "H:MM:SS" or "M:SS" */
 export function formatDuration(nanos: number): string {
 	const totalSeconds = Math.floor(nanos / 1_000_000_000);
 	const hours = Math.floor(totalSeconds / 3600);
@@ -120,6 +136,7 @@ export interface BskyProfile {
 	createdAt?: string;
 }
 
+/** Fetch a Bluesky profile by handle or DID via the public API */
 export async function getProfile(actor: string): Promise<BskyProfile> {
 	const params = new URLSearchParams({ actor });
 	const res = await fetch(`${BSKY_PUBLIC_API}/xrpc/app.bsky.actor.getProfile?${params}`);
@@ -131,6 +148,7 @@ export async function getProfile(actor: string): Promise<BskyProfile> {
 
 const handleCache = new Map<string, string>();
 
+/** Resolve a DID to a human-readable @handle via the PLC directory */
 export async function resolveHandle(did: string): Promise<string> {
 	if (handleCache.has(did)) return handleCache.get(did)!;
 	try {
@@ -150,6 +168,7 @@ export async function resolveHandle(did: string): Promise<string> {
 
 const pdsCache = new Map<string, string>();
 
+/** Resolve a DID to its PDS (Personal Data Server) endpoint URL */
 export async function resolvePds(did: string): Promise<string | null> {
 	if (pdsCache.has(did)) return pdsCache.get(did)!;
 	try {
diff --git a/src/lib/theme.ts b/src/lib/theme.ts
index 8ad32d3..24588a2 100644
--- a/src/lib/theme.ts
+++ b/src/lib/theme.ts
@@ -1,14 +1,17 @@
-// VodFrog color scheme and theme constants
+/**
+ * VodFrog theme: color scheme, seeded randomness, and card layout utilities.
+ */
 
+/** Brand colors from the design spec */
 export const colors = {
-	green: '#39FF44',
-	blue: '#3992FF',
-	orange: '#FFA639',
-	pink: '#FF3992',
-	lightPink: '#FFDEED',
-	darkBlue: '#0A182B',
-
-	// Derived
+	green: '#39FF44',       // Main vibrant green
+	blue: '#3992FF',        // Water blue
+	orange: '#FFA639',      // Orange accent
+	pink: '#FF3992',        // Pink accent
+	lightPink: '#FFDEED',   // Light pink for dark regions
+	darkBlue: '#0A182B',    // Near-black blue for text/outlines
+
+	// Derived shades
 	greenDark: '#1A8C22',
 	greenMuted: '#2BBF33',
 	blueDark: '#1E4E8C',
@@ -16,8 +19,9 @@ export const colors = {
 } as const;
 
 /**
- * Generate a deterministic pseudo-random number from a string seed.
- * Uses a simple hash function to produce values in [0, 1).
+ * Deterministic pseudo-random number from a string seed.
+ * Same seed + index always produces the same value in [0, 1).
+ * Used to give each card/border a unique but consistent appearance.
  */
 export function seededRandom(seed: string, index = 0): number {
 	let hash = 0;
@@ -26,13 +30,12 @@ export function seededRandom(seed: string, index = 0): number {
 		const char = str.charCodeAt(i);
 		hash = ((hash << 5) - hash + char) | 0;
 	}
-	// Normalize to [0, 1)
 	return (((hash % 65536) + 65536) % 65536) / 65536;
 }
 
 /**
- * Generate organic offsets for a card based on its URI/DID.
- * Returns rotation (deg), translateX (px), translateY (px).
+ * Generate organic layout offsets for a video card, seeded by the creator's DID.
+ * Creates a hand-placed, off-grid feeling in the card grid.
  */
 export function getCardOffsets(seed: string): {
 	rotation: number;
@@ -44,36 +47,8 @@ export function getCardOffsets(seed: string): {
 	const r3 = seededRandom(seed, 2);
 
 	return {
-		rotation: (r1 - 0.5) * 10, // -5 to +5 degrees
-		translateX: (r2 - 0.5) * 60, // -30 to +30 px
-		translateY: (r3 - 0.5) * 60, // -30 to +30 px
+		rotation: (r1 - 0.5) * 10,  // ±5 degrees
+		translateX: (r2 - 0.5) * 60, // ±30px horizontal jitter
+		translateY: (r3 - 0.5) * 60, // ±30px vertical jitter
 	};
 }
-
-/**
- * Generate an SVG filter for wavy/turbulent borders seeded by a string.
- * Returns the filter ID and the full SVG filter definition.
- */
-export function generateWavyFilterId(seed: string): string {
-	// Use the seed to create a unique filter ID
-	let hash = 0;
-	for (let i = 0; i < seed.length; i++) {
-		hash = ((hash << 5) - hash + seed.charCodeAt(i)) | 0;
-	}
-	return `wavy-${((hash >>> 0) % 999999).toString(36)}`;
-}
-
-export function generateWavyFilterSvg(seed: string): { filterId: string; svgDefs: string } {
-	const filterId = generateWavyFilterId(seed);
-	const r1 = seededRandom(seed, 10);
-	const r2 = seededRandom(seed, 11);
-	const baseFreq = 0.015 + r1 * 0.015; // 0.015 - 0.03
-	const seed2 = Math.floor(r2 * 100);
-
-	const svgDefs = `<filter id="${filterId}" x="-5%" y="-5%" width="110%" height="110%">
-		<feTurbulence type="turbulence" baseFrequency="${baseFreq.toFixed(4)}" numOctaves="3" seed="${seed2}" result="turbulence"/>
-		<feDisplacementMap in="SourceGraphic" in2="turbulence" scale="12" xChannelSelector="R" yChannelSelector="G"/>
-	</filter>`;
-
-	return { filterId, svgDefs };
-}