Date: December 2025 Issue: Perceived performance regression after SSR implementation

Root Cause: Commit deea8a4bf ("Attempt to streamline server rendering loaders") removed query block prefetching logic, causing client-side waterfall fetches for pages with Query blocks.

File: frontend/apps/web/app/loaders.ts Lines: 317-357

Restored:

1. Query block extraction from document content

2. Server-side query execution

3. Prefetching of all query result documents

4. Graceful error handling with Promise.allSettled

Code Added:

// CRITICAL: Extract and prefetch query blocks (RESTORED)
const queryBlocks = extractQueryBlocks(document.content)

if (queryBlocks.length > 0) {
  await instrument(ctx || noopCtx, 'prefetchQueryBlocks', async () => {
    const queryBlockQueries = await Promise.all(
      queryBlocks.map(async (block) => {
        try {
          return await getQueryResults(block.attributes.query)
        } catch (e) {
          console.error('Error executing query block', e)
          return null
        }
      }),
    )

    // Add query result documents to embeddedDocs for prefetching
    const queryResultDocs = await Promise.allSettled(
      queryBlockQueries
        .filter((item) => item !== null && item.results)
        .flatMap((item) => item!.results)
        .map(async (item) => {
          try {
            const id = item.id
            const document = await getDocument(id)
            return {id, document}
          } catch (e) {
            console.error('Error fetching query result document', item.id, e)
            return null
          }
        }),
    )

    // Add successfully fetched query result docs to embeddedDocs
    queryResultDocs.forEach((result) => {
      if (result.status === 'fulfilled' && result.value) {
        embeddedDocs.push(result.value)
      }
    })
  })
}

Based on analysis of the SSR implementation, the following bottlenecks were identified:

File: frontend/apps/web/app/root.tsx Lines to modify: 29-36

Implementation:

export const links: LinksFunction = () => {
  // Get environment variables injected by loader
  const daemonUrl =
    typeof window !== 'undefined'
      ? window.ENV?.SEED_ASSET_HOST || 'http://localhost:56001'
      : 'http://localhost:56001'

  const lightningUrl =
    typeof window !== 'undefined'
      ? window.ENV?.LIGHTNING_API_URL || 'https://ln.seed.hyper.media'
      : 'https://ln.seed.hyper.media'

  return [
    // Resource hints - CRITICAL for performance
    {rel: 'preconnect', href: daemonUrl, crossOrigin: 'anonymous'},
    {rel: 'dns-prefetch', href: lightningUrl},

    // Existing stylesheets
    {rel: 'stylesheet', href: globalStyles},
    {rel: 'stylesheet', href: localTailwindStyles},
    {rel: 'stylesheet', href: sonnerStyles},
    {rel: 'stylesheet', href: slashMenuStyles},
  ]
}

Expected improvement: 100-300ms faster first request to each origin

File: frontend/apps/web/app/loaders.ts Lines to modify: 381-419

Strategy: Separate blocking vs non-blocking prefetches

Critical (must complete before response):

• Home document

• Home directory (for navigation)

• Document directory (for children)

• Authors

Non-Critical (can fail gracefully):

• Interaction summaries

• Embedded documents

• Query results

• Account metadata

Implementation:

// Prefetch CRITICAL data - must succeed
await instrument(ctx || noopCtx, 'prefetchCriticalData', async () => {
  await Promise.all([
    prefetchCtx.queryClient.prefetchQuery(queryResource(client, homeId)),
    prefetchCtx.queryClient.prefetchQuery(
      queryDirectory(client, homeId, 'Children'),
    ),
    prefetchCtx.queryClient.prefetchQuery(
      queryDirectory(client, docId, 'Children'),
    ),
  ])
})

// Prefetch NON-CRITICAL data - use allSettled for graceful degradation
await instrument(ctx || noopCtx, 'prefetchNonCriticalData', async () => {
  await Promise.allSettled([
    // Interaction summary - nice to have but not blocking
    prefetchCtx.queryClient.prefetchQuery(
      queryInteractionSummary(client, docId),
    ),
    // Embedded docs - will load on client if missing
    ...embeddedDocs.map((doc) =>
      prefetchCtx.queryClient.prefetchQuery(queryResource(client, doc.id)),
    ),
    // Account metadata - will load on client if missing
    ...authors.map((author) =>
      prefetchCtx.queryClient.prefetchQuery(
        queryAccount(client, author.id.uid),
      ),
    ),
  ])
})

Expected improvement: 200-500ms faster TTFB (Time To First Byte)

File: frontend/apps/web/app/providers.tsx Lines to modify: 38-49

Change:

function createQueryClient() {
  return new QueryClient({
    defaultOptions: {
      queries: {
        staleTime: 60000, // 1 minute (was Infinity)
        refetchOnMount: false,
        refetchOnWindowFocus: false,
        refetchOnReconnect: false,
      },
    },
  })
}

Rationale:

• Keeps SSR cache benefits (no refetch on mount/focus)

• Allows background freshness checks after 1 minute

• Balances performance with data freshness

Expected improvement: Better long-session UX, minimal performance impact

File: frontend/apps/web/app/routes/$.tsx Lines to modify: 155-236

Strategy: Split loader into critical shell data + deferred streaming data

Implementation:

import {defer} from '@remix-run/node'

export const loader = async ({params, request}) => {
  const parsedRequest = parseRequest(request)
  const documentId = unpackHmId(params['*'])

  if (!useFullRender(parsedRequest)) {
    return null
  }

  const serviceConfig = await getConfig(hostname)

  // Load CRITICAL data (blocks shell render)
  const criticalData = await loadCriticalSiteResource(parsedRequest, documentId)

  // Start loading NON-CRITICAL data (streams after shell)
  const deferredData = {
    interactionSummary: loadInteractionSummary(documentId),
    embeddedDocs: loadEmbeddedDocuments(documentId),
  }

  return defer({
    ...criticalData,
    ...deferredData,
  })
}

UI Changes Required:

• Wrap non-critical components in <Suspense>

• Use <Await> component for deferred data

• Add loading states for streaming sections

Expected improvement: 300-600ms faster perceived load time

Note: This is the most complex change and should be considered for a future iteration if simpler optimizations don't provide sufficient gains.

Server-Side:

• TTFB (Time To First Byte)

• Server processing time

• Prefetch operation duration (instrumentation)

Client-Side:

• FCP (First Contentful Paint)

• LCP (Largest Contentful Paint)

• TTI (Time To Interactive)

• Total Blocking Time

User Experience:

• Perceived load speed

• Client-side navigation smoothness

• Cache hit rates