@stainless-api/docs 0.1.0-beta.13 → 0.1.0-beta.130

package/stl-docs/index.ts

@@ -1,11 +1,12 @@
 import starlight from '@astrojs/starlight';
 import react from '@astrojs/react';
-import { stainlessStarlight } from '../plugin';
+import type { StarlightPlugin } from '@astrojs/starlight/types';
+import { disableCalloutSyntaxStarlightPlugin } from './disableCalloutSyntax';
 
 import type { AstroIntegration } from 'astro';
 
 import { normalizeRedirects, type NormalizedRedirectConfig } from './redirects';
-import { join } from 'path';
+import path from 'node:path';
 import { mkdirSync, writeFileSync } from 'fs';
 import {
   parseStlDocsConfig,
@@ -16,11 +17,21 @@ import {
   type StarlightSidebarConfig,
 } from './loadStlDocsConfig';
 import { buildVirtualModuleString } from '../shared/virtualModule';
-
-import geistPath from '../plugin/assets/fonts/geist/geist-latin.woff2?url';
+import type * as StlDocsVirtualModule from 'virtual:stl-docs-virtual-module';
+import { resolveSrcFile } from '../resolveSrcFile';
+import { stainlessDocsMarkdownRenderer } from './proseMarkdown/proseMarkdownIntegration';
+import { getSharedLogger, setSharedLogger } from '../shared/getSharedLogger';
+import { stainlessDocsVectorProseIndexing } from './proseDocSync';
+import { stainlessDocsAlgoliaProseIndexing } from './proseSearchIndexing';
+import { stainlessStarlight } from '../plugin';
+import { getFontRoles, flattenFonts } from './fonts';
+import conditionalIntegration from '../shared/conditionalIntegration';
+import generateExamplesPlugin from './aiChatExamples';
 
 export * from '../plugin';
 
+const COMPONENTS_FOLDER = '/stl-docs/components';
+
 function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig) {
   // We transform our tabs into a Starlight sidebar
   // This gives them all the built-in features of Starlight (eg. auto-generated entries by directory)
@@ -40,22 +51,48 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
   }
 
   type ComponentOverrides = StarlightConfigDefined['components'];
-  const plugins = [...config.starlightCompat.plugins];
-
   const componentOverrides: ComponentOverrides = {
-    Sidebar: '@stainless-api/docs/BaseSidebar',
-    Header: '@stainless-api/docs/Header',
-    ThemeSelect: '@stainless-api/docs/ThemeSelect',
-    ContentPanel: '@stainless-api/docs/ContentPanel',
-    TableOfContents: '@stainless-api/docs/TableOfContents',
+    Head: resolveSrcFile(COMPONENTS_FOLDER, './Head.astro'),
+
+    PageFrame: resolveSrcFile(COMPONENTS_FOLDER, './PageFrame.astro'),
+    TwoColumnContent: resolveSrcFile(COMPONENTS_FOLDER, './TwoColumnContent.astro'),
+
+    Header: resolveSrcFile(COMPONENTS_FOLDER, './Header.astro'),
+    ThemeProvider: resolveSrcFile(COMPONENTS_FOLDER, './ThemeProvider.astro'),
+    ThemeSelect: resolveSrcFile(COMPONENTS_FOLDER, './ThemeSelect.astro'),
+
+    Sidebar: resolveSrcFile(COMPONENTS_FOLDER, './sidebars/BaseSidebar.astro'),
+    ContentPanel: resolveSrcFile(COMPONENTS_FOLDER, './ContentPanel.astro'),
+    PageTitle: resolveSrcFile(COMPONENTS_FOLDER, './PageTitle.astro'),
+    PageSidebar: resolveSrcFile(COMPONENTS_FOLDER, './PageSidebar.astro'),
+    TableOfContents: resolveSrcFile(COMPONENTS_FOLDER, './TableOfContents.astro'),
+
+    Footer: resolveSrcFile(COMPONENTS_FOLDER, './Footer.astro'),
+    Pagination: resolveSrcFile(COMPONENTS_FOLDER, './pagination/Pagination.astro'),
   };
 
