handzon-core 0.6.0

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "handzon-core",
+  "version": "0.6.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"
+  },
+  "license": "MIT",
+  "author": "r4ph_t",
+  "homepage": "https://github.com/R4ph-t/handzon#readme",
+  "bugs": {
+    "url": "https://github.com/R4ph-t/handzon/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/R4ph-t/handzon.git",
+    "directory": "packages/ui"
+  },
+  "type": "module",
+  "files": [
+    "src",
+    "styles",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts",
+    "./collections.ts": "./src/collections.ts",
+    "./components/*": "./src/components/*",
+    "./components/auth/*": "./src/components/auth/*",
+    "./layouts/*": "./src/layouts/*",
+    "./lib/*": "./src/lib/*",
+    "./pages/*": "./src/pages/*",
+    "./server/*": "./src/server/*",
+    "./server/auth/*": "./src/server/auth/*",
+    "./styles/*": "./styles/*"
+  },
+  "peerDependencies": {
+    "astro": "^6.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "dependencies": {
+    "@auth/core": "^0.37.3",
+    "@auth/drizzle-adapter": "^1.11.2",
+    "@codesandbox/sandpack-react": "^2.20.0",
+    "@fontsource-variable/geist": "^5.2.9",
+    "@fontsource-variable/geist-mono": "^5.2.8",
+    "@radix-ui/react-dialog": "^1.1.15",
+    "auth-astro": "^4.2.0",
+    "cookie": "^1.0.2",
+    "diff": "^9.0.0",
+    "drizzle-orm": "^0.45.2",
+    "lucide-react": "^1.16.0",
+    "mermaid": "^11.15.0",
+    "postgres": "^3.4.9",
+    "react-markdown": "^9.0.1",
+    "remark-gfm": "^4.0.0",
+    "unist-util-visit": "^5.0.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/hast": "^3.0.4",
+    "@types/react": "^19.2.15",
+    "@types/react-dom": "^19.2.3",
+    "astro": "^6.3.5",
+    "typescript": "^6.0.3"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "build": "echo 'handzon-core ships source — Astro type-checks at consume time'"
+  }
+}

package/src/collections.ts

