handzon-core 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.14.1",
+  "version": "0.15.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/StepHeroMedia.astro

@@ -18,6 +18,14 @@ type StepHeroMedia =
       aspect?: string;
       type?: "iframe" | "video";
       caption?: string;
+    }
+  | {
+      kind: "slides";
+      src: string;
+      title: string;
+      aspect?: string;
+      slide?: string | number;
+      caption?: string;
     };
 
 interface Props {
@@ -35,6 +43,14 @@ const { media } = Astro.props;
       aspect={media.aspect}
       type={media.type}
     />
+  ) : media.kind === "slides" ? (
+    <Embed
+      src={media.src}
+      title={media.title}
+      aspect={media.aspect}
+      type="slides"
+      slide={media.slide}
+    />
   ) : typeof media.src !== "string" ? (
     <Image
       src={media.src}

package/src/components/StepNav.astro

@@ -1,7 +1,9 @@
 ---
+import TutorialCompletion from "./TutorialCompletion.tsx";
 import { withBase } from "../lib/base";
 import type { StepEntry } from "../lib/content";
 import { parseStepId } from "../lib/content";
+import type { TutorialSummary } from "../lib/tutorialSummary";
 
 interface Props {
   tutorialSlug: string;
@@ -9,16 +11,17 @@ interface Props {
   currentStepSlug: string;
   gated: boolean;
   hasCheckpoint: boolean;
+  nextTutorial?: TutorialSummary;
 }
 
-const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint } = Astro.props;
+const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint, 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;
 ---
-<nav class="step-nav" data-gated={gated && hasCheckpoint ? "true" : "false"} data-step-key={`${tutorialSlug}/${currentStepSlug}`}>
+<nav class:list={["step-nav", !next && "step-nav-final"]} data-gated={gated && hasCheckpoint ? "true" : "false"} data-step-key={`${tutorialSlug}/${currentStepSlug}`}>
   <div>
     {prev && (
       <a class="sn-prev" href={withBase(`/${tutorialSlug}/${prevSlug}`)}>
@@ -26,15 +29,18 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
       </a>
     )}
   </div>
-  <div>
+  <div class="sn-slot">
     {next ? (
       <a class="sn-next" href={withBase(`/${tutorialSlug}/${nextSlug}`)} data-next-link="true">
         {hasCheckpoint ? "Continue" : "Next"}: {next.data.title} →
       </a>
     ) : (
-      <a class="sn-next sn-done" href={withBase(`/${tutorialSlug}`)}>
-        Finish tutorial →
-      </a>
+      <TutorialCompletion
+        client:load
+        tutorialSlug={tutorialSlug}
+        totalSteps={steps.length}
+        nextTutorial={nextTutorial}
+      />
     )}
   </div>
 </nav>
@@ -83,11 +89,20 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
   .step-nav {
     display: flex;
     justify-content: space-between;
+    align-items: flex-start;
     gap: 1rem;
     margin-top: 3rem;
     padding-top: 1.5rem;
     border-top: var(--border-default, 2px) solid var(--color-border);
   }
+  .step-nav-final {
+    display: grid;
+    grid-template-columns: minmax(0, auto) minmax(18rem, 1fr);
+  }
+  .sn-slot {
+    display: flex;
+    justify-content: flex-end;
+  }
   .sn-prev, .sn-next {
     display: inline-block;
     padding: 0.7rem 1rem;
@@ -105,4 +120,78 @@ const nextSlug = next ? parseStepId(next.id).stepSlug : null;
   .sn-next { background: var(--color-accent); color: var(--color-accent-fg); border-color: var(--color-accent); }
   .sn-next:hover:not(.is-disabled) { color: var(--color-accent-fg); }
   .sn-next.is-disabled { opacity: 0.4; cursor: not-allowed; }
+  :global(.tutorial-completion) {
+    width: min(100%, 42rem);
+    display: grid;
+    gap: 0.9rem;
+  }
+  :global(.completion-status),
+  :global(.completion-card) {
+    border: var(--border-default, 2px) solid var(--color-border);
+    background: var(--color-surface);
+    padding: 1rem;
+  }
+  :global(.tutorial-completion.is-complete .completion-status) {
+    border-color: var(--color-success, var(--color-accent));
+    box-shadow: var(--shadow-raised);
+  }
+  :global(.completion-kicker),
+  :global(.completion-card-label),
+  :global(.completion-meta) {
+    display: block;
+    font-family: var(--font-mono);
+    font-size: 0.75rem;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+    color: var(--color-muted);
+  }
+  :global(.completion-status h2) {
+    margin: 0.3rem 0 0.25rem;
+    font-size: 1.25rem;
+    line-height: var(--leading-heading, 1.2);
+  }
+  :global(.completion-status p),
+  :global(.completion-card span) {
+    margin: 0;
+    color: var(--color-muted);
+  }
+  :global(.completion-actions) {
+    display: grid;
+    gap: 0.75rem;
+  }
+  :global(.completion-card) {
+    display: grid;
+    gap: 0.4rem;
+    color: var(--color-fg);
+    text-decoration: none;
+  }
+  :global(a.completion-card:hover) {
+    border-color: var(--color-accent);
+    transform: translate(-2px, -2px);
+    box-shadow: var(--shadow-raised);
+  }
+  :global(.completion-card-primary) {
+    border-color: var(--color-accent);
+  }
+  :global(.completion-card strong) {
+    font-size: 1.05rem;
+  }
+  :global(.tutorial-completion.is-locked .completion-status) {
+    opacity: 0.48;
+    filter: grayscale(1);
+    cursor: not-allowed;
+  }
+  @media (max-width: 760px) {
+    .step-nav,
+    .step-nav-final {
+      display: grid;
+      grid-template-columns: 1fr;
+    }
+    .sn-slot {
+      justify-content: stretch;
+    }
+    :global(.tutorial-completion) {
+      width: 100%;
+    }
+  }
 </style>

package/src/components/TutorialCompletion.tsx

@@ -0,0 +1,69 @@
+import { withBase } from "../lib/base";
+import { useProgress } from "../lib/progress/useProgress";
+import type { TutorialSummary } from "../lib/tutorialSummary";
+
+interface Props {
+  tutorialSlug: string;
+  totalSteps: number;
+  nextTutorial?: TutorialSummary;
+}
+
+function countCompletedSteps(steps: Record<string, unknown>, tutorialSlug: string): number {
+  return Object.entries(steps).filter(
+    ([key, value]) => key.startsWith(`${tutorialSlug}/`) && value === "complete",
+  ).length;
+}
+
+export default function TutorialCompletion({ tutorialSlug, totalSteps, nextTutorial }: Props) {
+  const { state } = useProgress();
+  const completedSteps = countCompletedSteps(state.steps, tutorialSlug);
+  const isComplete = totalSteps > 0 && completedSteps >= totalSteps;
+  const progressLabel = `${Math.min(completedSteps, totalSteps)} / ${totalSteps} steps complete`;
+
+  if (!isComplete) {
+    return (
+      <section className="tutorial-completion is-locked" aria-label="Tutorial completion">
+        <div className="completion-status" aria-disabled="true">
+          <span className="completion-kicker">Almost done</span>
+          <h2>Complete the remaining checkpoints to finish.</h2>
+          <p>
+            {progressLabel}
+            {nextTutorial ? ` Then you can continue to ${nextTutorial.title}.` : ""}
+          </p>
+        </div>
+      </section>
+    );
+  }
+
+  return (
+    <section className="tutorial-completion is-complete" aria-label="Tutorial completion">
+      <div className="completion-status">
+        <span className="completion-kicker">Tutorial complete</span>
+        <h2>You completed every step.</h2>
+        <p>{progressLabel}</p>
+      </div>
+      <div className="completion-actions">
+        {nextTutorial ? (
+          <a
+            className="completion-card completion-card-primary"
+            href={withBase(`/${nextTutorial.slug}`)}
+          >
+            <span className="completion-card-label">Continue learning</span>
+            <strong>{nextTutorial.title}</strong>
+            <span>{nextTutorial.description}</span>
+            <span className="completion-meta">
+              {nextTutorial.difficulty}
+              {nextTutorial.duration ? ` | ${nextTutorial.duration}` : ""}
+            </span>
+          </a>
+        ) : (
+          <a className="completion-card completion-card-primary" href={withBase("/")}>
+            <span className="completion-card-label">Browse tutorials</span>
+            <strong>Pick your next tutorial</strong>
+            <span>Browse the catalog and choose what to build next.</span>
+          </a>
+        )}
+      </div>
+    </section>
+  );
+}

package/src/components/mdx/Embed.astro

@@ -3,11 +3,18 @@ interface Props {
   src: string;
   title?: string;
   aspect?: string;
-  type?: "iframe" | "video";
+  type?: "iframe" | "video" | "slides";
+  slide?: string | number;
 }
-const { src, title = "Embedded content", aspect = "16/9", type = "iframe" } = Astro.props;
+const {
+  src,
+  title = "Embedded content",
+  aspect = "16/9",
+  type = "iframe",
+  slide,
+} = Astro.props;
 
-function normalize(url: string): string {
+function normalizeIframe(url: string): string {
   try {
     const u = new URL(url, "https://example.com");
     if (u.hostname.endsWith("youtube.com")) {
@@ -20,10 +27,53 @@ function normalize(url: string): string {
   }
 }
 
-const finalSrc = type === "iframe" ? normalize(src) : src;
+// Google Slides jumps to a slide via `slide=id.p<n>` for a numeric position, or
+// a raw object id (`id.g123abc`) passed through as-is.
+function googleSlideParam(value: string | number): string {
+  return typeof value === "number" ? `id.p${value}` : value;
+}
+
+function normalizeSlides(url: string, start?: string | number): string {
+  let u: URL;
+  try {
+    u = new URL(url);
+  } catch {
+    return url;
+  }
+  const isGoogleSlides =
+    u.hostname.endsWith("docs.google.com") && u.pathname.includes("/presentation/");
+  if (isGoogleSlides) {
+    u.pathname = u.pathname.replace(/\/(edit|pub|present|preview|view)$/, "/embed");
+    if (!u.pathname.endsWith("/embed")) {
+      u.pathname = `${u.pathname.replace(/\/$/, "")}/embed`;
+    }
+    // The editor URL carries the slide in a `#slide=...` fragment; the embed
+    // player reads it from the query string instead.
+    const fragmentSlide = u.hash.match(/slide=([^&]+)/);
+    if (fragmentSlide && !u.searchParams.has("slide")) {
+      u.searchParams.set("slide", fragmentSlide[1]);
+    }
+    u.hash = "";
+  }
+  if (start !== undefined) {
+    u.searchParams.set("slide", isGoogleSlides ? googleSlideParam(start) : String(start));
+  }
+  return u.toString();
+}
+
+const isVideo = type === "video";
+const finalSrc = isVideo
+  ? src
+  : type === "slides"
+    ? normalizeSlides(src, slide)
+    : normalizeIframe(src);
 ---
 <div class="embed" style={`aspect-ratio: ${aspect};`}>
-  {type === "iframe" ? (
+  {isVideo ? (
+    <video controls preload="metadata">
+      <source src={finalSrc} />
+    </video>
+  ) : (
     <iframe
       src={finalSrc}
       title={title}
@@ -32,10 +82,6 @@ const finalSrc = type === "iframe" ? normalize(src) : src;
       referrerpolicy="strict-origin-when-cross-origin"
       allowfullscreen
     />
-  ) : (
-    <video controls preload="metadata">
-      <source src={finalSrc} />
-    </video>
   )}
 </div>
 

package/src/index.ts

@@ -51,6 +51,12 @@ export {
 } from "./lib/progress/useProgress.ts";
 // Rehype plugin that lets Mermaid code fences round-trip as <pre class="mermaid">.
 export { default as rehypeMermaidPassthrough } from "./lib/rehype-mermaid-passthrough.ts";
+export {
+  createTutorialSummary,
+  type TutorialDifficulty,
+  type TutorialSummary,
+  type TutorialSummaryInput,
+} from "./lib/tutorialSummary.ts";
 
 // AI config type (consumers provide concrete values; framework consumes shape).
 export type { AiConfig } from "./types/ai.ts";

package/src/layouts/TutorialLayout.astro

@@ -5,6 +5,7 @@ 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";
+import type { TutorialSummary } from "../lib/tutorialSummary";
 
 interface Props {
   tutorial: TutorialEntry;
@@ -21,6 +22,7 @@ interface Props {
   repoUrl?: string;
   siteUrl?: string;
   siteCreditLabel?: string;
+  nextTutorial?: TutorialSummary;
   /** Set false to drop the built-in footer and supply your own. */
   showFooter?: boolean;
 }
@@ -40,6 +42,7 @@ const {
   repoUrl,
   siteUrl,
   siteCreditLabel,
+  nextTutorial,
   showFooter = true,
 } = Astro.props;
 
@@ -117,6 +120,7 @@ const trackBootstrap =
         currentStepSlug={currentStepSlug}
         gated={tutorial.data.gated}
         hasCheckpoint={hasCheckpoint}
+        nextTutorial={nextTutorial}
       />
 
       {tutorial.data.feedbackUrl && (

package/src/lib/heroMedia.ts

@@ -30,6 +30,16 @@ export function createHeroMediaSchema(
         caption: schema.string().min(1).optional(),
       })
       .strict(),
+    schema
+      .object({
+        kind: schema.literal("slides"),
+        src: schema.string().min(1),
+        title: schema.string().min(1),
+        aspect: schema.string().min(1).default("16/9"),
+        slide: schema.union([schema.string().min(1), schema.number()]).optional(),
+        caption: schema.string().min(1).optional(),
+      })
+      .strict(),
   ]);
 }
 

package/src/lib/tutorialSummary.ts

@@ -0,0 +1,32 @@
+export type TutorialDifficulty = "beginner" | "intermediate" | "advanced";
+
+export interface TutorialSummaryInput {
+  id: string;
+  data: {
+    title: string;
+    description: string;
+    difficulty: TutorialDifficulty;
+    estimatedDuration?: string;
+  };
+}
+
+export interface TutorialSummary {
+  slug: string;
+  title: string;
+  description: string;
+  difficulty: TutorialDifficulty;
+  duration?: string;
+}
+
+export function createTutorialSummary(
+  tutorial: TutorialSummaryInput,
+  summedDuration?: string,
+): TutorialSummary {
+  return {
+    slug: tutorial.id,
+    title: tutorial.data.title,
+    description: tutorial.data.description,
+    difficulty: tutorial.data.difficulty,
+    duration: tutorial.data.estimatedDuration ?? summedDuration,
+  };
+}

package/src/pages/TutorialStep.astro

@@ -5,11 +5,12 @@ import ChatButton from "../components/ai/ChatButton.tsx";
 import OpenInAgent from "../components/ai/OpenInAgent.tsx";
 import SelectionAsk from "../components/ai/SelectionAsk.tsx";
 import StepHelp from "../components/ai/StepHelp.tsx";
-import { parseStepId } from "../lib/content.ts";
+import { getStepsForTutorial, getTutorialBySlug, parseStepId, sumDurations } from "../lib/content.ts";
 import type { StepEntry, TutorialEntry } from "../lib/content.ts";
 import { mdxComponents } from "../lib/mdx-components.ts";
 import { buildContext } from "../lib/ai/context.ts";
 import { emptyState } from "../lib/progress/types.ts";
+import { createTutorialSummary } from "../lib/tutorialSummary.ts";
 import type { AiConfig } from "../types/ai.ts";
 
 interface Props {
@@ -51,6 +52,13 @@ const { Content } = await render(currentStep);
 
 const components = mdxComponents();
 const hasCheckpoint = currentStep.body?.includes("<Checkpoint") ?? false;
+const nextTutorial = tutorial.data.nextTutorial
+  ? await getTutorialBySlug(tutorial.data.nextTutorial)
+  : undefined;
+const nextTutorialSteps = nextTutorial ? await getStepsForTutorial(nextTutorial.id) : [];
+const nextTutorialSummary = nextTutorial
+  ? createTutorialSummary(nextTutorial, sumDurations(nextTutorialSteps))
+  : undefined;
 
 const aiConfig: AiConfig = { ...aiDefaults, ...(tutorial.data.ai ?? {}) };
 const initialContext = buildContext({
@@ -77,6 +85,7 @@ const initialContext = buildContext({
   repoUrl={repoUrl}
   siteUrl={siteUrl}
   siteCreditLabel={siteCreditLabel}
+  nextTutorial={nextTutorialSummary}
   showFooter={showFooter}
 >
   <slot name="head" slot="head" />

package/styles/components/chat.css

@@ -12,41 +12,27 @@
   display: inline-flex;
   align-items: center;
   gap: 0.5rem;
-  padding: 0.65rem 1rem;
-  background: linear-gradient(
-    135deg,
-    color-mix(in oklab, var(--color-accent) 92%, white),
-    var(--color-accent) 50%,
-    color-mix(in oklab, var(--color-accent) 80%, var(--color-fg))
-  );
-  color: var(--color-accent-fg);
-  border: 0;
+  padding: 0.55rem 0.9rem;
+  /* Ghost / outlined style: transparent surface so the button reads as a
+   * quiet affordance rather than a primary CTA. */
+  background: color-mix(in oklab, var(--color-surface) 70%, transparent);
+  color: var(--color-fg);
+  border: var(--border-default) solid color-mix(in oklab, var(--color-border) 80%, var(--color-accent));
   font-weight: 600;
   cursor: pointer;
-  /* Inset top-light for depth + a soft accent glow that lifts the
-   * button off the page bg without rounding the corners. */
-  box-shadow:
-    inset 0 1px 0 color-mix(in srgb, white 25%, transparent),
-    0 0 0 1px color-mix(in oklab, var(--color-accent) 60%, var(--color-fg)),
-    0 6px 20px color-mix(in oklab, var(--color-accent) 35%, transparent);
-  transition: transform 0.12s ease, box-shadow 0.12s ease, background-position 0.3s ease;
-  background-size: 140% 140%;
-  background-position: 0% 0%;
+  backdrop-filter: blur(6px);
+  transition: color 0.12s ease, border-color 0.12s ease, background 0.12s ease;
 }
 .chat-fab:hover {
-  transform: translateY(-1px);
-  background-position: 100% 100%;
-  box-shadow:
-    inset 0 1px 0 color-mix(in srgb, white 30%, transparent),
-    0 0 0 1px color-mix(in oklab, var(--color-accent) 70%, var(--color-fg)),
-    0 10px 26px color-mix(in oklab, var(--color-accent) 50%, transparent);
+  color: var(--color-accent);
+  border-color: var(--color-accent);
+  background: color-mix(in oklab, var(--color-accent) 10%, var(--color-surface));
 }
 .chat-fab:active {
-  transform: translateY(0);
+  background: color-mix(in oklab, var(--color-accent) 16%, var(--color-surface));
 }
 .chat-fab :is(svg) {
-  /* Tiny shadow under the Sparkles so it reads as an icon, not paint. */
-  filter: drop-shadow(0 1px 0 color-mix(in srgb, black 30%, transparent));
+  color: var(--color-accent);
 }
 
 .chat-panel {