handzon-core 0.14.1 → 0.15.1

package/package.json

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

@@ -2,6 +2,7 @@
 import { withBase } from "../lib/base";
 import type { TutorialEntry, StepEntry } from "../lib/content";
 import { parseStepId } from "../lib/content";
+import { STORAGE_KEY } from "../lib/progress/types";
 import { fallbackTextForTrack, iconForTrack } from "../lib/track-icons";
 import Progress from "./Progress.tsx";
 import TrackSelector from "./TrackSelector.tsx";
@@ -87,6 +88,40 @@ const slug = tutorial.id;
   </ol>
 </aside>
 
+{/* Pre-paint: mirror the persisted progress state into the SSR sidebar
+    before hydrated modules run, avoiding a step-change flash from
+    0 / unchecked to the learner's real progress. */}
+<script is:inline define:vars={{ storageKey: STORAGE_KEY, tutorialSlug: slug, totalSteps: steps.length }}>
+  (function () {
+    try {
+      var raw = window.localStorage.getItem(storageKey);
+      var state = raw ? JSON.parse(raw) : null;
+      var steps = (state && state.steps) || {};
+      var completed = 0;
+
+      document.querySelectorAll("[data-step-key]").forEach(function (el) {
+        var key = el.getAttribute("data-step-key");
+        var done = key && steps[key] === "complete";
+        el.setAttribute("data-done", done ? "true" : "false");
+        if (done && key.indexOf(tutorialSlug + "/") === 0) completed += 1;
+      });
+
+      var progress = document.querySelector(".sidebar .progress");
+      if (!progress) return;
+      var bounded = Math.min(completed, totalSteps);
+      var pct = totalSteps > 0 ? Math.round((bounded / totalSteps) * 100) : 0;
+      progress.setAttribute("aria-label", bounded + " of " + totalSteps + " steps complete");
+      progress.setAttribute("aria-valuenow", String(bounded));
+      var fill = progress.querySelector(".progress-fill");
+      if (fill) fill.style.width = pct + "%";
+      var label = progress.querySelector(".progress-label");
+      if (label) label.textContent = bounded + " / " + totalSteps + " steps";
+    } catch (e) {
+      /* ignore — hydrated progress will correct the sidebar */
+    }
+  })();
+</script>
+
 <script>
   // Hydrate per-step check marks from localStorage without an island.
   import { getStore } from "../lib/progress/local";

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/auth/UserMenu.astro

@@ -6,30 +6,126 @@
  * `Astro.request.headers` access at render time, no warning when a
  * prerendered route happens to include BaseLayout.
  */
+import { withBase } from "../../lib/base";
 import UserMenuIsland from "./UserMenu.tsx";
 
+// Shared with UserMenu.tsx's readAuthSnapshot/writeAuthSnapshot — the
+// inline script below reads this key before paint to swap the static
+// fallback to the cached signed-in state, removing the nav reload flash.
+const AUTH_SNAPSHOT_KEY = "hz-auth-snapshot";
+const TOKENS_HREF = withBase("/settings/tokens");
+
 const GITHUB_ICON_PATH =
   "M12 .5C5.65.5.5 5.65 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.55v-2.02c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.03 1.76 2.7 1.25 3.36.96.1-.74.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.66 0-1.25.45-2.27 1.18-3.07-.12-.29-.51-1.45.11-3.03 0 0 .96-.31 3.15 1.17a10.94 10.94 0 0 1 5.76 0c2.19-1.48 3.15-1.17 3.15-1.17.62 1.58.23 2.74.11 3.03.74.8 1.18 1.82 1.18 3.07 0 4.4-2.69 5.37-5.25 5.65.41.35.78 1.04.78 2.11v3.13c0 .3.21.66.79.55C20.71 21.39 24 17.08 24 12 24 5.65 18.85.5 12 .5z";
 ---
 <div class="user-menu-shell">
   <div class="user-menu um-fallback" data-user-menu-fallback aria-hidden="true">
