handzon-core 0.15.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.15.0",
+  "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/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"