handzon-core 0.7.0 → 0.8.0

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

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

package/src/lib/ai/stepData.ts

@@ -0,0 +1,74 @@
+import type { AssistantContext } from "./context";
+
+/**
+ * Reads the per-step JSON payload that TutorialLayout emits into
+ * `<script id="tt-step-data" type="application/json">`. Family B
+ * touchpoints (CopyPrompt, deep-link row, copy-step button, …) need
+ * the raw MDX source and tutorial/step titles at click time without
+ * having every island accept them as props.
+ */
+export interface StepData {
+  tutorialSlug: string;
+  tutorialTitle: string;
+  stepSlug: string;
+  stepTitle: string;
+  stepSource: string;
+}
+
+export function readStepData(): StepData | null {
+  if (typeof document === "undefined") return null;
+  const node = document.getElementById("tt-step-data");
+  if (!node?.textContent) return null;
+  try {
+    return JSON.parse(node.textContent) as StepData;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Render a CopyPrompt template by substituting `{{placeholder}}`
+ * tokens with the values from step data. Unknown placeholders are
+ * left untouched so authors notice typos.
+ */
+export function renderTemplate(template: string, data: StepData): string {
+  const map: Record<string, string> = {
+    tutorialTitle: data.tutorialTitle,
+    tutorialSlug: data.tutorialSlug,
+    stepTitle: data.stepTitle,
+    stepSlug: data.stepSlug,
+    stepSource: data.stepSource,
+  };
+  return template.replace(/\{\{\s*(\w+)\s*\}\}/g, (raw, key) => {
+    return key in map ? map[key] : raw;
+  });
+}
+
+/**
+ * Construct a minimal AssistantContext from client-side step data
+ * for Family B touchpoints that need to call buildAssistantPrompt
+ * without the build-time context that ChatButton holds. Fields we
+ * don't know client-side (difficulty, tags, outline, prior steps,
+ * progress) come back empty; the intents that Family B uses
+ * (explainStep, recap) only read tutorial + currentStep.
+ */
+export function contextFromStepData(data: StepData): AssistantContext {
+  return {
+    tutorial: {
+      slug: data.tutorialSlug,
+      title: data.tutorialTitle,
+      description: "",
+      difficulty: "",
+      tags: [],
+    },
+    outline: [],
+    currentStep: {
+      slug: data.stepSlug,
+      title: data.stepTitle,
+      source: data.stepSource,
+    },
+    priorSteps: [],
+    progress: { completed: [], quizzes: [], checkpoints: [] },
+    references: [],
+  };
+}

package/src/lib/mdx-components.ts

@@ -1,10 +1,12 @@
 import Callout from "../components/mdx/Callout.astro";
 import Checkpoint from "../components/mdx/Checkpoint.astro";
+import CopyPrompt from "../components/mdx/CopyPrompt.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 HelpMe from "../components/mdx/HelpMe.astro";
 import Hint from "../components/mdx/Hint.astro";
 import Mermaid from "../components/mdx/Mermaid.astro";
 import Playground from "../components/mdx/Playground.astro";
@@ -43,5 +45,7 @@ export function mdxComponents() {
     Quiz,
     Checkpoint,
     Playground,
+    HelpMe,
+    CopyPrompt,
   };
 }