handzon-core 0.15.4 → 0.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.15.4",
+  "version": "0.16.0",
   "description": "Core framework for Handzon — layouts, components, content + AI libs, and server runtime (handlers, DB, auth, migration runner) consumed by Handzon scaffolds.",
   "publishConfig": {
     "access": "public"

package/src/components/StepNav.astro

@@ -11,17 +11,20 @@ interface Props {
   currentStepSlug: string;
   gated: boolean;
   hasCheckpoint: boolean;
+  hasQuiz: boolean;
   nextTutorial?: TutorialSummary;
 }
 
-const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint, nextTutorial } = Astro.props;
+const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint, hasQuiz, nextTutorial } =
+  Astro.props;
 const idx = steps.findIndex((s) => parseStepId(s.id).stepSlug === currentStepSlug);
 const prev = idx > 0 ? steps[idx - 1] : null;
 const next = idx >= 0 && idx < steps.length - 1 ? steps[idx + 1] : null;
 const prevSlug = prev ? parseStepId(prev.id).stepSlug : null;
 const nextSlug = next ? parseStepId(next.id).stepSlug : null;
+const hasCompletionItem = hasCheckpoint || hasQuiz;
 ---
-<nav class:list={["step-nav", !next && "step-nav-final"]} data-gated={gated && hasCheckpoint ? "true" : "false"} data-step-key={`${tutorialSlug}/${currentStepSlug}`}>
+<nav class:list={["step-nav", !next && "step-nav-final"]} data-gated={gated && hasCompletionItem ? "true" : "false"} data-step-key={`${tutorialSlug}/${currentStepSlug}`}>
   <div>
     {prev && (
       <a class="sn-prev" href={withBase(`/${tutorialSlug}/${prevSlug}`)}>
@@ -32,7 +35,7 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
   <div class="sn-slot">
     {next ? (
       <a class="sn-next" href={withBase(`/${tutorialSlug}/${nextSlug}`)} data-next-link="true">
-        {hasCheckpoint ? "Continue" : "Next"}: {next.data.title} →
+        {hasCompletionItem ? "Continue" : "Next"}: {next.data.title} →
       </a>
     ) : (
       <TutorialCompletion
@@ -46,7 +49,7 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
 </nav>
 
 <script>
-  // Gating: if the host step contains a Checkpoint AND tutorial is gated,
+  // Gating: if the host step contains a completion item AND tutorial is gated,
   // disable Next until the step is marked complete.
   import { getStore } from "../lib/progress/local";
   const nav = document.querySelector<HTMLElement>(".step-nav");

package/src/components/mdx/Checkpoint.tsx

@@ -15,34 +15,19 @@ interface Props {
   id?: string;
 }
 
-/**
- * Reads the host tutorial/step from the page-level route marker
- * (<div id="tt-route" data-tutorial-slug=... data-step-slug=...>) that
- * TutorialLayout emits. Looking it up here keeps the Astro wrapper trivial.
- */
-function useRoute() {
-  const [route, setRoute] = useState<{ tutorial: string; step: string } | null>(null);
-  useEffect(() => {
-    const el = document.getElementById("tt-route");
-    if (!el) return;
-    const tutorial = el.dataset.tutorialSlug;
-    const step = el.dataset.stepSlug;
-    if (tutorial && step) setRoute({ tutorial, step });
-  }, []);
-  return route;
-}
-
 export default function Checkpoint({ label, id }: Props) {
   const reactId = useId();
   const checkpointId = id ?? `checkpoint:${reactId}:${label.slice(0, 40)}`;
-  const { state, recordCheckpoint, removeCheckpoint, markStepComplete, markStepIncomplete } =
-    useProgress();
-  const route = useRoute();
+  const { state, recordCheckpoint, removeCheckpoint } = useProgress();
   const done = !!state.checkpoints[checkpointId];
   const aiEnabled = useAiEnabled();
   const [stuck, setStuck] = useState(false);
   const rootRef = useRef<HTMLDivElement>(null);
 
+  useEffect(() => {
+    document.dispatchEvent(new CustomEvent("hz:step-item"));
+  }, []);
+
   // 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
@@ -75,11 +60,9 @@ export default function Checkpoint({ label, id }: Props) {
   function onToggle() {
     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.
@@ -91,7 +74,11 @@ export default function Checkpoint({ label, id }: Props) {
   const showFeedback = !done && feedback && !feedback.pass;
 
   return (
-    <div ref={rootRef} className={done ? "checkpoint is-done" : "checkpoint"}>
+    <div
+      ref={rootRef}
+      className={done ? "checkpoint is-done" : "checkpoint"}
+      data-checkpoint-id={checkpointId}
+    >
       <button type="button" onClick={onToggle} aria-pressed={done}>
         <span className="checkpoint-box">{done && <Check size={16} />}</span>
         <span>{label}</span>

package/src/components/mdx/Mermaid.tsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from "react";
+import { buildMermaidConfig } from "../../lib/mermaid-theme.ts";
 
 interface Props {
   chart: string;
@@ -19,7 +20,7 @@ export default function Mermaid({ chart, id }: Props) {
     (async () => {
       try {
         const mermaid = (await import("mermaid")).default;
-        mermaid.initialize({ startOnLoad: false, theme: "dark", securityLevel: "strict" });
+        mermaid.initialize(buildMermaidConfig());
         const { svg } = await mermaid.render(
           id ?? `mermaid-${Math.random().toString(36).slice(2)}`,
           chart,

package/src/components/mdx/Quiz.tsx

@@ -1,5 +1,5 @@
 import { Check, X } from "lucide-react";
-import { useId, useState } from "react";
+import { useEffect, useId, useState } from "react";
 import { dispatchAssist, useAiEnabled } from "../../lib/ai/assist";
 import { useProgress } from "../../lib/progress/useProgress";
 
@@ -25,6 +25,10 @@ export default function Quiz({ question, options, answer, explanation, id, multi
   const correctSet = new Set(Array.isArray(answer) ? answer : [answer]);
   const expectMulti = multi ?? Array.isArray(answer);
 
+  useEffect(() => {
+    document.dispatchEvent(new CustomEvent("hz:step-item"));
+  }, []);
+
   function toggle(i: number) {
     if (submitted) return;
     if (expectMulti) {
@@ -47,7 +51,7 @@ export default function Quiz({ question, options, answer, explanation, id, multi
   }
 
   return (
-    <fieldset className="quiz" disabled={submitted}>
+    <fieldset className="quiz" data-quiz-id={questionId} disabled={submitted}>
       <legend className="quiz-q">{question}</legend>
       <div className="quiz-options">
         {options.map((opt, i) => {

package/src/layouts/BaseLayout.astro

@@ -140,11 +140,33 @@ const socialImageUrl = ogImageUrl ? withBase(ogImageUrl) : undefined;
       />
     )}
     <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" });
+      // Render any <pre class="mermaid"> blocks emitted by rehype-mermaid,
+      // themed to match the active site palette (see lib/mermaid-theme).
+      //
+      // We capture each block's source synchronously (this module runs before
+      // the window `load` event) and render explicitly rather than calling
+      // mermaid.run(). mermaid auto-runs on `load` with its default theme, and
+      // on a fast load that race can win and mark nodes data-processed before
+      // our dynamic import resolves — leaving unthemed diagrams. Rendering each
+      // block ourselves from the captured source sidesteps that entirely.
+      const mermaidBlocks = Array.from(document.querySelectorAll("pre.mermaid"));
+      if (mermaidBlocks.length > 0) {
+        const sources = mermaidBlocks.map((el) => el.textContent ?? "");
+        Promise.all([
+          import("mermaid"),
+          import("handzon-core/lib/mermaid-theme.ts"),
+        ]).then(async ([{ default: mermaid }, { buildMermaidConfig }]) => {
+          mermaid.startOnLoad = false;
+          mermaid.initialize(buildMermaidConfig());
+          for (let i = 0; i < mermaidBlocks.length; i++) {
+            try {
+              const { svg } = await mermaid.render(`hz-mermaid-${i}`, sources[i]);
+              mermaidBlocks[i].innerHTML = svg;
+              mermaidBlocks[i].setAttribute("data-processed", "true");
+            } catch (err) {
+              console.error("Mermaid render failed", err);
+            }
+          }
         });
       }
     </script>

package/src/layouts/TutorialLayout.astro

@@ -13,6 +13,7 @@ interface Props {
   currentStep: StepEntry;
   currentStepSlug: string;
   hasCheckpoint?: boolean;
+  hasQuiz?: boolean;
   siteName?: string;
   tagline?: string;
   logoUrl?: string;
@@ -33,6 +34,7 @@ const {
   currentStep,
   currentStepSlug,
   hasCheckpoint = false,
+  hasQuiz = false,
   siteName,
   tagline,
   logoUrl,
@@ -120,6 +122,7 @@ const trackBootstrap =
         currentStepSlug={currentStepSlug}
         gated={tutorial.data.gated}
         hasCheckpoint={hasCheckpoint}
+        hasQuiz={hasQuiz}
         nextTutorial={nextTutorial}
       />
 
@@ -166,10 +169,13 @@ const trackBootstrap =
     // dynamic import("~/...") bypasses Vite's resolver and the browser
     // can't load the module.
     import { getStore } from "../lib/progress/local";
+    import { deriveStepCompletion } from "../lib/progress/stepCompletion";
+    import type { StepKey } from "../lib/progress/types";
     const route = document.getElementById("tt-route");
     if (route) {
       const tutorialSlug = route.dataset.tutorialSlug!;
       const stepSlug = route.dataset.stepSlug!;
+      const stepKey = `${tutorialSlug}/${stepSlug}` as StepKey;
       const tutorialSteps = JSON.parse(
         route.dataset.tutorialSteps ?? "[]",
       ) as string[];
@@ -200,6 +206,34 @@ const trackBootstrap =
         };
       });
 
+      function readCompletionItemIds(selector: string, attr: string) {
+        const activeTrack = document.documentElement.dataset.track;
+        const ids = Array.from(document.querySelectorAll<HTMLElement>(selector))
+          .map((el) => {
+            const trackPanel = el.closest<HTMLElement>("[data-track-panel]");
+            if (activeTrack && trackPanel?.dataset.trackPanel !== activeTrack) return null;
+            return el.dataset[attr];
+          })
+          .filter((id): id is string => !!id);
+        return Array.from(new Set(ids));
+      }
+
+      function recomputeStepCompletion() {
+        const completion = deriveStepCompletion(store.get(), {
+          quizIds: readCompletionItemIds("[data-quiz-id]", "quizId"),
+          checkpointIds: readCompletionItemIds("[data-checkpoint-id]", "checkpointId"),
+        });
+        if (completion === null) return;
+        store.set((s) => {
+          if (s.steps[stepKey] === completion) return s;
+          return { ...s, steps: { ...s.steps, [stepKey]: completion } };
+        });
+      }
+
+      recomputeStepCompletion();
+      document.addEventListener("hz:step-item", recomputeStepCompletion);
+      store.subscribe(recomputeStepCompletion);
+
       // 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

package/src/lib/mermaid-theme.ts

@@ -0,0 +1,130 @@
+import type { MermaidConfig } from "mermaid";
+
+/**
+ * Browser-only helpers that derive a Mermaid configuration from the active
+ * theme's CSS custom properties. Mermaid bakes colors into the rendered SVG
+ * and runs color math (via khroma) on its theme variables, so we cannot hand
+ * it raw `var(--token)` references or `oklch()` strings. Instead we read the
+ * computed token values and normalize each to a hex/rgb string the renderer
+ * can manipulate, then feed Mermaid's `base` theme so diagrams inherit the
+ * site palette, fonts, and light/dark mode rather than Mermaid's stock theme.
+ */
+
+/**
+ * Normalize any CSS color string (including `oklch()`) to a `#rrggbb` string.
+ * We rasterize one pixel and read the bytes back rather than reading
+ * `ctx.fillStyle`, because Chromium re-serializes `oklch()` as `oklch()` and
+ * Mermaid's color library (khroma) only understands hex/rgb/hsl. Reading the
+ * pixel forces a concrete sRGB value the renderer can manipulate. Returns the
+ * fallback when the value is empty or the browser cannot parse it.
+ */
+function resolveColor(value: string, fallback: string): string {
+  const input = value.trim();
+  if (!input) return fallback;
+  const ctx = document.createElement("canvas").getContext("2d", {
+    willReadFrequently: true,
+  });
+  if (!ctx) return fallback;
+  // Seed with a sentinel; if the input is rejected the pixel stays this value.
+  ctx.fillStyle = "#ff00ff";
+  ctx.fillRect(0, 0, 1, 1);
+  ctx.fillStyle = input;
+  if (ctx.fillStyle === "#ff00ff" && input.toLowerCase() !== "#ff00ff") {
+    return fallback;
+  }
+  ctx.fillRect(0, 0, 1, 1);
+  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+  const hex = (n: number) => n.toString(16).padStart(2, "0");
+  return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+
+/** Relative luminance (0–1) of a `#rrggbb` color, for dark-mode detection. */
+function luminance(hex: string): number {
+  const m = /^#([0-9a-f]{6})$/i.exec(hex);
+  if (!m) return 0;
+  const int = parseInt(m[1], 16);
+  const channel = (c: number) => {
+    const s = c / 255;
+    return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+  };
+  const r = channel((int >> 16) & 0xff);
+  const g = channel((int >> 8) & 0xff);
+  const b = channel(int & 0xff);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** Build a Mermaid config from the document's active theme tokens. */
+export function buildMermaidConfig(): MermaidConfig {
+  const cs = getComputedStyle(document.documentElement);
+  const token = (name: string) => cs.getPropertyValue(name).trim();
+  const color = (name: string, fallback: string) => resolveColor(token(name), fallback);
+
+  const bg = color("--color-bg", "#0a0a0a");
+  const surface = color("--color-surface", "#16181d");
+  const surface2 = color("--color-surface-2", surface);
+  const fg = color("--color-fg", "#f5f5f5");
+  const muted = color("--color-muted", "#9ca3af");
+  const border = color("--color-border", "#3a3a3a");
+  const borderStrong = color("--color-border-strong", border);
+  const accent = color("--color-accent", "#8b5cf6");
+  const accentFg = color("--color-accent-fg", "#ffffff");
+
+  const fontFamily = token("--font-sans") || "ui-sans-serif, system-ui, sans-serif";
+  const darkMode = luminance(bg) < 0.5;
+
+  return {
+    startOnLoad: false,
+    securityLevel: "strict",
+    theme: "base",
+    fontFamily,
+    themeVariables: {
+      darkMode,
+      background: surface,
+      fontFamily,
+      // Nodes
+      primaryColor: surface2,
+      primaryTextColor: fg,
+      primaryBorderColor: accent,
+      secondaryColor: surface,
+      secondaryTextColor: fg,
+      secondaryBorderColor: border,
+      tertiaryColor: surface,
+      tertiaryTextColor: fg,
+      tertiaryBorderColor: border,
+      mainBkg: surface2,
+      nodeBorder: accent,
+      nodeTextColor: fg,
+      // Edges + general text
+      lineColor: borderStrong,
+      textColor: fg,
+      titleColor: fg,
+      edgeLabelBackground: surface,
+      // Clusters / subgraphs
+      clusterBkg: surface,
+      clusterBorder: border,
+      // Notes
+      noteBkgColor: surface2,
+      noteTextColor: fg,
+      noteBorderColor: accent,
+      // Sequence diagrams
+      actorBkg: surface2,
+      actorBorder: accent,
+      actorTextColor: fg,
+      actorLineColor: borderStrong,
+      signalColor: fg,
+      signalTextColor: fg,
+      labelBoxBkgColor: surface2,
+      labelBoxBorderColor: border,
+      labelTextColor: fg,
+      loopTextColor: fg,
+      activationBkgColor: accent,
+      activationBorderColor: accent,
+      // Accent emphasis
+      altBackground: surface,
+      errorBkgColor: surface2,
+      errorTextColor: muted,
+      // Keep the accent legible where Mermaid fills with it.
+      primaryColorText: accentFg,
+    },
+  };
+}

package/src/lib/progress/stepCompletion.ts

@@ -0,0 +1,20 @@
+import type { ProgressState } from "./types";
+
+export interface StepCompletionItems {
+  quizIds: string[];
+  checkpointIds: string[];
+}
+
+export type DerivedStepCompletion = "complete" | "incomplete" | null;
+
+export function deriveStepCompletion(
+  state: ProgressState,
+  { quizIds, checkpointIds }: StepCompletionItems,
+): DerivedStepCompletion {
+  if (quizIds.length === 0 && checkpointIds.length === 0) return null;
+
+  const allQuizzesCorrect = quizIds.every((id) => state.quizzes[id]?.correct === true);
+  const allCheckpointsDone = checkpointIds.every((id) => !!state.checkpoints[id]);
+
+  return allQuizzesCorrect && allCheckpointsDone ? "complete" : "incomplete";
+}

package/src/pages/TutorialStep.astro

@@ -52,6 +52,7 @@ const { Content } = await render(currentStep);
 
 const components = mdxComponents();
 const hasCheckpoint = currentStep.body?.includes("<Checkpoint") ?? false;
+const hasQuiz = currentStep.body?.includes("<Quiz") ?? false;
 const nextTutorial = tutorial.data.nextTutorial
   ? await getTutorialBySlug(tutorial.data.nextTutorial)
   : undefined;
@@ -76,6 +77,7 @@ const initialContext = buildContext({
   currentStep={currentStep}
   currentStepSlug={stepSlug}
   hasCheckpoint={hasCheckpoint}
+  hasQuiz={hasQuiz}
   siteName={siteName}
   tagline={tagline}
   logoUrl={logoUrl}

package/styles/components/mermaid.css

@@ -1,16 +1,31 @@
-/* Mermaid */
-.mermaid-wrap {
+/* Mermaid — diagram colors come from JS (lib/mermaid-theme) so the SVG
+ * inherits the active palette; this only frames the rendered diagram so it
+ * reads as part of the page rather than a floating image. */
+.mermaid-wrap,
+pre.mermaid {
   margin: 1.25rem 0;
   padding: 1rem;
   background: var(--color-surface);
+  border: var(--border-default, 1px) solid var(--color-border);
+  border-radius: var(--radius-md, 0);
   display: grid;
   place-items: center;
-  border-radius: 0;
   min-height: var(--mermaid-min-height, 14rem);
+  overflow-x: auto;
 }
-.mermaid-wrap :global(svg) { max-width: 100%; height: auto; }
-pre.mermaid {
-  min-height: var(--mermaid-min-height, 14rem);
+/* Before the client script runs, the raw fenced source sits inside
+ * pre.mermaid; keep it from flashing as monospace text. */
+pre.mermaid:not([data-processed]) {
+  color: transparent;
+}
+.mermaid-wrap :global(svg),
+pre.mermaid svg {
+  max-width: 100%;
+  height: auto;
+}
+.mermaid-wrap :global(svg) text,
+pre.mermaid svg text {
+  font-family: var(--font-sans);
 }
 .mermaid-error {
   padding: 0.75rem;