handzon-core 0.8.4 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.8.4",
+  "version": "0.9.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"
@@ -65,12 +65,14 @@
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",
     "astro": "^6.3.5",
+    "tsx": "^4.22.3",
     "typescript": "^6.0.3"
   },
   "engines": {
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "echo 'handzon-core ships source — Astro type-checks at consume time'"
+    "build": "echo 'handzon-core ships source — Astro type-checks at consume time'",
+    "test": "node --import tsx --test tests/*.test.ts"
   }
 }

package/src/collections.ts

@@ -187,6 +187,35 @@ export const verifySchema = z.object({
 
 export type VerifySpec = z.infer<typeof verifySchema>;
 
+export const starterSchema = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("git"),
+      repo: z.string().url(),
+      ref: z.string().min(1).optional(),
+      subdir: z.string().min(1).optional(),
+      targetDir: z.string().min(1).optional(),
+      setupCommands: z.array(z.string().min(1)).default([]),
+      devCommand: z.string().min(1).optional(),
+      openPath: z.string().min(1).optional(),
+      notes: z.array(z.string().min(1)).default([]),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("command"),
+      initCommand: z.string().min(1),
+      targetDir: z.string().min(1).optional(),
+      setupCommands: z.array(z.string().min(1)).default([]),
+      devCommand: z.string().min(1).optional(),
+      openPath: z.string().min(1).optional(),
+      notes: z.array(z.string().min(1)).default([]),
+    })
+    .strict(),
+]);
+
+export type StarterSpec = z.infer<typeof starterSchema>;
+
 /** Schema for tutorial step entries. */
 export const stepsSchema = z.object({
   title: z.string(),
@@ -226,6 +255,7 @@ export function tutorialsSchema({ image }: { image: () => import("astro/zod").Zo
     gated: z.boolean().default(false),
     showProgress: z.boolean().default(true),
     feedbackUrl: z.string().url().optional(),
+    starter: starterSchema.optional(),
     ai: z
       .object({
         enabled: z.boolean().optional(),

package/src/components/Navbar.astro

@@ -33,17 +33,19 @@ const {
 ---
 <header class="hz-nav">
   <div class="hz-nav-inner">
-    {logoUrl && (
-      <a href="/" class="hz-nav-brand" aria-label={`${siteName} home`}>
+    <a href="/" class="hz-nav-brand" aria-label={`${siteName} home`}>
+      {logoUrl && (
         <img
           src={logoUrl}
-          alt={siteName}
+          alt=""
+          aria-hidden="true"
           class="hz-nav-logo"
           width={logoWidth}
           height={logoHeight}
         />
-      </a>
-    )}
+      )}
+      <span class="hz-nav-name">{siteName}</span>
+    </a>
     <div class="hz-nav-actions">
       <UserMenu />
     </div>
@@ -77,8 +79,11 @@ const {
   .hz-nav-brand {
     display: inline-flex;
     align-items: center;
-    line-height: 0;
+    gap: 0.45rem;
+    line-height: 1;
     opacity: 0.92;
+    color: var(--color-fg);
+    text-decoration: none;
     transition: opacity 0.12s ease;
   }
   .hz-nav-brand:hover { opacity: 1; }
@@ -86,6 +91,18 @@ const {
     display: block;
     height: 1.4rem;
     width: auto;
+    flex-shrink: 0;
+  }
+  /* Matches the Hero headline's font choice so the wordmark reads as
+     the same brand across the homepage hero and every-other-page nav.
+     Smaller, no display tracking — this is a chrome label, not a
+     headline. */
+  .hz-nav-name {
+    font-family: var(--font-display, var(--font-sans));
+    font-weight: var(--font-weight-display, 700);
+    font-size: 1.05rem;
+    letter-spacing: var(--tracking-display, -0.02em);
+    white-space: nowrap;
   }
   .hz-nav-actions {
     display: flex;

package/src/components/home/Hero.astro

@@ -74,7 +74,8 @@ const {
     font-size: 1.125rem;
     line-height: 1.55;
     color: var(--color-muted);
-    max-width: 60ch;
+    max-width: min(100%, 86ch);
     margin: 0;
+    text-wrap: pretty;
   }
 </style>

package/src/layouts/TutorialLayout.astro

@@ -214,18 +214,25 @@ const stepSlugs = steps.map((s) => parseStepId(s.id).stepSlug);
     height: calc(100dvh - var(--hz-nav-height, 3rem));
   }
   .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. */
+    padding: 2rem clamp(1rem, 4vw, 4rem);
+    /* Keep tutorial pages roomy enough for code-heavy components. Prose
+     * itself is constrained below so paragraphs do not become too wide. */
+    max-width: 86ch;
+  }
+  .main > .prose {
+    max-width: 100%;
+  }
+  .main > .prose > :where(p, ul, ol, blockquote, h2, h3, h4, h5, h6) {
     max-width: 80ch;
   }
   @media (min-width: 1280px) {
-    .main { max-width: 88ch; }
+    .main { max-width: 104ch; }
   }
   @media (min-width: 1600px) {
-    .main { max-width: 92ch; }
+    .main { max-width: 118ch; }
+  }
+  @media (min-width: 1920px) {
+    .main { max-width: 128ch; }
   }
   .crumb {
     font-family: var(--font-mono);

package/src/server/mcp/startTutorial.ts

@@ -0,0 +1,150 @@
+import type { StarterSpec, VerifySpec } from "../../collections.ts";
+import { type McpTool, text } from "./protocol.ts";
+
+interface StartTutorialStep {
+  slug: string;
+  order: number;
+  title: string;
+  summary?: string;
+  duration?: string;
+  verify?: VerifySpec | null;
+}
+
+interface StartTutorialInput {
+  tutorial: {
+    slug: string;
+    title: string;
+    description: string;
+    difficulty: string;
+    tags: string[];
+    starter?: StarterSpec;
+  };
+  steps: StartTutorialStep[];
+  workspaceName?: string;
+}
+
+export type LoadStartTutorial = (
+  slug: string,
+) => Promise<Omit<StartTutorialInput, "workspaceName"> | null>;
+
+export interface StartTutorialPayload {
+  tutorial: {
+    slug: string;
+    title: string;
+    description: string;
+    difficulty: string;
+    tags: string[];
+  };
+  starter: StarterSpec | null;
+  workspace: {
+    targetDir: string;
+    openPath: string;
+  };
+  commands: string[];
+  firstStep: StartTutorialStep;
+  next: string[];
+}
+
+function pathForCommand(...parts: string[]) {
+  return parts.filter(Boolean).join("/");
+}
+
+function resolveTargetDir(
+  slug: string,
+  starter: StarterSpec | undefined,
+  workspaceName: string | undefined,
+) {
+  return workspaceName ?? starter?.targetDir ?? slug;
+}
+
+function resolveOpenPath(targetDir: string, starter: StarterSpec | undefined) {
+  if (!starter) return targetDir;
+  if (starter.openPath) {
+    return starter.openPath === "." ? targetDir : starter.openPath;
+  }
+  if (starter.kind === "git" && starter.subdir) return pathForCommand(targetDir, starter.subdir);
+  return targetDir;
+}
+
+function buildCommands(starter: StarterSpec | undefined, targetDir: string, openPath: string) {
+  if (!starter) return [];
+  const commands: string[] = [];
+  if (starter.kind === "git") {
+    const ref = starter.ref ? ` --branch ${starter.ref}` : "";
+    commands.push(`git clone${ref} ${starter.repo} ${targetDir}`);
+  } else {
+    commands.push(starter.initCommand);
+  }
+  commands.push(`cd ${openPath}`);
+  commands.push(...starter.setupCommands);
+  return commands;
+}
+
+export function buildStartTutorialPayload({
+  tutorial,
+  steps,
+  workspaceName,
+}: StartTutorialInput): StartTutorialPayload {
+  const [firstStep] = [...steps].sort((a, b) => a.order - b.order);
+  if (!firstStep) {
+    throw new Error(`Tutorial ${tutorial.slug} has no steps.`);
+  }
+
+  const targetDir = resolveTargetDir(tutorial.slug, tutorial.starter, workspaceName);
+  const openPath = resolveOpenPath(targetDir, tutorial.starter);
+  const commands = buildCommands(tutorial.starter, targetDir, openPath);
+
+  return {
+    tutorial: {
+      slug: tutorial.slug,
+      title: tutorial.title,
+      description: tutorial.description,
+      difficulty: tutorial.difficulty,
+      tags: tutorial.tags,
+    },
+    starter: tutorial.starter ?? null,
+    workspace: { targetDir, openPath },
+    commands,
+    firstStep,
+    next: [
+      `Call get_step with tutorial=${tutorial.slug} and step=${firstStep.slug}.`,
+      "Run the step locally in the prepared workspace.",
+      firstStep.verify
+        ? "If the step has verify checks, collect observations and call submit_verification."
+        : "If the step has only a prose checkpoint, inspect the result before calling complete_checkpoint.",
+    ],
+  };
+}
+
+export function createStartTutorialTool(load: LoadStartTutorial): McpTool {
+  return {
+    name: "start_tutorial",
+    description:
+      "Return local bootstrap commands and next MCP actions for starting a tutorial from a blank workspace.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        slug: { type: "string", minLength: 1 },
+        workspaceName: {
+          type: "string",
+          minLength: 1,
+          description:
+            "Optional local directory name to use instead of the tutorial's default targetDir.",
+        },
+      },
+      required: ["slug"],
+      additionalProperties: false,
+    },
+    handler: async (args) => {
+      const { slug, workspaceName } = args as { slug: string; workspaceName?: string };
+      const loaded = await load(slug);
+      if (!loaded) {
+        return {
+          content: [{ type: "text", text: `No tutorial with slug "${slug}".` }],
+          isError: true,
+        };
+      }
+      return text(JSON.stringify(buildStartTutorialPayload({ ...loaded, workspaceName }), null, 2));
+    },
+  };
+}

package/src/server/mcp/tools.ts

@@ -9,6 +9,7 @@ import {
 import { getDb } from "../db/client.ts";
 import { progressEntries } from "../db/schema.ts";
 import { type McpTool, text } from "./protocol.ts";
+import { createStartTutorialTool } from "./startTutorial.ts";
 import { progressWriteTools, verificationTools } from "./writeTools.ts";
 
 /**
@@ -72,6 +73,7 @@ export const catalogReadTools: McpTool[] = [
         difficulty: tutorial.data.difficulty,
         tags: tutorial.data.tags,
         gated: tutorial.data.gated,
+        starter: tutorial.data.starter ?? null,
         steps: steps.map((s) => {
           const { stepSlug, order } = parseStepId(s.id);
           return {
@@ -86,6 +88,32 @@ export const catalogReadTools: McpTool[] = [
       return text(JSON.stringify(payload, null, 2));
     },
   },
+  createStartTutorialTool(async (slug) => {
+    const tutorial = await getTutorialBySlug(slug);
+    if (!tutorial) return null;
+    const steps = await getStepsForTutorial(slug);
+    return {
+      tutorial: {
+        slug: tutorial.id,
+        title: tutorial.data.title,
+        description: tutorial.data.description,
+        difficulty: tutorial.data.difficulty,
+        tags: tutorial.data.tags,
+        starter: tutorial.data.starter,
+      },
+      steps: steps.map((s) => {
+        const { stepSlug, order } = parseStepId(s.id);
+        return {
+          slug: stepSlug,
+          order,
+          title: s.data.title,
+          summary: s.data.summary,
+          duration: s.data.duration,
+          verify: s.data.verify ?? null,
+        };
+      }),
+    };
+  }),
   {
     name: "get_step",
     description: "Return one step's full Markdown source + metadata.",

package/styles/components/diff.css

@@ -3,8 +3,10 @@
   margin: 1.25rem 0;
   background: var(--color-surface);
   font-family: var(--font-mono);
-  font-size: 0.85em;
-  border-radius: 0;
+  font-size: 0.875rem;
+  line-height: 1.55;
+  border: var(--border-default) solid var(--color-border);
+  border-radius: var(--radius-sm, 0);
   overflow: hidden;
 }
 .diff-bar {
@@ -23,8 +25,16 @@
   border-radius: 0;
 }
 .diff-bar button:hover { color: var(--color-fg); border-color: var(--color-border-strong); }
-.diff-grid { display: grid; grid-template-columns: 1fr 1fr; gap: 1px; background: var(--color-border); }
-.diff-col { background: var(--color-surface); }
+.diff-grid {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 1px;
+  background: var(--color-border);
+}
+.diff-col {
+  min-width: 0;
+  background: var(--color-surface);
+}
 .diff-label {
   padding: 0.4rem 0.6rem;
   background: var(--color-surface-2);
@@ -35,10 +45,36 @@
 }
 .diff pre {
   margin: 0;
-  padding: 0.6rem 0.8rem;
+  padding: 0.65rem 0;
   white-space: pre;
   overflow-x: auto;
+  tab-size: 2;
+}
+.diff-add,
+.diff-del,
+.diff-ctx {
+  display: block;
+  min-width: max-content;
+  padding: 0.08rem 0.85rem;
+}
+.diff-add {
+  background: color-mix(in oklab, var(--color-success) 16%, transparent);
+  color: var(--color-success);
+}
+.diff-del {
+  background: color-mix(in oklab, var(--color-danger) 16%, transparent);
+  color: var(--color-danger);
+}
+.diff-ctx {
+  color: var(--color-muted);
+}
+
+@media (max-width: 1100px) {
+  .diff-grid {
+    grid-template-columns: 1fr;
+  }
+
+  .diff-col + .diff-col {
+    border-top: var(--border-default) solid var(--color-border);
+  }
 }
-.diff-add { background: color-mix(in oklab, var(--color-success) 14%, transparent); color: var(--color-success); display: block; }
-.diff-del { background: color-mix(in oklab, var(--color-danger) 14%, transparent); color: var(--color-danger); display: block; }
-.diff-ctx { color: var(--color-muted); display: block; }

package/styles/components/quiz.css

@@ -64,11 +64,31 @@
 .quiz-opt.is-correct {
   background: color-mix(in oklab, var(--color-success) 18%, var(--color-surface));
 }
-.quiz-opt.is-correct .quiz-opt-toggle { border-color: var(--color-success); background: var(--color-success); color: var(--color-bg); }
+.quiz-opt.is-correct .quiz-opt-toggle {
+  border-color: var(--color-success);
+  background: var(--color-success);
+  color: var(--color-bg);
+  display: inline-grid;
+  place-items: center;
+}
 .quiz-opt.is-wrong {
   background: color-mix(in oklab, var(--color-danger) 16%, var(--color-surface));
 }
-.quiz-opt.is-wrong .quiz-opt-toggle { border-color: var(--color-danger); background: var(--color-danger); color: var(--color-bg); }
+.quiz-opt.is-wrong .quiz-opt-toggle {
+  border-color: var(--color-danger);
+  background: var(--color-danger);
+  color: var(--color-bg);
+  display: inline-grid;
+  place-items: center;
+}
+/* Graded options swap the accent-filled `::after` for the Lucide
+   <Check>/<X> icon injected by Quiz.tsx — without this, the purple
+   accent rectangle covers the icon and you see a purple dot inside
+   the green/red box. */
+.quiz-opt.is-correct .quiz-opt-toggle::after,
+.quiz-opt.is-wrong .quiz-opt-toggle::after {
+  display: none;
+}
 .quiz-marker {
   display: inline-grid;
   place-items: center;