handzon-core 0.6.0

package/src/lib/ai/context.ts

@@ -0,0 +1,97 @@
+import type { StepEntry, TutorialEntry } from "../content";
+import { parseStepId } from "../content";
+import type { ProgressState } from "../progress/types";
+
+export interface AssistantContext {
+  tutorial: {
+    slug: string;
+    title: string;
+    description: string;
+    difficulty: string;
+    tags: string[];
+  };
+  outline: Array<{ slug: string; title: string; completed: boolean; current: boolean }>;
+  currentStep: {
+    slug: string;
+    title: string;
+    source: string;
+  };
+  priorSteps: Array<{ slug: string; title: string; source: string }>;
+  progress: {
+    completed: string[];
+    quizzes: Array<{ id: string; correct: boolean }>;
+    checkpoints: string[];
+  };
+  references: Array<{ source: string; content: string }>;
+}
+
+interface BuildOptions {
+  tutorial: TutorialEntry;
+  steps: StepEntry[];
+  currentStep: StepEntry;
+  progress: ProgressState;
+  references?: Array<{ source: string; content: string }>;
+  includeFutureSteps?: boolean;
+}
+
+/**
+ * Assemble the per-request context. Prior-step bodies are inlined verbatim
+ * so the assistant has the same view of the work as the learner. Future
+ * steps are excluded by default to avoid spoilers.
+ */
+export function buildContext({
+  tutorial,
+  steps,
+  currentStep,
+  progress,
+  references = [],
+  includeFutureSteps = false,
+}: BuildOptions): AssistantContext {
+  const slug = tutorial.id;
+  const currentIdx = steps.findIndex((s) => s.id === currentStep.id);
+  const { stepSlug: currentSlug } = parseStepId(currentStep.id);
+
+  const outline = steps.map((s) => {
+    const { stepSlug } = parseStepId(s.id);
+    return {
+      slug: stepSlug,
+      title: s.data.title,
+      completed: progress.steps[`${slug}/${stepSlug}`] === "complete",
+      current: stepSlug === currentSlug,
+    };
+  });
+
+  const priorSteps = steps
+    .slice(0, includeFutureSteps ? steps.length : currentIdx)
+    .filter((s) => s.id !== currentStep.id)
+    .map((s) => ({
+      slug: parseStepId(s.id).stepSlug,
+      title: s.data.title,
+      source: s.body ?? "",
+    }));
+
+  return {
+    tutorial: {
+      slug,
+      title: tutorial.data.title,
+      description: tutorial.data.description,
+      difficulty: tutorial.data.difficulty,
+      tags: tutorial.data.tags,
+    },
+    outline,
+    currentStep: {
+      slug: currentSlug,
+      title: currentStep.data.title,
+      source: currentStep.body ?? "",
+    },
+    priorSteps,
+    progress: {
+      completed: Object.entries(progress.steps)
+        .filter(([k, v]) => k.startsWith(`${slug}/`) && v === "complete")
+        .map(([k]) => k.split("/").slice(1).join("/")),
+      quizzes: Object.entries(progress.quizzes).map(([id, q]) => ({ id, correct: q.correct })),
+      checkpoints: Object.keys(progress.checkpoints),
+    },
+    references,
+  };
+}

package/src/lib/content.ts