@@ -0,0 +1,150 @@
+/**
+ * Content schemas + loaders for Handzon tutorials.
+ *
+ * Scaffolds wire these into their `src/content.config.ts`:
+ *
+ *   import { defineCollection } from "astro:content";
+ *   import { tutorialsLoader, tutorialsSchema, stepsLoader, stepsSchema } from "handzon-core/collections.ts";
+ *
+ *   export const collections = {
+ *     tutorials: defineCollection({ loader: tutorialsLoader(), schema: tutorialsSchema }),
+ *     steps: defineCollection({ loader: stepsLoader(), schema: stepsSchema }),
+ *   };
+ *
+ * The loader path is resolved against cwd, which is the scaffold root at
+ * Astro build/dev time — no need to thread the path through.
+ */
+import { z } from "astro:content";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import type { Loader } from "astro/loaders";
+import { glob } from "astro/loaders";
+
+const TUTORIALS_REL = "src/content/tutorials";
+const INDEX_FILE = "_index.json";
+
+async function readIndexOrder(dir: string): Promise<string[]> {
+  try {
+    const raw = await readFile(join(dir, INDEX_FILE), "utf8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.order)
+      ? parsed.order.filter((s: unknown) => typeof s === "string")
+      : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Custom loader that scans tutorials/<slug>/_meta.json for each tutorial.
+ * Tutorial order is driven by `_index.json` at the tutorials root; folder
+ * names are used verbatim as slugs (no numeric prefix expected).
+ */
+export function tutorialsLoader(): Loader {
+  return {
+    name: "tutorials-meta",
+    load: async ({ store, parseData, watcher }) => {
+      const dir = resolve(TUTORIALS_REL);
+      store.clear();
+      let folders: string[] = [];
+      try {
+        const dirents = await readdir(dir, { withFileTypes: true });
+        folders = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
+      } catch {
+        return;
+      }
+      const indexOrder = await readIndexOrder(dir);
+      const listed = new Set(indexOrder);
+      const unlisted = folders.filter((f) => !listed.has(f)).sort();
+      const orderOf = (slug: string): number => {
+        const i = indexOrder.indexOf(slug);
+        if (i >= 0) return i;
+        const u = unlisted.indexOf(slug);
+        return u >= 0 ? indexOrder.length + u : indexOrder.length + unlisted.length;
+      };
+      for (const folder of folders) {
+        const metaPath = join(dir, folder, "_meta.json");
+        let raw: string;
+        try {
+          raw = await readFile(metaPath, "utf8");
+        } catch {
+          continue;
+        }
+        const parsed = JSON.parse(raw);
+        const validated = await parseData({ id: folder, data: parsed });
+        store.set({
+          id: folder,
+          data: { ...validated, order: orderOf(folder) },
+          filePath: relative(process.cwd(), metaPath),
+        });
+      }
+      if (watcher) {
+        watcher.add(`${dir}/**/_meta.json`);
+        watcher.add(join(dir, INDEX_FILE));
+      }
+    },
+  };
+}
+
+/** Glob loader for tutorial step `.mdx`/`.md` files. */
+export function stepsLoader() {
+  return glob({
+    pattern: "**/[0-9]*-*.{mdx,md}",
+    base: `./${TUTORIALS_REL}`,
+  });
+}
+
+/** Schema for tutorial step entries. */
+export const stepsSchema = z.object({
+  title: z.string(),
+  duration: z.string().optional(),
+  summary: z.string().optional(),
+  ai: z.boolean().optional(),
+});
+
+/** Schema for tutorial entries. Pass through Astro's image() helper. */
+export function tutorialsSchema({ image }: { image: () => import("astro/zod").ZodType }) {
+  return z.object({
+    title: z.string(),
+    description: z.string(),
+    author: z
+      .object({
+        name: z.string(),
+        url: z.string().url().optional(),
+        avatar: image().optional(),
+      })
+      .optional(),
+    publishedAt: z.coerce.date().optional(),
+    updatedAt: z.coerce.date().optional(),
+    tags: z.array(z.string()).default([]),
+    difficulty: z.enum(["beginner", "intermediate", "advanced"]).default("beginner"),
+    estimatedDuration: z.string().optional(),
+    prerequisites: z.array(z.string()).default([]),
+    nextTutorial: z.string().optional(),
+    cover: image().optional(),
+    icon: z.union([z.string(), image()]).optional(),
+    steps: z.array(z.string()).optional(),
+    gated: z.boolean().default(false),
+    showProgress: z.boolean().default(true),
+    feedbackUrl: z.string().url().optional(),
+    ai: z
+      .object({
+        enabled: z.boolean().optional(),
+        name: z.string().optional(),
+        tagline: z.string().optional(),
+        greeting: z.string().optional(),
+        avatar: image().optional(),
+        persona: z.string().optional(),
+        tone: z.enum(["socratic", "direct", "encouraging"]).optional(),
+        provider: z.string().optional(),
+        model: z.string().optional(),
+        byok: z.enum(["required", "optional", "disabled"]).optional(),
+        references: z.array(z.string()).default([]),
+        allowedDomains: z.array(z.string()).default([]),
+        disabledSkills: z.array(z.string()).default([]),
+        enableSuggestPlaygroundEdit: z.boolean().default(false),
+        includeFutureSteps: z.boolean().optional(),
+      })
+      .optional(),
+  });
+}

package/src/components/Footer.astro

@@ -0,0 +1,85 @@
+---
+/**
+ * Site footer. A single quiet line at the bottom of every page,
+ * crediting the framework + linking to the Handzon repo. Sized to
+ * match the rest of the brutalist surface treatment.
+ */
+interface Props {
+  /** Public URL to the framework repo. Override to point elsewhere. */
+  repoUrl?: string;
+  /** Year displayed in the credit line; defaults to the current year. */
+  year?: number;
+}
+
+const {
+  repoUrl = "https://github.com/R4ph-t/handzon",
+  year = new Date().getFullYear(),
+} = Astro.props;
+---
+<footer class="hz-footer">
+  <div class="hz-footer-inner">
+    <span class="hz-footer-credit">
+      © {year} · Built with
+      <a class="hz-footer-link" href={repoUrl} target="_blank" rel="noopener">
+        Handzon
+        <svg
+          viewBox="0 0 24 24"
+          width="11"
+          height="11"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M7 17 17 7" />
+          <path d="M7 7h10v10" />
+        </svg>
+      </a>
+    </span>
+  </div>
+</footer>
+
+<style is:global>
+  /* No margin-top here: the footer's border sits flush against the
+   * preceding block. Pages that need breathing room above the footer
+   * (home grid, tutorial landing) carry their own padding-bottom on
+   * their content column; the tutorial step page wants the sidebar's
+   * right border to meet the footer's top border without a gap, which
+   * only works when this margin is zero. */
+  .hz-footer {
+    border-top: 1px solid var(--color-border);
+  }
+  .hz-footer-inner {
+    /* Same alignment trick as the navbar — match the active page's
+     * content column so the footer sits flush with what's above. */
+    max-width: var(--hz-page-max-width, 80rem);
+    margin: 0 auto;
+    padding: 1.25rem var(--hz-page-padding-x, clamp(1rem, 4vw, 2rem));
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    color: var(--color-muted);
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+  }
+  .hz-footer-credit {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+  }
+  .hz-footer-link {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.25rem;
+    color: var(--color-fg);
+    text-decoration: none;
+    border-bottom: 1px solid transparent;
+    transition: color 0.12s ease, border-color 0.12s ease;
+  }
+  .hz-footer-link:hover {
+    color: var(--color-accent);
+    border-bottom-color: var(--color-accent);
+  }
+</style>

package/src/components/Navbar.astro

@@ -0,0 +1,74 @@
+---
+/**
+ * Site-wide top bar. Rendered by BaseLayout on every page except the
+ * homepage (the homepage's Hero contains the brand mark inline).
+ *
+ * Layout: logo left, UserMenu right. The logo links back to the
+ * homepage. Sticky so it stays available as users scroll long
+ * tutorial steps.
+ */
+import UserMenu from "./auth/UserMenu.astro";
+
+interface Props {
+  logoUrl?: string;
+  siteName?: string;
+}
+
+const { logoUrl = "/logo.svg", siteName = "Handzon" } = 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" />
+      </a>
+    )}
+    <div class="hz-nav-actions">
+      <UserMenu />
+    </div>
+  </div>
+</header>
+
+<style is:global>
+  .hz-nav {
+    position: sticky;
+    top: 0;
+    z-index: 40;
+    background: color-mix(in oklab, var(--color-bg) 92%, transparent);
+    backdrop-filter: blur(8px);
+    -webkit-backdrop-filter: blur(8px);
+    border-bottom: 1px solid var(--color-border);
+  }
+  .hz-nav-inner {
+    /* Align with the current page's content column. Each page sets
+     * --hz-page-max-width + --hz-page-padding-x via BaseLayout so the
+     * logo lines up with whatever's directly below it: home grid
+     * (80rem, 2rem), tutorial landing (56rem, 3rem), tutorial step
+     * (full width, 1rem to match the sidebar). */
+    max-width: var(--hz-page-max-width, 80rem);
+    margin: 0 auto;
+    padding: 0.75rem var(--hz-page-padding-x, clamp(1rem, 4vw, 2rem));
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1rem;
+  }
+  .hz-nav-brand {
+    display: inline-flex;
+    align-items: center;
+    line-height: 0;
+    opacity: 0.92;
+    transition: opacity 0.12s ease;
+  }
+  .hz-nav-brand:hover { opacity: 1; }
+  .hz-nav-logo {
+    display: block;
+    height: 1.4rem;
+    width: auto;
+  }
+  .hz-nav-actions {
+    display: flex;
+    align-items: center;
+    margin-left: auto;
+  }
+</style>

package/src/components/Progress.tsx

@@ -0,0 +1,36 @@
+import { useMemo } from "react";
+import { useProgress } from "../lib/progress/useProgress";
+
+interface Props {
+  tutorialSlug: string;
+  totalSteps: number;
+}
+
+export default function Progress({ tutorialSlug, totalSteps }: Props) {
+  const { state } = useProgress();
+  const completed = useMemo(() => {
+    return Object.entries(state.steps).filter(
+      ([k, v]) => k.startsWith(`${tutorialSlug}/`) && v === "complete",
+    ).length;
+  }, [state.steps, tutorialSlug]);
+
+  const pct = totalSteps > 0 ? Math.round((completed / totalSteps) * 100) : 0;
+
+  return (
+    <div
+      className="progress"
+      role="progressbar"
+      aria-label={`${completed} of ${totalSteps} steps complete`}
+      aria-valuenow={completed}
+      aria-valuemin={0}
+      aria-valuemax={totalSteps}
+    >
+      <div className="progress-bar">
+        <div className="progress-fill" style={{ width: `${pct}%` }} />
+      </div>
+      <div className="progress-label">
+        {completed} / {totalSteps} steps
+      </div>
+    </div>
+  );
+}

package/src/components/Sidebar.astro

@@ -0,0 +1,162 @@
+---
+import type { TutorialEntry, StepEntry } from "../lib/content";
+import { parseStepId } from "../lib/content";
+import Progress from "./Progress.tsx";
+
+interface Props {
+  tutorial: TutorialEntry;
+  steps: StepEntry[];
+  currentStepSlug: string;
+}
+
+const { tutorial, steps, currentStepSlug } = Astro.props;
+const slug = tutorial.id;
+---
+<aside class="sidebar" aria-label="Tutorial steps">
+  {/* Top block: back link, title, progress. Stays fixed while the
+   * step list below scrolls when there are many steps. */}
+  <div class="sb-top">
+    <header class="sb-header">
+      <a class="sb-back" href="/">← All tutorials</a>
+      <h2 class="sb-title">
+        <a href={`/${slug}`}>{tutorial.data.title}</a>
+      </h2>
+      {tutorial.data.estimatedDuration && (
+        <div class="sb-meta">{tutorial.data.estimatedDuration}</div>
+      )}
+    </header>
+
+    {tutorial.data.showProgress && (
+      <Progress tutorialSlug={slug} totalSteps={steps.length} client:load />
+    )}
+  </div>
+
+  <ol class="sb-steps">
+    {steps.map((step) => {
+      const { stepSlug } = parseStepId(step.id);
+      const isCurrent = stepSlug === currentStepSlug;
+      return (
+        <li class={isCurrent ? "is-current" : ""} data-step-slug={stepSlug}>
+          <a href={`/${slug}/${stepSlug}`}>
+            <span class="sb-check" data-step-key={`${slug}/${stepSlug}`}></span>
+            <span class="sb-name">{step.data.title}</span>
+            {step.data.duration && <span class="sb-dur">{step.data.duration}</span>}
+          </a>
+        </li>
+      );
+    })}
+  </ol>
+</aside>
+
+<script>
+  // Hydrate per-step check marks from localStorage without an island.
+  import { getStore } from "../lib/progress/local";
+  function refresh() {
+    const store = getStore();
+    const state = store.get();
+    document.querySelectorAll<HTMLElement>("[data-step-key]").forEach((el) => {
+      const key = el.dataset.stepKey as `${string}/${string}`;
+      const done = state.steps[key] === "complete";
+      el.dataset.done = done ? "true" : "false";
+    });
+  }
+  refresh();
+  getStore().subscribe(refresh);
+</script>
+
+<style>
+  /* Two-zone layout: `.sb-top` (back link + title + progress) stays
+   * at the top; `.sb-steps` scrolls underneath when the list
+   * overflows. The wrapping `.sidebar-wrap` handles sticky
+   * positioning below the navbar; the sidebar fills it 100%. The
+   * column divider against `.main` is drawn by `.layout`'s
+   * background gradient, not a border here. */
+  .sidebar {
+    height: 100%;
+    background: var(--color-bg);
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+  }
+  .sb-top {
+    padding: 1rem 1rem 0.75rem;
+    flex-shrink: 0;
+  }
+  .sb-header { margin-bottom: 1rem; }
+  .sb-back {
+    font-family: var(--font-mono);
+    font-size: 0.75em;
+    color: var(--color-muted);
+    text-decoration: none;
+    text-transform: uppercase;
+    letter-spacing: 0.06em;
+  }
+  .sb-back:hover { color: var(--color-accent); }
+  .sb-title {
+    font-size: 1.15rem;
+    font-weight: 700;
+    letter-spacing: -0.015em;
+    margin: 0.5rem 0 0.25rem;
+    line-height: 1.2;
+  }
+  .sb-title a { color: var(--color-fg); text-decoration: none; }
+  .sb-meta {
+    color: var(--color-muted);
+    font-size: 0.72em;
+    font-family: var(--font-mono);
+    letter-spacing: 0.04em;
+  }
+  .sb-steps {
+    list-style: none;
+    padding: 0 1rem 2rem;
+    margin: 0.75rem 0 0;
+    flex: 1;
+    overflow-y: auto;
+    border-top: var(--border-default) solid var(--color-border);
+  }
+  .sb-steps li + li {
+    border-top: var(--border-default) solid var(--color-border);
+  }
+  .sb-steps a {
+    display: grid;
+    grid-template-columns: 18px 1fr auto;
+    align-items: center;
+    gap: 0.6rem;
+    padding: 0.6rem 0.7rem;
+    color: var(--color-fg);
+    text-decoration: none;
+    font-size: 0.92em;
+    font-weight: 500;
+    letter-spacing: -0.005em;
+  }
+  .sb-steps a:hover {
+    background: var(--color-surface);
+    color: var(--color-fg);
+  }
+  .sb-steps li.is-current a {
+    background: color-mix(in oklab, var(--color-accent) 40%, var(--color-bg));
+    color: var(--color-fg);
+    font-weight: 500;
+  }
+  .sb-steps li.is-current a:hover {
+    background: color-mix(in oklab, var(--color-accent) 48%, var(--color-bg));
+  }
+  .sb-check {
+    width: 14px;
+    height: 14px;
+    border: var(--border-default) solid var(--color-border-strong);
+    display: inline-block;
+  }
+  .sb-check[data-done="true"],
+  .sb-steps [data-step-key][data-done="true"] {
+    background: var(--color-accent);
+    border-color: var(--color-accent);
+  }
+  .sb-dur {
+    color: var(--color-muted);
+    font-family: var(--font-mono);
+    font-size: 0.72em;
+    font-weight: 400;
+    letter-spacing: 0.02em;
+  }
+</style>

package/src/components/StepNav.astro

@@ -0,0 +1,107 @@
+---
+import type { StepEntry } from "../lib/content";
+import { parseStepId } from "../lib/content";
+
+interface Props {
+  tutorialSlug: string;
+  steps: StepEntry[];
+  currentStepSlug: string;
+  gated: boolean;
+  hasCheckpoint: boolean;
+}
+
+const { tutorialSlug, steps, currentStepSlug, gated, hasCheckpoint } = 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}`}>
+  <div>
+    {prev && (
+      <a class="sn-prev" href={`/${tutorialSlug}/${prevSlug}`}>
+        ← {prev.data.title}
+      </a>
+    )}
+  </div>
+  <div>
+    {next ? (
+      <a class="sn-next" href={`/${tutorialSlug}/${nextSlug}`} data-next-link="true">
+        {hasCheckpoint ? "Continue" : "Next"}: {next.data.title} →
+      </a>
+    ) : (
+      <a class="sn-next sn-done" href={`/${tutorialSlug}`}>
+        Finish tutorial →
+      </a>
+    )}
+  </div>
+</nav>
+
+<script>
+  // Gating: if the host step contains a Checkpoint AND tutorial is gated,
+  // disable Next until the step is marked complete.
+  import { getStore } from "../lib/progress/local";
+  const nav = document.querySelector<HTMLElement>(".step-nav");
+  if (nav && nav.dataset.gated === "true") {
+    const next = nav.querySelector<HTMLAnchorElement>("[data-next-link]");
+    if (next) {
+      const key = nav.dataset.stepKey as `${string}/${string}`;
+      const refresh = () => {
+        const done = getStore().get().steps[key] === "complete";
+        if (!done) {
+          next.classList.add("is-disabled");
+          next.setAttribute("aria-disabled", "true");
+          next.addEventListener("click", blockClick);
+        } else {
+          next.classList.remove("is-disabled");
+          next.removeAttribute("aria-disabled");
+          next.removeEventListener("click", blockClick);
+        }
+      };
+      function blockClick(e: Event) { e.preventDefault(); }
+      refresh();
+      getStore().subscribe(refresh);
+    }
+  }
+
+  // Keyboard nav: ← prev, → next.
+  document.addEventListener("keydown", (e) => {
+    if (e.target instanceof HTMLElement && /^(INPUT|TEXTAREA|SELECT)$/.test(e.target.tagName)) return;
+    if (e.key === "ArrowLeft") {
+      const prev = document.querySelector<HTMLAnchorElement>(".sn-prev");
+      if (prev) window.location.href = prev.href;
+    } else if (e.key === "ArrowRight") {
+      const next = document.querySelector<HTMLAnchorElement>(".sn-next:not(.is-disabled)");
+      if (next) window.location.href = next.href;
+    }
+  });
+</script>
+
+<style>
+  .step-nav {
+    display: flex;
+    justify-content: space-between;
+    gap: 1rem;
+    margin-top: 3rem;
+    padding-top: 1.5rem;
+    border-top: var(--border-default, 2px) solid var(--color-border);
+  }
+  .sn-prev, .sn-next {
+    display: inline-block;
+    padding: 0.7rem 1rem;
+    border: var(--border-default, 2px) solid var(--color-fg);
+    text-decoration: none;
+    color: var(--color-fg);
+    font-weight: 700;
+    transition: transform 0.08s ease, box-shadow 0.08s ease;
+  }
+  .sn-prev:hover, .sn-next:hover:not(.is-disabled) {
+    transform: translate(-2px, -2px);
+    box-shadow: var(--shadow-raised);
+    color: var(--color-fg);
+  }
+  .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; }
+</style>