-  if (config.apiReference !== null) {
-    componentOverrides.Sidebar = '@stainless-api/docs/SDKSelectSidebar';
-    componentOverrides.Search = '@stainless-api/docs/Search';
-    plugins.unshift(stainlessStarlight(config.apiReference));
+  const plugins: StarlightPlugin[] = [
+    // Disable starlight callout syntax in favor of our own component
+    disableCalloutSyntaxStarlightPlugin,
+  ];
+
+  if (config.apiReference) {
+    plugins.push(
+      stainlessStarlight({
+        ...config.apiReference,
+        contextMenu: config.contextMenu,
+        experimentalPrerender:
+          config.apiReference.experimentalPrerender === undefined
+            ? config.starlightPassThrough.prerender
+            : config.apiReference.experimentalPrerender,
+      }),
+    );
+    componentOverrides.Sidebar = resolveSrcFile(COMPONENTS_FOLDER, './sidebars/SDKSelectSidebar.astro');
+    componentOverrides.Search = resolveSrcFile('/plugin/components/search/Search.astro');
   }
 
+  plugins.push(...config.starlightCompat.plugins, ...config.plugins.map((p) => p(config)));
+
   // TODO: re-add once we figure out what to do with the client router
   // if (config.enableClientRouter) {
   //   // logger.info(`Client router is enabled`);
@@ -64,8 +101,11 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
   //   // logger.info(`Client router is disabled`);
   // }
 
+  const userExpressiveCode = typeof config.expressiveCode === 'object' ? config.expressiveCode : {};
+
   return starlight({
     ...config.starlightPassThrough,
+    pagefind: config.starlightCompat.pagefind,
     sidebar,
     components: {
       ...componentOverrides,
@@ -87,68 +127,110 @@ function stainlessDocsStarlightIntegration(config: NormalizedStainlessDocsConfig
         setupNavLinksInitial();
       `,
       },
-      // TODO: for users who are overriding the font stack in their own styles, how can we know that
-      // and preload their font instead of ours?
-      {
-        tag: 'link',
-        attrs: {
-          rel: 'preload',
-          as: 'font',
-          type: 'font/woff2',
-          crossorigin: 'anonymous',
-          href: geistPath,
+    ],
+    routeMiddleware: [
+      ...config.starlightCompat.routeMiddleware,
+      resolveSrcFile('/stl-docs/tabsMiddleware.ts'),
+    ],
+    customCss: [resolveSrcFile('/theme.css'), ...config.customCss],
+
+    expressiveCode: {
+      ...userExpressiveCode,
+      themes: userExpressiveCode.themes ?? ['github-light', 'github-dark'],
+      styleOverrides: {
+        ...userExpressiveCode.styleOverrides,
+        textMarkers: {
+          insBackground: 'var(--stl-color-green-muted-background)',
+          insBorderColor: 'var(--stl-color-green-border)',
+          insDiffIndicatorColor: 'var(--stl-color-green-foreground-reduced)',
+
+          delBackground: 'var(--stl-color-red-muted-background)',
+          delBorderColor: 'var(--stl-color-red-border)',
+          delDiffIndicatorColor: 'var(--stl-color-red-foreground-reduced)',
+
+          markBackground: 'var(--stl-color-blue-muted-background)',
+          markBorderColor: 'var(--stl-color-blue-border)',
+          ...userExpressiveCode.styleOverrides?.textMarkers,
         },
       },
-    ],
-    routeMiddleware: [...config.starlightCompat.routeMiddleware, '@stainless-api/docs/tabsMiddleware'],
-    customCss: ['@stainless-api/docs/theme', ...config.customCss],
+    },
     plugins,
   });
 }
 
-function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroIntegration {
-  const virtualId = `virtual:stl-docs-virtual-module`;
-  // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
-  const resolvedId = `\0${virtualId}`;
+function stainlessDocsIntegration(
+  config: NormalizedStainlessDocsConfig,
+  apiReferenceBasePath: string | null,
+): AstroIntegration {
   let redirects: NormalizedRedirectConfig | null = null;
 
   return {
-    name: 'stl-docs-integration',
+    name: 'stl-docs-astro',
     hooks: {
-      'astro:config:setup': ({ updateConfig, command, config: astroConfig }) => {
-        // // we only handle redirects for builds
-        // // in dev, Astro handles them for us
+      'astro:config:setup': async ({ updateConfig, command, config: astroConfig, logger: localLogger }) => {
+        const logger = getSharedLogger({ fallback: localLogger });
+        // we only handle redirects for builds
+        // in dev, Astro handles them for us
         if (command === 'build' && astroConfig.redirects) {
           redirects = normalizeRedirects(astroConfig.redirects);
         }
 
+        const base = astroConfig.base ?? '/';
+        const withBase = (link: string) =>
+          /^([a-z][a-z0-9+.-]*:|\/\/)/.test(link) ? link : path.posix.join(base, link);
+
+        const virtualModules = new Map(
+          Object.entries({
+            'virtual:stl-docs-virtual-module': buildVirtualModuleString({
+              TABS: config.tabs.map((tab) => ({ ...tab, link: withBase(tab.link) })),
+              SPLIT_TABS_ENABLED: config.splitTabsEnabled,
+              HEADER_LINKS: config.header.links.map((link) => ({ ...link, link: withBase(link.link) })),
+              HEADER_LAYOUT: config.header.layout,
+              ENABLE_CLIENT_ROUTER: config.enableClientRouter,
+              API_REFERENCE_BASE_PATH: apiReferenceBasePath ?? '/api',
+              ENABLE_PROSE_MARKDOWN_RENDERING: config.enableProseMarkdownRendering,
+              ENABLE_CONTEXT_MENU: config.contextMenu, // TODO: do not duplicate this between both virtual modules
+              RENDER_PAGE_DESCRIPTIONS: config.renderPageDescriptions,
+              FONTS: getFontRoles(config.fonts),
+              LINK_GROUP_TITLES_TO_OVERVIEW_PAGES: config.linkGroupTitlesToOverviewPages,
+              RENDER_CREDITS: config.credits,
+              SITE_TITLE: config.siteTitle,
+              ENABLE_AI_CHAT: !!config.aiChat,
+            } satisfies typeof StlDocsVirtualModule),
+          }),
+        );
+
         updateConfig({
+          fonts: [...flattenFonts(config.fonts), ...(astroConfig?.fonts ?? [])],
           vite: {
-            ssr: {
-              noExternal: ['@stainless-api/ui-primitives'],
+            define: {
+              __STLDOCS_HAS_API_REFERENCE__: !!config.apiReference,
+              __STLDOCS_ENABLE_AI_CHAT__: !!config.aiChat,
             },
-            optimizeDeps: { include: ['@stainless-api/ui-primitives'] },
             plugins: [
               {
-                name: 'stl-docs-vite',
+                name: 'stl-docs-virtual-modules',
                 resolveId(id) {
-                  if (id === virtualId) {
-                    return resolvedId;
-                  }
+                  // The '\0' prefix tells Vite “this is a virtual module” and prevents it from being resolved again.
+                  if (virtualModules.has(id)) return `\0${id}`;
                 },
                 load(id) {
-                  if (id === resolvedId) {
-                    return buildVirtualModuleString({
-                      TABS: config.tabs,
-                      SPLIT_TABS_ENABLED: config.splitTabsEnabled,
-                      HEADER_LINKS: config.header.links,
-                      HEADER_LAYOUT: config.header.layout,
-                      ENABLE_CLIENT_ROUTER: config.enableClientRouter,
-                      INCLUDE_AI_DROPDOWN_OPTIONS: config.includeAIDropdownOptions,
-                    });
-                  }
+                  const bare = id.replace(/^\0/, '');
+                  if (virtualModules.has(bare)) return virtualModules.get(bare);
                 },
               },
+              // Separate plugin for the examples because it has async resolution; not a simple string
+              // like the above plugins
+              ...(config.aiChat
+                ? [
+                    await generateExamplesPlugin({
+                      projectName: config.apiReference?.stainlessProject ?? undefined,
+                      logger,
+                      exampleOverrides:
+                        typeof config.aiChat === 'object' ? config.aiChat.exampleOverrides : undefined,
+                    }),
+                  ]
+                : []),
             ],
           },
           build: {
@@ -159,9 +241,9 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
       },
       'astro:build:done': ({ dir }) => {
         if (redirects !== null) {
-          const stainlessDir = join(dir.pathname, '_stainless');
-          mkdirSync(stainlessDir);
-          const outputPath = join(stainlessDir, 'redirects.json');
+          const stainlessDir = path.join(dir.pathname, '_stainless');
+          mkdirSync(stainlessDir, { recursive: true });
+          const outputPath = path.join(stainlessDir, 'redirects.json');
           writeFileSync(outputPath, JSON.stringify(redirects, null, 2), {
             encoding: 'utf-8',
           });
@@ -171,7 +253,18 @@ function stainlessDocsIntegration(config: NormalizedStainlessDocsConfig): AstroI
   };
 }
 
-export function stainlessDocs(config: StainlessDocsUserConfig) {
+function sharedLoggerIntegration(): AstroIntegration {
+  return {
+    name: 'stainless',
+    hooks: {
+      'astro:config:setup': ({ logger }) => {
+        setSharedLogger(logger);
+      },
+    },
+  };
+}
+
+export function stainlessDocs(config: StainlessDocsUserConfig): AstroIntegration[] {
   const normalizedConfigResult = parseStlDocsConfig(config);
   if (normalizedConfigResult.result === 'error') {
     // TODO: would be good to use the astro logger somehow
@@ -180,9 +273,34 @@ export function stainlessDocs(config: StainlessDocsUserConfig) {
   }
   const normalizedConfig = normalizedConfigResult.config;
 
+  // TODO: need to refactor this, but this allows us to get the base path for the API reference _if_ it exists
+  // if it doesn't exist, the value of basePath is null.
+  // the stl-starlight virtual module has base path, but it's not available when there's no API reference
+  const hasApiReference = normalizedConfig.apiReference !== null;
+  let apiReferenceBasePath: string | null = null;
+  if (hasApiReference) {
+    apiReferenceBasePath = normalizedConfig.apiReference?.basePath ?? '/api';
+  }
+
   return [
+    sharedLoggerIntegration(), // this **must** be first so it can set the shared logger used by our other integrations
     react(),
     stainlessDocsStarlightIntegration(normalizedConfig),
-    stainlessDocsIntegration(normalizedConfig),
+    stainlessDocsIntegration(normalizedConfig, apiReferenceBasePath),
+    conditionalIntegration({
+      condition: !config.experimental?.disableProseMarkdownRendering,
+      integration: stainlessDocsMarkdownRenderer({ apiReferenceBasePath }),
+      reason: 'disabled by experimental config "disableProseMarkdownRendering"',
+    }),
+    conditionalIntegration({
+      condition: !config.experimental?.disableStainlessProseIndexing,
+      integration: stainlessDocsAlgoliaProseIndexing({ apiReferenceBasePath }),
+      reason: 'disabled by experimental config "disableStainlessProseIndexing"',
+    }),
+    conditionalIntegration({
+      condition: !config.experimental?.disableStainlessProseIndexing,
+      integration: stainlessDocsVectorProseIndexing(normalizedConfig, apiReferenceBasePath),
+      reason: 'disabled by experimental config "disableStainlessProseIndexing"',
+    }),
   ];
 }

package/stl-docs/loadStlDocsConfig.ts

@@ -1,8 +1,10 @@
 import type { StainlessStarlightUserConfig } from '../plugin/loadPluginConfig';
-import type { StarlightUserConfig } from '@astrojs/starlight/types';
+import type { StarlightPlugin, StarlightUserConfig } from '@astrojs/starlight/types';
 import type { ButtonVariant } from '@stainless-api/ui-primitives';
 import type { AnchorHTMLAttributes } from 'react';
 import type starlight from '@astrojs/starlight';
+import { normalizeFonts, type StlDocsFontConfig } from './fonts';
+import type { ExamplePromptResponse } from './aiChatExamples';
 
 type StarlightConfig = Parameters<typeof starlight>[0];
 
@@ -32,20 +34,22 @@ type PassThroughStarlightConfigOptions = Pick<
   | 'lastUpdated'
   | 'pagination'
   | 'sidebar'
+  | 'expressiveCode'
 >;
 
 type ExperimentalStarlightCompatibilityConfig = Pick<
   StarlightConfigDefined,
-  'components' | 'routeMiddleware' | 'plugins'
+  'components' | 'routeMiddleware' | 'plugins' | 'prerender' | 'pagefind'
 >;
 
-type Tabs = {
+export type Tabs = {
   label: string;
   link: string;
   sidebar?: SidebarEntry[];
   /**
    * Whether to hide the tab in the tab bar.
-   * Defaults to `false`.
+   *
+   * @default false
    */
   hidden?: boolean;
 }[];
@@ -64,10 +68,44 @@ export type StainlessDocsUserConfig = {
     layout?: HeaderLayout;
     links?: HeaderLink[];
   };
+  disableCredits?: boolean;
+  fonts?: StlDocsFontConfig;
   experimental?: {
     starlightCompat?: ExperimentalStarlightCompatibilityConfig;
     enableClientRouter?: boolean;
+    /**
+     * Disable markdown rendering for prose content. Only disable this if it is causing issues.
+     *
+     * @default false
+     */
+    disableProseMarkdownRendering?: boolean;
+    disableStainlessProseIndexing?: boolean;
+    aiChat?: { exampleOverrides?: ExamplePromptResponse } | true;
+    /**
+     * Whether to link group titles to overview pages. Note: overview pages must already be present in the sidebar for this to work.
+     *
+     * @default false
+     */
+    linkGroupTitlesToOverviewPages?: boolean;
   };
+  /**
+   * Whether to show the context menu with options like "Copy as Markdown" and "Open in ChatGPT".
+   *
+   * @default true
+   */
+  contextMenu?: boolean;
+
+  /**
+   * Whether to render page descriptions in prose page headers
+   *
+   * @default true
+   */
+  renderPageDescriptions?: boolean;
+  /**
+   * Stainless Docs plugins.
+   * Each plugin is a function that receives the normalized config and returns a Starlight plugin.
+   */
+  plugins?: ((config: Exclude<NormalizedStainlessDocsConfig, 'plugins'>) => StarlightPlugin)[];
 } & PassThroughStarlightConfigOptions;
 
 type HeaderLayout = 'default' | 'stacked';
@@ -99,6 +137,19 @@ function normalizeRouteMiddleware(userConfig: StainlessDocsUserConfig) {
   return entry;
 }
 
+function normalizeSiteTitle(userConfig: StainlessDocsUserConfig) {
+  if (typeof userConfig.title === 'string') {
+    return userConfig.title;
+  }
+  if (typeof userConfig.title === 'object') {
+    const firstValue = Object.values(userConfig.title)[0];
+    if (typeof firstValue === 'string') {
+      return firstValue;
+    }
+  }
+  throw new Error('Site title provided in config is not valid.');
+}
+
 function normalizeConfig(userConfig: StainlessDocsUserConfig) {
   const splitTabsEnabled = areSplitTabsEnabled(userConfig);
 
@@ -112,6 +163,7 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
       layout: userConfig.header?.layout ?? 'default',
       links: userConfig.header?.links ?? [],
     },
+    fonts: normalizeFonts(userConfig.fonts),
     starlightPassThrough: {
       tableOfContents: userConfig.tableOfContents,
       titleDelimiter: userConfig.titleDelimiter,
@@ -125,16 +177,29 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
       locales: userConfig.locales,
       lastUpdated: userConfig.lastUpdated,
       pagination: userConfig.pagination,
+      prerender: userConfig.experimental?.starlightCompat?.prerender ?? true,
     },
     starlightCompat: {
       components: userConfig.experimental?.starlightCompat?.components ?? {},
       plugins: userConfig.experimental?.starlightCompat?.plugins ?? [],
+      pagefind: userConfig.experimental?.starlightCompat?.pagefind ?? true,
       routeMiddleware: normalizeRouteMiddleware(userConfig),
     },
     enableClientRouter: userConfig.experimental?.enableClientRouter ?? false,
     apiReference: userConfig.apiReference ?? null,
     sidebar: userConfig.sidebar,
-    includeAIDropdownOptions: userConfig.apiReference?.includeAIDropdownOptions ?? false,
+    enableStainlessProseIndexing:
+      userConfig.experimental?.disableStainlessProseIndexing === true ? false : true,
+    enableProseMarkdownRendering:
+      userConfig.experimental?.disableProseMarkdownRendering === true ? false : true,
+    contextMenu: userConfig.contextMenu ?? true,
+    expressiveCode: userConfig.expressiveCode,
+    renderPageDescriptions: userConfig.renderPageDescriptions ?? true,
+    plugins: userConfig.plugins ?? [],
+    aiChat: userConfig.experimental?.aiChat,
+    linkGroupTitlesToOverviewPages: userConfig.experimental?.linkGroupTitlesToOverviewPages ?? false,
+    credits: !userConfig.disableCredits,
+    siteTitle: normalizeSiteTitle(userConfig),
   };
 
   return configWithDefaults;
@@ -143,12 +208,12 @@ function normalizeConfig(userConfig: StainlessDocsUserConfig) {
 export type NormalizedStainlessDocsConfig = ReturnType<typeof normalizeConfig>;
 
 /*
- The goal of the code in this file is to take a user's config and normalize it. 
+ The goal of the code in this file is to take a user's config and normalize it.
  Specifically: we want a single complete config format used throughout the internals of the plugin.
 
  We've tried to avoid any config values being optional/undefined. To accomplish this:
- - Any optional config values should have their defaults set here: eg. basePath defaults to /api 
- - If a field is only used in certain contexts, we make each context a discriminated union (see SpecRetrieverConfig)
+ - Any optional config values should have their defaults set here: eg. basePath defaults to /api
+ - If a field is only used in certain contexts, we make each context a discriminated union (see SDKJSONInputs)
  - We prefer empty arrays over undefined/null
 */
 export function parseStlDocsConfig(userConfig: StainlessDocsUserConfig) {

package/stl-docs/proseDocSync.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from 'vitest';
+import { batchBySize, MAX_BATCH_BYTES, MAX_BATCH_DOCS } from './proseDocSync';
+
+function makeDoc(docId: string, sizeBytes: number) {
+  return {
+    docId,
+    content: Buffer.alloc(sizeBytes, 'x'),
+    sha256: 'fake',
+    source: `/${docId}`,
+  };
+}
+
+describe('batchBySize', () => {
+  it('returns empty array for no docs', () => {
+    expect(batchBySize([])).toEqual([]);
+  });
+
+  it('puts all docs in one batch when under both limits', () => {
+    const docs = Array.from({ length: 5 }, (_, i) => makeDoc(`doc-${i}`, 100));
+    const batches = batchBySize(docs);
+    expect(batches).toHaveLength(1);
+    expect(batches[0]).toHaveLength(5);
+  });
+
+  it('splits at MAX_BATCH_DOCS', () => {
+    const docs = Array.from({ length: MAX_BATCH_DOCS + 10 }, (_, i) => makeDoc(`doc-${i}`, 10));
+    const batches = batchBySize(docs);
+    expect(batches).toHaveLength(2);
+    expect(batches[0]).toHaveLength(MAX_BATCH_DOCS);
+    expect(batches[1]).toHaveLength(10);
+  });
+
+  it('splits when cumulative size exceeds MAX_BATCH_BYTES', () => {
+    const docSize = 10 * 1024 * 1024; // 10MB each
+    // 4 docs = 40MB > 30MB limit, so should split into [3, 1]
+    const docs = Array.from({ length: 4 }, (_, i) => makeDoc(`doc-${i}`, docSize));
+    const batches = batchBySize(docs);
+    expect(batches).toHaveLength(2);
+    expect(batches[0]).toHaveLength(3);
+    expect(batches[1]).toHaveLength(1);
+  });
+
+  it('handles a single doc larger than MAX_BATCH_BYTES', () => {
+    const docs = [makeDoc('huge', MAX_BATCH_BYTES + 1)];
+    const batches = batchBySize(docs);
+    // Still goes into a batch on its own — we can't split a single doc
+    expect(batches).toHaveLength(1);
+    expect(batches[0]).toHaveLength(1);
+  });
+
+  it('byte limit takes precedence over doc count when hit first', () => {
+    // 2 docs of 20MB each = 40MB > 30MB limit, well under 100 doc limit
+    const docs = [makeDoc('a', 20 * 1024 * 1024), makeDoc('b', 20 * 1024 * 1024)];
+    const batches = batchBySize(docs);
+    expect(batches).toHaveLength(2);
+    expect(batches[0]).toHaveLength(1);
+    expect(batches[1]).toHaveLength(1);
+  });
+
+  it('creates multiple batches for many large docs', () => {
+    const docSize = 8 * 1024 * 1024; // 8MB each
+    // 10 docs * 8MB = 80MB, should split into batches of ~3 (24MB each)
+    const docs = Array.from({ length: 10 }, (_, i) => makeDoc(`doc-${i}`, docSize));
+    const batches = batchBySize(docs);
+    // Every batch should be <= MAX_BATCH_BYTES
+    for (const batch of batches) {
+      const totalBytes = batch.reduce((sum, d) => sum + d.content.byteLength, 0);
+      expect(totalBytes).toBeLessThanOrEqual(MAX_BATCH_BYTES);
+    }
+    // All docs should be accounted for
+    const totalDocs = batches.reduce((sum, b) => sum + b.length, 0);
+    expect(totalDocs).toBe(10);
+  });
+});