pulse-js-framework 1.8.3 → 1.9.2

package/runtime/ssr-stream.js

@@ -0,0 +1,388 @@
+/**
+ * Pulse SSR Streaming - Streaming server-side rendering
+ *
+ * Provides streaming SSR using Web Streams API (ReadableStream).
+ * Sends shell HTML immediately, streams async content as it resolves.
+ * Compatible with Node.js pipe() via Readable.fromWeb() and Web Streams.
+ *
+ * @module pulse-js-framework/runtime/ssr-stream
+ */
+
+import { createContext, batch, setSSRMode as setPulseSSRMode } from './pulse.js';
+import { MockDOMAdapter, withAdapter } from './dom-adapter.js';
+import { serializeToHTML, serializeChildren, escapeAttr } from './ssr-serializer.js';
+import { SSRAsyncContext, setSSRAsyncContext } from './ssr-async.js';
+import { loggers } from './logger.js';
+
+const log = loggers.dom;
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Minimal client-side script that replaces streaming boundary markers
+ * with resolved content. Injected once into the stream.
+ * ~200 bytes minified.
+ */
+const STREAMING_RUNTIME_SCRIPT = `<script>function $P(i,h){var b=document.querySelectorAll('[data-ssr-boundary="'+i+'"]');if(b.length===2){var r=document.createRange();r.setStartAfter(b[0]);r.setEndBefore(b[1]);r.deleteContents();var t=document.createElement('template');t.innerHTML=h;r.insertNode(t.content);b[0].remove();b[1].remove()}}</script>`;
+
+// ============================================================================
+// SSR Stream Context
+// ============================================================================
+
+/**
+ * Manages streaming SSR state: boundary tracking, chunk queue, flush control.
+ */
+export class SSRStreamContext {
+  constructor(options = {}) {
+    /** @type {number} Next boundary ID */
+    this._nextId = 0;
+
+    /** @type {Map<number, {promise: Promise, fallback: string}>} */
+    this.boundaries = new Map();
+
+    /** @type {boolean} */
+    this.shellFlushed = false;
+
+    /** @type {number} */
+    this.timeout = options.timeout ?? 10000;
+
+    /** @type {Function|null} */
+    this.onShellError = options.onShellError ?? null;
+
+    /** @type {Function|null} */
+    this.onBoundaryError = options.onBoundaryError ?? null;
+  }
+
+  /**
+   * Create a new boundary ID for an async chunk.
+   * @returns {number}
+   */
+  createBoundary() {
+    return this._nextId++;
+  }
+
+  /**
+   * Register an async boundary with its promise and fallback HTML.
+   * @param {number} id - Boundary ID
+   * @param {Promise} promise - Promise that resolves to content
+   * @param {string} fallback - Fallback HTML shown while loading
+   */
+  registerBoundary(id, promise, fallback) {
+    this.boundaries.set(id, { promise, fallback });
+  }
+
+  /**
+   * Get the number of pending boundaries.
+   * @returns {number}
+   */
+  get pendingCount() {
+    return this.boundaries.size;
+  }
+}
+
+// ============================================================================
+// Boundary Markers
+// ============================================================================
+
+/**
+ * Create opening boundary marker comment.
+ * @param {number} id - Boundary ID
+ * @returns {string}
+ */
+export function createBoundaryStart(id) {
+  return `<!--$B:${id}-->`;
+}
+
+/**
+ * Create closing boundary marker comment.
+ * @param {number} id - Boundary ID
+ * @returns {string}
+ */
+export function createBoundaryEnd(id) {
+  return `<!--/$B:${id}-->`;
+}
+
+/**
+ * Create boundary marker pair with data attributes for client-side replacement.
+ * @param {number} id - Boundary ID
+ * @param {string} fallbackHtml - Fallback content HTML
+ * @returns {string}
+ */
+export function createBoundaryMarker(id, fallbackHtml) {
+  return (
+    `<template data-ssr-boundary="${id}" style="display:none"></template>` +
+    fallbackHtml +
+    `<template data-ssr-boundary="${id}" style="display:none"></template>`
+  );
+}
+
+/**
+ * Create a replacement script that swaps boundary content on the client.
+ * @param {number} id - Boundary ID
+ * @param {string} html - Resolved content HTML
+ * @returns {string}
+ */
+export function createReplacementScript(id, html) {
+  // Use JSON.stringify for safe JS string embedding, then escape HTML-sensitive sequences
+  const escaped = JSON.stringify(html)
+    .replace(/<\/script/gi, '<\\u002fscript')
+    .replace(/<!--/g, '<\\u0021--');
+  return `<script>$P(${Number(id)},${escaped})</script>`;
+}
+
+// ============================================================================
+// Streaming SSR
+// ============================================================================
+
+/**
+ * @typedef {Object} RenderToStreamOptions
+ * @property {string} [shellStart] - HTML before app content
+ * @property {string} [shellEnd] - HTML after app content
+ * @property {number} [timeout=10000] - Timeout for async boundaries (ms)
+ * @property {Function} [onShellError] - Error callback during shell render
+ * @property {Function} [onBoundaryError] - Error callback for async boundary
+ * @property {string[]} [bootstrapScripts] - Script URLs to include in shell
+ * @property {string[]} [bootstrapModules] - Module script URLs to include
+ * @property {boolean} [generatePreloadHints=false] - Generate link preload tags
+ */
+
+/**
+ * Render a component tree to a ReadableStream.
+ *
+ * Sends the HTML shell immediately, then streams async content
+ * as each boundary resolves. The browser renders progressive content
+ * without needing client-side JavaScript for the initial swap.
+ *
+ * @param {Function} componentFactory - Function that returns the root component
+ * @param {RenderToStreamOptions} [options] - Streaming options
+ * @returns {ReadableStream} HTML stream
+ *
+ * @example
+ * const stream = renderToStream(() => App(), {
+ *   shellStart: '<!DOCTYPE html><html><head></head><body><div id="app">',
+ *   shellEnd: '</div></body></html>',
+ *   timeout: 5000
+ * });
+ *
+ * // Web Streams
+ * return new Response(stream, { headers: { 'Content-Type': 'text/html' } });
+ *
+ * // Node.js pipe
+ * import { Readable } from 'stream';
+ * Readable.fromWeb(stream).pipe(res);
+ */
+export function renderToStream(componentFactory, options = {}) {
+  const {
+    shellStart = '',
+    shellEnd = '',
+    timeout = 10000,
+    onShellError = null,
+    onBoundaryError = null,
+    bootstrapScripts = [],
+    bootstrapModules = []
+  } = options;
+
+  const streamCtx = new SSRStreamContext({ timeout, onShellError, onBoundaryError });
+
+  let streamController;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      streamController = controller;
+      const encoder = new TextEncoder();
+
+      // Run SSR in microtask to allow stream to be returned first
+      Promise.resolve().then(async () => {
+        try {
+          // Enable SSR mode
+          setPulseSSRMode(true);
+
+          const ctx = createContext({ name: 'ssr-stream' });
+          const asyncCtx = new SSRAsyncContext();
+          const adapter = new MockDOMAdapter();
+
+          let shellHtml = '';
+
+          try {
+            // Render shell synchronously
+            ctx.run(() => {
+              withAdapter(adapter, () => {
+                setSSRAsyncContext(asyncCtx);
+
+                const result = componentFactory();
+                if (result) {
+                  adapter.appendChild(adapter.getBody(), result);
+                }
+
+                shellHtml = serializeChildren(adapter.getBody());
+                setSSRAsyncContext(null);
+              });
+            });
+          } catch (shellError) {
+            if (onShellError) {
+              onShellError(shellError);
+            }
+            log.error('SSR shell render error:', shellError.message);
+            controller.close();
+            setPulseSSRMode(false);
+            ctx.reset();
+            return;
+          }
+
+          // Build script tags
+          let scriptTags = '';
+          for (const src of bootstrapScripts) {
+            scriptTags += `<script src="${escapeAttr(src)}"></script>`;
+          }
+          for (const src of bootstrapModules) {
+            scriptTags += `<script type="module" src="${escapeAttr(src)}"></script>`;
+          }
+
+          // Enqueue shell HTML
+          const shellContent = shellStart + shellHtml + scriptTags;
+          controller.enqueue(encoder.encode(shellContent));
+          streamCtx.shellFlushed = true;
+
+          // If there are pending async operations, stream them
+          if (asyncCtx.pendingCount > 0) {
+            // Inject streaming runtime script
+            controller.enqueue(encoder.encode(STREAMING_RUNTIME_SCRIPT));
+
+            // Wait for each async operation and stream results
+            const boundaryPromises = [];
+
+            for (const { key, promise } of asyncCtx.pending) {
+              const boundaryId = streamCtx.createBoundary();
+
+              const boundaryPromise = Promise.resolve(promise)
+                .then(async () => {
+                  // Re-render with resolved data
+                  const boundaryAdapter = new MockDOMAdapter();
+                  const boundaryCtx = createContext({ name: `ssr-boundary-${boundaryId}` });
+
+                  try {
+                    let boundaryHtml = '';
+                    boundaryCtx.run(() => {
+                      withAdapter(boundaryAdapter, () => {
+                        setSSRAsyncContext(asyncCtx);
+                        const result = componentFactory();
+                        if (result) {
+                          boundaryAdapter.appendChild(boundaryAdapter.getBody(), result);
+                        }
+                        boundaryHtml = serializeChildren(boundaryAdapter.getBody());
+                        setSSRAsyncContext(null);
+                      });
+                    });
+
+                    const script = createReplacementScript(boundaryId, boundaryHtml);
+                    controller.enqueue(encoder.encode(script));
+                  } finally {
+                    boundaryCtx.reset();
+                  }
+                })
+                .catch(err => {
+                  if (onBoundaryError) {
+                    onBoundaryError(boundaryId, err);
+                  }
+                  log.warn(`SSR boundary ${boundaryId} error:`, err.message);
+                });
+
+              boundaryPromises.push(boundaryPromise);
+            }
+
+            // Wait for all boundaries with timeout
+            const timeoutPromise = new Promise(resolve => {
+              setTimeout(() => {
+                log.warn(`SSR streaming timed out after ${timeout}ms`);
+                resolve();
+              }, timeout);
+            });
+
+            await Promise.race([
+              Promise.allSettled(boundaryPromises),
+              timeoutPromise
+            ]);
+          }
+
+          // Enqueue shell end and close
+          if (shellEnd) {
+            controller.enqueue(encoder.encode(shellEnd));
+          }
+          controller.close();
+
+          // Clean up
+          setPulseSSRMode(false);
+          ctx.reset();
+
+        } catch (err) {
+          log.error('SSR stream error:', err.message);
+          try {
+            controller.error(err);
+          } catch {
+            // Controller may already be closed
+          }
+          setPulseSSRMode(false);
+        }
+      });
+    },
+
+    cancel() {
+      // Stream was cancelled by consumer
+      setPulseSSRMode(false);
+    }
+  });
+
+  return stream;
+}
+
+/**
+ * Render to a ReadableStream with abort control.
+ *
+ * @param {Function} componentFactory - Function that returns the root component
+ * @param {RenderToStreamOptions} [options] - Streaming options
+ * @returns {{ stream: ReadableStream, abort: Function }}
+ *
+ * @example
+ * const { stream, abort } = renderToReadableStream(() => App(), options);
+ * // Later: abort() to cancel streaming
+ */
+export function renderToReadableStream(componentFactory, options = {}) {
+  let abortController;
+
+  // Wrap with abort support
+  const wrappedOptions = {
+    ...options,
+    onShellError: (err) => {
+      options.onShellError?.(err);
+    }
+  };
+
+  const stream = renderToStream(componentFactory, wrappedOptions);
+
+  const abort = () => {
+    try {
+      stream.cancel('Aborted by caller');
+    } catch {
+      // Stream may already be closed
+    }
+  };
+
+  return { stream, abort };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default {
+  SSRStreamContext,
+  createBoundaryStart,
+  createBoundaryEnd,
+  createBoundaryMarker,
+  createReplacementScript,
+  renderToStream,
+  renderToReadableStream,
+  STREAMING_RUNTIME_SCRIPT
+};

package/runtime/ssr.js

@@ -2,6 +2,8 @@
  * Pulse SSR - Server-Side Rendering Module
  *
  * Provides server-side rendering and client-side hydration for Pulse applications.
+ * Includes streaming SSR, selective rendering (@client/@server), and hydration
+ * mismatch detection.
  *
  * @module pulse-js-framework/runtime/ssr
  *
@@ -25,6 +27,15 @@
  * hydrate('#app', () => App(), {
  *   state: window.__PULSE_STATE__
  * });
+ *
+ * @example
+ * // Streaming SSR
+ * import { renderToStream } from 'pulse-js-framework/runtime/ssr';
+ *
+ * const stream = renderToStream(() => App(), {
+ *   shellStart: '<!DOCTYPE html><html><body><div id="app">',
+ *   shellEnd: '</div></body></html>'
+ * });
  */
 
 import { createContext, batch, setSSRMode as setPulseSSRMode, isSSRMode } from './pulse.js';
@@ -298,6 +309,76 @@ export function hydrate(target, componentFactory, options = {}) {
   };
 }
 
