diff --git a/runner/apps/authoring/src/App.tsx b/runner/apps/authoring/src/App.tsx
index 080c2065..92ac0fe6 100644
--- a/runner/apps/authoring/src/App.tsx
+++ b/runner/apps/authoring/src/App.tsx
@@ -3,6 +3,7 @@ import { EditorShell, theme, logoUrl, type PreviewStatus } from "@handsontable/d
 import {
   applyHandsontableCss,
   applyHandsontableVersion,
+  deriveDocsBucketCandidate,
   validateHandsontableVersion,
   type CatalogEntry,
   type DemoRuntime,
@@ -12,7 +13,12 @@ import { SandpackRuntime } from "@handsontable/demo-runtime/sandpack";
 import { ContainerRuntime } from "@handsontable/demo-runtime/container";
 import { zipSync, strToU8 } from "fflate";
 import { catalog, getEntry, fetchVersions, VERSION_OPTIONS, DEFAULT_VERSION } from "./catalog.js";
-import { fetchDocsManifest, loadDocsExample, type DocsManifestItem } from "./docs-catalog.js";
+import {
+  fetchDocsManifest,
+  loadDocsExample,
+  type DocsManifest,
+  type DocsManifestItem,
+} from "./docs-catalog.js";
 import { DocsCascader, type CascaderLeaf } from "./DocsCascader.js";
 import { currentUser, login, logout, getToken, type User } from "./auth.js";
 import { MyDemos } from "./MyDemos.js";
@@ -55,6 +61,23 @@ function describeRuntimeError(e: unknown, engine: string): string {
   return msg;
 }
 
+function pinHandsontableFiles(files: FilesMap, version: string): FilesMap {
+  const validated = validateHandsontableVersion(version);
+  if (!validated.ok || files["/package.json"] === undefined) return files;
+  try {
+    return applyHandsontableCss(
+      applyHandsontableVersion(files, validated.value),
+      validated.value,
+    );
+  } catch {
+    return files;
+  }
+}
+
+function isMissingDocsResource(error: unknown): boolean {
+  return error instanceof Error && /\b404\b/.test(error.message);
+}
+
 type EditorRoute =
   | { mode: "play" }
   | { mode: "edit"; id: string }
@@ -116,15 +139,17 @@ function Splash({ text }: { text: string }) {
   );
 }
 
