@farm.js/islx 0.0.4 → 0.0.6

package/dist/_chunks/vite-BTzYlEiY.mjs

@@ -0,0 +1,506 @@
+import { i as transformActions, r as hasModuleDirective, t as ActionCompileError } from "./actions-Eutk6UzT.mjs";
+import { t as ISLAND_STRATEGIES } from "./schedule-CjoybS3b.mjs";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { walk } from "estree-walker";
+import MagicString from "magic-string";
+import { analyze } from "periscopic";
+import { readFile, readdir, writeFile } from "node:fs/promises";
+// src/compiler/client.ts
+/**
+* The `"use client"` compiler. In the server build, every component a `"use client"` module
+* exports renders as an island: its server HTML, and its props for the browser. The browser build
+* keeps the module as it is.
+*
+* A component is an export named in PascalCase (`Chart`, not `COLORS` or `useChart`) that is not
+* a literal value, or the default export. Other exports (hooks, constants, helpers) stay as they
+* are on both sides.
+*
+* When an island hydrates comes from the module's `hydrate` export:
+*
+*   export const hydrate = "visible";                        // every component in the file
+*   export const hydrate = { Chart: "visible", Legend: "idle" };  // per component; others "load"
+*/
+const FUNCTION_TYPES = /* @__PURE__ */ new Set([
+	"FunctionDeclaration",
+	"FunctionExpression",
+	"ArrowFunctionExpression"
+]);
+function isComponentName(name) {
+	return /^[A-Z]/.test(name) && /[a-z]/.test(name);
+}
+const VALUE_TYPES = /* @__PURE__ */ new Set([
+	"Literal",
+	"ArrayExpression",
+	"ObjectExpression",
+	"TemplateLiteral",
+	"UnaryExpression",
+	"BinaryExpression"
+]);
+/** Reads the `hydrate` export: a strategy for every component, or one per component. */
+function readStrategies(program, fail) {
+	const byName = /* @__PURE__ */ new Map();
+	const check = (value, node) => {
+		if (typeof value !== "string" || !ISLAND_STRATEGIES.includes(value)) fail(`hydrate must be one of ${ISLAND_STRATEGIES.map((s) => `"${s}"`).join(", ")}`, node);
+		return value;
+	};
+	for (const node of program.body ?? []) {
+		if (node.type !== "ExportNamedDeclaration" || node.declaration?.type !== "VariableDeclaration") continue;
+		for (const declarator of node.declaration.declarations ?? []) {
+			if (declarator.id?.type !== "Identifier" || declarator.id.name !== "hydrate") continue;
+			let init = declarator.init;
+			while (init && (init.type === "TSAsExpression" || init.type === "TSSatisfiesExpression")) init = init.expression;
+			if (init?.type === "Literal") return {
+				all: check(init.value, init),
+				byName
+			};
+			if (init?.type === "ObjectExpression") {
+				for (const property of init.properties ?? []) {
+					const key = property.key?.type === "Identifier" ? property.key.name : property.key?.value;
+					if (property.type !== "Property" || property.computed || typeof key !== "string" || property.value?.type !== "Literal") fail("hydrate must be a string, or an object of strings: { Chart: \"visible\" }", property);
+					byName.set(key, check(property.value.value, property.value));
+				}
+				return { byName };
+			}
+			fail("hydrate must be written as a literal: \"visible\", or { Chart: \"visible\" }", declarator);
+		}
+	}
+	return { byName };
+}
+/** Wraps a `"use client"` module's components as islands, or returns null for any other module. */
+function transformClientModule(options) {
+	const { code, id, root } = options;
+	if (!hasModuleDirective(code, options.directive ?? "use client")) return null;
+	const file = id.split("?", 1)[0];
+	const relative = path.relative(root, file).split(path.sep).join("/");
+	const program = options.parse(code);
+	const fail = (message, node) => {
+		throw new ActionCompileError(message, file, code, node.start);
+	};
+	const strategies = readStrategies(program, fail);
+	const strategyOf = (name) => {
+		const configured = options.strategy?.(name);
+		if (configured !== void 0 && !ISLAND_STRATEGIES.includes(configured)) throw new Error(`islx: strategy for ${name} must be one of ${ISLAND_STRATEGIES.join(", ")}`);
+		return configured ?? strategies.byName.get(name) ?? strategies.all ?? "load";
+	};
+	const output = new MagicString(code);
+	const wrapped = [];
+	for (const node of program.body ?? []) if (node.type === "ExportNamedDeclaration" && !node.source && node.exportKind !== "type") {
+		const declaration = node.declaration;
+		if (declaration) {
+			const names = declaration.type === "VariableDeclaration" ? declaration.declarations.flatMap((d) => d.id?.type === "Identifier" && !(d.init && VALUE_TYPES.has(d.init.type)) ? [d.id.name] : []) : declaration.id?.name ? [declaration.id.name] : [];
+			const declared = declaration.type === "VariableDeclaration" ? declaration.declarations.length : names.length;
+			const components = names.filter(isComponentName);
+			if (components.length === 0 || String(declaration.type).startsWith("TS")) continue;
+			if (components.length !== declared) fail("Export components and other values in separate statements", declaration);
+			output.remove(node.start, declaration.start);
+			for (const name of components) wrapped.push({
+				local: name,
+				exportName: name
+			});
+			continue;
+		}
+		const kept = [];
+		for (const specifier of node.specifiers ?? []) {
+			const exported = specifier.exported?.name ?? specifier.exported?.value;
+			const local = specifier.local?.name ?? specifier.local?.value;
+			if (specifier.exportKind !== "type" && (isComponentName(exported) || exported === "default")) wrapped.push({
+				local,
+				exportName: exported
+			});
+			else kept.push(output.slice(specifier.start, specifier.end));
+		}
+		output.overwrite(node.start, node.end, kept.length > 0 ? `export { ${kept.join(", ")} };` : "");
+	} else if (node.type === "ExportDefaultDeclaration") {
+		const declaration = node.declaration;
+		if (FUNCTION_TYPES.has(declaration.type) || declaration.type === "ClassDeclaration" || declaration.type === "ClassExpression") {
+			if (declaration.id?.name) {
+				output.remove(node.start, declaration.start);
+				wrapped.push({
+					local: declaration.id.name,
+					exportName: "default"
+				});
+			} else {
+				output.overwrite(node.start, declaration.start, "const $$islx_default = ");
+				wrapped.push({
+					local: "$$islx_default",
+					exportName: "default"
+				});
+			}
+		} else if (declaration.type === "Identifier" || declaration.type.endsWith("Expression")) {
+			output.overwrite(node.start, declaration.start, "const $$islx_default = ");
+			if (!code.slice(declaration.end, node.end).includes(";")) output.appendLeft(declaration.end, ";");
+			wrapped.push({
+				local: "$$islx_default",
+				exportName: "default"
+			});
+		}
+	}
+	if (wrapped.length === 0) return null;
+	const runtime = options.runtime ?? "@farm.js/islx/react";
+	const src = options.reference(relative);
+	const lines = [...wrapped.map(({ local, exportName }, index) => {
+		return `const $$islx_island_${index} = $$islx_island(${local}, ${src}, ${JSON.stringify(exportName)}, ${JSON.stringify(strategyOf(exportName === "default" ? "default" : exportName))});`;
+	}), `export { ${wrapped.map(({ exportName }, index) => `$$islx_island_${index} as ${exportName}`).join(", ")} };`];
+	const imports = [`import { createIsland as $$islx_island } from ${JSON.stringify(runtime)};`, ...(options.sideEffects ?? []).map((module) => `import ${JSON.stringify(module)};`)];
+	output.prepend(`${imports.join("\n")}\n`);
+	output.append(`\n${lines.join("\n")}\n`);
+	return {
+		code: output.toString(),
+		map: output.generateMap({
+			hires: true,
+			source: file
+		}),
+		islands: wrapped.map(({ exportName }) => ({
+			exportName,
+			strategy: strategyOf(exportName)
+		}))
+	};
+}
+// src/vite.ts
+/**
+* @farm.js/islx/vite: islx for Vite 6 and later (the Environment API).
+*
+*   import react from "@vitejs/plugin-react";
+*   import { islx } from "@farm.js/islx/vite";
+*   export default defineConfig({ plugins: [react(), islx()] });
+*
+* - Server environments: `"use client"` components render as islands, `"use server"` exports
+*   and inline actions register.
+* - The client environment: `"use server"` modules become references; inline actions are
+*   refused; the browser entry hydrates islands.
+* - `vite build` builds the server first, which finds the client components pages use, then the
+*   browser with exactly those (plus `clientComponents.include`), each in a chunk of its own that
+*   the browser entry imports when an island needs it. An island names its module by its path
+*   from the root; the server build learns the entry's URL once the browser build has named it.
+*/
+const RUNTIME_ID = "virtual:islx/runtime";
+/** @internal The browser entry, for a framework whose own entry imports it. */
+const ENTRY_ID = "virtual:islx/client-entry";
+const LIBRARY_RUNTIME_ID = "virtual:islx/react-for-libraries";
+const CLIENT_HOOKS_ID = "virtual:islx/hooks-client";
+const SERVER_HOOKS_ID = "virtual:islx/hooks-server";
+const BROWSER_GLOBALS = /* @__PURE__ */ new Set([
+	"window",
+	"document",
+	"location",
+	"history",
+	"navigator",
+	"screen",
+	"localStorage",
+	"sessionStorage",
+	"alert",
+	"confirm",
+	"prompt",
+	"requestAnimationFrame",
+	"cancelAnimationFrame",
+	"requestIdleCallback",
+	"cancelIdleCallback",
+	"IntersectionObserver",
+	"MutationObserver",
+	"ResizeObserver",
+	"HTMLElement",
+	"Element",
+	"Node",
+	"CustomEvent",
+	"Event",
+	"matchMedia",
+	"getComputedStyle",
+	"innerWidth",
+	"innerHeight",
+	"scrollX",
+	"scrollY",
+	"self"
+]);
+/**
+* The source of a hooks module made from callbacks. Each callback is copied as written, so it
+* must not use anything from where it was written: an outside variable, an import.
+*/
+function serializeHooks(hooks, where, parse) {
+	const entries = [];
+	for (const [name, value] of Object.entries(hooks)) {
+		if (value === void 0) continue;
+		if (typeof value !== "function") throw new Error(`islx: hooks.${where}.${name} must be a function`);
+		const source = Function.prototype.toString.call(value);
+		if (source.includes("[native code]")) throw new Error(`islx: hooks.${where}.${name} must be written in the config, not a built-in or bound function`);
+		const expression = parse("hook.js", `(${source});`).errors.length === 0;
+		entries.push(expression ? `${JSON.stringify(name)}: ${source}` : source);
+	}
+	const code = `export default {\n${entries.join(",\n")}\n};\n`;
+	const program = parse("hooks.js", code);
+	const { globals } = analyze(program);
+	const outside = [...globals.keys()].filter((name) => where === "client" ? !(name in globalThis) && !BROWSER_GLOBALS.has(name) : BROWSER_GLOBALS.has(name) || !(name in globalThis));
+	let imports = false;
+	walk(program, { enter(node) {
+		if (node.type === "ImportExpression") imports = true;
+	} });
+	if (outside.length > 0 || imports) {
+		const what = imports ? "`import()`" : outside.map((name) => `\`${name}\``).join(", ");
+		throw new Error(`islx: hooks.${where} uses ${what}, which does not exist where the hook runs: hooks written in the config are copied into the ${where === "client" ? "browser" : "server"} build as source. Use a global${where === "client" ? " (window.analytics)" : ""}, or put the hooks in a module and pass its path: hooks: { ${where}: "./src/islx.${where}.ts" }.`);
+	}
+	return code;
+}
+/** Stand for the browser entry's URL, and the files each client module needs, in the server
+* build until the browser build names them. */
+const ENTRY_PLACEHOLDER = "__islx_client_entry_url__";
+const MODULES_PLACEHOLDER = "__islx_client_modules__";
+const SCRIPT = /\.[cm]?[jt]sx?$/;
+async function createParser() {
+	const withErrors = (result) => Object.assign(result.program, { errors: result.errors ?? [] });
+	const vite = await import("vite");
+	if (typeof vite.parseSync === "function") return (file, code) => withErrors(vite.parseSync(file, code));
+	try {
+		const oxc = await import("oxc-parser");
+		return (file, code) => withErrors(oxc.parseSync(file, code));
+	} catch {
+		throw new Error("@farm.js/islx/vite needs Vite 8, or oxc-parser installed with an older Vite");
+	}
+}
+/** A tiny glob matcher: `**`, `*` and `?`, on paths from the root. */
+function globToRegExp(glob) {
+	let pattern = "";
+	for (let index = 0; index < glob.length; index++) {
+		const char = glob[index];
+		if (char === "*" && glob[index + 1] === "*") {
+			pattern += glob[index + 2] === "/" ? "(?:.*/)?" : ".*";
+			index += glob[index + 2] === "/" ? 2 : 1;
+		} else if (char === "*") pattern += "[^/]*";
+		else if (char === "?") pattern += "[^/]";
+		else pattern += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	}
+	return new RegExp(`^${pattern.replace(/^\.\//, "")}$`);
+}
+async function listFiles(root, directory = root) {
+	const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+	const files = [];
+	for (const entry of entries) {
+		if (entry.name === "node_modules" || entry.name.startsWith(".") || entry.name === "dist") continue;
+		const full = path.join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await listFiles(root, full));
+		else if (SCRIPT.test(entry.name)) files.push(full);
+	}
+	return files;
+}
+async function listOutput(directory) {
+	const entries = await readdir(directory, { withFileTypes: true }).catch(() => []);
+	const files = [];
+	for (const entry of entries) {
+		const full = path.join(directory, entry.name);
+		if (entry.isDirectory()) files.push(...await listOutput(full));
+		else if (/\.[cm]?js$/.test(entry.name)) files.push(full);
+	}
+	return files;
+}
+const toPosix = (value) => value.split(path.sep).join("/");
+const RESERVED_DIRECTIVES = /* @__PURE__ */ new Set(["use strict", "use asm"]);
+/** The directives to use, refusing ones that would make a file mean two things. */
+function resolveDirectives(directives = {}) {
+	const client = directives.client ?? "use client";
+	const server = directives.server ?? "use server";
+	for (const [kind, value] of [["client", client], ["server", server]]) if (typeof value !== "string" || !/^[\w-]+( [\w-]+)*$/.test(value) || RESERVED_DIRECTIVES.has(value)) throw new Error(`islx: directives.${kind} must be a plain directive such as "use island", not ${JSON.stringify(value)}`);
+	if (client === server) throw new Error(`islx: directives.client and directives.server are both ${JSON.stringify(client)}`);
+	return {
+		client,
+		server
+	};
+}
+function islx(options = {}, host = {}) {
+	const directives = resolveDirectives(options.directives);
+	let config;
+	let parse;
+	let preamble = false;
+	const include = (options.clientComponents?.include ?? []).map(globToRegExp);
+	const exclude = (options.clientComponents?.exclude ?? []).map(globToRegExp);
+	/** Client modules the server build rendered, by path from the root. */
+	const discovered = /* @__PURE__ */ new Set();
+	/** The browser entry's URL, once the browser build named it. */
+	let entryUrl;
+	/** The files each client module needs, once the browser build named them. */
+	const moduleFiles = {};
+	/** Whether the browser build ran first (a framework that orders the build). */
+	let clientBuilt = false;
+	const buildKey = randomBytes(32).toString("base64url");
+	const isServer = (name) => options.serverEnvironments ? options.serverEnvironments.includes(name) : name !== "client";
+	const relativeOf = (id) => toPosix(path.relative(config.root, id.split("?", 1)[0]));
+	const excluded = (relative) => exclude.some((pattern) => pattern.test(relative));
+	const isBuild = () => config.command === "build";
+	const clientInputs = async () => {
+		const inputs = new Set(discovered);
+		if (include.length > 0) for (const file of await listFiles(config.root)) {
+			const relative = relativeOf(file);
+			if (!include.some((pattern) => pattern.test(relative)) || excluded(relative)) continue;
+			if ((await readFile(file, "utf8")).includes("use client")) inputs.add(relative);
+		}
+		return [...inputs].sort();
+	};
+	return [
+		{
+			name: "islx",
+			enforce: "pre",
+			sharedDuringBuild: true,
+			config(user) {
+				const clientBuild = user.environments?.client?.build;
+				const input = clientBuild?.rollupOptions?.input;
+				return {
+					builder: user.builder ?? {},
+					environments: { client: {
+						optimizeDeps: { include: [
+							"react",
+							"react/jsx-runtime",
+							"react/jsx-dev-runtime",
+							"react-dom",
+							"react-dom/client"
+						] },
+						build: {
+							outDir: clientBuild?.outDir ?? "dist/client",
+							rollupOptions: { input: host.frameworkEntry ? input : {
+								...typeof input === "string" ? { index: input } : Array.isArray(input) ? Object.fromEntries(input.map((entry, index) => [`input${index}`, entry])) : input,
+								"islx-entry": ENTRY_ID
+							} }
+						}
+					} }
+				};
+			},
+			async configResolved(resolved) {
+				config = resolved;
+				parse = await createParser();
+				preamble = resolved.plugins.some((plugin) => plugin.name === "vite:react-virtual-preamble");
+			},
+			resolveId(id) {
+				if (id === LIBRARY_RUNTIME_ID) return this.resolve("@farm.js/islx/react", path.join(config.root, "package.json"), { skipSelf: true });
+				if (id === RUNTIME_ID || id === "virtual:islx/client-entry" || id === CLIENT_HOOKS_ID || id === SERVER_HOOKS_ID) return `\0${id}`;
+			},
+			async load(id) {
+				if (id === `\0${RUNTIME_ID}`) {
+					const entry = host.frameworkEntry ? void 0 : !isBuild() ? `${config.base}@id/__x00__${ENTRY_ID}` : clientBuilt ? entryUrl : ENTRY_PLACEHOLDER;
+					const modules = !isBuild() ? "{}" : clientBuilt ? JSON.stringify(moduleFiles) : `JSON.parse(${JSON.stringify(MODULES_PLACEHOLDER)})`;
+					return [
+						...host.frameworkRender ? [`import "@farm.js/islx/react/server";`] : [],
+						`import { setBuildDefaults, setServerHooks } from "@farm.js/islx/server";`,
+						`import hooks from ${JSON.stringify(SERVER_HOOKS_ID)};`,
+						`setBuildDefaults({ entry: ${JSON.stringify(entry)}, key: ${JSON.stringify(buildKey)}, modules: ${modules} });`,
+						`setServerHooks(hooks);`
+					].join("\n");
+				}
+				if (id === `\0${CLIENT_HOOKS_ID}` || id === `\0${SERVER_HOOKS_ID}`) {
+					const where = id === `\0${CLIENT_HOOKS_ID}` ? "client" : "server";
+					const hooks = options.hooks?.[where];
+					if (hooks === void 0) return "export default undefined;";
+					if (typeof hooks === "string") return `export { default } from ${JSON.stringify(path.resolve(config.root, hooks))};`;
+					return serializeHooks(hooks, where, parse);
+				}
+				if (id === `\0virtual:islx/client-entry`) {
+					const load = isBuild() ? `const modules = {\n${(await clientInputs()).map((relative) => `  ${JSON.stringify(relative)}: () => import(${JSON.stringify(path.resolve(config.root, relative))}),`).join("\n")}\n};\nconst load = (src) => modules[src] ? modules[src]() : Promise.reject(new Error("islx: no client module " + src));` : `const root = new URL(${JSON.stringify(`file://${toPosix(config.root)}/`)});\nconst load = (src) => import(/* @vite-ignore */ src.startsWith("../") ? "/@fs" + new URL(src, root).pathname : ${JSON.stringify(config.base)} + src);`;
+					return [
+						...preamble && !isBuild() ? [`import "@vitejs/plugin-react/preamble";`] : [],
+						`import { createHydrationRuntime, refreshDocument, scheduleHydration, swapDocument } from "@farm.js/islx/react/client";`,
+						`import { enhanceForms, setActionNavigator, setClientHooks, startNavigation, navigate } from "@farm.js/islx/client";`,
+						`import hooks from ${JSON.stringify(CLIENT_HOOKS_ID)};`,
+						`setClientHooks(hooks);`,
+						load,
+						`const runtime = createHydrationRuntime({ load, schedule: scheduleHydration });`,
+						`setActionNavigator({ refresh: () => refreshDocument(runtime), navigate: (href) => navigate(href) });`,
+						`enhanceForms();`,
+						...options.navigation === false ? [] : [`startNavigation({ swap: (next) => swapDocument(runtime, next), viewTransition: ${typeof options.navigation === "object" && options.navigation.viewTransition === true} });`],
+						`runtime.hydrate(document);`,
+						`export { runtime };`
+					].join("\n");
+				}
+			},
+			transform(code, id) {
+				if (id.startsWith("\0") || !SCRIPT.test(id.split("?", 1)[0])) return null;
+				const library = id.includes("/node_modules/");
+				const clientDirective = library ? "use client" : directives.client;
+				if (!code.includes(clientDirective) && (library || !code.includes(directives.server))) return null;
+				const file = id.split("?", 1)[0];
+				const server = isServer(this.environment.name);
+				const relative = relativeOf(file);
+				const parseFile = (source) => parse(file, source);
+				if (server && !excluded(relative)) {
+					const island = transformClientModule({
+						code,
+						id: file,
+						root: config.root,
+						parse: parseFile,
+						reference: (relative) => {
+							discovered.add(relative);
+							return JSON.stringify(relative);
+						},
+						sideEffects: [RUNTIME_ID],
+						directive: clientDirective,
+						...library ? { runtime: LIBRARY_RUNTIME_ID } : {}
+					});
+					if (island) {
+						if (!library) transformActions({
+							code,
+							id: file,
+							root: config.root,
+							environment: "client",
+							parse: parseFile,
+							directive: directives.server
+						});
+						return {
+							code: island.code,
+							map: island.map
+						};
+					}
+				}
+				if (library) return null;
+				const actions = transformActions({
+					code,
+					id: file,
+					root: config.root,
+					environment: server ? "server" : "client",
+					parse: parseFile,
+					directive: directives.server
+				});
+				if (!actions) return null;
+				return {
+					code: server ? `import ${JSON.stringify(RUNTIME_ID)};\n${actions.code}` : actions.code,
+					map: server ? null : actions.map
+				};
+			}
+		},
+		{
+			name: "islx:reload",
+			apply: "serve",
+			hotUpdate({ file, modules, server }) {
+				if (!isServer(this.environment.name) || modules.length === 0) return;
+				const client = server.environments.client;
+				if (client?.moduleGraph.getModulesByFile(file)?.size) return;
+				client?.hot.send({ type: "full-reload" });
+			}
+		},
+		{
+			name: "islx:build",
+			sharedDuringBuild: true,
+			async buildApp(builder) {
+				if (host.frameworkBuild) return;
+				const servers = Object.values(builder.environments).filter((environment) => isServer(environment.name));
+				for (const environment of servers) await builder.build(environment);
+				await builder.build(builder.environments.client);
+				if (!entryUrl) throw new Error("islx: the browser build did not emit the islx entry");
+				for (const environment of servers) {
+					const outDir = path.resolve(config.root, environment.config.build.outDir);
+					for (const file of await listOutput(outDir)) {
+						const source = await readFile(file, "utf8");
+						if (!source.includes(ENTRY_PLACEHOLDER) && !source.includes(MODULES_PLACEHOLDER)) continue;
+						const modules = JSON.stringify(JSON.stringify(moduleFiles)).slice(1, -1);
+						await writeFile(file, source.replaceAll(ENTRY_PLACEHOLDER, entryUrl).replaceAll(MODULES_PLACEHOLDER, modules));
+					}
+				}
+			},
+			generateBundle(_options, bundle) {
+				if (this.environment.name !== "client") return;
+				const url = (fileName) => `${config.base}${fileName}`;
+				for (const chunk of Object.values(bundle)) {
+					if (chunk.type !== "chunk" || !chunk.facadeModuleId) continue;
+					if (chunk.isEntry && chunk.facadeModuleId === `\0virtual:islx/client-entry`) entryUrl = url(chunk.fileName);
+					else if (chunk.isDynamicEntry && !chunk.facadeModuleId.startsWith("\0")) moduleFiles[relativeOf(chunk.facadeModuleId)] = [chunk.fileName, ...chunk.imports].map(url);
+				}
+				clientBuilt = true;
+			}
+		}
+	];
+}
+export { serializeHooks as i, islx as n, resolveDirectives as r, ENTRY_ID as t };

