handzon-core 0.6.0

package/src/components/ai/ByokSetup.tsx

@@ -0,0 +1,90 @@
+import * as Dialog from "@radix-ui/react-dialog";
+import { X } from "lucide-react";
+import { useState } from "react";
+import { saveLearnerKey } from "../../lib/ai/client";
+
+interface Props {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  provider: string;
+  assistantName: string;
+  onKeySaved?: () => void;
+}
+
+const PROVIDER_INFO: Record<string, { label: string; href: string }> = {
+  anthropic: { label: "Anthropic (Claude)", href: "https://console.anthropic.com/settings/keys" },
+  openai: { label: "OpenAI", href: "https://platform.openai.com/api-keys" },
+  google: { label: "Google AI Studio", href: "https://aistudio.google.com/app/apikey" },
+  "openai-compatible": { label: "OpenAI-compatible", href: "" },
+};
+
+export default function ByokSetup({
+  open,
+  onOpenChange,
+  provider,
+  assistantName,
+  onKeySaved,
+}: Props) {
+  const [key, setKey] = useState("");
+  const info = PROVIDER_INFO[provider] ?? { label: provider, href: "" };
+
+  function save() {
+    if (!key.trim()) return;
+    saveLearnerKey(provider, key.trim());
+    setKey("");
+    onOpenChange(false);
+    onKeySaved?.();
+  }
+
+  return (
+    <Dialog.Root open={open} onOpenChange={onOpenChange}>
+      <Dialog.Portal>
+        <Dialog.Overlay className="ms-overlay" />
+        <Dialog.Content className="byok-panel">
+          <Dialog.Close asChild>
+            <button type="button" className="ms-close" aria-label="Close">
+              <X size={18} />
+            </button>
+          </Dialog.Close>
+          <Dialog.Title>Set up {assistantName}</Dialog.Title>
+          <Dialog.Description className="byok-desc">
+            {assistantName} needs an API key to answer questions. The key is stored in this browser,
+            and sent over TLS to the assistant service with each question so it can call your chosen
+            model provider on your behalf. It is never written to a database or shared with other
+            learners.
+          </Dialog.Description>
+
+          {info.href && (
+            <p className="byok-link">
+              Get a {info.label} key →{" "}
+              <a href={info.href} target="_blank" rel="noopener noreferrer">
+                {info.href.replace(/^https?:\/\//, "")}
+              </a>
+            </p>
+          )}
+
+          <label className="byok-field">
+            <span>API key</span>
+            <input
+              type="password"
+              value={key}
+              onChange={(e) => setKey(e.target.value)}
+              placeholder="sk-..."
+            />
+          </label>
+
+          <div className="byok-actions">
+            <button type="button" onClick={save} disabled={!key.trim()}>
+              Save key
+            </button>
+          </div>
+
+          <p className="byok-disclaimer">
+            The assistant service forwards your key to {info.label} on each request and discards it
+            after the response. It is never logged or persisted server-side.
+          </p>
+        </Dialog.Content>
+      </Dialog.Portal>
+    </Dialog.Root>
+  );
+}

package/src/components/ai/ChatButton.tsx

@@ -0,0 +1,30 @@
+import { Sparkles } from "lucide-react";
+import { useState } from "react";
+import type { AiConfig } from "../../types/ai";
+import type { AssistantContext } from "../../lib/ai/context";
+import ChatPanel from "./ChatPanel";
+
+interface Props {
+  config: AiConfig;
+  context: AssistantContext;
+}
+
+export default function ChatButton({ config, context }: Props) {
+  const [open, setOpen] = useState(false);
+  if (!config.enabled) return null;
+
+  return (
+    <>
+      <button
+        type="button"
+        className="chat-fab"
+        onClick={() => 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} />
+    </>
+  );
+}

package/src/components/ai/ChatPanel.tsx

@@ -0,0 +1,244 @@
+import * as Dialog from "@radix-ui/react-dialog";
+import { KeyRound, Send, Settings, Sparkles, Trash2, X } from "lucide-react";
+import { useEffect, useRef, useState } from "react";
+import ReactMarkdown from "react-markdown";
+import remarkGfm from "remark-gfm";
+import type { AiConfig } from "../../types/ai";
+import { type ChatMessage, clearLearnerKey, loadLearnerKey, streamChat } from "../../lib/ai/client";
+import type { AssistantContext } from "../../lib/ai/context";
+import ByokSetup from "./ByokSetup";
+
+interface Props {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  config: AiConfig;
+  context: AssistantContext;
+}
+
+export default function ChatPanel({ open, onOpenChange, config, context }: 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 [input, setInput] = useState("");
+  const [streaming, setStreaming] = useState(false);
+  const [byokOpen, setByokOpen] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // Reactive copy of the stored BYOK key so the chat can show / hide its
+  // "set up your key" card without waiting for the learner to try to
+  // send a message. localStorage isn't readable on the server, hence
+  // the mount-time read instead of useState initialiser.
+  const [learnerKey, setLearnerKey] = useState<string | null>(null);
+  useEffect(() => {
+    setLearnerKey(loadLearnerKey(config.provider));
+  }, [config.provider]);
+  const needsKey = config.byok === "required" && !learnerKey;
+  const abortRef = useRef<AbortController | null>(null);
+  const listRef = useRef<HTMLDivElement>(null);
+
+  // Keep the latest message in view as chunks stream in (and on every
+  // send / clear). Without this, long responses scroll out of frame.
+  useEffect(() => {
+    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("");
+    setStreaming(true);
+    setError(null);
+
+    abortRef.current = new AbortController();
+    try {
+      const stream = await streamChat({
+        messages: next,
+        config,
+        context,
+        learnerKey: learnerKey ?? undefined,
+        signal: abortRef.current.signal,
+      });
+      // Delay adding the assistant message until the first chunk
+      // arrives so the thinking indicator (shown when the last
+      // message is from the user) stays visible during the wait.
+      let acc = "";
+      let assistantAdded = false;
+      const reader = stream.getReader();
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        acc += value;
+        if (!assistantAdded) {
+          setMessages((m) => [...m, { role: "assistant", content: acc }]);
+          assistantAdded = true;
+        } else {
+          setMessages((m) => {
+            const copy = m.slice();
+            copy[copy.length - 1] = { role: "assistant", content: acc };
+            return copy;
+          });
+        }
+      }
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      setError(msg);
+    } finally {
+      setStreaming(false);
+    }
+  }
+
+  function clear() {
+    setMessages([]);
+    setError(null);
+  }
+
+  function resetKey() {
+    clearLearnerKey(config.provider);
+    setLearnerKey(null);
+    setByokOpen(true);
+  }
+
+  return (
+    <>
+      {/*
+        modal={false}: the chat is a co-pilot, not a takeover. Removing
+        the overlay + focus trap lets the learner keep scrolling the
+        tutorial, clicking code blocks, and editing the playground
+        while the assistant is open. ESC still closes via Radix.
+      */}
+      <Dialog.Root open={open} onOpenChange={onOpenChange} modal={false}>
+        <Dialog.Portal>
+          <Dialog.Content
+            className="chat-panel"
+            aria-describedby={undefined}
+            onInteractOutside={(e) => e.preventDefault()}
+          >
+            <header className="chat-head">
+              <div className="chat-head-id">
+                <Sparkles size={16} className="chat-head-icon" aria-hidden="true" />
+                <div>
+                  <Dialog.Title className="chat-title">{config.name}</Dialog.Title>
+                  {config.tagline && <div className="chat-tagline">{config.tagline}</div>}
+                </div>
+              </div>
+              <div className="chat-head-actions">
+                {config.byok !== "disabled" && (
+                  <button type="button" title="Reset key" onClick={resetKey}>
+                    <Settings size={16} />
+                  </button>
+                )}
+                <button type="button" title="Clear chat" onClick={clear}>
+                  <Trash2 size={16} />
+                </button>
+                <Dialog.Close asChild>
+                  <button type="button" aria-label="Close">
+                    <X size={16} />
+                  </button>
+                </Dialog.Close>
+              </div>
+            </header>
+
+            <div className="chat-meta">
+              On: <strong>{context.currentStep.title}</strong>
+            </div>
+
+            {needsKey ? (
+              <div className="chat-setup" role="status">
+                <KeyRound size={22} aria-hidden="true" />
+                <h3>API key required</h3>
+                <p>
+                  {config.name} needs an API key to answer questions. Add one to get started —
+                  it's stored in this browser only.
+                </p>
+                <button type="button" onClick={() => setByokOpen(true)}>
+                  Set up key
+                </button>
+              </div>
+            ) : (
+              <div className="chat-list" ref={listRef}>
+                {messages.map((m, i) => (
+                  <div key={i} className={`chat-msg chat-msg-${m.role}`}>
+                    <span className="chat-role">{m.role === "user" ? "You" : config.name}</span>
+                    <div className="chat-content">
+                      {m.role === "assistant" ? (
+                        // react-markdown sanitizes by default (no raw HTML),
+                        // which matters because the assistant output is
+                        // untrusted. remark-gfm adds tables + strikethrough.
+                        <ReactMarkdown remarkPlugins={[remarkGfm]}>{m.content}</ReactMarkdown>
+                      ) : (
+                        m.content
+                      )}
+                    </div>
+                  </div>
+                ))}
+                {/*
+                  Show the thinking indicator while we're streaming AND the
+                  last message isn't yet from the assistant (i.e. we haven't
+                  received the first chunk that adds an empty assistant
+                  message to the array). Once chunks start landing, the
+                  message itself updates and the dots disappear.
+                */}
+                {streaming && messages[messages.length - 1]?.role !== "assistant" && (
+                  <div className="chat-msg chat-msg-assistant">
+                    <span className="chat-role">{config.name}</span>
+                    <div className="chat-content">
+                      <span className="chat-thinking" aria-label="Thinking">
+                        <span /> <span /> <span />
+                      </span>
+                    </div>
+                  </div>
+                )}
+                {error && <div className="chat-error">⚠ {error}</div>}
+              </div>
+            )}
+
+            <form
+              className="chat-input"
+              onSubmit={(e) => {
+                e.preventDefault();
+                void send();
+              }}
+            >
+              <input
+                value={input}
+                onChange={(e) => setInput(e.target.value)}
+                placeholder={needsKey ? "Add an API key to start chatting" : `Ask ${config.name}…`}
+                disabled={streaming || needsKey}
+              />
+              <button
+                type="submit"
+                disabled={streaming || needsKey || !input.trim()}
+                aria-label="Send"
+              >
+                <Send size={16} />
+              </button>
+            </form>
+          </Dialog.Content>
+        </Dialog.Portal>
+      </Dialog.Root>
+
+      <ByokSetup
+        open={byokOpen}
+        onOpenChange={setByokOpen}
+        provider={config.provider}
+        assistantName={config.name}
+        onKeySaved={() => setLearnerKey(loadLearnerKey(config.provider))}
+      />
+    </>
+  );
+}

package/src/components/auth/SignInButton.astro

@@ -0,0 +1,41 @@
+---
+/**
+ * Themed re-export of auth-astro's `SignIn` component. Use this when
+ * the bare SignIn needs styling consistent with the rest of the brutalist
+ * tokens — `UserMenu` already wraps this for you.
+ *
+ *   <SignInButton provider="github">Sign in with GitHub</SignInButton>
+ */
+import { SignIn } from "auth-astro/components";
+
+interface Props {
+  provider?: string;
+  className?: string;
+}
+
+const { provider = "github", className } = Astro.props;
+---
+<SignIn provider={provider} class:list={["sib", className]}>
+  <slot>Sign in</slot>
+</SignIn>
+
+<style is:global>
+  .sib {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+    padding: 0.45rem 0.85rem;
+    background: transparent;
+    color: var(--color-fg);
+    border: var(--border-default, 2px) solid var(--color-fg);
+    font-family: var(--font-mono);
+    font-size: 0.85em;
+    text-decoration: none;
+    cursor: pointer;
+  }
+  .sib:hover {
+    background: var(--color-accent);
+    color: var(--color-accent-fg);
+    border-color: var(--color-accent);
+  }
+</style>

package/src/components/auth/UserMenu.astro

@@ -0,0 +1,79 @@
+---
+/**
+ * Astro wrapper around the React UserMenu island. Auth state is
+ * fetched on the client (see UserMenu.tsx), so this component works
+ * the same on prerendered pages and SSR routes — no
+ * `Astro.request.headers` access at render time, no warning when a
+ * prerendered route happens to include BaseLayout.
+ */
+import UserMenuIsland from "./UserMenu.tsx";
+---
+<UserMenuIsland client:only="react" />
+
+<style is:global>
+  .user-menu {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-family: var(--font-mono);
+    font-size: 0.8em;
+  }
+  .um-avatar {
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    border: 1px solid var(--color-border);
+    display: inline-block;
+    object-fit: cover;
+    flex-shrink: 0;
+  }
+  .um-avatar-fallback {
+    background: color-mix(in oklab, var(--color-accent) 15%, var(--color-bg));
+    color: var(--color-accent);
+    font-weight: 700;
+    font-size: 0.75em;
+    display: inline-grid;
+    place-items: center;
+  }
+  .um-name {
+    color: var(--color-fg);
+    max-width: 12ch;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .user-menu form { display: inline-flex; }
+  .um-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.35rem;
+    padding: 0.3rem 0.65rem;
+    background: transparent;
+    color: var(--color-fg);
+    border: 1px solid var(--color-border);
+    font: inherit;
+    text-decoration: none;
+    cursor: pointer;
+  }
+  .um-btn:hover {
+    border-color: var(--color-accent);
+    color: var(--color-accent);
+  }
+  .um-btn-icon {
+    padding: 0.3rem 0.45rem;
+  }
+  .um-gh {
+    flex-shrink: 0;
+  }
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+</style>

package/src/components/auth/UserMenu.tsx

@@ -0,0 +1,136 @@
+import { useEffect, useState } from "react";
+
+/**
+ * Client-only auth menu. Fetches `/api/auth/session` + `/api/auth/csrf`
+ * on mount and renders either:
+ *  - signed-out: a "Sign in with GitHub" form-post button
+ *  - signed-in:  avatar + name + sign-out icon button
+ *  - nothing:    if the auth-astro integration isn't wired (the
+ *                endpoints 404), so dropping handzon-core into a Tier-1
+ *                scaffold doesn't surface dead UI
+ *
+ * Lives as a `client:only="react"` island instead of an Astro component
+ * so it works on prerendered pages too — Astro warns whenever a
+ * prerendered route accesses `Astro.request.headers`, which the old
+ * server-rendered UserMenu did transitively via auth-astro's
+ * `getSession`. With the data fetched on the client there's no SSR
+ * dependency on request state at all.
+ */
+
+interface SessionUser {
+  name?: string | null;
+  email?: string | null;
+  image?: string | null;
+}
+interface Session {
+  user?: SessionUser;
+}
+
+const GITHUB_ICON_PATH =
+  "M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.55v-2.02c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.03 1.76 2.7 1.25 3.36.96.1-.74.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.66 0-1.25.45-2.27 1.18-3.07-.12-.29-.51-1.45.11-3.03 0 0 .96-.31 3.15 1.17a10.94 10.94 0 0 1 5.76 0c2.19-1.48 3.15-1.17 3.15-1.17.62 1.58.23 2.74.11 3.03.74.8 1.18 1.82 1.18 3.07 0 4.4-2.69 5.37-5.25 5.65.41.35.78 1.04.78 2.11v3.13c0 .3.21.66.79.55C20.71 21.39 24 17.08 24 12 24 5.65 18.85.5 12 .5z";
+
+export default function UserMenu() {
+  // `undefined` = not yet loaded; `null` = no auth or signed out;
+  // object = signed in. The tri-state avoids flashing the sign-in
+  // button while the session fetch is in flight.
+  const [session, setSession] = useState<Session | null | undefined>(undefined);
+  const [csrfToken, setCsrfToken] = useState<string | null>(null);
+
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        const [sessRes, csrfRes] = await Promise.all([
+          fetch("/api/auth/session", { credentials: "same-origin" }),
+          fetch("/api/auth/csrf", { credentials: "same-origin" }),
+        ]);
+        if (cancelled) return;
+        // 404 → auth-astro integration not wired in this scaffold.
+        if (!sessRes.ok || !csrfRes.ok) {
+          setSession(null);
+          setCsrfToken(null);
+          return;
+        }
+        const sess = (await sessRes.json()) as Session | null;
+        const csrf = (await csrfRes.json()) as { csrfToken?: string } | null;
+        setSession(sess && sess.user ? sess : null);
+        setCsrfToken(csrf?.csrfToken ?? null);
+      } catch {
+        if (!cancelled) {
+          setSession(null);
+          setCsrfToken(null);
+        }
+      }
+    })();
+    return () => {
+      cancelled = true;
+    };
+  }, []);
+
+  // Loading or auth not wired → render nothing.
+  if (session === undefined || !csrfToken) return null;
+
+  const user = session?.user;
+  const callbackUrl = typeof window !== "undefined" ? window.location.href : "/";
+
+  return (
+    <div className="user-menu">
+      {user ? (
+        <>
+          {user.image ? (
+            <img
+              className="um-avatar"
+              src={user.image}
+              alt={user.name ?? user.email ?? "Signed in"}
+            />
+          ) : (
+            <span className="um-avatar um-avatar-fallback" aria-hidden="true">
+              {(user.name ?? user.email ?? "?").trim().charAt(0).toUpperCase()}
+            </span>
+          )}
+          <span className="um-name">{user.name ?? user.email ?? "Signed in"}</span>
+          <form method="post" action="/api/auth/signout">
+            <input type="hidden" name="csrfToken" value={csrfToken} />
+            <input type="hidden" name="callbackUrl" value={callbackUrl} />
+            <button type="submit" className="um-btn um-btn-icon" title="Sign out">
+              <svg
+                viewBox="0 0 24 24"
+                width="14"
+                height="14"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+                <polyline points="16 17 21 12 16 7" />
+                <line x1="21" y1="12" x2="9" y2="12" />
+              </svg>
+              <span className="sr-only">Sign out</span>
+            </button>
+          </form>
+        </>
+      ) : (
+        <form method="post" action="/api/auth/signin/github">
+          <input type="hidden" name="csrfToken" value={csrfToken} />
+          <input type="hidden" name="callbackUrl" value={callbackUrl} />
+          <button type="submit" className="um-btn">
+            <svg
+              className="um-gh"
+              viewBox="0 0 24 24"
+              width="14"
+              height="14"
+              fill="currentColor"
+              aria-hidden="true"
+            >
+              <path d={GITHUB_ICON_PATH} />
+            </svg>
+            <span>Sign in with GitHub</span>
+          </button>
+        </form>
+      )}
+    </div>
+  );
+}