@taujs/react 0.0.8 → 0.1.0

package/README.md

@@ -6,96 +6,8 @@
 
 `pnpm add @taujs/react`
 
-## CSR; SSR; Streaming SSR; Hydration; Fastify + React 19
+# τjs
 
-Supports rendering modes:
+React Renderer: CSR, SSR, Streaming SSR
 
-- Client-side rendering (CSR)
-- Server-side rendering (SSR)
-- Streaming SSR
-
-Supported application structure and composition:
-
-- Single-page Application (SPA)
-- Multi-page Application (MPA)
-- Build-time Micro-Frontends (MFE), with server orchestration and delivery
-
-Assemble independent frontends at build time incorporating flexible per-route SPA-MPA hybrid with CSR, SSR, and Streaming SSR, rendering options.
-
-Fastify Plugin for integration with taujs [ τjs ] template https://github.com/aoede3/taujs
-
-- Production: Fastify, React
-- Development: Fastify, React, tsx, Vite
-
-- TypeScript-first
-- ESM-only focus
-
-## τjs - DX Developer Experience
-
-Integrated Vite HMR run alongside tsx (TS eXecute) providing fast responsive dev reload times for universal backend / frontend changes
-
-- Fastify https://fastify.dev/
-- React https://reactjs.org/
-- tsx https://tsx.is/
-- Vite https://vitejs.dev/guide/ssr#building-for-production
-
-- ESBuild https://esbuild.github.io/
-- Rollup https://rollupjs.org/
-- ESM https://nodejs.org/api/esm.html
-
-## Development / CI
-
-`npm install --legacy-peer-deps`
-
-## Usage
-
-### Fastify
-
-https://github.com/aoede3/taujs/blob/main/src/server/index.ts
-
-Not utilising taujs [ τjs ] template? Add in your own ts `alias` object for your own particular directory setup e.g. `alias: { object }`
-
-### React 'entry-client.tsx'
-
-https://github.com/aoede3/taujs/blob/main/src/client/entry-client.tsx
-
-### React 'entry-server.tsx'
-
-Extended pipe object with callbacks to @taujs/server enabling additional manipulation of HEAD content from client code
-
-https://github.com/aoede3/taujs/blob/main/src/client/entry-server.tsx
-
-### index.html
-
-https://github.com/aoede3/taujs/blob/main/src/client/index.html
-
-### client.d.ts
-
-https://github.com/aoede3/taujs/blob/main/src/client/client.d.ts
-
-### Routes
-
-Integral to τjs is its internal routing:
-
-1. Fastify serving index.html to client browser for client routing
-2. Internal service calls to API to provide data for streaming/hydration
-3. Fastify serving API calls via HTTP in the more traditional sense of client/server
-
-In ensuring a particular 'route' receives data for hydration there are two options:
-
-1. An HTTP call syntactically not unlike 'fetch' providing params to a 'fetch' call
-2. Internal service call returning data as per your architecture
-
-In supporting Option 2. there is a registry of services. More detail in 'Service Registry'.
-
-Each routes 'path' is a simple URL regex as per below examples.
-
-https://github.com/aoede3/taujs/blob/main/src/shared/routes/Routes.ts
-
-### Service Registry
-
-In supporting internal calls via τjs a registry of available services and methods can provide linkage to your own architectural setup and developmental patterns
-
-https://github.com/aoede3/taujs/blob/main/src/server/services/ServiceRegistry.ts
-
-https://github.com/aoede3/taujs/blob/main/src/server/services/ServiceExample.ts
+https://taujs.dev/

package/dist/index.d.ts

@@ -1,49 +1,88 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
 import React from 'react';
-import { ServerResponse } from 'node:http';
+import { Writable } from 'node:stream';
 
 type SSRStore<T> = {
     getSnapshot: () => T;
     getServerSnapshot: () => T;
     setData: (newData: T) => void;
     subscribe: (callback: () => void) => () => void;
+    status: 'pending' | 'success' | 'error';
+    lastError?: Error;
 };
