Spaces:

build-small-hackathon
/

roulette

Running

App Files Files Community

ratandeep commited on 22 days ago

Commit

653b61d

1 Parent(s): b73da1b

Deploy Build Small Roulette — static space serendipity engine for the org

Browse files

Files changed (12) hide show

README.md +20 -5
index.html +48 -17
js/api.js +69 -0
js/app.js +172 -0
js/bag.js +79 -0
js/config.js +23 -0
js/embed.js +105 -0
js/oauth.js +65 -0
js/store.js +63 -0
js/tracks.js +13 -0
js/ui.js +116 -0
style.css +172 -18

README.md CHANGED Viewed

@@ -1,10 +1,25 @@
 ---
-title: Roulette
-emoji: 🦀
-colorFrom: pink
-colorTo: indigo
 sdk: static
 pinned: false
 ---
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

 ---
+title: Build Small Roulette
+emoji: 🧭
+colorFrom: yellow
+colorTo: green
 sdk: static
+app_file: index.html
 pinned: false
+hf_oauth: true
+hf_oauth_expiration_minutes: 480
+license: mit
 ---
+# Build Small Roulette 🧭
+A serendipity engine for the **Build Small Hackathon**. Spins through every public Space in the
+[`build-small-hackathon`](https://huggingface.co/build-small-hackathon) org one full-screen card at a
+time — 👍 like, 💾 save, ⏭ shuffle. A shuffle bag guarantees you see every project before any repeats.
+- **👍 Like** writes a real Hugging Face like when you're signed in (falls back to a local like otherwise).
+- **💾 Save** bookmarks projects locally.
+- **⏭ Next** / `Space` / `→` shuffles onward. `←` Prev, `L` like, `S` save, `O` open on HF, `?` shortcuts.
+Static Space — no backend. The project list comes from the public Hub API; saves and local-likes live
+in your browser. OAuth requests only `openid profile` (no repo access).

index.html CHANGED Viewed

@@ -1,19 +1,50 @@
 <!doctype html>
-<html>
-	<head>
-		<meta charset="utf-8" />
-		<meta name="viewport" content="width=device-width" />
-		<title>My static Space</title>
-		<link rel="stylesheet" href="style.css" />
-	</head>
-	<body>
-		<div class="card">
-			<h1>Welcome to your static Space!</h1>
-			<p>You can modify this app directly by editing <i>index.html</i> in the Files and versions tab.</p>
-			<p>
-				Also don't forget to check the
-				<a href="https://huggingface.co/docs/hub/spaces" target="_blank">Spaces documentation</a>.
-			</p>
-		</div>
-	</body>
 </html>

 <!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover" />
+  <title>Build Small Roulette</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,400;9..144,600;9..144,700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="style.css" />
+  <script async src="https://unpkg.com/es-module-shims@1.7.0/dist/es-module-shims.js"></script>
+  <script type="importmap">
+    { "imports": { "@huggingface/hub": "https://cdn.jsdelivr.net/npm/@huggingface/hub@2.11.2/+esm" } }
+  </script>
+</head>
+<body>
+  <header id="topbar" class="topbar" hidden>
+    <div class="tb-left">
+      <span id="card-emoji" class="emoji"></span>
+      <span id="card-title" class="title"></span>
+      <span id="card-track" class="track-badge" hidden></span>
+      <a id="hf-likes" class="hf-likes" title="Likes on Hugging Face" target="_blank" rel="noopener"></a>
+    </div>
+    <div class="tb-right">
+      <button id="btn-like" class="btn btn-icon" title="Like (L)">👍</button>
+      <button id="btn-save" class="btn btn-icon" title="Save (S)">💾</button>
+      <button id="btn-next" class="btn btn-next" title="Next (Space/→)"><span class="compass">🧭</span> Next</button>
+    </div>
+  </header>
+  <main id="stage" class="stage">
+    <div id="loader" class="loader">Finding a trail…</div>
+  </main>
+  <footer id="bottombar" class="bottombar" hidden>
+    <button id="btn-prev" class="btn btn-ghost" title="Prev (←)">⏮ Prev</button>
+    <a id="btn-open" class="btn btn-ghost" target="_blank" rel="noopener" title="Open on HF (O)">↗ Open on HF</a>
+    <button id="btn-saved" class="btn btn-ghost" title="Saved">☰ Saved (0)</button>
+    <button id="btn-track" class="btn btn-ghost" title="Filter by track">⤮ All</button>
+    <span id="progress" class="progress"></span>
+    <span id="auth" class="auth"></span>
+  </footer>
+  <div id="drawer" class="drawer" hidden></div>
+  <div id="overlay" class="overlay" hidden></div>
+  <div id="toast" class="toast" hidden></div>
+  <script type="module" src="js/app.js"></script>
+</body>
 </html>

js/api.js ADDED Viewed

	@@ -0,0 +1,69 @@

+import { CONFIG } from "./config.js";
+import { normalizeTrack } from "./tracks.js";
+const DEFAULT_EMOJI = "🛖";
+export function parseLinkHeader(header) {
+  if (!header) return null;
+  for (const part of header.split(",")) {
+    const m = part.match(/<([^>]+)>\s*;\s*rel="?next"?/);
+    if (m) return m[1];
+  }
+  return null;
+}
+export function filterEligible(spaces, denylist = CONFIG.denylist) {
+  const deny = new Set(denylist);
+  return spaces.filter((s) => !deny.has(s.id) && s.private !== true);
+}
+export function toViewModel(s) {
+  const card = s.cardData || {};
+  const name = s.id.includes("/") ? s.id.split("/").slice(1).join("/") : s.id;
+  const subdomain = s.subdomain || s.id.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  return {
+    id: s.id,
+    name,
+    title: card.title || name,
+    emoji: card.emoji || DEFAULT_EMOJI,
+    shortDescription: card.short_description || "",
+    likes: typeof s.likes === "number" ? s.likes : 0,
+    sdk: s.sdk || "",
+    track: normalizeTrack(card.tags),
+    colorFrom: card.colorFrom || "gray",
+    colorTo: card.colorTo || "gray",
+    embedUrl: `https://${subdomain}.hf.space`,
+    hfUrl: `${CONFIG.apiBase}/spaces/${s.id}`,
+  };
+}
+// ---- network (live-verified) ----
+export async function fetchAllSpaces() {
+  let url = `${CONFIG.apiBase}/api/spaces?author=${CONFIG.org}&full=true&limit=${CONFIG.apiLimit}`;
+  const all = [];
+  for (let guard = 0; url && guard < 20; guard++) {
+    const res = await fetch(url);
+    if (!res.ok) throw new Error(`list fetch ${res.status}`);
+    const page = await res.json();
+    all.push(...page);
+    url = parseLinkHeader(res.headers.get("Link"));
+  }
+  return filterEligible(all).map(toViewModel);
+}
+export async function fetchAllSpacesWithRetry() {
+  try { return await fetchAllSpaces(); }
+  catch { return await fetchAllSpaces(); } // retry once; second failure throws to caller
+}
+export async function fetchDetail(id) {
+  const res = await fetch(`${CONFIG.apiBase}/api/spaces/${id}`);
+  if (!res.ok) throw new Error(`detail ${res.status}`);
+  const d = await res.json();
+  const stage = d?.runtime?.stage || null;
+  const domainsReady = Array.isArray(d?.runtime?.domains)
+    ? d.runtime.domains.some((x) => x.stage === "READY")
+    : false;
+  return { stage, domainsReady, gated: !!d.gated, disabled: !!d.disabled, likes: d.likes };
+}

js/app.js ADDED Viewed

	@@ -0,0 +1,172 @@

+import { CONFIG } from "./config.js";
+import { Store } from "./store.js";
+import { Bag } from "./bag.js";
+import { TRACKS } from "./tracks.js";
+import { fetchAllSpacesWithRetry } from "./api.js";
+import { mountCard } from "./embed.js";
+import * as ui from "./ui.js";
+import { initOAuth, signIn, signOut, likeOnHf } from "./oauth.js";
+const $ = (id) => document.getElementById(id);
+const state = {
+  store: new Store({ key: CONFIG.storageKey }),
+  all: [],            // all view models
+  byId: new Map(),
+  bag: null,
+  filterTrack: null,  // null | "Backyard" | "Wood"
+  current: null,      // current vm
+  controller: null,   // mountCard controller
+  oauth: null,
+};
+function idsForTrack(track) {
+  const list = track ? state.all.filter((v) => v.track === track) : state.all;
+  return list.map((v) => v.id);
+}
+function eligibleIds() { return idsForTrack(state.filterTrack); }
+function prefetchNext() {
+  if (!CONFIG.prefetchNext || !state.bag) return;
+  const peekId = state.bag.bag[state.bag.cursor];
+  const vm = peekId && state.byId.get(peekId);
+  if (!vm) return;
+  let link = document.getElementById("prefetch-link");
+  if (!link) {
+    link = document.createElement("link");
+    link.id = "prefetch-link";
+    link.rel = "preconnect";
+    document.head.append(link);
+  }
+  link.href = vm.embedUrl;
+}
+function show(vm) {
+  if (!vm) return;
+  state.controller?.destroy();
+  state.current = vm;
+  state.store.markSeen(vm.id);
+  ui.renderCard(vm, state.store);
+  ui.setProgress(state.bag.progress());
+  state.controller = mountCard($("stage"), vm, { onSkip: next });
+  if (CONFIG.resumeRound) state.store.saveRound({ ...state.bag.serialize(), track: state.filterTrack });
+  prefetchNext();
+}
+function next() { show(state.byId.get(state.bag.next())); }
+function prev() { const id = state.bag.prev(); if (id) show(state.byId.get(id)); }
+function cycleTrack() {
+  const order = [null, ...TRACKS];
+  const nextTrack = order[(order.indexOf(state.filterTrack) + 1) % order.length];
+  const ids = idsForTrack(nextTrack);
+  if (!ids.length) { ui.toast(`No spaces in ${nextTrack}`); return; }
+  state.filterTrack = nextTrack;
+  ui.setTrackFilterLabel(state.filterTrack);
+  state.bag.setIds(ids);
+  next();
+}
+function wireKeys() {
+  document.addEventListener("keydown", (e) => {
+    const tag = e.target.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA") return;
+    switch (e.key) {
+      case " ": case "ArrowRight": e.preventDefault(); next(); break;
+      case "ArrowLeft": prev(); break;
+      case "l": case "L": $("btn-like").click(); break;
+      case "s": case "S": $("btn-save").click(); break;
+      case "o": case "O": if (state.current) window.open(state.current.hfUrl, "_blank"); break;
+      case "?": ui.showShortcuts(); break;
+    }
+  });
+}
+function wireButtons() {
+  $("btn-next").onclick = next;
+  $("btn-prev").onclick = prev;
+  $("btn-track").onclick = cycleTrack;
+  ui.setTrackFilterLabel(null);
+  $("btn-save").onclick = () => {
+    if (!state.current) return;
+    const on = state.store.toggleSaved(state.current.id);
+    ui.setSaveState(on);
+    ui.setSavedCount(state.store.savedIds().length);
+    ui.toast(on ? "Saved 💾" : "Removed from saved");
+  };
+  $("btn-saved").onclick = () => {
+    const vms = state.store.savedIds().map((id) => state.byId.get(id)).filter(Boolean);
+    ui.openDrawer(vms, {
+      onOpenHere: (id) => { $("drawer").hidden = true; show(state.byId.get(id)); },
+      onUnsave: (id) => { state.store.toggleSaved(id); ui.setSavedCount(state.store.savedIds().length); },
+    });
+  };
+  ui.setSavedCount(state.store.savedIds().length);
+  $("btn-like").onclick = async () => {
+    const vm = state.current;
+    if (!vm) return;
+    const turningOn = !state.store.isLiked(vm.id);
+    ui.setLikeState(turningOn); // optimistic
+    const where = await likeOnHf(vm.id, turningOn, state.oauth?.accessToken);
+    if (where === "hf") {
+      state.store.setHfLiked(vm.id, turningOn);
+      vm.likes = Math.max(0, (vm.likes || 0) + (turningOn ? 1 : -1));
+      ui.setHfLikes(vm.likes);
+      ui.toast(turningOn ? "Liked on Hugging Face 💚" : "Unliked");
+    } else {
+      state.store.setLocalLiked(vm.id, turningOn);
+      ui.toast(state.oauth
+        ? "Couldn't like on HF — saved locally. Open on HF to like officially ↗"
+        : "Saved your like locally — sign in to like on HF ↗");
+    }
+  };
+}
+function renderAuth() {
+  ui.renderAuth(state.oauth?.userInfo, {
+    onSignIn: signIn,
+    onSignOut: () => { signOut(); state.oauth = null; renderAuth(); },
+  });
+}
+function showError(msg) {
+  $("stage").innerHTML = `<div class="fallback"><strong>${msg}</strong>
+    <div class="fallback-actions">
+      <a class="btn" target="_blank" rel="noopener" href="${CONFIG.apiBase}/${CONFIG.org}">Visit the org ↗</a>
+      <button class="btn btn-ghost" onclick="location.reload()">Retry</button>
+    </div></div>`;
+}
+async function boot() {
+  wireKeys();
+  wireButtons();
+  try {
+    state.all = await fetchAllSpacesWithRetry();
+  } catch {
+    showError("Couldn't reach the Hugging Face API. Check your connection and retry.");
+    return;
+  }
+  if (!state.all.length) { showError("No projects found on the trail yet."); return; }
+  state.byId = new Map(state.all.map((v) => [v.id, v]));
+  state.oauth = await initOAuth();
+  renderAuth();
+  const saved = CONFIG.resumeRound ? state.store.loadRound() : null;
+  state.filterTrack = saved?.track ?? null;
+  ui.setTrackFilterLabel(state.filterTrack);
+  const canResume = saved && saved.track === state.filterTrack;
+  state.bag = new Bag(eligibleIds(), { state: canResume ? saved : null });
+  next();
+  if (!localStorage.getItem("bsr:hinted")) {
+    ui.toast("Spot a project · 👍 like · 💾 save · 🧭 Next (or hit Space). Press ? for keys.", 6000);
+    localStorage.setItem("bsr:hinted", "1");
+  }
+}
+boot();

js/bag.js ADDED Viewed

	@@ -0,0 +1,79 @@

+export function shuffle(arr, rng = Math.random) {
+  const a = [...arr];
+  for (let i = a.length - 1; i > 0; i--) {
+    const j = Math.floor(rng() * (i + 1));
+    [a[i], a[j]] = [a[j], a[i]];
+  }
+  return a;
+}
+export class Bag {
+  constructor(ids, { rng = Math.random, state = null } = {}) {
+    this.rng = rng;
+    if (state && Array.isArray(state.bag) && state.bag.length) {
+      this.ids = [...ids];
+      this.bag = state.bag;
+      this.cursor = state.cursor ?? 0;
+      this.round = state.round ?? 1;
+      this.history = [];
+      this.histPos = -1;
+      this.lastShown = null;
+    } else {
+      this.setIds(ids);
+    }
+  }
+  setIds(ids) {
+    this.ids = [...ids];
+    this.bag = shuffle(this.ids, this.rng);
+    this.cursor = 0;
+    this.round = 1;
+    this.history = [];
+    this.histPos = -1;
+    this.lastShown = null;
+  }
+  _pop() {
+    if (this.cursor >= this.bag.length) {
+      // new round: reshuffle, avoid immediate repeat of lastShown
+      this.round += 1;
+      this.cursor = 0;
+      if (this.ids.length > 1) {
+        do { this.bag = shuffle(this.ids, this.rng); }
+        while (this.bag[0] === this.lastShown);
+      } else {
+        this.bag = shuffle(this.ids, this.rng);
+      }
+    }
+    return this.bag[this.cursor++];
+  }
+  next() {
+    // if we stepped back, going next replays forward through history first
+    if (this.histPos < this.history.length - 1) {
+      this.histPos += 1;
+      this.lastShown = this.history[this.histPos];
+      return this.lastShown;
+    }
+    const id = this._pop();
+    this.history.push(id);
+    this.histPos = this.history.length - 1;
+    this.lastShown = id;
+    return id;
+  }
+  prev() {
+    if (this.histPos <= 0) return null;
+    this.histPos -= 1;
+    this.lastShown = this.history[this.histPos];
+    return this.lastShown;
+  }
+  progress() {
+    return { seen: Math.min(this.cursor, this.bag.length), total: this.bag.length, round: this.round };
+  }
+  serialize() {
+    return { bag: this.bag, cursor: this.cursor, round: this.round };
+  }
+}

js/config.js ADDED Viewed

	@@ -0,0 +1,23 @@

+export const CONFIG = {
+  org: "build-small-hackathon",
+  apiBase: "https://huggingface.co",
+  apiLimit: 1000,
+  denylist: ["build-small-hackathon/field-guide", "build-small-hackathon/HOME"],
+  skipUnhealthyStages: ["RUNTIME_ERROR", "BUILD_ERROR", "NO_APP_FILE", "PAUSED"],
+  loadTimeoutMs: 15000,
+  detailFetch: true,
+  autoAdvanceMs: 6000,
+  resumeRound: true,
+  prefetchNext: true,
+  hfHub: "https://cdn.jsdelivr.net/npm/@huggingface/hub@2.11.2/+esm",
+  oauthScopes: null,
+  storageKey: "bsr:v1",
+  oauthKey: "oauth",
+  trackMap: {
+    "track:backyard": "Backyard",
+    "track:backyard-ai": "Backyard",
+    "track:wood": "Wood",
+    "track:thousand-token-wood": "Wood",
+    "track:thousand_token_wood": "Wood",
+  },
+};

js/embed.js ADDED Viewed

	@@ -0,0 +1,105 @@

+import { CONFIG } from "./config.js";
+import { fetchDetail } from "./api.js";
+const ALLOW = "accelerometer; autoplay; camera; microphone; clipboard-read; clipboard-write; encrypted-media; geolocation; gyroscope; midi";
+const SANDBOX = "allow-scripts allow-same-origin allow-forms allow-popups allow-downloads allow-modals";
+function el(tag, cls, html) {
+  const e = document.createElement(tag);
+  if (cls) e.className = cls;
+  if (html != null) e.innerHTML = html;
+  return e;
+}
+export function buildIframe(vm) {
+  const f = document.createElement("iframe");
+  f.src = vm.embedUrl;
+  f.title = vm.title;
+  f.loading = "eager";
+  f.setAttribute("allow", ALLOW);
+  f.setAttribute("sandbox", SANDBOX);
+  f.referrerPolicy = "no-referrer-when-downgrade";
+  return f;
+}
+function fallbackCard(vm, message, { onSkip, countdownMs }) {
+  const box = el("div", "fallback");
+  box.append(el("div", "fallback-emoji", vm.emoji));
+  box.append(el("strong", null, vm.title));
+  box.append(el("p", null, message));
+  const open = el("a", "btn");
+  open.textContent = "↗ Open on HF";
+  open.href = vm.hfUrl; open.target = "_blank"; open.rel = "noopener";
+  const skip = el("button", "btn btn-ghost");
+  skip.textContent = "Skip →";
+  skip.onclick = onSkip;
+  const actions = el("div", "fallback-actions");
+  actions.append(open, skip);
+  box.append(actions);
+  let timer = null;
+  if (countdownMs && onSkip) timer = setTimeout(onSkip, countdownMs);
+  box._cleanup = () => timer && clearTimeout(timer);
+  return box;
+}
+/**
+ * Mounts a card into `stage`. Returns a controller with destroy().
+ * onState(state) receives "loading" | "waking" | "ready" | "broken".
+ */
+export function mountCard(stage, vm, { onState, onSkip } = {}) {
+  stage.innerHTML = "";
+  const loader = el("div", "loader", "Loading the demo…");
+  stage.append(loader);
+  onState?.("loading");
+  let destroyed = false;
+  let iframe = null;
+  let timeout = null;
+  let fb = null;
+  const showBroken = (msg) => {
+    if (destroyed) return;
+    iframe?.remove();
+    loader.remove();
+    fb?._cleanup?.();
+    fb = fallbackCard(vm, msg, { onSkip, countdownMs: CONFIG.autoAdvanceMs });
+    stage.append(fb);
+    onState?.("broken");
+  };
+  const embed = (waking) => {
+    if (destroyed) return;
+    if (waking) { loader.textContent = "Waking this Space up…"; onState?.("waking"); }
+    iframe = buildIframe(vm);
+    iframe.addEventListener("load", () => {
+      if (destroyed) return;
+      clearTimeout(timeout);
+      iframe.classList.add("ready"); // cross-fade in
+      loader.remove();
+      onState?.("ready");
+    });
+    stage.append(iframe);
+    timeout = setTimeout(
+      () => showBroken("This one didn't wake in time. Open it on Hugging Face, or skip ahead."),
+      CONFIG.loadTimeoutMs
+    );
+  };
+  if (CONFIG.detailFetch) {
+    fetchDetail(vm.id).then((d) => {
+      if (destroyed) return;
+      if (d.gated || d.disabled || CONFIG.skipUnhealthyStages.includes(d.stage)) {
+        showBroken("This one isn't running right now — catch it on Hugging Face.");
+      } else {
+        embed(d.stage === "SLEEPING");
+      }
+    }).catch(() => embed(false)); // detail failed — just try embedding
+  } else {
+    embed(false);
+  }
+  return {
+    el: () => iframe,
+    destroy() { destroyed = true; clearTimeout(timeout); fb?._cleanup?.(); iframe?.remove(); },
+  };
+}

js/oauth.js ADDED Viewed

	@@ -0,0 +1,65 @@

+import { CONFIG } from "./config.js";
+// Lazily load @huggingface/hub (resolved via the importmap in index.html).
+// Dynamic import means a CDN hiccup degrades liking only — never the whole app.
+let _hub = null;
+async function hub() {
+  if (!_hub) _hub = await import("@huggingface/hub");
+  return _hub;
+}
+function load(key) {
+  try { return JSON.parse(localStorage.getItem(key) || "null"); } catch { return null; }
+}
+function save(key, v) {
+  try { localStorage.setItem(key, JSON.stringify(v)); } catch { /* ignore */ }
+}
+/** Returns the active OAuthResult or null (handles the redirect-back leg on load). */
+export async function initOAuth() {
+  let oauth = null;
+  try {
+    const { oauthHandleRedirectIfPresent } = await hub();
+    oauth = await oauthHandleRedirectIfPresent();
+  } catch {
+    oauth = null;
+  }
+  oauth = oauth || load(CONFIG.oauthKey);
+  if (oauth) {
+    const exp = new Date(oauth.accessTokenExpiresAt).getTime();
+    if (Number.isFinite(exp) && exp < Date.now()) oauth = null; // expired
+  }
+  if (oauth) save(CONFIG.oauthKey, oauth);
+  return oauth;
+}
+export async function signIn() {
+  try {
+    const { oauthLoginUrl } = await hub();
+    const opts = CONFIG.oauthScopes ? { scopes: CONFIG.oauthScopes } : {};
+    window.location.href = await oauthLoginUrl(opts);
+  } catch {
+    /* OAuth lib unavailable — stay signed out; likes go local */
+  }
+}
+export function signOut() {
+  try { localStorage.removeItem(CONFIG.oauthKey); } catch { /* ignore */ }
+}
+/**
+ * Attempts a real HF like/unlike. Returns "hf" on success, "local" on any failure/offline.
+ * Caller persists the local fallback + UI.
+ */
+export async function likeOnHf(id, on, token) {
+  if (!token) return "local";
+  try {
+    const res = await fetch(`${CONFIG.apiBase}/api/spaces/${id}/like`, {
+      method: on ? "POST" : "DELETE",
+      headers: { Authorization: `Bearer ${token}` },
+    });
+    return res.ok ? "hf" : "local";
+  } catch {
+    return "local";
+  }
+}

js/store.js ADDED Viewed

	@@ -0,0 +1,63 @@

+const DEFAULTS = () => ({ liked: {}, hfLiked: {}, saved: {}, seen: [], round: null });
+export class Store {
+  constructor({ key = "bsr:v1", backend } = {}) {
+    this.key = key;
+    this.backend = backend || globalThis.localStorage;
+    this.data = this._read();
+  }
+  _read() {
+    try {
+      const raw = this.backend?.getItem(this.key);
+      if (!raw) return DEFAULTS();
+      return { ...DEFAULTS(), ...JSON.parse(raw) };
+    } catch {
+      return DEFAULTS();
+    }
+  }
+  _write() {
+    try {
+      this.backend?.setItem(this.key, JSON.stringify(this.data));
+    } catch {
+      /* storage full / blocked — ignore */
+    }
+  }
+  // saves
+  isSaved(id) { return !!this.data.saved[id]; }
+  toggleSaved(id) {
+    if (this.data.saved[id]) { delete this.data.saved[id]; this._write(); return false; }
+    this.data.saved[id] = Date.now(); this._write(); return true;
+  }
+  savedIds() {
+    return Object.keys(this.data.saved).sort((a, b) => this.data.saved[b] - this.data.saved[a]);
+  }
+  // local-like fallback
+  isLocalLiked(id) { return !!this.data.liked[id]; }
+  setLocalLiked(id, on) {
+    if (on) this.data.liked[id] = Date.now(); else delete this.data.liked[id];
+    this._write();
+  }
+  // confirmed real HF like (this session/device)
+  isHfLiked(id) { return !!this.data.hfLiked[id]; }
+  setHfLiked(id, on) {
+    if (on) this.data.hfLiked[id] = true; else delete this.data.hfLiked[id];
+    this._write();
+  }
+  // any like (real or local) — for button fill state
+  isLiked(id) { return this.isHfLiked(id) || this.isLocalLiked(id); }
+  // seen / progress
+  markSeen(id) {
+    if (!this.data.seen.includes(id)) { this.data.seen.push(id); this._write(); }
+  }
+  // resume round
+  saveRound(round) { this.data.round = round; this._write(); }
+  loadRound() { return this.data.round; }
+}

js/tracks.js ADDED Viewed

	@@ -0,0 +1,13 @@

+import { CONFIG } from "./config.js";
+export const TRACKS = ["Backyard", "Wood"];
+export function normalizeTrack(tags) {
+  if (!Array.isArray(tags)) return null;
+  for (const t of tags) {
+    if (typeof t !== "string") continue;
+    const hit = CONFIG.trackMap[t.toLowerCase()];
+    if (hit) return hit;
+  }
+  return null;
+}

js/ui.js ADDED Viewed

	@@ -0,0 +1,116 @@

+const $ = (id) => document.getElementById(id);
+export function renderCard(vm, store) {
+  $("topbar").hidden = false;
+  $("bottombar").hidden = false;
+  $("card-emoji").textContent = vm.emoji;
+  $("card-title").textContent = vm.title;
+  const track = $("card-track");
+  track.hidden = !vm.track;
+  track.textContent = vm.track || "";
+  const likes = $("hf-likes");
+  likes.textContent = `♥ ${vm.likes}`;
+  likes.href = vm.hfUrl;
+  $("btn-open").href = vm.hfUrl;
+  setLikeState(store.isLiked(vm.id));
+  setSaveState(store.isSaved(vm.id));
+}
+export function setLikeState(on) { $("btn-like").classList.toggle("on", !!on); }
+export function setSaveState(on) { $("btn-save").classList.toggle("on", !!on); }
+export function setHfLikes(n) { $("hf-likes").textContent = `♥ ${n}`; }
+export function setProgress(p) {
+  $("progress").textContent = `↳ ${p.seen} / ${p.total} seen · lap ${p.round}`;
+}
+export function setSavedCount(n) { $("btn-saved").textContent = `☰ Saved (${n})`; }
+export function setTrackFilterLabel(track) {
+  $("btn-track").textContent = `⤮ ${track || "All"}`;
+}
+let toastTimer = null;
+export function toast(msg, ms = 2600) {
+  const t = $("toast");
+  t.textContent = msg;
+  t.hidden = false;
+  clearTimeout(toastTimer);
+  toastTimer = setTimeout(() => (t.hidden = true), ms);
+}
+export function renderAuth(user, { onSignIn, onSignOut }) {
+  const a = $("auth");
+  a.innerHTML = "";
+  if (user) {
+    const img = document.createElement("img");
+    img.src = user.picture; img.width = 22; img.height = 22;
+    img.className = "avatar";
+    const out = document.createElement("button");
+    out.className = "btn btn-ghost";
+    out.textContent = `@${user.preferred_username} ⏏`;
+    out.onclick = onSignOut;
+    a.append(img, out);
+  } else {
+    const inBtn = document.createElement("button");
+    inBtn.className = "btn btn-ghost";
+    inBtn.textContent = "Sign in to like on HF";
+    inBtn.onclick = onSignIn;
+    a.append(inBtn);
+  }
+}
+const NAMED = {
+  indigo: "#4f46e5", green: "#16a34a", blue: "#2563eb", red: "#dc2626", yellow: "#eab308",
+  purple: "#9333ea", pink: "#db2777", orange: "#ea580c", gray: "#6b7280", teal: "#0d9488",
+};
+function cssColor(name) { return NAMED[name] || "#6b7280"; }
+export function openDrawer(savedVms, { onOpenHere, onUnsave }) {
+  const d = $("drawer");
+  d.hidden = false;
+  d.innerHTML = `<div class="drawer-head">
+    <strong>Saved (${savedVms.length})</strong>
+    <button class="btn btn-ghost" id="drawer-close">✕</button></div>`;
+  $("drawer-close").onclick = () => (d.hidden = true);
+  if (!savedVms.length) {
+    d.insertAdjacentHTML("beforeend", `<p class="drawer-empty">Nothing saved yet. Tap 💾 on a project you like.</p>`);
+    return;
+  }
+  for (const vm of savedVms) {
+    const row = document.createElement("div");
+    row.className = "saved-row";
+    row.innerHTML = `
+      <span class="saved-thumb" style="background:linear-gradient(135deg,${cssColor(vm.colorFrom)},${cssColor(vm.colorTo)})">${vm.emoji}</span>
+      <span class="saved-meta">
+        <span class="saved-title">${vm.title}</span>
+        <span class="saved-sub">${vm.track || vm.sdk}</span>
+      </span>`;
+    row.onclick = () => onOpenHere(vm.id);
+    const un = document.createElement("button");
+    un.className = "btn btn-ghost";
+    un.textContent = "🗑";
+    un.onclick = (e) => { e.stopPropagation(); onUnsave(vm.id); row.remove(); };
+    row.append(un);
+    d.append(row);
+  }
+}
+export function showShortcuts() {
+  const o = $("overlay");
+  o.hidden = false;
+  o.innerHTML = `<div class="overlay-card">
+    <h3>Shortcuts</h3>
+    <ul class="keys">
+      <li><kbd>Space</kbd> / <kbd>→</kbd> Next</li>
+      <li><kbd>←</kbd> Prev</li>
+      <li><kbd>L</kbd> Like</li>
+      <li><kbd>S</kbd> Save</li>
+      <li><kbd>O</kbd> Open on HF</li>
+      <li><kbd>?</kbd> This help</li>
+    </ul>
+    <button class="btn btn-next" id="ov-close">Got it</button></div>`;
+  $("ov-close").onclick = () => (o.hidden = true);
+  o.onclick = (e) => { if (e.target === o) o.hidden = true; };
+}

style.css CHANGED Viewed

@@ -1,28 +1,182 @@
 body {
-	padding: 2rem;
-	font-family: -apple-system, BlinkMacSystemFont, "Arial", sans-serif;
 }
-h1 {
-	font-size: 16px;
-	margin-top: 0;
 }
-p {
-	color: rgb(107, 114, 128);
-	font-size: 15px;
-	margin-bottom: 10px;
-	margin-top: 5px;
 }
-.card {
-	max-width: 620px;
-	margin: 0 auto;
-	padding: 16px;
-	border: 1px solid lightgray;
-	border-radius: 16px;
 }
-.card p:last-child {
-	margin-bottom: 0;
 }

+/* Build Small Roulette — "dusk on the trail" field-guide theme.
+   The embedded Space is the star: chrome stays dark, thin, and disciplined.
+   Boldness is spent in one place — the specimen field-tag + dotted trail + compass. */
+:root {
+  --bark: #20281f;          /* deep forest, near-black — persistent bars */
+  --bark-2: #161a14;        /* stage backdrop */
+  --parchment: #f3ead6;     /* warm paper — journal panels + text on bark */
+  --blaze: #e2602a;         /* trail-blaze orange — Next + active, used sparingly */
+  --lichen: #b8c4a9;        /* muted sage — secondary/data text */
+  --moss: #3a5a40;          /* forest — track badge */
+  --ink: #2a2620;           /* text on parchment */
+  --line: rgba(184,196,169,.20);
+  --font-display: "Fraunces", Georgia, "Times New Roman", serif;
+  --font-mono: "Space Mono", ui-monospace, "SFMono-Regular", monospace;
+  --font-body: system-ui, "Segoe UI", sans-serif;
+}
+* { box-sizing: border-box; }
+html, body { height: 100%; margin: 0; }
 body {
+  font: 15px/1.45 var(--font-body);
+  color: var(--ink); background: var(--bark-2);
+  display: grid; grid-template-rows: auto 1fr auto; height: 100dvh; overflow: hidden;
 }
+/* ---- persistent bars ---- */
+.topbar, .bottombar {
+  display: flex; align-items: center; gap: 10px;
+  background: var(--bark); color: var(--parchment); padding: 9px 14px; z-index: 5;
+}
+.topbar { border-bottom: 2px solid var(--blaze); }           /* the trail blaze */
+.bottombar {
+  font: 12px/1 var(--font-mono); letter-spacing: .02em;
+  border-top: 1.5px dotted rgba(184,196,169,.4);             /* the trail line */
+}
+.tb-left { display: flex; align-items: center; gap: 10px; min-width: 0; flex: 1; }
+.tb-right { display: flex; align-items: center; gap: 8px; }
+.emoji {
+  font-size: 18px; line-height: 1; flex: 0 0 auto;
+  width: 30px; height: 30px; display: grid; place-items: center;
+  background: rgba(243,234,214,.08); border: 1px solid var(--line); border-radius: 9px;
+}
+.title {
+  font: 600 19px/1.1 var(--font-display); letter-spacing: -.01em;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+.track-badge {
+  font: 700 10px/1 var(--font-mono); letter-spacing: .12em; text-transform: uppercase;
+  padding: 4px 9px; border-radius: 4px; flex: 0 0 auto;
+  background: var(--moss); color: #eafdf0; box-shadow: inset 0 0 0 1px rgba(255,255,255,.08);
 }
+.hf-likes {
+  font: 400 12px/1 var(--font-mono); color: var(--lichen);
+  text-decoration: none; white-space: nowrap; flex: 0 0 auto;
+}
+.hf-likes:hover { color: var(--parchment); }
+/* ---- buttons ---- */
+.btn {
+  font: inherit; cursor: pointer; border: 0; border-radius: 9px;
+  background: transparent; color: inherit; padding: 8px 10px;
+  transition: transform .12s ease, background .15s ease, opacity .15s ease;
+}
+.btn-icon {
+  font-size: 17px; line-height: 1; width: 38px; height: 36px;
+  background: rgba(243,234,214,.08); border: 1px solid var(--line);
 }
+.btn-icon:hover { background: rgba(243,234,214,.16); }
+.btn-icon.on { background: var(--blaze); border-color: var(--blaze); animation: pop .32s ease; }
+.btn-icon:active { transform: scale(.9); }
+.btn-next {
+  font: 700 14px/1 var(--font-body); letter-spacing: .01em;
+  background: var(--blaze); color: #fff; padding: 11px 18px; display: inline-flex; gap: 7px; align-items: center;
+  box-shadow: 0 1px 0 rgba(0,0,0,.25);
+}
+.btn-next:hover { filter: brightness(1.06); }
+.btn-next:active { transform: translateY(1px); }
+.btn-next .compass { display: inline-block; font-size: 15px; transition: transform .45s cubic-bezier(.34,1.56,.64,1); }
+.btn-next:hover .compass { transform: rotate(72deg); }
+.btn-ghost { color: var(--parchment); opacity: .8; }
+.btn-ghost:hover { opacity: 1; background: rgba(243,234,214,.08); }
+.progress { margin-left: auto; color: var(--lichen); white-space: nowrap; }
+.auth { display: flex; align-items: center; gap: 7px; }
+.avatar { border-radius: 50%; border: 1px solid var(--line); }
+@keyframes pop { 0% { transform: scale(1); } 45% { transform: scale(1.22); } 100% { transform: scale(1); } }
+/* ---- stage + iframe ---- */
+.stage {
+  position: relative; background-color: var(--bark-2); overflow: hidden;
+  background-image:
+    linear-gradient(rgba(184,196,169,.045) 1px, transparent 1px),
+    linear-gradient(90deg, rgba(184,196,169,.045) 1px, transparent 1px); /* field-notebook grid */
+  background-size: 28px 28px;
+}
+.stage iframe {
+  position: absolute; inset: 0; width: 100%; height: 100%; border: 0;
+  opacity: 0; transition: opacity .4s ease;
+}
+.stage iframe.ready { opacity: 1; }
+.loader, .fallback {
+  position: absolute; inset: 0; display: flex; flex-direction: column;
+  align-items: center; justify-content: center; gap: 14px; color: var(--parchment);
+  text-align: center; padding: 24px;
+}
+.loader { font: 400 14px/1.4 var(--font-mono); color: var(--lichen); letter-spacing: .04em; }
+.loader::after { content: " ·"; animation: blink 1.1s steps(3, end) infinite; }
+@keyframes blink { 0% { opacity: .2; } 50% { opacity: 1; } 100% { opacity: .2; } }
+.fallback strong { font: 600 22px/1.2 var(--font-display); }
+.fallback p { max-width: 32ch; margin: 0; color: var(--lichen); }
+.fallback-emoji { font-size: 44px; }
+.fallback-actions { display: flex; gap: 10px; }
+.fallback .btn { background: var(--blaze); color: #fff; }
+.fallback .btn-ghost { background: rgba(243,234,214,.12); color: var(--parchment); }
+/* ---- drawer (the field journal) ---- */
+.drawer {
+  position: fixed; top: 0; right: 0; width: min(380px, 92vw); height: 100%;
+  background: var(--parchment); color: var(--ink); z-index: 20; padding: 18px; overflow: auto;
+  box-shadow: -10px 0 30px rgba(0,0,0,.35); border-left: 3px solid var(--blaze);
+}
+.drawer-head { display: flex; justify-content: space-between; align-items: center; margin-bottom: 14px; }
+.drawer-head strong { font: 600 19px/1 var(--font-display); }
+.drawer-head .btn-ghost { color: var(--ink); }
+.drawer-empty { color: rgba(42,38,32,.7); }
+.saved-row { display: flex; gap: 11px; align-items: center; padding: 9px; border-radius: 10px; cursor: pointer; }
+.saved-row:hover { background: rgba(42,38,32,.07); }
+.saved-thumb {
+  width: 36px; height: 36px; border-radius: 9px; display: grid; place-items: center;
+  font-size: 18px; flex: 0 0 auto; box-shadow: inset 0 0 0 1px rgba(0,0,0,.15);
+}
+.saved-meta { flex: 1; min-width: 0; }
+.saved-title { display: block; font: 600 15px/1.2 var(--font-display); overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.saved-sub { font: 400 11px/1 var(--font-mono); color: rgba(42,38,32,.6); text-transform: uppercase; letter-spacing: .08em; }
+.saved-row .btn-ghost { color: var(--ink); opacity: .55; }
+.saved-row .btn-ghost:hover { opacity: 1; background: rgba(42,38,32,.08); }
+/* ---- overlay (shortcuts) ---- */
+.overlay {
+  position: fixed; inset: 0; background: rgba(22,26,20,.9); color: var(--parchment);
+  z-index: 30; display: flex; align-items: center; justify-content: center; padding: 24px;
+}
+.overlay-card {
+  max-width: 320px; background: var(--bark); border: 1px solid var(--line);
+  border-radius: 14px; padding: 22px 24px; box-shadow: 0 20px 60px rgba(0,0,0,.5);
+}
+.overlay-card h3 { font: 600 20px/1 var(--font-display); margin: 0 0 14px; }
+.keys { list-style: none; padding: 0; margin: 0 0 18px; font: 13px/1 var(--font-mono); }
+.keys li { display: flex; gap: 8px; align-items: center; padding: 6px 0; color: var(--lichen); }
+kbd {
+  background: rgba(243,234,214,.1); border: 1px solid var(--line); border-radius: 5px;
+  padding: 2px 7px; font: 12px/1 var(--font-mono); color: var(--parchment); min-width: 18px; text-align: center;
+}
+/* ---- toast ---- */
+.toast {
+  position: fixed; bottom: 64px; left: 50%; transform: translateX(-50%);
+  background: var(--bark); color: var(--parchment); border: 1px solid var(--line);
+  padding: 11px 16px; border-radius: 10px; z-index: 40; max-width: 90vw; text-align: center;
+  font: 13px/1.3 var(--font-mono); box-shadow: 0 8px 24px rgba(0,0,0,.4);
+}
+/* ---- accessibility floor ---- */
+.btn:focus-visible, .saved-row:focus-visible, a:focus-visible {
+  outline: 2px solid var(--blaze); outline-offset: 2px;
+}
+@media (prefers-reduced-motion: reduce) {
+  *, *::after { animation: none !important; transition: none !important; }
+  .stage iframe { opacity: 1; }
 }
+/* ---- mobile ---- */
+@media (max-width: 620px) {
+  .title { font-size: 17px; }
+  .btn-next { padding: 11px 14px; }
+  .bottombar { gap: 8px; flex-wrap: wrap; }
+  .hf-likes { display: none; }
+  .progress { margin-left: 0; order: 9; flex-basis: 100%; }
 }