+// ============================================================================
+// Selective SSR: ClientOnly / ServerOnly (#39)
+// ============================================================================
+
+/**
+ * Render content only on the client side. During SSR, renders the fallback
+ * (or an empty comment node). On the client, renders the main content.
+ *
+ * Use this for browser-only components (charts, maps, animations, etc.)
+ * that would break during server-side rendering.
+ *
+ * @param {Function} clientFactory - Factory function for client-side content
+ * @param {Function} [fallbackFactory] - Optional fallback factory for SSR
+ * @returns {*} DOM node(s) or comment placeholder
+ *
+ * @example
+ * import { ClientOnly } from 'pulse-js-framework/runtime/ssr';
+ *
+ * const chart = ClientOnly(
+ *   () => el('canvas.chart', { onmount: initChart }),
+ *   () => el('.placeholder', 'Chart loading...')
+ * );
+ *
+ * @example
+ * // In .pulse file with @client directive:
+ * // .chart @client { canvas "Loading..." }
+ */
+export function ClientOnly(clientFactory, fallbackFactory) {
+  if (isSSR()) {
+    // During SSR: render fallback or empty placeholder
+    if (fallbackFactory) {
+      return fallbackFactory();
+    }
+    // Return a comment node as placeholder
+    const adapter = getAdapter();
+    return adapter.createComment('client-only');
+  }
+  // On client: render the actual content
+  return clientFactory();
+}
+
+/**
+ * Render content only during SSR. On the client, renders an empty comment node.
+ *
+ * Use this for server-only content like JSON-LD structured data,
+ * meta tags, or server-side analytics scripts.
+ *
+ * @param {Function} serverFactory - Factory function for server-side content
+ * @returns {*} DOM node(s) or comment placeholder
+ *
+ * @example
+ * import { ServerOnly } from 'pulse-js-framework/runtime/ssr';
+ *
+ * const seoData = ServerOnly(
+ *   () => el('script[type=application/ld+json]', JSON.stringify(schema))
+ * );
+ *
+ * @example
+ * // In .pulse file with @server directive:
+ * // .seo @server { script[type=application/ld+json] "{seoJson}" }
+ */
+export function ServerOnly(serverFactory) {
+  if (isSSR()) {
+    return serverFactory();
+  }
+  // On client: empty placeholder
+  const adapter = getAdapter();
+  return adapter.createComment('server-only');
+}
+
 // ============================================================================
 // State Serialization
 // ============================================================================
