handzon-core 0.7.0 → 0.8.1

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} />

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/index.ts

@@ -17,6 +17,11 @@ export {
   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 {
   getStep,

package/src/layouts/BaseLayout.astro

@@ -75,6 +75,12 @@ const desc = description ?? tagline;
     <meta property="og:title" content={pageTitle} />
     <meta property="og:description" content={desc} />
     <meta property="og:type" content="website" />
+    {/* Optional consumer-side <head> injections. Forwarded by every
+     * page wrapper (Home, TutorialLanding, TutorialStep / TutorialLayout)
+     * so scaffolds can preload fonts, attach per-page OG images, add
+     * JSON-LD structured data, or wire verification meta without
+     * forking BaseLayout. See README for usage. */}
+    <slot name="head" />
   </head>
   <body style={`--hz-page-max-width: ${resolvedMaxWidth}; --hz-page-padding-x: ${pagePaddingX}; --hz-nav-height: 3rem;`}>
     {nav === "full" && (

package/src/layouts/TutorialLayout.astro

@@ -42,6 +42,7 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
 >
+  <slot name="head" slot="head" />
   <div class="layout">
     <div class="sidebar-wrap">
       <Sidebar tutorial={tutorial} steps={steps} currentStepSlug={currentStepSlug} />
@@ -82,9 +83,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
@@ -158,23 +178,30 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
 
 <style>
   /* Draw the sidebar/main divider as a background line on the grid
-   * itself: 1px-thin vertical strip at the 280px column boundary,
+   * itself: 1px-thin vertical strip at the sidebar column boundary,
    * from the top of the layout to the bottom. The grid auto-stretches
    * to fit its content, so the line runs all the way down to the
    * footer regardless of step length — without piggybacking on the
-   * (sticky, viewport-height) sidebar's own border. */
+   * (sticky, viewport-height) sidebar's own border.
+   *
+   * `--sb-w` keeps the column track and the divider stop in lockstep
+   * so widening the sidebar at one breakpoint doesn't desync the line. */
   .layout {
+    --sb-w: 280px;
     display: grid;
-    grid-template-columns: 280px minmax(0, 1fr);
+    grid-template-columns: var(--sb-w) minmax(0, 1fr);
     min-height: 100dvh;
     background: linear-gradient(
       to right,
-      transparent 280px,
-      var(--color-border) 280px,
-      var(--color-border) 281px,
-      transparent 281px
+      transparent var(--sb-w),
+      var(--color-border) var(--sb-w),
+      var(--color-border) calc(var(--sb-w) + 1px),
+      transparent calc(var(--sb-w) + 1px)
     ) no-repeat;
   }
+  @media (min-width: 1280px) {
+    .layout { --sb-w: 320px; }
+  }
   .sidebar-wrap {
     position: sticky;
     top: var(--hz-nav-height, 3rem);
@@ -192,10 +219,11 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
     color: var(--color-muted);
   }
   .step-title {
+    font-family: var(--font-display, var(--font-sans));
     font-size: clamp(1.75rem, 3vw, 2.25rem);
-    font-weight: 700;
+    font-weight: var(--font-weight-display, 700);
     margin: 0.3rem 0 0.5rem;
-    letter-spacing: -0.02em;
+    letter-spacing: var(--tracking-display, -0.02em);
     line-height: 1.15;
   }
   .step-dur {

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;
+}

package/src/lib/ai/prompts.ts

@@ -0,0 +1,126 @@
+import type { ChatMessage } from "./client";
+import type { AssistantContext } from "./context";
+
+export type AssistantIntent =
+  | { kind: "unstuck"; topic?: string }
+  | {
+      kind: "quizFix";
+      question: string;
+      chosen: string[];
+      correct: string[];
+    }
+  | { kind: "checkpoint"; label: string }
+  | { kind: "selection"; text: string }
+  | { kind: "playgroundFix"; files: Record<string, string> }
+  | { kind: "explainStep" }
+  | { kind: "recap" };
+
+export interface AssistantPrompt {
+  /** Ready-to-render Markdown a learner can paste anywhere. */
+  markdown: string;
+  /** Seed messages for ChatPanel — first user turn, no assistant turn. */
+  seedMessages: ChatMessage[];
+  /** URL-encoded prompt for each external agent. */
+  deepLinks: {
+    cursor: string;
+    claude: string;
+    chatgpt: string;
+    vscode: string;
+  };
+}
+
+function header(ctx: AssistantContext): string {
+  return [`Tutorial: ${ctx.tutorial.title}`, `Step: ${ctx.currentStep.title}`].join("\n");
+}
+
+function renderIntent(ctx: AssistantContext, intent: AssistantIntent): string {
+  switch (intent.kind) {
+    case "unstuck":
+      return intent.topic
+        ? `I'm stuck on "${intent.topic}". Help me figure out what to do next without giving the whole answer.`
+        : `I'm stuck on this step. Help me figure out what to do next without giving the whole answer.`;
+    case "quizFix":
+      return [
+        `I got a quiz question wrong and want to understand why.`,
+        ``,
+        `Question: ${intent.question}`,
+        `I chose: ${intent.chosen.join(", ") || "(nothing)"}`,
+        `Correct answer: ${intent.correct.join(", ")}`,
+        ``,
+        `Explain why my choice is wrong without restating the correct answer verbatim — help me see what concept I'm missing.`,
+      ].join("\n");
+    case "checkpoint":
+      return `I'm not sure how to complete this checkpoint: "${intent.label}". Walk me through what to try next.`;
+    case "selection":
+      return [
+        `I have a question about this part of the tutorial:`,
+        ``,
+        "```",
+        intent.text,
+        "```",
+        ``,
+        `Can you explain it in context of where I am?`,
+      ].join("\n");
+    case "playgroundFix": {
+      const files = Object.entries(intent.files)
+        .map(([path, body]) => `### \`${path}\`\n\n\`\`\`\n${body}\n\`\`\``)
+        .join("\n\n");
+      return [
+        `My playground code isn't working as expected. Here are the current files:`,
+        ``,
+        files,
+        ``,
+        `What's wrong, and what should I change? Point me at the bug; don't just rewrite the file.`,
+      ].join("\n");
+    }
+    case "explainStep":
+      return [
+        `Walk me through what this step is asking me to do and why it matters.`,
+        ``,
+        `Step content:`,
+        ``,
+        ctx.currentStep.source,
+      ].join("\n");
+    case "recap":
+      return `Give me a one-paragraph recap of what I've learned so far in this tutorial.`;
+  }
+}
+
+function buildMarkdown(ctx: AssistantContext, intent: AssistantIntent): string {
+  return [header(ctx), "", renderIntent(ctx, intent)].join("\n");
+}
+
+/**
+ * Cursor's anysphere deep link expects a `text` query param.
+ * Claude.ai and ChatGPT use `?q=...`. VS Code can launch a chat
+ * extension via the `vscode://` scheme; we use the generic
+ * `vscode://GitHub.copilot-chat/chat?prompt=...` form, which is
+ * the closest thing to a stable contract today.
+ */
+function buildDeepLinks(prompt: string): AssistantPrompt["deepLinks"] {
+  const enc = encodeURIComponent(prompt);
+  return {
+    cursor: `cursor://anysphere.cursor-deeplink/prompt?text=${enc}`,
+    claude: `https://claude.ai/new?q=${enc}`,
+    chatgpt: `https://chat.openai.com/?q=${enc}`,
+    vscode: `vscode://GitHub.copilot-chat/chat?prompt=${enc}`,
+  };
+}
+
+/**
+ * Render an assistant context + a small intent payload into the three
+ * surfaces every touchpoint needs: chat seed messages, copyable
+ * markdown, and per-agent deep links. Each Family A/B touchpoint is a
+ * one-liner around this function.
+ */
+export function buildAssistantPrompt(
+  context: AssistantContext,
+  intent: AssistantIntent,
+): AssistantPrompt {
+  const markdown = buildMarkdown(context, intent);
+  return {
+    markdown,
+    seedMessages: [{ role: "user", content: markdown }],
+    deepLinks: buildDeepLinks(markdown),
+  };
+}