handzon-core 0.6.2 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.6.2",
+  "version": "0.7.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/collections.ts

@@ -121,6 +121,11 @@ export function tutorialsSchema({ image }: { image: () => import("astro/zod").Zo
     estimatedDuration: z.string().optional(),
     prerequisites: z.array(z.string()).default([]),
     nextTutorial: z.string().optional(),
+    // TODO(handzon): `cover` and `icon` are accepted by the schema for
+    // forward compatibility, but no page currently renders them
+    // (Home cards, TutorialLanding, OG meta all ignore them). Wire them
+    // up in TutorialCard and BaseLayout's OG tags before promoting
+    // cover art in author-facing docs and skills.
     cover: image().optional(),
     icon: z.union([z.string(), image()]).optional(),
     steps: z.array(z.string()).optional(),

package/src/components/ai/ChatButton.tsx

@@ -1,7 +1,7 @@
 import { Sparkles } from "lucide-react";
 import { useState } from "react";
-import type { AiConfig } from "../../types/ai";
 import type { AssistantContext } from "../../lib/ai/context";
+import type { AiConfig } from "../../types/ai";
 import ChatPanel from "./ChatPanel";
 
 interface Props {

package/src/components/ai/ChatPanel.tsx

@@ -3,9 +3,9 @@ import { KeyRound, Send, Settings, Sparkles, Trash2, X } from "lucide-react";
 import { useEffect, useRef, useState } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
-import type { AiConfig } from "../../types/ai";
 import { type ChatMessage, clearLearnerKey, loadLearnerKey, streamChat } from "../../lib/ai/client";
 import type { AssistantContext } from "../../lib/ai/context";
+import type { AiConfig } from "../../types/ai";
 import ByokSetup from "./ByokSetup";
 
 interface Props {
@@ -45,6 +45,11 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
 
   // Keep the latest message in view as chunks stream in (and on every
   // send / clear). Without this, long responses scroll out of frame.
+  // The deps aren't read inside the effect — they're triggers, so the
+  // effect re-runs when a new chunk arrives or streaming flips. Biome's
+  // exhaustive-deps lint would have us remove them; that would break
+  // the autoscroll. Keep the suppression scoped to this single effect.
+  // biome-ignore lint/correctness/useExhaustiveDependencies: messages + streaming are intentional triggers
   useEffect(() => {
     listRef.current?.scrollTo({ top: listRef.current.scrollHeight });
   }, [messages, streaming]);
@@ -162,8 +167,8 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
                 <KeyRound size={22} aria-hidden="true" />
                 <h3>API key required</h3>
                 <p>
-                  {config.name} needs an API key to answer questions. Add one to get started —
-                  it's stored in this browser only.
+                  {config.name} needs an API key to answer questions. Add one to get started — it's
+                  stored in this browser only.
                 </p>
                 <button type="button" onClick={() => setByokOpen(true)}>
                   Set up key
@@ -197,7 +202,7 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
                   <div className="chat-msg chat-msg-assistant">
                     <span className="chat-role">{config.name}</span>
                     <div className="chat-content">
-                      <span className="chat-thinking" aria-label="Thinking">
+                      <span className="chat-thinking" role="status" aria-label="Thinking">
                         <span /> <span /> <span />
                       </span>
                     </div>

package/src/components/auth/UserMenu.tsx

@@ -53,7 +53,7 @@ export default function UserMenu() {
         }
         const sess = (await sessRes.json()) as Session | null;
         const csrf = (await csrfRes.json()) as { csrfToken?: string } | null;
-        setSession(sess && sess.user ? sess : null);
+        setSession(sess?.user ? sess : null);
         setCsrfToken(csrf?.csrfToken ?? null);
       } catch {
         if (!cancelled) {
@@ -79,9 +79,9 @@ export default function UserMenu() {
   // long-form context.
   const fullLabel = user?.name ?? user?.email ?? "Signed in";
   const displayName = user
-    ? (user.name ? user.name.trim().split(/\s+/)[0] : null) ??
+    ? ((user.name ? user.name.trim().split(/\s+/)[0] : null) ??
       (user.email ? user.email.split("@")[0] : null) ??
-      "Signed in"
+      "Signed in")
     : "";
 
   return (
@@ -95,7 +95,9 @@ export default function UserMenu() {
               {fullLabel.trim().charAt(0).toUpperCase()}
             </span>
           )}
-          <span className="um-name" title={fullLabel}>{displayName}</span>
+          <span className="um-name" title={fullLabel}>
+            {displayName}
+          </span>
           <form method="post" action="/api/auth/signout">
             <input type="hidden" name="csrfToken" value={csrfToken} />
             <input type="hidden" name="callbackUrl" value={callbackUrl} />

package/src/components/home/ActiveFilterChips.tsx

@@ -40,6 +40,7 @@ export default function ActiveFilterChips({
   }
 
   return (
+    // biome-ignore lint/a11y/useSemanticElements: <fieldset> requires <legend> and carries form-control semantics; this row groups filter-removal buttons.
     <div className="active-filters" role="group" aria-label="Active filters">
       {q && (
         <button
@@ -79,11 +80,7 @@ export default function ActiveFilterChips({
           <X size={12} aria-hidden="true" />
         </button>
       ))}
-      <button
-        type="button"
-        className="active-filter-clear"
-        onClick={onClearAll}
-      >
+      <button type="button" className="active-filter-clear" onClick={onClearAll}>
         Clear all
       </button>
     </div>

package/src/components/home/FilterBar.tsx

@@ -21,7 +21,12 @@ interface FilterState {
 
 function parseCsv(value: string | null): Set<string> {
   if (!value) return new Set();
-  return new Set(value.split(",").map((s) => s.trim()).filter(Boolean));
+  return new Set(
+    value
+      .split(",")
+      .map((s) => s.trim())
+      .filter(Boolean),
+  );
 }
 
 function readUrlState(): FilterState {
@@ -61,11 +66,9 @@ function applyFilters(state: FilterState) {
   let visible = 0;
   cards.forEach((card) => {
     const matchesQ = !q || card.dataset.search!.includes(q);
-    const matchesLevel =
-      state.levels.size === 0 || state.levels.has(card.dataset.difficulty ?? "");
+    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 matchesTag = state.tags.size === 0 || cardTags.some((t) => state.tags.has(t));
     const show = matchesQ && matchesLevel && matchesTag;
     if (show) {
       card.removeAttribute("data-filter-hidden");
@@ -95,12 +98,7 @@ function applyFilters(state: FilterState) {
   window.dispatchEvent(new CustomEvent("hz:filter-changed"));
 }
 
-export default function FilterBar({
-  difficulties,
-  tags,
-  difficultyCounts,
-  tagCounts,
-}: Props) {
+export default function FilterBar({ difficulties, tags, difficultyCounts, tagCounts }: Props) {
   const [state, setState] = useState<FilterState>(readUrlState);
 
   useEffect(() => {

package/src/components/home/Pagination.tsx

@@ -19,9 +19,7 @@ interface Props {
  */
 function applyPagination(page: number, pageSize: number): number {
   const visibleByFilter = Array.from(
-    document.querySelectorAll<HTMLElement>(
-      "[data-search]:not([data-filter-hidden])",
-    ),
+    document.querySelectorAll<HTMLElement>("[data-search]:not([data-filter-hidden])"),
   );
   const start = (page - 1) * pageSize;
   const end = start + pageSize;

package/src/components/home/ResumeRail.tsx

@@ -44,7 +44,9 @@ export default function ResumeRail({ tutorials }: Props) {
       <span className="rr-prefix">Continue</span>
       <span className="rr-title">{mostRecent.title}</span>
       <span className="rr-step">/ {mostRecent.step}</span>
-      <span className="rr-arrow" aria-hidden="true">→</span>
+      <span className="rr-arrow" aria-hidden="true">
+        →
+      </span>
     </a>
   );
 }

package/src/components/mdx/Checkpoint.tsx

@@ -27,12 +27,17 @@ function useRoute() {
 export default function Checkpoint({ label, id }: Props) {
   const reactId = useId();
   const checkpointId = id ?? `checkpoint:${reactId}:${label.slice(0, 40)}`;
-  const { state, recordCheckpoint, markStepComplete } = useProgress();
+  const { state, recordCheckpoint, removeCheckpoint, markStepComplete, markStepIncomplete } =
+    useProgress();
   const route = useRoute();
   const done = !!state.checkpoints[checkpointId];
 
   function onToggle() {
-    if (done) return;
+    if (done) {
+      removeCheckpoint(checkpointId);
+      if (route) markStepIncomplete(route.tutorial, route.step);
+      return;
+    }
     recordCheckpoint(checkpointId);
     if (route) markStepComplete(route.tutorial, route.step);
   }

package/src/components/ui/Dropdown.tsx

@@ -65,21 +65,13 @@ export default function Dropdown<V extends string = string>({
         </Select.Trigger>
 
         <Select.Portal>
-          <Select.Content
-            className="hz-dd-content"
-            position="popper"
-            sideOffset={6}
-          >
+          <Select.Content className="hz-dd-content" position="popper" sideOffset={6}>
             <Select.ScrollUpButton className="hz-dd-scroll">
               <ChevronUp size={14} aria-hidden="true" />
             </Select.ScrollUpButton>
             <Select.Viewport className="hz-dd-viewport">
               {options.map((opt) => (
-                <Select.Item
-                  key={opt.value}
-                  value={opt.value}
-                  className="hz-dd-item"
-                >
+                <Select.Item key={opt.value} value={opt.value} className="hz-dd-item">
                   {opt.icon && <span className="hz-dd-icon">{opt.icon}</span>}
                   <Select.ItemText>{opt.label}</Select.ItemText>
                   <Select.ItemIndicator className="hz-dd-check">

package/src/components/ui/MultiSelect.tsx

@@ -1,13 +1,6 @@
 import * as Popover from "@radix-ui/react-popover";
 import { Check, ChevronDown, Search, X } from "lucide-react";
-import {
-  type KeyboardEvent,
-  type ReactNode,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
+import { type KeyboardEvent, type ReactNode, useEffect, useMemo, useRef, useState } from "react";
 
 export interface MultiSelectOption {
   value: string;
@@ -64,10 +57,7 @@ export default function MultiSelect({
   // Sort by count desc so "weighty" facets bubble up. Stable
   // alphabetical secondary sort keeps neighbours predictable.
   const sorted = useMemo(
-    () =>
-      [...options].sort(
-        (a, b) => b.count - a.count || a.label.localeCompare(b.label),
-      ),
+    () => [...options].sort((a, b) => b.count - a.count || a.label.localeCompare(b.label)),
     [options],
   );
 
@@ -158,11 +148,7 @@ export default function MultiSelect({
         </button>
       </Popover.Trigger>
       <Popover.Portal>
-        <Popover.Content
-          className="hz-ms-content"
-          align="start"
-          sideOffset={6}
-        >
+        <Popover.Content className="hz-ms-content" align="start" sideOffset={6}>
           {searchable && (
             <label className="hz-ms-search">
               <Search size={14} aria-hidden="true" />

package/src/index.ts

@@ -8,48 +8,43 @@
  * and types.
  */
 
+// AI client (browser-side BYOK + streaming chat to handzon-ai).
+export {
+  type ChatMessage,
+  clearLearnerKey,
+  loadLearnerKey,
+  saveLearnerKey,
+  streamChat,
+} from "./lib/ai/client.ts";
+export { type AssistantContext, buildContext } from "./lib/ai/context.ts";
 // Content collection helpers (built on top of astro:content).
 export {
-  parseStepId,
-  getTutorials,
-  getTutorialBySlug,
-  getStepsForTutorial,
   getStep,
+  getStepsForTutorial,
+  getTutorialBySlug,
+  getTutorials,
+  parseStepId,
+  type StepEntry,
   sumDurations,
   type TutorialEntry,
-  type StepEntry,
 } from "./lib/content.ts";
-
 // MDX component map used by .astro pages rendering tutorial content.
 export { mdxComponents } from "./lib/mdx-components.ts";
-
-// Rehype plugin that lets Mermaid code fences round-trip as <pre class="mermaid">.
-export { default as rehypeMermaidPassthrough } from "./lib/rehype-mermaid-passthrough.ts";
-
-// AI client (browser-side BYOK + streaming chat to handzon-ai).
-export {
-  streamChat,
-  loadLearnerKey,
-  saveLearnerKey,
-  clearLearnerKey,
-  type ChatMessage,
-} from "./lib/ai/client.ts";
-
-export { buildContext, type AssistantContext } from "./lib/ai/context.ts";
-
 // Progress store (localStorage + optional server sync).
 export { getStore } from "./lib/progress/local.ts";
-export {
-  useProgress,
-  useProgressAfterMount,
-} from "./lib/progress/useProgress.ts";
 export {
   emptyState,
-  type ProgressState,
-  type StepKey,
   type LastVisitedEntry,
+  type ProgressState,
   type ProgressStore,
+  type StepKey,
 } from "./lib/progress/types.ts";
+export {
+  useProgress,
+  useProgressAfterMount,
+} from "./lib/progress/useProgress.ts";
+// Rehype plugin that lets Mermaid code fences round-trip as <pre class="mermaid">.
+export { default as rehypeMermaidPassthrough } from "./lib/rehype-mermaid-passthrough.ts";
 
 // AI config type (consumers provide concrete values; framework consumes shape).
 export type { AiConfig } from "./types/ai.ts";

package/src/lib/progress/remote.ts

@@ -65,6 +65,13 @@ function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
       out.push({ kind: "checkpoint", scope: "global", key: id, value });
     }
   }
+  // Emit deletions so the server tombstones unchecked checkpoints; without
+  // this the next snapshot fetch would resurrect them from the DB.
+  for (const id of Object.keys(prev.checkpoints)) {
+    if (!next.checkpoints[id]) {
+      out.push({ kind: "checkpoint", scope: "global", key: id, value: null });
+    }
+  }
   for (const [k, value] of Object.entries(next.prefs)) {
     if ((prev.prefs as Record<string, unknown>)[k] !== value) {
       out.push({ kind: "pref", scope: "global", key: k, value });
@@ -150,6 +157,7 @@ export function createRemoteStore(): ProgressStore {
           } else if (e.kind === "quiz") {
             merged.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
           } else if (e.kind === "checkpoint") {
+            if (e.value == null) continue;
             merged.checkpoints[e.key] = e.value as ProgressState["checkpoints"][string];
           } else if (e.kind === "pref") {
             (merged.prefs as Record<string, unknown>)[e.key] = e.value;

package/src/lib/progress/useProgress.ts

@@ -8,6 +8,7 @@ interface ProgressApi {
   markStepIncomplete: (tutorial: string, step: string) => void;
   recordQuiz: (questionId: string, chosen: number[], correct: boolean) => void;
   recordCheckpoint: (checkpointId: string) => void;
+  removeCheckpoint: (checkpointId: string) => void;
   setPref: <K extends keyof ProgressState["prefs"]>(
     key: K,
     value: ProgressState["prefs"][K],
@@ -56,6 +57,13 @@ export function useProgress(): ProgressApi {
           ...s,
           checkpoints: { ...s.checkpoints, [checkpointId]: { ts: Date.now() } },
         })),
+      removeCheckpoint: (checkpointId: string) =>
+        store.set((s) => {
+          if (!s.checkpoints[checkpointId]) return s;
+          const next = { ...s.checkpoints };
+          delete next[checkpointId];
+          return { ...s, checkpoints: next };
+        }),
       setPref: <K extends keyof ProgressState["prefs"]>(key: K, value: ProgressState["prefs"][K]) =>
         store.set((s) => ({ ...s, prefs: { ...s.prefs, [key]: value } })),
       setLastVisited: (tutorial: string, step: string) =>

package/src/pages/paths.ts

@@ -5,8 +5,9 @@
  *   export const getStaticPaths = getTutorialLandingPaths;
  *   export const getStaticPaths = getTutorialStepPaths;
  */
-import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
+
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
+import { getStepsForTutorial, getTutorials, parseStepId } from "../lib/content.ts";
 
 export async function getTutorialLandingPaths() {
   const tutorials = await getTutorials();

package/src/server/auth/config.ts

@@ -10,8 +10,9 @@
  * GitHub is the only provider in 0.2; email/password and others are
  * out of scope (see plan: github-auth_d52529d5).
  */
-import { DrizzleAdapter } from "@auth/drizzle-adapter";
+
 import GitHub from "@auth/core/providers/github";
+import { DrizzleAdapter } from "@auth/drizzle-adapter";
 import { defineConfig } from "auth-astro";
 import { accounts, sessions, users, verificationTokens } from "./schema.ts";
 

package/src/server/auth/schema.ts

@@ -6,14 +6,7 @@
  * The `learners` row that maps a signed-in user to local progress lives
  * in `../db/schema.ts` — it adds a nullable `user_id` FK to `users` here.
  */
-import {
-  integer,
-  pgTable,
-  primaryKey,
-  text,
-  timestamp,
-  uuid,
-} from "drizzle-orm/pg-core";
+import { integer, pgTable, primaryKey, text, timestamp, uuid } from "drizzle-orm/pg-core";
 
 export const users = pgTable("users", {
   id: uuid("id").primaryKey().defaultRandom(),

package/src/server/auth.ts

@@ -61,11 +61,7 @@ export async function getOrCreateLearner(
   // Anonymous path — unchanged from pre-auth behaviour.
   let deviceId = cookies.get(COOKIE)?.value;
   if (deviceId) {
-    const found = await db
-      .select()
-      .from(learners)
-      .where(eq(learners.deviceId, deviceId))
-      .limit(1);
+    const found = await db.select().from(learners).where(eq(learners.deviceId, deviceId)).limit(1);
     if (found[0]) return { id: found[0].id, deviceId };
   }
   deviceId = randomDeviceId();

package/src/server/db/schema.ts

@@ -13,7 +13,7 @@ import { users } from "../auth/schema.ts";
 
 // Re-export the Auth.js tables so consumers (and drizzle-kit) see one
 // schema barrel.
-export { users, accounts, sessions, verificationTokens } from "../auth/schema.ts";
+export { accounts, sessions, users, verificationTokens } from "../auth/schema.ts";
 
 export const learners = pgTable(
   "learners",

package/src/server/handlers/progress.ts

@@ -1,5 +1,5 @@
 import type { APIRoute } from "astro";
-import { eq, sql } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { z } from "zod";
 import { getOrCreateLearner } from "../auth.ts";
 import { getDb } from "../db/client.ts";
@@ -61,30 +61,53 @@ export const POST: APIRoute = async ({ cookies, request }) => {
   const learner = await getOrCreateLearner(cookies, request);
   const db = getDb();
   const now = new Date();
-  const rows = parsed.map((b) => ({
-    learnerId: learner.id,
-    kind: b.kind,
-    scope: b.scope,
-    key: b.key,
-    value: b.value,
-    updatedAt: now,
-  }));
-  await db
-    .insert(progressEntries)
-    .values(rows)
-    .onConflictDoUpdate({
-      target: [
-        progressEntries.learnerId,
-        progressEntries.kind,
-        progressEntries.scope,
-        progressEntries.key,
-      ],
-      set: {
-        // `excluded` is the row Postgres would have inserted — without
-        // this the SET was a no-op (`value = progress_entries.value`).
-        value: sql`excluded.value`,
-        updatedAt: sql`excluded.updated_at`,
-      },
-    });
-  return json({ written: rows.length });
+
+  // `value: null` is the tombstone signal for "this entry was undone"
+  // (e.g. unchecking a checkpoint). The `value` column is NOT NULL, so
+  // we DELETE these rows instead of upserting them.
+  const deletes = parsed.filter((b) => b.value === null);
+  const upserts = parsed.filter((b) => b.value !== null);
+
+  for (const d of deletes) {
+    await db
+      .delete(progressEntries)
+      .where(
+        and(
+          eq(progressEntries.learnerId, learner.id),
+          eq(progressEntries.kind, d.kind),
+          eq(progressEntries.scope, d.scope),
+          eq(progressEntries.key, d.key),
+        ),
+      );
+  }
+
+  if (upserts.length > 0) {
+    const rows = upserts.map((b) => ({
+      learnerId: learner.id,
+      kind: b.kind,
+      scope: b.scope,
+      key: b.key,
+      value: b.value,
+      updatedAt: now,
+    }));
+    await db
+      .insert(progressEntries)
+      .values(rows)
+      .onConflictDoUpdate({
+        target: [
+          progressEntries.learnerId,
+          progressEntries.kind,
+          progressEntries.scope,
+          progressEntries.key,
+        ],
+        set: {
+          // `excluded` is the row Postgres would have inserted — without
+          // this the SET was a no-op (`value = progress_entries.value`).
+          value: sql`excluded.value`,
+          updatedAt: sql`excluded.updated_at`,
+        },
+      });
+  }
+
+  return json({ written: parsed.length });
 };

package/src/server/handlers/tutorialStats.ts

@@ -29,9 +29,12 @@ let cache: CacheEntry | null = null;
  */
 export const GET: APIRoute = async () => {
   if (!process.env.DATABASE_URL) {
-    return json({ stats: [] satisfies TutorialStat[] }, {
-      headers: { "Cache-Control": "public, max-age=60" },
-    });
+    return json(
+      { stats: [] satisfies TutorialStat[] },
+      {
+        headers: { "Cache-Control": "public, max-age=60" },
+      },
+    );
   }
   const now = Date.now();
   if (cache && cache.expiresAt > now) {