handzon-core 0.8.1 → 0.8.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "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/Navbar.astro

@@ -12,15 +12,36 @@ import UserMenu from "./auth/UserMenu.astro";
 interface Props {
   logoUrl?: string;
   siteName?: string;
+  /**
+   * Intrinsic aspect ratio of the logo (in the image's native units —
+   * only the ratio matters). Forwarded to the <img> element's
+   * `width`/`height` attributes so the browser reserves the correct
+   * box before the SVG loads, preventing CLS in the navbar row.
+   * Defaults track the shipped `public/logo.svg`. Override both when
+   * the consumer swaps in a non-square logo.
+   */
+  logoWidth?: number;
+  logoHeight?: number;
 }
 
-const { logoUrl = "/logo.svg", siteName = "Handzon" } = Astro.props;
+const {
+  logoUrl = "/logo.svg",
+  siteName = "Handzon",
+  logoWidth = 76,
+  logoHeight = 58,
+} = Astro.props;
 ---
 <header class="hz-nav">
   <div class="hz-nav-inner">
     {logoUrl && (
       <a href="/" class="hz-nav-brand" aria-label={`${siteName} home`}>
-        <img src={logoUrl} alt={siteName} class="hz-nav-logo" />
+        <img
+          src={logoUrl}
+          alt={siteName}
+          class="hz-nav-logo"
+          width={logoWidth}
+          height={logoHeight}
+        />
       </a>
     )}
     <div class="hz-nav-actions">

package/src/components/Sidebar.astro

@@ -120,18 +120,33 @@ const slug = tutorial.id;
   .sb-steps li + li {
     border-top: var(--border-default) solid var(--color-border);
   }
+  /* Single-row grid (check + name) with the duration pinned absolutely
+   * to the top-right corner. Pulling it out of the grid flow means the
+   * title row gets the full cell height — checkbox and title stay
+   * vertically centered together, and the duration doesn't crowd the
+   * top of long, wrapping titles the way a stacked grid track did.
+   * `padding-right` on `.sb-name` reserves space so wrapping titles
+   * never collide with the corner-stamped duration. */
   .sb-steps a {
+    position: relative;
     display: grid;
-    grid-template-columns: 18px 1fr auto;
+    grid-template-columns: 18px 1fr;
     align-items: center;
-    gap: 0.6rem;
-    padding: 0.6rem 1rem;
+    column-gap: 0.6rem;
+    padding: 1.05rem 1rem;
     color: var(--color-fg);
     text-decoration: none;
     font-size: 0.92em;
     font-weight: 500;
     letter-spacing: -0.005em;
   }
