@solidjs/web 2.0.0-beta.17 → 2.0.0-beta.18

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@solidjs/web",
   "description": "Solid's web runtime: client rendering, hydration, SSR, and DOM-specific control flow (Portal, Dynamic).",
-  "version": "2.0.0-beta.17",
+  "version": "2.0.0-beta.18",
   "author": "Ryan Carniato",
   "license": "MIT",
   "homepage": "https://solidjs.com",
@@ -27,7 +27,11 @@
     "storage/dist",
     "storage/types",
     "storage/types-cjs",
-    "storage/package.json"
+    "storage/package.json",
+    "serialization/dist",
+    "serialization/types",
+    "serialization/types-cjs",
+    "serialization/package.json"
   ],
   "exports": {
     ".": {
@@ -130,30 +134,41 @@
         "default": "./storage/dist/storage.cjs"
       }
     },
+    "./serialization": {
+      "import": {
+        "types": "./serialization/types/index.d.ts",
+        "default": "./serialization/dist/serialization.js"
+      },
+      "require": {
+        "types": "./serialization/types-cjs/index.d.cts",
+        "default": "./serialization/dist/serialization.cjs"
+      }
+    },
     "./types/*": "./types/*"
   },
   "dependencies": {
-    "seroval": "^1.1.0",
-    "seroval-plugins": "^1.1.0"
+    "seroval": "~1.5.4",
+    "seroval-plugins": "~1.5.4"
   },
   "peerDependencies": {
-    "solid-js": "^2.0.0-beta.17"
+    "solid-js": "^2.0.0-beta.18"
   },
   "devDependencies": {
-    "solid-js": "2.0.0-beta.17"
+    "solid-js": "2.0.0-beta.18"
   },
   "scripts": {
     "build": "npm-run-all -nl build:clean types:copy-jsx build:js",
     "build:clean": "rimraf dist/",
     "build:js": "rollup -c",
     "link": "symlink-dir . node_modules/@solidjs/web",
-    "types": "npm-run-all -nl types:clean types:copy-jsx types:web types:copy-web types:web-storage types:cjs",
-    "types:clean": "rimraf types/ types-cjs/ storage/types-cjs/",
+    "types": "npm-run-all -nl types:clean types:copy-jsx types:web types:copy-web types:web-storage types:copy-serialization types:cjs",
+    "types:clean": "rimraf types/ types-cjs/ storage/types/ storage/types-cjs/ serialization/types/ serialization/types-cjs/",
     "types:copy-jsx": "ncp ../../node_modules/@dom-expressions/runtime/src/jsx.d.ts ./src/jsx.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/jsx-properties.d.ts ./src/jsx-properties.d.ts && dom-expressions-jsx-types --input ./src/jsx.d.ts --element \"SolidElement | Node | ArrayElement\" --import 'import type { Element as SolidElement } from \"solid-js\";'",
     "types:web": "tsc --project ./tsconfig.build.json",
-    "types:copy-web": "ncp ../../node_modules/@dom-expressions/runtime/src/client.d.ts ./types/client.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/server.d.ts ./types/server.d.ts && ncp ./src/jsx.d.ts ./types/jsx.d.ts && ncp ./src/jsx-properties.d.ts ./types/jsx-properties.d.ts",
+    "types:copy-web": "ncp ../../node_modules/@dom-expressions/runtime/src/client.d.ts ./types/client.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/server.d.ts ./types/server.d.ts && ncp ../../node_modules/@dom-expressions/runtime/src/serializer.d.ts ./types/serializer.d.ts && ncp ./src/jsx.d.ts ./types/jsx.d.ts && ncp ./src/jsx-properties.d.ts ./types/jsx-properties.d.ts",
     "types:web-storage": "tsc --project ./storage/tsconfig.build.json",
-    "types:cjs": "node ../../scripts/sync-dual-types.mjs ./types ./types-cjs ./storage/types ./storage/types-cjs",
+    "types:copy-serialization": "node -e \"fs.mkdirSync('./serialization/types', { recursive: true }); fs.copyFileSync('../../node_modules/@dom-expressions/runtime/src/serializer.d.ts', './serialization/types/index.d.ts');\"",
+    "types:cjs": "node ../../scripts/sync-dual-types.mjs ./types ./types-cjs ./storage/types ./storage/types-cjs ./serialization/types ./serialization/types-cjs",
     "test": "vitest run && vitest run --config vite.config.server.mjs && vitest run --config vite.config.hydrate.mjs",
     "test:server": "vitest run --config vite.config.server.mjs",
     "coverage": "vitest run --coverage",

package/serialization/dist/serialization.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+var seroval = require('seroval');
+var web = require('seroval-plugins/web');
+
+const DEFAULT_DISABLED_FEATURES = seroval.Feature.AggregateError | seroval.Feature.BigIntTypedArray;
+const HYDRATION_GLOBAL = "_$HY.r";
+const DEFAULT_WEB_PLUGINS = Object.freeze([web.AbortSignalPlugin,
+web.CustomEventPlugin, web.DOMExceptionPlugin, web.EventPlugin,
+web.FormDataPlugin, web.HeadersPlugin, web.ReadableStreamPlugin, web.RequestPlugin, web.ResponsePlugin, web.URLSearchParamsPlugin, web.URLPlugin]);
+function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
+function createSerializer(options) {
+  return new seroval.Serializer({
+    ...options,
+    plugins: resolveSerializerPlugins(options.plugins),
+    disabledFeatures: options.disabledFeatures === undefined ? DEFAULT_DISABLED_FEATURES : options.disabledFeatures
+  });
+}
+function createHydrationSerializer({
+  onData,
+  onDone,
+  scopeId,
+  onError,
+  plugins
+}) {
+  return createSerializer({
+    scopeId,
+    plugins,
+    globalIdentifier: HYDRATION_GLOBAL,
+    onData,
+    onDone,
+    onError
+  });
+}
+function getLocalHeaderScript(id) {
+  return seroval.getCrossReferenceHeader(id) + ";";
+}
+const JSON_CODEC_DISABLED_FEATURES = seroval.Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+function resolveCodecOptions({
+  plugins,
+  disabledFeatures,
+  depthLimit
+} = {}) {
+  return {
+    plugins: resolveSerializerPlugins(plugins),
+    disabledFeatures: disabledFeatures === undefined ? JSON_CODEC_DISABLED_FEATURES : disabledFeatures,
+    depthLimit: depthLimit === undefined ? JSON_CODEC_DEPTH_LIMIT : depthLimit
+  };
+}
+function serializeJSON(value, {
+  onParse,
+  onDone,
+  onError,
+  ...codecOptions
+}) {
+  return seroval.toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolveCodecOptions(codecOptions)
+  });
+}
+function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return seroval.fromCrossJSON(node, {
+      refs,
+      ...resolved
+    });
+  };
+}
+
+exports.DEFAULT_WEB_PLUGINS = DEFAULT_WEB_PLUGINS;
+exports.createHydrationSerializer = createHydrationSerializer;
+exports.createJSONDeserializer = createJSONDeserializer;
+exports.createSerializer = createSerializer;
+exports.getLocalHeaderScript = getLocalHeaderScript;
+exports.resolveSerializerPlugins = resolveSerializerPlugins;
+exports.serializeJSON = serializeJSON;

