handzon-core 0.12.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.12.1",
+  "version": "0.13.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/collections.ts

@@ -19,10 +19,15 @@ import { readdir, readFile } from "node:fs/promises";
 import { join, relative, resolve } from "node:path";
 import type { Loader } from "astro/loaders";
 import { glob } from "astro/loaders";
+import { createHeroMediaSchema } from "./lib/heroMedia";
 
 const TUTORIALS_REL = "src/content/tutorials";
 const INDEX_FILE = "_index.json";
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
 async function readIndexOrder(dir: string): Promise<string[]> {
   try {
     const raw = await readFile(join(dir, INDEX_FILE), "utf8");
@@ -35,6 +40,114 @@ async function readIndexOrder(dir: string): Promise<string[]> {
   }
 }
 
+async function readTutorialTrackIds(tutorialSlug: string): Promise<string[]> {
+  try {
+    const raw = await readFile(join(resolve(TUTORIALS_REL), tutorialSlug, "_meta.json"), "utf8");
+    const parsed = JSON.parse(raw) as { tracks?: unknown };
+    return Array.isArray(parsed.tracks)
+      ? parsed.tracks
+          .map((track) => (isRecord(track) && typeof track.id === "string" ? track.id : null))
+          .filter((id): id is string => !!id)
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+function isStarterSpec(value: unknown): value is StarterSpec {
+  return isRecord(value) && typeof value.kind === "string";
+}
+
+function isVerifySpec(value: unknown): value is VerifySpec {
+  return isRecord(value) && typeof value.id === "string" && Array.isArray(value.checks);
+}
+
+function isTrackMap<T>(
+  value: TrackScoped<T> | undefined,
+  isShared: (v: unknown) => v is T,
+): value is TrackMap<T> {
+  return isRecord(value) && !isShared(value);
+}
+
+function validateTrackMapCoverage<T>({
+  entryId,
+  label,
+  map,
+  trackIds,
+}: {
+  entryId: string;
+  label: string;
+  map: TrackMap<T>;
+  trackIds: string[];
+}) {
+  if (trackIds.length === 0) {
+    throw new Error(
+      `[handzon] ${entryId}: ${label} is keyed by track, but the tutorial declares no tracks.`,
+    );
+  }
+  const declared = new Set(trackIds);
+  const actual = Object.keys(map);
+  const unknown = actual.filter((id) => !declared.has(id));
+  const missing = trackIds.filter((id) => !(id in map));
+  if (unknown.length > 0 || missing.length > 0) {
+    const details = [
+      unknown.length > 0 ? `unknown: ${unknown.join(", ")}` : null,
+      missing.length > 0 ? `missing: ${missing.join(", ")}` : null,
+    ]
+      .filter(Boolean)
+      .join("; ");
+    throw new Error(`[handzon] ${entryId}: ${label} track coverage mismatch (${details}).`);
+  }
+}
+
+function validateTrackIdsInBody({
+  body,
+  entryId,
+  trackIds,
+}: {
+  body: string;
+  entryId: string;
+  trackIds: string[];
+}) {
+  const trackRe = /<Track\b[^>]*\bid\s*=\s*(?:"([^"]+)"|'([^']+)'|\{`([^`]+)`\})/g;
+  const declared = new Set(trackIds);
+  for (;;) {
+    const m = trackRe.exec(body);
+    if (m === null) break;
+    const id = m[1] ?? m[2] ?? m[3];
+    if (!id) continue;
+    if (trackIds.length === 0) {
+      throw new Error(
+        `[handzon] step ${entryId}: <Track id="${id}"> is used, but the tutorial declares no tracks.`,
+      );
+    }
+    if (!declared.has(id)) {
+      throw new Error(
+        `[handzon] step ${entryId}: <Track id="${id}"> is not declared in the tutorial's tracks.`,
+      );
+    }
+  }
+}
+
+function validateVerifySpecCheckpoint({
+  entryId,
+  ids,
+  trackId,
+  verify,
+}: {
+  entryId: string;
+  ids: Set<string>;
+  trackId?: string;
+  verify: VerifySpec;
+}) {
+  if (!ids.has(verify.id)) {
+    const prefix = trackId ? `verify.${trackId}.id` : "verify.id";
+    throw new Error(
+      `[handzon] step ${entryId}: ${prefix} "${verify.id}" has no matching <Checkpoint id="…"> in the step body. Either add a <Checkpoint id="${verify.id}" …/> or remove the verify block.`,
+    );
+  }
+}
+
 /**
  * Custom loader that scans tutorials/<slug>/_meta.json for each tutorial.
  * Tutorial order is driven by `_index.json` at the tutorials root; folder
@@ -106,10 +219,18 @@ export function stepsLoader(): Loader {
     load: async (args) => {
       await inner.load(args);
       const checkpointRe = /<Checkpoint\b[^>]*\bid\s*=\s*(?:"([^"]+)"|'([^']+)'|\{`([^`]+)`\})/g;
+      const trackIdCache = new Map<string, Promise<string[]>>();
       for (const value of args.store.values()) {
-        const verify = (value.data as { verify?: { id?: string } } | undefined)?.verify;
-        if (!verify?.id) continue;
+        const { tutorialSlug } = parseStepCollectionId(value.id);
+        const trackIdsPromise =
+          trackIdCache.get(tutorialSlug) ?? readTutorialTrackIds(tutorialSlug);
+        trackIdCache.set(tutorialSlug, trackIdsPromise);
+        const trackIds = await trackIdsPromise;
         const body = value.body ?? "";
+        validateTrackIdsInBody({ body, entryId: value.id, trackIds });
+
+        const verify = (value.data as { verify?: TrackScoped<VerifySpec> } | undefined)?.verify;
+        if (!verify) continue;
         const ids = new Set<string>();
         checkpointRe.lastIndex = 0;
         for (;;) {
@@ -118,10 +239,19 @@ export function stepsLoader(): Loader {
           const id = m[1] ?? m[2] ?? m[3];
           if (id) ids.add(id);
         }
-        if (!ids.has(verify.id)) {
-          throw new Error(
-            `[handzon] step ${value.id}: verify.id "${verify.id}" has no matching <Checkpoint id="…"> in the step body. Either add a <Checkpoint id="${verify.id}" …/> or remove the verify block.`,
-          );
+
+        if (isTrackMap(verify, isVerifySpec)) {
+          validateTrackMapCoverage({
+            entryId: `step ${value.id}`,
+            label: "verify",
+            map: verify,
+            trackIds,
+          });
+          for (const [trackId, spec] of Object.entries(verify)) {
+            validateVerifySpecCheckpoint({ entryId: value.id, ids, trackId, verify: spec });
+          }
+        } else {
+          validateVerifySpecCheckpoint({ entryId: value.id, ids, verify });
         }
       }
     },
@@ -216,64 +346,171 @@ export const starterSchema = z.discriminatedUnion("kind", [
 
 export type StarterSpec = z.infer<typeof starterSchema>;
 
-/** Schema for tutorial step entries. */
-export const stepsSchema = z.object({
-  title: z.string(),
-  duration: z.string().optional(),
-  summary: z.string().optional(),
-  ai: z.boolean().optional(),
-  verify: verifySchema.optional(),
+export const trackSchema = z.object({
+  id: z
+    .string()
+    .min(1)
+    .regex(/^[a-z0-9][a-z0-9_-]*$/i, "Use a stable id like py, ts, or rust."),
+  label: z.string().min(1),
 });
 
-/** Schema for tutorial entries. Pass through Astro's image() helper. */
-export function tutorialsSchema({ image }: { image: () => import("astro/zod").ZodType }) {
+export type TutorialTrack = z.infer<typeof trackSchema>;
+export type TrackMap<T> = Record<string, T>;
+export type TrackScoped<T> = T | TrackMap<T>;
+
+export const verifyByTrackSchema = z.record(verifySchema);
+export const trackScopedVerifySchema = z.union([verifySchema, verifyByTrackSchema]);
+
+export const starterByTrackSchema = z.record(starterSchema);
+export const trackScopedStarterSchema = z.union([starterSchema, starterByTrackSchema]);
+
+export type TrackScopedVerifySpec = z.infer<typeof trackScopedVerifySchema>;
+export type TrackScopedStarterSpec = z.infer<typeof trackScopedStarterSchema>;
+
+export function resolveForTrack<T>(
+  value: TrackScoped<T> | undefined,
+  trackId: string | undefined,
+  isShared: (v: unknown) => v is T,
+): T | undefined {
+  if (!value) return undefined;
+  if (isShared(value)) return value;
+  return trackId ? value[trackId] : undefined;
+}
+
+export function resolveStarterForTrack(
+  starter: TrackScoped<StarterSpec> | undefined,
+  trackId: string | undefined,
+): StarterSpec | undefined {
+  return resolveForTrack(starter, trackId, isStarterSpec);
+}
+
+export function resolveVerifyForTrack(
+  verify: TrackScoped<VerifySpec> | undefined,
+  trackId: string | undefined,
+): VerifySpec | undefined {
+  return resolveForTrack(verify, trackId, isVerifySpec);
+}
+
+function parseStepCollectionId(id: string): { tutorialSlug: string; stepFile: string } {
+  const slash = id.indexOf("/");
+  if (slash < 0) {
+    throw new Error(`Unrecognized step id: ${id}`);
+  }
+  return { tutorialSlug: id.slice(0, slash), stepFile: id.slice(slash + 1) };
+}
+
+function refineTrackConfig(
+  data: {
+    tracks?: TutorialTrack[];
+    defaultTrack?: string;
+    starter?: TrackScoped<StarterSpec>;
+  },
+  ctx: z.RefinementCtx,
+) {
+  const trackIds = data.tracks?.map((track) => track.id) ?? [];
+  const duplicated = trackIds.filter((id, index) => trackIds.indexOf(id) !== index);
+  for (const id of new Set(duplicated)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["tracks"],
+      message: `Duplicate track id "${id}".`,
+    });
+  }
+  if (data.defaultTrack && !trackIds.includes(data.defaultTrack)) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["defaultTrack"],
+      message: `defaultTrack "${data.defaultTrack}" is not declared in tracks.`,
+    });
+  }
+  if (isTrackMap(data.starter, isStarterSpec)) {
+    const actual = Object.keys(data.starter);
+    const unknown = actual.filter((id) => !trackIds.includes(id));
+    const missing = trackIds.filter((id) => !(id in data.starter!));
+    if (trackIds.length === 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["starter"],
+        message: "Per-track starter requires declared tracks.",
+      });
+    }
+    for (const id of unknown) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["starter", id],
+        message: `Unknown starter track "${id}".`,
+      });
+    }
+    if (missing.length > 0) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ["starter"],
+        message: `Missing starter for track(s): ${missing.join(", ")}.`,
+      });
+    }
+  }
+}
+
+/** Schema for tutorial step entries. Pass through Astro's image() helper. */
+export function stepsSchema({ image }: { image: () => import("astro/zod").ZodType }) {
   return z.object({
     title: z.string(),
-    description: z.string(),
-    author: z
-      .object({
-        name: z.string(),
-        url: z.string().url().optional(),
-        avatar: image().optional(),
-      })
-      .optional(),
-    publishedAt: z.coerce.date().optional(),
-    updatedAt: z.coerce.date().optional(),
-    tags: z.array(z.string()).default([]),
-    difficulty: z.enum(["beginner", "intermediate", "advanced"]).default("beginner"),
-    estimatedDuration: z.string().optional(),
-    prerequisites: z.array(z.string()).default([]),
-    nextTutorial: z.string().optional(),
-    // TODO(handzon): `cover` and `icon` are accepted by the schema for
-    // forward compatibility, but no page currently renders them
-    // (Home cards, TutorialLanding, OG meta all ignore them). Wire them
-    // up in TutorialCard and BaseLayout's OG tags before promoting
-    // cover art in author-facing docs and skills.
-    cover: image().optional(),
-    icon: z.union([z.string(), image()]).optional(),
-    steps: z.array(z.string()).optional(),
-    gated: z.boolean().default(false),
-    showProgress: z.boolean().default(true),
-    feedbackUrl: z.string().url().optional(),
-    starter: starterSchema.optional(),
-    ai: z
-      .object({
-        enabled: z.boolean().optional(),
-        name: z.string().optional(),
-        tagline: z.string().optional(),
-        greeting: z.string().optional(),
-        avatar: image().optional(),
-        persona: z.string().optional(),
-        tone: z.enum(["socratic", "direct", "encouraging"]).optional(),
-        provider: z.string().optional(),
-        model: z.string().optional(),
-        byok: z.enum(["required", "optional", "disabled"]).optional(),
-        references: z.array(z.string()).default([]),
-        allowedDomains: z.array(z.string()).default([]),
-        disabledSkills: z.array(z.string()).default([]),
-        enableSuggestPlaygroundEdit: z.boolean().default(false),
-        includeFutureSteps: z.boolean().optional(),
-      })
-      .optional(),
+    duration: z.string().optional(),
+    summary: z.string().optional(),
+    ai: z.boolean().optional(),
+    heroMedia: createHeroMediaSchema(z, image).optional(),
+    verify: trackScopedVerifySchema.optional(),
   });
 }
