@jasonshimmy/custom-elements-runtime 3.0.0 → 3.1.1

package/dist/runtime/scheduler.d.ts

@@ -7,6 +7,18 @@
  *                    (time-sliced, non-blocking rendering for low-priority work).
  */
 export type UpdatePriority = 'immediate' | 'normal' | 'idle';
+/**
+ * Environment detection utilities
+ */
+export interface TestEnvironment {
+    isTest: boolean;
+    isVitest: boolean;
+    isCypress: boolean;
+}
+/**
+ * Detect test environment with improved reliability
+ */
+export declare function detectTestEnvironment(): TestEnvironment;
 declare class UpdateScheduler {
     private pendingUpdates;
     private isFlushScheduled;

package/dist/runtime/ssr-context.d.ts

@@ -0,0 +1,47 @@
+/**
+ * SSR execution context for running component render functions server-side.
+ *
+ * When generating Declarative Shadow DOM (DSD) output, the SSR renderer must
+ * call each custom element's render function to obtain its shadow DOM VNode
+ * tree and capture any useStyle() / useGlobalStyle() output. This module
+ * provides the minimal execution environment that makes that safe.
+ *
+ * Guarantees:
+ *  - useStyle() callbacks are executed and their output is captured.
+ *  - useGlobalStyle() callbacks are captured (not injected into document).
+ *  - Lifecycle hooks (useOnConnected, watch, …) register harmlessly to arrays
+ *    that are never invoked.
+ *  - The reactive system is never permanently mutated — component registration
+ *    is cleaned up by the render wrapper in factory.ts after each call.
+ */
+import type { ComponentConfig, VNode } from './types';
+/** Start collecting useGlobalStyle() output from the current render pass. */
+export declare function beginSSRGlobalStyleCollection(): void;
+/** Stop collecting and return everything gathered so far. */
+export declare function endSSRGlobalStyleCollection(): string[];
+/**
+ * Called by useGlobalStyle() when an SSR collection pass is active.
+ * Returns true if the CSS was captured (caller should skip DOM injection).
+ */
+export declare function captureGlobalStyleForSSR(css: string): boolean;
+export interface SSRRenderResult {
+    /** VNode tree from the component's render function (shadow DOM content). */
+    shadowVNode: VNode | VNode[] | null;
+    /** CSS string captured from useStyle() calls during this render. */
+    useStyleCSS: string;
+    /** Present when the component's render function returned a Promise. */
+    asyncPromise?: Promise<VNode | VNode[]>;
+}
+/**
+ * Run a component's render function in a minimal SSR context to capture its
+ * shadow DOM VNode tree and any useStyle() output.
+ *
+ * The component's render wrapper in factory.ts handles:
+ *   - setCurrentComponentContext / clearCurrentComponentContext
+ *   - _hookCallbacks reset
+ *   - _computedStyle reset
+ *   - reactiveSystem registration / cleanup
+ *
+ * We only need to build a context object that satisfies the hooks' expectations.
+ */
+export declare function runComponentSSRRender(config: ComponentConfig<object, object, object, object>, attrs: Record<string, string | number | boolean | null | undefined>, tag?: string): SSRRenderResult;

package/dist/runtime/ssr-utils.d.ts

@@ -0,0 +1,9 @@
+export type RenderOptions = {
+    /** Backwards-compatible: whether to inject the SVG namespace on <svg> nodes (default true) */
+    injectSvgNamespace?: boolean;
+    /** Inject known well-known namespaces for tags like <math> when missing (default follows injectSvgNamespace) */
+    injectKnownNamespaces?: boolean;
+};
+export declare const VOID_ELEMENTS: Set<string>;
+export declare function buildAttrs(attrs: Record<string, unknown>, tag: string, opts: RenderOptions): string;
+export declare function buildRawAttrs(attrs: Record<string, unknown>): string;

package/dist/runtime/types.d.ts

@@ -86,11 +86,29 @@ export type ComponentContext<S extends object, C extends object, P extends objec
 } & {
     [key: string]: unknown;
 };