@@ -0,0 +1,73 @@
+import { type CollectionEntry, getCollection } from "astro:content";
+
+export type TutorialEntry = CollectionEntry<"tutorials">;
+export type StepEntry = CollectionEntry<"steps">;
+
+const STEP_PREFIX = /^(\d+)-(.+)$/;
+
+/**
+ * Parse a step's collection id ("react-todo/01-setup") into its parts.
+ * Tutorial slug is the verbatim first path segment; step ordering comes
+ * from the file's numeric prefix.
+ */
+export function parseStepId(id: string): { tutorialSlug: string; stepSlug: string; order: number } {
+  const slash = id.indexOf("/");
+  if (slash < 0) {
+    throw new Error(`Unrecognized step id: ${id}`);
+  }
+  const tutorialSlug = id.slice(0, slash);
+  const stepFile = id.slice(slash + 1);
+  if (!tutorialSlug || !stepFile) {
+    throw new Error(`Unrecognized step id: ${id}`);
+  }
+  const stepMatch = STEP_PREFIX.exec(stepFile);
+  return {
+    tutorialSlug,
+    stepSlug: stepMatch?.[2] ?? stepFile,
+    order: stepMatch?.[1] ? Number.parseInt(stepMatch[1], 10) : 0,
+  };
+}
+
+export async function getTutorials(): Promise<TutorialEntry[]> {
+  const all = await getCollection("tutorials");
+  return all.sort((a, b) => {
+    const ao = (a.data as { order?: number }).order ?? 0;
+    const bo = (b.data as { order?: number }).order ?? 0;
+    return ao - bo;
+  });
+}
+
+export async function getTutorialBySlug(slug: string): Promise<TutorialEntry | undefined> {
+  const all = await getCollection("tutorials");
+  return all.find((t) => t.id === slug);
+}
+
+export async function getStepsForTutorial(slug: string): Promise<StepEntry[]> {
+  const all = await getCollection("steps");
+  return all
+    .filter((s) => parseStepId(s.id).tutorialSlug === slug)
+    .sort((a, b) => parseStepId(a.id).order - parseStepId(b.id).order);
+}
+
+export async function getStep(
+  tutorialSlug: string,
+  stepSlug: string,
+): Promise<StepEntry | undefined> {
+  const steps = await getStepsForTutorial(tutorialSlug);
+  return steps.find((s) => parseStepId(s.id).stepSlug === stepSlug);
+}
+
+/**
+ * "5 min" + "3 min" → "8 min". Falls back to undefined if any step is missing duration.
+ */
+export function sumDurations(steps: StepEntry[]): string | undefined {
+  let total = 0;
+  for (const step of steps) {
+    const dur = step.data.duration;
+    if (!dur) return undefined;
+    const match = /(\d+)\s*min/i.exec(dur);
+    if (!match?.[1]) return undefined;
+    total += Number.parseInt(match[1], 10);
+  }
+  return total > 0 ? `${total} min` : undefined;
+}

package/src/lib/mdx-components.ts

@@ -0,0 +1,47 @@
+import Callout from "../components/mdx/Callout.astro";
+import Checkpoint from "../components/mdx/Checkpoint.astro";
+import Diff from "../components/mdx/Diff.astro";
+import Download from "../components/mdx/Download.astro";
+import Embed from "../components/mdx/Embed.astro";
+import File from "../components/mdx/File.astro";
+import FileTree from "../components/mdx/FileTree.astro";
+import Hint from "../components/mdx/Hint.astro";
+import Mermaid from "../components/mdx/Mermaid.astro";
+import Playground from "../components/mdx/Playground.astro";
+import Quiz from "../components/mdx/Quiz.astro";
+import Recap from "../components/mdx/Recap.astro";
+import Reveal from "../components/mdx/Reveal.astro";
+import StepCmp from "../components/mdx/Step.astro";
+import StepsCmp from "../components/mdx/Steps.astro";
+import Tab from "../components/mdx/Tab.astro";
+import Tabs from "../components/mdx/Tabs.astro";
+import Terminal from "../components/mdx/Terminal.astro";
+
+/**
+ * The components map passed to <Content components={...} />. Every React
+ * island has an .astro wrapper that pre-binds the hydration directive
+ * (Astro's MDX render call can't apply client:* itself; the wrapper does).
+ * Checkpoint reads its host route from a DOM marker, not props.
+ */
+export function mdxComponents() {
+  return {
+    Callout,
+    Hint,
+    Steps: StepsCmp,
+    Step: StepCmp,
+    File,
+    Recap,
+    Embed,
+    Download,
+    Tabs,
+    Tab,
+    FileTree,
+    Reveal,
+    Terminal,
+    Mermaid,
+    Diff,
+    Quiz,
+    Checkpoint,
+    Playground,
+  };
+}