-    <button type="button" class="um-btn" disabled tabindex="-1">
-      <svg
-        class="um-gh"
-        viewBox="0 0 24 24"
-        width="14"
-        height="14"
-        fill="currentColor"
-        aria-hidden="true"
-      >
-        <path d={GITHUB_ICON_PATH} />
-      </svg>
-      <span>Sign in with GitHub</span>
-    </button>
+    {/* Signed-out placeholder. Shown by default; the inline script below
+        hides it when a cached signed-in snapshot exists. */}
+    <span class="um-fallback-variant" data-um-fallback-signedout>
+      <button type="button" class="um-btn" disabled tabindex="-1">
+        <svg
+          class="um-gh"
+          viewBox="0 0 24 24"
+          width="14"
+          height="14"
+          fill="currentColor"
+          aria-hidden="true"
+        >
+          <path d={GITHUB_ICON_PATH} />
+        </svg>
+        <span>Sign in with GitHub</span>
+      </button>
+    </span>
+    {/* Signed-in placeholder. Hidden until the inline script fills in the
+        cached avatar + name and reveals it. Mirrors the island's
+        signed-in layout so the swap on hydration is invisible. */}
+    <span class="um-fallback-variant" data-um-fallback-signedin hidden>
+      <img class="um-avatar" alt="" data-um-avatar hidden />
+      <span class="um-avatar um-avatar-fallback" aria-hidden="true" data-um-initial hidden></span>
+      <span class="um-name" data-um-name></span>
+      <a class="um-btn um-mcp-btn" href={TOKENS_HREF} tabindex="-1">
+        <svg
+          viewBox="0 0 24 24"
+          width="14"
+          height="14"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <circle cx="7.5" cy="15.5" r="4.5" />
+          <path d="M11 12L20 3l1.5 1.5L20 6l1.5 1.5L19 9l-1.5-1.5L16 9" />
+        </svg>
+        <span>MCP setup</span>
+      </a>
+      <button type="button" class="um-btn um-btn-icon" disabled tabindex="-1">
+        <svg
+          viewBox="0 0 24 24"
+          width="14"
+          height="14"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4" />
+          <polyline points="16 17 21 12 16 7" />
+          <line x1="21" y1="12" x2="9" y2="12" />
+        </svg>
+        <span class="sr-only">Sign out</span>
+      </button>
+    </span>
   </div>
   <UserMenuIsland client:only="react" />
 </div>
 