package/dist/client.d.mts

@@ -10,8 +10,24 @@ interface ActionNavigator {
   /** A client navigation to `href`, as the action's redirect. */
   navigate?(href: string): Promise<void> | void;
 }
+/** A call of a server action, as an interceptor sees it. */
+interface ActionCall {
+  id: string;
+  /** The export (or inline function) name, when known. */
+  name?: string;
+  /** The arguments, after any bound with `.bind`. */
+  args: readonly unknown[];
+}
+/**
+ * Wraps every server action call: call `next` to make the request, and return what the caller
+ * gets. A framework uses it to unwrap what its own server side adds to a result (cache
+ * invalidations, a query's cache entry) or to turn a returned error back into one it throws.
+ */
+type ActionInterceptor = (call: ActionCall, next: () => Promise<unknown>) => Promise<unknown>;
 /** Connects actions to the framework's router. */
 declare function setActionNavigator(navigator: ActionNavigator): void;
+/** Installs the framework's interceptor for server action calls (one; a later call replaces it). */
+declare function setActionInterceptor(interceptor: ActionInterceptor | undefined): void;
 /** Decodes an action in a result or props: `{"$":"a","v":id,"b"?:sealed}`. */
 declare function decodeActionReference(object: Record<string, unknown>): AnyFunction | undefined;
 /** The function that calls a server action; one per id and sealed values, so props keep identity. */