+/**
+ * Controls when (and whether) a server-rendered custom element is hydrated
+ * on the client after the JavaScript bundle loads.
+ *
+ * | Value     | Behaviour |
+ * |-----------|-----------|
+ * | `'load'`  | Hydrate immediately when the element connects (default). |
+ * | `'idle'`  | Defer until `requestIdleCallback` fires. |
+ * | `'visible'` | Defer until the element enters the viewport (`IntersectionObserver`). |
+ * | `'none'`  | Never hydrate — element stays as static server-rendered HTML. |
+ */
+export type HydrateStrategy = 'load' | 'idle' | 'visible' | 'none';
 export type ComponentConfig<S extends object, C extends object = object, P extends object = object, T extends object = object> = {
     props?: Record<string, {
         type: StringConstructor | NumberConstructor | BooleanConstructor | FunctionConstructor;
         default?: string | number | boolean;
     }>;
+    /**
+     * Partial-hydration strategy for this component when SSR DSD output is used.
+     * Emitted as `data-cer-hydrate` on the host element in DSD HTML.
+     * @default 'load'
+     */
+    hydrate?: HydrateStrategy;
     render: (context: ComponentContext<S, C, P, T>) => VNode | VNode[] | Promise<VNode | VNode[]>;
     onConnected?: (context: ComponentContext<S, C, P, T>) => void;
     onDisconnected?: (context: ComponentContext<S, C, P, T>) => void;

package/dist/runtime/vdom-ssr-dsd.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Declarative Shadow DOM (DSD) SSR renderer.
+ *
+ * When `dsd: true` is passed to the render options, registered custom elements
+ * are serialised as:
+ *
+ * ```html
+ * <my-element attr="val">
+ *   <template shadowrootmode="open">
+ *     <style>
+ *       /* baseReset + useStyle() output + JIT utility CSS *\/
+ *     </style>
+ *     <!-- shadow DOM from component render function -->
+ *   </template>
+ *   <!-- light DOM / slotted children from vnode.children -->
+ * </my-element>
+ * ```
+ *
+ * The browser parses the `<template shadowrootmode="open">` block and attaches
+ * a real shadow root before any JavaScript executes. All CSS layers are present
+ * at first paint — eliminating both FOUC and layout shift.
+ *
+ * Non-custom-element VNodes are rendered identically to renderToString() but
+ * with DSD recursion active for any custom elements nested inside them.
+ */
+import type { VNode } from './types';
+import { type RenderOptions } from './ssr-utils';
+export type DSDRenderOptions = RenderOptions & {
+    /**
+     * Emit Declarative Shadow DOM output for registered custom elements.
+     * Shadow content is serialised inside `<template shadowrootmode="open">`,
+     * with a complete CSS layer stack (`baseReset` + `useStyle` + JIT CSS)
+     * injected as a `<style>` block so styles are available at first paint.
+     * @default false
+     */
+    dsd?: boolean;
+    /**
+     * Append the DSD polyfill `<script>` for browsers without native support
+     * (Firefox < 123). Only meaningful when `dsd` is true.
+     * @default true
+     */
+    dsdPolyfill?: boolean;
+};
+/**
+ * @internal
+ * Minified DSD polyfill for browsers without native Declarative Shadow DOM.
+ * Processes all `<template shadowrootmode>` elements synchronously.
+ */
+export declare const DSD_POLYFILL_SCRIPT: string;
+/**
+ * Build the combined `<style>` block for a shadow root.
+ *
+ * Layer order (matches the runtime adoptedStyleSheets order):
+ *   1. baseReset — global reset + CSS custom properties
+ *   2. useStyle() output — component-defined rules (:host, ::slotted, etc.)
+ *   3. JIT CSS — utility classes extracted from the shadow HTML
+ */
+export declare function buildShadowStyleBlock(useStyleCSS: string, shadowHTML: string): string;
+export interface AsyncStreamEntry {
+    id: string;
+    tag: string;
+    attrsString: string;
+    hydrateAttr: string;
+    useStyleCSS: string;
+    lightDOM: string;
+    opts: DSDRenderOptions;
+    promise: Promise<VNode | VNode[]>;
+}
+/** @internal Called by renderToStream() before the sync render pass. */
+export declare function beginStreamingCollection(collector: AsyncStreamEntry[]): void;
+/** @internal Called by renderToStream() after the sync render pass. */
+export declare function endStreamingCollection(): void;
+/**
+ * Render a VNode tree to an HTML string with Declarative Shadow DOM output
+ * for all registered custom elements encountered in the tree.
+ */
+export declare function renderToDSD(vnode: VNode, opts: DSDRenderOptions): string;
+/**
+ * Render a VNode tree to a DSD HTML string and optionally append the
+ * DSD polyfill script for older browsers.
+ */
+export declare function renderToStringDSD(vnode: VNode, opts?: DSDRenderOptions): string;

package/dist/runtime/vdom-ssr.d.ts

@@ -1,4 +1,5 @@
 import type { VNode } from './types';
+import { type RenderOptions } from './ssr-utils';
 /**
  * Render a VNode to a string (SSR).
  * Kept intentionally minimal: only serializes attributes under `props.attrs`
@@ -6,10 +7,5 @@ import type { VNode } from './types';
  * @param vnode The virtual node to render.
  * @returns The rendered HTML string.
  */
-export type RenderOptions = {
-    /** Backwards-compatible: whether to inject the SVG namespace on <svg> nodes (default true) */
-    injectSvgNamespace?: boolean;
-    /** Inject known well-known namespaces for tags like <math> when missing (default follows injectSvgNamespace) */
-    injectKnownNamespaces?: boolean;
-};
+export type { RenderOptions } from './ssr-utils';
 export declare function renderToString(vnode: VNode, opts?: RenderOptions): string;

package/dist/ssr-middleware.d.ts

@@ -0,0 +1,125 @@
+/**
+ * SSR middleware helpers for Express, Fastify, Hono, and other Node.js HTTP frameworks.
+ *
+ * Provides two handler factories that wrap the SSR rendering pipeline and
+ * emit a complete HTML document response. Both accept a static VNode **or**
+ * a per-request factory function so route-specific data can be threaded into
+ * the render tree.
+ *
+ * @example Express — static VNode
+ * ```ts
+ * import express from 'express';
+ * import { createSSRHandler } from '@jasonshimmy/custom-elements-runtime/ssr-middleware';
+ * import { html } from '@jasonshimmy/custom-elements-runtime';
+ *
+ * const app = express();
+ * app.get('/', createSSRHandler(html`<my-app />`, {
+ *   render: { dsd: true, jit: { extendedColors: true } },
+ * }));
+ * ```
+ *
+ * @example Express — per-request factory
+ * ```ts
+ * app.get('*', createSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ *   { render: { dsd: true }, head: '<link rel="stylesheet" href="/app.css">' },
+ * ));
+ * ```
+ *
+ * @example Streaming variant
+ * ```ts
+ * app.get('*', createStreamingSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ * ));
+ * ```
+ */
+import type { VNode } from './runtime/types';
+import type { RenderOptions } from './runtime/vdom-ssr';
+import type { DSDRenderOptions } from './runtime/vdom-ssr-dsd';
+import type { JITCSSOptions } from './runtime/style';
+/**
+ * Minimal request interface compatible with Express, Fastify, Hono, and the
+ * raw Node.js `IncomingMessage`. Extend or replace with your framework's
+ * request type via the generic parameter on `createSSRHandler`.
+ */
+export interface MinimalRequest {
+    url?: string;
+    method?: string;
+    headers?: Record<string, string | string[] | undefined>;
+}
+/**
+ * Minimal response interface compatible with Express, Fastify, Hono, and the
+ * raw Node.js `ServerResponse`. `write` is optional — handlers fall back to
+ * buffering when it is absent.
+ */
+export interface MinimalResponse {
+    setHeader(name: string, value: string): void;
+    write?(chunk: string): boolean | void;
+    end(data?: string): void;
+}
+/**
+ * Options for {@link createSSRHandler} and {@link createStreamingSSRHandler}.
+ */
+export interface SSRMiddlewareOptions {
+    /**
+     * Render options forwarded to `renderToStringWithJITCSS`.
+     * Defaults to `{ dsd: true }` so DSD output is on by default.
+     */
+    render?: RenderOptions & DSDRenderOptions & {
+        jit?: JITCSSOptions;
+    };
+    /**
+     * Additional HTML inserted at the end of the `<head>` tag.
+     * Use this to inject `<link>`, `<script>`, `<meta>`, or `<title>` tags.
+     */
+    head?: string;
+    /**
+     * When `true` (default), the response is wrapped in a complete
+     * `<!DOCTYPE html>` document shell. Set to `false` if you want to
+     * assemble the document yourself and only need the rendered fragment.
+     */
+    document?: boolean;
+}
+/**
+ * Create a request handler that SSR-renders a VNode tree and sends the full
+ * HTML document as the response.
+ *
+ * Compatible with Express, Fastify, Hono, and any framework that uses an
+ * `(req, res)` handler signature. The generic `Req` parameter lets you use
+ * your framework's typed request object.
+ *
+ * @param vnodeOrFactory - A static {@link VNode} **or** a (possibly async)
+ *   factory function that receives the request and returns the VNode to render.
+ * @param options - Render and document-shell options.
+ *
+ * @example
+ * ```ts
+ * app.get('*', createSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ *   { render: { dsd: true, jit: { extendedColors: true } } },
+ * ));
+ * ```
+ */
+export declare function createSSRHandler<Req extends MinimalRequest = MinimalRequest>(vnodeOrFactory: VNode | ((req: Req) => VNode | Promise<VNode>), options?: SSRMiddlewareOptions): (req: Req, res: MinimalResponse) => Promise<void>;
+/**
+ * Create a request handler that SSR-renders a VNode tree and streams the HTML
+ * response using chunked transfer encoding.
+ *
+ * Each chunk produced by the underlying {@link renderToStream} call is written
+ * to the response as it becomes available, minimising Time-to-First-Byte.
+ * The document shell preamble (`<!DOCTYPE html>…<body>`) is sent in the first
+ * write so the browser can begin parsing immediately.
+ *
+ * @param vnodeOrFactory - A static {@link VNode} **or** a (possibly async)
+ *   factory function that receives the request and returns the VNode to render.
+ * @param options - Render and document-shell options.
+ *
+ * @example
+ * ```ts
+ * app.get('*', createStreamingSSRHandler(
+ *   (req) => html`<my-app url="${req.url}" />`,
+ *   { render: { dsd: true } },
+ * ));
+ * ```
+ */
+export declare function createStreamingSSRHandler<Req extends MinimalRequest = MinimalRequest>(vnodeOrFactory: VNode | ((req: Req) => VNode | Promise<VNode>), options?: SSRMiddlewareOptions): (req: Req, res: MinimalResponse) => Promise<void>;

package/dist/ssr.d.ts

@@ -1,70 +1,132 @@
 /**
- * SSR entrypoint — small re-export so consumers can import SSR-only helpers
- * without pulling them into the main client runtime bundle.
+ * SSR entry point — import from `@jasonshimmy/custom-elements-runtime/ssr`.
  *
- * renderToString accepts an optional second argument to control SSR behavior:
+ * Provides four rendering modes:
  *
- *   renderToString(vnode, { injectSvgNamespace?: boolean })
+ * 1. **renderToString** — baseline HTML serialisation (no shadow DOM content).
+ *    Backwards-compatible with the original API.
  *
- * - injectSvgNamespace (default: true): when true, the SSR renderer will
- *   inject the standard SVG namespace attribute (xmlns="http://www.w3.org/2000/svg")
- *   onto `<svg>` elements that do not already provide an explicit `xmlns`.
- *   This matches the client runtime behavior (createElementNS) and avoids
- *   hydration/namespace mismatches. Set to `false` to opt out and keep SSR
- *   output minimal.
+ * 2. **renderToStringWithJITCSS** — HTML + pre-generated JIT CSS injected into
+ *    `<head>` to prevent FOUC. Supports `dsd: true` for DSD output.
  *
- * Examples
+ * 3. **renderToStringWithJITCSSDSD** — convenience alias for DSD mode.
+ *    Full Declarative Shadow DOM output with per-shadow-root CSS layer stack
+ *    (baseReset + useStyle() + JIT CSS). Enables true hydration, zero FOUC.
  *
- *   // Default (injects xmlns for <svg> if missing)
- *   import { renderToString } from '@jasonshimmy/custom-elements-runtime/ssr';
- *   const html = renderToString(vnodeTree);
+ * 4. **renderToStream** — ReadableStream variant for streaming SSR.
  *
- *   // Opt-out
- *   const htmlNoNs = renderToString(vnodeTree, { injectSvgNamespace: false });
+ * Entity map utilities are also exported for full HTML5 named-entity support.
+ *
+ * @example DSD usage (recommended)
+ * ```ts
+ * import { renderToStringWithJITCSSDSD } from '@jasonshimmy/custom-elements-runtime/ssr';
+ *
+ * const { htmlWithStyles } = renderToStringWithJITCSSDSD(appVNode, {
+ *   jit: { extendedColors: true },
+ * });
+ * res.send(`<!DOCTYPE html><html><head>${head}</head><body>${htmlWithStyles}</body></html>`);
+ * ```
  */
 export { renderToString } from './runtime/vdom-ssr';
 export type { VNode } from './runtime/types';
 export type { RenderOptions } from './runtime/vdom-ssr';
 export { registerEntityMap, loadEntityMap, clearRegisteredEntityMap, } from './runtime/helpers';
+export { renderToStringDSD, DSD_POLYFILL_SCRIPT, } from './runtime/vdom-ssr-dsd';
+export type { DSDRenderOptions } from './runtime/vdom-ssr-dsd';
 import { type JITCSSOptions } from './runtime/style';
 import type { VNode } from './runtime/types';
 import type { RenderOptions } from './runtime/vdom-ssr';
+import type { DSDRenderOptions } from './runtime/vdom-ssr-dsd';
 /**
- * Result of `renderToStringWithJITCSS()`.
+ * Result of `renderToStringWithJITCSS()` and `renderToStringWithJITCSSDSD()`.
  */
 export interface SSRJITResult {
-    /** The rendered HTML string. */
+    /** The rendered HTML string (styles not yet injected). */
     html: string;
     /**
-     * Pre-generated JIT CSS extracted from the rendered HTML.
-     * Embed this in a `<style>` element in your document `<head>` to eliminate
-     * Flash of Unstyled Content (FOUC) on hydration.
+     * Global JIT CSS extracted from the rendered HTML.
+     * For DSD renders, each shadow root embeds its own scoped styles; this field
+     * holds any residual light-DOM utility CSS.
      */
     css: string;
     /**
-     * Convenience: the HTML with a `<style>` element injected before `</head>`.
-     * If no `</head>` tag is found, the `<style>` is prepended to the HTML.
+     * CSS captured from `useGlobalStyle()` calls during this render pass
+     * (e.g. `@font-face`, `:root` custom properties).
+     * Inject in a `<style id="cer-ssr-global">` in `<head>`.
+     */
+    globalStyles: string;
+    /**
+     * Convenience: `html` with both `<style>` tags injected before `</head>`.
+     * If no `</head>` is found, the styles are prepended.
      */
     htmlWithStyles: string;
 }
 /**
- * Server-side render a VNode tree and simultaneously pre-generate JIT CSS for
- * all utility classes present in the rendered output.
+ * Server-side render a VNode tree and simultaneously pre-generate JIT CSS.
  *
- * Embed the returned `css` in a `<style>` element in your document `<head>`
- * to ensure correct styles are present before the client runtime hydrates,
- * eliminating Flash of Unstyled Content (FOUC).
+ * Pass `dsd: true` to enable Declarative Shadow DOM output with full per-shadow-
+ * root CSS layer extraction (recommended for new apps).
  *
- * @example
+ * @example Standard (no DSD)
  * ```ts
- * import { renderToStringWithJITCSS } from '@jasonshimmy/custom-elements-runtime/ssr';
+ * const { htmlWithStyles } = renderToStringWithJITCSS(appVNode);
+ * ```
  *
- * const { htmlWithStyles } = await renderToStringWithJITCSS(appVNode, {
+ * @example With DSD
+ * ```ts
+ * const { htmlWithStyles } = renderToStringWithJITCSS(appVNode, {
+ *   dsd: true,
  *   jit: { extendedColors: true },
  * });
- * res.send(`<!DOCTYPE html><html><head>${headTags}</head><body>${htmlWithStyles}</body></html>`);
  * ```
  */
-export declare function renderToStringWithJITCSS(vnode: VNode, options?: RenderOptions & {
+export declare function renderToStringWithJITCSS(vnode: VNode, options?: RenderOptions & DSDRenderOptions & {
     jit?: JITCSSOptions;
 }): SSRJITResult;
+/**
+ * Convenience alias: `renderToStringWithJITCSS(vnode, { dsd: true, ...options })`.
+ *
+ * Renders with Declarative Shadow DOM output, full per-shadow-root CSS layer
+ * extraction, and the DSD browser polyfill. This is the recommended function
+ * for all new server-rendered applications.
+ *
+ * @example
+ * ```ts
+ * import { renderToStringWithJITCSSDSD } from '@jasonshimmy/custom-elements-runtime/ssr';
+ *
+ * const { htmlWithStyles } = renderToStringWithJITCSSDSD(appVNode, {
+ *   jit: { extendedColors: true },
+ * });
+ * ```
+ */
+export declare function renderToStringWithJITCSSDSD(vnode: VNode, options?: Omit<RenderOptions & DSDRenderOptions & {
+    jit?: JITCSSOptions;
+}, 'dsd'>): SSRJITResult;
+/**
+ * Render a VNode tree to a `ReadableStream<string>`.
+ *
+ * The current implementation flushes the complete rendered output as a single
+ * chunk, providing the streaming API surface for framework adapters. True
+ * incremental streaming (flush shell immediately, resolve async components
+ * progressively) is planned for a future release.
+ *
+ * @example Node.js
+ * ```ts
+ * import { renderToStream } from '@jasonshimmy/custom-elements-runtime/ssr';
+ *
+ * app.get('/', (req, res) => {
+ *   const stream = renderToStream(appVNode, { dsd: true });
+ *   const reader = stream.getReader();
+ *   const pump = () =>
+ *     reader.read().then(({ value, done }) => {
+ *       if (done) { res.end(); return; }
+ *       res.write(value);
+ *       pump();
+ *     });
+ *   pump();
+ * });
+ * ```
+ */
+export declare function renderToStream(vnode: VNode, options?: RenderOptions & DSDRenderOptions & {
+    jit?: JITCSSOptions;
+}): ReadableStream<string>;