handzon-core 0.6.2 → 0.8.0

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

@@ -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;
@@ -27,23 +35,84 @@ 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];
+  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) return;
+    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.
+  // 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} />

package/src/components/mdx/CopyPrompt.tsx

@@ -0,0 +1,56 @@
+import { Check, ClipboardCopy } from "lucide-react";
+import { useState } from "react";
+import { readStepData, renderTemplate } from "../../lib/ai/stepData";
+
+interface Props {
+  /**
+   * Templated prompt body. Supports `{{tutorialTitle}}`,
+   * `{{tutorialSlug}}`, `{{stepTitle}}`, `{{stepSlug}}`, and
+   * `{{stepSource}}` placeholders. Unknown placeholders are left
+   * untouched so typos surface.
+   */
+  template: string;
+  /** Override the default button label. */
+  label?: string;
+}
+
+/**
+ * Family B touchpoint: author-placed "Copy prompt" button that
+ * always works (no aiConfig required). Substitutes step + tutorial
+ * data into the template at click time so it stays in sync if the
+ * author edits the step.
+ */
+export default function CopyPrompt({ template, label }: Props) {
+  const [copied, setCopied] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function copy() {
+    setError(null);
+    const data = readStepData();
+    const body = data ? renderTemplate(template, data) : template;
+    try {
+      await navigator.clipboard.writeText(body);
+      setCopied(true);
+      window.setTimeout(() => setCopied(false), 1800);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      className="hz-copy-prompt"
+      onClick={() => void copy()}
+      aria-live="polite"
+      title={error ?? undefined}
+    >
+      {copied ? (
+        <Check size={14} aria-hidden="true" />
+      ) : (
+        <ClipboardCopy size={14} aria-hidden="true" />
+      )}
+      <span>{copied ? "Copied" : (label ?? "Copy prompt")}</span>
+    </button>
+  );
+}

package/src/components/mdx/HelpMe.astro

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

package/src/components/mdx/HelpMe.tsx

@@ -0,0 +1,29 @@
+import { LifeBuoy } from "lucide-react";
+import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
+
+interface Props {
+  /** Free-form topic appended to the seed message ("I'm stuck on …"). */
+  topic?: string;
+  /** Override the default button label. */
+  label?: string;
+}
+
+/**
+ * Author-placed inline button that opens the in-app tutor pre-seeded
+ * with an "unstuck" intent. Renders nothing when `aiConfig.enabled`
+ * is false on the host page.
+ */
+export default function HelpMe({ topic, label }: Props) {
+  const enabled = useAiEnabled();
+  if (!enabled) return null;
+  return (
+    <button
+      type="button"
+      className="hz-helpme"
+      onClick={() => dispatchAssist({ kind: "unstuck", topic })}
+    >
+      <LifeBuoy size={14} aria-hidden="true" />
+      <span>{label ?? (topic ? `Stuck on ${topic}?` : "Stuck? Ask the tutor")}</span>
+    </button>
+  );
+}

package/src/components/mdx/Playground.tsx

@@ -1,4 +1,14 @@
-import { Sandpack, type SandpackPredefinedTemplate } from "@codesandbox/sandpack-react";
+import {
+  SandpackCodeEditor,
+  SandpackConsole,
+  SandpackLayout,
+  type SandpackPredefinedTemplate,
+  SandpackPreview,
+  SandpackProvider,
+  useSandpack,
+} from "@codesandbox/sandpack-react";
+import { Sparkles } from "lucide-react";
+import { dispatchAssist, useAiTool } from "../../lib/ai/assist";
 
 interface Props {
   template?: SandpackPredefinedTemplate;
@@ -6,6 +16,42 @@ interface Props {
   dependencies?: Record<string, string>;
   height?: number;
   showConsole?: boolean;
+  /**
+   * Whether to render the "Ask AI to fix" button in the toolbar.
+   * Driven by `aiConfig.tools.suggestPlaygroundEdit` on the host
+   * page; the button still hides itself client-side when the tutor
+   * isn't enabled.
+   */
+  askAiToFix?: boolean;
+}
+
+/**
+ * Toolbar button rendered inside SandpackProvider so useSandpack
+ * can read the *current* file contents (post-edit) at click time.
+ */
+function AskAiButton() {
+  const toolEnabled = useAiTool("suggestPlaygroundEdit");
+  const { sandpack } = useSandpack();
+  if (!toolEnabled) return null;
+
+  function onClick() {
+    const files: Record<string, string> = {};
+    for (const [path, entry] of Object.entries(sandpack.files)) {
+      // Hidden files are author scaffolding (e.g. config) the learner
+      // didn't touch — exclude them so the prompt focuses on what
+      // they're actually editing.
+      if (entry.hidden) continue;
+      files[path] = entry.code;
+    }
+    dispatchAssist({ kind: "playgroundFix", files });
+  }
+
+  return (
+    <button type="button" className="hz-helpme hz-playground-ask" onClick={onClick}>
+      <Sparkles size={14} aria-hidden="true" />
+      <span>Ask AI to fix</span>
+    </button>
+  );
 }
 
 export default function Playground({
@@ -14,21 +60,27 @@ export default function Playground({
   dependencies,
   height = 480,
   showConsole = true,
+  askAiToFix = true,
 }: Props) {
   return (
     <div className="playground" style={{ height }}>
-      <Sandpack
+      <SandpackProvider
         template={template}
         files={files}
         customSetup={dependencies ? { dependencies } : undefined}
         theme="dark"
-        options={{
-          showConsole,
-          showConsoleButton: true,
-          editorHeight: height,
-          editorWidthPercentage: 50,
-        }}
-      />
+      >
+        <SandpackLayout>
+          <SandpackCodeEditor style={{ height }} />
+          <SandpackPreview style={{ height }} showOpenInCodeSandbox={false} />
+        </SandpackLayout>
+        {showConsole && <SandpackConsole />}
+        {askAiToFix && (
+          <div className="playground-toolbar">
+            <AskAiButton />
+          </div>
+        )}
+      </SandpackProvider>
     </div>
   );
 }

package/src/components/mdx/Quiz.tsx

@@ -1,5 +1,6 @@
 import { Check, X } from "lucide-react";
 import { useId, useState } from "react";
+import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
 import { useProgress } from "../../lib/progress/useProgress";
 
 interface Props {
@@ -15,6 +16,7 @@ export default function Quiz({ question, options, answer, explanation, id, multi
   const reactId = useId();
   const questionId = id ?? `quiz:${reactId}:${question.slice(0, 40)}`;
   const { state, recordQuiz } = useProgress();
+  const aiEnabled = useAiEnabled();
 
   const previous = state.quizzes[questionId];
   const [chosen, setChosen] = useState<number[]>(previous?.chosen ?? []);
@@ -97,6 +99,22 @@ export default function Quiz({ question, options, answer, explanation, id, multi
         )}
       </div>
       {submitted && explanation && <p className="quiz-exp">{explanation}</p>}
+      {submitted && previous && !previous.correct && aiEnabled && (
+        <button
+          type="button"
+          className="hz-helpme"
+          onClick={() =>
+            dispatchAssist({
+              kind: "quizFix",
+              question,
+              chosen: previous.chosen.map((i) => options[i] ?? `(option ${i})`),
+              correct: Array.from(correctSet).map((i) => options[i] ?? `(option ${i})`),
+            })
+          }
+        >
+          Why is this wrong?
+        </button>
+      )}
     </fieldset>
   );
 }

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,48 @@
  * 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";
+export {
+  type AssistantIntent,
+  type AssistantPrompt,
+  buildAssistantPrompt,
+} from "./lib/ai/prompts.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/layouts/TutorialLayout.astro

@@ -82,9 +82,28 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
     id="tt-route"
     data-tutorial-slug={tutorial.id}
     data-step-slug={currentStepSlug}
+    data-tutorial-title={tutorial.data.title}
     data-tutorial-steps={JSON.stringify(stepSlugs)}
     hidden
   ></div>
+  {/*
+    Raw MDX source of the current step + selected metadata. CopyPrompt,
+    "Copy step as Markdown", deep-link row, and the BYOA touchpoints
+    read this at click time. Replacing "<" with "<" inside JSON
+    keeps a stray "</script>" or "<!--" in the step body from
+    terminating the script tag early.
+  */}
+  <script
+    id="tt-step-data"
+    type="application/json"
+    set:html={JSON.stringify({
+      tutorialSlug: tutorial.id,
+      tutorialTitle: tutorial.data.title,
+      stepSlug: currentStepSlug,
+      stepTitle: currentStep.data.title,
+      stepSource: currentStep.body ?? "",
+    }).replace(/</g, "\\u003c")}
+  ></script>
   <script>
     // Record last-visited + popularity markers from a data marker
     // (set in the markup above). Using a normal <script> + relative

package/src/lib/ai/assist.ts

@@ -0,0 +1,81 @@
+import { useEffect, useState } from "react";
+import type { AssistantIntent } from "./prompts";
+
+/**
+ * Document-scoped event that Family A touchpoints (HelpMe, quiz wrong
+ * answer, checkpoint nudge, selection ask, playground fix, step
+ * footer) dispatch to ask the in-app tutor to open with a pre-seeded
+ * intent. ChatButton is the single listener — it owns the context
+ * and config needed to render the intent into seedMessages.
+ */
+export const ASSIST_EVENT = "handzon:assist";
+
+/**
+ * Dispatched by ChatButton once on mount, and reflected as
+ * `document.documentElement.dataset.handzonAi = "ready"` for islands
+ * that mount after the chat (read the flag) or before (await the
+ * event). Family A islands use `useAiEnabled()` to hide themselves
+ * when the tutor isn't on this page.
+ */
+export const ASSIST_READY_EVENT = "handzon:ai-ready";
+
+export interface AssistEventDetail {
+  intent: AssistantIntent;
+}
+
+/**
+ * Fire a touchpoint intent. ChatButton receives, builds the prompt
+ * with the live AssistantContext it already holds, and opens the
+ * panel with the seed user turn.
+ */
+export function dispatchAssist(intent: AssistantIntent): void {
+  if (typeof document === "undefined") return;
+  const detail: AssistEventDetail = { intent };
+  document.dispatchEvent(new CustomEvent(ASSIST_EVENT, { detail }));
+}
+
+/**
+ * Reactive flag: is the in-app tutor mounted on this page? Family A
+ * islands return null when false so the affordance is hidden
+ * entirely when `aiConfig.enabled === false`.
+ */
+export function useAiEnabled(): boolean {
+  const [enabled, setEnabled] = useState(false);
+  useEffect(() => {
+    if (document.documentElement.dataset.handzonAi === "ready") {
+      setEnabled(true);
+      return;
+    }
+    const onReady = () => setEnabled(true);
+    document.addEventListener(ASSIST_READY_EVENT, onReady);
+    return () => document.removeEventListener(ASSIST_READY_EVENT, onReady);
+  }, []);
+  return enabled;
+}
+
+/**
+ * Reactive flag: is a specific tool (config.tools.X) enabled by the
+ * host page's aiConfig? Returns false until ChatButton publishes the
+ * tools manifest on mount. Family A islands that gate on a tool
+ * (Playground's "Ask AI to fix") use this in addition to
+ * useAiEnabled.
+ */
+export function useAiTool(name: string): boolean {
+  const enabled = useAiEnabled();
+  const [tools, setTools] = useState<Record<string, boolean>>({});
+  useEffect(() => {
+    function read() {
+      const raw = document.documentElement.dataset.handzonAiTools;
+      if (!raw) return;
+      try {
+        setTools(JSON.parse(raw));
+      } catch {
+        /* ignore */
+      }
+    }
+    read();
+    document.addEventListener(ASSIST_READY_EVENT, read);
+    return () => document.removeEventListener(ASSIST_READY_EVENT, read);
+  }, []);
+  return enabled && tools[name] === true;
+}