package/serialization/dist/serialization.js

@@ -0,0 +1,75 @@
+import { Feature, Serializer, getCrossReferenceHeader, toCrossJSONStream, fromCrossJSON } from 'seroval';
+import { AbortSignalPlugin, CustomEventPlugin, DOMExceptionPlugin, EventPlugin, FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin } from 'seroval-plugins/web';
+
+const DEFAULT_DISABLED_FEATURES = Feature.AggregateError | Feature.BigIntTypedArray;
+const HYDRATION_GLOBAL = "_$HY.r";
+const DEFAULT_WEB_PLUGINS = Object.freeze([AbortSignalPlugin,
+CustomEventPlugin, DOMExceptionPlugin, EventPlugin,
+FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin]);
+function resolveSerializerPlugins(customPlugins) {
+  return customPlugins ? [...customPlugins, ...DEFAULT_WEB_PLUGINS] : [...DEFAULT_WEB_PLUGINS];
+}
+function createSerializer(options) {
+  return new Serializer({
+    ...options,
+    plugins: resolveSerializerPlugins(options.plugins),
+    disabledFeatures: options.disabledFeatures === undefined ? DEFAULT_DISABLED_FEATURES : options.disabledFeatures
+  });
+}
+function createHydrationSerializer({
+  onData,
+  onDone,
+  scopeId,
+  onError,
+  plugins
+}) {
+  return createSerializer({
+    scopeId,
+    plugins,
+    globalIdentifier: HYDRATION_GLOBAL,
+    onData,
+    onDone,
+    onError
+  });
+}
+function getLocalHeaderScript(id) {
+  return getCrossReferenceHeader(id) + ";";
+}
+const JSON_CODEC_DISABLED_FEATURES = Feature.RegExp;
+const JSON_CODEC_DEPTH_LIMIT = 64;
+function resolveCodecOptions({
+  plugins,
+  disabledFeatures,
+  depthLimit
+} = {}) {
+  return {
+    plugins: resolveSerializerPlugins(plugins),
+    disabledFeatures: disabledFeatures === undefined ? JSON_CODEC_DISABLED_FEATURES : disabledFeatures,
+    depthLimit: depthLimit === undefined ? JSON_CODEC_DEPTH_LIMIT : depthLimit
+  };
+}
+function serializeJSON(value, {
+  onParse,
+  onDone,
+  onError,
+  ...codecOptions
+}) {
+  return toCrossJSONStream(value, {
+    onParse,
+    onDone,
+    onError,
+    ...resolveCodecOptions(codecOptions)
+  });
+}
+function createJSONDeserializer(options) {
+  const refs = new Map();
+  const resolved = resolveCodecOptions(options);
+  return function deserializeJSONChunk(node) {
+    return fromCrossJSON(node, {
+      refs,
+      ...resolved
+    });
+  };
+}
+
+export { DEFAULT_WEB_PLUGINS, createHydrationSerializer, createJSONDeserializer, createSerializer, getLocalHeaderScript, resolveSerializerPlugins, serializeJSON };