@@ -55,4 +71,4 @@ declare const INTERACTION_EVENT = "f:island-interaction";
 declare const REPLAYABLE_SELECTOR = "button,[role=\"button\"],input[type=\"button\"],input[type=\"submit\"],input[type=\"reset\"]";
 /** The inline script's source (no `<script>` tag): pass it to the page's head or bootstrap. */
 declare const PREHYDRATION_SCRIPT: string;
-export { type ActionNavigator, type ClientHookEvent, type ClientHookEvents, type ClientHooks, INTERACTION_EVENT, NAVIGATION_RENDER, type NavigateOptions, type NavigationOptions, PENDING_INTERACTIONS, PREHYDRATION_SCRIPT, REPLAYABLE_SELECTOR, type ValueStore, createServerReference, createValueStore, decodeActionReference, defineClientHooks, enhanceForms, getValueStore, hookEventName, navigate, setActionNavigator, setClientHooks, startNavigation, valueHeaders };
+export { type ActionCall, type ActionInterceptor, type ActionNavigator, type ClientHookEvent, type ClientHookEvents, type ClientHooks, INTERACTION_EVENT, NAVIGATION_RENDER, type NavigateOptions, type NavigationOptions, PENDING_INTERACTIONS, PREHYDRATION_SCRIPT, REPLAYABLE_SELECTOR, type ValueStore, createServerReference, createValueStore, decodeActionReference, defineClientHooks, enhanceForms, getValueStore, hookEventName, navigate, setActionInterceptor, setActionNavigator, setClientHooks, startNavigation, valueHeaders };

