handzon-core 0.15.2 → 0.15.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.15.2",
+  "version": "0.15.4",
   "description": "Core framework for Handzon — layouts, components, content + AI libs, and server runtime (handlers, DB, auth, migration runner) consumed by Handzon scaffolds.",
   "publishConfig": {
     "access": "public"

package/src/components/auth/UserMenu.astro

@@ -14,29 +14,13 @@ import UserMenuIsland from "./UserMenu.tsx";
 // fallback to the cached signed-in state, removing the nav reload flash.
 const AUTH_SNAPSHOT_KEY = "hz-auth-snapshot";
 const TOKENS_HREF = withBase("/settings/tokens");
-
-const GITHUB_ICON_PATH =
-  "M12 .5C5.65.5.5 5.65 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.55v-2.02c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.03 1.76 2.7 1.25 3.36.96.1-.74.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.66 0-1.25.45-2.27 1.18-3.07-.12-.29-.51-1.45.11-3.03 0 0 .96-.31 3.15 1.17a10.94 10.94 0 0 1 5.76 0c2.19-1.48 3.15-1.17 3.15-1.17.62 1.58.23 2.74.11 3.03.74.8 1.18 1.82 1.18 3.07 0 4.4-2.69 5.37-5.25 5.65.41.35.78 1.04.78 2.11v3.13c0 .3.21.66.79.55C20.71 21.39 24 17.08 24 12 24 5.65 18.85.5 12 .5z";
 ---
 <div class="user-menu-shell">
   <div class="user-menu um-fallback" data-user-menu-fallback aria-hidden="true">
-    {/* Signed-out placeholder. Shown by default; the inline script below
-        hides it when a cached signed-in snapshot exists. */}
-    <span class="um-fallback-variant" data-um-fallback-signedout>
-      <button type="button" class="um-btn" disabled tabindex="-1">
-        <svg
-          class="um-gh"
-          viewBox="0 0 24 24"
-          width="14"
-          height="14"
-          fill="currentColor"
-          aria-hidden="true"
-        >
-          <path d={GITHUB_ICON_PATH} />
-        </svg>
-        <span>Sign in with GitHub</span>
-      </button>
-    </span>
+    {/* Neutral placeholder. The static page cannot read Auth.js' HttpOnly
+        session cookie, so do not show a signed-out GitHub button until
+        the client fetch resolves. */}
+    <span class="um-fallback-variant um-fallback-spacer" data-um-fallback-spacer></span>
     {/* Signed-in placeholder. Hidden until the inline script fills in the
         cached avatar + name and reveals it. Mirrors the island's
         signed-in layout so the swap on hydration is invisible. */}
@@ -97,9 +81,9 @@ const GITHUB_ICON_PATH =
       if (!user) return; // signed out → keep the default placeholder
       var root = document.querySelector("[data-user-menu-fallback]");
       if (!root) return;
-      var signedOut = root.querySelector("[data-um-fallback-signedout]");
+      var spacer = root.querySelector("[data-um-fallback-spacer]");
       var signedIn = root.querySelector("[data-um-fallback-signedin]");
-      if (!signedOut || !signedIn) return;
+      if (!spacer || !signedIn) return;
 
       var label = user.name || user.email || "Signed in";
       var first = String(label).trim().split(/\s+/)[0] || "Signed in";
@@ -118,7 +102,7 @@ const GITHUB_ICON_PATH =
         initial.textContent = label.trim().charAt(0).toUpperCase();
         initial.hidden = false;
       }