package/src/lib/progress/local.ts

@@ -0,0 +1,89 @@
+import { createRemoteStore } from "./remote";
+import {
+  CHANNEL_NAME,
+  emptyState,
+  type ProgressState,
+  type ProgressStore,
+  STORAGE_KEY,
+} from "./types";
+
+const isBrowser = typeof window !== "undefined";
+
+function readStorage(): ProgressState {
+  if (!isBrowser) return emptyState();
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return emptyState();
+    const parsed = JSON.parse(raw) as Partial<ProgressState>;
+    return { ...emptyState(), ...parsed };
+  } catch {
+    return emptyState();
+  }
+}
+
+function writeStorage(state: ProgressState): void {
+  if (!isBrowser) return;
+  try {
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+  } catch {
+    // quota or private mode — silently swallow
+  }
+}
+
+export function createLocalStore(): ProgressStore {
+  let state: ProgressState = readStorage();
+  const subscribers = new Set<(s: ProgressState) => void>();
+  let channel: BroadcastChannel | null = null;
+
+  if (isBrowser && typeof BroadcastChannel !== "undefined") {
+    channel = new BroadcastChannel(CHANNEL_NAME);
+    channel.addEventListener("message", (event: MessageEvent) => {
+      if (event.data?.type === "set") {
+        state = event.data.state as ProgressState;
+        for (const fn of subscribers) fn(state);
+      }
+    });
+  }
+
+  if (isBrowser) {
+    window.addEventListener("storage", (e) => {
+      if (e.key !== STORAGE_KEY) return;
+      state = readStorage();
+      for (const fn of subscribers) fn(state);
+    });
+  }
+
+  return {
+    get: () => state,
+    set: (updater) => {
+      state = updater(state);
+      writeStorage(state);
+      for (const fn of subscribers) fn(state);
+      channel?.postMessage({ type: "set", state });
+    },
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+  };
+}
+
+let singleton: ProgressStore | null = null;
+
+/**
+ * Pick the right store based on PUBLIC_PROGRESS_BACKEND. Both stores
+ * are statically imported because dynamic `require()` doesn't exist in
+ * the browser ESM bundle (this file ships to the client) and a dynamic
+ * `import()` would force every call site to become async.
+ */
+export function getStore(): ProgressStore {
+  if (singleton) return singleton;
+  if (isBrowser && import.meta.env.PUBLIC_PROGRESS_BACKEND === "remote") {
+    singleton = createRemoteStore();
+  } else {
+    singleton = createLocalStore();
+  }
+  return singleton;
+}

package/src/lib/progress/remote.ts