+
+/** Schema for tutorial entries. Pass through Astro's image() helper. */
+export function tutorialsSchema({ image }: { image: () => import("astro/zod").ZodType }) {
+  return z
+    .object({
+      title: z.string(),
+      description: z.string(),
+      author: z
+        .object({
+          name: z.string(),
+          url: z.string().url().optional(),
+          avatar: image().optional(),
+        })
+        .optional(),
+      publishedAt: z.coerce.date().optional(),
+      updatedAt: z.coerce.date().optional(),
+      tags: z.array(z.string()).default([]),
+      tracks: z.array(trackSchema).default([]),
+      defaultTrack: z.string().min(1).optional(),
+      difficulty: z.enum(["beginner", "intermediate", "advanced"]).default("beginner"),
+      estimatedDuration: z.string().optional(),
+      prerequisites: z.array(z.string()).default([]),
+      nextTutorial: z.string().optional(),
+      cover: image().optional(),
+      icon: z.union([z.string(), image()]).optional(),
+      steps: z.array(z.string()).optional(),
+      gated: z.boolean().default(false),
+      showProgress: z.boolean().default(true),
+      feedbackUrl: z.string().url().optional(),
+      starter: trackScopedStarterSchema.optional(),
+      ai: z
+        .object({
+          enabled: z.boolean().optional(),
+          name: z.string().optional(),
+          tagline: z.string().optional(),
+          greeting: z.string().optional(),
+          avatar: image().optional(),
+          persona: z.string().optional(),
+          tone: z.enum(["socratic", "direct", "encouraging"]).optional(),
+          provider: z.string().optional(),
+          model: z.string().optional(),
+          byok: z.enum(["required", "optional", "disabled"]).optional(),
+          references: z.array(z.string()).default([]),
+          allowedDomains: z.array(z.string()).default([]),
+          disabledSkills: z.array(z.string()).default([]),
+          enableSuggestPlaygroundEdit: z.boolean().default(false),
+          includeFutureSteps: z.boolean().optional(),
+        })
+        .optional(),
+    })
+    .superRefine(refineTrackConfig);
+}

