stack-site-builder 1.10.0

package/src/components/ArticleDetail.astro

@@ -0,0 +1,100 @@
+---
+import { render } from 'astro:content';
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
+import { getConcepts, type ConceptEntry } from '../lib/concepts';
+import { Image } from 'astro:assets';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { formatDate } from '../lib/dates';
+import { inlineMd } from '../lib/inline-md';
+import TocRail from './TocRail.astro';
+import MermaidLoader from './MermaidLoader.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import { articleTree, articleCatOf } from '@aas-data/article-categories';
+import RelatedTools from './RelatedTools.astro';
+import RelatedConcepts from './RelatedConcepts.astro';
+import RelatedArticles from './RelatedArticles.astro';
+
+interface Props {
+  entry: ArticleEntry;
+  lang: Lang;
+}
+
+const { entry, lang } = Astro.props;
+const t = useTranslations(lang);
+const { Content, headings } = await render(entry);
+const data = entry.data;
+const dateStr = data.date.toISOString().slice(0, 10);
+const updatedStr = data.updated?.toISOString().slice(0, 10);
+const tocItems = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+// Articles may embed Mermaid diagrams (and a <SampleProject/> whose README can
+// too); load the client renderer when the body uses any.
+const bodyHasMermaid = (entry.body ?? '').includes('```mermaid');
+
+// Related concepts: concepts whose frontmatter lists this article (backlink).
+const articleSlug = articleSlugOf(entry);
+const relatedConcepts = (await getConcepts(lang)).filter((c) =>
+  c.data.articles.includes(articleSlug),
+) as ConceptEntry[];
+
+// Related writing: articles this one explicitly cross-links (frontmatter
+// `related`), kept in the authored order.
+const articlesBySlug = new Map((await getArticles(lang)).map((a) => [articleSlugOf(a), a]));
+const relatedArticles = (data.related ?? [])
+  .map((s) => articlesBySlug.get(s))
+  .filter((a): a is ArticleEntry => Boolean(a) && articleSlugOf(a!) !== articleSlug);
+
+// A referenced sample (frontmatter `project`) is no longer embedded here — the
+// body's <SampleProject/> renders a callout card to its sample/<folder>/ page,
+// which carries the viewer, the file rail, and the related tools itself.
+
+// Breadcrumb: All writing › category › subcategory… (each segment linked).
+const crumbs = [
+  { label: t('article.backToBlog'), href: getRelativeLocaleUrl(lang, 'article/') },
+  ...articleTree.pathOf(articleCatOf(data.category)).map((c) => ({
+    label: c.label[lang],
+    href: getRelativeLocaleUrl(lang, `article/category/${c.id}/`),
+  })),
+];
+---
+
+<Breadcrumb segments={crumbs} />
+
+<header class="mt-4 pb-6">
+  <p class="text-sm text-[var(--aas-muted)]">
+    <time datetime={dateStr}>{formatDate(data.date, lang)}</time>
+    {data.version && <span> · {t('meta.docVersion')} {data.version}</span>}
+    {data.updated && updatedStr !== dateStr && (
+      <span>
+        {' '}
+        · {t('meta.updated')} <time datetime={updatedStr}>{formatDate(data.updated, lang)}</time>
+      </span>
+    )}
+  </p>
+  <h1 class="mt-1 text-3xl font-bold tracking-tight">{data.title}</h1>
+  <p class="mt-2 aas-md text-lg whitespace-pre-line text-[var(--aas-muted)]" set:html={inlineMd(data.description)} />
+  {
+    data.image && (
+      <Image
+        src={data.image}
+        alt={data.imageAlt ?? data.title}
+        class="mt-5 aspect-[2/1] w-full rounded-2xl border border-[var(--aas-border)] object-cover"
+      />
+    )
+  }
+</header>
+
+<RelatedConcepts lang={lang} concepts={relatedConcepts} />
+
+<div class="mt-8 flex items-start gap-8">
+  <article class="prose max-w-none aas-reading min-w-0 flex-1">
+    <Content />
+  </article>
+  <TocRail lang={lang} items={tocItems} />
+</div>
+
+<RelatedTools lang={lang} slugs={data.tools} />
+
+<RelatedArticles lang={lang} articles={relatedArticles} />
+
+{bodyHasMermaid && <MermaidLoader />}