@@ -0,0 +1,199 @@
+import {
+  CHANNEL_NAME,
+  emptyState,
+  type ProgressState,
+  type ProgressStore,
+  STORAGE_KEY,
+} from "./types";
+
+const isBrowser = typeof window !== "undefined";
+
+type ProgressEntry = {
+  kind: string;
+  scope: string;
+  key: string;
+  value: unknown;
+  updatedAt?: string;
+};
+
+const PENDING_KEY = "handzon:pending";
+
+function readStorage(): ProgressState {
+  if (!isBrowser) return emptyState();
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return emptyState();
+    return { ...emptyState(), ...(JSON.parse(raw) as Partial<ProgressState>) };
+  } catch {
+    return emptyState();
+  }
+}
+
+function writeStorage(state: ProgressState): void {
+  if (!isBrowser) return;
+  window.localStorage.setItem(STORAGE_KEY, JSON.stringify(state));
+}
+
+function readPending(): ProgressEntry[] {
+  if (!isBrowser) return [];
+  try {
+    return JSON.parse(window.localStorage.getItem(PENDING_KEY) ?? "[]") as ProgressEntry[];
+  } catch {
+    return [];
+  }
+}
+
+function writePending(entries: ProgressEntry[]): void {
+  window.localStorage.setItem(PENDING_KEY, JSON.stringify(entries));
+}
+
+function diffState(prev: ProgressState, next: ProgressState): ProgressEntry[] {
+  const out: ProgressEntry[] = [];
+  for (const [key, value] of Object.entries(next.steps)) {
+    if (prev.steps[key as `${string}/${string}`] !== value) {
+      const [scope, k] = key.split("/") as [string, string];
+      out.push({ kind: "step", scope, key: k, value });
+    }
+  }
+  for (const [id, value] of Object.entries(next.quizzes)) {
+    if (JSON.stringify(prev.quizzes[id]) !== JSON.stringify(value)) {
+      out.push({ kind: "quiz", scope: "global", key: id, value });
+    }
+  }
+  for (const [id, value] of Object.entries(next.checkpoints)) {
+    if (!prev.checkpoints[id]) {
+      out.push({ kind: "checkpoint", scope: "global", key: id, value });
+    }
+  }
+  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 });
+    }
+  }
+  for (const [scope, value] of Object.entries(next.lastVisited)) {
+    const prevValue = prev.lastVisited[scope];
+    if (!prevValue || prevValue.step !== value.step || prevValue.ts !== value.ts) {
+      out.push({ kind: "lastVisited", scope, key: "step", value });
+    }
+  }
+  for (const [scope, marker] of Object.entries(next.tutorials)) {
+    const prevMarker = prev.tutorials[scope] ?? {};
+    if (marker.started && prevMarker.started !== marker.started) {
+      out.push({ kind: "tutorial", scope, key: "started", value: { ts: marker.started } });
+    }
+    if (marker.completed && prevMarker.completed !== marker.completed) {
+      out.push({ kind: "tutorial", scope, key: "completed", value: { ts: marker.completed } });
+    }
+  }
+  return out;
+}
+
+/**
+ * Same shape as the local store, but mirrors writes to /api/progress with
+ * debounced batching and an offline queue.
+ */
+export function createRemoteStore(): ProgressStore {
+  let state: ProgressState = readStorage();
+  const subscribers = new Set<(s: ProgressState) => void>();
+  let channel: BroadcastChannel | null = null;
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  if (isBrowser && typeof BroadcastChannel !== "undefined") {
+    channel = new BroadcastChannel(CHANNEL_NAME);
+    channel.addEventListener("message", (event: MessageEvent) => {
+      if (event.data?.type === "set") {
+        state = event.data.state as ProgressState;
+        for (const fn of subscribers) fn(state);
+      }
+    });
+  }
+
+  async function flush() {
+    flushTimer = null;
+    const pending = readPending();
+    if (pending.length === 0) return;
+    try {
+      const res = await fetch("/api/progress", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(pending),
+        credentials: "same-origin",
+      });
+      if (res.ok) writePending([]);
+    } catch {
+      // stay offline-queued
+    }
+  }
+
+  function scheduleFlush() {
+    if (flushTimer) clearTimeout(flushTimer);
+    flushTimer = setTimeout(flush, 750);
+  }
+
+  if (isBrowser) {
+    window.addEventListener("online", () => void flush());
+
+    // On first mount, pull the server's snapshot and merge in.
+    void (async () => {
+      try {
+        const res = await fetch("/api/progress", { credentials: "same-origin" });
+        if (!res.ok) return;
+        const { entries } = (await res.json()) as {
+          entries: Array<{ kind: string; scope: string; key: string; value: unknown }>;
+        };
+        const merged: ProgressState = { ...emptyState(), ...state };
+        for (const e of entries) {
+          if (e.kind === "step") {
+            merged.steps[`${e.scope}/${e.key}` as `${string}/${string}`] = e.value as
+              | "incomplete"
+              | "complete";
+          } else if (e.kind === "quiz") {
+            merged.quizzes[e.key] = e.value as ProgressState["quizzes"][string];
+          } else if (e.kind === "checkpoint") {
+            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;
+          } else if (e.kind === "lastVisited") {
+            // Tolerate both new ({step, ts}) and legacy (string) shapes.
+            const v = e.value as unknown;
+            merged.lastVisited[e.scope] =
+              typeof v === "string" ? { step: v, ts: 0 } : (v as { step: string; ts: number });
+          } else if (e.kind === "tutorial") {
+            const v = (e.value as { ts?: number }) ?? {};
+            const marker = merged.tutorials[e.scope] ?? {};
+            if (e.key === "started") marker.started = v.ts;
+            else if (e.key === "completed") marker.completed = v.ts;
+            merged.tutorials[e.scope] = marker;
+          }
+        }
+        state = merged;
+        writeStorage(state);
+        for (const fn of subscribers) fn(state);
+      } catch {
+        // ignore — local data still drives the UI
+      }
+    })();
+  }
+
+  return {
+    get: () => state,
+    set: (updater) => {
+      const prev = state;
+      state = updater(state);
+      writeStorage(state);
+      const entries = diffState(prev, state);
+      if (entries.length > 0) {
+        writePending([...readPending(), ...entries]);
+        scheduleFlush();
+      }
+      for (const fn of subscribers) fn(state);
+      channel?.postMessage({ type: "set", state });
+    },
+    subscribe: (fn) => {
+      subscribers.add(fn);
+      return () => {
+        subscribers.delete(fn);
+      };
+    },
+  };
+}

