From 78e48dee5f68e8b18ce40a6c45983e77acedc3ff Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Fri, 14 Aug 2026 14:04:31 +0100
Subject: [PATCH 1/3] docs: add SDK language switcher

---
 astro.config.mjs                        |   3 +-
 plugins/remark-language-code-groups.mjs | 174 ++++++++++++++++++++++++
 scripts/check-generated-markdown.mjs    |  10 +-
 scripts/copy-md-sources.mjs             |  20 ++-
 src/components/Head.astro               |   2 +
 src/components/LanguageCodeSync.astro   | 168 +++++++++++++++++++++++
 src/styles/custom.css                   | 125 +++++++++++++++++
 7 files changed, 496 insertions(+), 6 deletions(-)
 create mode 100644 plugins/remark-language-code-groups.mjs
 create mode 100644 src/components/LanguageCodeSync.astro

diff --git a/astro.config.mjs b/astro.config.mjs
index 5a2ee6e..d5afc2b 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -5,6 +5,7 @@ import starlightClientMermaid from '@pasqal-io/starlight-client-mermaid';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import rehypeBasePath from './plugins/rehype-base-path.mjs';
 import remarkSnippet from './plugins/remark-snippet.mjs';
+import remarkLanguageCodeGroups from './plugins/remark-language-code-groups.mjs';
 
 // https://astro.build/config
 export default defineConfig({
@@ -73,7 +74,7 @@ export default defineConfig({
 	},
 	base: process.env.BASE_PATH || '/',
 	markdown: {
-		remarkPlugins: [remarkSnippet],
+		remarkPlugins: [remarkSnippet, remarkLanguageCodeGroups],
 		rehypePlugins: [[rehypeBasePath, { base: process.env.BASE_PATH || '/' }]],
 	},
 	integrations: [
diff --git a/plugins/remark-language-code-groups.mjs b/plugins/remark-language-code-groups.mjs
new file mode 100644
index 0000000..105f708
--- /dev/null
+++ b/plugins/remark-language-code-groups.mjs
@@ -0,0 +1,174 @@
+const CODE_LANGUAGE_META =
+  /(?:^|\s)code-language="(javascript|react-native|rust)"/;
+
+const LANGUAGE_LABELS = {
+  javascript: 'JavaScript',
+  'react-native': 'React Native',
+  rust: 'Rust',
+};
+
+const LANGUAGE_ORDER = ['javascript', 'react-native', 'rust'];
+
+/**
+ * Turn consecutive language-specific code fences into an accessible,
+ * synchronized language group. Every group has JavaScript and Rust, while
+ * individual groups may also offer React Native.
+ *
+ * Usage:
+ *
+ *   ```js code-language="javascript"
+ *   ```
+ *   ```js code-language="react-native"
+ *   ```
+ *   ```rust code-language="rust"
+ *   ```
+ */
+export default function remarkLanguageCodeGroups() {
+  return (tree) => {
+    let groupIndex = 0;
+
+    walk(tree, () => {
+      groupIndex += 1;
+      return groupIndex;
+    });
+  };
+}
+
+function walk(parent, nextGroupIndex) {
+  if (!Array.isArray(parent.children)) return;
+
+  for (let index = 0; index < parent.children.length; index += 1) {
+    const first = getLanguageCode(parent.children[index]);
+    if (!first) {
+      walk(parent.children[index], nextGroupIndex);
+      continue;
+    }
+
+    const groupedCodes = [];
+    for (let cursor = index; cursor < parent.children.length; cursor += 1) {
+      const code = getLanguageCode(parent.children[cursor]);
+      if (!code) break;
+      groupedCodes.push(code);
+    }
+
+    if (groupedCodes.length < 2) {
+      throw new Error(
+        `language code group: ${first.language} block must be followed by its paired language block`,
+      );
+    }
+
+    const blocks = new Map();
+    for (const code of groupedCodes) {
+      if (blocks.has(code.language)) {
+        throw new Error(
+          `language code group: duplicate ${code.language} block`,
+        );
+      }
+      blocks.set(code.language, code.node);
+    }
+
+    if (!blocks.has('javascript') || !blocks.has('rust')) {
+      throw new Error(
+        'language code group: each group must contain one JavaScript block and one Rust block',
+      );
+    }
+
+    const groupId = `language-code-${nextGroupIndex()}`;
+    const languages = LANGUAGE_ORDER.filter((language) => blocks.has(language));
+    for (const language of languages) {
+      const block = blocks.get(language);
+      block.meta = withUnframedCodeWindow(block.meta);
+    }
+
+    const replacement = [
+      {
+        type: 'html',
+        value: renderGroupStart(groupId, languages),
+      },
+      blocks.get(languages[0]),
+    ];
+
+    for (const language of languages.slice(1)) {
+      replacement.push(
+        {
+          type: 'html',
+          value: renderPanelSwitch(groupId, language),
+        },
+        blocks.get(language),
+      );
+    }
+    replacement.push({
+      type: 'html',
+      value: '</div>\n</div>\n</div>',
+    });
+
+    parent.children.splice(index, groupedCodes.length, ...replacement);
+
+    index += replacement.length - 1;
+  }
+}
+
+function getLanguageCode(node) {
+  if (node?.type !== 'code' || !node.meta) return null;
+
+  const language = getCodeLanguage(node.meta);
+  if (!language) return null;
+
+  return {
+    language,
+    node,
+  };
+}
+
+export function getCodeLanguage(meta) {
+  return meta?.match(CODE_LANGUAGE_META)?.[1] ?? null;
+}
+
+export function stripCodeLanguage(meta) {
+  return meta
+    .replace(
+      /(^|\s+)code-language="(?:javascript|react-native|rust)"/,
+      '$1',
+    )
+    .trim() || null;
+}
+
+export function getCodeLanguageLabel(language) {
+  return LANGUAGE_LABELS[language] ?? language;
+}
+
+function withUnframedCodeWindow(meta) {
+  return [stripCodeLanguage(meta), 'frame="none"'].filter(Boolean).join(' ');
+}
+
+function renderGroupStart(groupId, languages) {
+  const firstLanguage = languages[0];
+  const tabs = languages
+    .map((language, index) => {
+      const active = index === 0;
+      const activeClass = active ? ' active' : '';
+      const tabIndex = active ? '' : ' tabindex="-1"';
+
+      return `<button class="tab${activeClass}" id="${groupId}-${language}-tab" type="button" role="tab" aria-selected="${active}" aria-controls="${groupId}-${language}-panel"${tabIndex} data-index="${language}" data-code-language="${language}">${LANGUAGE_LABELS[language]}</button>`;
+    })
+    .join('\n');
+
+  return `<div class="language-code-group not-content" data-language-code-group>
+<div class="language-code-terminal">
+<div class="terminal-bar">
+<div class="dots" aria-hidden="true">
+<span class="dot dot-red"></span>
+<span class="dot dot-yellow"></span>
+<span class="dot dot-green"></span>
+</div>
+<div class="tabs" role="tablist" aria-label="Code language" data-language-count="${languages.length}">
+${tabs}
+</div>
+</div>
+<div class="language-code-panel command active" id="${groupId}-${firstLanguage}-panel" role="tabpanel" aria-labelledby="${groupId}-${firstLanguage}-tab" data-index="${firstLanguage}" data-language-code-panel="${firstLanguage}">`;
+}
+
+function renderPanelSwitch(groupId, language) {
+  return `</div>
+<div class="language-code-panel command" id="${groupId}-${language}-panel" role="tabpanel" aria-labelledby="${groupId}-${language}-tab" data-index="${language}" data-language-code-panel="${language}" hidden>`;
+}
diff --git a/scripts/check-generated-markdown.mjs b/scripts/check-generated-markdown.mjs
index a2037b9..8582737 100644
--- a/scripts/check-generated-markdown.mjs
+++ b/scripts/check-generated-markdown.mjs
@@ -3,6 +3,7 @@ import { extname, join } from 'node:path';
 
 const DEST = 'dist';
 const UNEXPANDED_SNIPPET = /(?:^|\s)snippet="[^"]+"/;
+const UNEXPANDED_CODE_LANGUAGE = /(?:^|\s)code-language="[^"]+"/;
 
 function walkDir(dir) {
   const files = [];
@@ -17,11 +18,14 @@ function walkDir(dir) {
   return files;
 }
 
-const failures = walkDir(DEST).filter((file) => UNEXPANDED_SNIPPET.test(readFileSync(file, 'utf-8')));
+const failures = walkDir(DEST).filter((file) => {
+  const content = readFileSync(file, 'utf-8');
+  return UNEXPANDED_SNIPPET.test(content) || UNEXPANDED_CODE_LANGUAGE.test(content);
+});
 
 if (failures.length > 0) {
-  console.error(`Unexpanded snippet references found in:\n${failures.join('\n')}`);
+  console.error(`Unexpanded generated Markdown metadata found in:\n${failures.join('\n')}`);
   process.exit(1);
 }
 
-console.log('Verified generated Markdown contains no unexpanded snippet references');
+console.log('Verified generated Markdown contains no unexpanded snippet or code-language metadata');
diff --git a/scripts/copy-md-sources.mjs b/scripts/copy-md-sources.mjs
index 30f5a02..3a0d4bb 100644
--- a/scripts/copy-md-sources.mjs
+++ b/scripts/copy-md-sources.mjs
@@ -14,6 +14,11 @@ import {
   loadSnippet,
   stripSnippetReference,
 } from '../plugins/snippet-loader.mjs';
+import {
+  getCodeLanguage,
+  getCodeLanguageLabel,
+  stripCodeLanguage,
+} from '../plugins/remark-language-code-groups.mjs';
 
 const SRC = 'src/content/docs';
 const DEST = 'dist';
@@ -62,18 +67,29 @@ function transformDocument(content) {
     }
 
     const reference = getSnippetReference(opening.info);
+    const codeLanguage = getCodeLanguage(opening.info);
+    const languageLabel = codeLanguage
+      ? `${opening.indent}**${getCodeLanguageLabel(codeLanguage)}:**`
+      : null;
+
     if (!reference) {
-      output.push(lines.slice(index, closingIndex + 1).join('\n'));
+      const info = stripCodeLanguage(opening.info) ?? '';
+      if (languageLabel) output.push(languageLabel);
+      output.push(
+        `${opening.indent}${opening.marker}${info}`,
+        ...lines.slice(index + 1, closingIndex + 1),
+      );
       index = closingIndex;
       continue;
     }
 
     const snippet = loadSnippet(reference);
     const marker = safeFenceMarker(opening.marker, snippet);
-    const info = stripSnippetReference(opening.info);
+    const info = stripCodeLanguage(stripSnippetReference(opening.info)) ?? '';
     const closingIndent = lines[closingIndex].match(/^[ \t]*/)[0];
     const snippetLines = snippet.split('\n').map((line) => `${opening.indent}${line}`);
 
+    if (languageLabel) output.push(languageLabel);
     output.push(`${opening.indent}${marker}${info}`, ...snippetLines, `${closingIndent}${marker}`);
     index = closingIndex;
   }
diff --git a/src/components/Head.astro b/src/components/Head.astro
index 6fa7fc8..748a017 100644
--- a/src/components/Head.astro
+++ b/src/components/Head.astro
@@ -1,5 +1,6 @@
 ---
 import Default from '@astrojs/starlight/components/Head.astro';
+import LanguageCodeSync from './LanguageCodeSync.astro';
 
 // Emit a per-page og:image. Every docs page gets a generated card at
 // /og/<slug>.png (page title as subtitle); the homepage falls back to the
@@ -14,3 +15,4 @@ const ogImage = new URL(ogPath, Astro.site).href;
 <Default><slot /></Default>
 <meta property="og:image" content={ogImage} />
 <meta name="twitter:image" content={ogImage} />
+<LanguageCodeSync />
diff --git a/src/components/LanguageCodeSync.astro b/src/components/LanguageCodeSync.astro
new file mode 100644
index 0000000..1539f84
--- /dev/null
+++ b/src/components/LanguageCodeSync.astro
@@ -0,0 +1,168 @@
+<script>
+  type CodeLanguage = "javascript" | "react-native" | "rust";
+  type ViewportAnchor = {
+    element: HTMLElement;
+    top: number;
+  };
+
+  const storageKey = "pubky-code-language";
+  const languageParameter = "lang";
+  let pendingViewportAnchor: ViewportAnchor | null = null;
+  let pendingViewportFrame: number | null = null;
+
+  function isCodeLanguage(language: string | undefined | null): language is CodeLanguage {
+    return language === "javascript" || language === "react-native" || language === "rust";
+  }
+
+  function getSavedLanguage(): CodeLanguage | null {
+    try {
+      const language = sessionStorage.getItem(storageKey);
+      return isCodeLanguage(language) ? language : null;
+    } catch {
+      return null;
+    }
+  }
+
+  function getUrlLanguage(): CodeLanguage | null {
+    const language = new URL(window.location.href).searchParams.get(languageParameter);
+    return isCodeLanguage(language) ? language : null;
+  }
+
+  function saveLanguage(language: CodeLanguage): void {
+    try {
+      sessionStorage.setItem(storageKey, language);
+    } catch {
+      // The switcher still works when storage is unavailable.
+    }
+  }
+
+  function writeUrlLanguage(language: CodeLanguage): void {
+    const url = new URL(window.location.href);
+    if (url.searchParams.get(languageParameter) === language) return;
+
+    url.searchParams.set(languageParameter, language);
+    window.history.replaceState(window.history.state, "", url);
+  }
+
+  function restoreViewportAnchor(): void {
+    const anchor = pendingViewportAnchor;
+    pendingViewportAnchor = null;
+    pendingViewportFrame = null;
+
+    if (!anchor?.element.isConnected) return;
+
+    const offset = anchor.element.getBoundingClientRect().top - anchor.top;
+    if (offset !== 0) {
+      window.scrollBy({ top: offset, left: 0, behavior: "auto" });
+    }
+  }
+
+  function scheduleViewportAnchor(element: HTMLElement, top: number): void {
+    pendingViewportAnchor = { element, top };
+    pendingViewportFrame = requestAnimationFrame(restoreViewportAnchor);
+  }
+
+  function selectLanguage(
+    language: CodeLanguage,
+    persist = true,
+    anchor?: HTMLElement,
+  ): void {
+    if (pendingViewportFrame !== null) {
+      cancelAnimationFrame(pendingViewportFrame);
+      restoreViewportAnchor();
+    }
+
+    const anchorTop = anchor?.getBoundingClientRect().top;
+
+    document.querySelectorAll<HTMLElement>(".language-code-group").forEach((block) => {
+      const tabs = block.querySelectorAll<HTMLButtonElement>(".tab");
+      const commands = block.querySelectorAll<HTMLElement>(".command");
+      const selectedLanguage = Array.from(commands).some(
+        (command) => command.dataset.index === language,
+      )
+        ? language
+        : "javascript";
+
+      tabs.forEach((tab) => {
+        const selected = tab.dataset.index === selectedLanguage;
+        tab.classList.toggle("active", selected);
+        tab.setAttribute("aria-selected", String(selected));
+        tab.tabIndex = selected ? 0 : -1;
+      });
+
+      commands.forEach((command) => {
+        const selected = command.dataset.index === selectedLanguage;
+        command.classList.toggle("active", selected);
+        command.hidden = !selected;
+      });
+    });
+
+    if (anchor && anchorTop !== undefined) scheduleViewportAnchor(anchor, anchorTop);
+    if (persist) {
+      saveLanguage(language);
+      writeUrlLanguage(language);
+    }
+  }
+
+  function bindLanguageBlock(block: HTMLElement): void {
+    if (block.dataset.codeLanguageReady === "true") return;
+    block.dataset.codeLanguageReady = "true";
+
+    const tabs = Array.from(block.querySelectorAll<HTMLButtonElement>(".tab"));
+    tabs.forEach((tab, tabIndex) => {
+      tab.addEventListener("click", () => {
+        const language = tab.dataset.index;
+        if (isCodeLanguage(language)) selectLanguage(language, true, block);
+      });
+
+      tab.addEventListener("keydown", (event) => {
+        if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) return;
+
+        event.preventDefault();
+        const nextIndex =
+          event.key === "Home"
+            ? 0
+            : event.key === "End"
+              ? tabs.length - 1
+              : event.key === "ArrowLeft"
+                ? (tabIndex - 1 + tabs.length) % tabs.length
+                : (tabIndex + 1) % tabs.length;
+        const nextTab = tabs[nextIndex];
+        const language = nextTab?.dataset.index;
+        if (!nextTab || !isCodeLanguage(language)) return;
+
+        selectLanguage(language, true, block);
+        nextTab.focus({ preventScroll: true });
+      });
+    });
+  }
+
+  function setupLanguageCodeSwitchers(): void {
+    const blocks = document.querySelectorAll<HTMLElement>(".language-code-group");
+    blocks.forEach(bindLanguageBlock);
+
+    if (blocks.length > 0) {
+      const language = getUrlLanguage() ?? getSavedLanguage() ?? "javascript";
+      selectLanguage(language, false);
+      saveLanguage(language);
+      writeUrlLanguage(language);
+    }
+  }
+
+  function syncLanguageFromUrl(): void {
+    const blocks = document.querySelectorAll<HTMLElement>(".language-code-group");
+    if (blocks.length === 0) return;
+
+    const language = getUrlLanguage() ?? "javascript";
+    selectLanguage(language, false);
+    saveLanguage(language);
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", setupLanguageCodeSwitchers, { once: true });
+  } else {
+    setupLanguageCodeSwitchers();
+  }
+  document.addEventListener("astro:page-load", setupLanguageCodeSwitchers);
+  window.addEventListener("popstate", syncLanguageFromUrl);
+</script>
diff --git a/src/styles/custom.css b/src/styles/custom.css
index 76bf184..d9a674e 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -34,6 +34,7 @@
 	--spacing-1: 4px;
 	--spacing-2: 8px;
 	--spacing-2-5: 10px; /* Figma half-step between spacing-2(8) and spacing-3(12) */
+	--spacing-window-controls: 11px;
 	--spacing-3: 12px;
 	--spacing-4: 16px;
 	--spacing-5: 20px;
@@ -45,6 +46,7 @@
 	--spacing-20: 80px;
 
 	/* Border radius */
+	--radius-none: 0;
 	--radius-sm: 6px;
 	--radius-md: 8px;
 	--radius-lg: 12px;
@@ -85,7 +87,16 @@
 	--alpha-white-16: rgba(255, 255, 255, 0.16);
 	--alpha-white-10: rgba(255, 255, 255, 0.1);
 	--alpha-white-5: rgba(255, 255, 255, 0.045);
+	--terminal-tab-hover: rgba(255, 255, 255, 0.05);
 	--base-secondary-hover: #3a3a3f;
+	--window-control-red: #ff5f57;
+	--window-control-yellow: #febc2e;
+	--window-control-green: #28c840;
+
+	/* Component dimensions */
+	--window-control-size: 9px;
+	--code-switcher-width: 200px;
+	--code-switcher-height: 48px;
 
 	/* Shadows */
 	--shadow-xs: 0 1px 2px rgba(5, 5, 10, 0.2);
@@ -215,6 +226,120 @@ site-search button[data-open-modal] kbd {
 	outline-offset: 2px;
 }
 
+/* Language code windows copy the landing install terminal's exact
+   terminal-bar, dots, tabs, and tab trigger styling. */
+.language-code-group {
+	margin-block: var(--spacing-4);
+}
+
+.language-code-terminal {
+	overflow: hidden;
+	border: 1px solid var(--base-border);
+	border-radius: var(--radius-xl);
+	background: var(--base-background);
+	display: flex;
+	flex-direction: column;
+}
+
+.language-code-group .terminal-bar {
+	display: flex;
+	flex-wrap: wrap;
+	align-items: center;
+	gap: var(--spacing-window-controls);
+	padding: var(--spacing-2) var(--spacing-4);
+	background: var(--base-card);
+}
+
+.language-code-group .dots {
+	display: flex;
+	gap: var(--spacing-window-controls);
+}
+
+.language-code-group .dot {
+	width: var(--window-control-size);
+	height: var(--window-control-size);
+	border-radius: var(--radius-full);
+}
+
+.language-code-group .dot-red {
+	background: var(--window-control-red);
+}
+
+.language-code-group .dot-yellow {
+	background: var(--window-control-yellow);
+}
+
+.language-code-group .dot-green {
+	background: var(--window-control-green);
+}
+
+.language-code-group .tabs {
+	display: flex;
+	align-items: center;
+	width: var(--code-switcher-width);
+	height: var(--code-switcher-height);
+	padding: var(--spacing-2);
+	gap: var(--spacing-2);
+	border-radius: var(--radius-md);
+}
+
+.language-code-group .tabs[data-language-count="3"] {
+	width: max-content;
+	flex-shrink: 0;
+}
+
+.language-code-group .tabs[data-language-count="3"] .tab {
+	white-space: nowrap;
+}
+
+.language-code-group .tab {
+	flex: 1;
+	background: transparent;
+	border: none;
+	color: var(--base-secondary-foreground);
+	font-family: var(--sl-font);
+	font-size: var(--text-xs-size);
+	font-weight: 700;
+	line-height: var(--text-xs-lh);
+	padding: var(--spacing-2);
+	border-radius: var(--radius-md);
+	cursor: pointer;
+	transition: all 0.15s ease;
+	text-align: center;
+}
+
+.language-code-group .tab:hover {
+	color: var(--base-foreground);
+	background: var(--terminal-tab-hover);
+}
+
+.language-code-group .tab.active {
+	color: var(--base-foreground);
+	background: var(--base-muted);
+	box-shadow: var(--shadow-sm);
+}
+
+.language-code-group .command {
+	display: none;
+}
+
+.language-code-group .command.active {
+	display: block;
+}
+
+.language-code-panel > .expressive-code {
+	margin: 0;
+}
+
+.language-code-panel > .expressive-code .frame {
+	--code-background: var(--base-background);
+}
+
+.language-code-panel > .expressive-code pre {
+	border: none;
+	border-radius: var(--radius-none);
+}
+
 /* Shrink FAQ per-question headings */
 .faq h3 {
 	font-size: var(--text-xl-size);

From caeec88f1220ef84e9ac4b727b3746cb170c58e5 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Fri, 14 Aug 2026 14:08:50 +0100
Subject: [PATCH 2/3] fix: Rebase sdk.md and apply language picker

---
 src/content/docs/explore/pubky-protocol/sdk.md | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/src/content/docs/explore/pubky-protocol/sdk.md b/src/content/docs/explore/pubky-protocol/sdk.md
index 6ab1002..bf69594 100644
--- a/src/content/docs/explore/pubky-protocol/sdk.md
+++ b/src/content/docs/explore/pubky-protocol/sdk.md
@@ -48,12 +48,9 @@ For event-driven apps, **EventStreamBuilder** lets you subscribe to real-time ch
 
 Sign in and read/write data. Account creation (signup) is generally handled outside of your app. See the [Developer Guide](/explore/pubkycore/getting-started/) for testnet setup where you bootstrap accounts for development.
 
-**Rust:**
-```rust snippet="snippets/rust/src/lib.rs:rust_quick_example"
+```js snippet="snippets/js/src/sdk.ts:js_quick_example" code-language="javascript"
 ```
-
-**JavaScript:**
-```javascript snippet="snippets/js/src/sdk.ts:js_quick_example"
+```rust snippet="snippets/rust/src/lib.rs:rust_quick_example" code-language="rust"
 ```
 
 ## Resources

From 7c926d5a493a219ccfef039168f52249bffb72e0 Mon Sep 17 00:00:00 2001
From: tomos <tomos@synonym.to>
Date: Fri, 14 Aug 2026 15:18:53 +0100
Subject: [PATCH 3/3] feat: User Starlight's built-in Tabs feature in favour of
 own implementation

---
 astro.config.mjs                              |   3 +-
 plugins/remark-language-code-groups.mjs       | 174 -----------------
 scripts/check-generated-markdown.mjs          |  10 +-
 scripts/copy-md-sources.mjs                   |  20 +-
 src/components/Head.astro                     |   2 -
 src/components/InstallBlock.astro             | 176 +++---------------
 src/components/LanguageCodeSync.astro         | 168 -----------------
 src/components/TabUrlSync.astro               | 104 +++++++++++
 .../pubky-protocol/{sdk.md => sdk.mdx}        |  21 ++-
 src/styles/custom.css                         | 117 +++---------
 10 files changed, 189 insertions(+), 606 deletions(-)
 delete mode 100644 plugins/remark-language-code-groups.mjs
 delete mode 100644 src/components/LanguageCodeSync.astro
 create mode 100644 src/components/TabUrlSync.astro
 rename src/content/docs/explore/pubky-protocol/{sdk.md => sdk.mdx} (88%)

diff --git a/astro.config.mjs b/astro.config.mjs
index d5afc2b..5a2ee6e 100644
--- a/astro.config.mjs
+++ b/astro.config.mjs
@@ -5,7 +5,6 @@ import starlightClientMermaid from '@pasqal-io/starlight-client-mermaid';
 import starlightLlmsTxt from 'starlight-llms-txt';
 import rehypeBasePath from './plugins/rehype-base-path.mjs';
 import remarkSnippet from './plugins/remark-snippet.mjs';
-import remarkLanguageCodeGroups from './plugins/remark-language-code-groups.mjs';
 
 // https://astro.build/config
 export default defineConfig({
@@ -74,7 +73,7 @@ export default defineConfig({
 	},
 	base: process.env.BASE_PATH || '/',
 	markdown: {
-		remarkPlugins: [remarkSnippet, remarkLanguageCodeGroups],
+		remarkPlugins: [remarkSnippet],
 		rehypePlugins: [[rehypeBasePath, { base: process.env.BASE_PATH || '/' }]],
 	},
 	integrations: [
diff --git a/plugins/remark-language-code-groups.mjs b/plugins/remark-language-code-groups.mjs
deleted file mode 100644
index 105f708..0000000
--- a/plugins/remark-language-code-groups.mjs
+++ /dev/null
@@ -1,174 +0,0 @@
-const CODE_LANGUAGE_META =
-  /(?:^|\s)code-language="(javascript|react-native|rust)"/;
-
-const LANGUAGE_LABELS = {
-  javascript: 'JavaScript',
-  'react-native': 'React Native',
-  rust: 'Rust',
-};
-
-const LANGUAGE_ORDER = ['javascript', 'react-native', 'rust'];
-
-/**
- * Turn consecutive language-specific code fences into an accessible,
- * synchronized language group. Every group has JavaScript and Rust, while
- * individual groups may also offer React Native.
- *
- * Usage:
- *
- *   ```js code-language="javascript"
- *   ```
- *   ```js code-language="react-native"
- *   ```
- *   ```rust code-language="rust"
- *   ```
- */
-export default function remarkLanguageCodeGroups() {
-  return (tree) => {
-    let groupIndex = 0;
-
-    walk(tree, () => {
-      groupIndex += 1;
-      return groupIndex;
-    });
-  };
-}
-
-function walk(parent, nextGroupIndex) {
-  if (!Array.isArray(parent.children)) return;
-
-  for (let index = 0; index < parent.children.length; index += 1) {
-    const first = getLanguageCode(parent.children[index]);
-    if (!first) {
-      walk(parent.children[index], nextGroupIndex);
-      continue;
-    }
-
-    const groupedCodes = [];
-    for (let cursor = index; cursor < parent.children.length; cursor += 1) {
-      const code = getLanguageCode(parent.children[cursor]);
-      if (!code) break;
-      groupedCodes.push(code);
-    }
-
-    if (groupedCodes.length < 2) {
-      throw new Error(
-        `language code group: ${first.language} block must be followed by its paired language block`,
-      );
-    }
-
-    const blocks = new Map();
-    for (const code of groupedCodes) {
-      if (blocks.has(code.language)) {
-        throw new Error(
-          `language code group: duplicate ${code.language} block`,
-        );
-      }
-      blocks.set(code.language, code.node);
-    }
-
-    if (!blocks.has('javascript') || !blocks.has('rust')) {
-      throw new Error(
-        'language code group: each group must contain one JavaScript block and one Rust block',
-      );
-    }
-
-    const groupId = `language-code-${nextGroupIndex()}`;
-    const languages = LANGUAGE_ORDER.filter((language) => blocks.has(language));
-    for (const language of languages) {
-      const block = blocks.get(language);
-      block.meta = withUnframedCodeWindow(block.meta);
-    }
-
-    const replacement = [
-      {
-        type: 'html',
-        value: renderGroupStart(groupId, languages),
-      },
-      blocks.get(languages[0]),
-    ];
-
-    for (const language of languages.slice(1)) {
-      replacement.push(
-        {
-          type: 'html',
-          value: renderPanelSwitch(groupId, language),
-        },
-        blocks.get(language),
-      );
-    }
-    replacement.push({
-      type: 'html',
-      value: '</div>\n</div>\n</div>',
-    });
-
-    parent.children.splice(index, groupedCodes.length, ...replacement);
-
-    index += replacement.length - 1;
-  }
-}
-
-function getLanguageCode(node) {
-  if (node?.type !== 'code' || !node.meta) return null;
-
-  const language = getCodeLanguage(node.meta);
-  if (!language) return null;
-
-  return {
-    language,
-    node,
-  };
-}
-
-export function getCodeLanguage(meta) {
-  return meta?.match(CODE_LANGUAGE_META)?.[1] ?? null;
-}
-
-export function stripCodeLanguage(meta) {
-  return meta
-    .replace(
-      /(^|\s+)code-language="(?:javascript|react-native|rust)"/,
-      '$1',
-    )
-    .trim() || null;
-}
-
-export function getCodeLanguageLabel(language) {
-  return LANGUAGE_LABELS[language] ?? language;
-}
-
-function withUnframedCodeWindow(meta) {
-  return [stripCodeLanguage(meta), 'frame="none"'].filter(Boolean).join(' ');
-}
-
-function renderGroupStart(groupId, languages) {
-  const firstLanguage = languages[0];
-  const tabs = languages
-    .map((language, index) => {
-      const active = index === 0;
-      const activeClass = active ? ' active' : '';
-      const tabIndex = active ? '' : ' tabindex="-1"';
-
-      return `<button class="tab${activeClass}" id="${groupId}-${language}-tab" type="button" role="tab" aria-selected="${active}" aria-controls="${groupId}-${language}-panel"${tabIndex} data-index="${language}" data-code-language="${language}">${LANGUAGE_LABELS[language]}</button>`;
-    })
-    .join('\n');
-
-  return `<div class="language-code-group not-content" data-language-code-group>
-<div class="language-code-terminal">
-<div class="terminal-bar">
-<div class="dots" aria-hidden="true">
-<span class="dot dot-red"></span>
-<span class="dot dot-yellow"></span>
-<span class="dot dot-green"></span>
-</div>
-<div class="tabs" role="tablist" aria-label="Code language" data-language-count="${languages.length}">
-${tabs}
-</div>
-</div>
-<div class="language-code-panel command active" id="${groupId}-${firstLanguage}-panel" role="tabpanel" aria-labelledby="${groupId}-${firstLanguage}-tab" data-index="${firstLanguage}" data-language-code-panel="${firstLanguage}">`;
-}
-
-function renderPanelSwitch(groupId, language) {
-  return `</div>
-<div class="language-code-panel command" id="${groupId}-${language}-panel" role="tabpanel" aria-labelledby="${groupId}-${language}-tab" data-index="${language}" data-language-code-panel="${language}" hidden>`;
-}
diff --git a/scripts/check-generated-markdown.mjs b/scripts/check-generated-markdown.mjs
index 8582737..a2037b9 100644
--- a/scripts/check-generated-markdown.mjs
+++ b/scripts/check-generated-markdown.mjs
@@ -3,7 +3,6 @@ import { extname, join } from 'node:path';
 
 const DEST = 'dist';
 const UNEXPANDED_SNIPPET = /(?:^|\s)snippet="[^"]+"/;
-const UNEXPANDED_CODE_LANGUAGE = /(?:^|\s)code-language="[^"]+"/;
 
 function walkDir(dir) {
   const files = [];
@@ -18,14 +17,11 @@ function walkDir(dir) {
   return files;
 }
 
-const failures = walkDir(DEST).filter((file) => {
-  const content = readFileSync(file, 'utf-8');
-  return UNEXPANDED_SNIPPET.test(content) || UNEXPANDED_CODE_LANGUAGE.test(content);
-});
+const failures = walkDir(DEST).filter((file) => UNEXPANDED_SNIPPET.test(readFileSync(file, 'utf-8')));
 
 if (failures.length > 0) {
-  console.error(`Unexpanded generated Markdown metadata found in:\n${failures.join('\n')}`);
+  console.error(`Unexpanded snippet references found in:\n${failures.join('\n')}`);
   process.exit(1);
 }
 
-console.log('Verified generated Markdown contains no unexpanded snippet or code-language metadata');
+console.log('Verified generated Markdown contains no unexpanded snippet references');
diff --git a/scripts/copy-md-sources.mjs b/scripts/copy-md-sources.mjs
index 3a0d4bb..30f5a02 100644
--- a/scripts/copy-md-sources.mjs
+++ b/scripts/copy-md-sources.mjs
@@ -14,11 +14,6 @@ import {
   loadSnippet,
   stripSnippetReference,
 } from '../plugins/snippet-loader.mjs';
-import {
-  getCodeLanguage,
-  getCodeLanguageLabel,
-  stripCodeLanguage,
-} from '../plugins/remark-language-code-groups.mjs';
 
 const SRC = 'src/content/docs';
 const DEST = 'dist';
@@ -67,29 +62,18 @@ function transformDocument(content) {
     }
 
     const reference = getSnippetReference(opening.info);
-    const codeLanguage = getCodeLanguage(opening.info);
-    const languageLabel = codeLanguage
-      ? `${opening.indent}**${getCodeLanguageLabel(codeLanguage)}:**`
-      : null;
-
     if (!reference) {
-      const info = stripCodeLanguage(opening.info) ?? '';
-      if (languageLabel) output.push(languageLabel);
-      output.push(
-        `${opening.indent}${opening.marker}${info}`,
-        ...lines.slice(index + 1, closingIndex + 1),
-      );
+      output.push(lines.slice(index, closingIndex + 1).join('\n'));
       index = closingIndex;
       continue;
     }
 
     const snippet = loadSnippet(reference);
     const marker = safeFenceMarker(opening.marker, snippet);
-    const info = stripCodeLanguage(stripSnippetReference(opening.info)) ?? '';
+    const info = stripSnippetReference(opening.info);
     const closingIndent = lines[closingIndex].match(/^[ \t]*/)[0];
     const snippetLines = snippet.split('\n').map((line) => `${opening.indent}${line}`);
 
-    if (languageLabel) output.push(languageLabel);
     output.push(`${opening.indent}${marker}${info}`, ...snippetLines, `${closingIndent}${marker}`);
     index = closingIndex;
   }
diff --git a/src/components/Head.astro b/src/components/Head.astro
index 748a017..6fa7fc8 100644
--- a/src/components/Head.astro
+++ b/src/components/Head.astro
@@ -1,6 +1,5 @@
 ---
 import Default from '@astrojs/starlight/components/Head.astro';
-import LanguageCodeSync from './LanguageCodeSync.astro';
 
 // Emit a per-page og:image. Every docs page gets a generated card at
 // /og/<slug>.png (page title as subtitle); the homepage falls back to the
@@ -15,4 +14,3 @@ const ogImage = new URL(ogPath, Astro.site).href;
 <Default><slot /></Default>
 <meta property="og:image" content={ogImage} />
 <meta name="twitter:image" content={ogImage} />
-<LanguageCodeSync />
diff --git a/src/components/InstallBlock.astro b/src/components/InstallBlock.astro
index 467cc9d..e372a0b 100644
--- a/src/components/InstallBlock.astro
+++ b/src/components/InstallBlock.astro
@@ -1,5 +1,6 @@
 ---
 import { withBase } from '../utils/base-path';
+import { Tabs, TabItem } from '@astrojs/starlight/components';
 
 const commands = [
   { label: "npm", command: "npm install @synonymdev/pubky" },
@@ -75,43 +76,26 @@ const installSectionBg = `--install-section-bg: url("${withBase('/images/bg-squa
   </div>
 
   <div class="install-right not-content">
-    <div class="terminal not-content">
-      <div class="terminal-bar">
-        <div class="dots">
-          <span class="dot dot-red"></span>
-          <span class="dot dot-yellow"></span>
-          <span class="dot dot-green"></span>
-        </div>
-        <div class="tabs" role="tablist" aria-label="Package manager">
-          {commands.map((cmd, i) => (
-            <button
-              class:list={["tab", { active: i === 0 }]}
-              data-index={i}
-              role="tab"
-              aria-selected={i === 0 ? "true" : "false"}
-            >
-              {cmd.label}
-            </button>
-          ))}
-        </div>
-      </div>
-      <div class="terminal-body">
-        {commands.map((cmd, i) => (
-          <div class:list={["command", { active: i === 0 }]} data-index={i}>
-            <span class="prompt">$</span>
-            <span class="cmd-text">{cmd.command}</span>
-            <button class="copy-btn" data-command={cmd.command} aria-label="Copy to clipboard" aria-live="polite">
-              <svg class="copy-icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
-                <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
-                <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
-              </svg>
-              <svg class="check-icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
-                <polyline points="20 6 9 17 4 12"></polyline>
-              </svg>
-            </button>
-          </div>
+    <div class="install-terminal terminal-tabs">
+      <Tabs>
+        {commands.map((cmd) => (
+          <TabItem label={cmd.label}>
+            <div class="install-command">
+              <span class="prompt">$</span>
+              <span class="cmd-text">{cmd.command}</span>
+              <button class="copy-btn" data-command={cmd.command} aria-label="Copy to clipboard" aria-live="polite">
+                <svg class="copy-icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+                  <rect x="9" y="9" width="13" height="13" rx="2" ry="2"></rect>
+                  <path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"></path>
+                </svg>
+                <svg class="check-icon" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
+                  <polyline points="20 6 9 17 4 12"></polyline>
+                </svg>
+              </button>
+            </div>
+          </TabItem>
         ))}
-      </div>
+      </Tabs>
     </div>
   </div>
 </div>
@@ -119,24 +103,10 @@ const installSectionBg = `--install-section-bg: url("${withBase('/images/bg-squa
 
 <script>
   document.querySelectorAll('.install-block').forEach((block) => {
-    const tabs = block.querySelectorAll('.tab');
-    const commands = block.querySelectorAll('.command');
-
-    tabs.forEach((tab) => {
-      tab.addEventListener('click', () => {
-        const index = tab.getAttribute('data-index');
-        tabs.forEach((t) => { t.classList.remove('active'); t.setAttribute('aria-selected', 'false'); });
-        commands.forEach((c) => c.classList.remove('active'));
-        tab.classList.add('active');
-        tab.setAttribute('aria-selected', 'true');
-        block.querySelector(`.command[data-index="${index}"]`)?.classList.add('active');
-      });
-    });
-
     block.querySelectorAll('.copy-prompt-btn').forEach((btn) => {
       btn.addEventListener('click', () => {
         const prompt = btn.getAttribute('data-prompt') || '';
-        navigator.clipboard.writeText(prompt);
+        navigator.clipboard.writeText(prompt).catch(() => {});
         btn.classList.add('copied');
         btn.setAttribute('data-tooltip', 'Copied!');
         btn.setAttribute('aria-label', 'Copied!');
@@ -151,7 +121,7 @@ const installSectionBg = `--install-section-bg: url("${withBase('/images/bg-squa
     block.querySelectorAll('.copy-btn').forEach((btn) => {
       btn.addEventListener('click', () => {
         const command = btn.getAttribute('data-command') || '';
-        navigator.clipboard.writeText(command);
+        navigator.clipboard.writeText(command).catch(() => {});
         btn.classList.add('copied');
         btn.setAttribute('aria-label', 'Copied!');
         setTimeout(() => { btn.classList.remove('copied'); btn.setAttribute('aria-label', 'Copy to clipboard'); }, 1500);
@@ -518,108 +488,25 @@ const installSectionBg = `--install-section-bg: url("${withBase('/images/bg-squa
     height: 500px;
   }
 
-  /* ── Terminal ── */
-  /* Figma: 500x140, border 1px base/border, radius rounded-xl(16), bg base/background, overflow clip */
-  .terminal {
+  /* ── Install terminal (Starlight Tabs) ── */
+  /* Figma: 500x140 terminal */
+  .install-terminal {
     width: 500px;
-    height: 140px;
-    border: 1px solid var(--base-border);
-    border-radius: var(--radius-xl);
-    overflow: hidden;
-    background: var(--base-background);
-    display: flex;
-    flex-direction: column;
-  }
-
-  /* Figma: Dots bar = px spacing-4(16), py 8, bg base/card(#1d1d20), gap 11.
-     11px is hardcoded — Figma-specific value, doesn't fit 4px spacing scale */
-  .terminal-bar {
-    display: flex;
-    align-items: center;
-    gap: 11px;
-    padding: var(--spacing-2) var(--spacing-4);
-    background: var(--base-card);
-  }
-
-  /* Figma: dots = 9px, gap 11px (same oddball spacing as terminal-bar) */
-  .dots {
-    display: flex;
-    gap: 11px;
-  }
-
-  .dot {
-    width: 9px;
-    height: 9px;
-    border-radius: 50%;
-  }
-
-  .dot-red { background: #ff5f57; }
-  .dot-yellow { background: #febc2e; }
-  .dot-green { background: #28c840; }
-
-  /* Figma: Tabs = w 200, h 48, p spacing-2(8), gap spacing-2(8), radius rounded-md(8) */
-  .tabs {
-    display: flex;
-    align-items: center;
-    width: 200px;
-    height: 48px;
-    padding: var(--spacing-2);
-    gap: var(--spacing-2);
-    border-radius: var(--radius-md);
   }
 
-  /* Figma: Tab trigger = flex-1, p spacing-2(8), radius rounded-md(8), text-xs(12/16) bold */
-  .tab {
-    flex: 1;
-    background: transparent;
-    border: none;
-    color: var(--base-secondary-foreground);
-    font-family: var(--sl-font);
-    font-size: var(--text-xs-size);
-    font-weight: 700;
-    line-height: var(--text-xs-lh);
-    padding: var(--spacing-2);
-    border-radius: var(--radius-md);
-    cursor: pointer;
-    transition: all 0.15s ease;
-    text-align: center;
-  }
-
-  .tab:hover {
-    color: var(--base-foreground);
-    background: rgba(255, 255, 255, 0.05);
-  }
-
-  /* Figma: Active tab = bg base/muted(#303034), text foreground, shadow sm */
-  .tab.active {
-    color: var(--base-foreground);
-    background: var(--base-muted);
-    box-shadow: var(--shadow-sm);
-  }
-
-  /* Figma: Terminal body = flex-1, p spacing-4(16), gap spacing-4(16), items center */
-  .terminal-body {
-    display: flex;
-    flex: 1;
-    align-items: center;
-    gap: var(--spacing-4);
+  .install-terminal starlight-tabs > [role="tabpanel"] {
     padding: var(--spacing-4);
   }
 
-  /* Figma: Large typography = text-lg(18/28) semibold, items-center inherited from .terminal-body */
-  .command {
-    display: none;
+  /* Figma: Large typography = text-lg(18/28) semibold */
+  .install-command {
+    display: flex;
     align-items: center;
     gap: var(--spacing-4);
     font-family: var(--sl-font);
     font-size: var(--text-lg-size);
     font-weight: 600;
     line-height: var(--text-lg-lh);
-    width: 100%;
-  }
-
-  .command.active {
-    display: flex;
   }
 
   /* Figma: $ prompt = muted-foreground */
@@ -762,12 +649,11 @@ const installSectionBg = `--install-section-bg: url("${withBase('/images/bg-squa
       display: none;
     }
 
-    .terminal {
+    .install-terminal {
       width: 100%;
-      height: auto;
     }
 
-    .command {
+    .install-command {
       font-size: var(--text-sm-size);
       line-height: var(--text-sm-lh);
     }
diff --git a/src/components/LanguageCodeSync.astro b/src/components/LanguageCodeSync.astro
deleted file mode 100644
index 1539f84..0000000
--- a/src/components/LanguageCodeSync.astro
+++ /dev/null
@@ -1,168 +0,0 @@
-<script>
-  type CodeLanguage = "javascript" | "react-native" | "rust";
-  type ViewportAnchor = {
-    element: HTMLElement;
-    top: number;
-  };
-
-  const storageKey = "pubky-code-language";
-  const languageParameter = "lang";
-  let pendingViewportAnchor: ViewportAnchor | null = null;
-  let pendingViewportFrame: number | null = null;
-
-  function isCodeLanguage(language: string | undefined | null): language is CodeLanguage {
-    return language === "javascript" || language === "react-native" || language === "rust";
-  }
-
-  function getSavedLanguage(): CodeLanguage | null {
-    try {
-      const language = sessionStorage.getItem(storageKey);
-      return isCodeLanguage(language) ? language : null;
-    } catch {
-      return null;
-    }
-  }
-
-  function getUrlLanguage(): CodeLanguage | null {
-    const language = new URL(window.location.href).searchParams.get(languageParameter);
-    return isCodeLanguage(language) ? language : null;
-  }
-
-  function saveLanguage(language: CodeLanguage): void {
-    try {
-      sessionStorage.setItem(storageKey, language);
-    } catch {
-      // The switcher still works when storage is unavailable.
-    }
-  }
-
-  function writeUrlLanguage(language: CodeLanguage): void {
-    const url = new URL(window.location.href);
-    if (url.searchParams.get(languageParameter) === language) return;
-
-    url.searchParams.set(languageParameter, language);
-    window.history.replaceState(window.history.state, "", url);
-  }
-
-  function restoreViewportAnchor(): void {
-    const anchor = pendingViewportAnchor;
-    pendingViewportAnchor = null;
-    pendingViewportFrame = null;
-
-    if (!anchor?.element.isConnected) return;
-
-    const offset = anchor.element.getBoundingClientRect().top - anchor.top;
-    if (offset !== 0) {
-      window.scrollBy({ top: offset, left: 0, behavior: "auto" });
-    }
-  }
-
-  function scheduleViewportAnchor(element: HTMLElement, top: number): void {
-    pendingViewportAnchor = { element, top };
-    pendingViewportFrame = requestAnimationFrame(restoreViewportAnchor);
-  }
-
-  function selectLanguage(
-    language: CodeLanguage,
-    persist = true,
-    anchor?: HTMLElement,
-  ): void {
-    if (pendingViewportFrame !== null) {
-      cancelAnimationFrame(pendingViewportFrame);
-      restoreViewportAnchor();
-    }
-
-    const anchorTop = anchor?.getBoundingClientRect().top;
-
-    document.querySelectorAll<HTMLElement>(".language-code-group").forEach((block) => {
-      const tabs = block.querySelectorAll<HTMLButtonElement>(".tab");
-      const commands = block.querySelectorAll<HTMLElement>(".command");
-      const selectedLanguage = Array.from(commands).some(
-        (command) => command.dataset.index === language,
-      )
-        ? language
-        : "javascript";
-
-      tabs.forEach((tab) => {
-        const selected = tab.dataset.index === selectedLanguage;
-        tab.classList.toggle("active", selected);
-        tab.setAttribute("aria-selected", String(selected));
-        tab.tabIndex = selected ? 0 : -1;
-      });
-
-      commands.forEach((command) => {
-        const selected = command.dataset.index === selectedLanguage;
-        command.classList.toggle("active", selected);
-        command.hidden = !selected;
-      });
-    });
-
-    if (anchor && anchorTop !== undefined) scheduleViewportAnchor(anchor, anchorTop);
-    if (persist) {
-      saveLanguage(language);
-      writeUrlLanguage(language);
-    }
-  }
-
-  function bindLanguageBlock(block: HTMLElement): void {
-    if (block.dataset.codeLanguageReady === "true") return;
-    block.dataset.codeLanguageReady = "true";
-
-    const tabs = Array.from(block.querySelectorAll<HTMLButtonElement>(".tab"));
-    tabs.forEach((tab, tabIndex) => {
-      tab.addEventListener("click", () => {
-        const language = tab.dataset.index;
-        if (isCodeLanguage(language)) selectLanguage(language, true, block);
-      });
-
-      tab.addEventListener("keydown", (event) => {
-        if (!["ArrowLeft", "ArrowRight", "Home", "End"].includes(event.key)) return;
-
-        event.preventDefault();
-        const nextIndex =
-          event.key === "Home"
-            ? 0
-            : event.key === "End"
-              ? tabs.length - 1
-              : event.key === "ArrowLeft"
-                ? (tabIndex - 1 + tabs.length) % tabs.length
-                : (tabIndex + 1) % tabs.length;
-        const nextTab = tabs[nextIndex];
-        const language = nextTab?.dataset.index;
-        if (!nextTab || !isCodeLanguage(language)) return;
-
-        selectLanguage(language, true, block);
-        nextTab.focus({ preventScroll: true });
-      });
-    });
-  }
-
-  function setupLanguageCodeSwitchers(): void {
-    const blocks = document.querySelectorAll<HTMLElement>(".language-code-group");
-    blocks.forEach(bindLanguageBlock);
-
-    if (blocks.length > 0) {
-      const language = getUrlLanguage() ?? getSavedLanguage() ?? "javascript";
-      selectLanguage(language, false);
-      saveLanguage(language);
-      writeUrlLanguage(language);
-    }
-  }
-
-  function syncLanguageFromUrl(): void {
-    const blocks = document.querySelectorAll<HTMLElement>(".language-code-group");
-    if (blocks.length === 0) return;
-
-    const language = getUrlLanguage() ?? "javascript";
-    selectLanguage(language, false);
-    saveLanguage(language);
-  }
-
-  if (document.readyState === "loading") {
-    document.addEventListener("DOMContentLoaded", setupLanguageCodeSwitchers, { once: true });
-  } else {
-    setupLanguageCodeSwitchers();
-  }
-  document.addEventListener("astro:page-load", setupLanguageCodeSwitchers);
-  window.addEventListener("popstate", syncLanguageFromUrl);
-</script>
diff --git a/src/components/TabUrlSync.astro b/src/components/TabUrlSync.astro
new file mode 100644
index 0000000..a9ebcaa
--- /dev/null
+++ b/src/components/TabUrlSync.astro
@@ -0,0 +1,104 @@
+---
+/**
+ * Syncs Starlight `<Tabs syncKey>` selection with a URL query parameter.
+ *
+ * Usage (in .mdx):
+ *   <TabUrlSync syncKey="sdk-lang" param="lang" />
+ *
+ * - On load: reads `?lang=…` and activates the matching tab.
+ * - On tab switch: updates the URL via `history.replaceState`.
+ */
+interface Props {
+  syncKey: string;
+  param: string;
+}
+
+const { syncKey, param } = Astro.props;
+---
+
+<tab-url-sync data-sync-key={syncKey} data-param={param}></tab-url-sync>
+
+<script>
+  // One instance per syncKey — avoids duplicate listeners when multiple
+  // <TabUrlSync> elements share the same key (e.g. via layout composition).
+  const activeSyncKeys = new Set<string>();
+
+  class TabUrlSync extends HTMLElement {
+    #syncKey: string;
+    #param: string;
+
+    constructor() {
+      super();
+      this.#syncKey = this.dataset.syncKey ?? "";
+      this.#param = this.dataset.param ?? "";
+    }
+
+    connectedCallback() {
+      if (activeSyncKeys.has(this.#syncKey)) return;
+      activeSyncKeys.add(this.#syncKey);
+
+      // Defer so Starlight's <starlight-tabs> has time to upgrade and
+      // attach its own click handlers before we programmatically click.
+      requestAnimationFrame(() => this.#applyUrlSelection());
+
+      // Global listener because the target <starlight-tabs> may not exist
+      // yet at connectedCallback time (custom-element upgrade order).
+      document.addEventListener("click", this.#handleTabClick);
+    }
+
+    disconnectedCallback() {
+      activeSyncKeys.delete(this.#syncKey);
+      document.removeEventListener("click", this.#handleTabClick);
+    }
+
+    #getTabs(): HTMLElement[] {
+      const container = document.querySelector(
+        `starlight-tabs[data-sync-key="${CSS.escape(this.#syncKey)}"]`,
+      );
+      if (!container) return [];
+      return [...container.querySelectorAll<HTMLElement>('[role="tab"]')];
+    }
+
+    // Normalises a tab label to a URL-safe param value.
+    // Collisions are possible (e.g. "C Sharp" vs "c-sharp") — keep
+    // tab labels distinct after lowercasing + whitespace replacement.
+    #labelToParam(label: string): string {
+      return label.toLowerCase().replace(/\s+/g, "-");
+    }
+
+    #applyUrlSelection = (): void => {
+      const value = new URL(window.location.href).searchParams.get(this.#param);
+      if (!value) return;
+
+      const tabs = this.#getTabs();
+      const match = tabs.find(
+        (tab) => this.#labelToParam(tab.textContent?.trim() ?? "") === value,
+      );
+      if (match && match.getAttribute("aria-selected") !== "true") {
+        match.click();
+      }
+    };
+
+    #handleTabClick = (event: Event): void => {
+      const tab = (event.target as Element)?.closest?.('[role="tab"]');
+      if (!tab) return;
+
+      const container = tab.closest("starlight-tabs");
+      if (container?.dataset.syncKey !== this.#syncKey) return;
+
+      const label = tab.textContent?.trim();
+      if (!label) return;
+
+      const url = new URL(window.location.href);
+      const paramValue = this.#labelToParam(label);
+      if (url.searchParams.get(this.#param) === paramValue) return;
+
+      url.searchParams.set(this.#param, paramValue);
+      window.history.replaceState(window.history.state, "", url);
+    };
+  }
+
+  if (!customElements.get("tab-url-sync")) {
+    customElements.define("tab-url-sync", TabUrlSync);
+  }
+</script>
diff --git a/src/content/docs/explore/pubky-protocol/sdk.md b/src/content/docs/explore/pubky-protocol/sdk.mdx
similarity index 88%
rename from src/content/docs/explore/pubky-protocol/sdk.md
rename to src/content/docs/explore/pubky-protocol/sdk.mdx
index bf69594..047d33b 100644
--- a/src/content/docs/explore/pubky-protocol/sdk.md
+++ b/src/content/docs/explore/pubky-protocol/sdk.mdx
@@ -2,6 +2,11 @@
 title: "Pubky SDK: Client Libraries for Decentralized Applications"
 ---
 
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import TabUrlSync from '../../../../components/TabUrlSync.astro';
+
+<TabUrlSync syncKey="sdk-lang" param="lang" />
+
 :::note
 The SDK is now at **v0.10**. If you're upgrading from an earlier version, see the [v0.10 Migration Guide](https://github.com/pubky/pubky-homeserver/tree/main/docs/v0.10-migration).
 :::
@@ -48,10 +53,18 @@ For event-driven apps, **EventStreamBuilder** lets you subscribe to real-time ch
 
 Sign in and read/write data. Account creation (signup) is generally handled outside of your app. See the [Developer Guide](/explore/pubkycore/getting-started/) for testnet setup where you bootstrap accounts for development.
 
-```js snippet="snippets/js/src/sdk.ts:js_quick_example" code-language="javascript"
-```
-```rust snippet="snippets/rust/src/lib.rs:rust_quick_example" code-language="rust"
-```
+<div class="terminal-tabs">
+<Tabs syncKey="sdk-lang">
+  <TabItem label="JavaScript">
+    ```js snippet="snippets/js/src/sdk.ts:js_quick_example"
+    ```
+  </TabItem>
+  <TabItem label="Rust">
+    ```rust snippet="snippets/rust/src/lib.rs:rust_quick_example"
+    ```
+  </TabItem>
+</Tabs>
+</div>
 
 ## Resources
 
diff --git a/src/styles/custom.css b/src/styles/custom.css
index d9a674e..22851b2 100644
--- a/src/styles/custom.css
+++ b/src/styles/custom.css
@@ -34,7 +34,6 @@
 	--spacing-1: 4px;
 	--spacing-2: 8px;
 	--spacing-2-5: 10px; /* Figma half-step between spacing-2(8) and spacing-3(12) */
-	--spacing-window-controls: 11px;
 	--spacing-3: 12px;
 	--spacing-4: 16px;
 	--spacing-5: 20px;
@@ -46,7 +45,6 @@
 	--spacing-20: 80px;
 
 	/* Border radius */
-	--radius-none: 0;
 	--radius-sm: 6px;
 	--radius-md: 8px;
 	--radius-lg: 12px;
@@ -87,16 +85,7 @@
 	--alpha-white-16: rgba(255, 255, 255, 0.16);
 	--alpha-white-10: rgba(255, 255, 255, 0.1);
 	--alpha-white-5: rgba(255, 255, 255, 0.045);
-	--terminal-tab-hover: rgba(255, 255, 255, 0.05);
 	--base-secondary-hover: #3a3a3f;
-	--window-control-red: #ff5f57;
-	--window-control-yellow: #febc2e;
-	--window-control-green: #28c840;
-
-	/* Component dimensions */
-	--window-control-size: 9px;
-	--code-switcher-width: 200px;
-	--code-switcher-height: 48px;
 
 	/* Shadows */
 	--shadow-xs: 0 1px 2px rgba(5, 5, 10, 0.2);
@@ -226,118 +215,74 @@ site-search button[data-open-modal] kbd {
 	outline-offset: 2px;
 }
 
-/* Language code windows copy the landing install terminal's exact
-   terminal-bar, dots, tabs, and tab trigger styling. */
-.language-code-group {
-	margin-block: var(--spacing-4);
-}
-
-.language-code-terminal {
-	overflow: hidden;
+/* ── Terminal-style tabs ── */
+/* Opt-in via .terminal-tabs wrapper around Starlight <Tabs>.
+   ⚠ Couples to Starlight's internal DOM: starlight-tabs, .tablist-wrapper,
+   .tab, [role="tab"], [role="tabpanel"]. Review after Starlight upgrades. */
+.terminal-tabs starlight-tabs {
 	border: 1px solid var(--base-border);
 	border-radius: var(--radius-xl);
+	overflow: hidden;
 	background: var(--base-background);
-	display: flex;
-	flex-direction: column;
 }
 
-.language-code-group .terminal-bar {
-	display: flex;
-	flex-wrap: wrap;
-	align-items: center;
-	gap: var(--spacing-window-controls);
-	padding: var(--spacing-2) var(--spacing-4);
+.terminal-tabs starlight-tabs .tablist-wrapper {
+	overflow: visible;
 	background: var(--base-card);
+	padding: var(--spacing-2) var(--spacing-4);
 }
 
-.language-code-group .dots {
-	display: flex;
-	gap: var(--spacing-window-controls);
-}
-
-.language-code-group .dot {
-	width: var(--window-control-size);
-	height: var(--window-control-size);
-	border-radius: var(--radius-full);
-}
-
-.language-code-group .dot-red {
-	background: var(--window-control-red);
-}
-
-.language-code-group .dot-yellow {
-	background: var(--window-control-yellow);
-}
-
-.language-code-group .dot-green {
-	background: var(--window-control-green);
-}
-
-.language-code-group .tabs {
-	display: flex;
-	align-items: center;
-	width: var(--code-switcher-width);
-	height: var(--code-switcher-height);
+.terminal-tabs starlight-tabs [role="tablist"] {
+	border-bottom: none;
+	width: fit-content;
+	max-width: 100%;
 	padding: var(--spacing-2);
 	gap: var(--spacing-2);
 	border-radius: var(--radius-md);
 }
 
-.language-code-group .tabs[data-language-count="3"] {
-	width: max-content;
-	flex-shrink: 0;
-}
-
-.language-code-group .tabs[data-language-count="3"] .tab {
-	white-space: nowrap;
+.terminal-tabs starlight-tabs .tab {
+	flex: 1;
 }
 
-.language-code-group .tab {
-	flex: 1;
-	background: transparent;
-	border: none;
-	color: var(--base-secondary-foreground);
-	font-family: var(--sl-font);
+.terminal-tabs starlight-tabs .tab > [role="tab"] {
+	justify-content: center;
+	padding: var(--spacing-2);
+	border-radius: var(--radius-md);
 	font-size: var(--text-xs-size);
 	font-weight: 700;
 	line-height: var(--text-xs-lh);
-	padding: var(--spacing-2);
-	border-radius: var(--radius-md);
-	cursor: pointer;
+	box-shadow: none;
+	color: var(--base-secondary-foreground);
 	transition: all 0.15s ease;
-	text-align: center;
 }
 
-.language-code-group .tab:hover {
+.terminal-tabs starlight-tabs .tab > [role="tab"]:hover {
 	color: var(--base-foreground);
-	background: var(--terminal-tab-hover);
+	background: rgba(255, 255, 255, 0.05);
 }
 
-.language-code-group .tab.active {
-	color: var(--base-foreground);
+.terminal-tabs starlight-tabs .tab > [role="tab"][aria-selected="true"] {
 	background: var(--base-muted);
 	box-shadow: var(--shadow-sm);
+	color: var(--base-foreground);
 }
 
-.language-code-group .command {
-	display: none;
-}
-
-.language-code-group .command.active {
-	display: block;
+.terminal-tabs starlight-tabs > [role="tabpanel"] {
+	margin-top: 0;
 }
 
-.language-code-panel > .expressive-code {
+.terminal-tabs starlight-tabs > [role="tabpanel"] .expressive-code {
 	margin: 0;
 }
 
-.language-code-panel > .expressive-code .frame {
+.terminal-tabs starlight-tabs > [role="tabpanel"] .expressive-code .frame {
 	--code-background: var(--base-background);
 }
 
-.language-code-panel > .expressive-code pre {
+.terminal-tabs starlight-tabs > [role="tabpanel"] .expressive-code pre {
 	border: none;
-	border-radius: var(--radius-none);
+	border-radius: 0;
 }
 
 /* Shrink FAQ per-question headings */