+{/* Pre-paint: read the cached session snapshot and, if signed in, swap
+    the static fallback to an avatar + name placeholder before the first
+    frame. Runs inline (blocking) so there's no flash of "Sign in with
+    GitHub" for returning signed-in users. */}
+<script is:inline define:vars={{ snapshotKey: AUTH_SNAPSHOT_KEY }}>
+  (function () {
+    try {
+      var raw = window.localStorage.getItem(snapshotKey);
+      if (!raw) return;
+      var user = (JSON.parse(raw) || {}).user;
+      if (!user) return; // signed out → keep the default placeholder
+      var root = document.querySelector("[data-user-menu-fallback]");
+      if (!root) return;
+      var signedOut = root.querySelector("[data-um-fallback-signedout]");
+      var signedIn = root.querySelector("[data-um-fallback-signedin]");
+      if (!signedOut || !signedIn) return;
+
+      var label = user.name || user.email || "Signed in";
+      var first = String(label).trim().split(/\s+/)[0] || "Signed in";
+      var nameEl = signedIn.querySelector("[data-um-name]");
+      if (nameEl) {
+        nameEl.textContent = first;
+        nameEl.setAttribute("title", label);
+      }
+      var avatar = signedIn.querySelector("[data-um-avatar]");
+      var initial = signedIn.querySelector("[data-um-initial]");
+      if (user.image && avatar) {
+        avatar.src = user.image;
+        avatar.alt = label;
+        avatar.hidden = false;
+      } else if (initial) {
+        initial.textContent = label.trim().charAt(0).toUpperCase();
+        initial.hidden = false;
+      }
+      signedOut.hidden = true;
+      signedIn.hidden = false;
+    } catch (e) {
+      /* ignore — fall back to the default signed-out placeholder */
+    }
+  })();
+</script>
+
 <style is:global>
   .user-menu-shell {
     display: grid;
@@ -76,6 +172,14 @@ const GITHUB_ICON_PATH =
   .um-fallback[hidden] {
     display: none;
   }
+  /* Variants flow their children directly into the .user-menu flex row
+     (so the parent's gap applies), and collapse fully when hidden. */
+  .um-fallback-variant {
+    display: contents;
+  }
+  .um-fallback-variant[hidden] {
+    display: none;
+  }
   .um-btn {
     display: inline-flex;
     align-items: center;

package/src/components/auth/UserMenu.tsx

@@ -27,15 +27,72 @@ interface Session {
   user?: SessionUser;
 }
 
+// Key for the client-side session snapshot. Shared with the inline
+// pre-paint script in UserMenu.astro — keep both in sync.
+const AUTH_SNAPSHOT_KEY = "hz-auth-snapshot";
+
+// Read the last-known session synchronously so the island can paint the
+// correct menu on its very first render instead of waiting a network
+// round-trip (the source of the nav "reload flash"). Returns:
+//  - `undefined` → never resolved on this device; render nothing yet
+//  - `null`      → last known to be signed out
+//  - Session     → last known signed-in user
+function readAuthSnapshot(): Session | null | undefined {
+  if (typeof window === "undefined") return undefined;
+  try {
+    const raw = window.localStorage.getItem(AUTH_SNAPSHOT_KEY);
+    if (!raw) return undefined;
+    const parsed = JSON.parse(raw) as { user?: SessionUser | null };
+    return parsed?.user ? { user: parsed.user } : null;
+  } catch {
+    return undefined;
+  }
+}
+
+// Persist a minimal, non-sensitive snapshot (name/email/image) so the
+// next page load can render optimistically. Stores `{ user: null }` when
+// signed out so a returning signed-out user also skips the loading gap.
+function writeAuthSnapshot(session: Session | null) {
+  if (typeof window === "undefined") return;
+  try {
+    const user = session?.user
+      ? {
+          name: session.user.name ?? null,
+          email: session.user.email ?? null,
+          image: session.user.image ?? null,
+        }
+      : null;
+    window.localStorage.setItem(AUTH_SNAPSHOT_KEY, JSON.stringify({ user }));
+  } catch {
+    /* storage unavailable (private mode, quota) — degrade to no cache */
+  }
+}
+
+function clearAuthSnapshot() {
+  if (typeof window === "undefined") return;
+  try {
+    window.localStorage.removeItem(AUTH_SNAPSHOT_KEY);
+  } catch {
+    /* storage unavailable (private mode, quota) — degrade to no cache */
+  }
+}
+
 const GITHUB_ICON_PATH =
   "M12 .5C5.65.5.5 5.65.5 12c0 5.08 3.29 9.39 7.86 10.91.58.11.79-.25.79-.55v-2.02c-3.2.7-3.88-1.36-3.88-1.36-.52-1.33-1.28-1.68-1.28-1.68-1.04-.71.08-.7.08-.7 1.15.08 1.76 1.18 1.76 1.18 1.03 1.76 2.7 1.25 3.36.96.1-.74.4-1.25.72-1.54-2.55-.29-5.24-1.27-5.24-5.66 0-1.25.45-2.27 1.18-3.07-.12-.29-.51-1.45.11-3.03 0 0 .96-.31 3.15 1.17a10.94 10.94 0 0 1 5.76 0c2.19-1.48 3.15-1.17 3.15-1.17.62 1.58.23 2.74.11 3.03.74.8 1.18 1.82 1.18 3.07 0 4.4-2.69 5.37-5.25 5.65.41.35.78 1.04.78 2.11v3.13c0 .3.21.66.79.55C20.71 21.39 24 17.08 24 12 24 5.65 18.85.5 12 .5z";
 
 export default function UserMenu() {
   // `undefined` = not yet loaded; `null` = no auth or signed out;
-  // object = signed in. The tri-state avoids flashing the sign-in
+  // object = signed in. Seeded from the last-known snapshot so a
+  // returning user paints the right menu immediately, then revalidated
+  // by the fetch below. The tri-state avoids flashing the sign-in
   // button while the session fetch is in flight.
-  const [session, setSession] = useState<Session | null | undefined>(undefined);
+  const [session, setSession] = useState<Session | null | undefined>(readAuthSnapshot);
   const [csrfToken, setCsrfToken] = useState<string | null>(null);
+  // Flips true once the network fetch settles (success, 404, or error).
+  // Lets us tell a *cached* signed-out state (keep the static fallback
+  // visible until we know more) apart from a *resolved* not-wired state
+  // (hide the fallback so Tier-1 scaffolds show no dead UI).
+  const [resolved, setResolved] = useState(false);
 
   useEffect(() => {
     let cancelled = false;
@@ -50,16 +107,23 @@ export default function UserMenu() {
         if (!sessRes.ok || !csrfRes.ok) {
           setSession(null);
           setCsrfToken(null);
+          setResolved(true);
+          clearAuthSnapshot();
           return;
         }
         const sess = (await sessRes.json()) as Session | null;
         const csrf = (await csrfRes.json()) as { csrfToken?: string } | null;
-        setSession(sess?.user ? sess : null);
+        const nextSession = sess?.user ? sess : null;
+        setSession(nextSession);
         setCsrfToken(csrf?.csrfToken ?? null);
+        setResolved(true);
+        writeAuthSnapshot(nextSession);
       } catch {
         if (!cancelled) {
           setSession(null);
           setCsrfToken(null);
+          setResolved(true);
+          clearAuthSnapshot();
         }
       }
     })();
@@ -69,16 +133,28 @@ export default function UserMenu() {
   }, []);
 
   useEffect(() => {
-    if (session === undefined) return;
+    // Only retire the static fallback once the island has something to
+    // show in its place (a known user or the wired sign-in form) or the
+    // fetch has resolved with nothing to show (Tier-1). Until then, keep
+    // the server-rendered fallback so the nav never goes blank.
+    const islandHasContent = Boolean(session?.user) || Boolean(csrfToken);
+    if (!islandHasContent && !resolved) return;
     document.querySelectorAll<HTMLElement>("[data-user-menu-fallback]").forEach((el) => {
       el.hidden = true;
     });
-  }, [session]);
-
-  // Loading or auth not wired → render nothing.
-  if (session === undefined || !csrfToken) return null;
+  }, [session, csrfToken, resolved]);
 
   const user = session?.user;
