@solidjs/web 2.0.0-beta.22 → 2.0.0-beta.23

package/server-functions/dist/client.js

@@ -1,4 +1,4 @@
-import { fromCrossJSON, Feature, toCrossJSONStream } from 'seroval';
+import { fromCrossJSON, Feature } from 'seroval';
 import { AbortSignalPlugin, CustomEventPlugin, DOMExceptionPlugin, EventPlugin, FormDataPlugin, HeadersPlugin, ReadableStreamPlugin, RequestPlugin, ResponsePlugin, URLSearchParamsPlugin, URLPlugin } from 'seroval-plugins/web';
 
 Feature.AggregateError | Feature.BigIntTypedArray;
@@ -21,19 +21,6 @@ function resolveCodecOptions({
     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);
@@ -51,9 +38,6 @@ const codecConfig = {
 function configureServerFunctionsCodec(codec) {
   codecConfig.codec = codec;
 }
-function getServerFunctionsCodec() {
-  return codecConfig.codec;
-}
 const flightConfig = {
   consumer: undefined
 };
@@ -120,7 +104,8 @@ const BodyFormat = {
   Blob: "4",
   File: "5",
   ArrayBuffer: "6",
-  Uint8Array: "7"
+  Uint8Array: "7",
+  Json: "8"
 };
 function getHeadersAndBody(body) {
   switch (true) {
@@ -190,6 +175,8 @@ async function extractBody(source, codecOptions) {
   switch (true) {
     case format === BodyFormat.Serialized:
       return await deserializeStream(clone, codecOptions);
+    case format === BodyFormat.Json:
+      return JSON.parse(await clone.text());
     case format === BodyFormat.String:
       return await clone.text();
     case format === BodyFormat.File:
@@ -212,17 +199,6 @@ async function extractBody(source, codecOptions) {
   }
   return undefined;
 }
-function createChunk(data) {
-  const encodeData = new TextEncoder().encode(data);
-  const bytes = encodeData.length;
-  const baseHex = bytes.toString(16);
-  const totalHex = "00000000".substring(0, 8 - baseHex.length) + baseHex;
-  const head = new TextEncoder().encode(`;0x${totalHex};`);
-  const chunk = new Uint8Array(12 + bytes);
-  chunk.set(head);
-  chunk.set(encodeData, 12);
-  return chunk;
-}
 class ChunkReader {
   constructor(stream) {
     this.reader = stream.getReader();
@@ -279,28 +255,6 @@ class ChunkReader {
     }
   }
 }
-function serializeStream(value, codecOptions) {
-  return new ReadableStream({
-    start(controller) {
-      serializeJSON(value, {
-        ...codecOptions,
-        onParse(node) {
-          controller.enqueue(createChunk(JSON.stringify(node)));
-        },
-        onDone() {
-          controller.close();
-        },
-        onError(error) {
-          controller.error(error);
-        }
-      });
-    }
-  });
-}
-async function serializeString(value, codecOptions) {
-  const response = new Response(serializeStream(value, codecOptions));
-  return await response.text();
-}
 async function deserializeStream(source, codecOptions) {
   if (!source.body) {
     throw new Error("missing body");
@@ -324,16 +278,43 @@ async function decodeResponse(response, codecOptions) {
 
 const config = {
   endpoint: "/_server",
-  prepareRequest: undefined
+  prepareRequest: undefined,
+  responseHandler: undefined,
+  serializeArgs: undefined
 };
+function isJSONSafe(value) {
+  if (value === null) return true;
+  const t = typeof value;
+  if (t === "string" || t === "boolean") return true;
+  if (t === "number") return Number.isFinite(value);
+  if (t !== "object") return false;
+  if (Array.isArray(value)) {
+    for (const v of value) if (!isJSONSafe(v)) return false;
+    return true;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  for (const k in value) if (!isJSONSafe(value[k])) return false;
+  return true;
+}
+function serializeArguments(args) {
+  if (!config.serializeArgs) {
+    throw new Error("Server function arguments are sent as JSON by default and these " + "arguments are not JSON-serializable. Call enableRichArguments() " + "(from the server-functions rich-args entry) once at startup to " + "send Dates, Maps, Sets, typed arrays, etc. through the codec — or " + "pass a single Blob/FormData/File argument, which has a native " + "HTTP encoding.");
+  }
+  return config.serializeArgs(args);
+}
 function configureServerFunctionsClient({
   endpoint,
   codec,
-  prepareRequest
+  prepareRequest,
+  responseHandler,
+  serializeArgs
 } = {}) {
   if (endpoint !== undefined) config.endpoint = endpoint;
   if (codec !== undefined) configureServerFunctionsCodec(codec);
   if (prepareRequest !== undefined) config.prepareRequest = prepareRequest;
+  if (responseHandler !== undefined) config.responseHandler = responseHandler;
+  if (serializeArgs !== undefined) config.serializeArgs = serializeArgs;
 }
 let INSTANCE = 0;
 async function createRequest(base, id, instance, options, meta) {
@@ -375,9 +356,20 @@ async function initializeResponse(base, id, instance, options, args, meta) {
       }, meta);
     }
   }
+  if (isJSONSafe(args)) {
+    return createRequest(base, id, instance, {
+      ...options,
+      body: JSON.stringify(args),
+      headers: {
+        ...options.headers,
+        "Content-Type": "application/json",
+        [BODY_FORMAT_HEADER]: BodyFormat.Json
+      }
+    }, meta);
+  }
   return createRequest(base, id, instance, {
     ...options,
-    body: await serializeString(args, getServerFunctionsCodec()),
+    body: await serializeArguments(args),
     headers: {
       ...options.headers,
       "Content-Type": "text/plain",
@@ -387,7 +379,21 @@ async function initializeResponse(base, id, instance, options, args, meta) {
 }
 async function fetchServerFunction(base, id, options, args, meta) {
   const instance = `server-function:${INSTANCE++}`;
+  const handler = config.responseHandler;
+  const context = handler && handler.capture ? handler.capture({
+    id,
+    meta
+  }) : undefined;
   const response = await initializeResponse(base, id, instance, options, args, meta);
+  if (handler) {
+    const handled = handler.handle(response, {
+      id,
+      meta,
+      args,
+      context
+    });
+    if (handled !== undefined) return handled;
+  }
   if (response.headers.has(SINGLE_FLIGHT_HEADER)) {
     const consumer = getFlightDataConsumer();
     if (consumer) {
@@ -414,7 +420,18 @@ function createServerReference(id, name, base) {
   const metadata = name === undefined ? {} : {
     name
   };
-  const fn = (...args) => fetchServerFunction(base || config.endpoint, id, {}, args, metadata);
+  const fn = (...args) => {
+    const handler = config.responseHandler;
+    if (handler && handler.intercept) {
+      const hit = handler.intercept({
+        id,
+        meta: metadata,
+        args
+      });
+      if (hit !== undefined) return hit;
+    }
+    return fetchServerFunction(base || config.endpoint, id, {}, args, metadata);
+  };
   fn[SERVER_FUNCTION_METADATA] = metadata;
   return new Proxy(fn, {
     get(target, prop) {
@@ -435,9 +452,19 @@ function GET(fn) {
     ...getServerFunctionMetadata(fn)
   };
   const wrapped = async (...args) => {
+    const handler = config.responseHandler;
+    if (handler && handler.intercept) {
+      const hit = handler.intercept({
+        id,
+        meta: metadata,
+        args
+      });
+      if (hit !== undefined) return hit;
+    }
     let base = `${config.endpoint}?id=${encodeURIComponent(id)}`;
     if (args.length) {
-      base += `&args=${encodeURIComponent(await serializeString(args, getServerFunctionsCodec()))}`;
+      const encoded = isJSONSafe(args) ? JSON.stringify(args) : await serializeArguments(args);
+      base += `&args=${encodeURIComponent(encoded)}`;
     }
     return fetchServerFunction(base, id, {
       method: "GET"

package/server-functions/dist/server.cjs

@@ -125,7 +125,8 @@ const BodyFormat = {
   Blob: "4",
   File: "5",
   ArrayBuffer: "6",
-  Uint8Array: "7"
+  Uint8Array: "7",
+  Json: "8"
 };
 function getHeadersAndBody(body) {
   switch (true) {
@@ -195,6 +196,8 @@ async function extractBody(source, codecOptions) {
   switch (true) {
     case format === BodyFormat.Serialized:
       return await deserializeStream(clone, codecOptions);
+    case format === BodyFormat.Json:
+      return JSON.parse(await clone.text());
     case format === BodyFormat.String:
       return await clone.text();
     case format === BodyFormat.File:
@@ -329,16 +332,19 @@ async function decodeResponse(response, codecOptions) {
 const config = {
   provideEvent: undefined,
   collectFlightData: undefined,
+  transformDirectResult: undefined,
   endpoint: "/_server"
 };
 function configureServerFunctionsServer({
   provideEvent,
   collectFlightData,
+  transformDirectResult,
   endpoint,
   codec
 } = {}) {
   if (provideEvent !== undefined) config.provideEvent = provideEvent;
   if (collectFlightData !== undefined) config.collectFlightData = collectFlightData;
+  if (transformDirectResult !== undefined) config.transformDirectResult = transformDirectResult;
   if (endpoint !== undefined) config.endpoint = endpoint;
   if (codec !== undefined) configureServerFunctionsCodec(codec);
 }
@@ -397,9 +403,20 @@ function createServerReference({
         id
       };
       evt.serverOnly = true;
-      return provideEvent(evt, () => {
+      const result = provideEvent(evt, () => {
         return fn.apply(thisArg, args);
       });
+      const transform = config.transformDirectResult;
+      if (transform && result && typeof result.then === "function") {
+        return result.then(value => transform(value, {
+          id,
+          event: evt
+        }));
+      }
+      return transform ? transform(result, {
+        id,
+        event: evt
+      }) : result;
     }
   });
 }
@@ -437,7 +454,7 @@ async function parseArguments(request, url, instance, codec) {
   }
   if (request.method === "POST" && request.body !== null) {
     const decoded = await extractBody(request.clone(), codec);
-    if (bodyFormat === BodyFormat.Serialized) {
+    if (bodyFormat === BodyFormat.Serialized || bodyFormat === BodyFormat.Json) {
       return decoded;
     }
     parsed.push(decoded);

package/server-functions/dist/server.js

@@ -123,7 +123,8 @@ const BodyFormat = {
   Blob: "4",
   File: "5",
   ArrayBuffer: "6",
-  Uint8Array: "7"
+  Uint8Array: "7",
+  Json: "8"
 };
 function getHeadersAndBody(body) {
   switch (true) {
@@ -193,6 +194,8 @@ async function extractBody(source, codecOptions) {
   switch (true) {
     case format === BodyFormat.Serialized:
       return await deserializeStream(clone, codecOptions);
+    case format === BodyFormat.Json:
+      return JSON.parse(await clone.text());
     case format === BodyFormat.String:
       return await clone.text();
     case format === BodyFormat.File:
@@ -327,16 +330,19 @@ async function decodeResponse(response, codecOptions) {
 const config = {
   provideEvent: undefined,
   collectFlightData: undefined,
+  transformDirectResult: undefined,
   endpoint: "/_server"
 };
 function configureServerFunctionsServer({
   provideEvent,
   collectFlightData,
+  transformDirectResult,
   endpoint,
   codec
 } = {}) {
   if (provideEvent !== undefined) config.provideEvent = provideEvent;
   if (collectFlightData !== undefined) config.collectFlightData = collectFlightData;
+  if (transformDirectResult !== undefined) config.transformDirectResult = transformDirectResult;
   if (endpoint !== undefined) config.endpoint = endpoint;
   if (codec !== undefined) configureServerFunctionsCodec(codec);
 }
@@ -395,9 +401,20 @@ function createServerReference({
         id
       };
       evt.serverOnly = true;
-      return provideEvent(evt, () => {
+      const result = provideEvent(evt, () => {
         return fn.apply(thisArg, args);
       });
+      const transform = config.transformDirectResult;
+      if (transform && result && typeof result.then === "function") {
+        return result.then(value => transform(value, {
+          id,
+          event: evt
+        }));
+      }
+      return transform ? transform(result, {
+        id,
+        event: evt
+      }) : result;
     }
   });
 }
@@ -435,7 +452,7 @@ async function parseArguments(request, url, instance, codec) {
   }
   if (request.method === "POST" && request.body !== null) {
     const decoded = await extractBody(request.clone(), codec);
-    if (bodyFormat === BodyFormat.Serialized) {
+    if (bodyFormat === BodyFormat.Serialized || bodyFormat === BodyFormat.Json) {
       return decoded;
     }
     parsed.push(decoded);

package/types/client.d.ts

@@ -84,6 +84,14 @@ export function registerElementClaim(handler: (element: Element) => void): () =>
  * Emitted by the compiler at element creation; idempotent by contract.
  */
 export function claimElement<T extends Element>(node: T): T;
+/**
+ * Sweep-claim every navigation-relevant element (`a[href]`, `form[action]`)
+ * in `root` — the subtree equivalent of the per-element `claimElement`
+ * compiled output emits, for content that becomes live DOM without compiled
+ * creation code (frame streams, adopted SSR ranges). Dormant without a
+ * registered consumer.
+ */
+export function claimElementTree<T extends Node>(root: T): T;
 export function className(node: Element, value: JSX.ClassValue, prev?: JSX.ClassValue): void;
 export function setProperty(node: Element, name: string, value: any): void;
 export function setStyleProperty(node: Element, name: string, value: any): void;

package/types/core.d.ts

@@ -1,3 +1,4 @@
-export { getOwner, runWithOwner, createComponent, createRoot as root, sharedConfig, untrack, merge as mergeProps, flatten, ssrHandleError, ssrScope } from "solid-js";
+export { getOwner, runWithOwner, createComponent, createRoot as root, sharedConfig, untrack, merge as mergeProps, flatten, ssrHandleError, ssrScope, NoHydration, Hydration } from "solid-js";
 export declare const effect: (fn: any, effectFn: any, options: any) => void;
 export declare const memo: (fn: any) => import("solid-js").SourceAccessor<any>;
+export declare const runWithHydrationScope: (id: any, fn: any) => unknown;

package/types/frames/client.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @solidjs/web/frames — client half. Consume frame streams into live DOM
+ * boundaries. There is deliberately no server-component API here beyond
+ * `installServerComponents()`: `dynamic` + server functions IS the client
+ * surface — a server-function call whose response is a frame stream
+ * resolves with a stable per-call-site component.
+ *
+ * Copied next to the runtime's frame d.ts files at publish (see
+ * types:copy-frames), so the relative imports below resolve in-place.
+ */
+export {
+  createFrame,
+  createFrameHost,
+  createFrameInsertable,
+  FRAME_APPLIED_EVENT
+} from "./frame-client.js";
+export type {
+  Frame,
+  FrameChunk,
+  FrameHost,
+  FrameHostOptions,
+  FrameOptions,
+  FrameWrite,
+  Slot,
+  SlotContext
+} from "./frame-client.js";
+export {
+  FRAME_STREAM_HEADER,
+  applyFrameResponse,
+  isFrameStreamResponse,
+  createServerComponentHandler
+} from "./frame-transport.js";
+export { createJSONDataTable } from "./serializer.js";
+export type { JSONDataTable } from "./serializer.js";
+
+import type { FrameHost } from "./frame-client.js";
+
+/**
+ * The app-wide frame host (created on first use): one chunk router, with
+ * codec data tables rotated per response — deserializer cross-reference
+ * space is stream-scoped by contract.
+ */
+export function getFrameHost(): FrameHost;
+
+/**
+ * Installs the server-component transport policy on the server-function
+ * client: boundary identity derives from the reactive owner captured at the
+ * call site, frame-stream responses resolve to stable per-call-site
+ * components, and document-SSR boundaries adopt their server-rendered
+ * ranges. Call once in the client entry (the package is sideEffects:false —
+ * a bare import would be tree-shaken); call again to rebind a custom host.
+ */
+export function installServerComponents(host?: FrameHost): void;

package/types/frames/frame-client.d.ts

@@ -0,0 +1,205 @@
+/**
+ * Client frame runtime — the consumer side of a frame stream. A frame
+ * renders server-owned content into a DOM boundary from a resident keyed
+ * record store: chunks are writes, not events, so application is
+ * prerequisite-driven and order-independent. Client-owned slot ranges
+ * inside the boundary are preserved across server updates — the
+ * version is a stale-guard only ("policy A"): newer content morphs in
+ * place, and teardown is `dispose()`, never a version bump.
+ */
+
+/** One transport chunk of a frame stream, addressed by frame `id`. */
+export type FrameChunk =
+  | { type: "start"; id: string; version: number }
+  | { type: "html"; id: string; version: number; html: string }
+  | { type: "fragment"; id: string; version: number; key: string; html: string }
+  | {
+      type: "reveal";
+      id: string;
+      version: number;
+      keys: string[];
+      waitForStyles?: boolean;
+      fallback?: boolean;
+    }
+  | {
+      type: "data";
+      id: string;
+      version: number;
+      key?: string;
+      node?: unknown;
+      initial?: boolean;
+      /** Eval-style hydration script — only when produced with the hydration serializer. */
+      payload?: string;
+    }
+  | {
+      type: "assets";
+      id: string;
+      version: number;
+      key: string;
+      modules?: string[];
+      styles?: string[];
+      inlineStyles?: { id: string; content?: string; attrs?: Record<string, string> }[];
+    }
+  | { type: "slot"; id: string; version: number; key: string; args: Record<string, unknown> }
+  | { type: "template"; id: string; version: number; key: string; html: string; fields: string[] }
+  | {
+      type: "block";
+      id: string;
+      version: number;
+      key: string;
+      template: string;
+      values: unknown[];
+    }
+  | { type: "complete"; id: string; version: number }
+  | { type: "error"; id: string; version: number; key?: string; error: unknown };
+
+/**
+ * Maps a wire chunk onto resident-store record writes. `data` chunks map to
+ * no records — they are response-scoped and the host applies them through
+ * its data hook.
+ */
+export function chunkToRecords(chunk: FrameChunk): Record<string, unknown>;
+
+/**
+ * One store write applied to a frame: `r` maps record keys to values
+ * (`chunkToRecords` produces these from wire chunks) and `version` is the
+ * stream stamp — an older version than the frame's current one is ignored.
+ */
+export interface FrameWrite {
+  version: number;
+  r: Record<string, unknown>;
+}
+
+/** Context passed to a slot callback. */
+export interface SlotContext {
+  /**
+   * Register cleanup for when this occurrence's range is removed from the
+   * server content, or the owning frame is disposed.
+   */
+  onCleanup(fn: () => void): void;
+  /**
+   * The range's current interior — server-rendered client content on an
+   * adopted document-SSR boot, or the previous output on a re-call. A
+   * framework binding hydrates onto it and returns `undefined` to claim it
+   * in place (zero DOM mutation).
+   */
+  existing: ChildNode[];
+}
+
+/**
+ * Client content for a server-declared slot. Direct-insert occurrences
+ * call it with empty props; render-prop occurrences pass the occurrence's
+ * resolved args (primitives literal, `{$ref}` data resolved through the
+ * host, `{$frame}` regions as marker-range fragments). Return nodes to fill
+ * the range, or `undefined` to claim `ctx.existing` untouched.
+ */
+export type Slot = (props: Record<string, unknown>, ctx: SlotContext) => Node | Node[] | undefined;
+
+export interface Frame {
+  /** Merge a write into the store and flush (morph/reveal/slot sync). */
+  apply(write: FrameWrite): void;
+  /** The active version, or undefined before the first apply. */
+  readonly version: number | undefined;
+  /** Read-only view of the resident record store. */
+  readonly store: Readonly<Record<string, unknown>>;
+  /** The stream's error record, if an `error` chunk arrived. */
+  readonly error: unknown;
+  /** Whether the named fragment has been revealed into the boundary. */
+  isRevealed(segment: string): boolean;
+  /** Tear down: slot cleanups cascade, later chunks are ignored. Idempotent. */
+  dispose(): void;
+}
+
+/**
+ * Routes a flat stream of addressed chunks to frames by id, buffering chunks
+ * for frames that have not registered yet (only the newest version's chunks
+ * are kept). `data` chunks are response-scoped and go to `applyData`.
+ *
+ * An id may have several frames (the same server component mounted more
+ * than once): chunks fan out to all of them, and a frame registering after
+ * delivery is seeded from a sibling's store.
+ */
+export interface FrameHost {
+  register(id: string, frame: Frame): void;
+  /** Remove one frame (or all frames of the id when `frame` is omitted). */
+  unregister(id: string, frame?: Frame): void;
+  apply(chunk: FrameChunk): void;
+  /** The first registered frame under the id, if any. */
+  get(id: string): Frame | undefined;
+  serialize(value: unknown): { $ref: string };
+  /** `frameId` is the resolving frame's id — route to its stream's table. */
+  resolve(ref: { $ref: string }, frameId?: string): unknown;
+}
+
+/**
+ * The bubbling DOM event (`"frame:applied"`) a frame dispatches from its
+ * parent element whenever server content lands in the document — root
+ * materialize/morph, segment reveal, fallback materialization — with
+ * `detail: { id, version, reason }`. One document-level listener sees every
+ * boundary (nested region frames dispatch too); use it to re-apply
+ * client-owned decorations on server-owned markup (router affordance
+ * reflection, e.g. `aria-current`) without a MutationObserver.
+ */
+export const FRAME_APPLIED_EVENT: "frame:applied";
+
+/** Options for `createFrameHost`. */
+export interface FrameHostOptions {
+  /**
+   * Backs `{$ref}` slot args (typically a codec data table's `resolve`).
+   * `frameId` identifies the resolving frame — data tables are
+   * response-scoped, so multi-stream hosts route by it (nested region ids
+   * prefix-match their root).
+   */
+  resolve?(ref: { $ref: string }, frameId?: string): unknown;
+  /** Test/host-side counterpart of `resolve`. */
+  serialize?(value: unknown): { $ref: string };
+  /**
+   * Receives each `data` chunk whole. Wire a codec table:
+   * `applyData: c => table.apply(c)` (see `createJSONDataTable`).
+   */
+  applyData?(chunk: Extract<FrameChunk, { type: "data" }>): void;
+}
+
+export function createFrameHost(options?: FrameHostOptions): FrameHost;
+
+/** Options for `createFrame` / `createFrameInsertable`. */
+export interface FrameOptions {
+  /** Register with this host under `id`, receiving routed/buffered chunks. */
+  host?: FrameHost;
+  id?: string;
+  /** Client content keyed by prop name (occurrences resolve by prop). */
+  slots?: Record<string, Slot>;
+  /**
+   * Adopt existing server-rendered DOM: the first apply morphs against it,
+   * and slots sync immediately (hydration attach) — a document-SSR boot
+   * needs no chunk.
+   */
+  adopt?: boolean;
+  /** Called after each apply flush (tests/telemetry). */
+  onApply?(info: { version: number; reason: "materialize" | "morph" | "reveal" }): void;
+  /**
+   * Wraps element-claim sweeps (`a[href]`/`form[action]` in materialized
+   * server content — and only those) so claim consumers register their
+   * per-element cleanup against the boundary's reactive owner, e.g.
+   * `fn => runWithOwner(owner, fn)`. Nested region frames inherit it.
+   * Without it, sweeps run under whatever owner is current (none, for
+   * streamed chunks).
+   */
+  ownerScope?<T>(fn: () => T): T;
+}
+
+/** A frame rendering into an element boundary. */
+export function createFrame(boundary: Element, options?: FrameOptions): Frame;
+
+/**
+ * A branded frame-insertable value: the client runtime's `insert` recognizes
+ * it (registered `$$FRAME` symbol) and calls the mount handler the value
+ * carries — a comment range is established at the insertion point and a
+ * host-registered frame binds to it. One static mount per value; lifecycle
+ * belongs to the creator via `dispose()` (register it with your owner's
+ * cleanup).
+ */
+export function createFrameInsertable(options: FrameOptions): {
+  readonly frame: Frame | null;
+  dispose(): void;
+};