package/src/components/Sidebar.astro

@@ -3,6 +3,7 @@ import { withBase } from "../lib/base";
 import type { TutorialEntry, StepEntry } from "../lib/content";
 import { parseStepId } from "../lib/content";
 import Progress from "./Progress.tsx";
+import TrackSelector from "./TrackSelector.tsx";
 
 interface Props {
   tutorial: TutorialEntry;
@@ -30,6 +31,13 @@ const slug = tutorial.id;
     {tutorial.data.showProgress && (
       <Progress tutorialSlug={slug} totalSteps={steps.length} client:load />
     )}
+    {tutorial.data.tracks.length > 1 && (
+      <TrackSelector
+        tracks={tutorial.data.tracks}
+        defaultTrack={tutorial.data.defaultTrack}
+        client:load
+      />
+    )}
   </div>
 
   <ol class="sb-steps">

package/src/components/StepHeroMedia.astro

@@ -0,0 +1,77 @@
+---
+import { Image } from "astro:assets";
+import type { ImageMetadata } from "astro";
+import { withBase } from "../lib/base";
+import Embed from "./mdx/Embed.astro";
+
+type StepHeroMedia =
+  | {
+      kind: "image";
+      src: string | ImageMetadata;
+      alt: string;
+      caption?: string;
+    }
+  | {
+      kind: "video";
+      src: string;
+      title: string;
+      aspect?: string;
+      type?: "iframe" | "video";
+      caption?: string;
+    };
+
+interface Props {
+  media: StepHeroMedia;
+}
+
+const { media } = Astro.props;
+
+---
+<figure class="step-hero-media">
+  {media.kind === "video" ? (
+    <Embed
+      src={media.src}
+      title={media.title}
+      aspect={media.aspect}
+      type={media.type}
+    />
+  ) : typeof media.src !== "string" ? (
+    <Image
+      src={media.src}
+      alt={media.alt}
+      class="step-hero-image"
+      widths={[720, 960, 1200, 1440]}
+      sizes="(min-width: 900px) 720px, 100vw"
+    />
+  ) : (
+    <img
+      src={withBase(media.src)}
+      alt={media.alt}
+      class="step-hero-image"
+      loading="eager"
+    />
+  )}
+  {media.caption && <figcaption>{media.caption}</figcaption>}
+</figure>
+
+<style>
+  .step-hero-media {
+    margin: 0 0 2rem;
+  }
+  .step-hero-media :global(.embed) {
+    margin: 0;
+  }
+  .step-hero-image {
+    display: block;
+    width: 100%;
+    height: auto;
+    border: var(--border-default, 2px) solid var(--color-border);
+    background: var(--color-surface);
+  }
+  figcaption {
+    margin-top: 0.65rem;
+    color: var(--color-muted);
+    font-size: 0.85em;
+    line-height: 1.5;
+  }
+</style>

package/src/components/TrackSelector.tsx

@@ -0,0 +1,62 @@
+import { useEffect, useMemo } from "react";
+import { useProgress } from "../lib/progress/useProgress";
+import { resolveActiveTrack, type TrackOption, trackStyleText } from "../lib/tracks";
+
+interface Props {
+  tracks: TrackOption[];
+  defaultTrack?: string;
+}
+
+function applyTrackStyle(trackId: string | undefined) {
+  if (typeof document === "undefined" || !trackId) return;
+  document.documentElement.dataset.track = trackId;
+  let style = document.getElementById("handzon-track-style") as HTMLStyleElement | null;
+  if (!style) {
+    style = document.createElement("style");
+    style.id = "handzon-track-style";
+    document.head.appendChild(style);
+  }
+  style.textContent = trackStyleText(trackId);
+}
+
+export default function TrackSelector({ tracks, defaultTrack }: Props) {
+  const { state, setPref } = useProgress();
+  const activeTrack = useMemo(
+    () =>
+      resolveActiveTrack({
+        tracks,
+        preferredTrack: state.prefs.track,
+        defaultTrack,
+      }),
+    [tracks, state.prefs.track, defaultTrack],
+  );
+
+  useEffect(() => {
+    applyTrackStyle(activeTrack);
+  }, [activeTrack]);
+
+  if (tracks.length < 2 || !activeTrack) return null;
+
+  return (
+    <section className="track-selector" aria-label="Tutorial track">
+      <div className="track-selector-label">Track</div>
+      <div className="track-selector-list">
+        {tracks.map((track) => {
+          const selected = track.id === activeTrack;
+          return (
+            <button
+              type="button"
+              key={track.id}
+              className="track-selector-option"
+              data-active={selected ? "true" : "false"}
+              aria-pressed={selected}
+              onClick={() => setPref("track", track.id)}
+            >
+              {track.label}
+            </button>
+          );
+        })}
+      </div>
+    </section>
+  );
+}

package/src/components/ai/ChatButton.tsx

@@ -1,9 +1,12 @@
 import { Sparkles } from "lucide-react";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import { ASSIST_EVENT, ASSIST_READY_EVENT, type AssistEventDetail } from "../../lib/ai/assist";
 import type { ChatMessage } from "../../lib/ai/client";
 import type { AssistantContext } from "../../lib/ai/context";
 import { buildAssistantPrompt } from "../../lib/ai/prompts";
+import { useProgress } from "../../lib/progress/useProgress";
+import { stripInactiveTrackBlocks } from "../../lib/track-source";
+import { resolveActiveTrack } from "../../lib/tracks";
 import type { AiConfig } from "../../types/ai";
 import ChatPanel from "./ChatPanel";
 
@@ -13,12 +16,33 @@ interface Props {
 }
 
 export default function ChatButton({ config, context }: Props) {
+  const { state } = useProgress();
   const [open, setOpen] = useState(false);
   const [seed, setSeed] = useState<ChatMessage[] | undefined>(undefined);
   // Bumped on each new assist seed so ChatPanel remounts with the
   // new initialMessages even if the panel is already open from a
   // previous intent or FAB click.
   const [seedToken, setSeedToken] = useState(0);
+  const trackContext = useMemo<AssistantContext>(() => {
+    const activeTrack = resolveActiveTrack({
+      tracks: context.tutorial.tracks,
+      preferredTrack: state.prefs.track,
+      defaultTrack: context.tutorial.defaultTrack,
+    });
+    if (!activeTrack) return context;
+    return {
+      ...context,
+      tutorial: { ...context.tutorial, track: activeTrack },
+      currentStep: {
+        ...context.currentStep,
+        source: stripInactiveTrackBlocks(context.currentStep.source, activeTrack),
+      },
+      priorSteps: context.priorSteps.map((step) => ({
+        ...step,
+        source: stripInactiveTrackBlocks(step.source, activeTrack),
+      })),
+    };
+  }, [context, state.prefs.track]);
 
   // Tell Family A islands (HelpMe, Checkpoint nudge, …) that the tutor
   // is mounted on this page. Set the dataset flag for islands that
@@ -40,14 +64,14 @@ export default function ChatButton({ config, context }: Props) {
     function onAssist(e: Event) {
       const detail = (e as CustomEvent<AssistEventDetail>).detail;
       if (!detail?.intent) return;
-      const { seedMessages } = buildAssistantPrompt(context, detail.intent);
+      const { seedMessages } = buildAssistantPrompt(trackContext, detail.intent);
       setSeed(seedMessages);
       setSeedToken((t) => t + 1);
       setOpen(true);
     }
     document.addEventListener(ASSIST_EVENT, onAssist);
     return () => document.removeEventListener(ASSIST_EVENT, onAssist);
-  }, [context]);
+  }, [trackContext]);
 
   if (!config.enabled) return null;
 
@@ -70,7 +94,7 @@ export default function ChatButton({ config, context }: Props) {
         open={open}
         onOpenChange={setOpen}
         config={config}
-        context={context}
+        context={trackContext}
         initialMessages={seed}
       />
     </>

package/src/components/ai/ChatPanel.tsx

@@ -224,6 +224,16 @@ export default function ChatPanel({ open, onOpenChange, config, context, initial
 
             <div className="chat-meta">
               On: <strong>{context.currentStep.title}</strong>
+              {context.tutorial.track && (
+                <>
+                  {" "}
+                  · Track:{" "}
+                  <strong>
+                    {context.tutorial.tracks.find((track) => track.id === context.tutorial.track)
+                      ?.label ?? context.tutorial.track}
+                  </strong>
+                </>
+              )}
             </div>
 
             {needsKey ? (