@farm.js/islx 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.0.5
+
+TanStack Start.
+
+- `@farm.js/islx/tanstack-start`: `islxTanstackStart()` next to `tanstackStart()` runs a Start app
+  as islands, with configuration only. Routes, loaders and layouts render on the server; the
+  browser loads islx and the `"use client"` components a page uses (the modules under `src/`), not
+  the router, the route tree or loader data. Start's client entry becomes islx's and the router is
+  not dehydrated. Links move between routes without loading a document; a loader's promise passed
+  unawaited to a client component streams in; islands call Start server functions and islx server
+  actions. An app with its own `src/server.ts` uses `islandsHandler` from
+  `@farm.js/islx/tanstack-start/server`. Needs Node 22.12 or later (Start's own requirement).
+
 ## 0.0.4
 
 Promise props, and islands in a page that streams after it loaded.

package/README.md

@@ -13,7 +13,7 @@ islx started as [Farm.js](https://github.com/farming-labs/farm.js)'s islands mod
 replaces React Server Components' Flight payload. On a 300-page docs app it ships 26% less
 JavaScript, and a client navigation sends 2.5 KB instead of 12 KB.
 
-> Status: 0.0.4. React and Vite are supported; other renderers and framework
+> Status: 0.0.5. React, Vite and TanStack Start are supported; other renderers and framework
 > integrations follow. The wire format is in [SPEC.md](./SPEC.md), changes in
 > [CHANGELOG.md](./CHANGELOG.md).
 
@@ -169,6 +169,41 @@ export function Chart(props: { points: Map<string, number> }) { … }
 `examples/react` is a runnable app; `pnpm test:e2e` runs it in Chrome, in development and from
 its production build.
 
+## TanStack Start
+
+A Start app as islands, with configuration only:
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { tanstackStart } from "@tanstack/react-start/plugin/vite";
+import react from "@vitejs/plugin-react";
+import { islxTanstackStart } from "@farm.js/islx/tanstack-start";
+
+export default defineConfig({ plugins: [tanstackStart(), react(), islxTanstackStart()] });
+```
+
+Routes, loaders and layouts render on the server. The browser loads islx and the `"use client"`
+components a page uses (the modules under `src/`), not the router, the route tree or loader
+data: Start's client entry becomes islx's, `<Scripts />` still loads it, and the router is not
+dehydrated. Links move between routes without loading a document. A loader's promise passed
+unawaited to a client component streams in. Islands call Start server functions
+(`createServerFn`) and islx server actions (`"use server"`).
+
+- An app with its own `src/server.ts` renders with islx's handler:
+  `createServerEntry({ fetch: createStartHandler(islandsHandler) })`, with `islandsHandler` from
+  `@farm.js/islx/tanstack-start/server` (and `handleAction` from `@farm.js/islx/server` in front of
+  it for islx actions).
+- Client components run without a router in the browser: they cannot use `useRouter`,
+  `useNavigate` or `<Link>` (render plain `<a>` links; the server renders `<Link>` in routes).
+- A library's `"use client"` components render as server HTML.
+- A click before the islands hydrate is not replayed yet (the `interaction` strategy hydrates on
+  it, but the click itself is dropped).
+- Start sends a bot the whole page before any of it; people get it streamed.
+- Start needs Node 22.12 or later.
+
+`examples/tanstack-start` runs in the e2e suite, in development and from its production build.
+
 ## In a framework
 
 A framework that renders pages itself (Farm does) uses the pieces directly instead of

package/dist/_chunks/{actions-CtLpJPEB.mjs → actions-BuS5jDi0.mjs}

@@ -1,147 +1,6 @@
-import { A as VALUES_HEADER, P as formFieldName, d as FORM_REF_PREFIX, j as VALUE_KEY_PATTERN } from "./wire-QEQWBr5s.mjs";
-import { a as encode, c as needsObjectTag, o as encodeLeaf, r as decode, t as EncodeError } from "./codec-C8to-RQW.mjs";
+import { P as formFieldName, d as FORM_REF_PREFIX } from "./wire-QEQWBr5s.mjs";
 import { t as getBuildDefaults } from "./build-COIcs7wm.mjs";
-// src/server/values.ts
-/**
-* Values sent once: which parts of an island's props travel as values of their own, keyed by a
-* hash of their JSON, and which of those a response leaves out because the browser already holds
-* them. The browser side is `@farm.js/islx/client` (`getValueStore`).
-*/
-/** Shorter values stay inline: a reference and its script cost about 60 bytes. */
-const VALUE_MIN_LENGTH = 512;
-/** A 64-bit hash of a value's JSON, as 14 base-36 characters. Not cryptographic. */
-function hashValue(json) {
-	let h1 = 3735928559 ^ json.length;
-	let h2 = 1103547991 ^ json.length;
-	for (let index = 0; index < json.length; index++) {
-		const code = json.charCodeAt(index);
-		h1 = Math.imul(h1 ^ code, 2654435761);
-		h2 = Math.imul(h2 ^ code, 1597334677);
-	}
-	h1 = Math.imul(h1 ^ h1 >>> 16, 2246822507) ^ Math.imul(h2 ^ h2 >>> 13, 3266489909);
-	h2 = Math.imul(h2 ^ h2 >>> 16, 2246822507) ^ Math.imul(h1 ^ h1 >>> 13, 3266489909);
-	return (h2 >>> 0).toString(36).padStart(7, "0") + (h1 >>> 0).toString(36).padStart(7, "0");
-}
-/**
-* Serializes props with every value whose JSON reaches `minLength` replaced by a reference to it.
-* Types JSON cannot hold are tagged first (the codec), so a `Map` or a `Date` is addressed like
-* any other value. Inner values are addressed first, so a large value that differs between pages
-* in one place still shares its unchanged parts.
-*/
-function addressValues(props, { minLength = 512, encodeSpecial, encoded = false } = {}) {
-	const values = /* @__PURE__ */ new Map();
-	const reference = (json, children, parent) => {
-		const key = hashValue(json);
-		if (!values.has(key)) values.set(key, {
-			key,
-			json,
-			children
-		});
-		parent.push(key);
-		return `{"$":"r","v":"${key}"}`;
-	};
-	const seen = /* @__PURE__ */ new Set();
-	const encode = (value, parent) => {
-		const special = encoded ? void 0 : encodeSpecial?.(value);
-		if (special !== void 0) {
-			const json = JSON.stringify(special);
-			return [json, json.length];
-		}
-		const leaf = encoded ? void 0 : encodeLeaf(value);
-		if (leaf) {
-			const json = JSON.stringify(leaf);
-			return [json, json.length];
-		}
-		if (typeof value === "function") throw new TypeError("functions are not serializable");
-		if (typeof value === "symbol") throw new TypeError("symbol values are not serializable");
-		if (value === null || typeof value !== "object") {
-			const json = JSON.stringify(value);
-			return [typeof value === "string" && json.length >= minLength ? reference(json, [], parent) : json, json.length];
-		}
-		if (seen.has(value)) throw new TypeError("circular values are not serializable");
-		seen.add(value);
-		try {
-			if (!encoded && (value instanceof Map || value instanceof Set)) {
-				const entries = value instanceof Map ? Array.from(value, ([key, entry]) => [key, entry]) : [...value];
-				const [json, length] = encode(entries, parent);
-				const prefix = `{"$":"${value instanceof Map ? "M" : "S"}","v":`;
-				return [`${prefix}${json}}`, length + prefix.length + 1];
-			}
-			const prototype = Object.getPrototypeOf(value);
-			if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) throw new TypeError("class instances are not serializable");
-			const own = [];
-			let length = 2;
-			const parts = [];
-			if (Array.isArray(value)) for (const entry of value) {
-				const [json, entryLength] = encode(entry, own);
-				parts.push(json);
-				length += entryLength + 1;
-			}
-			else for (const [key, entry] of Object.entries(value)) {
-				const [json, entryLength] = encode(entry, own);
-				const name = JSON.stringify(key);
-				parts.push(`${name}:${json}`);
-				length += name.length + entryLength + 2;
-			}
-			let json = Array.isArray(value) ? `[${parts.join(",")}]` : `{${parts.join(",")}}`;
-			if (!encoded && !Array.isArray(value) && needsObjectTag(value)) {
-				json = `{"$":"o","v":${json}}`;
-				length += 14;
-			}
-			const wrapper = own.length === 1 && json.length < minLength / 4;
-			if (length >= minLength && !wrapper) return [reference(json, own, parent), length];
-			parent.push(...own);
-			return [json, length];
-		} finally {
-			seen.delete(value);
-		}
-	};
-	const roots = [];
-	return {
-		json: `{${Object.entries(props).map(([key, entry]) => `${JSON.stringify(key)}:${encode(entry, roots)[0]}`).join(",")}}`,
-		values,
-		roots
-	};
-}
-/**
-* The values a response sends for `addressed`, parents first. A value the browser holds is left
-* out with everything inside it: the browser kept those when it read the value.
-*/
-function selectValuesToSend(addressed, held) {
-	const send = [];
-	const seen = /* @__PURE__ */ new Set();
-	const visit = (key) => {
-		if (seen.has(key)) return;
-		seen.add(key);
-		if (held?.has(key)) return;
-		const value = addressed.values.get(key);
-		send.push(value);
-		value.children.forEach(visit);
-	};
-	addressed.roots.forEach(visit);
-	return send;
-}
-/**
-* The value keys a request names (`F-Values`): well-formed keys only, at most `MAX_HELD_VALUES`.
-*
-* A response that leaves values out is one browser's. Integrations must keep it out of shared
-* caches (CDN, ISR, PPR shells), and add `Vary: F-Values` to cacheable responses.
-*/
-function parseHeldValues(input) {
-	const header = typeof input === "string" || input == null ? input : (input instanceof Request ? input.headers : input).get(VALUES_HEADER);
-	const held = /* @__PURE__ */ new Set();
-	if (!header) return held;
-	for (const key of header.split(",", 256)) {
-		const trimmed = key.trim();
-		if (VALUE_KEY_PATTERN.test(trimmed)) held.add(trimmed);
-		if (held.size === 128) break;
-	}
-	return held;
-}
-/** A value script's JSON, safe inside a `<script>` element. */
-function escapeScriptJson(json) {
-	return json.replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029");
-}
+import { a as encode, r as decode, t as EncodeError } from "./codec-C8to-RQW.mjs";
 // src/server/seal.ts
 /**
 * Sealing an action's captured values. An inline `"use server"` function that reads a variable of
@@ -612,4 +471,4 @@ async function resolveAction(id, token) {
 		run: async (args) => runEntry(entry, values, args)
 	};
 }
-export { hashValue as _, getActionReference as a, resolveAction as c, generateActionKey as d, sealBound as f, escapeScriptJson as g, addressValues as h, encodeActionReference as i, SealError as l, VALUE_MIN_LENGTH as m, configureActionKeys as n, registerInlineAction as o, unsealBound as p, decodeActionReference as r, registerServerReference as s, bindInlineAction as t, createActionKeys as u, parseHeldValues as v, selectValuesToSend as y };
+export { getActionReference as a, resolveAction as c, generateActionKey as d, sealBound as f, encodeActionReference as i, SealError as l, configureActionKeys as n, registerInlineAction as o, unsealBound as p, decodeActionReference as r, registerServerReference as s, bindInlineAction as t, createActionKeys as u };

package/dist/_chunks/island-DVOr-OUw.mjs

@@ -0,0 +1,262 @@
+import { t as getBuildDefaults } from "./build-COIcs7wm.mjs";
+import { M as VALUE_SCRIPT_TYPE, h as ISLAND_ELEMENT, w as SLOT_ELEMENT, x as PROPS_SCRIPT_TYPE, y as PROMISE_SCRIPT_TYPE } from "./wire-QEQWBr5s.mjs";
+import * as React from "react";
+import * as ReactDOM from "react-dom";
+// src/react/island.ts
+/**
+* A client component, as the server renders it: its HTML inside `<f-island>`, and its props in
+* a script after it. Shared by the server and the browser: inside a hydrating island, a nested
+* client component is part of that island's React tree, not an island of its own.
+*
+* The compiler wraps every export of a `"use client"` module with `createIsland` in the server
+* build. The browser build keeps the module as it is.
+*/
+const CLIENT_REFERENCE = Symbol.for("islx.react.client-reference");
+/** The module export an island component renders, or undefined for any other type. */
+function getClientReference(type) {
+	if (!type || typeof type !== "function" && typeof type !== "object") return void 0;
+	return type[CLIENT_REFERENCE];
+}
+/**
+* Makes `element`'s client components part of the React root around it (a layout that hydrates
+* as one root), instead of islands of their own.
+*/
+function withinClientRoot(element) {
+	return React.createElement(getContexts().graph.Provider, { value: true }, element);
+}
+/**
+* Starts islands again below a `withinClientRoot`: the page a hydrating layout keeps as server
+* HTML renders its client components as islands of their own.
+*/
+function isolateIslands(element) {
+	return React.createElement(getContexts().graph.Provider, { value: false }, element);
+}
+const RENDER_STATE_RESOLVER = Symbol.for("islx.react.render-state");
+/**
+* For a framework that knows the request being rendered without React context (a request store):
+* returns the render's settings when no `IslandsProvider` or `renderToStream` gave them. Keep the
+* same `sent` set for the whole response.
+*/
+function setRenderStateResolver(resolve) {
+	globalThis[RENDER_STATE_RESOLVER] = resolve;
+}
+function resolveRenderState() {
+	const resolve = globalThis[RENDER_STATE_RESOLVER];
+	return resolve ? resolve() : null;
+}
+/**
+* Gives islands a render's settings when the framework renders the page itself (not through
+* `renderToStream`): which values the browser holds, and which this render already wrote.
+*/
+function IslandsProvider({ held = null, children }) {
+	const state = React.useMemo(() => ({
+		held: held && held.size > 0 ? held : null,
+		sent: /* @__PURE__ */ new Set()
+	}), [held]);
+	return React.createElement(getContexts().render.Provider, { value: state }, children);
+}
+const SERVER_HOOK = Symbol.for("islx.react.server");
+/** @internal */
+function getIslandServerHook() {
+	return globalThis[SERVER_HOOK];
+}
+/** @internal */
+function setIslandServerHook(hook) {
+	globalThis[SERVER_HOOK] = hook;
+}
+/** Tagged objects the runtime made (slots), as opposed to app data with a "$" key. */
+const runtimeTagged = /* @__PURE__ */ new WeakSet();
+const CONTEXTS = Symbol.for("islx.react.contexts");
+/** @internal */
+function getContexts() {
+	const scope = globalThis;
+	const all = scope[CONTEXTS] ??= /* @__PURE__ */ new WeakMap();
+	let contexts = all.get(React.createElement);
+	if (!contexts) {
+		contexts = {
+			graph: React.createContext(false),
+			render: React.createContext(null)
+		};
+		all.set(React.createElement, contexts);
+	}
+	return contexts;
+}
+function isElement(value) {
+	const type = value?.$$typeof;
+	return type === Symbol.for("react.transitional.element") || type === Symbol.for("react.element");
+}
+const slotStyle = { display: "contents" };
+/**
+* Splits props into what renders on the server and what travels: server output passed to an
+* island (`children`, or any element prop) renders once inside `<f-slot>`, and travels as a
+* reference to it, so the browser reads its HTML from the page instead of receiving it twice.
+*/
+function splitSlots(value, prefix, counter) {
+	if (isElement(value)) {
+		const name = `${prefix}${counter.next++}`;
+		const reference = {
+			["$"]: "s",
+			["v"]: name
+		};
+		runtimeTagged.add(reference);
+		return {
+			render: React.createElement(SLOT_ELEMENT, {
+				key: value.key ?? name,
+				name,
+				style: slotStyle
+			}, value),
+			wire: reference
+		};
+	}
+	if (Array.isArray(value)) {
+		const parts = value.map((entry) => splitSlots(entry, prefix, counter));
+		return {
+			render: parts.map((part) => part.render),
+			wire: parts.map((part) => part.wire)
+		};
+	}
+	if (value && typeof value === "object") {
+		const prototype = Object.getPrototypeOf(value);
+		if (prototype !== Object.prototype && prototype !== null) return {
+			render: value,
+			wire: value
+		};
+		const render = {};
+		const wire = {};
+		for (const [key, entry] of Object.entries(value)) {
+			const part = splitSlots(entry, prefix, counter);
+			render[key] = part.render;
+			wire[key] = part.wire;
+		}
+		return {
+			render,
+			wire
+		};
+	}
+	return {
+		render: value,
+		wire: value
+	};
+}
+const warned = /* @__PURE__ */ new Set();
+const outcomes = /* @__PURE__ */ new WeakMap();
+function settle(promise) {
+	let outcome = outcomes.get(promise);
+	if (!outcome) {
+		outcome = Promise.resolve(promise).then((value) => ({
+			ok: true,
+			value
+		}), (reason) => ({
+			ok: false,
+			reason
+		}));
+		outcomes.set(promise, outcome);
+	}
+	return outcome;
+}
+const REJECTED = "{\"e\":1}";
+/** Each promise an island received, in a boundary of its own: its outcome once it settles. */
+function promiseBoundaries(promises, label) {
+	return promises.map(({ name, promise }) => React.createElement(React.Suspense, {
+		key: name,
+		fallback: null
+	}, React.createElement(IslandPromise, {
+		name,
+		promise,
+		label
+	})));
+}
+/**
+* A promise's outcome, written when it settles. Its values are sent whether or not the page wrote
+* them already: this script may land before an earlier island's, wherever React puts it.
+*/
+function IslandPromise({ name, promise, label }) {
+	const outcome = React.use(settle(promise));
+	const state = React.useContext(getContexts().render) ?? resolveRenderState();
+	const hook = getIslandServerHook();
+	let encoded = {
+		json: REJECTED,
+		values: [],
+		promises: []
+	};
+	if (outcome.ok) try {
+		encoded = hook.encode({ v: outcome.value }, state?.held ?? null);
+	} catch (error) {
+		console.warn(`[islx] A promise passed to ${label} resolved to a value that cannot be sent to the browser: it rejects there.`, error);
+	}
+	else console.error(`[islx] A promise passed to ${label} rejected.`, outcome.reason);
+	return React.createElement(React.Fragment, null, ...encoded.values.map((value) => React.createElement("script", {
+		key: value.key,
+		type: VALUE_SCRIPT_TYPE,
+		name: value.key,
+		dangerouslySetInnerHTML: { __html: hook.escape(value.json) }
+	})), React.createElement("script", {
+		key: "outcome",
+		type: PROMISE_SCRIPT_TYPE,
+		name,
+		dangerouslySetInnerHTML: { __html: hook.escape(encoded.json) }
+	}), ...promiseBoundaries(encoded.promises, label));
+}
+function isThenable(value) {
+	return !!value && typeof value.then === "function";
+}
+/**
+* Wraps a client component so the server renders it as an island. `src` is the module the browser
+* imports, `exportName` the component's export there.
+*/
+function createIsland(Component, src, exportName, strategy = "load") {
+	function Island(props) {
+		const { graph, render } = getContexts();
+		const insideIsland = React.useContext(graph);
+		const state = React.useContext(render) ?? resolveRenderState();
+		const id = React.useId();
+		if (insideIsland) return React.createElement(Component, props);
+		const hook = getIslandServerHook();
+		if (!hook) throw new Error("islx: an island rendered on a server that did not import @farm.js/islx/react/server");
+		let encoded;
+		let renderProps;
+		try {
+			const { render: rendered, wire } = splitSlots(props, `${id}s`, { next: 0 });
+			renderProps = rendered;
+			const skip = state ? /* @__PURE__ */ new Set([...state.held ?? [], ...state.sent]) : null;
+			encoded = hook.encode(wire, skip);
+			for (const value of encoded.values) state?.sent.add(value.key);
+		} catch (error) {
+			if (isThenable(error)) throw error;
+			const message = error instanceof Error ? error.message : String(error);
+			const key = `${src}#${exportName}:${message}`;
+			if (!warned.has(key)) {
+				warned.add(key);
+				console.warn(`[islx] ${exportName} (${src}) was rendered without hydration: its props cannot be sent to the browser. ${message}`);
+			}
+			return React.createElement(Component, props);
+		}
+		if (strategy === "load") for (const href of getBuildDefaults().modules?.[src] ?? []) ReactDOM.preloadModule?.(href, { as: "script" });
+		return React.createElement(React.Fragment, null, ...encoded.values.map((value) => React.createElement("script", {
+			key: value.key,
+			type: VALUE_SCRIPT_TYPE,
+			name: value.key,
+			dangerouslySetInnerHTML: { __html: hook.escape(value.json) }
+		})), React.createElement(ISLAND_ELEMENT, {
+			key: "island",
+			src,
+			export: exportName,
+			props: id,
+			strategy,
+			style: slotStyle
+		}, React.createElement(graph.Provider, { value: true }, React.createElement(Component, renderProps))), React.createElement("script", {
+			key: "props",
+			type: PROPS_SCRIPT_TYPE,
+			htmlFor: id,
+			dangerouslySetInnerHTML: { __html: hook.escape(encoded.json) }
+		}), ...promiseBoundaries(encoded.promises, `${exportName} (${src})`));
+	}
+	Island.displayName = `Island(${Component.displayName || Component.name || exportName})`;
+	Object.defineProperty(Island, CLIENT_REFERENCE, { value: {
+		src,
+		exportName,
+		Component
+	} });
+	return Island;
+}
+export { getIslandServerHook as a, setIslandServerHook as c, getContexts as i, setRenderStateResolver as l, createIsland as n, isolateIslands as o, getClientReference as r, runtimeTagged as s, IslandsProvider as t, withinClientRoot as u };