handzon-core 0.12.2 → 0.13.2

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 ? (

package/src/components/home/TutorialCard.astro

@@ -1,4 +1,5 @@
 ---
+import { Image } from "astro:assets";
 import { withBase } from "../../lib/base";
 import type { TutorialEntry } from "../../lib/content";
 
@@ -15,6 +16,8 @@ interface Props {
 const { tutorial, duration, stepCount } = Astro.props;
 const data = tutorial.data;
 const slug = tutorial.id;
+const iconText = typeof data.icon === "string" ? data.icon : undefined;
+const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undefined;
 ---
 <article
   class="card"
@@ -25,8 +28,33 @@ const slug = tutorial.id;
   data-popularity="0"
 >
   <a href={withBase(`/${slug}`)} class="card-link">
+    {data.cover && (
+      <div class="card-media">
+        <Image
+          src={data.cover}
+          alt=""
+          class="card-cover"
+          loading="lazy"
+          widths={[360, 540, 720]}
+          sizes="(min-width: 960px) 33vw, (min-width: 640px) 50vw, 100vw"
+        />
+      </div>
+    )}
     <div class="card-body">
-      <h3>{data.title}</h3>
+      <div class="card-title-row">
+        {iconImage && (
+          <Image
+            src={iconImage}
+            alt=""
+            class="card-icon card-icon-image"
+            loading="lazy"
+            width={32}
+            height={32}
+          />
+        )}
+        {iconText && <span class="card-icon card-icon-text" aria-hidden="true">{iconText}</span>}
+        <h3>{data.title}</h3>
+      </div>
       <p>{data.description}</p>
       <div class="badges">
         <span class={`badge badge-${data.difficulty}`}>{data.difficulty}</span>
@@ -57,7 +85,7 @@ const slug = tutorial.id;
       </div>
       {data.tags.length > 0 && (
         <div class="tags">
-          {data.tags.map((tag) => <span class="tag">#{tag}</span>)}
+          {data.tags.map((tag: string) => <span class="tag">#{tag}</span>)}
         </div>
       )}
       <div
@@ -87,12 +115,58 @@ const slug = tutorial.id;
     flex-direction: column;
     width: 100%;
   }
+  .card-media {
+    aspect-ratio: 16 / 9;
+    border-bottom: 1px solid var(--color-border);
+    background:
+      linear-gradient(
+        135deg,
+        color-mix(in oklab, var(--color-accent) 10%, transparent),
+        var(--color-surface)
+      );
+    overflow: hidden;
+  }
+  .card-cover {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    display: block;
+    filter: saturate(0.92) contrast(1.05);
+    transition: transform 0.18s ease, filter 0.18s ease;
+  }
+  .card:hover .card-cover {
+    transform: scale(1.025);
+    filter: saturate(1) contrast(1.08);
+  }
   .card-body {
     padding: 1.1rem 1.2rem 1.2rem;
     display: flex;
     flex-direction: column;
     flex: 1;
   }
+  .card-title-row {
+    display: flex;
+    align-items: flex-start;
+    gap: 0.65rem;
+    margin-bottom: 0.5rem;
+  }
+  .card-icon {
+    flex-shrink: 0;
+    width: 2rem;
+    height: 2rem;
+    border: 1px solid var(--color-border);
+    background: var(--color-surface);
+  }
+  .card-icon-image {
+    object-fit: cover;
+    display: block;
+  }
+  .card-icon-text {
+    display: inline-grid;
+    place-items: center;
+    font-size: 1rem;
+    line-height: 1;
+  }
 
   /* Metadata row: difficulty + duration with a divider beneath it.
    * `margin-top: auto` pins this row (and everything below it — tags,
@@ -140,7 +214,7 @@ const slug = tutorial.id;
   h3 {
     font-size: 1.05rem;
     font-weight: 700;
-    margin: 0 0 0.5rem;
+    margin: 0;
     letter-spacing: -0.015em;
     line-height: 1.3;
   }

package/src/components/mdx/Track.astro

@@ -0,0 +1,11 @@
+---
+interface Props {
+  id: string;
+}
+
+const { id } = Astro.props;
+---
+
+<div class="track-panel" data-track-panel={id}>
+  <slot />
+</div>

package/src/layouts/BaseLayout.astro

@@ -30,6 +30,8 @@ interface Props {
   logoHeight?: number;
   /** Favicon URL injected into <head>. */
   faviconUrl?: string;
+  /** Optional social preview image for Open Graph and Twitter cards. */
+  ogImageUrl?: string;
   /** Show the site footer ("Built with Handzon" + repo link). */
   showFooter?: boolean;
   /** Footer link URL; defaults to the Handzon repo. */
@@ -67,6 +69,7 @@ const {
   logoWidth = 76,
   logoHeight = 58,
   faviconUrl = "/favicon.svg",
+  ogImageUrl,
   showFooter = true,
   repoUrl,
   siteUrl,
@@ -83,6 +86,7 @@ const {
 const resolvedMaxWidth = pageMaxWidth === "none" ? "none" : pageMaxWidth;
 const pageTitle = title ? `${title} — ${siteName}` : siteName;
 const desc = description ?? tagline;
+const socialImageUrl = ogImageUrl ? withBase(ogImageUrl) : undefined;
 ---
 <!doctype html>
 <html lang="en">
@@ -95,6 +99,9 @@ const desc = description ?? tagline;
     <meta property="og:title" content={pageTitle} />
     <meta property="og:description" content={desc} />
     <meta property="og:type" content="website" />
+    {socialImageUrl && <meta property="og:image" content={socialImageUrl} />}
+    {socialImageUrl && <meta name="twitter:card" content="summary_large_image" />}
+    {socialImageUrl && <meta name="twitter:image" content={socialImageUrl} />}
     {/* Optional consumer-side <head> injections. Forwarded by every
      * page wrapper (Home, TutorialLanding, TutorialStep / TutorialLayout)
      * so scaffolds can preload fonts, attach per-page OG images, add

package/src/layouts/TutorialLayout.astro

@@ -1,6 +1,7 @@
 ---
 import BaseLayout from "./BaseLayout.astro";
 import Sidebar from "../components/Sidebar.astro";
+import StepHeroMedia from "../components/StepHeroMedia.astro";
 import StepNav from "../components/StepNav.astro";
 import { parseStepId } from "../lib/content.ts";
 import type { TutorialEntry, StepEntry } from "../lib/content";
@@ -43,6 +44,34 @@ const {
 } = Astro.props;
 
 const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
+const trackBootstrap =
+  tutorial.data.tracks.length > 0
+    ? `(() => {
+  try {
+    const tracks = ${JSON.stringify(tutorial.data.tracks).replace(/</g, "\\u003c")};
+    const defaultTrack = ${JSON.stringify(tutorial.data.defaultTrack ?? null)};
+    const ids = tracks.map((track) => track.id);
+    const raw = window.localStorage.getItem("handzon:v1");
+    const preferred = raw ? JSON.parse(raw)?.prefs?.track : null;
+    const active = ids.includes(preferred)
+      ? preferred
+      : defaultTrack && ids.includes(defaultTrack)
+        ? defaultTrack
+        : ids[0];
+    if (!active) return;
+    document.documentElement.dataset.track = active;
+    let style = document.getElementById("handzon-track-style");
+    if (!style) {
+      style = document.createElement("style");
+      style.id = "handzon-track-style";
+      document.head.appendChild(style);
+    }
+    style.textContent = '[data-track-panel]:not([data-track-panel="' + active + '"]) { display: none !important; }';
+  } catch {
+    // Track selection is progressive enhancement; leave all content visible on failure.
+  }
+})();`
+    : null;
 ---
 <BaseLayout
   title={`${currentStep.data.title} — ${tutorial.data.title}`}
@@ -59,6 +88,7 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
   showFooter={showFooter}
 >
   <slot name="head" slot="head" />
+  {trackBootstrap && <script is:inline set:html={trackBootstrap} />}
   <div class="layout">
     <div class="sidebar-wrap">
       <Sidebar tutorial={tutorial} steps={steps} currentStepSlug={currentStepSlug} />
@@ -73,6 +103,10 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
         )}
       </header>
 
+      {currentStep.data.heroMedia && (
+        <StepHeroMedia media={currentStep.data.heroMedia} />
+      )}
+
       <article class="prose">
         <slot />
       </article>

package/src/lib/ai/context.ts

@@ -1,6 +1,8 @@
 import type { StepEntry, TutorialEntry } from "../content";
 import { parseStepId } from "../content";
 import type { ProgressState } from "../progress/types";
+import { stripInactiveTrackBlocks } from "../track-source";
+import type { TrackOption } from "../tracks";
 
 export interface AssistantContext {
   tutorial: {
@@ -9,6 +11,9 @@ export interface AssistantContext {
     description: string;
     difficulty: string;
     tags: string[];
+    tracks: TrackOption[];
+    defaultTrack?: string;
+    track?: string | null;
   };
   outline: Array<{ slug: string; title: string; completed: boolean; current: boolean }>;
   currentStep: {
@@ -32,6 +37,7 @@ interface BuildOptions {
   progress: ProgressState;
   references?: Array<{ source: string; content: string }>;
   includeFutureSteps?: boolean;
+  activeTrack?: string;
 }
 
 /**
@@ -46,6 +52,7 @@ export function buildContext({
   progress,
   references = [],
   includeFutureSteps = false,
+  activeTrack,
 }: BuildOptions): AssistantContext {
   const slug = tutorial.id;
   const currentIdx = steps.findIndex((s) => s.id === currentStep.id);
@@ -67,7 +74,7 @@ export function buildContext({
     .map((s) => ({
       slug: parseStepId(s.id).stepSlug,
       title: s.data.title,
-      source: s.body ?? "",
+      source: stripInactiveTrackBlocks(s.body ?? "", activeTrack),
     }));
 
   return {
@@ -77,12 +84,15 @@ export function buildContext({
       description: tutorial.data.description,
       difficulty: tutorial.data.difficulty,
       tags: tutorial.data.tags,
+      tracks: tutorial.data.tracks,
+      defaultTrack: tutorial.data.defaultTrack,
+      track: activeTrack ?? null,
     },
     outline,
     currentStep: {
       slug: currentSlug,
       title: currentStep.data.title,
-      source: currentStep.body ?? "",
+      source: stripInactiveTrackBlocks(currentStep.body ?? "", activeTrack),
     },
     priorSteps,
     progress: {

package/src/lib/ai/prompts.ts

@@ -30,7 +30,14 @@ export interface AssistantPrompt {
 }
 
 function header(ctx: AssistantContext): string {
-  return [`Tutorial: ${ctx.tutorial.title}`, `Step: ${ctx.currentStep.title}`].join("\n");
+  const lines = [`Tutorial: ${ctx.tutorial.title}`, `Step: ${ctx.currentStep.title}`];
+  if (ctx.tutorial.track) {
+    const label =
+      ctx.tutorial.tracks.find((track) => track.id === ctx.tutorial.track)?.label ??
+      ctx.tutorial.track;
+    lines.push(`Track: ${label}`);
+  }
+  return lines.join("\n");
 }
 
 function renderIntent(ctx: AssistantContext, intent: AssistantIntent): string {

package/src/lib/heroMedia.ts

@@ -0,0 +1,37 @@
+import { z as defaultZ } from "zod";
+
+type SchemaBuilder = typeof defaultZ;
+type ImageSchemaFactory = () => unknown;
+
+export function createHeroMediaSchema(
+  schema: SchemaBuilder = defaultZ,
+  image?: ImageSchemaFactory,
+) {
+  const imageSrc = image
+    ? schema.union([image() as never, schema.string().min(1)])
+    : schema.string().min(1);
+
+  return schema.discriminatedUnion("kind", [
+    schema
+      .object({
+        kind: schema.literal("image"),
+        src: imageSrc,
+        alt: schema.string().min(1),
+        caption: schema.string().min(1).optional(),
+      })
+      .strict(),
+    schema
+      .object({
+        kind: schema.literal("video"),
+        src: schema.string().min(1),
+        title: schema.string().min(1),
+        aspect: schema.string().min(1).default("16/9"),
+        type: schema.enum(["iframe", "video"]).default("iframe"),
+        caption: schema.string().min(1).optional(),
+      })
+      .strict(),
+  ]);
+}
+
+export const heroMediaSchema = createHeroMediaSchema();
+export type HeroMedia = defaultZ.infer<typeof heroMediaSchema>;

package/src/lib/mdx-components.ts

@@ -18,6 +18,7 @@ import StepsCmp from "../components/mdx/Steps.astro";
 import Tab from "../components/mdx/Tab.astro";
 import Tabs from "../components/mdx/Tabs.astro";
 import Terminal from "../components/mdx/Terminal.astro";
+import Track from "../components/mdx/Track.astro";
 
 /**
  * The components map passed to <Content components={...} />. Every React
@@ -37,6 +38,7 @@ export function mdxComponents() {
     Download,
     Tabs,
     Tab,
+    Track,
     FileTree,
     Reveal,
     Terminal,

package/src/lib/progress/types.ts

@@ -46,6 +46,7 @@ export type ProgressState = {
     packageManager?: "npm" | "pnpm" | "yarn" | "bun";
     os?: "macos" | "linux" | "windows";
     theme?: "light" | "dark";
+    track?: string;
   };
   /**
    * Per-tutorial "where was I last?" marker. Tracks `ts` so consumers

package/src/lib/track-scoped.ts

@@ -0,0 +1,24 @@
+export type TrackMap<T> = Record<string, T>;
+export type TrackScoped<T> = T | TrackMap<T>;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+export function isStarterSpec(value: unknown): value is { kind: string } {
+  return isRecord(value) && typeof value.kind === "string";
+}
+
+export function isVerifySpec(value: unknown): value is { id: string; checks: unknown[] } {
+  return isRecord(value) && typeof value.id === "string" && Array.isArray(value.checks);
+}
+
+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;
+}

package/src/lib/track-source.ts

@@ -0,0 +1,10 @@
+const TRACK_BLOCK =
+  /<Track\b[^>]*\bid\s*=\s*(?:"([^"]+)"|'([^']+)'|\{`([^`]+)`\})[^>]*>([\s\S]*?)<\/Track>/g;
+
+export function stripInactiveTrackBlocks(source: string, activeTrack: string | undefined): string {
+  if (!activeTrack) return source;
+  return source.replace(TRACK_BLOCK, (_full, doubleId, singleId, templateId, body) => {
+    const id = doubleId ?? singleId ?? templateId;
+    return id === activeTrack ? String(body).trim() : "";
+  });
+}

package/src/lib/tracks.ts

@@ -0,0 +1,32 @@
+export interface TrackOption {
+  id: string;
+  label: string;
+}
+
+export interface ResolveTrackInput {
+  tracks?: TrackOption[];
+  explicitTrack?: string | null;
+  preferredTrack?: string | null;
+  defaultTrack?: string | null;
+}
+
+export function resolveActiveTrack({
+  tracks = [],
+  explicitTrack,
+  preferredTrack,
+  defaultTrack,
+}: ResolveTrackInput): string | undefined {
+  if (tracks.length === 0) return undefined;
+  const ids = new Set(tracks.map((track) => track.id));
+  if (explicitTrack && ids.has(explicitTrack)) return explicitTrack;
+  if (preferredTrack && ids.has(preferredTrack)) return preferredTrack;
+  if (defaultTrack && ids.has(defaultTrack)) return defaultTrack;
+  return tracks[0]?.id;
+}
+
+export function trackStyleText(trackId: string | undefined): string {
+  if (!trackId) return "";
+  // Track ids are schema-limited to [a-z0-9_-], so a quoted attribute
+  // selector is safe without relying on CSS.escape in older browsers.
+  return `[data-track-panel]:not([data-track-panel="${trackId}"]) { display: none !important; }`;
+}