✨ Show experimental APIs on the API docs (#1200)

Surface symbols exported from the package's `./experimental` entrypoint in the
API Reference section:

- `/api` index lists a stable release's experimental symbols inline with an
  "experimental" badge (none for 4.0.3 today; appears when a stable release
  exports `./experimental`). The prerelease's experimental APIs are reached via
  the "next" toggle / its symbol pages.
- Experimental symbol pages live at `/api/:series/experimental/:symbol` with an
  "Experimental" banner; the sidebar lists stable + experimental symbols with
  badges, resolving each link to the correct (flat vs namespaced) URL.
- Version toggle gains a "next" entry for the prerelease when it's newer than
  its stable parent and documents the current symbol; the active entry is
  derived from the page's own series.

The "experimental" signal is entrypoint membership (`DocPage.experimental`, set
in `package.ts`). Stable pages, older series, and search are unaffected.

Author: taras

www/components/api/api-page.tsx

@@ -1,31 +1,50 @@
-import { all } from "effection";
+import { all, type Operation } from "effection";
 import type { JSXElement } from "revolution";
 import { useConfig } from "../../context/config.ts";
 import { LocalDocPage } from "../../hooks/use-deno-doc.tsx";
 import { ResolveLinkFunction, useMarkdown } from "../../hooks/use-markdown.tsx";
 import { Package, usePackage } from "../../lib/package.ts";
-import { major } from "../../lib/semver.ts";
-import { createRootUrl, createSibling } from "../../lib/links-resolvers.ts";
+import { gt, major } from "../../lib/semver.ts";
+import { createRootUrl } from "../../lib/links-resolvers.ts";
 import { SourceCodeIcon } from "../icons/source-code.tsx";
 import { GithubPill } from "../package/source-link.tsx";
-import { Icon } from "../type/icon.tsx";
+import { ExperimentalBadge, Icon } from "../type/icon.tsx";
 import { Type } from "../type/jsx.tsx";
 import { Keyword } from "../type/tokens.tsx";
 
+/**
+ * Root-based URL for a symbol's doc page. Experimental symbols live under a
+ * `/experimental` segment, so linking cannot be relative to the current page
+ * (which would resolve into or out of the wrong namespace).
+ */
+function* pageHref(
+  seriesName: string,
+  page: LocalDocPage,
+): Operation<string> {
+  let base = page.experimental
+    ? `api/${seriesName}/experimental`
+    : `api/${seriesName}`;
+  return yield* createRootUrl(base)(page.name);
+}
+
 export function* ApiPage({
   pages,
   current,
+  currentExperimental = false,
+  seriesName,
   pkg,
-  externalLinkResolver,
   banner,
 }: {
   current: string;
+  currentExperimental?: boolean;
+  seriesName: string;
   pages: LocalDocPage[];
   pkg: Package;
   banner?: JSXElement;
-  externalLinkResolver: ResolveLinkFunction;
 }) {
-  const page = pages.find((node) => node.name === current);
+  const page = pages.find((node) =>
+    node.name === current && !!node.experimental === currentExperimental
+  );
 
   if (!page) throw new Error(`Could not find a doc page for ${current}`);
 
@@ -38,11 +57,9 @@ export function* ApiPage({
       pages.find((page) => page.name === symbol);
 
     if (target) {
-      return `[${
-        [symbol, connector, method].join(
-          "",
-        )
-      }](${yield* externalLinkResolver(symbol, connector, method)})`;
+      let href = yield* pageHref(seriesName, target);
+      if (connector && method) href = `${href}#${method}`;
+      return `[${[symbol, connector, method].join("")}](${href})`;
     } else {
       return symbol;
     }
@@ -53,6 +70,8 @@ export function* ApiPage({
       {yield* ApiReference({
         pages,
         current,
+        currentExperimental,
+        seriesName,
         pkg,
         content: (
           <>
@@ -61,36 +80,53 @@ export function* ApiPage({
             {yield* ApiBody({ page, linkResolver })}
           </>
         ),
-        linkResolver: createSibling,
         versionToggle: yield* (function* () {
           const { series } = yield* useConfig();
-          // Only show stable series in version toggle (no prereleases)
-          const stableSeries = series.filter((s) => !s.includePrerelease);
-          const currentSeries = `v${major(pkg.version)}`;
+          const entrypoint = currentExperimental ? "./experimental" : ".";
+          const suffix = currentExperimental ? "/experimental" : "";
 
+          // Toggle across every series that documents the current symbol:
+          // stable releases show their version (e.g. 3.6.1, 4.0.3), and the
+          // prerelease shows as "next" — but only when it's actually newer
+          // than its stable parent (otherwise there's nothing to switch to).
           const links = yield* all(
-            stableSeries.map(function* (s) {
+            series.map(function* (s) {
               const seriesPkg = yield* usePackage({
                 type: "worktree",
                 series: s.name,
               });
+
+              if (s.includePrerelease) {
+                const parent = series.find((p) => p.name === s.parent);
+                if (parent) {
+                  const parentPkg = yield* usePackage({
+                    type: "worktree",
+                    series: parent.name,
+                  });
+                  if (!gt(seriesPkg.version, parentPkg.version)) return null;
+                }
+              }
+
               const seriesDocs = yield* seriesPkg.docs();
-              const hasSymbol = seriesDocs["."].some((node) =>
+              const hasSymbol = (seriesDocs[entrypoint] ?? []).some((node) =>
                 node.name === current
               );
 
               if (!hasSymbol) return null;
 
+              const isCurrent = s.name === seriesName;
+              const label = s.includePrerelease ? "next" : seriesPkg.version;
+
               return (
                 <a
-                  href={yield* createRootUrl(`api/${s.name}`)(current)}
+                  href={yield* createRootUrl(`api/${s.name}${suffix}`)(current)}
                   class={`text-base ${
-                    s.name === currentSeries
+                    isCurrent
                       ? "font-bold text-sky-500"
                       : "text-gray-600 dark:text-gray-400 hover:text-sky-500"
                   }`}
                 >
-                  {seriesPkg.version}
+                  {label}
                 </a>
               );
             }),
@@ -153,15 +189,17 @@ export function* ApiReference({
   pkg,
   content,
   current,
+  currentExperimental,
+  seriesName,
   pages,
-  linkResolver,
   versionToggle,
 }: {
   pkg: Package;
   content: JSXElement;
   current: string;
+  currentExperimental: boolean;
+  seriesName: string;
   pages: LocalDocPage[];
-  linkResolver: ResolveLinkFunction;
   versionToggle: JSXElement;
 }) {
   return (
@@ -172,7 +210,7 @@ export function* ApiReference({
             <span class="font-bold">API Reference</span>
             {versionToggle}
           </h3>
-          {yield* Menu({ pages, current, linkResolver })}
+          {yield* Menu({ pages, current, currentExperimental, seriesName })}
         </nav>
       </aside>
       <article
@@ -210,30 +248,36 @@ export function* SymbolHeader(
 function* Menu({
   pages,
   current,
-  linkResolver,
+  currentExperimental,
+  seriesName,
 }: {
   current: string;
+  currentExperimental: boolean;
+  seriesName: string;
   pages: LocalDocPage[];
-  linkResolver: ResolveLinkFunction;
 }) {
   const elements = [];
   for (const page of pages.sort((a, b) => a.name.localeCompare(b.name))) {
+    const isCurrent = current === page.name &&
+      !!page.experimental === currentExperimental;
     elements.push(
       <li>
-        {current === page.name
+        {isCurrent
           ? (
             <span class="rounded px-2 block w-full py-2 bg-gray-100 dark:bg-gray-700 cursor-default ">
               <Icon kind={page.kind} />
               {page.name}
+              {page.experimental ? <ExperimentalBadge class="ml-1" /> : ""}
             </span>
           )
           : (
             <a
               class="rounded px-2 block w-full py-2 hover:bg-gray-100 dark:hover:bg-gray-800"
-              href={yield* linkResolver(page.name)}
+              href={yield* pageHref(seriesName, page)}
             >
               <Icon kind={page.kind} />
               {page.name}
+              {page.experimental ? <ExperimentalBadge class="ml-1" /> : ""}
             </a>
           )}
       </li>,

www/components/type/icon.tsx

@@ -44,3 +44,20 @@ export function Icon(props: { kind: string; class?: string }) {
   }
   return <></>;
 }
+
+/**
+ * A small pill marking a symbol that is exported from the package's
+ * `./experimental` entrypoint. Rendered inline next to a symbol's name.
+ */
+export function ExperimentalBadge(props: { class?: string }) {
+  return (
+    <span
+      class={`${
+        props.class ? props.class : ""
+      } inline-block align-middle rounded bg-amber-100 dark:bg-amber-900 px-1.5 text-xs font-medium text-amber-800 dark:text-amber-200`}
+      title="Experimental API — may change or be removed in a future release"
+    >
+      experimental
+    </span>
+  );
+}

www/hooks/use-deno-doc.tsx

@@ -51,6 +51,11 @@ export interface DocPage {
   description: string;
   kind: DocNode["kind"];
   dependencies: Dependency[];
+  /**
+   * True when this symbol is exported from the package's `./experimental`
+   * entrypoint. Drives the "experimental" badge and the namespaced doc URL.
+   */
+  experimental?: boolean;
 }
 
 export interface DocPageSection {

www/lib/package.ts

@@ -166,6 +166,7 @@ function* initPackage(
         docs[entrypoint] = pages[`${url}`].map((page) => {
           return {
             ...page,
+            experimental: entrypoint === "./experimental",
             sections: page.sections.map((section) => ({
               ...section,
               node: {

www/main.tsx

@@ -86,6 +86,17 @@ if (import.meta.main) {
             apiReferenceRoute(s.name, { search: true }),
           )
         ),
+        // Experimental API docs (namespaced; empty for series without the
+        // `./experimental` entrypoint)
+        ...series.map((s) =>
+          route(
+            `/api/${s.name}/experimental/:symbol`,
+            apiReferenceRoute(s.name, {
+              search: true,
+              entrypoint: "./experimental",
+            }),
+          )
+        ),
         route("/blog", blogIndexRoute({ search: true })),
         route("/blog/feed.xml", blogFeedRoute()),
         route("/llms.txt", llmsTxtRoute()),

www/routes/api-index-route.tsx

@@ -1,6 +1,6 @@
 import { type JSXElement } from "revolution";
 
-import { Icon } from "../components/type/icon.tsx";
+import { ExperimentalBadge, Icon } from "../components/type/icon.tsx";
 import { DocPage } from "../hooks/use-deno-doc.tsx";
 import { ResolveLinkFunction } from "../hooks/use-markdown.tsx";
 import { usePackage } from "../lib/package.ts";
@@ -35,8 +35,10 @@ export function apiIndexRoute(
       // Only show prerelease link if it's newer than stable
       let showV4Prerelease = gt(v4Next.version, v4.version);
 
-      // Get first symbol for prerelease link
-      let v4NextDocs = showV4Prerelease ? yield* v4Next.docs() : null;
+      // v4-next docs feed the "also available" prerelease link. The
+      // prerelease's own experimental APIs are surfaced when you click through
+      // to its symbol pages (their sidebar lists them, badged).
+      let v4NextDocs = yield* v4Next.docs();
       let v4NextFirstSymbol = v4NextDocs?.["."]?.[0]?.name ?? "run";
 
       let docs = {
@@ -77,8 +79,20 @@ export function apiIndexRoute(
               </h3>
               <ul class="columns-3 pl-0">
                 {yield* listPages({
-                  pages: docs.v4["."],
-                  linkResolver: createChildURL("v4"),
+                  groups: [
+                    {
+                      pages: docs.v4["."],
+                      linkResolver: createChildURL("v4"),
+                      experimental: false,
+                    },
+                    {
+                      // Experimental APIs for the stable release itself (empty
+                      // until a stable version exports `./experimental`).
+                      pages: docs.v4["./experimental"] ?? [],
+                      linkResolver: createChildURL("v4/experimental"),
+                      experimental: true,
+                    },
+                  ],
                 })}
               </ul>
             </section>
@@ -95,8 +109,18 @@ export function apiIndexRoute(
               </h3>
               <ul class="columns-3 pl-0">
                 {yield* listPages({
-                  pages: docs.v3["."],
-                  linkResolver: createChildURL("v3"),
+                  groups: [
+                    {
+                      pages: docs.v3["."],
+                      linkResolver: createChildURL("v3"),
+                      experimental: false,
+                    },
+                    {
+                      pages: docs.v3["./experimental"] ?? [],
+                      linkResolver: createChildURL("v3/experimental"),
+                      experimental: true,
+                    },
+                  ],
                 })}
               </ul>
             </section>
@@ -107,23 +131,35 @@ export function apiIndexRoute(
   };
 }
 
-function* listPages({
-  pages,
-  linkResolver,
-}: {
+interface PageGroup {
   pages: DocPage[];
   linkResolver: ResolveLinkFunction;
-}) {
-  let elements = [];
+  experimental: boolean;
+}
+
+function* listPages({ groups }: { groups: PageGroup[] }) {
+  // Resolve links first (linkResolver is an Operation), then merge every
+  // group into a single alphabetically-sorted list so experimental symbols
+  // sit inline with stable ones, each carrying its own badge and link.
+  let items: Array<{ page: DocPage; link: string; experimental: boolean }> = [];
+  for (let group of groups) {
+    for (let page of group.pages) {
+      let link = yield* group.linkResolver(page.name);
+      items.push({ page, link, experimental: group.experimental });
+    }
+  }
+
+  items.sort((a, b) => a.page.name.localeCompare(b.page.name));
 
-  for (let page of pages.sort((a, b) => a.name.localeCompare(b.name))) {
-    let link = yield* linkResolver(page.name);
+  let elements = [];
+  for (let { page, link, experimental } of items) {
     elements.push(
       <li class="list-none pb-1">
         <a class="text-blue-700 dark:text-blue-400" href={link}>
           <Icon kind={page.kind} class="mr-2" />
           {page.name}
         </a>
+        {experimental ? <ExperimentalBadge class="ml-2" /> : ""}
       </li>,
     );
   }