handzon-core 0.15.3 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "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/StepNav.astro

@@ -11,17 +11,20 @@ interface Props {
   currentStepSlug: string;
   gated: boolean;
   hasCheckpoint: boolean;
+  hasQuiz: boolean;
   nextTutorial?: TutorialSummary;
 }
 
-const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint, nextTutorial } = Astro.props;
+const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint, hasQuiz, nextTutorial } =
+  Astro.props;
 const idx = steps.findIndex((s) => parseStepId(s.id).stepSlug === currentStepSlug);
 const prev = idx > 0 ? steps[idx - 1] : null;
 const next = idx >= 0 && idx < steps.length - 1 ? steps[idx + 1] : null;
 const prevSlug = prev ? parseStepId(prev.id).stepSlug : null;
 const nextSlug = next ? parseStepId(next.id).stepSlug : null;
+const hasCompletionItem = hasCheckpoint || hasQuiz;
 ---
-<nav class:list={["step-nav", !next && "step-nav-final"]} data-gated={gated && hasCheckpoint ? "true" : "false"} data-step-key={`${tutorialSlug}/${currentStepSlug}`}>
+<nav class:list={["step-nav", !next && "step-nav-final"]} data-gated={gated && hasCompletionItem ? "true" : "false"} data-step-key={`${tutorialSlug}/${currentStepSlug}`}>
   <div>
     {prev && (
       <a class="sn-prev" href={withBase(`/${tutorialSlug}/${prevSlug}`)}>
@@ -32,7 +35,7 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
   <div class="sn-slot">
     {next ? (
       <a class="sn-next" href={withBase(`/${tutorialSlug}/${nextSlug}`)} data-next-link="true">
-        {hasCheckpoint ? "Continue" : "Next"}: {next.data.title} →
+        {hasCompletionItem ? "Continue" : "Next"}: {next.data.title} →
       </a>
     ) : (
       <TutorialCompletion
@@ -46,7 +49,7 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
 </nav>
 
 <script>
-  // Gating: if the host step contains a Checkpoint AND tutorial is gated,
+  // Gating: if the host step contains a completion item AND tutorial is gated,
   // disable Next until the step is marked complete.
   import { getStore } from "../lib/progress/local";
   const nav = document.querySelector<HTMLElement>(".step-nav");

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/components/mdx/Checkpoint.tsx

@@ -15,34 +15,19 @@ interface Props {
   id?: string;
 }
 
-/**
- * Reads the host tutorial/step from the page-level route marker
- * (<div id="tt-route" data-tutorial-slug=... data-step-slug=...>) that
- * TutorialLayout emits. Looking it up here keeps the Astro wrapper trivial.
- */
-function useRoute() {
-  const [route, setRoute] = useState<{ tutorial: string; step: string } | null>(null);
-  useEffect(() => {
-    const el = document.getElementById("tt-route");
-    if (!el) return;
-    const tutorial = el.dataset.tutorialSlug;
-    const step = el.dataset.stepSlug;
-    if (tutorial && step) setRoute({ tutorial, step });
-  }, []);
-  return route;
-}
-
 export default function Checkpoint({ label, id }: Props) {
   const reactId = useId();
   const checkpointId = id ?? `checkpoint:${reactId}:${label.slice(0, 40)}`;
-  const { state, recordCheckpoint, removeCheckpoint, markStepComplete, markStepIncomplete } =
-    useProgress();
-  const route = useRoute();
+  const { state, recordCheckpoint, removeCheckpoint } = useProgress();
   const done = !!state.checkpoints[checkpointId];
   const aiEnabled = useAiEnabled();
   const [stuck, setStuck] = useState(false);
   const rootRef = useRef<HTMLDivElement>(null);
 
+  useEffect(() => {
+    document.dispatchEvent(new CustomEvent("hz:step-item"));
+  }, []);
+
   // Show the "Stuck?" nudge after STUCK_DELAY_MS of an unchecked
   // checkpoint being on-screen. Resets the timer if the checkpoint
   // scrolls back off screen. Fires once — once shown, stays shown
@@ -75,11 +60,9 @@ export default function Checkpoint({ label, id }: Props) {
   function onToggle() {
     if (done) {
       removeCheckpoint(checkpointId);
-      if (route) markStepIncomplete(route.tutorial, route.step);
       return;
     }
     recordCheckpoint(checkpointId);
-    if (route) markStepComplete(route.tutorial, route.step);
   }
 
   // Family D: inline failure feedback from a submit_verification call.
@@ -91,7 +74,11 @@ export default function Checkpoint({ label, id }: Props) {
   const showFeedback = !done && feedback && !feedback.pass;
 
   return (
-    <div ref={rootRef} className={done ? "checkpoint is-done" : "checkpoint"}>
+    <div
+      ref={rootRef}
+      className={done ? "checkpoint is-done" : "checkpoint"}
+      data-checkpoint-id={checkpointId}
+    >
       <button type="button" onClick={onToggle} aria-pressed={done}>
         <span className="checkpoint-box">{done && <Check size={16} />}</span>
         <span>{label}</span>

package/src/components/mdx/Mermaid.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import { buildMermaidConfig } from "../../lib/mermaid-theme.ts";
 
 interface Props {
   chart: string;
@@ -19,7 +20,7 @@ export default function Mermaid({ chart, id }: Props) {
     (async () => {
       try {
         const mermaid = (await import("mermaid")).default;
-        mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict" });
+        mermaid.initialize(buildMermaidConfig());
         const { svg } = await mermaid.render(
           id ?? `mermaid-${Math.random().toString(36).slice(2)}`,
           chart,

package/src/components/mdx/Quiz.tsx

@@ -1,5 +1,5 @@
 import { Check, X } from "lucide-react";
-import { useId, useState } from "react";
+import { useEffect, useId, useState } from "react";
 import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
 import { useProgress } from "../../lib/progress/useProgress";
 
@@ -25,6 +25,10 @@ export default function Quiz({ question, options, answer, explanation, id, multi
   const correctSet = new Set(Array.isArray(answer) ? answer : [answer]);
   const expectMulti = multi ?? Array.isArray(answer);
 
+  useEffect(() => {
+    document.dispatchEvent(new CustomEvent("hz:step-item"));
+  }, []);
+
   function toggle(i: number) {
     if (submitted) return;
     if (expectMulti) {
@@ -47,7 +51,7 @@ export default function Quiz({ question, options, answer, explanation, id, multi
   }
 
   return (
-    <fieldset className="quiz" disabled={submitted}>
+    <fieldset className="quiz" data-quiz-id={questionId} disabled={submitted}>
       <legend className="quiz-q">{question}</legend>
       <div className="quiz-options">
         {options.map((opt, i) => {

package/src/layouts/BaseLayout.astro

@@ -140,11 +140,33 @@ const socialImageUrl = ogImageUrl ? withBase(ogImageUrl) : undefined;
       />
     )}
     <script>
-      // Render any <pre class="mermaid"> blocks emitted by rehype-mermaid.
-      if (document.querySelector("pre.mermaid")) {
-        import("mermaid").then(({ default: mermaid }) => {
-          mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict" });
-          mermaid.run({ querySelector: "pre.mermaid" });
+      // Render any <pre class="mermaid"> blocks emitted by rehype-mermaid,
+      // themed to match the active site palette (see lib/mermaid-theme).
+      //
+      // We capture each block's source synchronously (this module runs before
+      // the window `load` event) and render explicitly rather than calling
+      // mermaid.run(). mermaid auto-runs on `load` with its default theme, and
+      // on a fast load that race can win and mark nodes data-processed before
+      // our dynamic import resolves — leaving unthemed diagrams. Rendering each
+      // block ourselves from the captured source sidesteps that entirely.
+      const mermaidBlocks = Array.from(document.querySelectorAll("pre.mermaid"));
+      if (mermaidBlocks.length > 0) {
+        const sources = mermaidBlocks.map((el) => el.textContent ?? "");
+        Promise.all([
+          import("mermaid"),
+          import("handzon-core/lib/mermaid-theme.ts"),
+        ]).then(async ([{ default: mermaid }, { buildMermaidConfig }]) => {
+          mermaid.startOnLoad = false;
+          mermaid.initialize(buildMermaidConfig());
+          for (let i = 0; i < mermaidBlocks.length; i++) {
+            try {
+              const { svg } = await mermaid.render(`hz-mermaid-${i}`, sources[i]);
+              mermaidBlocks[i].innerHTML = svg;
+              mermaidBlocks[i].setAttribute("data-processed", "true");
+            } catch (err) {
+              console.error("Mermaid render failed", err);
+            }
+          }
         });
       }
     </script>

package/src/layouts/TutorialLayout.astro

@@ -13,6 +13,7 @@ interface Props {
   currentStep: StepEntry;
   currentStepSlug: string;
   hasCheckpoint?: boolean;
+  hasQuiz?: boolean;
   siteName?: string;
   tagline?: string;
   logoUrl?: string;
@@ -33,6 +34,7 @@ const {
   currentStep,
   currentStepSlug,
   hasCheckpoint = false,
+  hasQuiz = false,
   siteName,
   tagline,
   logoUrl,
@@ -120,6 +122,7 @@ const trackBootstrap =
         currentStepSlug={currentStepSlug}
         gated={tutorial.data.gated}
         hasCheckpoint={hasCheckpoint}
+        hasQuiz={hasQuiz}
         nextTutorial={nextTutorial}
       />
 
@@ -166,10 +169,13 @@ const trackBootstrap =
     // dynamic import("~/...") bypasses Vite's resolver and the browser
     // can't load the module.
     import { getStore } from "../lib/progress/local";
+    import { deriveStepCompletion } from "../lib/progress/stepCompletion";
+    import type { StepKey } from "../lib/progress/types";
     const route = document.getElementById("tt-route");
     if (route) {
       const tutorialSlug = route.dataset.tutorialSlug!;
       const stepSlug = route.dataset.stepSlug!;
+      const stepKey = `${tutorialSlug}/${stepSlug}` as StepKey;
       const tutorialSteps = JSON.parse(
         route.dataset.tutorialSteps ?? "[]",
       ) as string[];
@@ -200,6 +206,34 @@ const trackBootstrap =
         };
       });
 
+      function readCompletionItemIds(selector: string, attr: string) {
+        const activeTrack = document.documentElement.dataset.track;
+        const ids = Array.from(document.querySelectorAll<HTMLElement>(selector))
+          .map((el) => {
+            const trackPanel = el.closest<HTMLElement>("[data-track-panel]");
+            if (activeTrack && trackPanel?.dataset.trackPanel !== activeTrack) return null;
+            return el.dataset[attr];
+          })
+          .filter((id): id is string => !!id);
+        return Array.from(new Set(ids));
+      }
+
+      function recomputeStepCompletion() {
+        const completion = deriveStepCompletion(store.get(), {
+          quizIds: readCompletionItemIds("[data-quiz-id]", "quizId"),
+          checkpointIds: readCompletionItemIds("[data-checkpoint-id]", "checkpointId"),
+        });
+        if (completion === null) return;
+        store.set((s) => {
+          if (s.steps[stepKey] === completion) return s;
+          return { ...s, steps: { ...s.steps, [stepKey]: completion } };
+        });
+      }
+
+      recomputeStepCompletion();
+      document.addEventListener("hz:step-item", recomputeStepCompletion);
+      store.subscribe(recomputeStepCompletion);
+
       // Watch for tutorial completion: once every step in the embedded
       // list flips to "complete", record the "completed" event exactly
       // once. Re-runs on store changes so finishing the last step on a

package/src/lib/icons.ts

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

package/src/lib/mermaid-theme.ts

@@ -0,0 +1,130 @@
+import type { MermaidConfig } from "mermaid";
+
+/**
+ * Browser-only helpers that derive a Mermaid configuration from the active
+ * theme's CSS custom properties. Mermaid bakes colors into the rendered SVG
+ * and runs color math (via khroma) on its theme variables, so we cannot hand
+ * it raw `var(--token)` references or `oklch()` strings. Instead we read the
+ * computed token values and normalize each to a hex/rgb string the renderer
+ * can manipulate, then feed Mermaid's `base` theme so diagrams inherit the
+ * site palette, fonts, and light/dark mode rather than Mermaid's stock theme.
+ */
+
+/**
+ * Normalize any CSS color string (including `oklch()`) to a `#rrggbb` string.
+ * We rasterize one pixel and read the bytes back rather than reading
+ * `ctx.fillStyle`, because Chromium re-serializes `oklch()` as `oklch()` and
+ * Mermaid's color library (khroma) only understands hex/rgb/hsl. Reading the
+ * pixel forces a concrete sRGB value the renderer can manipulate. Returns the
+ * fallback when the value is empty or the browser cannot parse it.
+ */
+function resolveColor(value: string, fallback: string): string {
+  const input = value.trim();
+  if (!input) return fallback;
+  const ctx = document.createElement("canvas").getContext("2d", {
+    willReadFrequently: true,
+  });
+  if (!ctx) return fallback;
+  // Seed with a sentinel; if the input is rejected the pixel stays this value.
+  ctx.fillStyle = "#ff00ff";
+  ctx.fillRect(0, 0, 1, 1);
+  ctx.fillStyle = input;
+  if (ctx.fillStyle === "#ff00ff" && input.toLowerCase() !== "#ff00ff") {
+    return fallback;
+  }
+  ctx.fillRect(0, 0, 1, 1);
+  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+  const hex = (n: number) => n.toString(16).padStart(2, "0");
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+/** Relative luminance (0–1) of a `#rrggbb` color, for dark-mode detection. */
+function luminance(hex: string): number {
+  const m = /^#([0-9a-f]{6})$/i.exec(hex);
+  if (!m) return 0;
+  const int = parseInt(m[1], 16);
+  const channel = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  const r = channel((int >> 16) & 0xff);
+  const g = channel((int >> 8) & 0xff);
+  const b = channel(int & 0xff);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** Build a Mermaid config from the document's active theme tokens. */
+export function buildMermaidConfig(): MermaidConfig {
+  const cs = getComputedStyle(document.documentElement);
+  const token = (name: string) => cs.getPropertyValue(name).trim();
+  const color = (name: string, fallback: string) => resolveColor(token(name), fallback);
+
+  const bg = color("--color-bg", "#0a0a0a");
+  const surface = color("--color-surface", "#16181d");
+  const surface2 = color("--color-surface-2", surface);
+  const fg = color("--color-fg", "#f5f5f5");
+  const muted = color("--color-muted", "#9ca3af");
+  const border = color("--color-border", "#3a3a3a");
+  const borderStrong = color("--color-border-strong", border);
+  const accent = color("--color-accent", "#8b5cf6");
+  const accentFg = color("--color-accent-fg", "#ffffff");
+
+  const fontFamily = token("--font-sans") || "ui-sans-serif, system-ui, sans-serif";
+  const darkMode = luminance(bg) < 0.5;
+
+  return {
+    startOnLoad: false,
+    securityLevel: "strict",
+    theme: "base",
+    fontFamily,
+    themeVariables: {
+      darkMode,
+      background: surface,
+      fontFamily,
+      // Nodes
+      primaryColor: surface2,
+      primaryTextColor: fg,
+      primaryBorderColor: accent,
+      secondaryColor: surface,
+      secondaryTextColor: fg,
+      secondaryBorderColor: border,
+      tertiaryColor: surface,
+      tertiaryTextColor: fg,
+      tertiaryBorderColor: border,
+      mainBkg: surface2,
+      nodeBorder: accent,
+      nodeTextColor: fg,
+      // Edges + general text
+      lineColor: borderStrong,
+      textColor: fg,
+      titleColor: fg,
+      edgeLabelBackground: surface,
+      // Clusters / subgraphs
+      clusterBkg: surface,
+      clusterBorder: border,
+      // Notes
+      noteBkgColor: surface2,
+      noteTextColor: fg,
+      noteBorderColor: accent,
+      // Sequence diagrams
+      actorBkg: surface2,
+      actorBorder: accent,
+      actorTextColor: fg,
+      actorLineColor: borderStrong,
+      signalColor: fg,
+      signalTextColor: fg,
+      labelBoxBkgColor: surface2,
+      labelBoxBorderColor: border,
+      labelTextColor: fg,
+      loopTextColor: fg,
+      activationBkgColor: accent,
+      activationBorderColor: accent,
+      // Accent emphasis
+      altBackground: surface,
+      errorBkgColor: surface2,
+      errorTextColor: muted,
+      // Keep the accent legible where Mermaid fills with it.
+      primaryColorText: accentFg,
+    },
+  };
+}

package/src/lib/progress/stepCompletion.ts

@@ -0,0 +1,20 @@
+import type { ProgressState } from "./types";
+
+export interface StepCompletionItems {
+  quizIds: string[];
+  checkpointIds: string[];
+}
+
+export type DerivedStepCompletion = "complete" | "incomplete" | null;
+
+export function deriveStepCompletion(
+  state: ProgressState,
+  { quizIds, checkpointIds }: StepCompletionItems,
+): DerivedStepCompletion {
+  if (quizIds.length === 0 && checkpointIds.length === 0) return null;
+
+  const allQuizzesCorrect = quizIds.every((id) => state.quizzes[id]?.correct === true);
+  const allCheckpointsDone = checkpointIds.every((id) => !!state.checkpoints[id]);
+
+  return allQuizzesCorrect && allCheckpointsDone ? "complete" : "incomplete";
+}

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/src/pages/TutorialStep.astro

@@ -52,6 +52,7 @@ const { Content } = await render(currentStep);
 
 const components = mdxComponents();
 const hasCheckpoint = currentStep.body?.includes("<Checkpoint") ?? false;
+const hasQuiz = currentStep.body?.includes("<Quiz") ?? false;
 const nextTutorial = tutorial.data.nextTutorial
   ? await getTutorialBySlug(tutorial.data.nextTutorial)
   : undefined;
@@ -76,6 +77,7 @@ const initialContext = buildContext({
   currentStep={currentStep}
   currentStepSlug={stepSlug}
   hasCheckpoint={hasCheckpoint}
+  hasQuiz={hasQuiz}
   siteName={siteName}
   tagline={tagline}
   logoUrl={logoUrl}

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:

package/styles/components/mermaid.css

@@ -1,16 +1,31 @@
-/* Mermaid */
-.mermaid-wrap {
+/* Mermaid — diagram colors come from JS (lib/mermaid-theme) so the SVG
+ * inherits the active palette; this only frames the rendered diagram so it
+ * reads as part of the page rather than a floating image. */
+.mermaid-wrap,
+pre.mermaid {
   margin: 1.25rem 0;
   padding: 1rem;
   background: var(--color-surface);
+  border: var(--border-default, 1px) solid var(--color-border);
+  border-radius: var(--radius-md, 0);
   display: grid;
   place-items: center;
-  border-radius: 0;
   min-height: var(--mermaid-min-height, 14rem);
+  overflow-x: auto;
 }
-.mermaid-wrap :global(svg) { max-width: 100%; height: auto; }
-pre.mermaid {
-  min-height: var(--mermaid-min-height, 14rem);
+/* Before the client script runs, the raw fenced source sits inside
+ * pre.mermaid; keep it from flashing as monospace text. */
+pre.mermaid:not([data-processed]) {
+  color: transparent;
+}
+.mermaid-wrap :global(svg),
+pre.mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+.mermaid-wrap :global(svg) text,
+pre.mermaid svg text {
+  font-family: var(--font-sans);
 }
 .mermaid-error {
   padding: 0.75rem;