-function NotFound({ path }: { path: string | null }) {
+function NotFound({ path, transient = false }: { path: string | null; transient?: boolean }) {
   return (
     <div style={centered}>
       <Logo size={40} />
       <p style={{ color: theme.color.text, fontFamily: theme.font.ui, fontWeight: 600, margin: 0 }}>
-        Example not found
+        {transient ? "Example temporarily unavailable" : "Example not found"}
       </p>
       <p style={{ color: theme.color.textMuted, fontFamily: theme.font.ui, margin: 0 }}>
-        This example may not be imported yet.
+        {transient
+          ? "The documentation catalog could not be loaded. Try again later."
+          : "This example may not be imported yet."}
       </p>
       {path && (
         <code style={{ color: theme.color.textMuted, fontSize: 12 }}>{path}</code>
@@ -155,16 +180,21 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
   const [entry, setEntry] = useState<CatalogEntry>(() => getEntry(framework));
   // Non-null when the current example is a documentation-guide example.
   const [docsPath, setDocsPath] = useState<string | null>(initialDocs);
-  // Docs examples for the Cascader picker (fetched once).
+  // Docs examples for the currently-resolved version bucket.
   const [docsItems, setDocsItems] = useState<DocsManifestItem[]>([]);
+  const [activeDocsBucket, setActiveDocsBucket] = useState<string | null>(null);
+  const [activeDocsManifest, setActiveDocsManifest] = useState<DocsManifest | null>(null);
 
   const [files, setFiles] = useState<FilesMap>(() => ({ ...entry.files }));
   const [version, setVersion] = useState<string>(
     () => new URLSearchParams(location.search).get("v") || DEFAULT_VERSION,
   );
   const [versionOptions, setVersionOptions] = useState<string[]>(VERSION_OPTIONS);
+  const [nextVersion, setNextVersion] = useState("");
+  const [versionsResolved, setVersionsResolved] = useState(false);
   const [status, setStatus] = useState<PreviewStatus>("booting");
   const [errorMessage, setErrorMessage] = useState<string | null>(null);
+  const [versionWarning, setVersionWarning] = useState<string | null>(null);
   const [bootLog, setBootLog] = useState<string>("");
   const [dirty, setDirty] = useState(false);
   const [syncing, setSyncing] = useState(false); // container rebuild in flight
@@ -183,6 +213,8 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
   // `?docs=` example has resolved, so we don't briefly boot the starter first.
   const [sourceLoaded, setSourceLoaded] = useState(!savedId && !initialDocs);
   const [docsNotFound, setDocsNotFound] = useState(false);
+  const [docsNotFoundTransient, setDocsNotFoundTransient] = useState(false);
+  const [docsRuntimeBlocked, setDocsRuntimeBlocked] = useState(!!initialDocs);
   const [title, setTitle] = useState("");
   const [description, setDescription] = useState("");
   const [saving, setSaving] = useState(false);
@@ -192,6 +224,17 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
   const [linksId, setLinksId] = useState<string | null>(null);
   const [forkedFrom, setForkedFrom] = useState<string | null>(`catalog:${framework}`);
   const [myDemosOpen, setMyDemosOpen] = useState(false);
+  const docsPathRef = useRef<string | null>(docsPath);
+  const dirtyRef = useRef(dirty);
+  const sourceLoadedRef = useRef(sourceLoaded);
+  const activeDocsBucketRef = useRef<string | null>(activeDocsBucket);
+  const activeDocsManifestRef = useRef<DocsManifest | null>(activeDocsManifest);
+  const docsRequestSeqRef = useRef(0);
+  docsPathRef.current = docsPath;
+  dirtyRef.current = dirty;
+  sourceLoadedRef.current = sourceLoaded;
+  activeDocsBucketRef.current = activeDocsBucket;
+  activeDocsManifestRef.current = activeDocsManifest;
 
   /** Replace the whole workspace (entry + files + lineage) and remount. */
   const loadWorkspace = useCallback((nextEntry: CatalogEntry, nextFiles: FilesMap, lineage: string) => {
@@ -201,6 +244,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
     setFiles(nextFiles);
     setForkedFrom(lineage);
     setDirty(false);
+    dirtyRef.current = false;
     setErrorMessage(null);
     setMountGen((g) => g + 1);
   }, []);
@@ -244,35 +288,6 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
     return () => { cancelled = true; };
   }, [savedId, isShare, loadWorkspace]);
 
-  // Fetch the docs-example manifest once (drives the breadcrumb-grouped picker).
-  useEffect(() => {
-    if (route.mode === "share") return; // read-only shared view has no picker
-    let cancelled = false;
-    fetchDocsManifest()
-      .then((m) => { if (!cancelled) setDocsItems(m.examples); })
-      .catch(() => { /* picker just shows starters */ });
-    return () => { cancelled = true; };
-  }, [route.mode]);
-
-  // Play mode with `?docs=`: lazy-load the docs example and boot it.
-  useEffect(() => {
-    if (!initialDocs) return;
-    let cancelled = false;
-    loadDocsExample(initialDocs)
-      .then((e) => {
-        if (cancelled) return;
-        loadWorkspace(e, { ...e.files }, `docs:${initialDocs}`);
-        setDocsPath(initialDocs);
-        setSourceLoaded(true);
-      })
-      .catch(() => {
-        if (cancelled) return;
-        setDocsNotFound(true);
-        setSourceLoaded(true);
-      });
-    return () => { cancelled = true; };
-  }, [initialDocs, loadWorkspace]);
-
   // Load real published versions from the API (npm-backed); default to latest
   // unless a version was deep-linked (or pinned by the demo being edited/shared).
   useEffect(() => {
@@ -280,38 +295,124 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
     fetchVersions(API_BASE)
       .then(({ latest, next, versions }) => {
         if (cancelled) return;
+        setNextVersion(next ?? "");
         const opts = [...new Set([latest, ...versions, next].filter((v): v is string => !!v))];
         if (opts.length) setVersionOptions(opts);
         if (latest && !hadUrlVersion.current) {
           setVersion((cur) => (cur === DEFAULT_VERSION ? latest : cur));
         }
+        setVersionsResolved(true);
       })
-      .catch(() => { /* keep fallback options */ });
+      .catch(() => {
+        if (!cancelled) setVersionsResolved(true); // release buckets can still resolve without dist-tags.next
+      });
     return () => { cancelled = true; };
   }, []);
 
-  // Reflect the selected version in the editor's package.json (re-pin
-  // handsontable + wrapper), keeping any other edits.
+  // A manifest fetch is the existence check for a derived bucket. Resolve it on
+  // startup and every selected-version change, then swap or preserve an open
+  // docs workspace according to its dirty state.
   useEffect(() => {
-    const v = validateHandsontableVersion(version);
-    if (!v.ok) return;
-    setFiles((prev) => {
-      if (prev["/package.json"] === undefined) return prev;
-      let next: FilesMap;
-      try {
-        next = applyHandsontableCss(applyHandsontableVersion(prev, v.value), v.value);
-      } catch {
-        return prev;
+    if (route.mode === "share" || !versionsResolved) return;
+    const requestSeq = ++docsRequestSeqRef.current;
+    const openPath = docsPathRef.current;
+    const initialLoad = !!initialDocs && !sourceLoadedRef.current;
+    const candidate = deriveDocsBucketCandidate(version, nextVersion);
+
+    setDocsItems([]);
+    setActiveDocsBucket(null);
+    setActiveDocsManifest(null);
+    activeDocsBucketRef.current = null;
+    activeDocsManifestRef.current = null;
+    if (openPath) {
+      setDocsRuntimeBlocked(true);
+      setStatus("booting");
+      setErrorMessage(null);
+    }
+
+    const failOpenDocs = (kind: "bucket" | "path" | "fetch") => {
+      if (docsRequestSeqRef.current !== requestSeq) return;
+      if (initialLoad) {
+        setDocsNotFoundTransient(kind === "fetch");
+        setDocsNotFound(true);
+        setSourceLoaded(true);
+        sourceLoadedRef.current = true;
+        return;
       }
-      if (
-        next["/package.json"] === prev["/package.json"] &&
-        next["/index.html"] === prev["/index.html"] &&
-        next["/src/index.html"] === prev["/src/index.html"]
-      ) return prev; // no change
-      filesRef.current = next;
-      return next;
-    });
-  }, [version, framework, mountGen]);
+      if (!openPath) return;
+      const message = kind === "bucket"
+        ? `No documentation examples are available for Handsontable ${version}. Choose another version or a starter.`
+        : kind === "path"
+          ? `This documentation example is unavailable for Handsontable ${version}. Choose another version or a starter.`
+          : `Could not load documentation examples for Handsontable ${version}. Try another version.`;
+      setStatus("error");
+      setErrorMessage(message);
+      setDocsRuntimeBlocked(true);
+    };
+
+    if (!candidate) {
+      failOpenDocs("bucket");
+      return;
+    }
+
+    let cancelled = false;
+    void fetchDocsManifest(candidate)
+      .then(async (manifest) => {
+        if (cancelled || docsRequestSeqRef.current !== requestSeq) return;
+        setDocsItems(manifest.examples);
+        setActiveDocsBucket(candidate);
+        setActiveDocsManifest(manifest);
+        activeDocsBucketRef.current = candidate;
+        activeDocsManifestRef.current = manifest;
+        if (!openPath) return;
+        if (!manifest.examples.some((item) => item.docsPath === openPath)) {
+          failOpenDocs("path");
+          return;
+        }
+
+        if (dirtyRef.current) {
+          const pinned = pinHandsontableFiles(filesRef.current, version);
+          filesRef.current = pinned;
+          setFiles(pinned);
+          setVersionWarning(
+            "This example has unsaved edits; its content may not match the selected version API.",
+          );
+          setErrorMessage(null);
+          setDocsRuntimeBlocked(false);
+          return;
+        }
+
+        try {
+          const docsEntry = await loadDocsExample(candidate, openPath);
+          if (cancelled || docsRequestSeqRef.current !== requestSeq) return;
+          const nextFiles = manifest.hotVersion === version
+            ? { ...docsEntry.files }
+            : pinHandsontableFiles({ ...docsEntry.files }, version);
+          loadWorkspace(docsEntry, nextFiles, `docs:${candidate}:${openPath}`);
+          setDocsPath(openPath);
+          docsPathRef.current = openPath;
+          setVersionWarning(null);
+          setDocsRuntimeBlocked(false);
+          setSourceLoaded(true);
+          sourceLoadedRef.current = true;
+        } catch (error) {
+          failOpenDocs(isMissingDocsResource(error) ? "path" : "fetch");
+        }
+      })
+      .catch((error) => {
+        failOpenDocs(isMissingDocsResource(error) ? "bucket" : "fetch");
+      });
+    return () => { cancelled = true; };
+  }, [initialDocs, loadWorkspace, nextVersion, route.mode, version, versionsResolved]);
+
+  // Starters never load docs artifacts. Version changes only re-pin their
+  // existing package/CSS files and preserve any edits.
+  useEffect(() => {
+    if (docsPath) return;
+    const pinned = pinHandsontableFiles(filesRef.current, version);
+    filesRef.current = pinned;
+    setFiles(pinned);
+  }, [docsPath, version]);
 
   // Keep the URL in sync with the selected example + version — playground only
   // (edit/share have their own /edit/:id, /share/:id paths). Docs examples use
@@ -333,30 +434,82 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
   /** Pick a catalog starter template as a fresh starting template (playground). */
   const selectExample = useCallback(
     (fw: string) => {
+      docsRequestSeqRef.current += 1;
       setDocsPath(null);
-      loadWorkspace(getEntry(fw), { ...getEntry(fw).files }, `catalog:${fw}`);
+      docsPathRef.current = null;
+      setDocsRuntimeBlocked(false);
+      setVersionWarning(null);
+      const starter = getEntry(fw);
+      loadWorkspace(starter, pinHandsontableFiles({ ...starter.files }, version), `catalog:${fw}`);
     },
-    [loadWorkspace],
+    [loadWorkspace, version],
   );
 
   /** Open a documentation-guide example (lazy-loaded by its docs content path). */
   const selectDocs = useCallback(
     async (dp: string) => {
+      const bucket = activeDocsBucketRef.current;
+      const manifest = activeDocsManifestRef.current;
+      if (!bucket || !manifest || !manifest.examples.some((item) => item.docsPath === dp)) {
+        setErrorMessage(`Could not load docs example: ${dp}`);
+        return;
+      }
+      const requestSeq = ++docsRequestSeqRef.current;
+      setDocsRuntimeBlocked(true);
+      setStatus("booting");
+      setErrorMessage(null);
       try {
-        const e = await loadDocsExample(dp);
+        const e = await loadDocsExample(bucket, dp);
+        if (docsRequestSeqRef.current !== requestSeq || activeDocsBucketRef.current !== bucket) return;
+        const nextFiles = manifest.hotVersion === version
+          ? { ...e.files }
+          : pinHandsontableFiles({ ...e.files }, version);
         setDocsPath(dp);
-        loadWorkspace(e, { ...e.files }, `docs:${dp}`);
+        docsPathRef.current = dp;
+        loadWorkspace(e, nextFiles, `docs:${bucket}:${dp}`);
+        setVersionWarning(null);
+        setDocsRuntimeBlocked(false);
       } catch {
         // Unlike the deep-link (`?docs=`) load path, a working workspace is already
         // open here, so a toolbar note is enough — no full-screen not-found takeover.
-        setErrorMessage(`Could not load docs example: ${dp}`);
+        if (docsRequestSeqRef.current === requestSeq) {
+          setStatus("error");
+          setErrorMessage(`Could not load docs example: ${dp}`);
+          setDocsRuntimeBlocked(true);
+        }
       }
     },
-    [loadWorkspace],
+    [loadWorkspace, version],
   );
 
+  const changeVersion = useCallback((next: string) => {
+    docsRequestSeqRef.current += 1;
+    setVersionWarning(null);
+    if (docsPathRef.current) {
+      setDocsItems([]);
+      setActiveDocsBucket(null);
+      setActiveDocsManifest(null);
+      activeDocsBucketRef.current = null;
+      activeDocsManifestRef.current = null;
+      setDocsRuntimeBlocked(true);
+      setStatus("booting");
+      setErrorMessage(null);
+    }
+    setVersion(next);
+  }, []);
+
+  // Dispose and visibly clear a docs preview while its target bucket/path is
+  // unresolved or unavailable. The version picker and editor remain usable.
+  useEffect(() => {
+    if (!iframeEl || !docsRuntimeBlocked) return;
+    runtimeRef.current?.dispose();
+    runtimeRef.current = null;
+    iframeEl.removeAttribute("srcdoc");
+    iframeEl.src = "about:blank";
+  }, [iframeEl, docsRuntimeBlocked]);
+
   useEffect(() => {
-    if (!iframeEl || !sourceLoaded || docsNotFound) return;
+    if (!iframeEl || !sourceLoaded || docsNotFound || docsRuntimeBlocked) return;
     setErrorMessage(null);
     const v = validateHandsontableVersion(version);
     if (!v.ok) {
@@ -395,11 +548,14 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
       if (runtimeRef.current === runtime) runtimeRef.current = null;
     };
     // mountGen forces a remount when files are replaced (example switch or fork/edit load).
-  }, [iframeEl, entry, version, mountGen, sourceLoaded, docsNotFound]);
+  }, [iframeEl, entry, version, mountGen, sourceLoaded, docsNotFound, docsRuntimeBlocked]);
 
   const onEdit = useCallback((path: string, contents: string) => {
-    setFiles((prev) => ({ ...prev, [path]: contents }));
+    const next = { ...filesRef.current, [path]: contents };
+    filesRef.current = next;
+    setFiles(next);
     setDirty(true);
+    dirtyRef.current = true;
     try {
       runtimeRef.current?.writeFile(path, contents);
     } catch {
@@ -421,6 +577,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
     filesRef.current = next;
     setFiles(next);
     setDirty(true);
+    dirtyRef.current = true;
     try { runtimeRef.current?.writeFile(path, ""); } catch { /* not mounted */ }
   }, []);
 
@@ -431,6 +588,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
     filesRef.current = next;
     setFiles(next);
     setDirty(true);
+    dirtyRef.current = true;
     try { runtimeRef.current?.deleteFile?.(path); } catch { /* not mounted */ }
   }, []);
 
