docs: address review on the shared Plane theme

- PlaneHeader: remember and restore the scroll offset around the mobile
  menu's body scroll lock. `position: fixed` with `top: 0` dropped the
  document scroll, so opening the menu part-way down a page and closing
  it sent the reader back to the top.
- PlaneHeader: type the nav off `DefaultTheme.Config` and narrow the
  `NavItem` union properly (string-link guard, dropdown predicate). This
  fixes 11 real type errors the previous check:types never looked at.
- CookieConsent: both sites boot PostHog with `persistence: "memory"`, but
  granting consent only called `opt_in_capturing()`, so a consenting
  visitor still got a fresh distinct_id on every page load. Lift
  persistence on Accept, force it back on Decline, and revoke GA consent
  explicitly on Decline.
- theme/index.ts: remove the leaked `hashchange` listener on unmount and
  drop the duplicate synthetic click in the tab-hash handler.
- check-theme-sync: distinguish "sibling has not adopted plane/ yet" from
  "sibling unreachable". The master fallback 404s until both PRs land,
  which would have turned CI red on unrelated PRs in between.
- check:types: run vue-tsc through a shared wrapper. Plain `tsc` cannot
  parse `.vue`, so the new gate silently skipped every component; it now
  checks them and ignores only the vendored VoidZero sources.

Claude-Session: https://claude.ai/code/session_01JGiwdDajm1vYYNBfQMr44f

Author: sriramveeraghanta

AGENTS.md