package/src/components/ArticleLink.astro

@@ -0,0 +1,45 @@
+---
+// Inline, full-width callout linking to a blog article, for use inside a
+// concept's MDX body, e.g.
+//   <ArticleLink slug="web-search-fx-agent" />
+// Deliberately distinct from <ConceptLink/> (a filled accent tint, "learn
+// more"): this is a plain panel with an accent left-bar, a "related writing"
+// label, and the post's date — signalling a read, not another concept.
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
+import { formatDate } from '../lib/dates';
+import { useTranslations, type Lang } from '../i18n/ui';
+import { inlineMd } from '../lib/inline-md';
+
+interface Props {
+  slug: string;
+}
+
+const { slug } = Astro.props;
+const lang: Lang = Astro.currentLocale === 'ko' ? 'ko' : 'en';
+const t = useTranslations(lang);
+const articles = await getArticles(lang);
+const target = articles.find((a) => articleSlugOf(a) === slug) as ArticleEntry | undefined;
+---
+
+{
+  target && (
+    <a
+      href={getRelativeLocaleUrl(lang, `article/${articleSlugOf(target)}/`)}
+      class="aas-lift mt-3 flex items-start gap-4 rounded-xl border border-l-4 p-4 no-underline"
+      style="border-color: var(--aas-border); border-left-color: var(--aas-accent); background: var(--aas-panel);"
+    >
+      <div class="min-w-0 flex-1">
+        <span class="block text-xs font-semibold tracking-wide text-[var(--aas-accent)] uppercase">
+          {t('detail.relatedWriting')}
+        </span>
+        <span class="mt-0.5 block font-semibold text-[var(--aas-text)]">{target.data.title}</span>
+        <span class="aas-md mt-1 block text-sm text-[var(--aas-muted)]" set:html={inlineMd(target.data.description)} />
+        <span class="mt-1.5 block text-xs text-[var(--aas-muted)]">
+          {formatDate(target.data.date, lang)}
+        </span>
+      </div>
+      <span aria-hidden="true" class="shrink-0 text-xl text-[var(--aas-accent)]">&rarr;</span>
+    </a>
+  )
+}

package/src/components/BackToTop.astro

@@ -0,0 +1,47 @@
+---
+// Floating "back to top" button. Mobile only — on wide viewports (≥1200px) the
+// sticky TOC rail already gives a way to jump around, so it is hidden there via
+// the .aas-totop rule in global.css. Appears once the page is scrolled down.
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  lang: Lang;
+}
+
+const { lang } = Astro.props;
+const t = useTranslations(lang);
+---
+
+<button
+  type="button"
+  data-totop
+  aria-label={t('nav.backToTop')}
+  class="aas-totop fixed right-5 bottom-5 z-40 h-11 w-11 items-center justify-center rounded-full border border-[var(--aas-border)] bg-[var(--aas-panel)] text-[var(--aas-text)] shadow-lg transition hover:text-[var(--aas-accent)]"
+>
+  <svg
+    width="20"
+    height="20"
+    viewBox="0 0 24 24"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="2"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+    aria-hidden="true"
+  >
+    <path d="m18 15-6-6-6 6" />
+  </svg>
+</button>
+
+<script>
+  const btn = document.querySelector('[data-totop]');
+  if (btn) {
+    const onScroll = () => {
+      if (window.scrollY > 400) btn.setAttribute('data-visible', '');
+      else btn.removeAttribute('data-visible');
+    };
+    onScroll();
+    window.addEventListener('scroll', onScroll, { passive: true });
+    btn.addEventListener('click', () => window.scrollTo({ top: 0, behavior: 'smooth' }));
+  }
+</script>

package/src/components/BlogIndex.astro