package/serialization/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@solidjs/web/serialization",
+  "main": "./dist/serialization.cjs",
+  "module": "./dist/serialization.js",
+  "types": "./types/index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./types/index.d.ts",
+        "default": "./dist/serialization.js"
+      },
+      "require": {
+        "types": "./types-cjs/index.d.cts",
+        "default": "./dist/serialization.cjs"
+      }
+    }
+  }
+}

package/serialization/types/index.d.ts

@@ -0,0 +1,97 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+export type { SerovalNode };
+
+/** A Seroval plugin usable with the web serializers. */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays).
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
+ * and feature policy — only the wiring options (callbacks, scope, extra
+ * plugins) are configurable.
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/** Returns the cross-reference bootstrap script for a render scope. */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse`.
+ * Wire framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;

package/serialization/types-cjs/index.d.cts

@@ -0,0 +1,97 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+export type { SerovalNode };
+
+/** A Seroval plugin usable with the web serializers. */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays).
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
+ * and feature policy — only the wiring options (callbacks, scope, extra
+ * plugins) are configurable.
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/** Returns the cross-reference bootstrap script for a render scope. */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse`.
+ * Wire framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;

package/serialization/types-cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}

package/types/index.d.ts

@@ -118,6 +118,12 @@ export declare const hydrate: typeof hydrateCore;
  * still participates in the parent's reactive scope and disposes when the
  * parent does.
  *