package/src/lib/progress/types.ts

@@ -0,0 +1,63 @@
+export type StepKey = `${string}/${string}`;
+
+export interface LastVisitedEntry {
+  step: string;
+  ts: number;
+}
+
+/**
+ * Local mirror of the per-learner "I started / finished this tutorial"
+ * markers. We keep them locally so the remote diff is idempotent (no
+ * duplicate POSTs when the user reloads). The server's composite PK
+ * makes re-sends harmless but spamming `/api/progress` is rude.
+ */
+export interface TutorialMarker {
+  started?: number;
+  completed?: number;
+}
+
+export type ProgressState = {
+  steps: Record<StepKey, "incomplete" | "complete">;
+  quizzes: Record<string, { chosen: number[]; correct: boolean; ts: number }>;
+  checkpoints: Record<string, { ts: number }>;
+  prefs: {
+    packageManager?: "npm" | "pnpm" | "yarn" | "bun";
+    os?: "macos" | "linux" | "windows";
+    theme?: "light" | "dark";
+  };
+  /**
+   * Per-tutorial "where was I last?" marker. Tracks `ts` so consumers
+   * (like the ResumeRail) can pick the truly most-recent tutorial
+   * instead of relying on insertion order, which lies when an existing
+   * key is overwritten.
+   */
+  lastVisited: Record<string, LastVisitedEntry>;
+  /**
+   * Per-tutorial popularity-event markers. Cross-learner aggregates
+   * live on the server (`/api/tutorials/stats`); this map only tracks
+   * what *this* learner has emitted so we can dedupe.
+   */
+  tutorials: Record<string, TutorialMarker>;
+};
+
+export interface ProgressStore {
+  get(): ProgressState;
+  set(updater: (s: ProgressState) => ProgressState): void;
+  subscribe(fn: (s: ProgressState) => void): () => void;
+}
+
+export const emptyState = (): ProgressState => ({
+  steps: {},
+  quizzes: {},
+  checkpoints: {},
+  prefs: {},
+  lastVisited: {},
+  tutorials: {},
+});
+
+// TODO: when you change ProgressState's shape in a way that's not
+// forward-compatible with the spread-merge in readStorage(), bump the
+// version suffix and add a one-shot migration in `local.ts` that reads
+// the old key, transforms it, and writes the new one.
+export const STORAGE_KEY = "handzon:v1";
+export const CHANNEL_NAME = "handzon:v1";

package/src/lib/progress/useProgress.ts