-      signedOut.hidden = true;
+      spacer.hidden = true;
       signedIn.hidden = false;
     } catch (e) {
       /* ignore — fall back to the default signed-out placeholder */
@@ -180,6 +164,11 @@ const GITHUB_ICON_PATH =
   .um-fallback-variant[hidden] {
     display: none;
   }
+  .um-fallback-spacer {
+    display: inline-block;
+    width: 11.5rem;
+    height: calc(1em + 0.6rem + 2px);
+  }
   .um-btn {
     display: inline-flex;
     align-items: center;

package/src/components/auth/UserMenu.tsx

@@ -1,5 +1,6 @@
 import { useEffect, useLayoutEffect, useState } from "react";
 import { withBase } from "../../lib/base";
+import { GITHUB_ICON_PATH } from "../../lib/icons";
 
 /**
  * Client-only auth menu. Fetches `/api/auth/session` + `/api/auth/csrf`
@@ -77,9 +78,6 @@ function clearAuthSnapshot() {
   }
 }
 
-const GITHUB_ICON_PATH =
-  "M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.55v-2.02c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.03 1.76 2.7 1.25 3.36.96.1-.74.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.66 0-1.25.45-2.27 1.18-3.07-.12-.29-.51-1.45.11-3.03 0 0 .96-.31 3.15 1.17a10.94 10.94 0 0 1 5.76 0c2.19-1.48 3.15-1.17 3.15-1.17.62 1.58.23 2.74.11 3.03.74.8 1.18 1.82 1.18 3.07 0 4.4-2.69 5.37-5.25 5.65.41.35.78 1.04.78 2.11v3.13c0 .3.21.66.79.55C20.71 21.39 24 17.08 24 12 24 5.65 18.85.5 12 .5z";
-
 export default function UserMenu() {
   // `undefined` = not yet loaded; `null` = no auth or signed out;
   // object = signed in. Seeded from the last-known snapshot so a

package/src/components/home/ActiveFilterChips.tsx

@@ -5,9 +5,11 @@ interface Props {
   q: string;
   levels: Set<string>;
   tags: Set<string>;
+  favoritesOnly: boolean;
   onClearQ: () => void;
   onRemoveLevel: (level: string) => void;
   onRemoveTag: (tag: string) => void;
+  onClearFavorites: () => void;
   onClearAll: () => void;
 }
 
@@ -27,9 +29,11 @@ export default function ActiveFilterChips({
   q,
   levels,
   tags,
+  favoritesOnly,
   onClearQ,
   onRemoveLevel,
   onRemoveTag,
+  onClearFavorites,
   onClearAll,
 }: Props) {
   function chipKey(e: KeyboardEvent<HTMLButtonElement>, remove: () => void) {
@@ -80,6 +84,18 @@ export default function ActiveFilterChips({
           <X size={12} aria-hidden="true" />
         </button>
       ))}
+      {favoritesOnly && (
+        <button
+          type="button"
+          className="active-filter-chip"
+          aria-label="Remove favorites filter"
+          onClick={onClearFavorites}
+          onKeyDown={(e) => chipKey(e, onClearFavorites)}
+        >
+          <span className="afc-label">favorites</span>
+          <X size={12} aria-hidden="true" />
+        </button>
+      )}
       <button type="button" className="active-filter-clear" onClick={onClearAll}>
         Clear all
       </button>

package/src/components/home/FilterBar.tsx

@@ -1,5 +1,5 @@
-import { GraduationCap, Hash, Search } from "lucide-react";
-import { useEffect, useState } from "react";
+import { GraduationCap, Hash, Search, Star } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
 import MultiSelect, { type MultiSelectOption } from "../ui/MultiSelect.tsx";
 import ActiveFilterChips from "./ActiveFilterChips.tsx";
 import SortBar from "./SortBar.tsx";
@@ -17,6 +17,7 @@ interface FilterState {
   q: string;
   levels: Set<string>;
   tags: Set<string>;
+  favoritesOnly: boolean;
 }
 
 function parseCsv(value: string | null): Set<string> {
@@ -31,7 +32,7 @@ function parseCsv(value: string | null): Set<string> {
 
 function readUrlState(): FilterState {
   if (typeof window === "undefined") {
-    return { q: "", levels: new Set(), tags: new Set() };
+    return { q: "", levels: new Set(), tags: new Set(), favoritesOnly: false };
   }
   const url = new URL(window.location.href);
   const levels = url.searchParams.get("level")
@@ -43,6 +44,7 @@ function readUrlState(): FilterState {
     q: url.searchParams.get("q") ?? "",
     levels,
     tags: parseCsv(url.searchParams.get("tag")),
+    favoritesOnly: url.searchParams.get("favorites") === "1",
   };
 }
 
@@ -54,6 +56,8 @@ function writeUrlState(state: FilterState) {
   else url.searchParams.delete("level");
   if (state.tags.size > 0) url.searchParams.set("tag", [...state.tags].join(","));
   else url.searchParams.delete("tag");
+  if (state.favoritesOnly) url.searchParams.set("favorites", "1");
+  else url.searchParams.delete("favorites");
   // Always strip the legacy key so an upgraded URL doesn't carry both
   // shapes. First user interaction "migrates" the link.
   url.searchParams.delete("difficulty");
@@ -69,7 +73,8 @@ function applyFilters(state: FilterState) {
     const matchesLevel = state.levels.size === 0 || state.levels.has(card.dataset.difficulty ?? "");
     const cardTags = (card.dataset.tags ?? "").split(",");
     const matchesTag = state.tags.size === 0 || cardTags.some((t) => state.tags.has(t));
-    const show = matchesQ && matchesLevel && matchesTag;
+    const matchesFavorite = !state.favoritesOnly || card.hasAttribute("data-favorited");
+    const show = matchesQ && matchesLevel && matchesTag && matchesFavorite;
     if (show) {
       card.removeAttribute("data-filter-hidden");
       visible += 1;
@@ -100,12 +105,22 @@ function applyFilters(state: FilterState) {
 
 export default function FilterBar({ difficulties, tags, difficultyCounts, tagCounts }: Props) {
   const [state, setState] = useState<FilterState>(readUrlState);
+  const stateRef = useRef(state);
 
   useEffect(() => {
+    stateRef.current = state;
     applyFilters(state);
     writeUrlState(state);
   }, [state]);
 
+  useEffect(() => {
+    function onFavoritesChanged() {
+      applyFilters(stateRef.current);
+    }
+    window.addEventListener("hz:favorites-changed", onFavoritesChanged);
+    return () => window.removeEventListener("hz:favorites-changed", onFavoritesChanged);
+  }, []);
+
   function setQ(q: string) {
     setState((prev) => ({ ...prev, q }));
   }
@@ -115,6 +130,9 @@ export default function FilterBar({ difficulties, tags, difficultyCounts, tagCou
   function setTags(next: Set<string>) {
     setState((prev) => ({ ...prev, tags: next }));
   }
+  function setFavoritesOnly(favoritesOnly: boolean) {
+    setState((prev) => ({ ...prev, favoritesOnly }));
+  }
   function removeLevel(level: string) {
     setState((prev) => {
       const next = new Set(prev.levels);
@@ -130,7 +148,7 @@ export default function FilterBar({ difficulties, tags, difficultyCounts, tagCou
     });
   }
   function clearAll() {
-    setState({ q: "", levels: new Set(), tags: new Set() });
+    setState({ q: "", levels: new Set(), tags: new Set(), favoritesOnly: false });
   }
 
   const levelOpts: MultiSelectOption[] = difficulties.map((d) => ({
@@ -144,7 +162,8 @@ export default function FilterBar({ difficulties, tags, difficultyCounts, tagCou
     count: tagCounts[t] ?? 0,
   }));
 
-  const hasActive = state.q.length > 0 || state.levels.size > 0 || state.tags.size > 0;
+  const hasActive =
+    state.q.length > 0 || state.levels.size > 0 || state.tags.size > 0 || state.favoritesOnly;
 
   return (
     <div className="filterbar">
@@ -179,6 +198,16 @@ export default function FilterBar({ difficulties, tags, difficultyCounts, tagCou
           triggerIcon={<Hash size={14} aria-hidden="true" />}
         />
 
+        <button
+          type="button"
+          className="favorites-filter"
+          aria-pressed={state.favoritesOnly}
+          onClick={() => setFavoritesOnly(!state.favoritesOnly)}
+        >
+          <Star size={14} aria-hidden="true" />
+          Favorites
+        </button>
+
         <span className="fb-divider" aria-hidden="true" />
         <div className="fb-sort-slot">
           <SortBar />
@@ -190,9 +219,11 @@ export default function FilterBar({ difficulties, tags, difficultyCounts, tagCou
           q={state.q}
           levels={state.levels}
           tags={state.tags}
+          favoritesOnly={state.favoritesOnly}
           onClearQ={() => setQ("")}
           onRemoveLevel={removeLevel}
           onRemoveTag={removeTag}
+          onClearFavorites={() => setFavoritesOnly(false)}
           onClearAll={clearAll}
         />
       )}

package/src/components/home/TutorialCard.astro

@@ -37,6 +37,30 @@ const defaultCover = getDefaultCoverMeta({
   data-card-slug={slug}
   data-popularity="0"
 >
+  <button
+    type="button"
+    class="card-fav"
+    data-fav-slug={slug}
+    aria-pressed="false"
+    aria-label={`Add ${data.title} to favorites`}
+  >
+    <svg
+      viewBox="0 0 24 24"
+      width="18"
+      height="18"
+      fill="none"
+      stroke="currentColor"
+      stroke-width="2"
+      stroke-linecap="round"
+      stroke-linejoin="round"
+      aria-hidden="true"
+    >
+      <path
+        d="M11.48 3.5a.59.59 0 0 1 1.04 0l2.38 4.82a.59.59 0 0 0 .44.32l5.32.77a.59.59 0 0 1 .33 1l-3.85 3.75a.59.59 0 0 0-.17.52l.91 5.3a.59.59 0 0 1-.86.62l-4.76-2.5a.59.59 0 0 0-.55 0l-4.76 2.5a.59.59 0 0 1-.86-.62l.91-5.3a.59.59 0 0 0-.17-.52L3.01 10.4a.59.59 0 0 1 .33-1l5.32-.77a.59.59 0 0 0 .44-.32l2.38-4.82Z"
+      />
+    </svg>
+    <span class="sr-only">Favorite</span>
+  </button>
   <a href={withBase(`/${slug}`)} class="card-link">
     <div class="card-media">
       {
@@ -151,6 +175,7 @@ const defaultCover = getDefaultCoverMeta({
     border: 1px solid var(--color-border);
     background: var(--color-bg);
     display: flex;
+    position: relative;
     transition:
       border-color 0.12s ease,
       transform 0.12s ease;
@@ -166,6 +191,36 @@ const defaultCover = getDefaultCoverMeta({
     flex-direction: column;
     width: 100%;
   }
+  .card-fav {
+    position: absolute;
+    top: 0.35rem;
+    right: 0.35rem;
+    z-index: 5;
+    display: inline-grid;
+    place-items: center;
+    width: 2rem;
+    height: 2rem;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: var(--color-muted);
+    cursor: pointer;
+    transition:
+      color 0.12s ease,
+      transform 0.12s ease;
+  }
+  .card-fav:hover,
+  .card-fav:focus-visible {
+    color: var(--color-fg);
+    outline: none;
+    transform: scale(1.04);
+  }
+  .card-fav[aria-pressed="true"] {
+    color: #fff;
+  }
+  .card-fav[aria-pressed="true"] svg {
+    fill: currentColor;
+  }
   .card-media {
     aspect-ratio: 16 / 9;
     border-bottom: 1px solid var(--color-border);

package/src/lib/icons.ts

@@ -0,0 +1,3 @@
+import { siGithub } from "simple-icons";
+
+export const GITHUB_ICON_PATH = siGithub.path;

package/src/lib/progress/types.ts

@@ -35,6 +35,11 @@ export type ProgressState = {
   steps: Record<StepKey, "incomplete" | "complete">;
   quizzes: Record<string, { chosen: number[]; correct: boolean; ts: number }>;
   checkpoints: Record<string, { ts: number }>;
+  /**
+   * Per-learner favorite tutorials. Keyed by tutorial slug; the value is
+   * the timestamp when the learner last favorited it.
+   */
+  favorites: Record<string, number>;
   /**
    * Latest verification verdict per checkpoint id. `pass: true`
    * entries hang around as evidence; the Family D UI only renders
@@ -73,6 +78,7 @@ export const emptyState = (): ProgressState => ({
   steps: {},
   quizzes: {},
   checkpoints: {},
+  favorites: {},
   verificationFeedback: {},
   prefs: {},
   lastVisited: {},

package/src/lib/progress/useProgress.ts

@@ -16,7 +16,9 @@ interface ProgressApi {
   setLastVisited: (tutorial: string, step: string) => void;
   markTutorialStarted: (tutorial: string) => void;
   markTutorialCompleted: (tutorial: string) => void;
+  toggleFavorite: (tutorial: string) => void;
   isStepComplete: (tutorial: string, step: string) => boolean;
+  isFavorite: (tutorial: string) => boolean;
 }
 
 /**
@@ -100,6 +102,16 @@ export function useProgress(): ProgressApi {
             },
           };
         }),
+      toggleFavorite: (tutorial: string) =>
+        store.set((s) => {
+          const nextFavorites = { ...s.favorites };
+          if (nextFavorites[tutorial]) {
+            delete nextFavorites[tutorial];
+          } else {
+            nextFavorites[tutorial] = Date.now();
+          }
+          return { ...s, favorites: nextFavorites };
+        }),
     };
   }, [store]);
 
@@ -108,6 +120,7 @@ export function useProgress(): ProgressApi {
     ...actions,
     isStepComplete: (tutorial, step) =>
       state.steps[`${tutorial}/${step}` as StepKey] === "complete",
+    isFavorite: (tutorial) => !!state.favorites[tutorial],
   };
 }
 

package/src/pages/Home.astro

@@ -168,6 +168,64 @@ for (const t of tutorials) {
     getStore().subscribe(refresh);
   </script>
 
+  <script>
+    // Hydrate per-card favorites from the same local progress store used
+    // by steps and preferences. Cards expose `data-favorited` so the
+    // FilterBar can compose favorites with search, facets, and pagination.
+    import { getStore } from "../lib/progress/local.ts";
+    const store = getStore();
+    let lastFavoritesSignature: string | null = null;
+
+    function favoriteSignature(favorites: Record<string, number>): string {
+      return Object.keys(favorites).sort().join("\0");
+    }
+
+    function paintFavorites() {
+      const favorites = store.get().favorites ?? {};
+      const favoriteSlugs = new Set(Object.keys(favorites));
+      const signature = favoriteSignature(favorites);
+      document.querySelectorAll<HTMLButtonElement>("[data-fav-slug]").forEach((button) => {
+        const slug = button.dataset.favSlug!;
+        const card = button.closest<HTMLElement>("[data-card-slug]");
+        const title = card?.querySelector("h3")?.textContent?.trim() ?? slug;
+        const isFavorite = favoriteSlugs.has(slug);
+        button.setAttribute("aria-pressed", String(isFavorite));
+        button.setAttribute(
+          "aria-label",
+          isFavorite ? `Remove ${title} from favorites` : `Add ${title} to favorites`,
+        );
+        if (isFavorite) {
+          card?.setAttribute("data-favorited", "");
+        } else {
+          card?.removeAttribute("data-favorited");
+        }
+      });
+      if (signature !== lastFavoritesSignature) {
+        lastFavoritesSignature = signature;
+        window.dispatchEvent(new CustomEvent("hz:favorites-changed"));
+      }
+    }
+
+    document.querySelectorAll<HTMLButtonElement>("[data-fav-slug]").forEach((button) => {
+      button.addEventListener("click", () => {
+        const slug = button.dataset.favSlug;
+        if (!slug) return;
+        store.set((state) => {
+          const favorites = { ...state.favorites };
+          if (favorites[slug]) {
+            delete favorites[slug];
+          } else {
+            favorites[slug] = Date.now();
+          }
+          return { ...state, favorites };
+        });
+      });
+    });
+
+    paintFavorites();
+    store.subscribe(paintFavorites);
+  </script>
+
   <script>
     // Hydrate cross-learner popularity numbers and the `data-popularity`
     // attribute used by the FilterBar's "Popular" sort. Single fetch on
@@ -217,22 +275,36 @@ for (const t of tutorials) {
   </script>
 
   <script>
-    // Popularity sort: re-orders cards in place by writing CSS `order`
-    // from `data-popularity`. Composes with the existing filter/page
-    // hide attributes because order is a flex/grid layout concern, not
-    // a visibility concern.
+    // Home-page ordering: tutorials this learner already started come
+    // first. Within that group, either keep the curated server order or
+    // apply the selected popularity sort.
+    import { getStore } from "../lib/progress/local.ts";
+    const store = getStore();
+
+    function hasStarted(card: HTMLElement): boolean {
+      const slug = card.dataset.cardSlug;
+      if (!slug) return false;
+      return !!store.get().tutorials[slug]?.started;
+    }
+
     function applySort(mode: string) {
-      const cards = document.querySelectorAll<HTMLElement>("[data-card-slug]");
+      const cards = Array.from(document.querySelectorAll<HTMLElement>("[data-card-slug]"));
+      const originalOrder = new Map(cards.map((card, idx) => [card, idx]));
       if (mode === "popular") {
-        const sorted = Array.from(cards).sort((a, b) => {
-          return Number(b.dataset.popularity ?? 0) - Number(a.dataset.popularity ?? 0);
+        const sorted = cards.sort((a, b) => {
+          const startedDelta = Number(hasStarted(b)) - Number(hasStarted(a));
+          if (startedDelta !== 0) return startedDelta;
+          const popularityDelta =
+            Number(b.dataset.popularity ?? 0) - Number(a.dataset.popularity ?? 0);
+          if (popularityDelta !== 0) return popularityDelta;
+          return (originalOrder.get(a) ?? 0) - (originalOrder.get(b) ?? 0);
         });
         sorted.forEach((card, idx) => {
           card.style.order = String(idx);
         });
       } else {
-        cards.forEach((card) => {
-          card.style.removeProperty("order");
+        cards.forEach((card, idx) => {
+          card.style.order = String(hasStarted(card) ? idx : idx + cards.length);
         });
       }
     }
@@ -245,6 +317,7 @@ for (const t of tutorials) {
       applySort((e as CustomEvent<{ sort: string }>).detail.sort);
     });
     window.addEventListener("hz:stats-loaded", syncFromUrl);
+    store.subscribe(syncFromUrl);
   </script>
 </BaseLayout>
 

package/styles/components/filterbar.css

@@ -65,6 +65,35 @@
   flex-shrink: 0;
 }
 
+.favorites-filter {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.45rem;
+  min-height: 2.5rem;
+  padding: 0.4rem 0.65rem;
+  background: transparent;
+  border: 1px solid var(--color-border);
+  color: var(--color-fg);
+  font-family: var(--font-mono);
+  font-size: 0.78em;
+  cursor: pointer;
+  transition: border-color 0.12s ease, color 0.12s ease, background 0.12s ease;
+}
+.favorites-filter:hover,
+.favorites-filter:focus-visible {
+  border-color: var(--color-accent);
+  color: var(--color-accent);
+  outline: none;
+}
+.favorites-filter[aria-pressed="true"] {
+  border-color: var(--color-accent);
+  color: var(--color-accent);
+  background: color-mix(in oklab, var(--color-accent) 8%, transparent);
+}
+.favorites-filter[aria-pressed="true"] svg {
+  fill: currentColor;
+}
+
 /* On narrow viewports the toolbar wraps; sort drops to its own line.
  * Keep the divider visible only when the row hasn't wrapped — when it
  * has, the layout already reads as distinct rows. Cheap heuristic: