handzon-core 0.6.0

package/src/components/mdx/Steps.astro

@@ -0,0 +1,40 @@
+---
+// Wraps an ordered list of <Step> items.
+---
+<ol class="steps"><slot /></ol>
+
+<style is:global>
+  .steps {
+    counter-reset: step;
+    list-style: none;
+    padding: 0;
+    margin: 1.5rem 0;
+    display: grid;
+    gap: 0.6rem;
+  }
+  .steps li.step {
+    counter-increment: step;
+    display: grid;
+    grid-template-columns: 2.25rem 1fr;
+    gap: 0.85rem;
+    align-items: baseline;
+    padding: 0.6rem 0.85rem;
+    border: var(--border-default, 2px) solid var(--color-border);
+    background: var(--color-surface);
+  }
+  .steps li.step::before {
+    content: counter(step, decimal-leading-zero);
+    font-family: var(--font-mono);
+    font-size: 0.85em;
+    font-weight: 700;
+    color: var(--color-accent);
+    letter-spacing: 0.04em;
+  }
+  .steps li.step > * {
+    margin: 0;
+  }
+  .steps li.step strong {
+    display: block;
+    margin-bottom: 0.15rem;
+  }
+</style>

package/src/components/mdx/Tab.astro

@@ -0,0 +1,22 @@
+---
+interface Props {
+  value: string;
+}
+const { value } = Astro.props;
+// The Tabs script toggles hidden based on data-tab-panel === active value.
+// First panel renders visible by default (matches Tabs.astro's initial state).
+---
+<div class="tut-tab-panel" data-tab-panel={value} hidden={false}>
+  <slot />
+</div>
+
+<script define:vars={{ value }}>
+  // First-load: hide non-initial panels. Tabs' script flips hidden on activation.
+  const panels = document.querySelectorAll(`[data-tab-panel="${value}"]`);
+  panels.forEach((panel) => {
+    const root = panel.closest("[data-tabs]");
+    if (root && root.dataset.active !== value) {
+      panel.hidden = true;
+    }
+  });
+</script>

package/src/components/mdx/Tabs.astro

@@ -0,0 +1,67 @@
+---
+interface TabItem {
+  label: string;
+  value: string;
+}
+
+interface Props {
+  items: TabItem[];
+  group?: string;
+}
+
+const { items, group } = Astro.props;
+const groupAttr = group ?? `tabs-${Math.random().toString(36).slice(2, 8)}`;
+const initial = items[0]?.value ?? "";
+---
+
+<div class="tut-tabs" data-tabs data-tab-group={groupAttr} data-active={initial}>
+  <div class="tut-tabs-list" role="tablist">
+    {
+      items.map((item, i) => (
+        <button
+          type="button"
+          role="tab"
+          class="tut-tabs-trigger"
+          data-tab-value={item.value}
+          data-active={i === 0 ? "true" : "false"}
+          aria-selected={i === 0}
+        >
+          {item.label}
+        </button>
+      ))
+    }
+  </div>
+  <div class="tut-tabs-content">
+    <slot />
+  </div>
+</div>
+
+<script>
+  const STORAGE_PREFIX = "handzon:tabs:";
+
+  function activate(root: HTMLElement, value: string) {
+    root.dataset.active = value;
+    root.querySelectorAll<HTMLElement>("[data-tab-value]").forEach((btn) => {
+      const isActive = btn.dataset.tabValue === value;
+      btn.dataset.active = isActive ? "true" : "false";
+      btn.setAttribute("aria-selected", String(isActive));
+    });
+    root.querySelectorAll<HTMLElement>("[data-tab-panel]").forEach((panel) => {
+      panel.hidden = panel.dataset.tabPanel !== value;
+    });
+  }
+
+  document.querySelectorAll<HTMLElement>("[data-tabs]").forEach((root) => {
+    const group = root.dataset.tabGroup ?? "";
+    const storageKey = group ? `${STORAGE_PREFIX}${group}` : null;
+    const saved = storageKey ? window.localStorage.getItem(storageKey) : null;
+    if (saved) activate(root, saved);
+    root.querySelectorAll<HTMLButtonElement>("[data-tab-value]").forEach((btn) => {
+      btn.addEventListener("click", () => {
+        const v = btn.dataset.tabValue!;
+        activate(root, v);
+        if (storageKey) window.localStorage.setItem(storageKey, v);
+      });
+    });
+  });
+</script>

package/src/components/mdx/Terminal.astro

@@ -0,0 +1,6 @@
+---
+import TerminalIsland from "./Terminal.tsx";
+type Props = Parameters<typeof TerminalIsland>[0];
+const props = Astro.props as Props;
+---
+<TerminalIsland client:visible {...props} />

package/src/components/mdx/Terminal.tsx

@@ -0,0 +1,47 @@
+import { useState } from "react";
+
+type Entry =
+  | { command: string; output?: string; prompt?: string }
+  | { output: string; prompt?: never; command?: never };
+
+interface Props {
+  entries: Entry[];
+  title?: string;
+  prompt?: string;
+}
+
+export default function Terminal({ entries, title = "Terminal", prompt = "$" }: Props) {
+  const [revealed, setRevealed] = useState(entries.length);
+
+  const visible = entries.slice(0, revealed);
+  return (
+    <div className="term">
+      <div className="term-bar">
+        <span className="term-dots" aria-hidden="true">
+          <span /> <span /> <span />
+        </span>
+        <span className="term-title">{title}</span>
+      </div>
+      <pre className="term-body">
+        {visible.map((entry, i) => (
+          <div key={i}>
+            {entry.command !== undefined && (
+              <div className="term-line">
+                <span className="term-prompt">{entry.prompt ?? prompt}</span>
+                <span>{entry.command}</span>
+              </div>
+            )}
+            {entry.output !== undefined && entry.output !== "" && (
+              <div className="term-out">{entry.output}</div>
+            )}
+          </div>
+        ))}
+      </pre>
+      {revealed < entries.length && (
+        <button type="button" className="term-run" onClick={() => setRevealed((r) => r + 1)}>
+          ▶ Next
+        </button>
+      )}
+    </div>
+  );
+}

package/src/index.ts

@@ -0,0 +1,55 @@
+/**
+ * Handzon framework — public API surface.
+ *
+ * .astro and .tsx components are NOT re-exported here; consumers import
+ * them by subpath (e.g. `import BaseLayout from "handzon-core/layouts/BaseLayout.astro"`).
+ * Astro can only resolve `.astro` files through the package's `exports`
+ * map, not through a barrel re-export, so this file ships only TS values
+ * and types.
+ */
+
+// Content collection helpers (built on top of astro:content).
+export {
+  parseStepId,
+  getTutorials,
+  getTutorialBySlug,
+  getStepsForTutorial,
+  getStep,
+  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 ProgressStore,
+} from "./lib/progress/types.ts";
+
+// AI config type (consumers provide concrete values; framework consumes shape).
+export type { AiConfig } from "./types/ai.ts";

package/src/layouts/BaseLayout.astro

@@ -0,0 +1,112 @@
+---
+import Footer from "../components/Footer.astro";
+import Navbar from "../components/Navbar.astro";
+import UserMenu from "../components/auth/UserMenu.astro";
+
+interface Props {
+  title?: string;
+  description?: string;
+  siteName?: string;
+  tagline?: string;
+  /**
+   * Top navigation mode:
+   *  - "full": Navbar with logo + UserMenu (default — every page).
+   *  - "userMenu": floating UserMenu only, no logo. For the homepage
+   *    where the Hero already shows the brand inline.
+   *  - "none": no nav at all.
+   */
+  nav?: "full" | "userMenu" | "none";
+  /** Logo URL passed to Navbar (when nav === "full"). */
+  logoUrl?: string;
+  /** Favicon URL injected into <head>. */
+  faviconUrl?: string;
+  /** Show the site footer ("Built with Handzon" + repo link). */
+  showFooter?: boolean;
+  /** Footer link URL; defaults to the Handzon repo. */
+  repoUrl?: string;
+  /**
+   * Width of the page's content column. Drives the navbar + footer
+   * alignment via the --hz-page-max-width CSS custom property so the
+   * top/bottom bars sit flush with whatever the page renders. Default
+   * "80rem" matches the home grid; reader-style pages can pass a
+   * narrower value (e.g. "56rem"). Pass "none" for full-width layouts
+   * like the tutorial step (sidebar + main, no centered column).
+   */
+  pageMaxWidth?: string;
+  /**
+   * Horizontal padding inside the navbar + footer. Defaults to
+   * clamp(1rem, 4vw, 2rem). Use a smaller value (e.g. "1rem") when
+   * the page itself sits flush against the viewport edge — tutorial
+   * step pages do this to line up with the sidebar.
+   */
+  pagePaddingX?: string;
+}
+const {
+  title,
+  description,
+  siteName = "Handzon",
+  tagline = "Hands-on tutorials",
+  nav = "full",
+  logoUrl = "/logo.svg",
+  faviconUrl = "/favicon.svg",
+  showFooter = true,
+  repoUrl,
+  // Default to a full-width navbar + footer with a small consistent
+  // inset, matching the tutorial step page. Pages with a centred
+  // column (home grid, tutorial landing) keep their own content
+  // column; the bars stay as site-wide strips.
+  pageMaxWidth = "none",
+  pagePaddingX = "1rem",
+} = Astro.props;
+// pageMaxWidth: "none" means no constraint — bars span the full
+// viewport width with just the padding.
+const resolvedMaxWidth = pageMaxWidth === "none" ? "none" : pageMaxWidth;
+const pageTitle = title ? `${title} — ${siteName}` : siteName;
+const desc = description ?? tagline;
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="icon" type="image/svg+xml" href={faviconUrl} />
+    <title>{pageTitle}</title>
+    <meta name="description" content={desc} />
+    <meta property="og:title" content={pageTitle} />
+    <meta property="og:description" content={desc} />
+    <meta property="og:type" content="website" />
+  </head>
+  <body style={`--hz-page-max-width: ${resolvedMaxWidth}; --hz-page-padding-x: ${pagePaddingX}; --hz-nav-height: 3rem;`}>
+    {nav === "full" && (
+      <Navbar logoUrl={logoUrl} siteName={siteName} />
+    )}
+    {nav === "userMenu" && (
+      <div class="hz-topbar">
+        <UserMenu />
+      </div>
+    )}
+    <slot />
+    {showFooter && <Footer repoUrl={repoUrl} />}
+    <script>
+      // Render any <pre class="mermaid"> blocks emitted by rehype-mermaid.
+      if (document.querySelector("pre.mermaid")) {
+        import("mermaid").then(({ default: mermaid }) => {
+          mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict" });
+          mermaid.run({ querySelector: "pre.mermaid" });
+        });
+      }
+    </script>
+
+    <style is:global>
+      .hz-topbar {
+        position: fixed;
+        top: 0.75rem;
+        right: 0.9rem;
+        z-index: 50;
+      }
+      .hz-topbar:empty {
+        display: none;
+      }
+    </style>
+  </body>
+</html>

package/src/layouts/TutorialLayout.astro