@@ -0,0 +1,117 @@
+import { useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { getStore } from "./local";
+import type { ProgressState, StepKey } from "./types";
+
+interface ProgressApi {
+  state: ProgressState;
+  markStepComplete: (tutorial: string, step: string) => void;
+  markStepIncomplete: (tutorial: string, step: string) => void;
+  recordQuiz: (questionId: string, chosen: number[], correct: boolean) => void;
+  recordCheckpoint: (checkpointId: string) => void;
+  setPref: <K extends keyof ProgressState["prefs"]>(
+    key: K,
+    value: ProgressState["prefs"][K],
+  ) => void;
+  setLastVisited: (tutorial: string, step: string) => void;
+  markTutorialStarted: (tutorial: string) => void;
+  markTutorialCompleted: (tutorial: string) => void;
+  isStepComplete: (tutorial: string, step: string) => boolean;
+}
+
+/**
+ * Action methods are memoized in a useMemo with an empty dep list so their
+ * references stay stable across renders. Without this, every render produced
+ * a new `markStepComplete` (etc.) reference; consumers using these as effect
+ * deps would re-run effects forever, each call triggering a store update and
+ * another render — a freeze-the-tab render storm.
+ */
+export function useProgress(): ProgressApi {
+  const store = getStore();
+  const state = useSyncExternalStore(
+    store.subscribe,
+    () => store.get(),
+    () => store.get(),
+  );
+
+  const actions = useMemo(() => {
+    const stepKey = (tutorial: string, step: string): StepKey => `${tutorial}/${step}`;
+    return {
+      markStepComplete: (tutorial: string, step: string) =>
+        store.set((s) => ({
+          ...s,
+          steps: { ...s.steps, [stepKey(tutorial, step)]: "complete" as const },
+        })),
+      markStepIncomplete: (tutorial: string, step: string) =>
+        store.set((s) => ({
+          ...s,
+          steps: { ...s.steps, [stepKey(tutorial, step)]: "incomplete" as const },
+        })),
+      recordQuiz: (questionId: string, chosen: number[], correct: boolean) =>
+        store.set((s) => ({
+          ...s,
+          quizzes: { ...s.quizzes, [questionId]: { chosen, correct, ts: Date.now() } },
+        })),
+      recordCheckpoint: (checkpointId: string) =>
+        store.set((s) => ({
+          ...s,
+          checkpoints: { ...s.checkpoints, [checkpointId]: { ts: Date.now() } },
+        })),
+      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) =>
+        store.set((s) => ({
+          ...s,
+          lastVisited: { ...s.lastVisited, [tutorial]: { step, ts: Date.now() } },
+        })),
+      markTutorialStarted: (tutorial: string) =>
+        store.set((s) => {
+          // Idempotent: bail if we already recorded this learner's
+          // "started" event so we don't spam /api/progress on every
+          // navigation.
+          if (s.tutorials[tutorial]?.started) return s;
+          return {
+            ...s,
+            tutorials: {
+              ...s.tutorials,
+              [tutorial]: { ...s.tutorials[tutorial], started: Date.now() },
+            },
+          };
+        }),
+      markTutorialCompleted: (tutorial: string) =>
+        store.set((s) => {
+          if (s.tutorials[tutorial]?.completed) return s;
+          return {
+            ...s,
+            tutorials: {
+              ...s.tutorials,
+              [tutorial]: { ...s.tutorials[tutorial], completed: Date.now() },
+            },
+          };
+        }),
+    };
+  }, [store]);
+
+  return {
+    state,
+    ...actions,
+    isStepComplete: (tutorial, step) =>
+      state.steps[`${tutorial}/${step}` as StepKey] === "complete",
+  };
+}
+
+/**
+ * SSR-safe variant that only reads the store after mount. Use this when a
+ * component needs to render something only when the value is known (e.g.
+ * "Resume" buttons that should not flash on first paint).
+ */
+export function useProgressAfterMount(): ProgressState | null {
+  const [mounted, setMounted] = useState(false);
+  const store = getStore();
+  const state = useSyncExternalStore(
+    store.subscribe,
+    () => store.get(),
+    () => store.get(),
+  );
+  useEffect(() => setMounted(true), []);
+  return mounted ? state : null;
+}