handzon-core 0.7.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.7.0",
+  "version": "0.8.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

@@ -86,20 +86,114 @@ export function tutorialsLoader(): Loader {
   };
 }
 
-/** Glob loader for tutorial step `.mdx`/`.md` files. */
-export function stepsLoader() {
-  return glob({
+/**
+ * Glob loader for tutorial step `.mdx`/`.md` files.
+ *
+ * After the inner glob populates the store we walk every entry once
+ * and reject any step whose `verify.id` doesn't match a
+ * `<Checkpoint id="…">` in the MDX body. Catching this at load time
+ * means an author who renames a checkpoint id but forgets the
+ * frontmatter sees a loud build failure instead of silently broken
+ * verification at run time.
+ */
+export function stepsLoader(): Loader {
+  const inner = glob({
     pattern: "**/[0-9]*-*.{mdx,md}",
     base: `./${TUTORIALS_REL}`,
   });
+  return {
+    name: "handzon-steps",
+    load: async (args) => {
+      await inner.load(args);
+      const checkpointRe = /<Checkpoint\b[^>]*\bid\s*=\s*(?:"([^"]+)"|'([^']+)'|\{`([^`]+)`\})/g;
+      for (const value of args.store.values()) {
+        const verify = (value.data as { verify?: { id?: string } } | undefined)?.verify;
+        if (!verify?.id) continue;
+        const body = value.body ?? "";
+        const ids = new Set<string>();
+        checkpointRe.lastIndex = 0;
+        for (;;) {
+          const m = checkpointRe.exec(body);
+          if (m === null) break;
+          const id = m[1] ?? m[2] ?? m[3];
+          if (id) ids.add(id);
+        }
+        if (!ids.has(verify.id)) {
+          throw new Error(
+            `[handzon] step ${value.id}: verify.id "${verify.id}" has no matching <Checkpoint id="…"> in the step body. Either add a <Checkpoint id="${verify.id}" …/> or remove the verify block.`,
+          );
+        }
+      }
+    },
+  };
 }
 
+/**
+ * Schema for machine-verifiable checkpoint specs (Family D). Authors
+ * declare deterministic checks per step; the agent runs them on the
+ * learner's machine and POSTs observed values back to the server,
+ * which scores against the spec via the evaluator.
+ *
+ * `kind` is a discriminated union — only the fields valid for each
+ * check kind pass validation.
+ */
+export const verifyCheckSchema = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("file_exists"),
+    path: z.string().min(1),
+    hint: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal("file_contains"),
+    path: z.string().min(1),
+    /** Regex matched against the file body. */
+    pattern: z.string().min(1),
+    hint: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal("shell"),
+    run: z.string().min(1),
+    expect: z
+      .object({
+        exitCode: z.number().int().optional(),
+        stdoutMatches: z.string().optional(),
+      })
+      .default({}),
+    hint: z.string().optional(),
+  }),
+  z.object({
+    kind: z.literal("http"),
+    url: z.string().min(1),
+    expect: z
+      .object({
+        status: z.number().int().optional(),
+        bodyIncludes: z.string().optional(),
+        bodyMatches: z.string().optional(),
+      })
+      .default({}),
+    hint: z.string().optional(),
+  }),
+]);
+
+export type VerifyCheck = z.infer<typeof verifyCheckSchema>;
+
+export const verifySchema = z.object({
+  /** Must match a <Checkpoint id> in the step's MDX. */
+  id: z.string().min(1),
+  /** Advisory cwd hint passed to the agent (e.g. "$LEARNER_PROJECT"). */
+  cwd: z.string().optional(),
+  checks: z.array(verifyCheckSchema).min(1),
+});
+
+export type VerifySpec = z.infer<typeof verifySchema>;
+
 /** Schema for tutorial step entries. */
 export const stepsSchema = z.object({
   title: z.string(),
   duration: z.string().optional(),
   summary: z.string().optional(),
   ai: z.boolean().optional(),
+  verify: verifySchema.optional(),
 });
 
 /** Schema for tutorial entries. Pass through Astro's image() helper. */