@@ -0,0 +1,218 @@
+---
+import BaseLayout from "./BaseLayout.astro";
+import Sidebar from "../components/Sidebar.astro";
+import StepNav from "../components/StepNav.astro";
+import { parseStepId } from "../lib/content.ts";
+import type { TutorialEntry, StepEntry } from "../lib/content";
+
+interface Props {
+  tutorial: TutorialEntry;
+  steps: StepEntry[];
+  currentStep: StepEntry;
+  currentStepSlug: string;
+  hasCheckpoint?: boolean;
+  siteName?: string;
+  tagline?: string;
+  logoUrl?: string;
+  faviconUrl?: string;
+  repoUrl?: string;
+}
+
+const {
+  tutorial,
+  steps,
+  currentStep,
+  currentStepSlug,
+  hasCheckpoint = false,
+  siteName,
+  tagline,
+  logoUrl,
+  faviconUrl,
+  repoUrl,
+} = Astro.props;
+
+const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
+---
+<BaseLayout
+  title={`${currentStep.data.title} — ${tutorial.data.title}`}
+  description={currentStep.data.summary}
+  siteName={siteName}
+  tagline={tagline}
+  logoUrl={logoUrl}
+  faviconUrl={faviconUrl}
+  repoUrl={repoUrl}
+>
+  <div class="layout">
+    <div class="sidebar-wrap">
+      <Sidebar tutorial={tutorial} steps={steps} currentStepSlug={currentStepSlug} />
+    </div>
+
+    <main class="main">
+      <header class="step-head">
+        <div class="crumb">{tutorial.data.title}</div>
+        <h1 class="step-title">{currentStep.data.title}</h1>
+        {currentStep.data.duration && (
+          <div class="step-dur">⏱ {currentStep.data.duration}</div>
+        )}
+      </header>
+
+      <article class="prose">
+        <slot />
+      </article>
+
+      <StepNav
+        tutorialSlug={tutorial.id}
+        steps={steps}
+        currentStepSlug={currentStepSlug}
+        gated={tutorial.data.gated}
+        hasCheckpoint={hasCheckpoint}
+      />
+
+      {tutorial.data.feedbackUrl && (
+        <footer class="step-foot">
+          <a href={tutorial.data.feedbackUrl} target="_blank" rel="noopener">
+            Report an issue with this tutorial →
+          </a>
+        </footer>
+      )}
+    </main>
+  </div>
+
+  <div
+    id="tt-route"
+    data-tutorial-slug={tutorial.id}
+    data-step-slug={currentStepSlug}
+    data-tutorial-steps={JSON.stringify(stepSlugs)}
+    hidden
+  ></div>
+  <script>
+    // Record last-visited + popularity markers from a data marker
+    // (set in the markup above). Using a normal <script> + relative
+    // import so Vite resolves the path alias correctly; define:vars +
+    // dynamic import("~/...") bypasses Vite's resolver and the browser
+    // can't load the module.
+    import { getStore } from "../lib/progress/local";
+    const route = document.getElementById("tt-route");
+    if (route) {
+      const tutorialSlug = route.dataset.tutorialSlug!;
+      const stepSlug = route.dataset.stepSlug!;
+      const tutorialSteps = JSON.parse(
+        route.dataset.tutorialSteps ?? "[]",
+      ) as string[];
+      const store = getStore();
+
+      // Mark last-visited + tutorial "started" on every mount. The
+      // started branch is idempotent: it only writes the timestamp the
+      // first time per learner, so /api/progress sees one POST per
+      // tutorial — not one per page view.
+      store.set((s) => {
+        const nextLastVisited = {
+          ...s.lastVisited,
+          [tutorialSlug]: { step: stepSlug, ts: Date.now() },
+        };
+        if (s.tutorials[tutorialSlug]?.started) {
+          return { ...s, lastVisited: nextLastVisited };
+        }
+        return {
+          ...s,
+          lastVisited: nextLastVisited,
+          tutorials: {
+            ...s.tutorials,
+            [tutorialSlug]: {
+              ...s.tutorials[tutorialSlug],
+              started: Date.now(),
+            },
+          },
+        };
+      });
+
+      // Watch for tutorial completion: once every step in the embedded
+      // list flips to "complete", record the "completed" event exactly
+      // once. Re-runs on store changes so finishing the last step on a
+      // mid-tutorial page (rare) still triggers it.
+      function checkCompletion() {
+        const s = store.get();
+        if (s.tutorials[tutorialSlug]?.completed) return;
+        if (tutorialSteps.length === 0) return;
+        const allDone = tutorialSteps.every(
+          (slug) => s.steps[`${tutorialSlug}/${slug}` as `${string}/${string}`] === "complete",
+        );
+        if (allDone) {
+          store.set((cur) => ({
+            ...cur,
+            tutorials: {
+              ...cur.tutorials,
+              [tutorialSlug]: {
+                ...cur.tutorials[tutorialSlug],
+                completed: Date.now(),
+              },
+            },
+          }));
+        }
+      }
+      checkCompletion();
+      store.subscribe(checkCompletion);
+    }
+  </script>
+</BaseLayout>
+
+<style>
+  /* Draw the sidebar/main divider as a background line on the grid
+   * itself: 1px-thin vertical strip at the 280px 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. */
+  .layout {
+    display: grid;
+    grid-template-columns: 280px minmax(0, 1fr);
+    min-height: 100dvh;
+    background: linear-gradient(
+      to right,
+      transparent 280px,
+      var(--color-border) 280px,
+      var(--color-border) 281px,
+      transparent 281px
+    ) no-repeat;
+  }
+  .sidebar-wrap {
+    position: sticky;
+    top: var(--hz-nav-height, 3rem);
+    height: calc(100dvh - var(--hz-nav-height, 3rem));
+  }
+  .main {
+    padding: 2rem clamp(1rem, 4vw, 3rem);
+    max-width: 80ch;
+  }
+  .crumb {
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--color-muted);
+  }
+  .step-title {
+    font-size: clamp(1.75rem, 3vw, 2.25rem);
+    font-weight: 700;
+    margin: 0.3rem 0 0.5rem;
+    letter-spacing: -0.02em;
+    line-height: 1.15;
+  }
+  .step-dur {
+    font-family: var(--font-mono);
+    font-size: 0.85em;
+    color: var(--color-muted);
+  }
+  .step-head { margin-bottom: 1.5rem; padding-bottom: 1.5rem; border-bottom: var(--border-default, 2px) solid var(--color-border); }
+  .step-foot {
+    margin-top: 3rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--color-border);
+    font-size: 0.85em;
+    color: var(--color-muted);
+  }
+  @media (max-width: 900px) {
+    .layout { grid-template-columns: 1fr; }
+    .sidebar-wrap { display: none; }
+  }
+</style>

package/src/lib/ai/client.ts

@@ -0,0 +1,92 @@
+import type { AiConfig } from "../../types/ai";
+import type { AssistantContext } from "./context";
+
+export interface ChatMessage {
+  role: "user" | "assistant";
+  content: string;
+}
+
+interface ChatRequestOptions {
+  messages: ChatMessage[];
+  config: AiConfig;
+  context: AssistantContext;
+  learnerKey?: string;
+  signal?: AbortSignal;
+}
+
+/**
+ * Render's `fromService.property: host` returns a bare private-network
+ * hostname (e.g. "myproject-ai-abc"). The browser needs a public URL.
+ * Treat the env value as a hostname unless it already includes a scheme
+ * — that lets local dev pass `http://localhost:4111` directly.
+ */
+function resolveServiceUrl(raw: string): string {
+  const trimmed = raw.replace(/\/$/, "");
+  if (/^https?:\/\//i.test(trimmed)) return trimmed;
+  return `https://${trimmed}.onrender.com`;
+}
+
+/**
+ * POST to the Mastra service. Reads the service URL from
+ * import.meta.env.PUBLIC_AI_SERVICE_URL at build time. Streams plain text
+ * chunks via fetch's streaming response body.
+ */
+export async function streamChat(opts: ChatRequestOptions): Promise<ReadableStream<string>> {
+  const rawServiceUrl = import.meta.env.PUBLIC_AI_SERVICE_URL;
+  if (!rawServiceUrl) throw new Error("PUBLIC_AI_SERVICE_URL is not set.");
+  const serviceUrl = resolveServiceUrl(rawServiceUrl);
+
+  const headers: Record<string, string> = { "Content-Type": "application/json" };
+  if (opts.learnerKey) headers["X-Llm-Api-Key"] = opts.learnerKey;
+
+  const payload = {
+    tutorial: opts.context.tutorial,
+    outline: opts.context.outline,
+    currentStep: opts.context.currentStep,
+    priorSteps: opts.context.priorSteps,
+    progress: opts.context.progress,
+    references: opts.context.references,
+    allowedDomains: opts.config.allowedDomains ?? [],
+  };
+
+  const res = await fetch(`${serviceUrl}/chat`, {
+    method: "POST",
+    headers,
+    signal: opts.signal,
+    body: JSON.stringify({
+      messages: opts.messages,
+      config: {
+        provider: opts.config.provider,
+        model: opts.config.model,
+        name: opts.config.name,
+        tone: opts.config.tone,
+        persona: opts.config.persona,
+        disabledSkills: opts.config.disabledSkills,
+      },
+      payload,
+    }),
+  });
+
+  if (!res.ok) {
+    const text = await res.text();
+    throw new Error(`Chat service error ${res.status}: ${text}`);
+  }
+  if (!res.body) throw new Error("No response body from chat service.");
+
+  return res.body.pipeThrough(new TextDecoderStream());
+}
+
+const KEY_STORAGE_PREFIX = "handzon:byok:";
+
+export function loadLearnerKey(provider: string): string | null {
+  if (typeof window === "undefined") return null;
+  return window.localStorage.getItem(`${KEY_STORAGE_PREFIX}${provider}`);
+}
+
+export function saveLearnerKey(provider: string, key: string): void {
+  window.localStorage.setItem(`${KEY_STORAGE_PREFIX}${provider}`, key);
+}
+
+export function clearLearnerKey(provider: string): void {
+  window.localStorage.removeItem(`${KEY_STORAGE_PREFIX}${provider}`);
+}