handzon-core 0.13.4 → 0.14.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "handzon-core",
-  "version": "0.13.4",
+  "version": "0.14.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/collections.ts

@@ -480,6 +480,8 @@ export function tutorialsSchema({ image }: { image: () => import("astro/zod").Zo
       publishedAt: z.coerce.date().optional(),
       updatedAt: z.coerce.date().optional(),
       tags: z.array(z.string()).default([]),
+      published: z.boolean().default(true),
+      hidden: z.boolean().default(false),
       tracks: z.array(trackSchema).default([]),
       defaultTrack: z.string().min(1).optional(),
       difficulty: z.enum(["beginner", "intermediate", "advanced"]).default("beginner"),

package/src/components/auth/UserMenu.astro

@@ -99,6 +99,12 @@ const GITHUB_ICON_PATH =
   .um-btn-icon {
     padding: 0.3rem 0.45rem;
   }
+  .um-mcp-btn {
+    border-color: color-mix(in oklab, var(--color-accent) 45%, var(--color-border));
+    background: color-mix(in oklab, var(--color-accent) 8%, transparent);
+    color: var(--color-accent);
+    font-weight: 700;
+  }
   .um-gh {
     flex-shrink: 0;
   }

package/src/components/auth/UserMenu.tsx

@@ -107,9 +107,9 @@ export default function UserMenu() {
             {displayName}
           </span>
           <a
-            className="um-btn um-btn-icon"
+            className="um-btn um-mcp-btn"
             href={withBase("/settings/tokens")}
-            title="Access tokens for editor MCP"
+            title="Create an access token to connect your editor over MCP"
           >
             <svg
               viewBox="0 0 24 24"
@@ -125,7 +125,7 @@ export default function UserMenu() {
               <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 className="sr-only">Access tokens</span>
+            <span>MCP setup</span>
           </a>
           <form method="post" action={withBase("/api/auth/signout")}>
             <input type="hidden" name="csrfToken" value={csrfToken} />

package/src/components/home/TutorialCard.astro

@@ -2,6 +2,7 @@
 import { Image } from "astro:assets";
 import { withBase } from "../../lib/base";
 import type { TutorialEntry } from "../../lib/content";
+import { getDefaultCoverMeta } from "../../lib/defaultCover";
 
 interface Props {
   tutorial: TutorialEntry;
@@ -17,8 +18,17 @@ const { tutorial, duration, stepCount } = Astro.props;
 const data = tutorial.data;
 const slug = tutorial.id;
 const iconText = typeof data.icon === "string" ? data.icon : undefined;
-const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undefined;
+const iconImage =
+  data.icon && typeof data.icon !== "string" ? data.icon : undefined;
+const defaultCover = getDefaultCoverMeta({
+  slug,
+  title: data.title,
+  difficulty: data.difficulty,
+  tags: data.tags,
+  icon: data.icon,
+});
 ---
+
 <article
   class="card"
   data-difficulty={data.difficulty}
@@ -28,71 +38,110 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
   data-popularity="0"
 >
   <a href={withBase(`/${slug}`)} class="card-link">
-    {data.cover && (
-      <div class="card-media">
-        <Image
-          src={data.cover}
-          alt=""
-          class="card-cover"
-          loading="lazy"
-          widths={[360, 540, 720]}
-          sizes="(min-width: 960px) 33vw, (min-width: 640px) 50vw, 100vw"
-        />
-      </div>
-    )}
-    <div class="card-body">
-      <div class="card-title-row">
-        {iconImage && (
+    <div class="card-media">
+      {
+        data.cover ? (
           <Image
-            src={iconImage}
+            src={data.cover}
             alt=""
-            class="card-icon card-icon-image"
+            class="card-cover"
             loading="lazy"
-            width={32}
-            height={32}
+            widths={[360, 540, 720]}
+            sizes="(min-width: 960px) 33vw, (min-width: 640px) 50vw, 100vw"
           />
-        )}
-        {iconText && <span class="card-icon card-icon-text" aria-hidden="true">{iconText}</span>}
+        ) : (
+          <div
+            class={`card-cover-fallback pattern-${defaultCover.pattern} scale-${defaultCover.scale} glow-${defaultCover.glow} variant-${defaultCover.variant} difficulty-${defaultCover.difficulty}`}
+            aria-hidden="true"
+          >
+            <span class="fallback-keywords">
+              {defaultCover.keywords.map((keyword) => (
+                <span>{keyword}</span>
+              ))}
+            </span>
+            {defaultCover.icon ? (
+              <span class="fallback-watermark">
+                <svg
+                  viewBox="0 0 24 24"
+                  width="120"
+                  height="120"
+                  aria-hidden="true"
+                >
+                  <path d={defaultCover.icon.path} />
+                </svg>
+              </span>
+            ) : null}
+          </div>
+        )
+      }
+    </div>
+    <div class="card-body">
+      <div class="card-title-row">
+        {
+          iconImage && (
+            <Image
+              src={iconImage}
+              alt=""
+              class="card-icon card-icon-image"
+              loading="lazy"
+              width={32}
+              height={32}
+            />
+          )
+        }
+        {
+          iconText && (
+            <span class="card-icon card-icon-text" aria-hidden="true">
+              {iconText}
+            </span>
+          )
+        }
         <h3>{data.title}</h3>
       </div>
       <p>{data.description}</p>
       <div class="badges">
         <span class={`badge badge-${data.difficulty}`}>{data.difficulty}</span>
-        {duration && (
-          <span class="badge badge-neutral">
-            <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"
-            >
-              <circle cx="12" cy="12" r="10" />
-              <polyline points="12 7 12 12 15 14" />
-            </svg>
-            {duration}
-          </span>
-        )}
+        {
+          duration && (
+            <span class="badge badge-neutral">
+              <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"
+              >
+                <circle cx="12" cy="12" r="10" />
+                <polyline points="12 7 12 12 15 14" />
+              </svg>
+              {duration}
+            </span>
+          )
+        }
         <span
           class="card-progress"
           data-tutorial-slug={slug}
-          data-step-count={stepCount}
-        ></span>
+          data-step-count={stepCount}></span>
       </div>
-      {data.tags.length > 0 && (
-        <div class="tags">
-          {data.tags.map((tag: string) => <span class="tag">#{tag}</span>)}
-        </div>
-      )}
+      {
+        data.tags.length > 0 && (
+          <div class="tags">
+            {data.tags.map((tag: string) => (
+              <span class="tag">#{tag}</span>
+            ))}
+          </div>
+        )
+      }
       <div
         class="card-stats"
         data-tutorial-stats-slug={slug}
         aria-hidden="true"
-      ></div>
+      >
+      </div>
     </div>
   </a>
 </article>
@@ -102,7 +151,9 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
     border: 1px solid var(--color-border);
     background: var(--color-bg);
     display: flex;
-    transition: border-color 0.12s ease, transform 0.12s ease;
+    transition:
+      border-color 0.12s ease,
+      transform 0.12s ease;
   }
   .card:hover {
     border-color: var(--color-accent);
@@ -118,12 +169,11 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
   .card-media {
     aspect-ratio: 16 / 9;
     border-bottom: 1px solid var(--color-border);
-    background:
-      linear-gradient(
-        135deg,
-        color-mix(in oklab, var(--color-accent) 10%, transparent),
-        var(--color-surface)
-      );
+    background: linear-gradient(
+      135deg,
+      color-mix(in oklab, var(--color-accent) 10%, transparent),
+      var(--color-surface)
+    );
     overflow: hidden;
   }
   .card-cover {
@@ -132,9 +182,187 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
     object-fit: cover;
     display: block;
     filter: saturate(0.92) contrast(1.05);
-    transition: transform 0.18s ease, filter 0.18s ease;
+    transition:
+      transform 0.18s ease,
+      filter 0.18s ease;
+  }
+  .card-cover-fallback {
+    --cover-accent: var(--color-accent);
+    --cover-glow-x: 28%;
+    --cover-glow-y: 76%;
+    --cover-grid-size: 1rem;
+    --cover-dot-size: 0.9rem;
+    position: relative;
+    width: 100%;
+    height: 100%;
+    display: grid;
+    padding: 1rem;
+    overflow: hidden;
+    background:
+      radial-gradient(
+        circle at var(--cover-glow-x) var(--cover-glow-y),
+        color-mix(in oklab, var(--cover-accent) 22%, transparent),
+        transparent 34%
+      ),
+      linear-gradient(
+        135deg,
+        color-mix(in oklab, var(--cover-accent) 10%, var(--color-bg)),
+        var(--color-surface)
+      );
+    transition:
+      transform 0.18s ease,
+      filter 0.18s ease;
+  }
+  .card-cover-fallback::before {
+    content: "";
+    position: absolute;
+    inset: 0;
+    pointer-events: none;
+  }
+  .card-cover-fallback::before {
+    opacity: 0.24;
+  }
+  .difficulty-beginner {
+    --cover-accent: var(--color-success);
+  }
+  .difficulty-intermediate {
+    --cover-accent: var(--color-warn);
+  }
+  .difficulty-advanced {
+    --cover-accent: var(--color-danger);
+  }
+  .glow-1 {
+    --cover-glow-x: 28%;
+    --cover-glow-y: 76%;
+  }
+  .glow-2 {
+    --cover-glow-x: 28%;
+    --cover-glow-y: 76%;
+  }
+  .glow-3 {
+    --cover-glow-x: 28%;
+    --cover-glow-y: 76%;
+  }
+  .card-cover-fallback.variant-1 {
+    --cover-glow-x: 74%;
+    --cover-glow-y: 28%;
+  }
+  .card-cover-fallback.variant-2 {
+    --cover-glow-x: 74%;
+    --cover-glow-y: 76%;
   }
-  .card:hover .card-cover {
+  .card-cover-fallback.variant-3 {
+    --cover-glow-x: 28%;
+    --cover-glow-y: 28%;
+  }
+  .scale-1 {
+    --cover-grid-size: 1.45rem;
+    --cover-dot-size: 1.15rem;
+  }
+  .scale-2 {
+    --cover-grid-size: 0.72rem;
+    --cover-dot-size: 0.62rem;
+  }
+  .pattern-grid::before {
+    background-image:
+      linear-gradient(
+        color-mix(in oklab, var(--cover-accent) 16%, transparent) 1px,
+        transparent 1px
+      ),
+      linear-gradient(
+        90deg,
+        color-mix(in oklab, var(--cover-accent) 16%, transparent) 1px,
+        transparent 1px
+      );
+    background-size: var(--cover-grid-size) var(--cover-grid-size);
+  }
+  .pattern-dots::before {
+    background-image: radial-gradient(
+      circle,
+      color-mix(in oklab, var(--cover-accent) 18%, transparent) 1px,
+      transparent 1.5px
+    );
+    background-size: var(--cover-dot-size) var(--cover-dot-size);
+  }
+  .fallback-keywords,
+  .fallback-motif {
+    position: relative;
+    z-index: 3;
+  }
+  .fallback-keywords {
+    position: absolute;
+    inset: auto auto 1.05rem 1rem;
+    max-width: 58%;
+    display: grid;
+    gap: 0.15rem;
+    justify-items: start;
+    color: color-mix(in oklab, var(--cover-accent) 58%, transparent);
+    font-family: var(--font-mono);
+    font-size: clamp(1.05rem, 4.6vw, 2.1rem);
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    line-height: 0.9;
+    opacity: 0.42;
+    text-transform: uppercase;
+  }
+  .fallback-watermark {
+    position: absolute;
+    right: -1.35rem;
+    bottom: -2.15rem;
+    z-index: 1;
+    color: var(--cover-accent);
+    opacity: 0.16;
+    transform: rotate(-8deg);
+  }
+  .fallback-watermark svg {
+    display: block;
+    width: clamp(10.5rem, 58%, 14rem);
+    height: auto;
+    fill: currentColor;
+  }
+  .variant-1 .fallback-watermark {
+    left: -1.45rem;
+    right: auto;
+    bottom: -2.15rem;
+    transform: rotate(7deg);
+  }
+  .variant-2 .fallback-watermark {
+    left: -1.4rem;
+    right: auto;
+    top: -2.2rem;
+    bottom: auto;
+    transform: rotate(-10deg);
+  }
+  .variant-3 .fallback-watermark {
+    right: -1.45rem;
+    bottom: -2.2rem;
+    transform: rotate(9deg);
+  }
+  .fallback-keywords span:nth-child(2) {
+    margin-left: 1.4rem;
+  }
+  .fallback-keywords span:nth-child(3) {
+    margin-left: 0.55rem;
+  }
+  .fallback-keywords span {
+    max-width: 100%;
+    overflow: hidden;
+    text-overflow: clip;
+    white-space: nowrap;
+  }
+  .variant-1 .fallback-keywords {
+    inset: 2.9rem 1rem auto auto;
+    justify-items: end;
+  }
+  .variant-2 .fallback-keywords {
+    inset: auto 1rem 1rem auto;
+    justify-items: end;
+  }
+  .variant-3 .fallback-keywords {
+    inset: 3rem auto auto 1rem;
+  }
+  .card:hover .card-cover,
+  .card:hover .card-cover-fallback {
     transform: scale(1.025);
     filter: saturate(1) contrast(1.08);
   }
@@ -207,9 +435,15 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
     background: currentColor;
     flex-shrink: 0;
   }
-  .badge-beginner { color: var(--color-success); }
-  .badge-intermediate { color: var(--color-warn); }
-  .badge-advanced { color: var(--color-danger); }
+  .badge-beginner {
+    color: var(--color-success);
+  }
+  .badge-intermediate {
+    color: var(--color-warn);
+  }
+  .badge-advanced {
+    color: var(--color-danger);
+  }
 
   h3 {
     font-size: 1.05rem;
@@ -260,7 +494,9 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
     text-transform: uppercase;
     letter-spacing: 0.08em;
   }
-  .card-progress:empty { display: none; }
+  .card-progress:empty {
+    display: none;
+  }
   /* The ring + label live inside `.card-progress` but are injected
    * via innerHTML at runtime, so Astro's scope hash doesn't apply to
    * them. Use :global() so the rules still match. */
@@ -289,7 +525,9 @@ const iconImage = data.icon && typeof data.icon !== "string" ? data.icon : undef
    * Hidden until the script populates content so the card height
    * stays stable on first paint and gracefully degrades on Tier 1
    * (no DB → no numbers → no row). */
-  .card-stats:empty { display: none; }
+  .card-stats:empty {
+    display: none;
+  }
   .card-stats {
     margin-top: 0.6rem;
     display: flex;

package/src/index.ts

@@ -24,6 +24,7 @@ export {
 } from "./lib/ai/prompts.ts";
 // Content collection helpers (built on top of astro:content).
 export {
+  getListedTutorials,
   getStep,
   getStepsForTutorial,
   getTutorialBySlug,

package/src/lib/content.ts

@@ -1,4 +1,5 @@
 import { type CollectionEntry, getCollection } from "astro:content";
+import { isTutorialListed, isTutorialPublished } from "./publication.ts";
 
 export type TutorialEntry = CollectionEntry<"tutorials">;
 export type StepEntry = CollectionEntry<"steps">;
@@ -30,7 +31,16 @@ export function parseStepId(id: string): { tutorialSlug: string; stepSlug: strin
 
 export async function getTutorials(): Promise<TutorialEntry[]> {
   const all = await getCollection("tutorials");
-  return all.sort((a, b) => {
+  return sortTutorials(all.filter((tutorial) => isTutorialPublished(tutorial.data)));
+}
+
+export async function getListedTutorials(): Promise<TutorialEntry[]> {
+  const all = await getCollection("tutorials");
+  return sortTutorials(all.filter((tutorial) => isTutorialListed(tutorial.data)));
+}
+
+function sortTutorials(tutorials: TutorialEntry[]): TutorialEntry[] {
+  return tutorials.sort((a, b) => {
     const ao = (a.data as { order?: number }).order ?? 0;
     const bo = (b.data as { order?: number }).order ?? 0;
     return ao - bo;
@@ -39,7 +49,7 @@ export async function getTutorials(): Promise<TutorialEntry[]> {
 
 export async function getTutorialBySlug(slug: string): Promise<TutorialEntry | undefined> {
   const all = await getCollection("tutorials");
-  return all.find((t) => t.id === slug);
+  return all.find((t) => t.id === slug && isTutorialPublished(t.data));
 }
 
 export async function getStepsForTutorial(slug: string): Promise<StepEntry[]> {

package/src/lib/defaultCover.ts

@@ -0,0 +1,121 @@
+import {
+  siAstro,
+  siDocker,
+  siJavascript,
+  siPostgresql,
+  siPython,
+  siReact,
+  siRedis,
+  siTypescript,
+  siVite,
+} from "simple-icons";
+
+type Difficulty = "beginner" | "intermediate" | "advanced";
+
+type DefaultCoverInput = {
+  slug: string;
+  title: string;
+  difficulty: Difficulty;
+  tags: string[];
+  icon?: unknown;
+};
+
+export type DefaultCoverMeta = {
+  difficulty: Difficulty;
+  glow: 0 | 1 | 2 | 3;
+  icon?: {
+    path: string;
+    title: string;
+  };
+  keywords: string[];
+  label: string;
+  pattern: "grid" | "dots";
+  scale: 0 | 1 | 2;
+  variant: 0 | 1 | 2 | 3;
+};
+
+const PATTERNS: DefaultCoverMeta["pattern"][] = ["grid", "dots"];
+
+const TAG_PATTERNS: Record<string, DefaultCoverMeta["pattern"]> = {
+  ai: "dots",
+  api: "grid",
+  auth: "grid",
+  authoring: "grid",
+  databases: "dots",
+  deploy: "grid",
+  devops: "grid",
+  docker: "grid",
+  frontend: "grid",
+  javascript: "grid",
+  meta: "grid",
+  postgres: "dots",
+  python: "grid",
+  queues: "grid",
+  react: "grid",
+  redis: "dots",
+  render: "grid",
+  sql: "dots",
+  tracks: "grid",
+  typescript: "grid",
+  vite: "grid",
+  web: "grid",
+};
+
+const TAG_ICONS: Record<string, DefaultCoverMeta["icon"]> = {
+  astro: siAstro,
+  docker: siDocker,
+  javascript: siJavascript,
+  postgres: siPostgresql,
+  python: siPython,
+  react: siReact,
+  redis: siRedis,
+  typescript: siTypescript,
+  vite: siVite,
+};
+
+const KEYWORD_STOPWORDS = new Set(["A", "AN", "AND", "APP", "BUILD", "THE", "TO", "WITH"]);
+
+function stableIndex(value: string, modulo: number): number {
+  let hash = 0;
+  for (let i = 0; i < value.length; i += 1) {
+    hash = (hash * 31 + value.charCodeAt(i)) >>> 0;
+  }
+  return hash % modulo;
+}
+
+function normalizeKeywords(value: string): string[] {
+  return value
+    .split(/[^a-z0-9]+/i)
+    .map((word) => word.toUpperCase())
+    .filter(Boolean);
+}
+
+function getKeywords(input: DefaultCoverInput): string[] {
+  const words = [...input.tags, ...input.title.split(/\s+/)]
+    .flatMap(normalizeKeywords)
+    .filter((word) => word.length >= 2 && !KEYWORD_STOPWORDS.has(word));
+
+  return Array.from(new Set(words)).slice(0, 3);
+}
+
+export function getDefaultCoverMeta(input: DefaultCoverInput): DefaultCoverMeta {
+  const label = input.tags[0] ?? input.difficulty;
+  const icon = input.tags.map((tag) => TAG_ICONS[tag.toLowerCase()]).find(Boolean);
+  const variant = stableIndex(input.slug, 4) as DefaultCoverMeta["variant"];
+  const scale = stableIndex(`${input.slug}:${label}:scale`, 3) as DefaultCoverMeta["scale"];
+  const glow = stableIndex(`${input.slug}:${input.title}:glow`, 4) as DefaultCoverMeta["glow"];
+  const pattern =
+    input.tags.map((tag) => TAG_PATTERNS[tag.toLowerCase()]).find(Boolean) ??
+    PATTERNS[stableIndex(`${input.title}:${input.tags.join(":")}`, PATTERNS.length)];
+
+  return {
+    difficulty: input.difficulty,
+    glow,
+    icon,
+    keywords: getKeywords(input),
+    label,
+    pattern,
+    scale,
+    variant,
+  };
+}

package/src/lib/publication.ts

@@ -0,0 +1,12 @@
+export interface TutorialPublication {
+  published?: boolean;
+  hidden?: boolean;
+}
+
+export function isTutorialPublished(tutorial: TutorialPublication): boolean {
+  return tutorial.published !== false;
+}
+
+export function isTutorialListed(tutorial: TutorialPublication): boolean {
+  return isTutorialPublished(tutorial) && tutorial.hidden !== true;
+}

package/src/pages/Home.astro

@@ -5,7 +5,7 @@ import TutorialCard from "../components/home/TutorialCard.astro";
 import FilterBar from "../components/home/FilterBar.tsx";
 import Pagination from "../components/home/Pagination.tsx";
 import ResumeRail from "../components/home/ResumeRail.tsx";
-import { getTutorials, getStepsForTutorial, sumDurations } from "../lib/content.ts";
+import { getListedTutorials, getStepsForTutorial, sumDurations } from "../lib/content.ts";
 
 interface Props {
   siteName?: string;
@@ -43,7 +43,7 @@ const {
   pageSize = 9,
 } = Astro.props;
 
-const tutorials = await getTutorials();
+const tutorials = await getListedTutorials();
 const stepsByTutorial = new Map(
   await Promise.all(
     tutorials.map(async (t) => [t.id, await getStepsForTutorial(t.id)] as const),

package/src/server/mcp/tools.ts

@@ -1,10 +1,10 @@
 import { eq } from "drizzle-orm";
 import type { VerifySpec } from "../../collections.ts";
 import {
+  getListedTutorials,
   getStep,
   getStepsForTutorial,
   getTutorialBySlug,
-  getTutorials,
   parseStepId,
 } from "../../lib/content.ts";
 import { isVerifySpec, resolveForTrack, type TrackScoped } from "../../lib/track-scoped.ts";
@@ -43,10 +43,10 @@ function resolveVerifyForTrack(
 export const catalogReadTools: McpTool[] = [
   {
     name: "list_tutorials",
-    description: "List every tutorial published on this Handzon site.",
+    description: "List every tutorial published in this Handzon site's public catalog.",
     inputSchema: { type: "object", properties: {}, additionalProperties: false },
     handler: async () => {
-      const tutorials = await getTutorials();
+      const tutorials = await getListedTutorials();
       const rows = tutorials.map((t) => ({
         slug: t.id,
         title: t.data.title,