@@ -21,7 +21,7 @@ pnpm check:types          # Type-check the VitePress config and theme
 pnpm check:theme-sync     # Verify docs/.vitepress/theme/plane/ is identical to makeplane/docs (THEME_SIBLING_PATH=../docs for a local checkout)
 ```
 
-**CI checks on PRs** (to `master`): Prettier formatting + VitePress build must pass.
+**CI checks on PRs** (to `master`): Prettier formatting, type-check, VitePress build, and the shared-theme sync check must pass.
 
 ## Architecture
 

docs/.vitepress/theme/plane/components/CookieConsent.vue

@@ -7,6 +7,7 @@ declare global {
     posthog?: {
       opt_in_capturing?: () => void;
       opt_out_capturing?: () => void;
+      set_config?: (config: Record<string, unknown>) => void;
     };
   }
 }
@@ -32,21 +33,28 @@ function grantConsent() {
     });
   }
 
-  // PostHog (may not be loaded if VITE_POSTHOG_KEY is unset)
-  if (window.posthog?.opt_in_capturing) {
-    window.posthog.opt_in_capturing();
-  }
+  // PostHog (may not be loaded if VITE_POSTHOG_KEY is unset).
+  // Both sites boot PostHog with `persistence: "memory"` so nothing is stored
+  // pre-consent; without lifting that here a consenting visitor still gets a new
+  // distinct_id on every page load, so returning users never stitch together.
+  window.posthog?.set_config?.({ persistence: "localStorage+cookie" });
+  window.posthog?.opt_in_capturing?.();
 }
 
 function denyConsent() {
   if (typeof window === "undefined") return;
 
-  // Google Analytics — consent stays denied by default, no update needed
+  // Google Analytics — consent stays denied by default, but be explicit so a
+  // later "change cookie settings" entry point can revoke a previous grant.
+  if (typeof window.gtag === "function") {
+    window.gtag("consent", "update", {
+      analytics_storage: "denied",
+    });
+  }
 
   // PostHog (may not be loaded if VITE_POSTHOG_KEY is unset)
-  if (window.posthog?.opt_out_capturing) {
-    window.posthog.opt_out_capturing();
-  }
+  window.posthog?.set_config?.({ persistence: "memory" });
+  window.posthog?.opt_out_capturing?.();
 }
 
 function accept() {

docs/.vitepress/theme/plane/components/PlaneHeader.vue

@@ -18,35 +18,36 @@ import { useLangs } from "@vp-composables/langs";
 const SIGN_IN_RE = /sign-in/i;
 const EXTERNAL_URL_RE = /^(?:[a-z]+:|\/\/)/i;
 
-const { theme, frontmatter, isDark } = useData();
-const nav = computed(() => theme.value.nav ?? []);
+const { theme, frontmatter, isDark } = useData<DefaultTheme.Config>();
+const nav = computed<DefaultTheme.NavItem[]>(() => theme.value.nav ?? []);
+
+/** VitePress allows `link` to be a function; the header only handles string links. */
+type LinkNavItem = DefaultTheme.NavItemWithLink & { link: string };
+/** Any level of the nav tree, including the groups nested inside a dropdown. */
+type AnyNavItem = DefaultTheme.NavItem | DefaultTheme.NavItemChildren;
+
+const isLinkItem = (item: AnyNavItem): item is LinkNavItem =>
+  "link" in item && typeof item.link === "string";
 
 /**
  * Nav items flagged with `planeButton: "primary" | "secondary"` render as header
  * buttons (Sign in / cross-site link) instead of nav links. A `/sign-in` link is
  * treated as the primary button even without the flag.
  */
-const isLinkItem = (item: DefaultTheme.NavItem): item is DefaultTheme.NavItemWithLink =>
-  "link" in item && typeof item.link === "string";
-
-const isPrimaryButtonItem = (item: DefaultTheme.NavItem) =>
+const isPrimaryButtonItem = (item: DefaultTheme.NavItem): item is LinkNavItem =>
   isLinkItem(item) && (item.planeButton === "primary" || SIGN_IN_RE.test(item.link));
 
-const isSecondaryButtonItem = (item: DefaultTheme.NavItem) =>
+const isSecondaryButtonItem = (item: DefaultTheme.NavItem): item is LinkNavItem =>
   isLinkItem(item) && item.planeButton === "secondary";
 
 const isNavButtonItem = (item: DefaultTheme.NavItem) =>
   isPrimaryButtonItem(item) || isSecondaryButtonItem(item);
 
 const mainNav = computed(() => nav.value.filter((item) => !isNavButtonItem(item)));
 
-const signInNavItem = computed(() =>
-  nav.value.find((item): item is DefaultTheme.NavItemWithLink => isPrimaryButtonItem(item)),
-);
+const signInNavItem = computed(() => nav.value.find(isPrimaryButtonItem));
 
-const secondaryNavItem = computed(() =>
-  nav.value.find((item): item is DefaultTheme.NavItemWithLink => isSecondaryButtonItem(item)),
-);
+const secondaryNavItem = computed(() => nav.value.find(isSecondaryButtonItem));
 
 const route = useRoute();
 const { localeLinks, currentLang } = useLangs({ correspondingLink: true });
@@ -68,7 +69,8 @@ const mobileMenuOpen = ref(false);
 const expandedAccordions = ref<Set<number>>(new Set());
 const languageMenuOpen = ref(false);
 
-const isDropdown = (item: DefaultTheme.NavItem) => "items" in item && Array.isArray(item.items);
+const isDropdown = (item: AnyNavItem): item is DefaultTheme.NavItemWithChildren =>
+  "items" in item && Array.isArray(item.items);
 const isExternalLink = (link: string) => EXTERNAL_URL_RE.test(link);
 
 const toggleAccordion = (index: number) => {
@@ -86,23 +88,36 @@ const handleKeydown = (e: KeyboardEvent) => {
   }
 };
 
+/**
+ * `position: fixed` on <body> drops the document scroll to 0, so remember the
+ * offset and restore it on unlock — otherwise opening the mobile menu part-way
+ * down a page sends the reader back to the top when they close it.
+ */
+let lockedScrollY = 0;
+
 const lockBodyScroll = () => {
   const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+  lockedScrollY = window.scrollY;
   document.body.style.overflow = "hidden";
   document.body.style.position = "fixed";
   document.body.style.width = "100%";
-  document.body.style.top = "0";
+  document.body.style.top = `-${lockedScrollY}px`;
   if (scrollbarWidth > 0) {
     document.body.style.paddingRight = `${scrollbarWidth}px`;
   }
 };
 
 const unlockBodyScroll = () => {
+  const wasLocked = document.body.style.position === "fixed";
   document.body.style.overflow = "";
   document.body.style.position = "";
   document.body.style.width = "";
   document.body.style.top = "";
   document.body.style.paddingRight = "";
+  if (wasLocked) {
+    window.scrollTo(0, lockedScrollY);
+    lockedScrollY = 0;
+  }
 };
 
 const toggleMobileMenu = () => {
@@ -385,7 +400,7 @@ onUnmounted(() => {
         >
           <nav class="flex-1 w-full pt-6 pb-8">
             <ul class="space-y-1">
-              <li v-for="(navItem, index) in mainNav" :key="navItem.text">
+              <li v-for="(navItem, index) in mainNav" :key="index">
                 <template v-if="isDropdown(navItem)">
                   <button
                     type="button"
@@ -407,11 +422,8 @@ onUnmounted(() => {
                     </svg>
                   </button>
                   <ul v-show="expandedAccordions.has(index)" class="pl-4 space-y-1">
-                    <template
-                      v-for="childItem in navItem.items"
-                      :key="childItem.link || childItem.text"
-                    >
-                      <li v-if="'link' in childItem">
+                    <template v-for="(childItem, childIndex) in navItem.items" :key="childIndex">
+                      <li v-if="isLinkItem(childItem)">
                         <a
                           :href="normalizeLink(childItem.link)"
                           :target="isExternalLink(childItem.link) ? '_blank' : undefined"
@@ -429,7 +441,7 @@ onUnmounted(() => {
                           {{ childItem.text }}
                         </a>
                       </li>
-                      <li v-else-if="'items' in childItem">
+                      <li v-else-if="isDropdown(childItem)">
                         <p
                           v-if="childItem.text"
                           class="pt-3 pb-1 px-4 text-xs font-semibold uppercase tracking-wider text-grey/70 dark:text-white/50"
@@ -438,11 +450,11 @@ onUnmounted(() => {
                         </p>
                         <ul class="pl-4 space-y-1">
                           <li
-                            v-for="nestedItem in childItem.items"
-                            :key="nestedItem.link || nestedItem.text"
+                            v-for="(nestedItem, nestedIndex) in childItem.items"
+                            :key="nestedIndex"
                           >
                             <a
-                              v-if="nestedItem.link"
+                              v-if="isLinkItem(nestedItem)"
                               :href="normalizeLink(nestedItem.link)"
                               :target="isExternalLink(nestedItem.link) ? '_blank' : undefined"
                               :rel="isExternalLink(nestedItem.link) ? 'noreferrer' : undefined"
@@ -465,7 +477,7 @@ onUnmounted(() => {
                   </ul>
                 </template>
                 <a
-                  v-else-if="navItem.link"
+                  v-else-if="isLinkItem(navItem)"
                   :href="normalizeLink(navItem.link)"
                   :target="isExternalLink(navItem.link) ? '_blank' : undefined"
                   :rel="isExternalLink(navItem.link) ? 'noreferrer' : undefined"
@@ -480,8 +492,9 @@ onUnmounted(() => {
                 >
                   {{ navItem.text }}
                 </a>
+                <!-- `{ component }` nav items have no mobile representation; skip them. -->
                 <span
-                  v-else
+                  v-else-if="'text' in navItem"
                   class="block py-3 px-4 text-base font-sans text-primary dark:text-white"
                 >
                   {{ navItem.text }}

docs/.vitepress/theme/plane/index.ts

@@ -48,15 +48,16 @@ function handleTabHash() {
   document.querySelectorAll<HTMLElement>('[role="tab"]').forEach((button) => {
     const labelText = button.textContent?.trim().toLowerCase().replace(/\s+/g, "-");
     if (labelText === hash) {
-      button.dispatchEvent(
-        new MouseEvent("click", { view: window, bubbles: true, cancelable: true }),
-      );
       button.click();
       button.focus();
     }
   });
 }
 
+function handleHashChange() {
+  nextTick(handleTabHash);
+}
+
 function updateHashOnTabClick(event: Event) {
   const button = event.currentTarget as HTMLElement;
   const labelText = button.textContent?.trim().toLowerCase().replace(/\s+/g, "-");
@@ -169,7 +170,7 @@ export function createPlaneTheme(options: PlaneThemeOptions): Theme {
           syncHeaderTheme();
         }, 100);
 
-        window.addEventListener("hashchange", () => nextTick(handleTabHash));
+        window.addEventListener("hashchange", handleHashChange);
 
         htmlClassObserver = new MutationObserver(syncHeaderTheme);
         htmlClassObserver.observe(document.documentElement, {
@@ -179,6 +180,7 @@ export function createPlaneTheme(options: PlaneThemeOptions): Theme {
       });
 
       onUnmounted(() => {
+        window.removeEventListener("hashchange", handleHashChange);
         htmlClassObserver?.disconnect();
         zoom?.detach();
       });

docs/.vitepress/theme/plane/manifest.json

@@ -27,6 +27,7 @@
     "layout/top-banner.ts",
     "options.ts",
     "scripts/check-theme-sync.mjs",
+    "scripts/check-vue-types.mjs",
     "types/shims.d.ts",
     "types/vitepress-augment.d.ts",
     "types/voidzero-theme.ts",

docs/.vitepress/theme/plane/scripts/check-theme-sync.mjs

@@ -10,7 +10,12 @@
  *   2. https://raw.githubusercontent.com/<sibling>/<ref>/… — ref from THEME_SIBLING_REF,
  *      then GITHUB_HEAD_REF (same-named PR branch), then master.
  *
- * Exit codes: 0 identical · 1 drift (or manifest out of date) · 2 sibling unreachable / bad args
+ * While only one repo has adopted the shared theme the sibling has no `plane/` folder yet.
+ * That is reported and skipped (exit 0) rather than failing, so unrelated PRs in the repo
+ * that merged first are not blocked; the check becomes binding as soon as both sides have it.
+ *
+ * Exit codes: 0 identical (or sibling not adopted yet) · 1 drift (or manifest out of date)
+ *             · 2 sibling unreachable / bad args
  */
 import { createHash } from "node:crypto";
 import { readdir, readFile } from "node:fs/promises";
@@ -44,32 +49,55 @@ async function readLocal(file) {
   return readFile(join(THEME_DIR, file));
 }
 
+/** Present on every ref of both repos — tells "ref exists" apart from "ref has no plane/". */
+const ROOT_PROBE = "package.json";
+
 async function makeSiblingReader() {
   const localPath = process.env.THEME_SIBLING_PATH;
   if (localPath) {
-    const root = resolve(process.cwd(), localPath, THEME_REL);
-    return {
-      label: root,
-      read: (file) => readFile(join(root, file)).catch(() => null),
-    };
+    const checkout = resolve(process.cwd(), localPath);
+    const root = join(checkout, THEME_REL);
+    const exists = (file) =>
+      readFile(file).then(
+        () => true,
+        () => false,
+      );
+    if (await exists(join(root, "manifest.json"))) {
+      return {
+        status: "ok",
+        label: root,
+        read: (file) => readFile(join(root, file)).catch(() => null),
+      };
+    }
+    return (await exists(join(checkout, ROOT_PROBE)))
+      ? { status: "not-adopted", label: checkout }
+      : null;
   }
+
   const refs = [process.env.THEME_SIBLING_REF, process.env.GITHUB_HEAD_REF, "master"].filter(
     Boolean,
   );
+  let reachable = null;
   for (const ref of refs) {
-    const base = `https://raw.githubusercontent.com/${siblingArg}/${ref}/${THEME_REL}/`;
+    const root = `https://raw.githubusercontent.com/${siblingArg}/${ref}/`;
+    const base = `${root}${THEME_REL}/`;
     const probe = await fetch(base + "manifest.json").catch(() => null);
     if (probe?.ok) {
       return {
+        status: "ok",
         label: base,
         read: async (file) => {
           const res = await fetch(base + file).catch(() => null);
           return res?.ok ? Buffer.from(await res.arrayBuffer()) : null;
         },
       };
     }