@@ -365,9 +446,12 @@ export function serializeState(state) {
   const preprocessed = preprocessForSerialization(state);
 
   return JSON.stringify(preprocessed)
-    // Escape </script> to prevent XSS
-    .replace(/<\/script/gi, '<\\/script')
-    .replace(/<!--/g, '<\\!--');
+    // Escape all < and > to prevent HTML parser interference in <script> context
+    .replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    // Escape unicode line/paragraph separators (invalid in JS strings pre-ES2019)
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029');
 }
 
 /**
@@ -455,6 +539,15 @@ export function clearSSRState() {
 export { isHydratingMode, getHydrationContext } from './ssr-hydrator.js';
 export { getSSRAsyncContext } from './ssr-async.js';
 
+// Streaming SSR (#38)
+export { renderToStream, renderToReadableStream } from './ssr-stream.js';
+
+// Hydration mismatch detection (#44)
+export { MismatchType, diffNodes, logMismatches, getSuggestion } from './ssr-mismatch.js';
+
+// Preload hints (#42)
+export { generatePreloadHints, getRoutePreloads, parseBuildManifest, createPreloadMiddleware, hintsToHTML } from './ssr-preload.js';
+
 // ============================================================================
 // Default Export
 // ============================================================================
@@ -465,6 +558,13 @@ export default {
   renderToStringSync,
   hydrate,
 
+  // Streaming
+  // renderToStream and renderToReadableStream are re-exported above
+
+  // Selective rendering
+  ClientOnly,
+  ServerOnly,
+
   // State management
   serializeState,
   deserializeState,

package/server/express.js

@@ -0,0 +1,108 @@
+/**
+ * Pulse Express Adapter
+ *
+ * Middleware for Express.js that handles SSR, static asset serving,
+ * and state serialization for Pulse applications.
+ *
+ * @module pulse-js-framework/server/express
+ *
+ * @example
+ * import express from 'express';
+ * import { createExpressMiddleware } from 'pulse-js-framework/server/express';
+ * import App from './src/App.js';
+ *
+ * const app = express();
+ *
+ * app.use(createExpressMiddleware({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist'
+ * }));
+ *
+ * app.listen(3000);
+ */
+
+import { join } from 'path';
+import { createPulseHandler, resolveStaticAsset } from './index.js';
+import { createRequestContext } from './utils.js';
+
+// ============================================================================
+// Express Middleware
+// ============================================================================
+
+/**
+ * @typedef {import('./index.js').PulseMiddlewareOptions} PulseMiddlewareOptions
+ */
+
+/**
+ * Create Express middleware for Pulse SSR.
+ *
+ * @param {PulseMiddlewareOptions} options - Middleware options
+ * @returns {Function} Express middleware (req, res, next)
+ *
+ * @example
+ * app.use(createExpressMiddleware({
+ *   app: ({ route }) => App({ route }),
+ *   templatePath: './dist/index.html',
+ *   distDir: './dist',
+ *   streaming: false
+ * }));
+ */
+export function createExpressMiddleware(options = {}) {
+  const { distDir = 'dist', serveStatic = true } = options;
+  const handler = createPulseHandler(options);
+  const resolvedDistDir = join(process.cwd(), distDir);
+
+  return async function pulseMiddleware(req, res, next) {
+    // Skip non-GET requests
+    if (req.method !== 'GET') {
+      return next();
+    }
+
+    const pathname = req.path || req.url;
+
+    // Serve static assets first
+    if (serveStatic && pathname.startsWith('/assets/')) {
+      const asset = resolveStaticAsset(pathname, resolvedDistDir);
+      if (asset) {
+        for (const [key, value] of Object.entries(asset.headers)) {
+          res.setHeader(key, value);
+        }
+        return res.status(asset.status).end(asset.content);
+      }
+    }
+
+    // Skip API routes
+    if (pathname.startsWith('/api/')) {
+      return next();
+    }
+
+    try {
+      const ctx = createRequestContext(req, 'express');
+      const result = await handler(ctx);
+
+      res.status(result.status);
+      for (const [key, value] of Object.entries(result.headers)) {
+        res.setHeader(key, value);
+      }
+
+      // Handle streaming response
+      if (result.stream) {
+        const { Readable } = await import('stream');
+        const nodeStream = Readable.fromWeb(result.stream);
+        nodeStream.pipe(res);
+        return;
+      }
+
+      res.end(result.body);
+    } catch (error) {
+      next(error);
+    }
+  };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export default { createExpressMiddleware };