@@ -0,0 +1,137 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import ArticleCard from './ArticleCard.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import ListControls from './ListControls.astro';
+import ArrowUpRight from './ArrowUpRight.astro';
+
+const PAGE = 12;
+import { articleTree, articleCatOf } from '@aas-data/article-categories';
+import { getArticles, articleSlugOf, type ArticleEntry } from '../lib/articles';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+// Doubles as the writing index (no `categoryId` → all articles, grouped by
+// category) and a category browse page (`categoryId` → that category, with a
+// breadcrumb, its direct articles, and a section per subcategory).
+interface Props {
+  lang: Lang;
+  categoryId?: string;
+}
+
+const { lang, categoryId } = Astro.props;
+const t = useTranslations(lang);
+const all = await getArticles(lang);
+const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `article/category/${cid}/`);
+
+const itemsIn = (cid: string): ArticleEntry[] => {
+  const ids = new Set(articleTree.descendantIds(cid));
+  return all.filter((a) => ids.has(articleCatOf(a.data.category)));
+};
+
+const node = categoryId ? articleTree.map.get(categoryId) : undefined;
+const sections = node ? articleTree.childrenOf(node.id) : articleTree.roots;
+const direct = node ? all.filter((a) => articleCatOf(a.data.category) === node.id) : [];
+
+// A leaf category page shows one flat list — that grid gets ?page= pagination.
+// Index and parent-category pages stay grouped overviews: each section is
+// capped to PAGE cards with a "see all" link to the fuller list.
+const isLeaf = !!node && sections.length === 0;
+
+const path = node ? articleTree.pathOf(node.id) : [];
+const crumbs = node
+  ? [
+      { label: t('article.backToBlog'), href: getRelativeLocaleUrl(lang, 'article/') },
+      ...path.map((c, i) => ({
+        label: c.label[lang],
+        href: i === path.length - 1 ? undefined : catUrl(c.id),
+      })),
+    ]
+  : [];
+
+const card = (a: ArticleEntry) => ({
+  lang,
+  slug: articleSlugOf(a),
+  title: a.data.title,
+  description: a.data.description,
+  date: a.data.date,
+  version: a.data.version,
+  tags: a.data.tags,
+  image: a.data.image,
+  imageAlt: a.data.imageAlt,
+});
+---
+
+{
+  node ? (
+    <>
+      <Breadcrumb segments={crumbs} />
+      <header class="mt-4">
+        <h1 class="text-3xl font-bold tracking-tight">{node.label[lang]}</h1>
+        <p class="mt-2 max-w-2xl text-lg text-[var(--aas-muted)]">
+          {node.detail?.[lang] ?? node.description[lang]}
+        </p>
+      </header>
+    </>
+  ) : (
+    <section class="py-6">
+      <h1 class="text-4xl font-bold tracking-tight">{t('blog.title')}</h1>
+      <p class="mt-3 max-w-2xl text-lg text-[var(--aas-muted)]">{t('blog.tagline')}</p>
+    </section>
+  )
+}
+
+{all.length === 0 && <p class="mt-8 text-[var(--aas-muted)]">{t('blog.empty')}</p>}
+
+{all.length > 0 && <div class="mt-6"><ListControls lang={lang} /></div>}
+
+{
+  direct.length > 0 && (
+    <div
+      class="mt-4 grid gap-5 sm:grid-cols-2"
+      data-sortgrid
+      data-paginate={isLeaf ? true : undefined}
+      data-page-size={isLeaf ? PAGE : undefined}
+    >
+      {direct.map((a) => (
+        <ArticleCard {...card(a)} />
+      ))}
+    </div>
+  )
+}
+
+{
+  sections.map((cat) => {
+    const items = itemsIn(cat.id);
+    return (
+      items.length > 0 && (
+        <section class="mt-8">
+          <h2 class="text-2xl font-semibold">
+            <a
+              href={catUrl(cat.id)}
+              class="text-[var(--aas-text)] no-underline hover:text-[var(--aas-accent)]"
+            >
+              {cat.label[lang]}
+              <ArrowUpRight size={20} class="ml-1 text-[var(--aas-muted)]" />
+            </a>
+          </h2>
+          <p class="mt-1 text-sm text-[var(--aas-muted)]">{cat.description[lang]}</p>
+          <div class="mt-4 grid gap-5 sm:grid-cols-2" data-sortgrid>
+            {items.slice(0, PAGE).map((a) => (
+              <ArticleCard {...card(a)} />
+            ))}
+          </div>
+          {items.length > PAGE && (
+            <a
+              href={catUrl(cat.id)}
+              class="mt-3 inline-block text-sm font-medium text-[var(--aas-accent)] no-underline"
+            >
+              {t('list.seeAll').replace('{n}', String(items.length))} &rarr;
+            </a>
+          )}
+        </section>
+      )
+    );
+  })
+}
+
+{isLeaf && <nav data-pager aria-label="Pagination" class="mt-8 flex flex-wrap items-center justify-center gap-1.5" />}