package/dist/client.mjs

@@ -1,4 +1,4 @@
-import { a as emit, c as createValueStore, i as defineClientHooks, l as getValueStore, n as decodeActionReference, o as hookEventName, r as setActionNavigator, s as setClientHooks, t as createServerReference, u as valueHeaders } from "./_chunks/actions-8RQfrM-p.mjs";
+import { a as defineClientHooks, c as setClientHooks, d as valueHeaders, i as setActionNavigator, l as createValueStore, n as decodeActionReference, o as emit, r as setActionInterceptor, s as hookEventName, t as createServerReference, u as getValueStore } from "./_chunks/actions-C-IwUCKU.mjs";
 import { C as RENDER_HEADER, I as readPostedAction, L as stripRuntimeFields } from "./_chunks/wire-QEQWBr5s.mjs";
 import { i as REPLAYABLE_SELECTOR, n as PENDING_INTERACTIONS, r as PREHYDRATION_SCRIPT, t as INTERACTION_EVENT } from "./_chunks/prehydration-B1GLTLdk.mjs";
 // src/client/forms.ts
@@ -194,4 +194,4 @@ function navigate(href, options = {}) {
 	else location.assign(href);
 	return Promise.resolve();
 }
-export { INTERACTION_EVENT, NAVIGATION_RENDER, PENDING_INTERACTIONS, PREHYDRATION_SCRIPT, REPLAYABLE_SELECTOR, createServerReference, createValueStore, decodeActionReference, defineClientHooks, enhanceForms, getValueStore, hookEventName, navigate, setActionNavigator, setClientHooks, startNavigation, valueHeaders };
+export { INTERACTION_EVENT, NAVIGATION_RENDER, PENDING_INTERACTIONS, PREHYDRATION_SCRIPT, REPLAYABLE_SELECTOR, createServerReference, createValueStore, decodeActionReference, defineClientHooks, enhanceForms, getValueStore, hookEventName, navigate, setActionInterceptor, setActionNavigator, setClientHooks, startNavigation, valueHeaders };

