radiant-docs 0.1.63 → 0.1.65

package/template/src/components/endpoint/RequestSnippets.astro

@@ -507,7 +507,11 @@ const hasMultipleRequests = requestSnippetItems.length > 1;
       class="flex h-full min-h-0 w-full max-w-full min-w-0 flex-col rounded-xl"
     >
       <div
-        class="flex items-center justify-between gap-2"
+        class:list={[
+          "flex items-center justify-between gap-2",
+          !hasMultipleRequests &&
+            "border-b-[0.5px] border-(--rd-code-tab-edge-border)",
+        ]}
       >
         {
           hasMultipleRequests ? (
@@ -597,6 +601,7 @@ const hasMultipleRequests = requestSnippetItems.length > 1;
         class:list={[
           "relative min-h-0 min-w-0 flex-1 overflow-hidden rounded-b-xl border-[0.5px] border-(--rd-code-tab-edge-border) bg-(--rd-code-surface)",
           hasMultipleRequests && "rounded-tl-xl",
+          !hasMultipleRequests && "border-t-0",
         ]}
       >
         <div

package/template/src/components/endpoint/ResponseDisplay.astro

@@ -74,7 +74,7 @@ import { Icon } from "astro-icon/components";
     <div
       class="flex h-full min-h-0 w-full max-w-full min-w-0 flex-col rounded-xl"
     >
-      <div class="flex items-center justify-between gap-2">
+      <div class="relative z-10 flex items-center justify-between gap-2">
         <div class="min-w-0 flex-1 overflow-hidden rounded-t-xl">
           <div
             x-ref="tabList"
@@ -143,7 +143,7 @@ import { Icon } from "astro-icon/components";
         >
           <div x-show="selected === 'body'" class="h-full">
             <div
-              x-show="!response || !response.highlightedData"
+              x-show="!response || (!response.highlightedData && !response.bodyObjectUrl)"
               class="text-sm px-4 py-4 xs:py-8 flex flex-col items-center justify-center h-full text-foreground"
             >
               <div class="p-2 rounded-xl mb-1">
@@ -163,6 +163,113 @@ import { Icon } from "astro-icon/components";
               <pre
                 class="relative m-0 min-w-full p-0 text-[13px] leading-6"><code data-rd-code-theme class="block min-w-full py-2.5 font-mono text-neutral-800 dark:text-neutral-200" x-html="response?.highlightedData" /></pre>
             </div>
+            <div
+              x-show="response?.bodyKind === 'media'"
+              x-cloak
+              class="min-h-full p-4"
+            >
+              <div class="mb-4 flex flex-wrap items-center justify-between gap-3">
+                <div class="min-w-0">
+                  <div
+                    class="truncate text-sm font-medium text-neutral-900 dark:text-neutral-100"
+                    x-text="response?.bodyFilename || 'Response media'"
+                  >
+                  </div>
+                  <div class="mt-0.5 flex flex-wrap items-center gap-x-2 gap-y-1 text-xs text-neutral-500 dark:text-neutral-400">
+                    <span x-text="response?.bodyContentType || 'Binary response'">
+                    </span>
+                    <span x-show="response?.bodySizeLabel" aria-hidden="true">
+                      /
+                    </span>
+                    <span x-text="response?.bodySizeLabel"></span>
+                  </div>
+                </div>
+                <a
+                  x-bind:href="response?.bodyObjectUrl"
+                  x-bind:download="response?.bodyFilename || 'response'"
+                  class="inline-flex h-8 shrink-0 items-center gap-1.5 rounded-lg border border-neutral-200 bg-white px-2.5 text-xs font-medium text-neutral-700 shadow-xs transition-colors hover:bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-950 dark:text-neutral-300 dark:hover:bg-neutral-900"
+                >
+                  <Icon class="size-3.5" name="lucide:download" />
+                  Download
+                </a>
+              </div>
+
+              <div
+                x-show="response?.mediaKind === 'audio'"
+                x-cloak
+                class="flex min-h-28 items-center"
+              >
+                <audio
+                  class="w-full"
+                  controls
+                  preload="metadata"
+                  x-bind:src="response?.bodyObjectUrl"
+                >
+                </audio>
+              </div>
+
+              <div
+                x-show="response?.mediaKind === 'image'"
+                x-cloak
+                class="flex min-h-48 items-start justify-center"
+              >
+                <img
+                  class="max-h-[min(60dvh,32rem)] max-w-full rounded-lg object-contain"
+                  x-bind:src="response?.bodyObjectUrl"
+                  x-bind:alt="response?.bodyFilename || 'Response image'"
+                />
+              </div>
+
+              <div
+                x-show="response?.mediaKind === 'video'"
+                x-cloak
+                class="flex min-h-48 items-start justify-center"
+              >
+                <video
+                  class="max-h-[min(60dvh,32rem)] max-w-full rounded-lg"
+                  controls
+                  preload="metadata"
+                  x-bind:src="response?.bodyObjectUrl"
+                >
+                </video>
+              </div>
+            </div>
+
+            <div
+              x-show="response?.bodyKind === 'binary'"
+              x-cloak
+              class="flex min-h-full items-center justify-center p-4"
+            >
+              <div class="flex w-full max-w-md flex-col items-center text-center">
+                <div class="mb-3 rounded-xl bg-neutral-100 p-3 dark:bg-neutral-900">
+                  <Icon
+                    class="size-6 text-neutral-500 dark:text-neutral-400"
+                    name="lucide:file-down"
+                  />
+                </div>
+                <div
+                  class="max-w-full truncate text-sm font-medium text-neutral-900 dark:text-neutral-100"
+                  x-text="response?.bodyFilename || 'Binary response'"
+                >
+                </div>
+                <div class="mt-1 flex max-w-full flex-wrap justify-center gap-x-2 gap-y-1 text-xs text-neutral-500 dark:text-neutral-400">
+                  <span x-text="response?.bodyContentType || 'application/octet-stream'">
+                  </span>
+                  <span x-show="response?.bodySizeLabel" aria-hidden="true">
+                    /
+                  </span>
+                  <span x-text="response?.bodySizeLabel"></span>
+                </div>
+                <a
+                  x-bind:href="response?.bodyObjectUrl"
+                  x-bind:download="response?.bodyFilename || 'response'"
+                  class="mt-4 inline-flex h-8 items-center gap-1.5 rounded-lg border border-neutral-200 bg-white px-2.5 text-xs font-medium text-neutral-700 shadow-xs transition-colors hover:bg-neutral-50 dark:border-neutral-800 dark:bg-neutral-950 dark:text-neutral-300 dark:hover:bg-neutral-900"
+                >
+                  <Icon class="size-3.5" name="lucide:download" />
+                  Download
+                </a>
+              </div>
+            </div>
           </div>
 
           <div x-show="selected === 'header'" x-cloak class="h-full">

package/template/src/components/endpoint/ResponseFieldTree.astro

@@ -71,7 +71,7 @@ function countImmediateChildren(field: ResponseField): number {
             exclusiveMaximum={field.exclusiveMaximum}
           />
           {hasExpandableContent && (
-            <div class="mt-2.5 w-full overflow-hidden rounded-lg border-[0.5px] border-neutral-900/8 bg-white shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] transition-colors duration-200 dark:border-white/6 dark:bg-(--rd-code-surface) dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]">
+            <div class="mt-2.5 w-full overflow-hidden rounded-lg border-[0.5px] border-neutral-900/8 bg-neutral-50/50 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] transition-colors duration-200 dark:border-white/6 dark:bg-(--rd-code-surface) dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]">
               <button
                 type="button"
                 x-on:click="expanded = !expanded"

package/template/src/components/endpoint/ResponseFields.astro

@@ -2,6 +2,11 @@
 import type { OpenAPIV3, OpenAPIV3_1 } from "openapi-types";
 import ListChevronsToggle from "../ui/ListChevronsToggle.astro";
 import ResponseFieldTree from "./ResponseFieldTree.astro";
+import { getSchemaVariantLabel } from "../../lib/openapi/schema-variant-labels";
+import {
+  getBinaryResponseSummary,
+  type OpenApiBinaryResponseSummary,
+} from "../../lib/openapi/response-content";
 
 interface Props {
   responses: OpenAPIV3.ResponsesObject | OpenAPIV3_1.ResponsesObject;
@@ -39,6 +44,7 @@ interface ResponseData {
   fields: ResponseField[];
   variants?: ResponseVariant[];
   variantType?: "oneOf" | "anyOf";
+  binarySummary?: OpenApiBinaryResponseSummary;
 }
 
 function getStatusCodeDotClass(statusCode: string): string {
@@ -82,7 +88,9 @@ function getSchemaEnumValues(schema: any): (string | number)[] | undefined {
 }
 
 function parseFiniteNumber(value: unknown): number | undefined {
-  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+  return typeof value === "number" && Number.isFinite(value)
+    ? value
+    : undefined;
 }
 
 function parseNonNegativeInteger(value: unknown): number | undefined {
@@ -182,7 +190,10 @@ function mergeConjunctiveNumericConstraints(
     if (!second) return first;
     if (first.value > second.value) return first;
     if (second.value > first.value) return second;
-    return { value: first.value, exclusive: first.exclusive || second.exclusive };
+    return {
+      value: first.value,
+      exclusive: first.exclusive || second.exclusive,
+    };
   };
   const pickStricterUpper = (
     first?: { value: number; exclusive: boolean },
@@ -192,7 +203,10 @@ function mergeConjunctiveNumericConstraints(
     if (!second) return first;
     if (first.value < second.value) return first;
     if (second.value < first.value) return second;
-    return { value: first.value, exclusive: first.exclusive || second.exclusive };
+    return {
+      value: first.value,
+      exclusive: first.exclusive || second.exclusive,
+    };
   };
 
   const lower = pickStricterLower(toLowerBound(base), toLowerBound(next));
@@ -438,6 +452,23 @@ function getAdditionalPropertiesSchema(schema: any): any {
   return additionalProperties;
 }
 
+function getSchemaObjectProperties(schema: any): Record<string, any> {
+  if (!schema || typeof schema !== "object") return {};
+
+  let properties: Record<string, any> = {};
+  if (schema.properties && typeof schema.properties === "object") {
+    properties = { ...properties, ...schema.properties };
+  }
+
+  if (Array.isArray(schema.allOf)) {
+    schema.allOf.forEach((part: any) => {
+      properties = { ...properties, ...getSchemaObjectProperties(part) };
+    });
+  }
+
+  return properties;
+}
+
 function extractVariantData(
   schema: any,
   parentName: string,
@@ -458,7 +489,12 @@ function extractVariantData(
 
   const variants = variantSchemas
     .map((variantSchema: any, index: number) => ({
-      label: `Variant ${index + 1}`,
+      label: getSchemaVariantLabel(variantSchema, index, {
+        parentSchema: schema,
+        siblings: variantSchemas,
+        getObjectProperties: getSchemaObjectProperties,
+        getTypeLabel: getSchemaTypeLabel,
+      }),
       fields: extractFieldsFromSchema(
         variantSchema,
         parentName,
@@ -568,7 +604,9 @@ function extractFieldsFromSchema(
           const nestedFields = extractFieldsFromSchema(
             basePropSchema,
             fullName,
-            Array.isArray(basePropSchema.required) ? basePropSchema.required : [],
+            Array.isArray(basePropSchema.required)
+              ? basePropSchema.required
+              : [],
           );
           fields.push({
             name: fullName,
@@ -591,7 +629,9 @@ function extractFieldsFromSchema(
           const itemFields = extractFieldsFromSchema(
             baseItemSchema,
             `${fullName}[]`,
-            Array.isArray(baseItemSchema.required) ? baseItemSchema.required : [],
+            Array.isArray(baseItemSchema.required)
+              ? baseItemSchema.required
+              : [],
           );
           const itemVariantData = extractVariantData(
             itemSchema,
@@ -643,14 +683,18 @@ function extractFieldsFromSchema(
       ? extractFieldsFromSchema(
           additionalSchema,
           mapFieldName,
-          Array.isArray(additionalSchema?.required) ? additionalSchema.required : [],
+          Array.isArray(additionalSchema?.required)
+            ? additionalSchema.required
+            : [],
         )
       : [];
     const additionalVariantData = additionalSchema
       ? extractVariantData(
           additionalSchema,
           mapFieldName,
-          Array.isArray(additionalSchema?.required) ? additionalSchema.required : [],
+          Array.isArray(additionalSchema?.required)
+            ? additionalSchema.required
+            : [],
         )
       : {};
 
@@ -664,7 +708,9 @@ function extractFieldsFromSchema(
       nested: additionalContent.length > 0 ? additionalContent : undefined,
       variants: additionalVariantData.variants,
       variantType: additionalVariantData.variantType,
-      enum: additionalSchema ? getSchemaEnumValues(additionalSchema) : undefined,
+      enum: additionalSchema
+        ? getSchemaEnumValues(additionalSchema)
+        : undefined,
     });
   }
 
@@ -688,10 +734,13 @@ Object.entries(responses)
     return numA - numB;
   })
   .forEach(([statusCode, response]: [string, any]) => {
+    const binarySummary = getBinaryResponseSummary(response);
     // Try to get application/json content first
-    const contentType = response.content?.["application/json"]
-      ? "application/json"
-      : Object.keys(response.content || {})[0];
+    const contentType =
+      binarySummary?.contentTypes[0] ||
+      (response.content?.["application/json"]
+        ? "application/json"
+        : Object.keys(response.content || {})[0]);
 
     const mediaType = contentType ? response.content?.[contentType] : null;
     const schema = mediaType?.schema;
@@ -700,7 +749,7 @@ Object.entries(responses)
     let variants: ResponseVariant[] | undefined;
     let variantType: "oneOf" | "anyOf" | undefined;
 
-    if (schema) {
+    if (schema && !binarySummary) {
       const hasOneOf = Array.isArray(schema.oneOf) && schema.oneOf.length > 0;
       const hasAnyOf = Array.isArray(schema.anyOf) && schema.anyOf.length > 0;
 
@@ -720,7 +769,12 @@ Object.entries(responses)
 
         variants = variantSchemas
           .map((variantSchema, index) => ({
-            label: `Variant ${index + 1}`,
+            label: getSchemaVariantLabel(variantSchema, index, {
+              parentSchema: schema,
+              siblings: variantSchemas,
+              getObjectProperties: getSchemaObjectProperties,
+              getTypeLabel: getSchemaTypeLabel,
+            }),
             fields: extractFieldsFromSchema(
               variantSchema,
               "",
@@ -739,6 +793,7 @@ Object.entries(responses)
       fields,
       variants,
       variantType,
+      binarySummary,
     });
   });
 ---
@@ -769,12 +824,12 @@ Object.entries(responses)
         {response.fields.length > 0 && (
           <>
             {response.variants && response.variants.length > 0 && (
-              <p class="mb-2 text-xs text-neutral-500 dark:text-neutral-400">Common fields</p>
+              <p class="mb-2 text-xs text-neutral-500 dark:text-neutral-400">
+                Common fields
+              </p>
             )}
             <div x-data="{ expanded: true }">
-              <div
-                class="w-full overflow-hidden rounded-xl border-[0.5px] border-neutral-900/8 bg-white shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] transition-colors duration-200 dark:border-white/6 dark:bg-(--rd-code-surface) dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]"
-              >
+              <div class="w-full overflow-hidden rounded-xl border-[0.5px] border-neutral-900/12 bg-neutral-50/50 shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] transition-colors duration-200 dark:border-white/6 dark:bg-(--rd-code-surface) dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]">
                 <button
                   type="button"
                   x-on:click="expanded = !expanded"
@@ -785,9 +840,7 @@ Object.entries(responses)
                     <ListChevronsToggle class="size-4 shrink-0 text-neutral-500 group-hover:text-neutral-600 transition duration-200 dark:text-neutral-500 dark:group-hover:text-neutral-300" />
                     <span>
                       {response.fields.length}{" "}
-                      {response.fields.length === 1
-                        ? "field"
-                        : "fields"}
+                      {response.fields.length === 1 ? "field" : "fields"}
                     </span>
                   </span>
                 </button>
@@ -814,9 +867,7 @@ Object.entries(responses)
                     {variant.label}
                   </div>
                   <div x-data="{ expanded: true }">
-                    <div
-                      class="w-full overflow-hidden rounded-lg border-[0.5px] border-neutral-900/8 bg-white shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] transition-colors duration-200 dark:border-white/6 dark:bg-(--rd-code-surface) dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]"
-                    >
+                    <div class="w-full overflow-hidden rounded-lg border-[0.5px] border-neutral-900/8 bg-white shadow-[0_.5px_1px_rgba(0,0,0,0.15),0_5px_12px_-6px_rgba(0,0,0,0.08)] transition-colors duration-200 dark:border-white/6 dark:bg-(--rd-code-surface) dark:shadow-[0_-.5px_1px_rgba(255,255,255,0.15),0_5px_12px_-6px_rgba(0,0,0,0.2)]">
                       <button
                         type="button"
                         x-on:click="expanded = !expanded"
@@ -827,9 +878,7 @@ Object.entries(responses)
                           <ListChevronsToggle class="size-4 shrink-0 text-neutral-400 group-hover:text-neutral-600 transition duration-200 dark:text-neutral-500 dark:group-hover:text-neutral-300" />
                           <span>
                             {variant.fields.length}{" "}
-                            {variant.fields.length === 1
-                              ? "field"
-                              : "fields"}
+                            {variant.fields.length === 1 ? "field" : "fields"}
                           </span>
                         </span>
                       </button>
@@ -857,7 +906,27 @@ Object.entries(responses)
         )}
         {response.fields.length === 0 &&
         (!response.variants || response.variants.length === 0) ? (
-          <p class="text-sm text-neutral-500 ml-2 dark:text-neutral-400">No response body fields</p>
+          response.binarySummary ? (
+            <div class="ml-2 space-y-2 text-sm">
+              <div class="font-medium text-neutral-800 dark:text-neutral-200">
+                {response.binarySummary.title}
+              </div>
+              <p class="text-neutral-500 dark:text-neutral-400">
+                {response.binarySummary.description}
+              </p>
+              <div class="flex flex-wrap gap-1.5">
+                {response.binarySummary.contentTypes.map((contentType) => (
+                  <code class="rounded-sm border border-neutral-900/4 bg-neutral-100/80 px-[5px] py-[2px] font-mono text-[11px] leading-none text-neutral-700/90 dark:border-white/3 dark:bg-neutral-800/90 dark:text-neutral-200/90">
+                    {contentType}
+                  </code>
+                ))}
+              </div>
+            </div>
+          ) : (
+            <p class="text-sm text-neutral-500 ml-2 dark:text-neutral-400">
+              No structured response body fields
+            </p>
+          )
         ) : null}
       </div>
     ))

package/template/src/components/endpoint/ResponseSnippets.astro

@@ -8,6 +8,7 @@ import {
   getCodeLineTokens,
   normalizeCodeLanguageValue,
 } from "../../lib/code/code-block";
+import { getBinaryResponseSummary } from "../../lib/openapi/response-content";
 
 interface Props {
   responses: OpenAPIV3.ResponsesObject | OpenAPIV3_1.ResponsesObject;
@@ -20,19 +21,23 @@ const sampledResponses: Array<{
   description: string;
   example?: unknown;
   contentType?: string;
+  binarySummaryText?: string;
 }> = [];
 
 Object.entries(responses).forEach(([statusCode, response]: [string, any]) => {
+  const binarySummary = getBinaryResponseSummary(response);
   const contentTypes = Object.keys(response.content || {});
-  const contentType = response.content?.["application/json"]
-    ? "application/json"
-    : contentTypes[0];
+  const contentType =
+    binarySummary?.contentTypes[0] ||
+    (response.content?.["application/json"] ? "application/json" : contentTypes[0]);
 
   const mediaType = contentType ? response.content?.[contentType] : null;
   const schema = mediaType?.schema;
 
   let example: unknown = undefined;
-  if (schema) {
+  if (binarySummary) {
+    example = binarySummary.snippetText;
+  } else if (schema) {
     try {
       example = Sampler.sample(schema as JSONSchema7, {
         skipReadOnly: false,
@@ -47,6 +52,7 @@ Object.entries(responses).forEach(([statusCode, response]: [string, any]) => {
     description: response.description ?? "",
     example,
     contentType,
+    binarySummaryText: binarySummary?.snippetText,
   });
 });
 
@@ -194,11 +200,12 @@ const responseSnippetItems = await Promise.all(
       ? "json"
       : "plaintext";
     const code =
-      response.example === undefined
+      response.binarySummaryText ??
+      (response.example === undefined
         ? "This response has no body data."
         : typeof response.example === "string"
           ? response.example
-          : JSON.stringify(response.example, null, 2);
+          : JSON.stringify(response.example, null, 2));
 
     return {
       statusCode: response.statusCode,
@@ -430,7 +437,11 @@ const hasMultipleResponses = responseSnippetItems.length > 1;
       class="flex h-full min-h-0 w-full max-w-full min-w-0 flex-col rounded-xl"
     >
       <div
-        class="flex items-center justify-between gap-2"
+        class:list={[
+          "flex items-center justify-between gap-2",
+          !hasMultipleResponses &&
+            "border-b-[0.5px] border-(--rd-code-tab-edge-border)",
+        ]}
       >
         {
           hasMultipleResponses ? (
@@ -517,6 +528,7 @@ const hasMultipleResponses = responseSnippetItems.length > 1;
         class:list={[
           "relative min-h-0 min-w-0 flex-1 overflow-hidden rounded-b-xl border-[0.5px] border-(--rd-code-tab-edge-border) bg-(--rd-code-surface)",
           hasMultipleResponses && "rounded-tl-xl",
+          !hasMultipleResponses && "border-t-0",
         ]}
       >
         <div

package/template/src/layouts/Layout.astro

@@ -384,5 +384,99 @@ const tabsPresentation = navigationTabs?.presentation ?? "topbar";
         );
       }
     </style>
+    <script is:inline>
+      (() => {
+        const initializedKey = "__radiantDocsSidebarScrollPersistence";
+        const storageKey = "radiant-docs:sidebar-scroll-top";
+        const selector = "[data-rd-sidebar-scroll-container]";
+
+        const getVisibleSidebar = () => {
+          const sidebars = document.querySelectorAll(selector);
+
+          for (const sidebar of sidebars) {
+            if (!(sidebar instanceof HTMLElement)) continue;
+
+            const rect = sidebar.getBoundingClientRect();
+            if (rect.width > 0 && rect.height > 0) return sidebar;
+          }
+
+          return null;
+        };
+
+        const getSavedScrollTop = () => {
+          try {
+            const value = Number(sessionStorage.getItem(storageKey));
+            return Number.isFinite(value) && value > 0 ? value : 0;
+          } catch {
+            return 0;
+          }
+        };
+
+        const saveSidebarScroll = () => {
+          const sidebar = getVisibleSidebar();
+          if (!sidebar) return;
+
+          try {
+            sessionStorage.setItem(
+              storageKey,
+              String(Math.max(0, Math.round(sidebar.scrollTop))),
+            );
+          } catch {
+            // Storage can be unavailable in private browsing or locked-down embeds.
+          }
+        };
+
+        const restoreSidebarScroll = () => {
+          const sidebar = getVisibleSidebar();
+          if (!sidebar) return;
+
+          const savedScrollTop = getSavedScrollTop();
+          if (savedScrollTop <= 0) return;
+
+          sidebar.scrollTop = Math.min(
+            savedScrollTop,
+            Math.max(0, sidebar.scrollHeight - sidebar.clientHeight),
+          );
+        };
+
+        const scheduleSidebarScrollRestore = () => {
+          window.requestAnimationFrame(() => {
+            restoreSidebarScroll();
+            window.setTimeout(restoreSidebarScroll, 0);
+          });
+        };
+
+        if (window[initializedKey]) {
+          scheduleSidebarScrollRestore();
+          return;
+        }
+
+        window[initializedKey] = true;
+        document.addEventListener(
+          "astro:before-preparation",
+          saveSidebarScroll,
+        );
+        document.addEventListener("astro:before-swap", saveSidebarScroll);
+        document.addEventListener(
+          "astro:after-swap",
+          scheduleSidebarScrollRestore,
+        );
+        document.addEventListener(
+          "astro:page-load",
+          scheduleSidebarScrollRestore,
+        );
+        window.addEventListener("pagehide", saveSidebarScroll);
+
+        if (document.readyState === "loading") {
+          document.addEventListener(
+            "DOMContentLoaded",
+            scheduleSidebarScrollRestore,
+            { once: true },
+          );
+        } else {
+          scheduleSidebarScrollRestore();
+        }
+      })();
+    </script>
   </body>
 </html>

package/template/src/lib/client-shiki-config.ts

@@ -8,6 +8,8 @@ import {
 
 export type ClientShikiRuntimeConfig = AssistantShikiRuntimeConfig;
 
+const DEFAULT_SHIKI_PLATFORM_ASSET_HOST = "https://static.radiantdocs.com";
+
 function normalizeStaticAssetHost(value: unknown): string {
   const rawValue = typeof value === "string" ? value.trim() : "";
   if (!rawValue) return "";
@@ -43,9 +45,10 @@ function getConfiguredCodeSyntaxThemes(
 export function getClientShikiRuntimeConfig(
   config: DocsConfig,
 ): ClientShikiRuntimeConfig | undefined {
-  const staticAssetHost = normalizeStaticAssetHost(
-    import.meta.env.STATIC_ASSET_HOST ?? process.env.STATIC_ASSET_HOST,
-  );
+  const staticAssetHost =
+    normalizeStaticAssetHost(
+      import.meta.env.STATIC_ASSET_HOST ?? process.env.STATIC_ASSET_HOST,
+    ) || DEFAULT_SHIKI_PLATFORM_ASSET_HOST;
   if (!staticAssetHost) {
     return undefined;
   }