package/src/components/Breadcrumb.astro

@@ -0,0 +1,37 @@
+---
+// A simple breadcrumb trail. Segments with an `href` render as links; the
+// last (current) segment is typically passed without one.
+interface Segment {
+  label: string;
+  href?: string;
+}
+interface Props {
+  segments: Segment[];
+  class?: string;
+}
+const { segments, class: className } = Astro.props;
+---
+
+<nav
+  aria-label="Breadcrumb"
+  class:list={['flex flex-wrap items-center gap-1.5 text-sm text-[var(--aas-muted)]', className]}
+>
+  {
+    segments.map((s, i) => (
+      <Fragment>
+        {i > 0 && (
+          <span aria-hidden="true" class="opacity-60">
+            ›
+          </span>
+        )}
+        {s.href ? (
+          <a href={s.href} class="text-[var(--aas-accent)] no-underline hover:underline">
+            {s.label}
+          </a>
+        ) : (
+          <span class="text-[var(--aas-text)]">{s.label}</span>
+        )}
+      </Fragment>
+    ))
+  }
+</nav>

package/src/components/CategoryIndex.astro

@@ -0,0 +1,115 @@
+---
+import { getRelativeLocaleUrl } from 'astro:i18n';
+import StackCard from './StackCard.astro';
+import Breadcrumb from './Breadcrumb.astro';
+import FilterControls from './FilterControls.astro';
+import ArrowUpRight from './ArrowUpRight.astro';
+import { categoryMap, childrenOf, pathOf } from '@aas-data/categories';
+import { getStacks, getStacksByCategory, slugOf, type StackEntry } from '../lib/stacks';
+import { deriveFacets } from '../lib/facets';
+import { useTranslations, type Lang } from '../i18n/ui';
+
+interface Props {
+  lang: Lang;
+  id: string;
+}
+
+const { lang, id } = Astro.props;
+const t = useTranslations(lang);
+const node = categoryMap.get(id)!;
+const catUrl = (cid: string) => getRelativeLocaleUrl(lang, `categories/${cid}/`);
+
+// Breadcrumb: All tools › ancestors… › current (current is not a link).
+const path = pathOf(id);
+const crumbs = [
+  { label: t('detail.allTools'), href: getRelativeLocaleUrl(lang, '') },
+  ...path.map((c, i) => ({
+    label: c.label[lang],
+    href: i === path.length - 1 ? undefined : catUrl(c.id),
+  })),
+];
+
+const children = childrenOf(id);
+// Stacks attached directly to this node (vs. nested under a subcategory).
+const direct = (await getStacksByCategory(lang, id)).filter((s) => s.data.category === id);
+// Each child subcategory with its own rolled-up stacks.
+const childGroups = await Promise.all(
+  children.map(async (c) => ({ cat: c, items: await getStacksByCategory(lang, c.id) })),
+);
+
+// Filter facets are built from the WHOLE catalog (not just this page's tools) so
+// they're identical on every page — a sort/filter carried in from elsewhere can
+// always be restored here, even if no tool in this category has that value.
+const facets = deriveFacets(await getStacks(lang), lang);
+
+const cardProps = (e: StackEntry) => ({
+  slug: slugOf(e),
+  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,
+});
+---
+
+<section class="py-6">
+  <Breadcrumb segments={crumbs} />
+  <h1 class="mt-3 text-3xl font-bold tracking-tight">{node.label[lang]}</h1>
+  <p class="mt-3 max-w-3xl leading-relaxed text-[var(--aas-muted)]">
+    {node.detail?.[lang] ?? node.description[lang]}
+  </p>
+</section>
+
+{/* Search · filter · sort controls (client-side, URL-synced) */}
+<div class="mb-8">
+  <FilterControls lang={lang} facets={facets} />
+</div>
+
+{/* Tools sitting directly on this node (no subcategory). */}
+{
+  direct.length > 0 && (
+    <div data-section>
+      <div class="grid gap-4 sm:grid-cols-2" data-grid>
+        {direct.map((e) => (
+          <StackCard {...cardProps(e)} />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+{/* One section per subcategory, each rolling up its own subtree. */}
+<div class="mt-8 space-y-12">
+  {
+    childGroups
+      .filter((g) => g.items.length > 0)
+      .map((g) => (
+        <div data-section>
+          <div class="pb-1">
+            <h2 class="text-2xl font-semibold">
+              <a href={catUrl(g.cat.id)} data-keep-filters class="text-[var(--aas-text)] no-underline hover:text-[var(--aas-accent)]">
+                {g.cat.label[lang]}
+                <ArrowUpRight size={20} class="ml-1 text-[var(--aas-muted)]" />
+              </a>
+            </h2>
+            <p class="mt-1 text-sm text-[var(--aas-muted)]">{g.cat.description[lang]}</p>
+          </div>
+          <div class="mt-5 grid gap-4 sm:grid-cols-2" data-grid>
+            {g.items.map((e) => (
+              <StackCard {...cardProps(e)} />
+            ))}
+          </div>
+        </div>
+      ))
+  }
+</div>

package/src/components/ChevronDown.astro

@@ -0,0 +1,23 @@
+---
+interface Props {
+  size?: number;
+  class?: string;
+}
+
+const { size = 16, class: className } = Astro.props;
+---
+
+<svg
+  width={size}
+  height={size}
+  viewBox="0 0 24 24"
+  fill="none"
+  stroke="currentColor"
+  stroke-width="2"
+  stroke-linecap="round"
+  stroke-linejoin="round"
+  aria-hidden="true"
+  class:list={['shrink-0', className]}
+>
+  <path d="m6 9 6 6 6-6"></path>
+</svg>

package/src/components/CodeSamples.astro

@@ -0,0 +1,141 @@
+---
+import { useTranslations, type Lang } from '../i18n/ui';
+import ChevronDown from './ChevronDown.astro';
+import type { RenderedSample } from '../lib/samples';
+
+interface Props {
+  samples: RenderedSample[];
+  lang: Lang;
+}
+
+const { samples, lang } = Astro.props;
+const t = useTranslations(lang);
+---
+
+<div class="aas-samples" data-samples>
+  <div class="aas-sample-picker flex items-center gap-2 text-sm text-[var(--aas-muted)]">
+    {t('sample.example')}
+    <details class="aas-vdd" data-samples-dd>
+      <summary
+        class="flex cursor-pointer list-none items-center gap-2 rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] px-3 py-1.5 text-[var(--aas-text)] select-none"
+      >
+        <span data-sample-current>{samples[0]?.version}</span>
+        <ChevronDown class="text-[var(--aas-muted)]" />
+      </summary>
+      <ul
+        class="absolute left-0 z-10 mt-1 min-w-[13rem] overflow-hidden rounded-lg border border-[var(--aas-border)] bg-[var(--aas-panel)] py-1 shadow-lg"
+      >
+        {
+          samples.map((s, i) => (
+            <li>
+              <button
+                type="button"
+                data-sample-option={i}
+                data-sample-version={s.version}
+                aria-current={i === 0 ? 'true' : 'false'}
+                class="flex w-full items-center justify-between gap-2 px-3 py-1.5 text-left text-[var(--aas-muted)] hover:bg-[var(--aas-tint)] aria-[current=true]:font-semibold aria-[current=true]:text-[var(--aas-text)]"
+              >
+                {s.version}
+                <span data-check aria-hidden="true" class="opacity-0">
+                  ✓
+                </span>
+              </button>
+            </li>
+          ))
+        }
+      </ul>
+    </details>
+  </div>
+
+  <div class="mt-4 space-y-4">
+    {
+      samples.map((s, i) => (
+        <div data-sample-panel={i} class:list={[i === 0 ? '' : 'hidden']}>
+          {s.descHtml && <div class="prose mb-4 max-w-none" set:html={s.descHtml} />}
+          {s.diagram && (
+            <figure class="mb-4">
+              <figcaption class="mb-1 text-xs tracking-wide text-[var(--aas-muted)] uppercase">
+                {t('sample.diagram')}
+              </figcaption>
+              <div class="aas-diagram">
+                <pre class="mermaid">{s.diagram}</pre>
+              </div>
+            </figure>
+          )}
+          <div class="aas-code overflow-x-auto rounded-lg border border-[var(--aas-border)]" set:html={s.codeHtml} />
+          {s.note && <p class="mt-2 text-sm text-[var(--aas-muted)]">{s.note}</p>}
+        </div>
+      ))
+    }
+  </div>
+</div>
+
+<style>
+  .aas-vdd {
+    position: relative;
+  }
+  .aas-vdd > summary::-webkit-details-marker {
+    display: none;
+  }
+  .aas-vdd [data-sample-option][aria-current='true'] [data-check] {
+    opacity: 1;
+  }
+  /* Shiki emits its own background; pad it and keep corners rounded. */
+  .aas-code :global(pre.shiki) {
+    margin: 0;
+    padding: 1rem 1.1rem;
+    border-radius: 0.5rem;
+    overflow-x: auto;
+  }
+</style>
+
+<script>
+  document.querySelectorAll<HTMLElement>('[data-samples]').forEach((root) => {
+    const dd = root.querySelector<HTMLDetailsElement>('[data-samples-dd]');
+    const current = root.querySelector<HTMLElement>('[data-sample-current]');
+    const options = Array.from(root.querySelectorAll<HTMLButtonElement>('[data-sample-option]'));
+    const panels = Array.from(root.querySelectorAll<HTMLElement>('[data-sample-panel]'));
+
+    // The selected example lives in ?v=. The default (index 0) drops the param
+    // so there's one canonical URL per view — mirroring how DetailTabs drops
+    // ?tab for the default Overview tab.
+    const V_PARAM = 'v';
+    function writeV(index: string) {
+      const url = new URL(location.href);
+      if (index === '0') url.searchParams.delete(V_PARAM);
+      else url.searchParams.set(V_PARAM, index);
+      history.replaceState(null, '', url.pathname + url.search + url.hash);
+    }
+
+    function apply(index: string, write: boolean) {
+      panels.forEach((p) => p.classList.toggle('hidden', p.dataset.samplePanel !== index));
+      options.forEach((o) =>
+        o.setAttribute('aria-current', String(o.dataset.sampleOption === index)),
+      );
+      const opt = options.find((o) => o.dataset.sampleOption === index);
+      if (current && opt) current.textContent = opt.dataset.sampleVersion ?? '';
+      dd?.removeAttribute('open');
+      (window as unknown as { __aasRenderMermaid?: () => void }).__aasRenderMermaid?.();
+      document.dispatchEvent(new CustomEvent('aas:sample', { detail: { index: Number(index) } }));
+      if (write) writeV(index);
+    }
+
+    options.forEach((o) => o.addEventListener('click', () => apply(o.dataset.sampleOption!, true)));
+
+    // External request (e.g. a #s<n>-... deep link from DetailTabs).
+    document.addEventListener('aas:select-sample', (e) =>
+      apply(String((e as CustomEvent<{ index: number }>).detail.index), true),
+    );
+
+    // Restore the version from ?v= on load.
+    const v = new URLSearchParams(location.search).get(V_PARAM);
+    if (v && options.some((o) => o.dataset.sampleOption === v)) apply(v, false);
+
+    // Reflect the current version when the code tab becomes active (0 → drop ?v).
+    document.addEventListener('aas:tabchange', (e) => {
+      if ((e as CustomEvent<{ id: string }>).detail.id !== 'code') return;
+      const cur = options.find((o) => o.getAttribute('aria-current') === 'true');
+      if (cur) writeV(cur.dataset.sampleOption!);
+    });
+  });
+</script>