+ * Portals are client-only islands: the server renders nothing for them, and
+ * under hydration the children render fresh once hydration settles. Async
+ * read inside a portal therefore starts on the client — data that should be
+ * fetched on the server belongs above the portal (hoist the read, not the
+ * render), and async UI inside one wants its own `<Loading>` boundary.
+ *
  * @example
  * ```tsx
  * <Portal mount={document.getElementById("modal-root")!}>
@@ -127,7 +133,7 @@ export declare const hydrate: typeof hydrateCore;
  *
  * @description https://docs.solidjs.com/reference/components/portal
  */
-export declare function Portal<T extends boolean = false, S extends boolean = false>(props: {
+export declare function Portal(props: {
     mount?: Element;
     children: JSX.Element;
 }): JSX.Element;

package/types/serializer.d.ts

@@ -0,0 +1,97 @@
+import { Plugin, Serializer, SerovalNode } from "seroval";
+
+export type { SerovalNode };
+
+/** A Seroval plugin usable with the web serializers. */
+export type SerializerPlugin = Plugin<any, any>;
+
+/**
+ * Baseline plugin set for serializing web-platform values (AbortSignal,
+ * Event, FormData, Headers, ReadableStream, Request, Response, URL, ...).
+ */
+export const DEFAULT_WEB_PLUGINS: readonly SerializerPlugin[];
+
+/**
+ * Composes custom plugins with `DEFAULT_WEB_PLUGINS`. Custom plugins come
+ * first so they can shadow a default for values both would match. Returns a
+ * fresh array; the defaults are never mutated.
+ */
+export function resolveSerializerPlugins(customPlugins?: SerializerPlugin[]): SerializerPlugin[];
+
+export interface WebSerializerOptions {
+  /** Name of the global object the emitted scripts write resolved values into. */
+  globalIdentifier: string;
+  scopeId?: string;
+  /**
+   * Seroval feature bitflags to exclude from output. Defaults to disabling
+   * post-ES2017 features (AggregateError, BigInt typed arrays).
+   */
+  disabledFeatures?: number;
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. */
+  plugins?: SerializerPlugin[];
+  onData: (result: string) => void;
+  onError?: (error: unknown) => void;
+  onDone?: () => void;
+}
+
+/**
+ * Creates a streaming Seroval serializer preconfigured with the web plugin
+ * set and the default feature policy.
+ */
+export function createSerializer(options: WebSerializerOptions): Serializer;
+
+export type HydrationSerializerOptions = Omit<
+  WebSerializerOptions,
+  "globalIdentifier" | "disabledFeatures"
+>;
+
+/**
+ * Serializer for SSR hydration output. Pins the hydration global (`_$HY.r`)
+ * and feature policy — only the wiring options (callbacks, scope, extra
+ * plugins) are configurable.
+ */
+export function createHydrationSerializer(options: HydrationSerializerOptions): Serializer;
+
+/** Returns the cross-reference bootstrap script for a render scope. */
+export function getLocalHeaderScript(id?: string): string;
+
+// ---- JSON codec (server function transports) ----
+
+export interface JSONCodecOptions {
+  /** Extra plugins, composed ahead of `DEFAULT_WEB_PLUGINS`. Must match on both peers. */
+  plugins?: SerializerPlugin[];
+  /**
+   * Seroval feature bitflags to exclude. Defaults to disabling `RegExp`
+   * (payloads may come from an untrusted peer). Must match on both peers.
+   */
+  disabledFeatures?: number;
+  /** Maximum parse/deserialize depth. Defaults to 64. Must match on both peers. */
+  depthLimit?: number;
+}
+
+export interface JSONSerializeOptions extends JSONCodecOptions {
+  /**
+   * Receives each serialized node; `initial` is true for the first chunk
+   * (the source value itself). Async values produce additional chunks as
+   * they resolve.
+   */
+  onParse: (node: SerovalNode, initial: boolean) => void;
+  onError?: (error: unknown) => void;
+  /** Fires once all async values have settled. */
+  onDone?: () => void;
+}
+
+/**
+ * Serializes `value` as SerovalNode chunks delivered through `onParse`.
+ * Wire framing of the nodes is the transport's concern. Returns a cancel
+ * function that aborts pending async serialization.
+ */
+export function serializeJSON(value: unknown, options: JSONSerializeOptions): () => void;
+
+/**
+ * Creates the decoding counterpart of `serializeJSON`. Cross-references
+ * between chunks resolve through state shared across calls, so all chunks
+ * from one stream must go through the same deserializer instance. The first
+ * chunk's return value is the decoded source value.
+ */
+export function createJSONDeserializer(options?: JSONCodecOptions): <T>(node: SerovalNode) => T;

package/types/server.d.ts

@@ -1,4 +1,5 @@
 import { JSX } from "./jsx.js";
+import { SerializerPlugin } from "./serializer.js";
 export const DOMWithState: Record<string, Record<string, 1 | 2>>;
 export const ChildProperties: Set<string>;
 export const DelegatedEvents: Set<string>;
@@ -11,17 +12,59 @@ export const Namespaces: Record<string, string>;
 
 type MountableElement = Element | Document | ShadowRoot | DocumentFragment | Node;
 
+/** Static asset manifest produced by a build (e.g. parsed Vite manifest.json). */
+export type AssetManifest = Record<
+  string,
+  { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }
+> & { _base?: string };
+
+/** Inline style content, e.g. dev CSS collected from a bundler's module graph. */
+export type InlineStyleAsset = {
+  id: string;
+  content: string;
+  attrs?: Record<string, string>;
+};
+
+export type ResolvedAssets = {
+  js: string[];
+  css: (string | InlineStyleAsset)[];
+};
+
+/**
+ * Resolver form of the manifest option — the primitive a dev server
+ * implements against its live module graph (a static manifest object is
+ * normalized into a sync resolver internally). `resolve` may return a
+ * promise (async resolvers require streaming rendering); CSS entries may be
+ * URL strings (emitted as load-gated `<link>` tags) or inline-style
+ * descriptors (emitted as `<style>` tags). A bare `resolve`-shaped function
+ * is accepted as shorthand for `{ resolve }`.
+ */
+export type AssetResolver = {
+  resolve(
+    key: string
+  ): ResolvedAssets | null | undefined | Promise<ResolvedAssets | null | undefined>;
+  /**
+   * Synchronous fast path answering with whatever is knowable without async
+   * work (typically js URLs, omitting css). Sync consumers — e.g. a lazy
+   * component's `moduleUrl` getter used by islands — use this when `resolve`
+   * would return a promise, so adapters should provide it whenever possible.
+   */
+  resolveSync?(key: string): ResolvedAssets | null | undefined;
+};
+
+/** Bare-function shorthand for `AssetResolver` (no sync fast path). */
+export type AssetResolverFn = (
+  key: string
+) => ResolvedAssets | null | undefined | Promise<ResolvedAssets | null | undefined>;
+
 export function renderToString<T>(
   fn: () => T,
   options?: {
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<
-      string,
-      { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }
-    > & { _base?: string };
+    plugins?: SerializerPlugin[];
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
   }
 ): string;
@@ -33,11 +76,8 @@ export function renderToStringAsync<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<
-      string,
-      { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }
-    > & { _base?: string };
+    plugins?: SerializerPlugin[];
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onError?: (err: any) => void;
   }
 ): Promise<string>;
@@ -47,11 +87,8 @@ export function renderToStream<T>(
     nonce?: string;
     renderId?: string;
     noScripts?: boolean;
-    plugins?: any[];
-    manifest?: Record<
-      string,
-      { file: string; css?: string[]; isEntry?: boolean; imports?: string[] }
-    > & { _base?: string };
+    plugins?: SerializerPlugin[];
+    manifest?: AssetManifest | AssetResolver | AssetResolverFn;
     onCompleteShell?: (info: { write: (v: string) => void }) => void;
     onCompleteAll?: (info: { write: (v: string) => void }) => void;
     onError?: (err: any) => void;