package/dist/react/client.mjs

@@ -1,7 +1,8 @@
-import { a as emit, l as getValueStore, t as createServerReference, u as valueHeaders } from "../_chunks/actions-8RQfrM-p.mjs";
+import { d as valueHeaders, o as emit, t as createServerReference, u as getValueStore } from "../_chunks/actions-C-IwUCKU.mjs";
 import { i as decodeTagged, n as NOT_A_VALUE, r as decode, u as setOwn } from "../_chunks/codec-C8to-RQW.mjs";
 import { F as getTag, f as FORM_STATE_SCRIPT_TYPE, h as ISLAND_ELEMENT, m as HYDRATED_ATTRIBUTE, w as SLOT_ELEMENT, x as PROPS_SCRIPT_TYPE, y as PROMISE_SCRIPT_TYPE } from "../_chunks/wire-QEQWBr5s.mjs";
-import { d as isolateIslands, h as withinClientRoot, i as createServerTreeLayout, n as PAYLOAD_ONLY_ATTRIBUTE, o as updateServerTrees, r as createServerTreeElement, u as getContexts } from "../_chunks/tree-opIpaCke.mjs";
+import { i as getContexts, o as isolateIslands, u as withinClientRoot } from "../_chunks/island-DVOr-OUw.mjs";
+import { i as createServerTreeLayout, n as PAYLOAD_ONLY_ATTRIBUTE, o as updateServerTrees, r as createServerTreeElement } from "../_chunks/tree-C47p6khN.mjs";
 import { n as isIslandStrategy, r as scheduleHydration, t as ISLAND_STRATEGIES } from "../_chunks/schedule-CjoybS3b.mjs";
 import * as React from "react";
 import { hydrateRoot } from "react-dom/client";