+  .sb-name { line-height: 1.3; padding-right: 3.25rem; }
+  .sb-dur {
+    position: absolute;
+    top: 0.55rem;
+    right: 1rem;
+    line-height: 1;
+  }
   .sb-steps a:hover {
     background: var(--color-surface);
     color: var(--color-fg);

package/src/components/home/Hero.astro

@@ -8,17 +8,36 @@ interface Props {
    * to hide the logo entirely.
    */
   logoUrl?: string;
+  /**
+   * Intrinsic aspect ratio of the logo, supplied as the SVG/image's
+   * native width and height (any unit — only the ratio matters). The
+   * browser uses these to reserve the correct box size before the
+   * image loads, preventing CLS as surrounding text reflows. Defaults
+   * track the shipped `public/logo.svg` (`viewBox="10 20 76 58"`).
+   * Override both when swapping in a non-square logo.
+   */
+  logoWidth?: number;
+  logoHeight?: number;
 }
 const {
   title = "Handzon.",
   subtitle = "Step-by-step tutorials.",
   logoUrl = "/logo.svg",
+  logoWidth = 76,
+  logoHeight = 58,
 } = Astro.props;
 ---
 <header class="hero">
   <h1 class="hero-headline">
     {logoUrl && (
-      <img class="hero-logo" src={logoUrl} alt="" aria-hidden="true" />
+      <img
+        class="hero-logo"
+        src={logoUrl}
+        alt=""
+        aria-hidden="true"
+        width={logoWidth}
+        height={logoHeight}
+      />
     )}
     <span>{title}</span>
   </h1>

package/src/layouts/BaseLayout.astro

@@ -18,6 +18,15 @@ interface Props {
   nav?: "full" | "userMenu" | "none";
   /** Logo URL passed to Navbar (when nav === "full"). */
   logoUrl?: string;
+  /**
+   * Intrinsic logo aspect ratio (in the image's native units, ratio
+   * only). Forwarded to the Navbar's <img> as `width`/`height` so the
+   * browser reserves correct box size before the SVG arrives,
+   * preventing CLS in the navbar row. Override both for non-square
+   * logos.
+   */
+  logoWidth?: number;
+  logoHeight?: number;
   /** Favicon URL injected into <head>. */
   faviconUrl?: string;
   /** Show the site footer ("Built with Handzon" + repo link). */
@@ -48,6 +57,8 @@ const {
   tagline = "Hands-on tutorials",
   nav = "full",
   logoUrl = "/logo.svg",
+  logoWidth = 76,
+  logoHeight = 58,
   faviconUrl = "/favicon.svg",
   showFooter = true,
   repoUrl,
@@ -84,7 +95,12 @@ const desc = description ?? tagline;
   </head>
   <body style={`--hz-page-max-width: ${resolvedMaxWidth}; --hz-page-padding-x: ${pagePaddingX}; --hz-nav-height: 3rem;`}>
     {nav === "full" && (
-      <Navbar logoUrl={logoUrl} siteName={siteName} />
+      <Navbar
+        logoUrl={logoUrl}
+        siteName={siteName}
+        logoWidth={logoWidth}
+        logoHeight={logoHeight}
+      />
     )}
     {nav === "userMenu" && (
       <div class="hz-topbar">

package/src/layouts/TutorialLayout.astro

@@ -14,6 +14,8 @@ interface Props {
   siteName?: string;
   tagline?: string;
   logoUrl?: string;
+  logoWidth?: number;
+  logoHeight?: number;
   faviconUrl?: string;
   repoUrl?: string;
 }
@@ -27,6 +29,8 @@ const {
   siteName,
   tagline,
   logoUrl,
+  logoWidth,
+  logoHeight,
   faviconUrl,
   repoUrl,
 } = Astro.props;
@@ -39,6 +43,8 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
   siteName={siteName}
   tagline={tagline}
   logoUrl={logoUrl}
+  logoWidth={logoWidth}
+  logoHeight={logoHeight}
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
 >
@@ -209,8 +215,18 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
   }
   .main {
     padding: 2rem clamp(1rem, 4vw, 3rem);
+    /* 80ch is the upper end of comfortable prose width; on wide
+     * viewports we trade a little of that for code-block headroom so
+     * fenced blocks wrap less aggressively. Capped at 92ch — past
+     * that body prose starts to feel like a magazine column. */
     max-width: 80ch;
   }
+  @media (min-width: 1280px) {
+    .main { max-width: 88ch; }
+  }
+  @media (min-width: 1600px) {
+    .main { max-width: 92ch; }
+  }
   .crumb {
     font-family: var(--font-mono);
     font-size: 0.75em;

package/src/pages/Home.astro

@@ -12,6 +12,8 @@ interface Props {
   tagline?: string;
   hero?: { title?: string; subtitle?: string };
   logoUrl?: string;
+  logoWidth?: number;
+  logoHeight?: number;
   faviconUrl?: string;
   repoUrl?: string;
   showResumeRail?: boolean;
@@ -25,6 +27,8 @@ const {
   tagline = "Hands-on tutorials",
   hero,
   logoUrl,
+  logoWidth,
+  logoHeight,
   faviconUrl,
   repoUrl,
   showResumeRail = true,
@@ -56,13 +60,21 @@ for (const t of tutorials) {
   siteName={siteName}
   tagline={tagline}
   logoUrl={logoUrl}
+  logoWidth={logoWidth}
+  logoHeight={logoHeight}
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
   nav="userMenu"
 >
   <slot name="head" slot="head" />
   <div class="home">
-    <Hero title={hero?.title} subtitle={hero?.subtitle} logoUrl={logoUrl} />
+    <Hero
+      title={hero?.title}
+      subtitle={hero?.subtitle}
+      logoUrl={logoUrl}
+      logoWidth={logoWidth}
+      logoHeight={logoHeight}
+    />
 
     {showResumeRail && (
       <ResumeRail client:load tutorials={compactTutorials} />

package/src/pages/TutorialLanding.astro

@@ -8,11 +8,22 @@ interface Props {
   siteName?: string;
   tagline?: string;
   logoUrl?: string;
+  logoWidth?: number;
+  logoHeight?: number;
   faviconUrl?: string;
   repoUrl?: string;
 }
 
-const { tutorial, siteName, tagline, logoUrl, faviconUrl, repoUrl } = Astro.props;
+const {
+  tutorial,
+  siteName,
+  tagline,
+  logoUrl,
+  logoWidth,
+  logoHeight,
+  faviconUrl,
+  repoUrl,
+} = Astro.props;
 const steps = await getStepsForTutorial(tutorial.id);
 const duration = tutorial.data.estimatedDuration ?? sumDurations(steps) ?? "";
 const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
@@ -23,6 +34,8 @@ const firstStepSlug = steps[0] ? parseStepId(steps[0].id).stepSlug : null;
   siteName={siteName}
   tagline={tagline}
   logoUrl={logoUrl}
+  logoWidth={logoWidth}
+  logoHeight={logoHeight}
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
 >

package/src/pages/TutorialStep.astro

@@ -20,6 +20,8 @@ interface Props {
   siteName?: string;
   tagline?: string;
   logoUrl?: string;
+  logoWidth?: number;
+  logoHeight?: number;
   faviconUrl?: string;
   repoUrl?: string;
 }
@@ -32,6 +34,8 @@ const {
   siteName,
   tagline,
   logoUrl,
+  logoWidth,
+  logoHeight,
   faviconUrl,
   repoUrl,
 } = Astro.props;
@@ -60,6 +64,8 @@ const initialContext = buildContext({
   siteName={siteName}
   tagline={tagline}
   logoUrl={logoUrl}
+  logoWidth={logoWidth}
+  logoHeight={logoHeight}
   faviconUrl={faviconUrl}
   repoUrl={repoUrl}
 >