Merge pull request #99 from tenphi/fix-ssr-refactoring

fix: ssr improvements

Author: tenphi

.changeset/remove-ssr-context.md

@@ -0,0 +1,5 @@
+---
+'@tenphi/tasty': patch
+---
+
+Remove `TastySSRContext` React context from SSR pipeline. All hooks now discover the SSR collector via the same global getter used by `computeStyles()`, eliminating the need for a React context Provider in `TastyRegistry`. This simplifies the SSR architecture to a single collector discovery mechanism.

docs/ssr.md

@@ -82,15 +82,15 @@ That's it. All `tasty()` components inside the tree automatically get SSR suppor
 
 ### How it works
 
-- `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load.
-- During SSR, `computeStyles()` finds the collector (registered globally by `TastyRegistry`) and collects CSS rules into it.
-- `TastyRegistry` uses `useServerInsertedHTML` to flush collected CSS into the HTML stream as `<style data-tasty-ssr>` tags. This is fully streaming-compatible -- styles are injected alongside each Suspense boundary as it resolves.
+- `TastyRegistry` is a `'use client'` component, but Next.js still server-renders it on initial page load. The `'use client'` boundary is required solely to access `useServerInsertedHTML` — **not** because `tasty()` components need the client.
+- During SSR, `TastyRegistry` creates a `ServerStyleCollector` and registers it via a module-level global getter. All style computation — whether from `tasty()` components, `computeStyles()`, `useStyles()`, or other hooks like `useGlobalStyles()` — discovers the collector through this single global getter. No React context is involved.
+- `TastyRegistry` uses `useServerInsertedHTML` to flush collected CSS into the HTML stream as `<style data-tasty-ssr>` tags. This is fully streaming-compatible — styles are injected alongside each Suspense boundary as it resolves.
 - A companion `<script>` tag transfers the `cacheKey → className` mapping to the client.
 - When the module loads on the client, `hydrateTastyCache()` runs automatically and pre-populates the injector cache. During hydration, `computeStyles()` hits the cache and skips the entire pipeline.
 
 ### Using tasty() in Server Components
 
-`tasty()` components are hook-free and do not require `'use client'`. They can be used directly in React Server Components. Dynamic `styleProps` like `<Grid flow="column">` work normally in server components. During SSR, the `TastyRegistry` registers its collector globally so that `computeStyles()` can discover it without React context.
+`tasty()` components are hook-free and do not require `'use client'`. They can be used directly in React Server Components. Dynamic `styleProps` like `<Grid flow="column">` work normally in server components. During SSR, `computeStyles()` discovers the collector via the same global getter registered by `TastyRegistry` — no React context or client boundary needed for this path.
 
 ### Options
 
@@ -197,12 +197,12 @@ Same as Next.js -- call `configure({ nonce: '...' })` before any rendering happe
 
 ## Generic Framework Integration
 
-Any React-based framework can integrate using the core SSR API:
+Any React-based framework can integrate using `runWithCollector`, which binds a `ServerStyleCollector` to the current async context via `AsyncLocalStorage`. All `computeStyles()` and hook calls within the render automatically discover the collector.
 
 ```tsx
 import {
   ServerStyleCollector,
-  TastySSRContext,
+  runWithCollector,
   hydrateTastyCache,
 } from '@tenphi/tasty/ssr';
 import { renderToString } from 'react-dom/server';
@@ -212,10 +212,8 @@ import { hydrateRoot } from 'react-dom/client';
 
 const collector = new ServerStyleCollector();
 
