From 72cffdd14b1ff2d0b130844d11637d9dfe46c744 Mon Sep 17 00:00:00 2001
From: Brett Jephson <brett@gitbook.io>
Date: Thu, 30 Apr 2026 10:45:25 +0100
Subject: [PATCH] tidy

---
 packages/gitbook/src/lib/icons/symbols.ts |  7 +++++++
 packages/icons/src/Icon.tsx               |  2 +-
 packages/icons/src/IconSymbolLoader.tsx   |  4 ++++
 packages/icons/src/IconsProvider.tsx      |  4 ----
 packages/icons/src/symbols.ts             | 18 ++++++++++++++----
 5 files changed, 26 insertions(+), 9 deletions(-)

diff --git a/packages/gitbook/src/lib/icons/symbols.ts b/packages/gitbook/src/lib/icons/symbols.ts
index d1bb1e04d..af514b730 100644
--- a/packages/gitbook/src/lib/icons/symbols.ts
+++ b/packages/gitbook/src/lib/icons/symbols.ts
@@ -15,6 +15,9 @@ function escapeAttribute(value: string): string {
         .replaceAll('>', '&gt;');
 }
 
+/**
+ * Load and memoize the generated symbol manifest for a Font Awesome style.
+ */
 export async function getIconStyleManifest(style: string): Promise<StyleIconSymbolManifest | null> {
     const load = loaders[style as SupportedSymbolStyle];
     if (!load) {
@@ -34,6 +37,10 @@ export async function getIconStyleManifest(style: string): Promise<StyleIconSymb
     return manifestPromise;
 }
 
+/**
+ * Resolve one icon entry from the generated manifest and serialize it for sprite injection or
+ * lazy-loading through the symbol route.
+ */
 export async function getIconSymbol(style: string, icon: string, symbolId: string) {
     const manifest = await getIconStyleManifest(style);
     const entry = manifest?.[icon];
diff --git a/packages/icons/src/Icon.tsx b/packages/icons/src/Icon.tsx
index 2d85c1ab3..402c40401 100644
--- a/packages/icons/src/Icon.tsx
+++ b/packages/icons/src/Icon.tsx
@@ -54,7 +54,7 @@ export const Icon = React.forwardRef(function Icon(
     const [iconStyle, icon] = getIconStyle(propIconStyle, propIcon);
     const maskId = React.useId();
     const iconInstanceId = React.useId();
-    const symbolId = getIconSymbolId(context.symbolIdPrefix, iconStyle, icon);
+    const symbolId = getIconSymbolId(iconStyle, icon);
 
     if (context.renderMode === 'symbol') {
         registerServerIconSymbol({
diff --git a/packages/icons/src/IconSymbolLoader.tsx b/packages/icons/src/IconSymbolLoader.tsx
index e11453ee5..b6675ecf4 100644
--- a/packages/icons/src/IconSymbolLoader.tsx
+++ b/packages/icons/src/IconSymbolLoader.tsx
@@ -118,6 +118,10 @@ function setIconFallbackState(instanceId: string, failed: boolean) {
     icon.setAttribute('data-gb-icon-symbol-state', failed ? 'failed' : 'loaded');
 }
 
+/**
+ * Ensure a symbol referenced by an inline `<use>` exists after hydration, fetching it from the
+ * internal symbol route only when the SSR sprite did not already include it.
+ */
 export function IconSymbolLoader(props: {
     instanceId: string;
     symbolId: string;
diff --git a/packages/icons/src/IconsProvider.tsx b/packages/icons/src/IconsProvider.tsx
index 5d3af7867..69cc1c8cc 100644
--- a/packages/icons/src/IconsProvider.tsx
+++ b/packages/icons/src/IconsProvider.tsx
@@ -20,8 +20,6 @@ export type IconsContextType = Partial<IconsAssetsLocation> & {
     iconStyle: IconStyle;
     /** Rendering strategy for icons */
     renderMode: IconRenderMode;
-    /** Prefix used for inline SVG symbol ids */
-    symbolIdPrefix?: string;
     /** Internal route used to lazily load symbols introduced after hydration */
     symbolLoaderURL?: string;
 };
@@ -43,7 +41,6 @@ export function IconsProvider(props: React.PropsWithChildren<Partial<IconsContex
         iconStyle = parent.iconStyle,
         assetsByStyles = parent.assetsByStyles,
         renderMode = parent.renderMode,
-        symbolIdPrefix = parent.symbolIdPrefix,
         symbolLoaderURL = parent.symbolLoaderURL,
     } = props;
     const value = {
@@ -52,7 +49,6 @@ export function IconsProvider(props: React.PropsWithChildren<Partial<IconsContex
         iconStyle,
         assetsByStyles,
         renderMode,
-        symbolIdPrefix,
         symbolLoaderURL,
     };
 
diff --git a/packages/icons/src/symbols.ts b/packages/icons/src/symbols.ts
index 47f3129a5..4823e85ef 100644
--- a/packages/icons/src/symbols.ts
+++ b/packages/icons/src/symbols.ts
@@ -12,10 +12,11 @@ function sanitizeSymbolFragment(fragment: string): string {
     return fragment.replace(/[^a-zA-Z0-9_-]/g, '-');
 }
 
-export function getIconSymbolId(prefix: string | undefined, style: string, icon: string): string {
-    const basePrefix = prefix ?? 'gb-icon-';
-
-    return `${sanitizeSymbolFragment(basePrefix)}${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
+/**
+ * Build the DOM id used by both SSR-emitted symbols and the lazy symbol loader.
+ */
+export function getIconSymbolId(style: string, icon: string): string {
+    return `gb-icon-${sanitizeSymbolFragment(style)}-${sanitizeSymbolFragment(icon)}`;
 }
 
 function getRegisteredSymbolsStore(): Map<string, RegisteredIconSymbol> {
@@ -36,6 +37,9 @@ function shouldTrackSymbolRegistrations() {
     return typeof window === 'undefined' || typeof runtime.Bun !== 'undefined';
 }
 
+/**
+ * Record a symbol used during server rendering so the app can emit a deduplicated sprite subset.
+ */
 export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
     if (!shouldTrackSymbolRegistrations()) {
         return;
@@ -44,10 +48,16 @@ export function registerServerIconSymbol(symbol: RegisteredIconSymbol): void {
     getRegisteredSymbolsStore().set(`${symbol.style}/${symbol.icon}`, symbol);
 }
 
+/**
+ * Return the currently registered server-rendered symbols in insertion order.
+ */
 export function getRegisteredServerIconSymbols(): RegisteredIconSymbol[] {
     return [...getRegisteredSymbolsStore().values()];
 }
 
+/**
+ * Reset the per-request symbol registry after the sprite subset has been emitted.
+ */
 export function clearRegisteredServerIconSymbols(): void {
     getRegisteredSymbolsStore().clear();
 }