package/dist/react/server.mjs

@@ -1,9 +1,11 @@
 import { a as encode } from "../_chunks/codec-C8to-RQW.mjs";
 import { f as FORM_STATE_SCRIPT_TYPE } from "../_chunks/wire-QEQWBr5s.mjs";
 import { r as PREHYDRATION_SCRIPT } from "../_chunks/prehydration-B1GLTLdk.mjs";
-import { g as escapeScriptJson, h as addressValues, i as encodeActionReference, v as parseHeldValues, y as selectValuesToSend } from "../_chunks/actions-CtLpJPEB.mjs";
+import { i as encodeActionReference } from "../_chunks/actions-BuS5jDi0.mjs";
 import { t as getBuildDefaults } from "../_chunks/build-COIcs7wm.mjs";
-import { a as renderServerTree, c as createIsland, d as isolateIslands, f as runtimeTagged, h as withinClientRoot, l as getClientReference, m as setRenderStateResolver, n as PAYLOAD_ONLY_ATTRIBUTE, p as setIslandServerHook, s as IslandsProvider, t as Outlet, u as getContexts } from "../_chunks/tree-opIpaCke.mjs";
+import { a as parseHeldValues, n as addressValues, o as selectValuesToSend, r as escapeScriptJson } from "../_chunks/values-37UIzxM0.mjs";
+import { c as setIslandServerHook, i as getContexts, l as setRenderStateResolver, n as createIsland, o as isolateIslands, r as getClientReference, s as runtimeTagged, t as IslandsProvider, u as withinClientRoot } from "../_chunks/island-DVOr-OUw.mjs";
+import { a as renderServerTree, n as PAYLOAD_ONLY_ATTRIBUTE, t as Outlet } from "../_chunks/tree-C47p6khN.mjs";
 import * as React from "react";
 // src/react/server.ts
 /**

package/dist/react.mjs

@@ -1 +1,3 @@
-export { s as IslandsProvider, t as Outlet, c as createIsland, d as isolateIslands, a as renderServerTree, h as withinClientRoot } from "./_chunks/tree-opIpaCke.mjs";
+import { n as createIsland, o as isolateIslands, t as IslandsProvider, u as withinClientRoot } from "./_chunks/island-DVOr-OUw.mjs";
+import { a as renderServerTree, t as Outlet } from "./_chunks/tree-C47p6khN.mjs";
+export { IslandsProvider, Outlet, createIsland, isolateIslands, renderServerTree, withinClientRoot };

package/dist/server.mjs

@@ -1,4 +1,5 @@
-import { _ as hashValue, a as getActionReference, c as resolveAction, d as generateActionKey, f as sealBound, g as escapeScriptJson, h as addressValues, i as encodeActionReference, l as SealError, m as VALUE_MIN_LENGTH, n as configureActionKeys, o as registerInlineAction, p as unsealBound, r as decodeActionReference, s as registerServerReference, t as bindInlineAction, u as createActionKeys, v as parseHeldValues, y as selectValuesToSend } from "./_chunks/actions-CtLpJPEB.mjs";
+import { a as parseHeldValues, i as hashValue, n as addressValues, o as selectValuesToSend, r as escapeScriptJson, t as VALUE_MIN_LENGTH } from "./_chunks/values-37UIzxM0.mjs";
+import { a as getActionReference, c as resolveAction, d as generateActionKey, f as sealBound, i as encodeActionReference, l as SealError, n as configureActionKeys, o as registerInlineAction, p as unsealBound, r as decodeActionReference, s as registerServerReference, t as bindInlineAction, u as createActionKeys } from "./_chunks/actions-BuS5jDi0.mjs";
 import { a as encode, r as decode } from "./_chunks/codec-C8to-RQW.mjs";
 import { I as readPostedAction, L as stripRuntimeFields, N as attachmentField, n as ACTION_KEY_FIELD, o as BOUND_FIELD, r as ACTION_STALE_HEADER, s as CALL_FIELD, t as ACTION_HEADER } from "./_chunks/wire-QEQWBr5s.mjs";
 import { n as setBuildDefaults, t as getBuildDefaults } from "./_chunks/build-COIcs7wm.mjs";

package/dist/tanstack-start/server.d.mts

@@ -0,0 +1,11 @@
+import { HandlerCallback } from "@tanstack/react-router/ssr/server";
+import { AnyRouter } from "@tanstack/react-router";
+
+// src/tanstack-start/server.d.ts
+
+/**
+ * Renders the page with its islands: values the browser holds stay out, and a navigation (an
+ * `F-Render` request) gets the whole page in one piece, as islx's browser runtime swaps it in.
+ */
+declare const islandsHandler: HandlerCallback<AnyRouter>;
+export { islandsHandler };