-const html = renderToString(
-  <TastySSRContext.Provider value={collector}>
-    <App />
-  </TastySSRContext.Provider>
+const html = await runWithCollector(collector, () =>
+  renderToString(<App />)
 );
 
 const css = collector.getCSS();
@@ -251,11 +249,8 @@ For streaming with `renderToPipeableStream`, use `flushCSS()` instead of `getCSS
 ```tsx
 const collector = new ServerStyleCollector();
 
-const stream = renderToPipeableStream(
-  <TastySSRContext.Provider value={collector}>
-    <App />
-  </TastySSRContext.Provider>,
-  {
+const stream = await runWithCollector(collector, () =>
+  renderToPipeableStream(<App />, {
     onShellReady() {
       // Flush styles collected so far
       const css = collector.flushCSS();
@@ -270,31 +265,10 @@ const stream = renderToPipeableStream(
       const state = collector.getCacheState();
       res.write(`<script data-tasty-cache type="application/json">${JSON.stringify(state)}</script>`);
     },
-  }
+  })
 );
 ```
 
-### AsyncLocalStorage (no React context)
-
-If your framework doesn't support wrapping the React tree with a provider, use `runWithCollector`:
-
-```tsx
-import {
-  ServerStyleCollector,
-  runWithCollector,
-  hydrateTastyCache,
-} from '@tenphi/tasty/ssr';
-
-const collector = new ServerStyleCollector();
-
-const html = await runWithCollector(collector, () =>
-  renderToString(<App />)
-);
-
-const css = collector.getCSS();
-// ... inject into HTML as above
-```
-
 ---
 
 ## API Reference
@@ -303,7 +277,7 @@ const css = collector.getCSS();
 
 | Import path | Description |
 |---|---|
-| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `TastySSRContext`, `runWithCollector`, `hydrateTastyCache` |
+| `@tenphi/tasty/ssr` | Core SSR API: `ServerStyleCollector`, `runWithCollector`, `hydrateTastyCache` |
 | `@tenphi/tasty/ssr/next` | Next.js App Router: `TastyRegistry` component |
 | `@tenphi/tasty/ssr/astro` | Astro: `tastyMiddleware`, auto-hydration on import |
 
@@ -323,10 +297,6 @@ Server-safe style collector. One instance per request.
 | `flushCSS()` | Get only CSS collected since the last flush. For streaming SSR. |
 | `getCacheState()` | Serialize `{ entries: Record<cacheKey, className>, classCounter }` for client hydration. |
 
-### `TastySSRContext`
-
-React context (`createContext<ServerStyleCollector | null>(null)`). Used by the `useStyles()` hook to find the collector during SSR. Not needed when using `computeStyles()` directly (which discovers the collector via `AsyncLocalStorage` or the global getter registered by `TastyRegistry`).
-
 ### `TastyRegistry`
 
 Next.js App Router component. Props:

src/hooks/resolve-ssr-collector.ts

@@ -1,10 +1,9 @@
-import { useContext, useInsertionEffect, useMemo } from 'react';
+import { useInsertionEffect, useMemo } from 'react';
 
 import { getGlobalInjector } from '../config';
 import { formatCounterStyleRule } from '../counter-style';
 import type { CounterStyleDescriptors } from '../injector/types';
-import { resolveSSRCollector } from './resolve-ssr-collector';
-import { TastySSRContext } from '../ssr/context';
+import { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';
 
 interface UseCounterStyleOptions {
   name?: string;
@@ -73,8 +72,7 @@ export function useCounterStyle(
   depsOrOptions?: readonly unknown[] | UseCounterStyleOptions,
   options?: UseCounterStyleOptions,
 ): string {
-  const ssrContextValue = useContext(TastySSRContext);
-  const ssrCollector = resolveSSRCollector(ssrContextValue);
+  const ssrCollector = getRegisteredSSRCollector();
 
   const isFactory = typeof descriptorsOrFactory === 'function';
 

src/hooks/useCounterStyle.ts

@@ -1,10 +1,9 @@
-import { useContext, useInsertionEffect, useMemo } from 'react';
+import { useInsertionEffect, useMemo } from 'react';
 
 import { getGlobalInjector } from '../config';
 import { fontFaceContentHash, formatFontFaceRule } from '../font-face';
 import type { FontFaceDescriptors, FontFaceInput } from '../injector/types';
-import { resolveSSRCollector } from './resolve-ssr-collector';
-import { TastySSRContext } from '../ssr/context';
+import { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';
 
 interface UseFontFaceOptions {
   root?: Document | ShadowRoot;
@@ -48,8 +47,7 @@ export function useFontFace(
   input: FontFaceInput,
   options?: UseFontFaceOptions,
 ): void {
-  const ssrContextValue = useContext(TastySSRContext);
-  const ssrCollector = resolveSSRCollector(ssrContextValue);
+  const ssrCollector = getRegisteredSSRCollector();
 
   const inputKey = useMemo(() => JSON.stringify(input), [input]);
 

src/hooks/useFontFace.ts

@@ -1,13 +1,12 @@
-import { useContext, useInsertionEffect, useMemo, useRef } from 'react';
+import { useInsertionEffect, useMemo, useRef } from 'react';
 
 import { getConfig } from '../config';
 import { injectGlobal } from '../injector';
 import type { StyleResult } from '../pipeline';
 import { renderStyles } from '../pipeline';
 import { collectAutoInferredProperties } from '../ssr/collect-auto-properties';
-import { resolveSSRCollector } from './resolve-ssr-collector';
-import { TastySSRContext } from '../ssr/context';
 import { formatGlobalRules } from '../ssr/format-global-rules';
+import { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';
 import type { Styles } from '../styles/types';
 import { resolveRecipes } from '../utils/resolve-recipes';
 
@@ -35,8 +34,7 @@ import { resolveRecipes } from '../utils/resolve-recipes';
  * ```
  */
 export function useGlobalStyles(selector: string, styles?: Styles): void {
-  const ssrContextValue = useContext(TastySSRContext);
-  const ssrCollector = resolveSSRCollector(ssrContextValue);
+  const ssrCollector = getRegisteredSSRCollector();
 
   const disposeRef = useRef<(() => void) | null>(null);
 

src/hooks/useGlobalStyles.ts

@@ -1,10 +1,9 @@
-import { useContext, useInsertionEffect, useMemo, useRef } from 'react';
+import { useInsertionEffect, useMemo, useRef } from 'react';
 
 import { keyframes } from '../injector';
 import type { KeyframesResult, KeyframesSteps } from '../injector/types';
-import { resolveSSRCollector } from './resolve-ssr-collector';
-import { TastySSRContext } from '../ssr/context';
 import { formatKeyframesCSS } from '../ssr/format-keyframes';
+import { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';
 
 interface UseKeyframesOptions {
   name?: string;
@@ -75,8 +74,7 @@ export function useKeyframes(
   depsOrOptions?: readonly unknown[] | UseKeyframesOptions,
   options?: UseKeyframesOptions,
 ): string {
-  const ssrContextValue = useContext(TastySSRContext);
-  const ssrCollector = resolveSSRCollector(ssrContextValue);
+  const ssrCollector = getRegisteredSSRCollector();
 
   // Detect which overload is being used
   const isFactory = typeof stepsOrFactory === 'function';

src/hooks/useKeyframes.ts

@@ -1,9 +1,8 @@
-import { useContext, useInsertionEffect, useMemo } from 'react';
+import { useInsertionEffect, useMemo } from 'react';
 
 import { getGlobalInjector } from '../config';
-import { resolveSSRCollector } from './resolve-ssr-collector';
-import { TastySSRContext } from '../ssr/context';
 import { formatPropertyCSS } from '../ssr/format-property';
+import { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';
 
 export interface UsePropertyOptions {
   /**
@@ -81,8 +80,7 @@ export interface UsePropertyOptions {
  * ```
  */
 export function useProperty(name: string, options?: UsePropertyOptions): void {
-  const ssrContextValue = useContext(TastySSRContext);
-  const ssrCollector = resolveSSRCollector(ssrContextValue);
+  const ssrCollector = getRegisteredSSRCollector();
 
   // Memoize the options to create a stable dependency
   const optionsKey = useMemo(() => {

src/hooks/useProperty.ts

@@ -1,8 +1,7 @@
-import { useContext, useInsertionEffect, useMemo, useRef } from 'react';
+import { useInsertionEffect, useMemo, useRef } from 'react';
 
 import { injectRawCSS } from '../injector';
-import { resolveSSRCollector } from './resolve-ssr-collector';
-import { TastySSRContext } from '../ssr/context';
+import { getRegisteredSSRCollector } from '../ssr/ssr-collector-ref';
 
 interface UseRawCSSOptions {
   root?: Document | ShadowRoot;
@@ -69,8 +68,7 @@ export function useRawCSS(
   depsOrOptions?: readonly unknown[] | UseRawCSSOptions,
   options?: UseRawCSSOptions,
 ): void {
-  const ssrContextValue = useContext(TastySSRContext);
-  const ssrCollector = resolveSSRCollector(ssrContextValue);
+  const ssrCollector = getRegisteredSSRCollector();
 
   // Detect which overload is being used
   const isFactory = typeof cssOrFactory === 'function';

src/hooks/useRawCSS.ts

@@ -1,8 +1,4 @@
-import { useContext } from 'react';
-
 import { computeStyles } from '../compute-styles';
-import type { ServerStyleCollector } from '../ssr/collector';
-import { TastySSRContext } from '../ssr/context';
 import type { Styles } from '../styles/types';
 
 /**
@@ -21,11 +17,11 @@ export interface UseStylesResult {
 }
 
 /**
- * Hook to generate CSS classes from Tasty styles.
- * Thin wrapper around `computeStyles()` that adds React context-based
- * SSR collector discovery for backward compatibility with TastyRegistry.
+ * Generate CSS classes from Tasty styles.
+ * Thin re-export of `computeStyles()` kept for backward compatibility.
  *
- * For hook-free usage (e.g. in server components), use `computeStyles()` directly.
+ * Unlike a React hook, this is a plain function and can be called
+ * from both client components and React Server Components.
  *
  * @example
  * ```tsx
@@ -41,10 +37,5 @@ export interface UseStylesResult {
  * ```
  */
 export function useStyles(styles: UseStylesOptions): UseStylesResult {
-  const ssrContextValue: ServerStyleCollector | null =
-    useContext(TastySSRContext);
-
-  return computeStyles(styles, {
-    ssrCollector: ssrContextValue,
-  });
+  return computeStyles(styles);
 }