+    if (!reachable) {
+      const rootProbe = await fetch(root + ROOT_PROBE).catch(() => null);
+      if (rootProbe?.ok) reachable = `${siblingArg}@${ref}`;
+    }
   }
-  return null;
+  return reachable ? { status: "not-adopted", label: reachable } : null;
 }
 
 const manifest = JSON.parse(await readLocal("manifest.json"));
@@ -89,10 +117,19 @@ if (missingFromManifest.length || missingFromDisk.length) {
 const sibling = await makeSiblingReader();
 if (!sibling) {
   console.error(
-    `Could not reach the sibling theme (${siblingArg}). Set THEME_SIBLING_PATH=../<repo> for a local checkout.`,
+    `Could not reach the sibling repo (${siblingArg}). Set THEME_SIBLING_PATH=../<repo> for a local checkout.`,
   );
   process.exit(2);
 }
+
+if (sibling.status === "not-adopted") {
+  console.log(
+    `${sibling.label} has no ${THEME_REL} yet — skipping the cross-repo comparison.\n` +
+      `This is expected only until the companion PR lands; the check binds once both repos have the folder.`,
+  );
+  process.exit(failed ? 1 : 0);
+}
+
 console.log(`Comparing ${THEME_REL} against ${sibling.label}`);
 
 const siblingManifestRaw = await sibling.read("manifest.json");