+
+  // Render nothing until we either know a signed-in user (from the cache
+  // or the fetch) or have confirmed auth is wired (csrf token present).
+  // A cached user paints immediately — that's what kills the reload
+  // flash. Withholding the signed-out form until csrf loads keeps
+  // Tier-1 scaffolds — where the auth endpoints 404, so csrf stays
+  // null — from surfacing a dead "Sign in with GitHub" button, and
+  // avoids a tokenless form before the round-trip completes.
+  if (!user && !csrfToken) return null;
+
   const callbackUrl = typeof window !== "undefined" ? window.location.href : withBase("/");
 
   // Compact label for the topbar: first word of `name`, falling back
@@ -127,10 +203,19 @@ export default function UserMenu() {
             </svg>
             <span>MCP setup</span>
           </a>
-          <form method="post" action={withBase("/api/auth/signout")}>
-            <input type="hidden" name="csrfToken" value={csrfToken} />
+          <form
+            method="post"
+            action={withBase("/api/auth/signout")}
+            onSubmit={() => writeAuthSnapshot(null)}
+          >
+            <input type="hidden" name="csrfToken" value={csrfToken ?? ""} />
             <input type="hidden" name="callbackUrl" value={callbackUrl} />
-            <button type="submit" className="um-btn um-btn-icon" title="Sign out">
+            <button
+              type="submit"
+              className="um-btn um-btn-icon"
+              title="Sign out"
+              disabled={!csrfToken}
+            >
               <svg
                 viewBox="0 0 24 24"
                 width="14"
@@ -152,9 +237,9 @@ export default function UserMenu() {
         </>
       ) : (
         <form method="post" action={withBase("/api/auth/signin/github")}>
-          <input type="hidden" name="csrfToken" value={csrfToken} />
+          <input type="hidden" name="csrfToken" value={csrfToken ?? ""} />
           <input type="hidden" name="callbackUrl" value={callbackUrl} />
-          <button type="submit" className="um-btn">
+          <button type="submit" className="um-btn" disabled={!csrfToken}>
             <svg
               className="um-gh"
               viewBox="0 0 24 24"

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 {