stack-site-builder 1.10.0

package/src/components/Toc.astro

@@ -0,0 +1,39 @@
+---
+interface Item {
+  slug: string;
+  text: string;
+  depth: number;
+}
+
+interface Props {
+  items: Item[];
+  title: string;
+}
+
+const { items, title } = Astro.props;
+---
+
+{
+  items.length > 0 && (
+    <nav aria-label={title} class="text-sm">
+      <p class="mb-2 text-xs font-semibold tracking-wide text-[var(--aas-muted)] uppercase">
+        {title}
+      </p>
+      <ul class="space-y-0.5 rounded-xl border border-[var(--aas-border)] bg-[var(--aas-panel)] p-1.5">
+        {items.map((it) => (
+          <li>
+            <a
+              href={`#${it.slug}`}
+              class:list={[
+                'block rounded-lg py-1 pr-2 text-[var(--aas-muted)] no-underline hover:bg-[var(--aas-tint)] hover:text-[var(--aas-text)]',
+                it.depth >= 3 ? 'pl-5' : 'pl-2.5',
+              ]}
+            >
+              {it.text}
+            </a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}

package/src/components/TocRail.astro

@@ -0,0 +1,74 @@
+---
+// A self-contained fixed right-rail table of contents (with scroll-spy and a
+// back-to-top button) for single-column detail pages — concepts and articles.
+// (StackDetail has its own tab-aware rail.)
+import Toc from './Toc.astro';
+import ProjectRelatedTools, { type RelatedTool } from './ProjectRelatedTools.astro';
+import ProjectFileList from './ProjectFileList.astro';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Item {
+  slug: string;
+  text: string;
+  depth: number;
+}
+interface Props {
+  lang: Lang;
+  items: Item[];
+  // Optional: when an article embeds a runnable sample, surface its related
+  // tools + file list here, mirroring a stack's implementation rail. The file
+  // buttons wire to the body's <SampleProject/> viewer (matched by folder).
+  relatedTools?: RelatedTool[];
+  projectFiles?: { folder: string; files: { path: string }[] };
+}
+
+const { lang, items, relatedTools = [], projectFiles } = Astro.props;
+const t = useTranslations(lang);
+const hasContent = items.length > 0 || relatedTools.length > 0 || Boolean(projectFiles);
+---
+
+{
+  hasContent && (
+    <aside class="aas-toc-rail" data-toc-rail>
+      <div class="aas-toc-scroll">
+        {items.length > 0 && <Toc items={items} title={t('toc.onThisPage')} />}
+        {relatedTools.length > 0 && (
+          <div class="mt-5">
+            <ProjectRelatedTools lang={lang} tools={relatedTools} />
+          </div>
+        )}
+        {projectFiles && (
+          <div class="mt-5">
+            <ProjectFileList lang={lang} folder={projectFiles.folder} files={projectFiles.files} />
+          </div>
+        )}
+      </div>
+      <div class="aas-toc-foot">
+        <button type="button" class="aas-toc-top" data-back-to-top>
+          ↑ {t('top.label')}
+        </button>
+        <button
+          type="button"
+          class="aas-toc-allbtn"
+          data-toggle-all
+          data-collapse={t('toc.collapseAll')}
+          data-expand={t('toc.expandAll')}
+          hidden
+        >
+          {t('toc.collapseAll')}
+        </button>
+      </div>
+    </aside>
+  )
+}
+
+<script>
+  import { startScrollSpy, initBackToTop, initReveals } from '../lib/toc-rail-client';
+
+  const rail = document.querySelector<HTMLElement>('[data-toc-rail]');
+  if (rail) {
+    startScrollSpy(rail);
+    initBackToTop(rail);
+    initReveals(rail);
+  }
+</script>

package/src/components/ToolAvatar.astro

@@ -0,0 +1,133 @@
+---
+import { rootIdOf } from '@aas-data/categories';
+import { isImageRef, resolveImageUrl } from '../lib/assets';
+
+interface Props {
+  name: string;
+  /** Optional logo image (URL or /public path). Falls back to a category icon. */
+  logo?: string;
+  /** Optional dark-theme variant of `logo`; swapped in via CSS under data-theme. */
+  logoDark?: string;
+  category?: string;
+  /** Named fallback glyph when there's no logo (overrides the category icon).
+   *  Used for non-stack avatars, e.g. glossary concept/external terms. */
+  fallback?: string;
+  size?: number;
+  class?: string;
+}
+
+const { name, logo, logoDark, category, fallback, size = 44, class: className } = Astro.props;
+
+// Lucide-style line icons per category (inner SVG markup; 24×24 viewBox).
+const icons: Record<string, string> = {
+  frameworks:
+    '<circle cx="18" cy="5" r="3"/><circle cx="6" cy="12" r="3"/><circle cx="18" cy="19" r="3"/><line x1="8.59" x2="15.42" y1="13.51" y2="17.49"/><line x1="15.41" x2="8.59" y1="6.51" y2="10.49"/>',
+  'coding-agents':
+    '<polyline points="4 17 10 11 4 5"/><line x1="12" x2="20" y1="19" y2="19"/>',
+  'llm-providers':
+    '<path d="M9.937 15.5A2 2 0 0 0 8.5 14.063l-6.135-1.582a.5.5 0 0 1 0-.962L8.5 9.936A2 2 0 0 0 9.937 8.5l1.582-6.135a.5.5 0 0 1 .963 0L14.063 8.5A2 2 0 0 0 15.5 9.937l6.135 1.581a.5.5 0 0 1 0 .964L15.5 14.063a2 2 0 0 0-1.437 1.437l-1.582 6.135a.5.5 0 0 1-.963 0z"/><path d="M20 3v4"/><path d="M22 5h-4"/><path d="M4 17v2"/><path d="M5 18H3"/>',
+  'vector-stores':
+    '<ellipse cx="12" cy="5" rx="9" ry="3"/><path d="M3 5V19A9 3 0 0 0 21 19V5"/><path d="M3 12A9 3 0 0 0 21 12"/>',
+  observability: '<path d="M22 12h-4l-3 9L9 3l-3 9H2"/>',
+  // A concept/idea (lightbulb), an article (file-text, matching the Writing nav
+  // icon), an external link (globe), and a plain term (book) — glossary
+  // fallbacks for avatars without a logo.
+  concept:
+    '<path d="M15 14c.2-1 .7-1.7 1.5-2.5 1-.9 1.5-2.2 1.5-3.5A6 6 0 0 0 6 8c0 1 .2 2.2 1.5 3.5.7.7 1.3 1.5 1.5 2.5"/><path d="M9 18h6"/><path d="M10 22h4"/>',
+  article:
+    '<path d="M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7Z"/><path d="M14 2v4a2 2 0 0 0 2 2h4"/><path d="M16 13H8"/><path d="M16 17H8"/><path d="M10 9H8"/>',
+  external:
+    '<circle cx="12" cy="12" r="10"/><path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20"/><path d="M2 12h20"/>',
+  term: '<path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20"/>',
+  default:
+    '<path d="M21 8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 3 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16Z"/><path d="m3.3 7 8.7 5 8.7-5"/><path d="M12 22V12"/>',
+};
+// Priority: an explicit `fallback` glyph, else the top-level category's icon
+// (subcategory resolved to its root), else the generic default.
+const iconKey = category ? rootIdOf(category) : undefined;
+const icon = (fallback && icons[fallback]) || (iconKey && icons[iconKey]) || icons.default;
+
+// A `logo` is an image when it's a URL or a /public path; otherwise it's an
+// emoji/text glyph (e.g. "🚅"). Anything else falls back to the category icon.
+const isImage = isImageRef(logo);
+const logoSrc = isImage ? resolveImageUrl(logo) : undefined;
+// Dark-theme variant (only meaningful for a non-mono image logo).
+const logoDarkSrc = isImage && logoDark ? resolveImageUrl(logoDark) : undefined;
+const emoji = logo && !isImage ? logo : undefined;
+// A `-mono` suffix (e.g. `/logos/instructor-mono.svg`) marks a single-colour
+// logo: render it as a mask tinted with the theme text colour so it stays
+// visible in both light and dark — including the manual theme toggle.
+const isMono = isImage && /-mono\.[a-z0-9]+$/i.test(logo!);
+// A `-wbg` suffix (e.g. `/logos/lancedb-wbg.png`) sits the logo on a white,
+// padded tile so a dark or transparent logo stays visible on the dark theme.
+const isWbg = isImage && /-wbg\.[a-z0-9]+$/i.test(logo!);
+
+const boxStyle = `width:${size}px;height:${size}px`;
+const imgStyle = isWbg
+  ? `${boxStyle};background:#fff;padding:${Math.round(size * 0.12)}px`
+  : boxStyle;
+const iconSize = Math.round(size * 0.52);
+const tileClass =
+  'flex shrink-0 items-center justify-center rounded-lg border border-[var(--aas-border)] bg-[var(--aas-tint)] text-[var(--aas-muted)]';
+---
+
+{
+  isMono ? (
+    <span class:list={[tileClass, className]} style={boxStyle} aria-hidden="true">
+      <span
+        style={`display:block;width:${iconSize}px;height:${iconSize}px;background-color:var(--aas-text);-webkit-mask:url("${logoSrc}") center/contain no-repeat;mask:url("${logoSrc}") center/contain no-repeat`}
+      />
+    </span>
+  ) : isImage ? (
+    logoDarkSrc ? (
+      <Fragment>
+        <img
+          src={logoSrc}
+          alt={name}
+          width={size}
+          height={size}
+          loading="lazy"
+          class:list={['aas-logo-light shrink-0 rounded-lg object-contain', className]}
+          style={imgStyle}
+        />
+        <img
+          src={logoDarkSrc}
+          alt={name}
+          width={size}
+          height={size}
+          loading="lazy"
+          class:list={['aas-logo-dark shrink-0 rounded-lg object-contain', className]}
+          style={imgStyle}
+        />
+      </Fragment>
+    ) : (
+      <img
+        src={logoSrc}
+        alt={name}
+        width={size}
+        height={size}
+        loading="lazy"
+        class:list={['shrink-0 rounded-lg object-contain', className]}
+        style={imgStyle}
+      />
+    )
+  ) : emoji ? (
+    <span class:list={[tileClass, className]} style={boxStyle} aria-hidden="true">
+      <span style={`font-size:${Math.round(size * 0.52)}px;line-height:1`}>{emoji}</span>
+    </span>
+  ) : (
+    <span class:list={[tileClass, className]} style={boxStyle} aria-hidden="true">
+      <svg
+        width={iconSize}
+        height={iconSize}
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        set:html={icon}
+      />
+    </span>
+  )
+}

package/src/components/ToolMeta.astro

@@ -0,0 +1,95 @@
+---
+import { pricingLabels, licenseLabel, useTranslations, type Lang } from '../i18n/ui';
+import { formatStars, type Staleness } from '../lib/github';
+import { pricingTags, COMPLETELY_FREE } from '../lib/pricing';
+import StarIcon from './StarIcon.astro';
+
+interface Props {
+  lang: Lang;
+  pricing: string[];
+  license?: string;
+  language?: string;
+  stars?: number | null;
+  version?: string | null;
+  released?: string | null; // YYYY-MM-DD of the latest release
+  deprecated?: boolean;
+  staleness?: Staleness; // 'stale' (1y+, stronger) or 'aging' (6m+, milder) warning
+  class?: string;
+}
+
+const {
+  lang,
+  pricing,
+  license,
+  language,
+  stars,
+  version,
+  released,
+  deprecated,
+  staleness,
+  class: className,
+} = Astro.props;
+const t = useTranslations(lang);
+// "Maintenance only" and the staleness warning are independent signals and may
+// both apply (e.g. a superseded tool whose repo also went quiet).
+const showStale = staleness === 'stale';
+const showAging = staleness === 'aging';
+const hasAny =
+  deprecated ||
+  showStale ||
+  showAging ||
+  pricing.length > 0 ||
+  license ||
+  language ||
+  typeof stars === 'number' ||
+  version ||
+  released;
+
+// Filled "surface" chips with a faint outline; a touch taller for presence.
+const chip = 'aas-chip rounded-lg px-2.5 py-1';
+---
+
+{
+  hasAny && (
+    <div class:list={['flex flex-wrap items-center gap-1.5 text-xs', className]}>
+      {deprecated && (
+        <span class="aas-deprecated rounded-lg px-2.5 py-1 font-medium">{t('meta.deprecated')}</span>
+      )}
+      {showStale && (
+        <span title={t('meta.staleHint')} class="aas-stale rounded-lg px-2.5 py-1 font-medium">
+          {t('meta.stale')}
+        </span>
+      )}
+      {showAging && (
+        <span title={t('meta.agingHint')} class="aas-aging rounded-lg px-2.5 py-1 font-medium">
+          {t('meta.aging')}
+        </span>
+      )}
+      {typeof stars === 'number' && (
+        <span class:list={['inline-flex items-center gap-1', chip]}>
+          <StarIcon class="text-[var(--aas-text)]" />
+          {formatStars(stars)}
+        </span>
+      )}
+      {version && <span class:list={['font-mono', chip]}>{version}</span>}
+      {released && (
+        <span title={t('meta.released')} class:list={['inline-flex items-center gap-1', chip]}>
+          <span aria-hidden="true">↻</span>
+          {released}
+        </span>
+      )}
+      {language && <span class={chip}>{language}</span>}
+      {pricingTags(pricing).map((p) => (
+        <span class:list={[p === COMPLETELY_FREE ? 'aas-free' : 'aas-pricing', 'rounded-lg px-2.5 py-1']}>
+          {pricingLabels[lang][p] ?? p}
+        </span>
+      ))}
+      {license && (
+        <span class:list={['inline-flex items-center gap-1', chip]}>
+          <span aria-hidden="true">⚖</span>
+          {licenseLabel(lang, license)}
+        </span>
+      )}
+    </div>
+  )
+}

package/src/components/VendorIndex.astro

@@ -0,0 +1,51 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import StackCard from './StackCard.astro';
+import { getStacksByVendor, slugOf } from '../lib/stacks';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  lang: Lang;
+  vendor: string; // url slug
+}
+
+const { lang, vendor } = Astro.props;
+const t = useTranslations(lang);
+const entries = await getStacksByVendor(lang, vendor);
+// The display name is whatever the entries wrote (e.g. "Hugging Face").
+const vendorName = entries[0]?.data.vendor ?? vendor;
+---
+
+<section class="py-6">
+  <a href={getRelativeLocaleUrl(lang, '')} class="text-sm text-[var(--aas-accent)] no-underline"
+    >&larr; {t('tag.allTools')}</a
+  >
+  <h1 class="mt-3 text-3xl font-bold tracking-tight">
+    <span class="text-[var(--aas-muted)]">{t('vendor.heading')}</span> {vendorName}
+  </h1>
+</section>
+
+<div class="mt-4 grid gap-4 sm:grid-cols-2">
+  {
+    entries.map((e) => (
+      <StackCard
+        slug={slugOf(e)}
+        lang={lang}
+        name={e.data.name}
+        formerNames={e.data.formerNames}
+        vendor={e.data.vendor}
+        description={e.data.description}
+        tags={e.data.tags}
+        pricing={e.data.pricing}
+        license={e.data.license}
+        language={e.data.language}
+        category={e.data.category}
+        logo={e.data.logo}
+        logoDark={e.data.logoDark}
+        repo={e.data.repo}
+        version={e.data.version}
+        deprecated={e.data.deprecated}
+      />
+    ))
+  }
+</div>

package/src/content.ts

@@ -0,0 +1,228 @@
+import { defineCollection, z } from 'astro:content';
+import { glob } from 'astro/loaders';
+
+/**
+ * The shared content model for awesome-*-stack sites: `stacks` (the tool
+ * catalog), `articles`, `concepts` and `slides`. A site's content.config.ts
+ * stays thin:
+ *
+ *   import { defineAasCollections } from 'stack-site-builder/content';
+ *   import { categoryMap } from './data/categories';
+ *   export const collections = defineAasCollections({ categoryMap });
+ *
+ * Content lives in the site's `src/content/<collection>/` (the glob bases
+ * below resolve against the site root). `categoryMap` is the site's category
+ * tree — stack entries are validated against it so an unknown category id
+ * fails the build instead of silently dropping the entry from every listing.
+ */
+export function defineAasCollections({ categoryMap }: { categoryMap: Map<string, unknown> }) {
+  /**
+   * The `stacks` collection holds one entry per tool/service used to build
+   * AI agents. Each entry is an MDX file: frontmatter powers the listing and
+   * cards, while the body is the per-service detail page (overview + sample code).
+   *
+   * Entries are locale-partitioned: `stacks/en/<slug>.mdx`, `stacks/ko/<slug>.mdx`.
+   */
+  const stacks = defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/stacks' }),
+    schema: z.object({
+      name: z.string(),
+      // Prior names after a rename/rebrand, newest first. The card shows just the
+      // most recent (formerNames[0]); the detail page shows all of them.
+      formerNames: z.array(z.string()).default([]),
+      // Living-doc metadata for THIS catalog entry's writeup — bump on edits.
+      // Distinct from the tool's own software `version` (further below): docVersion
+      // tracks our article, `version` tracks the tool's release.
+      docVersion: z.string().optional(), // e.g. "1.0"
+      updated: z.coerce.date().optional(), // when the writeup was last revised (YYYY-MM-DD)
+      // The organization / company / person that makes and maintains the tool
+      // (e.g. "Microsoft"). Powers the per-vendor browse pages at /vendors/<slug>.
+      vendor: z.string().optional(),
+      // Must be a node id from the tree in the site's src/data/categories.ts. Validated here
+      // because an unknown id would not error anywhere downstream — the entry
+      // would just silently drop out of the homepage and every category page.
+      category: z.string().refine((id) => categoryMap.has(id), {
+        message: 'unknown category id — must match a node in the site data category tree',
+      }),
+      description: z.string(),
+      logo: z.string().optional(), // optional image URL/path; otherwise a monogram is shown
+      logoDark: z.string().optional(), // optional dark-theme variant of `logo`
+      website: z.string().url().optional(),
+      repo: z.string().url().optional(),
+      docs: z.string().url().optional(),
+      tags: z.array(z.string()).default([]),
+      language: z.string().optional(),
+      license: z.string().optional(),
+      version: z.string().optional(), // manual fallback; GitHub release/tag is used when available
+
+      // Composable pricing/hosting model tags (a tool can be several at once):
+      //   open-source = source is open / free to self-host
+      //   free-tier   = vendor-hosted free tier
+      //   paid        = paid plans exist
+      //   free        = entirely free to use (non-OSS)
+      pricing: z.array(z.enum(['open-source', 'free-tier', 'paid', 'free'])).default([]),
+      // Human-readable pricing summary shown on the detail page, with its source
+      // and the date it was last checked. `pricingNote` is localized per file.
+      pricingNote: z.string().optional(), // short intro shown above the tiers table
+      pricingTiers: z
+        .array(z.object({ plan: z.string(), price: z.string(), note: z.string().optional() }))
+        .default([]), // localized plan / price / note rows
+      pricingSource: z.string().url().optional(),
+      pricingCheckedAt: z.string().optional(), // YYYY-MM-DD
+      deprecated: z.boolean().default(false), // maintenance-only / superseded
+      related: z.array(z.string()).default([]), // slugs of related tools (same collection)
+      // Sample project folders under samples/. Either a bare folder name, or an
+      // object pairing the folder with the tools that project uses (slugs of other
+      // stacks; unknown slugs render as "not in our catalog").
+      //   projects: [langgraph_1]
+      //   projects:
+      //     - folder: langgraph_1
+      //       related: [langgraph, langchain]
+      projects: z
+        .array(
+          z.union([
+            z.string(),
+            z.object({
+              folder: z.string(),
+              related: z.array(z.string()).default([]),
+            }),
+          ]),
+        )
+        .default([]),
+
+
+
+      // Versioned code samples for the "Code" tab. Each can carry a Mermaid
+      // diagram explaining the structure plus a highlighted code snippet.
+      samples: z
+        .array(
+          z.object({
+            version: z.string(), // label shown in the version selector
+            lang: z.string().default('ts'), // language id for syntax highlighting
+            description: z.string().optional(), // Markdown explanation, shown above the code
+            diagram: z.string().optional(), // Mermaid source
+            code: z.string(),
+            note: z.string().optional(), // short caption below the code
+          }),
+        )
+        .default([]),
+      featured: z.boolean().default(false),
+    }),
+  });
+
+  /**
+   * The `articles` collection is the writing space — long-form posts kept
+   * separate from the tool catalog. `tools` lists the stack slugs an article
+   * references; it powers both forward links (article → tool) and backlinks
+   * (tool → article, computed in src/lib/articles.ts).
+   *
+   * Locale-partitioned like stacks: `articles/en/<slug>.mdx`, `articles/ko/...`.
+   */
+  const articles = defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/articles' }),
+    schema: ({ image }) =>
+      z.object({
+        title: z.string(),
+        description: z.string(),
+        date: z.coerce.date(), // first published
+        // Living-doc metadata, mirroring concepts: bump on meaningful edits.
+        version: z.string().optional(), // e.g. "1.0"
+        updated: z.coerce.date().optional(), // last meaningful update (YYYY-MM-DD)
+        image: image().optional(), // hero / card image (optimized; relative to the file)
+        imageAlt: z.string().optional(),
+        // Leaf id from the site's src/data/article-categories.ts (powers the breadcrumb +
+        // category browse pages + grouped index, like a stack's category).
+        category: z.string().optional(),
+        tools: z.array(z.string()).default([]),
+        related: z.array(z.string()).default([]), // related article slugs (mutual cross-links)
+        // Optional runnable sample (samples/<folder>/) the article walks through.
+        // Embed its viewer in the body with <SampleProject folder="…"/>; this
+        // field powers the right-rail file list + related tools (like a stack's
+        // implementation tab). A bare folder name, or { folder, related: [slugs] }.
+        project: z
+          .union([
+            z.string(),
+            z.object({ folder: z.string(), related: z.array(z.string()).default([]) }),
+          ])
+          .optional(),
+        tags: z.array(z.string()).default([]),
+        draft: z.boolean().default(false),
+      }),
+  });
+
+  /**
+   * The `concepts` collection explains higher-level patterns that compose several
+   * catalog tools into a working setup (e.g. "harness engineering"). Each concept
+   * groups the tools it uses by the role they play, and links related articles.
+   *
+   * Locale-partitioned like the others: `concepts/<lang>/<slug>.mdx`.
+   */
+  const concepts = defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/concepts' }),
+    schema: ({ image }) =>
+      z.object({
+        title: z.string(),
+        description: z.string(),
+        image: image().optional(), // hero / card image (optimized; relative to the file)
+        imageAlt: z.string().optional(),
+        // Leaf id from the site's src/data/concept-categories.ts (powers the breadcrumb +
+        // category browse pages + grouped index, like a stack's category).
+        category: z.string().optional(),
+        // A concept is living documentation: bump `version` and `updated` on edits.
+        version: z.string().optional(), // e.g. "1.0"
+        updated: z.coerce.date().optional(), // last meaningful update (YYYY-MM-DD)
+        // Tools grouped by the role they play in the pattern. `role` is content, so
+        // it's written per-locale (e.g. "메모리" / "Memory"); `tools` are stack slugs.
+        tools: z
+          .array(z.object({ role: z.string(), tools: z.array(z.string()).default([]) }))
+          .default([]),
+        articles: z.array(z.string()).default([]), // related article slugs
+        related: z.array(z.string()).default([]), // related concept slugs
+        tags: z.array(z.string()).default([]),
+        order: z.number().optional(), // manual sort on the index (lower first)
+        draft: z.boolean().default(false),
+      }),
+  });
+
+  /**
+   * The `slides` collection holds presentation decks — one MDX file per deck, with
+   * each slide wrapped in a <Slide> component (see src/components/Slide.astro). The
+   * deck renders as a fullscreen scroll-snap presentation at /slides/<name>/.
+   *
+   * Decks are self-contained and language-agnostic (flat, not locale-partitioned):
+   * a deck's prose carries its own language, and both locale indexes link to the
+   * same deck. Add per-locale folders later if decks need translating.
+   */
+  const slides = defineCollection({
+    loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/slides' }),
+    schema: z.object({
+      title: z.string(),
+      description: z.string(),
+      // Concept slug this deck summarizes (links back to /concept/<slug>/).
+      related: z.string().optional(),
+      order: z.number().optional(), // manual sort on the index (lower first)
+      // Slide-change animation: 'slide' animates the scroll between slides,
+      // 'none' cuts instantly. (Reduced-motion users always get an instant cut.)
+      transition: z.enum(['slide', 'none']).default('slide'),
+      // Visual style theme (typography / accent / spacing). Light vs dark still
+      // follows the site's color-scheme preference; this only picks the look.
+      theme: z.enum(['default', 'simple', 'calm', 'bold']).default('default'),
+      // Content aspect ratio: the content area's width tracks this ratio × height,
+      // so 16:9/16:10/4:3 give a proportioned (wider) content column; 'fill' uses
+      // the full slide width.
+      aspect: z.enum(['16:9', '16:10', '4:3', 'fill']).default('16:9'),
+      // Optional footer (bottom-left): presenter name and a date/version string.
+      presenter: z.string().optional(),
+      date: z.string().optional(),
+      // In-deck table of contents (top-right). `toc` toggles it; `toc_level` is the
+      // deepest heading level it includes (2 = ## only … up to 4 = ## ### ####);
+      // `toc_open` starts it expanded. Exclude a whole slide with <Slide toc={false}>.
+      toc: z.boolean().default(true),
+      toc_level: z.number().int().min(2).max(4).default(2),
+      toc_open: z.boolean().default(true),
+      draft: z.boolean().default(false),
+    }),
+  });
+
+  return { stacks, articles, concepts, slides };
+}