-declare const createSSRStore: <T>(initialDataOrPromise: T | Promise<T> | (() => Promise<T>)) => SSRStore<T>;
-declare const SSRStoreProvider: React.FC<React.PropsWithChildren<{
-    store: SSRStore<Record<string, unknown>>;
-}>>;
+declare function createSSRStore<T>(initialDataOrPromise: T | Promise<T> | (() => Promise<T>)): SSRStore<T>;
+declare const SSRStoreProvider: <T>({ store, children }: React.PropsWithChildren<{
+    store: SSRStore<T>;
+}>) => react_jsx_runtime.JSX.Element;
 declare const useSSRStore: <T>() => T;
 
-type HydrateAppOptions = {
+type UILogger = {
+    log: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+};
+type ServerLogs = {
+    info: (message: string, meta?: unknown) => void;
+    warn: (message: string, meta?: unknown) => void;
+    error: (message: string, meta?: unknown) => void;
+    debug?: (category: string, message: string, meta?: unknown) => void;
+    child?: (ctx: Record<string, unknown>) => ServerLogs;
+    isDebugEnabled?: (category: string) => boolean;
+};
+type LoggerLike = Partial<UILogger> | Partial<ServerLogs>;
+
+type HydrateAppOptions<T> = {
     appComponent: React.ReactElement;
-    initialDataKey?: keyof Window;
     rootElementId?: string;
-    debug?: boolean;
+    enableDebug?: boolean;
+    logger?: LoggerLike;
+    dataKey?: string;
+    onHydrationError?: (err: unknown) => void;
+    onStart?: () => void;
+    onSuccess?: () => void;
 };
-declare const hydrateApp: ({ appComponent, initialDataKey, rootElementId, debug }: HydrateAppOptions) => void;
+declare function hydrateApp<T>({ appComponent, rootElementId, enableDebug, logger, dataKey, onHydrationError, onStart, onSuccess, }: HydrateAppOptions<T>): void;
 
-type RendererOptions = {
+type RenderCallbacks<T> = {
+    onHead?: (head: string) => boolean | void;
+    onShellReady?: () => void;
+    onAllReady?: (data: T) => void;
+    onFinish?: (data: T) => void;
+    onError?: (err: unknown) => void;
+};
+type StreamOptions = {
+    /** Timeout in ms for shell to be ready (default: 10000) */
+    shellTimeoutMs?: number;
+    /** Whether to use cork/uncork for batched writes (default: true) */
+    useCork?: boolean;
+};
+type SSRResult = {
+    headContent: string;
+    appHtml: string;
+    aborted: boolean;
+};
+type StreamCallOptions = StreamOptions & {
+    logger?: LoggerLike;
+};
+declare function createRenderer<T extends Record<string, unknown>>({ appComponent, headContent, streamOptions, logger, enableDebug, }: {
     appComponent: (props: {
         location: string;
     }) => React.ReactElement;
-    headContent: string | ((data: Record<string, unknown>) => string);
-};
-type RenderCallbacks = {
-    onHead: (headContent: string) => void;
-    onFinish: (initialDataPromise: unknown) => void;
-    onError: (error: unknown) => void;
-};
-declare const resolveHeadContent: (headContent: string | ((meta: Record<string, unknown>) => string), meta?: Record<string, unknown>) => string;
-declare const createRenderer: ({ appComponent, headContent }: RendererOptions) => {
-    renderSSR: (initialDataPromise: Record<string, unknown>, location: string, meta?: Record<string, unknown>) => Promise<{
-        headContent: string;
-        appHtml: string;
-    }>;
-    renderStream: (serverResponse: ServerResponse, callbacks: RenderCallbacks, initialDataPromise: Record<string, unknown>, location: string, bootstrapModules?: string, meta?: Record<string, unknown>, cspNonce?: string) => void;
-};
-declare const createRenderStream: (serverResponse: ServerResponse, { onHead, onFinish, onError }: RenderCallbacks, { appComponent, headContent, initialDataPromise, location, bootstrapModules, }: RendererOptions & {
-    initialDataPromise: Record<string, unknown>;
-    location: string;
-    bootstrapModules?: string;
-}, cspNonce?: string) => void;
+    headContent: (ctx: {
+        data: T;
+        meta: Record<string, unknown>;
+    }) => string;
+    enableDebug?: boolean;
+    logger?: LoggerLike;
+    streamOptions?: StreamOptions;
+}): {
+    renderSSR: (initialData: T, location: string, meta?: Record<string, unknown>, signal?: AbortSignal, opts?: {
+        logger?: LoggerLike;
+    }) => Promise<SSRResult>;
+    renderStream: (writable: Writable, callbacks: RenderCallbacks<T> | undefined, initialData: T | Promise<T> | (() => Promise<T>), location: string, bootstrapModules?: string, meta?: Record<string, unknown>, cspNonce?: string, signal?: AbortSignal, opts?: StreamCallOptions) => {
+        abort: () => void;
+        done: Promise<void>;
+    };
+};
 
-export { type SSRStore, SSRStoreProvider, createRenderStream, createRenderer, createSSRStore, hydrateApp, resolveHeadContent, useSSRStore };
+export { type HydrateAppOptions, type RenderCallbacks, type SSRStore, SSRStoreProvider, type ServerLogs, type StreamOptions, createRenderer, createSSRStore, hydrateApp, useSSRStore };

package/dist/index.js

@@ -1,31 +1,33 @@
 // src/SSRDataStore.tsx
-import { createContext, useContext, useSyncExternalStore } from "react";
+import { createContext, useContext, useSyncExternalStore, useDeferredValue, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
-var createSSRStore = (initialDataOrPromise) => {
+function createSSRStore(initialDataOrPromise) {
   let currentData;
   let status;
   let lastError;
-  const subscribers = /* @__PURE__ */ new Set();
   let serverDataPromise;
+  const subscribers = /* @__PURE__ */ new Set();
+  const notify = () => subscribers.forEach((cb) => cb());
   const handleError = (error) => {
-    console.error("Failed to load initial data:", error);
-    lastError = error instanceof Error ? error : new Error(String(JSON.stringify(error)));
+    const normalised = error instanceof Error ? error : new Error(String(JSON.stringify(error)));
+    console.error("Failed to load initial data:", normalised);
+    lastError = normalised;
     status = "error";
+    notify();
   };
   if (typeof initialDataOrPromise === "function") {
     status = "pending";
-    const promiseFromFunction = initialDataOrPromise();
-    serverDataPromise = promiseFromFunction.then((data) => {
+    serverDataPromise = initialDataOrPromise().then((data) => {
       currentData = data;
       status = "success";
-      subscribers.forEach((callback) => callback());
+      notify();
     }).catch(handleError);
   } else if (initialDataOrPromise instanceof Promise) {
     status = "pending";
     serverDataPromise = initialDataOrPromise.then((data) => {
       currentData = data;
       status = "success";
-      subscribers.forEach((callback) => callback());
+      notify();
     }).catch(handleError);
   } else {
     currentData = initialDataOrPromise;
@@ -35,38 +37,41 @@ var createSSRStore = (initialDataOrPromise) => {
   const setData = (newData) => {
     currentData = newData;
     status = "success";
-    subscribers.forEach((callback) => callback());
+    notify();
   };
   const subscribe = (callback) => {
     subscribers.add(callback);
     return () => subscribers.delete(callback);
   };
   const getSnapshot = () => {
-    if (status === "pending") {
-      throw serverDataPromise;
-    } else if (status === "error") {
-      throw new Error(`SSR data fetch failed: ${lastError?.message || "Unknown error"}`);
-    }
+    if (status === "pending") throw serverDataPromise;
+    if (status === "error") throw new Error(`SSR data fetch failed: ${lastError?.message || "Unknown error"}`);
     if (currentData === void 0) throw new Error("SSR data is undefined - store initialisation problem");
     return currentData;
   };
   const getServerSnapshot = () => {
-    if (status === "pending") {
-      throw serverDataPromise;
-    } else if (status === "error") {
-      throw new Error(`Server-side data fetch failed: ${lastError?.message || "Unknown error"}`);
-    }
+    if (status === "pending") throw serverDataPromise;
+    if (status === "error") throw new Error(`Server-side data fetch failed: ${lastError?.message || "Unknown error"}`);
     if (currentData === void 0) throw new Error("Server data not available - check SSR configuration");
     return currentData;
   };
-  return { getSnapshot, getServerSnapshot, setData, subscribe };
-};
+  return {
+    getSnapshot,
+    getServerSnapshot,
+    setData,
+    subscribe,
+    status,
+    lastError
+  };
+}
 var SSRStoreContext = createContext(null);
 var SSRStoreProvider = ({ store, children }) => /* @__PURE__ */ jsx(SSRStoreContext.Provider, { value: store, children });
 var useSSRStore = () => {
   const store = useContext(SSRStoreContext);
   if (!store) throw new Error("useSSRStore must be used within a SSRStoreProvider");
-  return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+  const syncVal = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getServerSnapshot);
+  const deferred = useDeferredValue(syncVal);
+  return useMemo(() => deferred, [deferred]);
 };
 
 // src/SSRHydration.tsx
@@ -74,127 +79,479 @@ import React2 from "react";
 import { createRoot, hydrateRoot } from "react-dom/client";
 
 // src/utils/Logger.ts
-var createLogger = (debug) => ({
-  log: (...args) => {
-    if (debug) console.log(...args);
-  },
-  warn: (...args) => {
-    if (debug) console.warn(...args);
-  },
-  error: (...args) => {
-    if (debug) console.error(...args);
+var toJSONString = (v) => typeof v === "string" ? v : v instanceof Error ? v.stack ?? v.message : JSON.stringify(v);
+var splitMsgAndMeta = (args) => {
+  const [first, ...rest] = args;
+  const msg = toJSONString(first);
+  if (rest.length === 0) return { msg, meta: void 0 };
+  const only = rest.length === 1 ? rest[0] : void 0;
+  const meta = only && typeof only === "object" && !(only instanceof Error) ? only : { args: rest.map(toJSONString) };
+  return { msg, meta };
+};
+function createUILogger(logger, opts = {}) {
+  const { debugCategory = "ssr", context, preferDebug = false, enableDebug = false } = opts;
+  if (!enableDebug) return { log: () => {
+  }, warn: () => {
+  }, error: () => {
+  } };
+  const looksServer = !!logger && ("info" in logger || "debug" in logger || "child" in logger || "isDebugEnabled" in logger);
+  if (looksServer) {
+    let s = logger;
+    if (s.child && context) {
+      try {
+        s = s.child.call(s, context);
+      } catch {
+      }
+    }
+    const info = s.info ? s.info.bind(s) : (m, meta) => meta ? console.log(m, meta) : console.log(m);
+    const warn = s.warn ? s.warn.bind(s) : (m, meta) => meta ? console.warn(m, meta) : console.warn(m);
+    const error = s.error ? s.error.bind(s) : (m, meta) => meta ? console.error(m, meta) : console.error(m);
+    const debug = s.debug ? s.debug.bind(s) : void 0;
+    const isDebugEnabled = s.isDebugEnabled ? s.isDebugEnabled.bind(s) : void 0;
+    return {
+      log: (...args) => {
+        const { msg, meta } = splitMsgAndMeta(args);
+        if (debug) {
+          const enabled = (isDebugEnabled ? isDebugEnabled(debugCategory) : false) || preferDebug;
+          if (enabled) {
+            debug(debugCategory, msg, meta);
+            return;
+          }
+        }
+        info(msg, meta);
+      },
+      warn: (...args) => {
+        const { msg, meta } = splitMsgAndMeta(args);
+        warn(msg, meta);
+      },
+      error: (...args) => {
+        const { msg, meta } = splitMsgAndMeta(args);
+        error(msg, meta);
+      }
+    };
   }
-});
+  const ui = logger || {};
+  return {
+    log: (...a) => (ui.log ?? console.log)(...a),
+    warn: (...a) => (ui.warn ?? console.warn)(...a),
+    error: (...a) => (ui.error ?? console.error)(...a)
+  };
+}
 
 // src/SSRHydration.tsx
 import { jsx as jsx2 } from "react/jsx-runtime";
-var hydrateApp = ({ appComponent, initialDataKey = "__INITIAL_DATA__", rootElementId = "root", debug = false }) => {
-  const { log, warn, error } = createLogger(debug);
+function hydrateApp({
+  appComponent,
+  rootElementId = "root",
+  enableDebug = false,
+  logger,
+  dataKey = "__INITIAL_DATA__",
+  onHydrationError,
+  onStart,
+  onSuccess
+}) {
+  const { log, warn, error } = createUILogger(logger, { debugCategory: "ssr", context: { scope: "react-hydration" }, enableDebug });
+  const mountCSR = (rootEl) => {
+    rootEl.innerHTML = "";
+    const root = createRoot(rootEl);
+    root.render(/* @__PURE__ */ jsx2(React2.StrictMode, { children: appComponent }));
+  };
+  const startHydration = (rootEl, initialData) => {
+    if (enableDebug) log("Hydration started");
+    onStart?.();
+    if (enableDebug) log("Initial data loaded:", initialData);
+    const store = createSSRStore(initialData);
+    if (enableDebug) log("Store created:", store);
+    try {
+      hydrateRoot(
+        rootEl,
+        /* @__PURE__ */ jsx2(React2.StrictMode, { children: /* @__PURE__ */ jsx2(SSRStoreProvider, { store, children: appComponent }) }),
+        {
+          onRecoverableError: (err, info) => {
+            warn("Recoverable hydration error:", err, info);
+          }
+        }
+      );
+      if (enableDebug) log("Hydration completed");
+      onSuccess?.();
+    } catch (err) {
+      error("Hydration error:", err);
+      onHydrationError?.(err);
+    }
+  };
   const bootstrap = () => {
-    log("Hydration started");
-    const rootElement = document.getElementById(rootElementId);
-    if (!rootElement) {
+    const rootEl = document.getElementById(rootElementId);
+    if (!rootEl) {
       error(`Root element with id "${rootElementId}" not found.`);
       return;
     }
-    const initialData = window[initialDataKey];
-    if (!initialData) {
-      warn(`Initial data key "${initialDataKey}" is undefined on window. Defaulting to SPA createRoot`);
-      const root = createRoot(rootElement);
-      root.render(/* @__PURE__ */ jsx2(React2.StrictMode, { children: appComponent }));
-    } else {
-      log("Initial data loaded:", initialData);
-      const initialDataPromise = Promise.resolve(initialData);
-      const store = createSSRStore(initialDataPromise);
-      log("Store created:", store);
-      hydrateRoot(
-        rootElement,
-        /* @__PURE__ */ jsx2(React2.StrictMode, { children: /* @__PURE__ */ jsx2(SSRStoreProvider, { store, children: appComponent }) })
-      );
-      log("Hydration completed");
+    const data = window[dataKey];
+    if (data === void 0) {
+      if (enableDebug) warn(`No initial SSR data at window["${dataKey}"]. Mounting CSR.`);
+      mountCSR(rootEl);
+      return;
     }
+    startHydration(rootEl, data);
   };
   if (document.readyState !== "loading") {
     bootstrap();
   } else {
-    document.addEventListener("DOMContentLoaded", bootstrap);
+    document.addEventListener("DOMContentLoaded", bootstrap, { once: true });
   }
-};
+}
 
 // src/SSRRender.tsx
-import "http";
-import { Writable } from "stream";
 import "react";
 import { renderToPipeableStream, renderToString } from "react-dom/server";
-import { jsx as jsx3 } from "react/jsx-runtime";
-var resolveHeadContent = (headContent, meta = {}) => typeof headContent === "function" ? headContent(meta) : headContent;
-var createRenderer = ({ appComponent, headContent }) => {
-  const renderSSR = async (initialDataPromise, location, meta = {}) => {
-    const dataForHeadContent = Object.keys(initialDataPromise).length > 0 ? initialDataPromise : meta;
-    const dynamicHeadContent = resolveHeadContent(headContent, dataForHeadContent);
-    const appHtml = renderToString(/* @__PURE__ */ jsx3(SSRStoreProvider, { store: createSSRStore(initialDataPromise), children: appComponent({ location }) }));
-    return {
-      headContent: dynamicHeadContent,
-      appHtml
+
+// src/utils/Streaming.ts
+var DEFAULT_BENIGN_ERRORS = /ECONNRESET|EPIPE|socket hang up|aborted|premature/i;
+function isBenignStreamErr(err) {
+  const msg = String(err?.message ?? "");
+  return DEFAULT_BENIGN_ERRORS.test(msg);
+}
+function createSettler() {
+  let settled = false;
+  let resolve;
+  let reject;
+  const done = new Promise((r, j) => {
+    resolve = () => {
+      if (!settled) {
+        settled = true;
+        r();
+      }
     };
+    reject = (e) => {
+      if (!settled) {
+        settled = true;
+        j(e);
+      }
+    };
+  });
+  return { done, resolve, reject, isSettled: () => settled };
+}
+function startShellTimer(ms, onTimeout) {
+  const t = setTimeout(onTimeout, ms);
+  return () => clearTimeout(t);
+}
+function wireWritableGuards(writable, {
+  benignAbort,
+  fatalAbort,
+  onError,
+  onFinish,
+  benignErrorPattern = DEFAULT_BENIGN_ERRORS
+}) {
+  const handlers = [];
+  const add = (ev, fn) => {
+    writable.once(ev, fn);
+    handlers.push(() => writable.removeListener(ev, fn));
   };
-  const renderStream = (serverResponse, callbacks, initialDataPromise, location, bootstrapModules, meta = {}, cspNonce) => {
-    const dynamicHeadContent = resolveHeadContent(headContent, meta);
-    createRenderStream(
-      serverResponse,
-      callbacks,
-      {
-        appComponent: (props) => appComponent({ ...props, location }),
-        headContent: dynamicHeadContent,
-        initialDataPromise,
-        location,
-        bootstrapModules
-      },
-      cspNonce
-    );
+  add("error", (err) => {
+    const msg = String(err?.message ?? "");
+    if (benignErrorPattern.test(msg)) {
+      benignAbort("Client disconnected during stream");
+    } else {
+      onError?.(err);
+      fatalAbort(err);
+    }
+  });
+  add("close", () => benignAbort("Writable closed early (likely client disconnect)"));
+  add("finish", () => {
+    if (onFinish) onFinish();
+    else benignAbort("Stream finished (normal completion)");
+  });
+  return {
+    cleanup: () => {
+      for (const off of handlers) {
+        try {
+          off();
+        } catch {
+        }
+      }
+    }
   };
-  return { renderSSR, renderStream };
-};
-var createRenderStream = (serverResponse, { onHead, onFinish, onError }, {
+}
+function createStreamController(writable, logger) {
+  const { log, warn, error } = logger;
+  let aborted = false;
+  const settle = createSettler();
+  let stopShellTimer;
+  let removeAbortListener;
+  let guardsCleanup;
+  let streamAbort;
+  const cleanup = (benign, err) => {
+    if (aborted) return;
+    aborted = true;
+    try {
+      stopShellTimer?.();
+    } catch {
+    }
+    try {
+      removeAbortListener?.();
+    } catch {
+    }
+    try {
+      guardsCleanup?.();
+    } catch {
+    }
+    try {
+      streamAbort?.();
+    } catch {
+    }
+    try {
+      if (!writable.writableEnded && !writable.destroyed) writable.destroy();
+    } catch {
+    }
+    if (benign) settle.resolve();
+    else if (err !== void 0) settle.reject(err);
+    else settle.resolve();
+  };
+  return {
+    setStreamAbort: (fn) => {
+      streamAbort = fn;
+    },
+    setStopShellTimer: (fn) => {
+      stopShellTimer = fn;
+    },
+    setRemoveAbortListener: (fn) => {
+      removeAbortListener = fn;
+    },
+    setGuardsCleanup: (fn) => {
+      guardsCleanup = fn;
+    },
+    complete(message) {
+      if (aborted) return;
+      if (message) (log ?? warn)(message);
+      cleanup(true);
+    },
+    benignAbort(why) {
+      if (aborted) return;
+      warn(why);
+      cleanup(true);
+    },
+    fatalAbort(err) {
+      if (aborted) return;
+      error("Stream aborted with error:", err);
+      cleanup(false, err);
+    },
+    get done() {
+      return settle.done;
+    },
+    get isAborted() {
+      return aborted;
+    }
+  };
+}
+
+// src/SSRRender.tsx
+import { jsx as jsx3 } from "react/jsx-runtime";
+function createRenderer({
   appComponent,
   headContent,
-  initialDataPromise,
-  location,
-  bootstrapModules
-}, cspNonce) => {
-  const store = createSSRStore(initialDataPromise);
-  const appElement = /* @__PURE__ */ jsx3(SSRStoreProvider, { store, children: appComponent({ location }) });
-  const { pipe } = renderToPipeableStream(appElement, {
-    nonce: cspNonce,
-    bootstrapModules: bootstrapModules ? [bootstrapModules] : void 0,
-    onShellReady() {
-      const dynamicHeadContent = resolveHeadContent(headContent, initialDataPromise);
-      onHead(dynamicHeadContent);
-      pipe(
-        new Writable({
-          write(chunk, _encoding, callback) {
-            serverResponse.write(chunk, callback);
-          },
-          final(callback) {
-            onFinish(store.getSnapshot());
-            callback();
+  streamOptions = {},
+  logger,
+  enableDebug = false
+}) {
+  const { shellTimeoutMs = 1e4, useCork = true } = streamOptions;
+  const renderSSR = async (initialData, location, meta = {}, signal, opts) => {
+    const { log, warn } = createUILogger(opts?.logger ?? logger, {
+      debugCategory: "ssr",
+      context: { scope: "react-ssr" },
+      enableDebug
+    });
+    if (signal?.aborted) {
+      warn("SSR skipped; already aborted", { location });
+      return { headContent: "", appHtml: "", aborted: true };
+    }
+    let aborted = false;
+    const onAbort = () => aborted = true;
+    signal?.addEventListener("abort", onAbort, { once: true });
+    try {
+      log("Starting SSR:", location);
+      const dynamicHead = headContent({ data: initialData, meta });
+      const store = createSSRStore(initialData);
+      const html = renderToString(/* @__PURE__ */ jsx3(SSRStoreProvider, { store, children: appComponent({ location }) }));
+      if (aborted) {
+        warn("SSR completed after client abort", { location });
+        return { headContent: "", appHtml: "", aborted: true };
+      }
+      log("Completed SSR:", location);
+      return { headContent: dynamicHead, appHtml: html, aborted: false };
+    } finally {
+      try {
+        signal?.removeEventListener("abort", onAbort);
+      } catch {
+      }
+    }
+  };
+  const renderStream = (writable, callbacks = {}, initialData, location, bootstrapModules, meta = {}, cspNonce, signal, opts) => {
+    const { onAllReady, onError, onHead, onShellReady, onFinish } = callbacks;
+    const { log, warn, error } = createUILogger(opts?.logger ?? logger, {
+      debugCategory: "ssr",
+      context: { scope: "react-streaming" },
+      enableDebug
+    });
+    const effectiveShellTimeout = opts?.shellTimeoutMs ?? shellTimeoutMs;
+    const effectiveUseCork = opts?.useCork ?? useCork;
+    const controller = createStreamController(writable, { log, warn, error });
+    if (signal) {
+      const handleAbortSignal = () => controller.benignAbort(`AbortSignal triggered; aborting stream for location: ${location}`);
+      if (signal.aborted) {
+        handleAbortSignal();
+        return { abort: () => {
+        }, done: Promise.resolve() };
+      }
+      signal.addEventListener("abort", handleAbortSignal, { once: true });
+      controller.setRemoveAbortListener(() => {
+        try {
+          signal.removeEventListener("abort", handleAbortSignal);
+        } catch {
+        }
+      });
+    }
+    const { cleanup: guardsCleanup } = wireWritableGuards(writable, {
+      benignAbort: (why) => controller.benignAbort(why),
+      fatalAbort: (err) => {
+        onError?.(err);
+        controller.fatalAbort(err);
+      },
+      onError,
+      onFinish: () => controller.complete("Stream finished (normal completion)")
+    });
+    controller.setGuardsCleanup(guardsCleanup);
+    const stopShellTimer = startShellTimer(effectiveShellTimeout, () => {
+      if (controller.isAborted) return;
+      const timeoutErr = new Error(`Shell not ready after ${effectiveShellTimeout}ms`);
+      onError?.(timeoutErr);
+      controller.fatalAbort(timeoutErr);
+    });
+    controller.setStopShellTimer(stopShellTimer);
+    log("Starting stream:", location);
+    try {
+      const store = createSSRStore(initialData);
+      const appElement = /* @__PURE__ */ jsx3(SSRStoreProvider, { store, children: appComponent({ location }) });
+      const stream = renderToPipeableStream(appElement, {
+        nonce: cspNonce,
+        bootstrapModules: bootstrapModules ? [bootstrapModules] : void 0,
+        onShellReady() {
+          if (controller.isAborted) return;
+          try {
+            stopShellTimer();
+          } catch {
           }
-        })
-      );
-    },
-    onAllReady() {
-    },
-    onError(error) {
-      onError(error);
+          log("Shell ready:", location);
+          try {
+            let headData;
+            try {
+              headData = store.getSnapshot();
+            } catch (thrown) {
+              if (thrown && typeof thrown.then === "function") {
+                thrown.catch(() => {
+                });
+              }
+            }
+            const head = headContent({ data: headData ?? {}, meta });
+            const canCork = effectiveUseCork && typeof writable?.cork === "function" && typeof writable?.uncork === "function";
+            if (canCork) {
+              try {
+                writable.cork();
+              } catch {
+              }
+            }
+            let wroteOk = true;
+            try {
+              const res = writable?.write ? writable.write(head) : true;
+              wroteOk = res !== false;
+            } finally {
+              if (canCork) {
+                try {
+                  writable.uncork();
+                } catch {
+                }
+              }
+            }
+            let forceWait = false;
+            try {
+              const ret = onHead?.(head);
+              forceWait = ret === false;
+            } catch (cbErr) {
+              warn("onHead callback threw:", cbErr);
+            }
+            const startPipe = () => stream.pipe(writable);
+            if (forceWait || !wroteOk) writable?.once?.("drain", startPipe);
+            else startPipe();
+            try {
+              onShellReady?.();
+            } catch (cbErr) {
+              warn("onShellReady callback threw:", cbErr);
+            }
+          } catch (err) {
+            onError?.(err);
+            controller.fatalAbort(err);
+          }
+        },
+        onAllReady() {
+          if (controller.isAborted) return;
+          log("All content ready:", location);
+          const deliver = () => {
+            try {
+              const data = store.getSnapshot();
+              onAllReady?.(data);
+              onFinish?.(data);
+            } catch (thrown) {
+              if (thrown && typeof thrown.then === "function") {
+                thrown.then(deliver).catch((e) => {
+                  error("Data promise rejected:", e);
+                  onError?.(e);
+                  controller.fatalAbort(e);
+                });
+              } else {
+                error("Unexpected throw from getSnapshot:", thrown);
+                onError?.(thrown);
+                controller.fatalAbort(thrown);
+              }
+            }
+          };
+          deliver();
+        },
+        onShellError(err) {
+          if (controller.isAborted) return;
+          try {
+            stopShellTimer();
+          } catch {
+          }
+          onError?.(err);
+          controller.fatalAbort(err);
+        },
+        onError(err) {
+          if (controller.isAborted) return;
+          const msg = String(err?.message ?? "");
+          warn?.("React stream error:", msg);
+          if (isBenignStreamErr(err)) {
+            controller.benignAbort("Client disconnected before stream finished");
+            return;
+          }
+          onError?.(err);
+          controller.fatalAbort(err);
+        }
+      });
+      controller.setStreamAbort(() => stream.abort());
+    } catch (err) {
+      onError?.(err);
+      controller.fatalAbort(err);
     }
-  });
-};
+    return {
+      abort: () => controller.benignAbort(`Manual abort for location: ${location}`),
+      done: controller.done
+      // resolves on success/benign cancel; rejects on fatal error
+    };
+  };
+  return { renderSSR, renderStream };
+}
 export {
   SSRStoreProvider,
-  createRenderStream,
   createRenderer,
   createSSRStore,
   hydrateApp,
-  resolveHeadContent,
   useSSRStore
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taujs/react",
-  "version": "0.0.8",
+  "version": "0.1.0",
   "description": "taujs | τjs",
   "author": "Aoede <taujs@aoede.uk.net> (https://www.aoede.uk.net)",
   "license": "MIT",
@@ -38,7 +38,6 @@
   "files": [
     "dist"
   ],
-  "dependencies": {},
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.15.4",
     "@babel/preset-typescript": "^7.24.7",
@@ -48,24 +47,23 @@
     "@types/node": "^24.0.7",
     "@types/react": "^19.0.2",
     "@types/react-dom": "^19.0.2",
-    "@vitest/coverage-v8": "^2.1.0",
-    "@vitest/ui": "^2.1.9",
+    "@vitest/coverage-v8": "^3.2.4",
+    "@vitest/ui": "^3.2.4",
     "jsdom": "^25.0.0",
     "prettier": "^3.3.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "tsup": "^8.2.4",
     "typescript": "^5.5.4",
-    "vite": "^6.3.5",
-    "vitest": "^2.0.5"
+    "vite": "^7.1.9",
+    "vitest": "^3.2.4"
   },
   "peerDependencies": {
-    "@taujs/server": "^0.3.0",
     "@vitejs/plugin-react": "^4.6.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "typescript": "^5.5.4",
-    "vite": "^6.3.5"
+    "vite": "^7.1.9"
   },
   "peerDependenciesMeta": {
     "react": {