Caterwauler

Live, multi-user karaoke songbook synced to Supabase.

This is the one and only app in active use — an earlier separate project (karaoke-app, a React rebuild on Vercel) was retired in favor of adding multi-user support directly to this app instead. Nothing else reads or writes this database going forward.

Structure

• index.html — markup and sheet layouts, including the sign-in gate
• styles.css — all styling
• app.js — app logic (auth, Supabase calls, rendering, vocal range math, recommendations, venue search)

Auth & data model

• Sign-in is magic link / OTP via Supabase Auth (no passwords) — see the authClient/onSignedIn flow at the top and bottom of app.js.
• songs and performances are scoped per-user via a user_id column and RLS policies (auth.uid() = user_id). Each signed-in user only ever sees their own songbook.
• profiles holds each user's vocal range: either range_mode = 'auto' (computed from the widest span among Solid-status songs with a known range) or 'manual' (typed in directly under Settings > Vocal Range).
• karafun_catalog (~84k songs) and song_ranges (shared vocal-range lookup, matched by normalized title+artist) are shared reference data, open to all signed-in users — not scoped per-user.
• songs.in_karafun (drives the "K" badge) is computed server-side by a before insert or update of title, artist trigger (songs_karafun_check → check_karafun_match), not checked client-side on load. After importing a refreshed KaraFun catalog CSV into karafun_catalog, run select public.refresh_all_karafun_matches(); to re-check every existing song — otherwise only newly added/edited songs pick up the new catalog data.
• setlists (name, optional gig date/venue/notes) and setlist_songs (join table with a position column for ordering) let a user build named, ordered song lists — either a reusable collection or one tied to a specific gig date. Both are scoped per-user via user_id and RLS, same pattern as songs/performances. Songs are added manually — either from a setlist's own "Add songs" search, or via a "+ Setlist" button on every song card in the main songbook list, which opens a picker to add that song straight to an existing setlist or a newly-named one (openAddToSetlist in app.js). Reordering re-numbers every row's position rather than patching just the two swapped rows, since positions can develop gaps after a song is removed.
• The Setlists tab (renderSetlistsList) splits into Upcoming (gig_date today-or-later, ascending; undated/reusable lists included, sorted last within the group) and Past (visually de-emphasized) via splitSetlistsByGigDate. Tapping a setlist opens Perform mode (openPerformView/renderPerformSongs) by default — a read-mostly view with a "Mark as sung" button per song (logs to performances, same shape as manual logging, dated today and defaulting to the setlist's venue) and no reorder/remove controls. The full planning sheet (openSetlistDetail — reorder, add/remove songs, gig date/venue/notes) is reachable via an Edit button on each row or inside Perform itself. Both views show a readiness banner (computeReadinessBannerHtml) when the gig is within 14 days and any song in it isn't yet Solid.
• Uses Supabase's newer publishable key (sb_publishable_...), not the legacy anon key.

Recommendations

The Recs tab (loadRecommendations in app.js — a view-switcher tab, not a sheet, since promoting it out from behind a header icon in build 71) searches karafun_catalog for songs by artists related to your Solid songs, gates every candidate on vocal range via song_ranges, and groups results into in-range / would-need-a-key-change / range-unconfirmed. Seed artists come from three tiers (buildSeedArtists in app.js), each with a smaller per-artist cap the further it gets from a proven Solid artist:

• Solid — artists you're already Solid on (cap 10 songs/artist).
• Genre — other artists already in your songbook (any status but Retired) sharing a genre tag with a Solid song (cap 4).
• Similar — real similar-artist data from Last.fm's artist.getsimilar API, for your top 8 Solid artists by song count (cap 4). Only runs if a free Last.fm API key is saved under Settings > Recommendations; the key lives in localStorage only, not Supabase.

Tests

tests.js unit-tests the pure logic in app.js (note/semitone math, range fit scoring, transpose suggestions, string normalization) by extracting those functions straight from the shipped source — not a hand-copied duplicate, so it can't silently drift out of sync. It does not test DOM/UI behavior, Supabase calls, or auth.

Run with:

node tests.js

Deploying

tests.js must pass before every push. Also bump the cache-busting ?v= query param on app.js and styles.css in index.html, and match it to BUILD_VERSION at the top of app.js — GitHub Pages/browsers (especially iOS home-screen icons) can otherwise keep serving a stale cached bundle after a deploy, silently undoing whatever just shipped.

Known open items

• App icons for public/PWA install are still placeholder/empty.
• Some songs in the songbook don't have a matching karafun_catalog entry due to text normalization gaps (e.g. "and" vs "&" in artist names) — catalog-dependent features (autocomplete, range auto-fill) just won't fire for those specific songs.

To do

• Friending system — functionally complete as of build 59. friendships table (requester_id, addressee_id, status: pending/accepted/declined, unique index on the unordered pair so requests can't be duplicated or crossed). All writes go through security-definer RPCs, not direct REST — the table itself has only a SELECT policy, so a raw REST call can't mutate it: send_friend_request(username) (creates a request, or auto-accepts if the other person already requested you, or revives a declined one), accept_friend_request / decline_friend_request / remove_friendship (also doubles as cancel-outgoing and unfriend), list_friendships() (joined view with the other person's username, since profiles RLS wouldn't otherwise let you read it).
  • UI lives in its own top-level sheet (friendsSheet, opened via the new Friends icon in the marquee), not Settings — friending is a mainstream social feature that'll keep growing, not app config, and burying it in Settings was the wrong call from when it was first built (build 58). Settings keeps just the Username field.
  • Badge on the Friends icon shows the pending-incoming-request count via pending_friend_request_count(), refreshed on sign-in and after any action that changes it. It's a request counter, not a push notification — still requires opening the app to see it.
  • First real use of the graph: friends can view each other's setlists (read-only) via get_friend_setlists(friend_id), gated on an accepted friendship existing. Setlists were picked over the full songbook as the first share surface — a setlist is inherently "here's what I'm bringing to a gig," already meant to be seen, versus the songbook's more private in-progress status tracking.
  • Not built: comparing songbooks, seeing a friend's vocal range, any other cross-user feature — setlists were the one deliberate first step, not a general "friends can see everything" opening.
• Create test users and support admin impersonation of them — done (build 53): dedicated Users screen in Admin (usersSheet) — full roster with last-active time via admin-list-users, expandable read-only details via admin-view-as, and real full impersonation via admin-impersonate. Impersonation works by minting a genuine session for the target user through Supabase's own generateLink + verifyOtp (no service-role key ever reaches the client), so once switched, everything the admin sees is governed by the target's own RLS — not a bypass. The admin's own session is stashed in sessionStorage before switching so the "Exit" banner can restore it.