package/src/components/ai/ChatButton.tsx

@@ -1,6 +1,9 @@
 import { Sparkles } from "lucide-react";
-import { useState } from "react";
+import { useEffect, useState } from "react";
+import { ASSIST_EVENT, ASSIST_READY_EVENT, type AssistEventDetail } from "../../lib/ai/assist";
+import type { ChatMessage } from "../../lib/ai/client";
 import type { AssistantContext } from "../../lib/ai/context";
+import { buildAssistantPrompt } from "../../lib/ai/prompts";
 import type { AiConfig } from "../../types/ai";
 import ChatPanel from "./ChatPanel";
 
@@ -11,6 +14,41 @@ interface Props {
 
 export default function ChatButton({ config, context }: Props) {
   const [open, setOpen] = useState(false);
+  const [seed, setSeed] = useState<ChatMessage[] | undefined>(undefined);
+  // Bumped on each new assist seed so ChatPanel remounts with the
+  // new initialMessages even if the panel is already open from a
+  // previous intent or FAB click.
+  const [seedToken, setSeedToken] = useState(0);
+
+  // Tell Family A islands (HelpMe, Checkpoint nudge, …) that the tutor
+  // is mounted on this page. Set the dataset flag for islands that
+  // hydrate after us; dispatch the event for islands that hydrated
+  // before us and are waiting.
+  useEffect(() => {
+    document.documentElement.dataset.handzonAi = "ready";
+    document.documentElement.dataset.handzonAiTools = JSON.stringify(config.tools ?? {});
+    document.dispatchEvent(new CustomEvent(ASSIST_READY_EVENT));
+    return () => {
+      delete document.documentElement.dataset.handzonAi;
+      delete document.documentElement.dataset.handzonAiTools;
+    };
+  }, [config.tools]);
+
+  // Listen for touchpoint dispatches and open the panel with the
+  // matching seedMessages.
+  useEffect(() => {
+    function onAssist(e: Event) {
+      const detail = (e as CustomEvent<AssistEventDetail>).detail;
+      if (!detail?.intent) return;
+      const { seedMessages } = buildAssistantPrompt(context, detail.intent);
+      setSeed(seedMessages);
+      setSeedToken((t) => t + 1);
+      setOpen(true);
+    }
+    document.addEventListener(ASSIST_EVENT, onAssist);
+    return () => document.removeEventListener(ASSIST_EVENT, onAssist);
+  }, [context]);
+
   if (!config.enabled) return null;
 
   return (
@@ -18,13 +56,23 @@ export default function ChatButton({ config, context }: Props) {
       <button
         type="button"
         className="chat-fab"
-        onClick={() => setOpen(true)}
+        onClick={() => {
+          setSeed(undefined);
+          setOpen(true);
+        }}
         aria-label={`Open ${config.name}`}
       >
         <Sparkles size={18} aria-hidden="true" />
         <span>{config.name}</span>
       </button>
-      <ChatPanel open={open} onOpenChange={setOpen} config={config} context={context} />
+      <ChatPanel
+        key={seedToken}
+        open={open}
+        onOpenChange={setOpen}
+        config={config}
+        context={context}
+        initialMessages={seed}
+      />
     </>
   );
 }

package/src/components/ai/ChatPanel.tsx

@@ -13,19 +13,27 @@ interface Props {
   onOpenChange: (open: boolean) => void;
   config: AiConfig;
   context: AssistantContext;
+  /**
+   * Seed turns prepended after the assistant greeting. Callers that
+   * open the panel with a specific intent (HelpMe, quiz "why is this
+   * wrong?", checkpoint nudge, …) pass a single user turn here; the
+   * panel auto-streams a response once on open. The user-turn body
+   * stays editable in history but isn't re-sent on reopen.
+   */
+  initialMessages?: ChatMessage[];
 }
 
-export default function ChatPanel({ open, onOpenChange, config, context }: Props) {
+export default function ChatPanel({ open, onOpenChange, config, context, initialMessages }: Props) {
   const [messages, setMessages] = useState<ChatMessage[]>(() => {
-    if (config.greeting) {
-      return [{ role: "assistant", content: config.greeting }];
-    }
-    return [
-      {
-        role: "assistant",
-        content: `Hi, I'm ${config.name}. Ask me anything about "${context.tutorial.title}". I can see what step you're on.`,
-      },
-    ];
+    const greeting: ChatMessage = config.greeting
+      ? { role: "assistant", content: config.greeting }
+      : {
+          role: "assistant",
+          content: `Hi, I'm ${config.name}. Ask me anything about "${context.tutorial.title}". I can see what step you're on.`,
+        };
+    return initialMessages && initialMessages.length > 0
+      ? [greeting, ...initialMessages]
+      : [greeting];
   });
   const [input, setInput] = useState("");
   const [streaming, setStreaming] = useState(false);
@@ -54,21 +62,9 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
     listRef.current?.scrollTo({ top: listRef.current.scrollHeight });
   }, [messages, streaming]);
 
-  async function send() {
-    const trimmed = input.trim();
-    if (!trimmed || streaming) return;
-
-    if (needsKey) {
-      setByokOpen(true);
-      return;
-    }
-
-    const next: ChatMessage[] = [...messages, { role: "user", content: trimmed }];
-    setMessages(next);
-    setInput("");
+  async function runStream(next: ChatMessage[]) {
     setStreaming(true);
     setError(null);
-
     abortRef.current = new AbortController();
     try {
       const stream = await streamChat({
@@ -107,6 +103,73 @@ export default function ChatPanel({ open, onOpenChange, config, context }: Props
     }
   }
 
+  async function send() {
+    const trimmed = input.trim();
+    if (!trimmed || streaming) return;
+
+    if (needsKey) {
+      setByokOpen(true);
+      return;
+    }
+
+    const next: ChatMessage[] = [...messages, { role: "user", content: trimmed }];
+    setMessages(next);
+    setInput("");
+    await runStream(next);
+  }
+
+  // Help-bridge: when the panel first opens and there's no seed from
+  // a Family A touchpoint, fetch pending help requests posted by the
+  // agent via MCP and prepend them as user turns. Same one-shot ref
+  // as the seed below so subsequent opens don't re-replay them.
+  const inboxRef = useRef(false);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: open is the trigger
+  useEffect(() => {
+    if (!open || inboxRef.current) return;
+    if (initialMessages && initialMessages.length > 0) return;
+    inboxRef.current = true;
+    void (async () => {
+      try {
+        const res = await fetch("/api/help-inbox");
+        if (!res.ok) return;
+        const data = (await res.json()) as {
+          requests?: Array<{ query: string; tutorialSlug: string; stepSlug: string }>;
+        };
+        const queued = data.requests ?? [];
+        if (queued.length === 0) return;
+        const turns: ChatMessage[] = queued.map((r) => ({
+          role: "user",
+          content: `From my agent on ${r.tutorialSlug}/${r.stepSlug}: ${r.query}`,
+        }));
+        setMessages((prev) => [...prev, ...turns]);
+        if (!needsKey) void runStream([...messages, ...turns]);
+      } catch {
+        /* network error — silently fall back to a normal session */
+      }
+    })();
+  }, [open]);
+
+  // When the panel opens with a pre-seeded user turn (HelpMe, quiz
+  // "why is this wrong?", checkpoint nudge, …) auto-trigger the
+  // stream once. Gated on `open` so closing + reopening doesn't fire
+  // it again, and on a one-shot ref so re-renders during streaming
+  // don't either.
+  const seededRef = useRef(false);
+  // biome-ignore lint/correctness/useExhaustiveDependencies: open is the trigger; messages/needsKey are read once.
+  useEffect(() => {
+    if (!open) {
+      seededRef.current = false;
+      inboxRef.current = false;
+      return;
+    }
+    if (seededRef.current) return;
+    if (needsKey) return;
+    const last = messages[messages.length - 1];
+    if (!last || last.role !== "user") return;
+    seededRef.current = true;
+    void runStream(messages);
+  }, [open]);
+
   function clear() {
     setMessages([]);
     setError(null);

package/src/components/ai/CopyStep.tsx

@@ -0,0 +1,44 @@
+import { Check, ClipboardCopy } from "lucide-react";
+import { useState } from "react";
+import { readStepData } from "../../lib/ai/stepData";
+
+/**
+ * Family B touchpoint: copies the current step (title + tutorial
+ * title + raw MDX source) to the clipboard so the learner can
+ * paste into any tool. Always available — no aiConfig.enabled gate.
+ *
+ * Rendered alongside <OpenInAgent /> in the per-step footer row.
+ */
+export default function CopyStep() {
+  const [copied, setCopied] = useState(false);
+
+  async function copy() {
+    const data = readStepData();
+    if (!data) return;
+    const body = [
+      `# ${data.stepTitle}`,
+      ``,
+      `From: ${data.tutorialTitle}`,
+      ``,
+      data.stepSource,
+    ].join("\n");
+    try {
+      await navigator.clipboard.writeText(body);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1800);
+    } catch {
+      /* clipboard not available — fail silently */
+    }
+  }
+
+  return (
+    <button type="button" className="hz-assist-link" onClick={() => void copy()} aria-live="polite">
+      {copied ? (
+        <Check size={14} aria-hidden="true" />
+      ) : (
+        <ClipboardCopy size={14} aria-hidden="true" />
+      )}
+      <span>{copied ? "Copied" : "Copy step"}</span>
+    </button>
+  );
+}

package/src/components/ai/OpenInAgent.tsx

@@ -0,0 +1,55 @@
+import { useEffect, useState } from "react";
+import { buildAssistantPrompt } from "../../lib/ai/prompts";
+import { contextFromStepData, readStepData, type StepData } from "../../lib/ai/stepData";
+import CopyStep from "./CopyStep";
+
+interface Props {
+  /** Hide a specific agent from the row. All four shown by default. */
+  hide?: Array<"cursor" | "claude" | "chatgpt" | "vscode">;
+}
+
+const AGENTS: Array<{
+  key: "cursor" | "claude" | "chatgpt" | "vscode";
+  label: string;
+}> = [
+  { key: "cursor", label: "Cursor" },
+  { key: "claude", label: "Claude" },
+  { key: "chatgpt", label: "ChatGPT" },
+  { key: "vscode", label: "VS Code" },
+];
+
+/**
+ * Family B touchpoint: per-step row of "Open in <agent>" links that
+ * fire the explainStep prompt at Cursor / Claude / ChatGPT / VS
+ * Code via each tool's deep-link scheme. Always renders — no
+ * aiConfig.enabled gate — because the affordance is for learners
+ * who bring their own agent.
+ */
+export default function OpenInAgent({ hide = [] }: Props) {
+  const [data, setData] = useState<StepData | null>(null);
+  useEffect(() => {
+    setData(readStepData());
+  }, []);
+  if (!data) return null;
+
+  const { deepLinks } = buildAssistantPrompt(contextFromStepData(data), { kind: "explainStep" });
+  const visible = AGENTS.filter((a) => !hide.includes(a.key));
+
+  return (
+    <div className="hz-openin">
+      <span className="hz-openin-label">Explain this step in</span>
+      {visible.map((agent) => (
+        <a
+          key={agent.key}
+          className="hz-assist-link"
+          href={deepLinks[agent.key]}
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          {agent.label}
+        </a>
+      ))}
+      <CopyStep />
+    </div>
+  );
+}

package/src/components/ai/SelectionAsk.tsx

@@ -0,0 +1,98 @@
+import { Sparkles } from "lucide-react";
+import { useEffect, useState } from "react";
+import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
+
+/** Minimum selection length before the affordance appears. Avoids
+ * flashing on stray clicks or accidental drag-selects of one word.
+ */
+const MIN_CHARS = 8;
+
+interface Anchor {
+  top: number;
+  left: number;
+  text: string;
+}
+
+/**
+ * Listens for text selection inside <article.prose> (the tutorial
+ * step body). When a non-trivial selection lands, renders a small
+ * floating button anchored just above the selection range that
+ * opens the chat with a "selection" intent.
+ *
+ * Mounted once per page by TutorialStep alongside ChatButton. Hides
+ * itself entirely when the in-app tutor isn't enabled.
+ */
+export default function SelectionAsk() {
+  const enabled = useAiEnabled();
+  const [anchor, setAnchor] = useState<Anchor | null>(null);
+
+  useEffect(() => {
+    if (!enabled) return;
+    function onMouseUp() {
+      // Defer one frame so the selection is finalized before we read it.
+      window.requestAnimationFrame(() => {
+        const sel = window.getSelection();
+        if (!sel || sel.isCollapsed) {
+          setAnchor(null);
+          return;
+        }
+        const text = sel.toString().trim();
+        if (text.length < MIN_CHARS) {
+          setAnchor(null);
+          return;
+        }
+        const range = sel.getRangeAt(0);
+        // Only show inside <article.prose>; everywhere else (sidebar,
+        // chat, header) selections are not tutor-relevant.
+        const article = (range.commonAncestorContainer as Node).parentElement?.closest(
+          "article.prose",
+        );
+        if (!article) {
+          setAnchor(null);
+          return;
+        }
+        const rect = range.getBoundingClientRect();
+        if (rect.width === 0 && rect.height === 0) {
+          setAnchor(null);
+          return;
+        }
+        setAnchor({
+          top: window.scrollY + rect.top - 36,
+          left: window.scrollX + rect.left + rect.width / 2,
+          text,
+        });
+      });
+    }
+    function onScroll() {
+      setAnchor(null);
+    }
+    document.addEventListener("mouseup", onMouseUp);
+    document.addEventListener("selectionchange", () => {
+      const sel = window.getSelection();
+      if (!sel || sel.isCollapsed) setAnchor(null);
+    });
+    window.addEventListener("scroll", onScroll, { passive: true });
+    return () => {
+      document.removeEventListener("mouseup", onMouseUp);
+      window.removeEventListener("scroll", onScroll);
+    };
+  }, [enabled]);
+
+  if (!enabled || !anchor) return null;
+
+  return (
+    <button
+      type="button"
+      className="hz-selection-ask"
+      style={{ top: anchor.top, left: anchor.left, transform: "translateX(-50%)" }}
+      onClick={() => {
+        dispatchAssist({ kind: "selection", text: anchor.text });
+        setAnchor(null);
+        window.getSelection()?.removeAllRanges();
+      }}
+    >
+      <Sparkles size={12} aria-hidden="true" />
+      <span>Ask about this</span>
+    </button>
+  );
+}

package/src/components/ai/StepHelp.tsx

@@ -0,0 +1,31 @@
+import { LifeBuoy } from "lucide-react";
+import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
+
+interface Props {
+  /** Step title used as the "unstuck" topic seed. */
+  stepTitle: string;
+}
+
+/**
+ * Auto-injected step footer rendered by TutorialStep when
+ * `aiConfig.autoStepHelp` is true. A learner who scrolls to the end
+ * of an unchecked step without making progress hits this affordance
+ * before the next-step nav.
+ */
+export default function StepHelp({ stepTitle }: Props) {
+  const enabled = useAiEnabled();
+  if (!enabled) return null;
+  return (
+    <aside className="hz-step-help" role="note">
+      <LifeBuoy size={16} aria-hidden="true" />
+      <span className="hz-step-help-text">Stuck on this step?</span>
+      <button
+        type="button"
+        className="hz-helpme"
+        onClick={() => dispatchAssist({ kind: "unstuck", topic: stepTitle })}
+      >
+        Ask the tutor
+      </button>
+    </aside>
+  );
+}

package/src/components/mdx/Checkpoint.tsx

@@ -1,7 +1,15 @@
 import { Check } from "lucide-react";
-import { useEffect, useId, useState } from "react";
+import { useEffect, useId, useRef, useState } from "react";
+import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
 import { useProgress } from "../../lib/progress/useProgress";
 
+/**
+ * Time an unchecked checkpoint must be on-screen before we surface
+ * the "Stuck?" nudge. Long enough that learners actively working
+ * won't see it, short enough that genuinely stuck learners do.
+ */
+const STUCK_DELAY_MS = 45_000;
+
 interface Props {
   label: string;
   id?: string;
@@ -31,6 +39,38 @@ export default function Checkpoint({ label, id }: Props) {
     useProgress();
   const route = useRoute();
   const done = !!state.checkpoints[checkpointId];
+  const aiEnabled = useAiEnabled();
+  const [stuck, setStuck] = useState(false);
+  const rootRef = useRef<HTMLDivElement>(null);
+
+  // 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
+  // until the learner ticks the checkpoint.
+  useEffect(() => {
+    if (done || !aiEnabled || stuck) return;
+    const el = rootRef.current;
+    if (!el) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const e of entries) {
+          if (e.isIntersecting) {
+            if (timer === null) timer = setTimeout(() => setStuck(true), STUCK_DELAY_MS);
+          } else if (timer !== null) {
+            clearTimeout(timer);
+            timer = null;
+          }
+        }
+      },
+      { threshold: 0.5 },
+    );
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+      if (timer !== null) clearTimeout(timer);
+    };
+  }, [done, aiEnabled, stuck]);
 
   function onToggle() {
     if (done) {
@@ -42,13 +82,37 @@ export default function Checkpoint({ label, id }: Props) {
     if (route) markStepComplete(route.tutorial, route.step);
   }
 
+  // Family D: inline failure feedback from a submit_verification call.
+  // SSE pushes the verification row into state.verificationFeedback;
+  // we render it under the checkpoint label when present and the
+  // checkpoint isn't ticked yet. Cleared on the next pass or when
+  // the learner unchecks the checkpoint.
+  const feedback = state.verificationFeedback[checkpointId];
+  const showFeedback = !done && feedback && !feedback.pass;
+
   return (
-    <div className={done ? "checkpoint is-done" : "checkpoint"}>
+    <div ref={rootRef} className={done ? "checkpoint is-done" : "checkpoint"}>
       <button type="button" onClick={onToggle} aria-pressed={done}>
         <span className="checkpoint-box">{done && <Check size={16} />}</span>
         <span>{label}</span>
       </button>
       {done && <span className="checkpoint-msg">Step complete</span>}
+      {stuck && !done && (
+        <button
+          type="button"
+          className="checkpoint-nudge"
+          onClick={() => dispatchAssist({ kind: "checkpoint", label })}
+        >
+          Stuck? Ask the tutor →
+        </button>
+      )}
+      {showFeedback && (
+        <div className="checkpoint-feedback" role="status">
+          <strong>Check failed</strong>
+          {feedback.reason && <p>{feedback.reason}</p>}
+          {feedback.hint && <p className="checkpoint-feedback-hint">{feedback.hint}</p>}
+        </div>
+      )}
     </div>
   );
 }

package/src/components/mdx/CopyPrompt.astro

@@ -0,0 +1,10 @@
+---
+import CopyPromptIsland from "./CopyPrompt.tsx";
+
+interface Props {
+  template: string;
+  label?: string;
+}
+const props = Astro.props as Props;
+---
+<CopyPromptIsland client:visible {...props} />