@@ -442,6 +600,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
     filesRef.current = next;
     setFiles(next);
     setDirty(true);
+    dirtyRef.current = true;
     try {
       runtimeRef.current?.writeFile(newPath, content);
       runtimeRef.current?.deleteFile?.(oldPath);
@@ -549,6 +708,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
         throw new Error(body.error || `save failed (${res.status})`);
       }
       setDirty(false);
+      dirtyRef.current = false;
     } catch (e) {
       setErrorMessage(e instanceof Error ? e.message : String(e));
     } finally {
@@ -568,7 +728,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
         .sort((a, b) => FW_PREF.indexOf(a.framework) - FW_PREF.indexOf(b.framework))
     : [];
 
-  if (docsNotFound) return <NotFound path={initialDocs} />;
+  if (docsNotFound) return <NotFound path={initialDocs} transient={docsNotFoundTransient} />;
   if (savedId && !sourceLoaded) return <Splash text="Loading demo…" />;
 
   return (
@@ -614,7 +774,9 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
               selectedKey={
                 currentDocsMeta
                   ? `${currentDocsMeta.guide}|${currentDocsMeta.exampleId}`
-                  : `starter:${framework}`
+                  : docsPath
+                    ? undefined
+                    : `starter:${framework}`
               }
               onSelect={(leaf: CascaderLeaf) => {
                 if (leaf.kind === "starter") { selectExample(leaf.framework); return; }
@@ -679,6 +841,11 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
             {errorMessage}
           </span>
         )}
+        {versionWarning && (
+          <span style={{ color: theme.color.warning, fontSize: 12, maxWidth: 380 }} title={versionWarning}>
+            {versionWarning}
+          </span>
+        )}
         {isShare ? (
           <>
             <button style={ghostBtn} onClick={downloadZip} title="Download this example (including your edits) as a .zip">
@@ -709,7 +876,7 @@ function Authoring({ user, route }: { user: User | null; route: EditorRoute }) {
         syncing={syncing}
         version={version}
         versionOptions={versionOptions}
-        onVersionChange={setVersion}
+        onVersionChange={changeVersion}
         onEdit={onEdit}
         onAddFile={addFile}
         onRenameFile={renameFile}
diff --git a/runner/apps/authoring/src/docs-catalog.ts b/runner/apps/authoring/src/docs-catalog.ts
index 3ce585b9..4ca03f8c 100644
--- a/runner/apps/authoring/src/docs-catalog.ts
+++ b/runner/apps/authoring/src/docs-catalog.ts
@@ -2,8 +2,8 @@
 //
 // The importer (runner/pipeline/import-docs.mjs) emits, under
 // apps/authoring/public/docs-examples/:
-//   - manifest.json          — metadata list driving the grouped dropdown
-//   - <encoded-docsPath>.json — one full CatalogEntry per example, lazy-fetched
+//   - <bucket>/manifest.json — metadata list driving the grouped dropdown
+//   - <bucket>/<encoded-docsPath>.json — one full CatalogEntry per example, lazy-fetched
 //
 // Examples are opened by their docs content path via the `?docs=` URL param, e.g.
 //   /?docs=guides/columns/column-adding/javascript/example1.ts
@@ -13,6 +13,7 @@ import type { CatalogEntry } from "@handsontable/demo-runtime";
 const BASE = "/docs-examples";
 
 export interface DocsManifestItem {
+  bucket: string;
   docsPath: string;
   file: string;
   breadcrumb: string[];
@@ -28,6 +29,8 @@ export interface DocsManifestItem {
 }
 
 export interface DocsManifest {
+  bucket: string;
+  docsBranch: string;
   generatedFrom: string;
   hotVersion: string;
   count: number;
@@ -50,20 +53,22 @@ export interface DocsGroup {
   items: DocsManifestItem[];
 }
 
-let manifestPromise: Promise<DocsManifest> | null = null;
+const manifestPromises = new Map<string, Promise<DocsManifest>>();
 
-/** Fetch (once) and cache the docs example manifest. */
-export function fetchDocsManifest(): Promise<DocsManifest> {
+/** Fetch (once per bucket) and cache a docs example manifest. */
+export function fetchDocsManifest(bucket: string): Promise<DocsManifest> {
+  let manifestPromise = manifestPromises.get(bucket);
   if (!manifestPromise) {
-    manifestPromise = fetch(`${BASE}/manifest.json`)
+    manifestPromise = fetch(`${BASE}/${bucket}/manifest.json`)
       .then((r) => {
         if (!r.ok) throw new Error(`docs manifest ${r.status}`);
         return r.json() as Promise<DocsManifest>;
       })
       .catch((e) => {
-        manifestPromise = null; // allow retry
+        manifestPromises.delete(bucket); // allow retry
         throw e;
       });
+    manifestPromises.set(bucket, manifestPromise);
   }
   return manifestPromise;
 }
@@ -90,14 +95,18 @@ export function optionLabel(it: DocsManifestItem): string {
 
 const entryCache = new Map<string, DocsCatalogEntry>();
 
-/** Fetch (and cache) the full CatalogEntry for one docs example by its docsPath. */
-export async function loadDocsExample(docsPath: string): Promise<DocsCatalogEntry> {
-  const cached = entryCache.get(docsPath);
+/** Fetch and cache one bucket's full CatalogEntry by its docsPath. */
+export async function loadDocsExample(
+  bucket: string,
+  docsPath: string,
+): Promise<DocsCatalogEntry> {
+  const cacheKey = `${bucket}:${docsPath}`;
+  const cached = entryCache.get(cacheKey);
   if (cached) return cached;
   const file = docsPath.replace(/\//g, "__") + ".json";
-  const res = await fetch(`${BASE}/${file}`);
+  const res = await fetch(`${BASE}/${bucket}/${file}`);
   if (!res.ok) throw new Error(`docs example not found: ${docsPath} (${res.status})`);
   const entry = (await res.json()) as DocsCatalogEntry;
-  entryCache.set(docsPath, entry);
+  entryCache.set(cacheKey, entry);
   return entry;
 }
diff --git a/runner/e2e/docs-examples.spec.ts b/runner/e2e/docs-examples.spec.ts
index bdcee816..0d2012d7 100644
--- a/runner/e2e/docs-examples.spec.ts
+++ b/runner/e2e/docs-examples.spec.ts
@@ -5,8 +5,154 @@ import { test, expect } from "@playwright/test";
 // gated behind E2E_LIVE=1 (run against prod in the post-deploy smoke).
 
 const REACT_EXAMPLE = "/?docs=guides/columns/column-adding/react/example2.tsx";
+const DOCS_PATH = "guides/columns/column-adding/react/example2.tsx";
+const NEXT_VERSION = "19.0.0-next.1";
+
+const FRAMEWORKS = [
+  ["react", "React", "tsx"],
+  ["typescript", "TypeScript", "ts"],
+  ["javascript", "JavaScript", "js"],
+  ["vue", "Vue", "vue"],
+  ["angular", "Angular", "ts"],
+] as const;
+
+function docsPath(framework: string, exampleId: string, extension: string) {
+  return `guides/columns/column-adding/${framework}/${exampleId}.${extension}`;
+}
+
+function manifestItem(bucket: string, framework: string, displayName: string, path: string, exampleId: string) {
+  return {
+    bucket,
+    docsPath: path,
+    file: path.replace(/\//g, "__") + ".json",
+    breadcrumb: ["Columns", "Adding and removing columns"],
+    guide: "guides/columns/column-adding/column-adding.md",
+    guideTitle: "Adding and removing columns",
+    exampleId,
+    exampleTitle: exampleId === "example2"
+      ? "Add and remove columns from the context menu"
+      : "Standard example",
+    docPermalink: "/column-adding",
+    framework,
+    displayName,
+  };
+}
+
+function fixtureItems(bucket: string) {
+  return FRAMEWORKS.flatMap(([framework, displayName, extension]) => [
+    manifestItem(bucket, framework, displayName, docsPath(framework, "example1", extension), "example1"),
+    manifestItem(bucket, framework, displayName, docsPath(framework, "example2", extension), "example2"),
+  ]);
+}
+
+function fixtureEntry(bucket: string, path: string, generatedVersion: string) {
+  const framework = path.split("/").at(-2) ?? "react";
+  const source = `export const fixture = "${bucket}:${path}";\n`;
+  return {
+    framework,
+    displayName: FRAMEWORKS.find(([name]) => name === framework)?.[1] ?? framework,
+    tier: 1,
+    engine: "sandpack",
+    sandpackTemplate: "react-ts",
+    sandpackEnvironment: "parcel",
+    container: null,
+    htWrappers: framework === "react" ? ["@handsontable/react-wrapper"] : [],
+    entry: "/src/App.tsx",
+    htmlEntry: "/index.html",
+    devCommand: null,
+    buildCommand: "vite build",
+    outputDir: "dist",
+    outputGlob: null,
+    staticExport: false,
+    spaMode: false,
+    port: null,
+    installCommand: "pnpm install",
+    htCoreRange: generatedVersion,
+    fileCount: 3,
+    assets: [],
+    skipped: [],
+    docsPath: path,
+    breadcrumb: ["Columns", "Adding and removing columns"],
+    guide: "guides/columns/column-adding/column-adding.md",
+    guideTitle: "Adding and removing columns",
+    exampleId: path.includes("example2") ? "example2" : "example1",
+    lang: "tsx",
+    files: {
+      "/src/App.tsx": source,
+      "/index.html": `<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/handsontable@${generatedVersion}/styles/handsontable.min.css"><div id="root"></div>`,
+      "/package.json": JSON.stringify({
+        dependencies: {
+          handsontable: generatedVersion,
+          ...(framework === "react" ? { "@handsontable/react-wrapper": generatedVersion } : {}),
+        },
+      }, null, 2),
+    },
+  };
+}
+
+async function installRouteFixtures(
+  page: import("@playwright/test").Page,
+  {
+    latest = "18.0.0",
+    availableBuckets = ["18.0", "next"],
+    missingPaths = [],
+    requests = [],
+  }: {
+    latest?: string;
+    availableBuckets?: string[];
+    missingPaths?: string[];
+    requests?: string[];
+  } = {},
+) {
+  await page.route("**/api/versions", (route) => route.fulfill({
+    json: {
+      latest,
+      next: NEXT_VERSION,
+      versions: ["18.0.0", "17.1.0", NEXT_VERSION],
+    },
+  }));
+  await page.route("https://sandpack.codesandbox.io/**", (route) => route.abort());
+  await page.route("https://sandpack-bundler.codesandbox.io/**", (route) => route.abort());
+  await page.route("**/docs-examples/*/*.json", async (route) => {
+    const url = new URL(route.request().url());
+    requests.push(url.pathname);
+    const [, bucket, file] = url.pathname.match(/\/docs-examples\/([^/]+)\/(.+)$/) ?? [];
+    const path = decodeURIComponent(file ?? "").replace(/\.json$/, "").replace(/__/g, "/");
+    if (!bucket || !availableBuckets.includes(bucket) || missingPaths.includes(path)) {
+      await route.fulfill({ status: 404, body: "not found" });
+      return;
+    }
+    const generatedVersion = bucket === "next" ? "19.0.0-next.0" : "18.0.0";
+    await route.fulfill({ json: fixtureEntry(bucket, path, generatedVersion) });
+  });
+  await page.route("**/docs-examples/*/manifest.json", async (route) => {
+    const url = new URL(route.request().url());
+    requests.push(url.pathname);
+    const bucket = url.pathname.split("/").at(-2) ?? "";
+    if (!availableBuckets.includes(bucket)) {
+      await route.fulfill({ status: 404, body: "not found" });
+      return;
+    }
+    const examples = fixtureItems(bucket).filter((item) => !missingPaths.includes(item.docsPath));
+    await route.fulfill({
+      json: {
+        bucket,
+        docsBranch: bucket === "next" ? "develop" : `prod-docs/${bucket}`,
+        generatedFrom: "e2e fixture",
+        hotVersion: bucket === "next" ? "19.0.0-next.0" : "18.0.0",
+        count: examples.length,
+        examples,
+      },
+    });
+  });
+}
+
+function editor(page: import("@playwright/test").Page) {
+  return page.locator(".cm-content");
+}
 
 test("opens a docs example: breadcrumb, framework picker, docs link", async ({ page }) => {
+  await installRouteFixtures(page);
   await page.goto(REACT_EXAMPLE);
 
   // The picker trigger shows "<breadcrumb> · <example title>" (no framework).
@@ -30,6 +176,7 @@ test("opens a docs example: breadcrumb, framework picker, docs link", async ({ p
 });
 
 test("cascader drills down and highlights the current selection", async ({ page }) => {
+  await installRouteFixtures(page);
   await page.goto(REACT_EXAMPLE);
   await page.getByRole("button", { name: /Adding and removing columns/ }).click();
 
@@ -42,17 +189,19 @@ test("cascader drills down and highlights the current selection", async ({ page
   await expect(page.getByText("Add and remove columns from the context menu", { exact: true })).toBeVisible();
 
   // Search narrows results.
-  await page.getByPlaceholder("Search examples…").fill("dropdown array of values");
-  await expect(page.getByText(/Dropdown cell type ▸ Array of values/).first()).toBeVisible();
+  await page.getByPlaceholder("Search examples…").fill("context menu");
+  await expect(page.getByText(/Adding and removing columns ▸ Add and remove columns/).first()).toBeVisible();
 });
 
 test("switching framework updates the URL", async ({ page }) => {
+  await installRouteFixtures(page);
   await page.goto(REACT_EXAMPLE);
   await page.getByRole("button", { name: "Vue", exact: true }).click();
   await expect(page).toHaveURL(/docs=guides%2Fcolumns%2Fcolumn-adding%2Fvue%2Fexample2\.vue/);
 });
 
 test("selecting an example from the cascader loads it", async ({ page }) => {
+  await installRouteFixtures(page);
   await page.goto("/?example=react"); // start on a starter
   await page.getByRole("button", { name: /React/ }).first().click(); // open picker
   await page.getByText("Columns", { exact: true }).click();
@@ -62,7 +211,8 @@ test("selecting an example from the cascader loads it", async ({ page }) => {
 });
 
 test("unresolved docs path shows a not-found screen, not the default starter", async ({ page }) => {
-  await page.goto("/?docs=guides/does/not/exist.tsx");
+  await installRouteFixtures(page, { missingPaths: ["guides/does/not/exist.tsx"] });
+  await page.goto("/?docs=guides/does/not/exist.tsx&v=18.0.0");
 
   await expect(page.getByText("Example not found")).toBeVisible();
   await expect(page.getByText("guides/does/not/exist.tsx")).toBeVisible();
@@ -73,6 +223,75 @@ test("unresolved docs path shows a not-found screen, not the default starter", a
   await expect(page.locator("iframe")).toHaveCount(0);
 });
 
+test("clean version switch replaces docs source from the target bucket", async ({ page }) => {
+  const requests: string[] = [];
+  await installRouteFixtures(page, { requests });
+  await page.goto(`/?docs=${DOCS_PATH}&v=18.0.0`);
+  await expect(editor(page)).toContainText(`18.0:${DOCS_PATH}`);
+
+  await page.getByLabel("Handsontable version", { exact: true }).selectOption(NEXT_VERSION);
+
+  await expect(editor(page)).toContainText(`next:${DOCS_PATH}`);
+  expect(requests).toContain(`/docs-examples/18.0/${DOCS_PATH.replace(/\//g, "__")}.json`);
+  expect(requests).toContain(`/docs-examples/next/${DOCS_PATH.replace(/\//g, "__")}.json`);
+});
+
+test("dirty version switch preserves edits, re-pins, and warns", async ({ page }) => {
+  await installRouteFixtures(page);
+  await page.goto(`/?docs=${DOCS_PATH}&v=18.0.0`);
+  await expect(editor(page)).toContainText(`18.0:${DOCS_PATH}`);
+  await editor(page).fill("export const userEdit = true;");
+
+  await page.getByLabel("Handsontable version", { exact: true }).selectOption(NEXT_VERSION);
+
+  await expect(editor(page)).toContainText("export const userEdit = true;");
+  await expect(page.getByText(/content may not match the selected version API/i)).toBeVisible();
+  await page.getByTitle("/package.json").click();
+  await expect(editor(page)).toContainText(`"handsontable": "${NEXT_VERSION}"`);
+});
+
+test("same docs path uses isolated next and release cache entries", async ({ page }) => {
+  const requests: string[] = [];
+  await installRouteFixtures(page, { latest: NEXT_VERSION, requests });
+  await page.goto(`/?docs=${DOCS_PATH}&v=${NEXT_VERSION}`);
+  await expect(editor(page)).toContainText(`next:${DOCS_PATH}`);
+
+  await page.getByLabel("Handsontable version", { exact: true }).selectOption("18.0.0");
+
+  await expect(editor(page)).toContainText(`18.0:${DOCS_PATH}`);
+  expect(requests.filter((path) => path.endsWith(`${DOCS_PATH.replace(/\//g, "__")}.json`))).toEqual([
+    `/docs-examples/next/${DOCS_PATH.replace(/\//g, "__")}.json`,
+    `/docs-examples/18.0/${DOCS_PATH.replace(/\//g, "__")}.json`,
+  ]);
+});
+
+test("a version without a bucket leaves only starters in the picker", async ({ page }) => {
+  const requests: string[] = [];
+  await installRouteFixtures(page, { requests });
+  await page.goto("/?example=react&v=17.1.0");
+  await page.getByRole("button", { name: /React/ }).first().click();
+
+  await expect(page.getByText("Starter templates", { exact: true })).toBeVisible();
+  await expect(page.getByText("Columns", { exact: true })).toHaveCount(0);
+  expect(requests).toContain("/docs-examples/17.1/manifest.json");
+});
+
+test("an open docs example with no target bucket stops preview and remains recoverable", async ({ page }) => {
+  await installRouteFixtures(page);
+  await page.goto(`/?docs=${DOCS_PATH}&v=18.0.0`);
+  await expect(editor(page)).toContainText(`18.0:${DOCS_PATH}`);
+
+  await page.getByLabel("Handsontable version", { exact: true }).selectOption("17.1.0");
+
+  await expect(page.getByText(/No documentation examples are available for Handsontable 17\.1\.0/).first()).toBeVisible();
+  await expect(page.locator("section[aria-label='Preview'] iframe")).toHaveAttribute("src", "about:blank");
+  await page.getByRole("button", { name: /React/ }).first().click();
+  await expect(page.getByText("Starter templates", { exact: true })).toBeVisible();
+  await page.getByText("Starter templates", { exact: true }).click();
+  const reactStarter = page.locator(".hot-casc-row").filter({ hasText: "React (Vite, TS)" });
+  await expect(reactStarter).not.toContainText("✓");
+});
+
 // Live render — needs the external Sandpack bundler; opt-in via E2E_LIVE=1.
 test("live: a JavaScript example renders a Handsontable grid", async ({ page }) => {
   test.skip(process.env.E2E_LIVE !== "1", "set E2E_LIVE=1 to run live-render checks");
diff --git a/runner/packages/runtime/src/docs-bucket.ts b/runner/packages/runtime/src/docs-bucket.ts
index db5da95c..51a0df67 100644
--- a/runner/packages/runtime/src/docs-bucket.ts
+++ b/runner/packages/runtime/src/docs-bucket.ts
@@ -1,9 +1,22 @@
+import { parse } from "semver";
+
 export interface DocsBucketResolution {
   selectedVersion: string;
   nextVersion: string;
   bucketKeys: Iterable<string>;
 }
 
+/** Derive the docs bucket key a selected version would use, if available. */
+export function deriveDocsBucketCandidate(
+  selectedVersion: string,
+  nextVersion: string,
+): string | null {
+  if (selectedVersion === nextVersion) return "next";
+
+  const version = parse(selectedVersion);
+  return version ? `${version.major}.${version.minor}` : null;
+}
+
 /**
  * Resolve a selected Handsontable version to an imported docs-example bucket.
  * Unmatched versions intentionally have no bucket; callers must not fall back
@@ -15,14 +28,6 @@ export function resolveDocsBucket({
   bucketKeys,
 }: DocsBucketResolution): string | null {
   const buckets = new Set(bucketKeys);
-
-  if (selectedVersion === nextVersion) {
-    return buckets.has("next") ? "next" : null;
-  }
-
-  const match = selectedVersion.match(/^(\d+)\.(\d+)(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?$/);
-  if (!match) return null;
-
-  const bucket = `${match[1]}.${match[2]}`;
-  return buckets.has(bucket) ? bucket : null;
+  const candidate = deriveDocsBucketCandidate(selectedVersion, nextVersion);
+  return candidate && buckets.has(candidate) ? candidate : null;
 }
diff --git a/runner/packages/runtime/src/index.ts b/runner/packages/runtime/src/index.ts
index edbb0397..0e29f056 100644
--- a/runner/packages/runtime/src/index.ts
+++ b/runner/packages/runtime/src/index.ts
@@ -19,6 +19,7 @@ export {
 export type { ValidationResult } from "./version.js";
 
 export {
+  deriveDocsBucketCandidate,
   resolveDocsBucket,
 } from "./docs-bucket.js";
 export type { DocsBucketResolution } from "./docs-bucket.js";
diff --git a/runner/pipeline/catalog-smoke.test.mjs b/runner/pipeline/catalog-smoke.test.mjs
index 110d5c41..b6c398de 100644
--- a/runner/pipeline/catalog-smoke.test.mjs
+++ b/runner/pipeline/catalog-smoke.test.mjs
@@ -11,55 +11,70 @@ import { fileURLToPath } from "node:url";
 const dir = path.dirname(fileURLToPath(import.meta.url));
 const OUT = path.resolve(dir, "..", "apps", "authoring", "public", "docs-examples");
 
-function loadManifest() {
-  return JSON.parse(fs.readFileSync(path.join(OUT, "manifest.json"), "utf8"));
+function loadBucketManifests() {
+  return fs.readdirSync(OUT, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => ({
+      bucketDir: path.join(OUT, entry.name),
+      manifest: JSON.parse(fs.readFileSync(path.join(OUT, entry.name, "manifest.json"), "utf8")),
+    }));
 }
 
-test("manifest exists and is well-formed", () => {
-  const m = loadManifest();
-  assert.ok(Array.isArray(m.examples), "examples is an array");
-  assert.ok(m.examples.length > 0, "has examples");
-  assert.equal(m.count, m.examples.length, "count matches examples length");
+test("bucket manifests exist and are well-formed", () => {
+  const buckets = loadBucketManifests();
+  assert.ok(buckets.length > 0, "has bucket manifests");
+  for (const { bucketDir, manifest: m } of buckets) {
+    const bucket = path.basename(bucketDir);
+    assert.equal(m.bucket, bucket, `${bucket}: bucket matches directory`);
+    assert.ok(Array.isArray(m.examples), `${bucket}: examples is an array`);
+    assert.ok(m.examples.length > 0, `${bucket}: has examples`);
+    assert.equal(m.count, m.examples.length, `${bucket}: count matches examples length`);
+  }
 });
 
 test("every manifest entry has the required metadata fields", () => {
-  const m = loadManifest();
-  const required = ["docsPath", "file", "framework", "exampleId", "exampleTitle", "breadcrumb", "docPermalink"];
+  const required = ["bucket", "docsPath", "file", "framework", "exampleId", "exampleTitle", "breadcrumb", "docPermalink"];
   const problems = [];
-  for (const e of m.examples) {
-    for (const f of required) {
-      if (e[f] === undefined || e[f] === null) problems.push(`${e.docsPath || "?"}: missing ${f}`);
+  for (const { bucketDir, manifest: m } of loadBucketManifests()) {
+    const bucket = path.basename(bucketDir);
+    for (const e of m.examples) {
+      for (const f of required) {
+        if (e[f] === undefined || e[f] === null) problems.push(`${bucket}/${e.docsPath || "?"}: missing ${f}`);
+      }
+      if (e.bucket !== bucket) problems.push(`${bucket}/${e.docsPath}: entry bucket is ${e.bucket}`);
+      if (Array.isArray(e.breadcrumb) && e.breadcrumb.length === 0) problems.push(`${bucket}/${e.docsPath}: empty breadcrumb`);
     }
-    if (Array.isArray(e.breadcrumb) && e.breadcrumb.length === 0) problems.push(`${e.docsPath}: empty breadcrumb`);
   }
   assert.equal(problems.length, 0, "field problems:\n" + problems.slice(0, 25).join("\n"));
 });
 
-test("every entry points at a valid, runnable artifact", () => {
-  const m = loadManifest();
+test("every bucket entry points at a bucket-local runnable artifact", () => {
   const problems = [];
-  for (const e of m.examples) {
-    const p = path.join(OUT, e.file);
-    if (!fs.existsSync(p)) { problems.push(`${e.docsPath}: artifact ${e.file} missing`); continue; }
-    let entry;
-    try {
-      entry = JSON.parse(fs.readFileSync(p, "utf8"));
-    } catch {
-      problems.push(`${e.docsPath}: artifact is not valid JSON`);
-      continue;
-    }
-    if (!entry.files || !entry.files["/package.json"]) {
-      problems.push(`${e.docsPath}: no /package.json in files`);
-    } else {
-      try { JSON.parse(entry.files["/package.json"]); }
-      catch { problems.push(`${e.docsPath}: /package.json is not valid JSON`); }
+  for (const { bucketDir, manifest: m } of loadBucketManifests()) {
+    const bucket = path.basename(bucketDir);
+    for (const e of m.examples) {
+      const p = path.join(bucketDir, e.file);
+      if (!fs.existsSync(p)) { problems.push(`${bucket}/${e.docsPath}: artifact ${e.file} missing`); continue; }
+      let entry;
+      try {
+        entry = JSON.parse(fs.readFileSync(p, "utf8"));
+      } catch {
+        problems.push(`${bucket}/${e.docsPath}: artifact is not valid JSON`);
+        continue;
+      }
+      if (!entry.files || !entry.files["/package.json"]) {
+        problems.push(`${bucket}/${e.docsPath}: no /package.json in files`);
+      } else {
+        try { JSON.parse(entry.files["/package.json"]); }
+        catch { problems.push(`${bucket}/${e.docsPath}: /package.json is not valid JSON`); }
+      }
+      const hasEntry =
+        entry.files &&
+        (entry.files[entry.entry] !== undefined ||
+          (entry.htmlEntry && entry.files[entry.htmlEntry] !== undefined));
+      if (!hasEntry) problems.push(`${bucket}/${e.docsPath}: entry ${entry.entry} / ${entry.htmlEntry} not among files`);
+      if (!["sandpack", "container"].includes(entry.engine)) problems.push(`${bucket}/${e.docsPath}: bad engine ${entry.engine}`);
     }
-    const hasEntry =
-      entry.files &&
-      (entry.files[entry.entry] !== undefined ||
-        (entry.htmlEntry && entry.files[entry.htmlEntry] !== undefined));
-    if (!hasEntry) problems.push(`${e.docsPath}: entry ${entry.entry} / ${entry.htmlEntry} not among files`);
-    if (!["sandpack", "container"].includes(entry.engine)) problems.push(`${e.docsPath}: bad engine ${entry.engine}`);
   }
   assert.equal(problems.length, 0, `${problems.length} artifact problems:\n` + problems.slice(0, 25).join("\n"));
 });
diff --git a/runner/pipeline/docs-bucket.test.mjs b/runner/pipeline/docs-bucket.test.mjs
index 638afe95..c9330404 100644
--- a/runner/pipeline/docs-bucket.test.mjs
+++ b/runner/pipeline/docs-bucket.test.mjs
@@ -1,6 +1,30 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { resolveDocsBucket } from "../packages/runtime/dist/docs-bucket.js";
+import {
+  deriveDocsBucketCandidate,
+  resolveDocsBucket,
+} from "../packages/runtime/dist/docs-bucket.js";
+
+test("derives next for an exact dist-tags.next version", () => {
+  assert.equal(
+    deriveDocsBucketCandidate("19.0.0-next.1", "19.0.0-next.1"),
+    "next",
+  );
+});
+
+test("derives major.minor for a valid semver release", () => {
+  assert.equal(
+    deriveDocsBucketCandidate("18.0.4", "19.0.0-next.1"),
+    "18.0",
+  );
+});
+
+test("returns null candidate for a malformed selected version", () => {
+  assert.equal(
+    deriveDocsBucketCandidate("not-a-version", "19.0.0-next.1"),
+    null,
+  );
+});
 
 test("selects next only for an exact dist-tags.next version", () => {
   assert.equal(