@farm.js/islx 0.0.7 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.0.8
+
+Pages load the runtime only when they first need it, and islands that only react to clicks wait
+for one.
+
+- Pages start with a 1.4 KB boot script (`@farm.js/islx/boot`) instead of the browser entry
+  (65.6 KB on the React example). It loads the entry at once when an island hydrates at load (such
+  an island also preloads it), and otherwise on an island's trigger, a click, press or focus on a
+  waiting island, a pointer over a link, or a focus in a form. A link clicked before then is held
+  and followed once navigation runs. `islx({ boot: false })` starts every page with the entry.
+- A `"use client"` module without a `hydrate` export waits for a click when its code, and the app
+  files it imports, provably do nothing before one: no effect, external store or `use()`, no
+  handler but `onClick` and `onSubmit` on its elements, no form field, `ref` or `autoFocus`, no
+  props spread onto an element, and imports only from React, stylesheets and the app. The click is
+  held and replayed once it hydrates. A render that passes such an island `children` hydrates at
+  load. `islx({ infer: false })` keeps every island at load; `inferStrategy` in
+  `@farm.js/islx/compiler` runs the checks for other plugins.
+- A click on a same-page link (`#…`) in an island that has not hydrated is held and replayed, as a
+  button's is, so a table of contents that marks its heading still sees it.
+- Changed defaults: an island whose module declares nothing and passes the checks above now
+  waits for a click. Add `export const hydrate = "load"` to keep one hydrating at load.
+
 ## 0.0.7
 
 Cloudflare Workers start, and sealed captured values name their key with 4 bytes.

package/README.md

@@ -6,14 +6,16 @@ send only what changed.
 
 ```html
 <f-island src="/src/cart.tsx" export="Cart" props="_R_1_" strategy="load">…server HTML…</f-island>
-<script type="f/props" for="_R_1_">{"updated":{"$":"D","v":"2026-10-28T09:00:00.000Z"}}</script>
+<script type="f/props" for="_R_1_">
+  {"updated":{"$":"D","v":"2026-10-28T09:00:00.000Z"}}
+</script>
 ```
 
 islx started as [Farm.js](https://github.com/farming-labs/farm.js)'s islands mode, where it
 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.7. React, Vite and TanStack Start are supported; other renderers and framework
+> Status: 0.0.8. 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).
 
@@ -108,19 +110,36 @@ export async function handle(request: Request) {
 
 async function page(request: Request, formState?) {
   const stream = await renderToStream(<App />, { request, formState });
-  return new Response(stream, { headers: { "content-type": "text/html", "cache-control": "private" } });
+  return new Response(stream, {
+    headers: { "content-type": "text/html", "cache-control": "private" },
+  });
 }
 ```
 
 ```tsx
 // src/components/chart.tsx
 "use client";
-export const hydrate = "visible"; // or { Chart: "visible", Legend: "idle" }; default "load"
+export const hydrate = "visible"; // or { Chart: "visible", Legend: "idle" }; see below
 export function Chart(props: { points: Map<string, number> }) { … }
 ```
 
 - Components are server components unless their module says `"use client"`; those render as
   islands, and the page needs no other setup: `renderToStream` adds the browser entry.
+- A module without a `hydrate` export hydrates at load, unless its code provably does nothing
+  before a click: then it waits for one (`"interaction"`), and the click is held and replayed
+  once it hydrates. That means no effect, external store or `use()`, no handler but `onClick` and
+  `onSubmit` on its elements (a handled link only with a `#` link), no form field, `ref` or
+  `autoFocus`, no props spread onto an element, and imports only from React, stylesheets and the
+  app's own files that pass the same checks: copy buttons, like buttons, menu toggles and tables
+  of contents usually do. A render that gives the island server output (`children`) hydrates at
+  load. `islx({ infer: false })` turns this off; `inferStrategy` in `@farm.js/islx/compiler`
+  runs the same checks for other plugins.
+- Pages start with a 1.4 KB boot script instead of the browser entry. It loads the entry at once
+  when an island hydrates at load (which also preloads it), and otherwise when an island's
+  trigger comes, a waiting island is clicked, pressed or focused, the pointer reaches a link, or
+  a form gets focus. A link clicked before then is held and followed once navigation runs. So a
+  page whose islands all wait loads 1.4 KB of JavaScript until one is used. `islx({ boot: false })`
+  starts every page with the entry.
 - `vite build` builds the server, then the browser with exactly the client components the server
   rendered, each in its own chunk. `islx({ clientComponents: { include, exclude } })` adds
   components the server build cannot see (chosen by name at runtime) or leaves some out.
@@ -142,19 +161,29 @@ export function Chart(props: { points: Map<string, number> }) { … }
     navigation: { viewTransition: true },
     hooks: {
       client: {
-        navigate(event) { if (window.unsaved) event.preventDefault(); },  // stay on the page
-        navigated({ url, duration }) { window.plausible?.("pageview", { u: url.href }); },
-        hydrate({ export: name, duration }) { console.debug(name, "interactive in", duration); },
-        islandError({ src, error }) { console.error(src, error); },
+        navigate(event) {
+          if (window.unsaved) event.preventDefault();
+        }, // stay on the page
+        navigated({ url, duration }) {
+          window.plausible?.("pageview", { u: url.href });
+        },
+        hydrate({ export: name, duration }) {
+          console.debug(name, "interactive in", duration);
+        },
+        islandError({ src, error }) {
+          console.error(src, error);
+        },
         actionEnd({ name, ok, duration }) {},
       },
       server: {
-        async action({ request, name, module }, run) { /* check, log, time */ return run(); },
+        async action({ request, name, module }, run) {
+          /* check, log, time */ return run();
+        },
         actionError: (error) => (error instanceof Unauthorized ? { status: 401 } : undefined),
         error(error, { name }) {},
       },
     },
-  })
+  });
   ```
 
   Callbacks are copied into the browser or server build as source, so they may use only their
@@ -163,6 +192,7 @@ export function Chart(props: { points: Map<string, number> }) { … }
   exporting `defineServerHooks({ … })` (or `defineClientHooks`). Every client hook also fires as a
   DOM event on `document`: `f:navigate`, `f:navigated`, `f:navigate-error`, `f:hydrate`,
   `f:island-error`, `f:action`, `f:action-end`.
+
 - Each build makes its own key for sealed action values; set `ISLX_ACTIONS_KEY` to keep forms
   working across deploys.
 
@@ -209,26 +239,26 @@ unawaited to a client component streams in. Islands call Start server functions
 A framework that renders pages itself (Farm does) uses the pieces directly instead of
 `renderToStream` and the Vite plugin's entry:
 
-| Need | API |
-| --- | --- |
-| Compile client and action modules | `transformClientModule({ …, reference, strategy })`, `transformActions` from `@farm.js/islx/compiler` |
-| Render islands in its own render | wrap the page in `<IslandsProvider held={parseHeldValues(request)}>` |
-| A layout that hydrates as one root | `withinClientRoot(layout)`; its server-HTML page: `isolateIslands(page)` |
-| An async page under such a layout | `renderServerTree(page, { held, payloadOnly })` on the server; `createServerTreeElement(source, { load, ServerHtml })` in the browser |
+| Need                                                                  | API                                                                                                                                                                                                                                     |
+| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Compile client and action modules                                     | `transformClientModule({ …, reference, strategy })`, `transformActions` from `@farm.js/islx/compiler`                                                                                                                                   |
+| Render islands in its own render                                      | wrap the page in `<IslandsProvider held={parseHeldValues(request)}>`                                                                                                                                                                    |
+| A layout that hydrates as one root                                    | `withinClientRoot(layout)`; its server-HTML page: `isolateIslands(page)`                                                                                                                                                                |
+| An async page under such a layout                                     | `renderServerTree(page, { held, payloadOnly })` on the server; `createServerTreeElement(source, { load, ServerHtml })` in the browser                                                                                                   |
 | A server layout around a client provider, without shipping the layout | `renderServerTree(<Layout><Outlet /></Layout>, { outlets: { children: page }, scope })` on the server; `createServerTreeLayout(source, scope, { load, ServerHtml, onUpdate })` in the browser, then `layout.render({ children: page })` |
-| Hydrate | `createHydrationRuntime({ load, schedule?, wrap?, report? })`, `createServerHtml(runtime)` |
-| Hold early clicks | inline `PREHYDRATION_SCRIPT` in the page |
-| Actions | `handleAction(request, { allowedOrigins, bodySizeLimit, run, mapError, renderFormState })`; `setActionNavigator({ refresh, navigate })` |
-| Navigation with its router | send `F-Values` (`valueHeaders()`), `F-Layouts`, `F-Render`; `refreshDocument` / `swapDocument` or its own swap |
+| Hydrate                                                               | `createHydrationRuntime({ load, schedule?, wrap?, report? })`, `createServerHtml(runtime)`                                                                                                                                              |
+| Hold early clicks                                                     | inline `PREHYDRATION_SCRIPT` in the page                                                                                                                                                                                                |
+| Actions                                                               | `handleAction(request, { allowedOrigins, bodySizeLimit, run, mapError, renderFormState })`; `setActionNavigator({ refresh, navigate })`                                                                                                 |
+| Navigation with its router                                            | send `F-Values` (`valueHeaders()`), `F-Layouts`, `F-Render`; `refreshDocument` / `swapDocument` or its own swap                                                                                                                         |
 
 ## Planned
 
-| Entry | For |
-| --- | --- |
-| `@farm.js/islx/react` | server trees (a page rebuilt inside a hydrated layout), partial navigations |
-| `@farm.js/islx/webpack` | webpack, Rspack, and Next.js (Turbopack uses the loader) |
-| `@farm.js/islx/next`, `@farm.js/islx/astro`, `@farm.js/islx/nuxt` | thin framework integrations |
-| `@farm.js/islx/testing` | the conformance suite every integration must pass |
+| Entry                                                             | For                                                                         |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------- |
+| `@farm.js/islx/react`                                             | server trees (a page rebuilt inside a hydrated layout), partial navigations |
+| `@farm.js/islx/webpack`                                           | webpack, Rspack, and Next.js (Turbopack uses the loader)                    |
+| `@farm.js/islx/next`, `@farm.js/islx/astro`, `@farm.js/islx/nuxt` | thin framework integrations                                                 |
+| `@farm.js/islx/testing`                                           | the conformance suite every integration must pass                           |
 
 ## License
 

package/dist/_chunks/{actions-Eutk6UzT.mjs → infer-BIVT5aDz.mjs}

@@ -4,6 +4,7 @@ import { walk } from "estree-walker";
 import isReference from "is-reference";
 import MagicString from "magic-string";
 import { analyze } from "periscopic";
+import fs from "node:fs";
 // src/compiler/actions.ts
 /**
 * The server-action compiler: a pure function from a module's source to its source for the
@@ -323,4 +324,271 @@ function transformActions(options) {
 		})
 	};
 }
-export { transformActions as i, getActionId as n, hasModuleDirective as r, ActionCompileError as t };
+// src/compiler/infer.ts
+/**
+* When an island hydrates if its module sets no `hydrate` export: `"interaction"` when its code
+* provably does nothing before a click, `"load"` otherwise. Such an island renders exactly its
+* server HTML until it is clicked, so it can wait: the scheduler holds that click (or a submit),
+* hydrates the island, and replays it. A press or a focus on the island starts hydrating it early.
+*
+* The checks read the module and the app files it imports. They prove the island can wait when:
+*
+* - it calls no hook that runs code after a render or reads outside React: `useEffect`,
+*   `useLayoutEffect`, `useInsertionEffect`, `useSyncExternalStore`, `useImperativeHandle`, `use`,
+*   `useActionState`, `useOptimistic`, `useFormStatus`, `useDeferredValue`, `useEffectEvent`;
+* - its HTML elements handle only `onClick` and `onSubmit` (a handled link only when its `href` is a
+*   `#` link on the page), and none is a form field, takes a `ref`, `autoFocus`, `contentEditable`,
+*   a form `action` or `formAction`, or props spread onto it;
+* - it declares no class, calls no `createElement`, `cloneElement`, `forwardRef` or `createRef`,
+*   and imports nothing at runtime;
+* - its top level only declares values (`createContext()` and `memo()` included);
+* - it imports only React, stylesheets and assets, and app files that pass the same checks.
+*
+* Anything the checks cannot prove, a package import or a file they cannot read included, keeps
+* `"load"`. Renderer-neutral as a contract: the rules here are React's.
+*/
+const EFFECT_HOOKS = /* @__PURE__ */ new Set([
+	"useEffect",
+	"useLayoutEffect",
+	"useInsertionEffect",
+	"useSyncExternalStore",
+	"useImperativeHandle",
+	"use",
+	"useActionState",
+	"useOptimistic",
+	"useFormStatus",
+	"useDeferredValue",
+	"useEffectEvent"
+]);
+const UNREADABLE_CALLS = /* @__PURE__ */ new Set([
+	"createElement",
+	"cloneElement",
+	"forwardRef",
+	"createRef"
+]);
+const REACT_MODULES = /* @__PURE__ */ new Set([
+	"react",
+	"react/jsx-runtime",
+	"react/jsx-dev-runtime"
+]);
+const HELD_EVENTS = /* @__PURE__ */ new Set(["onClick", "onSubmit"]);
+const FORM_CONTROLS = /* @__PURE__ */ new Set([
+	"input",
+	"textarea",
+	"select"
+]);
+const ASSET_IMPORT = /\.(?:css|scss|sass|less|styl|svg|png|jpe?g|gif|webp|avif|ico|woff2?|ttf|json)(?:\?.*)?$/;
+const EXTENSIONS = [
+	".tsx",
+	".ts",
+	".jsx",
+	".js",
+	".mjs"
+];
+function defaultResolve(specifier, importer) {
+	if (!specifier.startsWith(".")) return null;
+	const base = path.resolve(path.dirname(importer), specifier);
+	for (const candidate of [
+		base,
+		...EXTENSIONS.map((extension) => base + extension),
+		...EXTENSIONS.map((extension) => path.join(base, `index${extension}`))
+	]) try {
+		if (fs.statSync(candidate).isFile()) return candidate;
+	} catch {}
+	return null;
+}
+/** Infers when the islands `file` exports hydrate; `code` is its source. */
+function inferStrategy(file, code, options) {
+	const resolve = options.resolve ?? defaultResolve;
+	const files = [];
+	const seen = /* @__PURE__ */ new Set();
+	const queue = [{
+		file,
+		code
+	}];
+	while (queue.length > 0) {
+		const next = queue.shift();
+		if (seen.has(next.file)) continue;
+		seen.add(next.file);
+		files.push(next.file);
+		let source = next.code;
+		if (source === null) try {
+			source = fs.readFileSync(next.file, "utf8");
+		} catch {
+			return {
+				strategy: null,
+				files,
+				reason: `${path.basename(next.file)} could not be read`
+			};
+		}
+		const imports = [];
+		const reason = inspect(next.file, source, options.parse, (specifier) => {
+			if (REACT_MODULES.has(specifier) || ASSET_IMPORT.test(specifier)) return null;
+			const resolved = resolve(specifier, next.file);
+			if (!resolved || resolved.includes(`${path.sep}node_modules${path.sep}`)) return `imports ${specifier}`;
+			imports.push(resolved);
+			return null;
+		});
+		if (reason) return {
+			strategy: null,
+			files,
+			reason: `${path.basename(next.file)}: ${reason}`
+		};
+		for (const imported of imports) queue.push({
+			file: imported,
+			code: null
+		});
+	}
+	return {
+		strategy: "interaction",
+		files
+	};
+}
+function inspect(file, source, parse, importSource) {
+	let program;
+	try {
+		program = parse(file, source);
+	} catch {
+		return "could not be parsed";
+	}
+	for (const statement of program.body ?? []) {
+		const problem = topLevelProblem(statement, importSource);
+		if (problem) return problem;
+	}
+	return findProblem(program);
+}
+function isTypeOnly(node) {
+	if (node.importKind === "type" || node.exportKind === "type") return true;
+	const specifiers = node.specifiers ?? [];
+	return specifiers.length > 0 && specifiers.every((specifier) => specifier.importKind === "type");
+}
+/** What a top-level statement does as the module loads, which waiting would delay. */
+function topLevelProblem(statement, importSource) {
+	switch (statement.type) {
+		case "ImportDeclaration": return isTypeOnly(statement) ? null : importSource(statement.source.value);
+		case "ExportAllDeclaration": return statement.exportKind === "type" ? null : importSource(statement.source.value);
+		case "ExportNamedDeclaration":
+			if (statement.source) return isTypeOnly(statement) ? null : importSource(statement.source.value);
+			return statement.declaration ? topLevelProblem(statement.declaration, importSource) : null;
+		case "ExportDefaultDeclaration": return statement.declaration.type === "FunctionDeclaration" || String(statement.declaration.type).startsWith("TS") ? null : pureValueProblem(statement.declaration);
+		case "ExpressionStatement": return typeof statement.directive === "string" ? null : "runs code as it loads";
+		case "VariableDeclaration":
+			for (const declarator of statement.declarations ?? []) {
+				const problem = declarator.init ? pureValueProblem(declarator.init) : null;
+				if (problem) return problem;
+			}
+			return null;
+		case "FunctionDeclaration":
+		case "EmptyStatement": return null;
+		case "ClassDeclaration": return "declares a class";
+		default: return String(statement.type).startsWith("TS") ? null : `has a top-level ${statement.type}`;
+	}
+}
+/** Whether evaluating `node` at the top level does anything but build a value. */
+function pureValueProblem(node) {
+	switch (node.type) {
+		case "Literal":
+		case "Identifier":
+		case "ArrowFunctionExpression":
+		case "FunctionExpression":
+		case "MemberExpression": return null;
+		case "TemplateLiteral": return firstProblem(node.expressions, pureValueProblem);
+		case "ArrayExpression": return firstProblem(node.elements.filter(Boolean), pureValueProblem);
+		case "ObjectExpression": return firstProblem(node.properties, (property) => property.type === "SpreadElement" ? pureValueProblem(property.argument) : property.computed ? "has a computed key" : pureValueProblem(property.value));
+		case "UnaryExpression":
+		case "SpreadElement": return pureValueProblem(node.argument);
+		case "BinaryExpression":
+		case "LogicalExpression": return pureValueProblem(node.left) ?? pureValueProblem(node.right);
+		case "ConditionalExpression": return pureValueProblem(node.test) ?? pureValueProblem(node.consequent) ?? pureValueProblem(node.alternate);
+		case "CallExpression": {
+			const name = memberCallName(node.callee);
+			if (name === "createContext" || name === "memo" || name === "Object.freeze") return firstProblem(node.arguments, pureValueProblem);
+			return "runs code as it loads";
+		}
+		default: return String(node.type).startsWith("TS") && node.expression ? pureValueProblem(node.expression) : `evaluates a ${node.type} as it loads`;
+	}
+}
+function firstProblem(items, check) {
+	for (const item of items) {
+		const problem = check(item);
+		if (problem) return problem;
+	}
+	return null;
+}
+function memberCallName(callee) {
+	if (callee.type === "Identifier") return callee.name;
+	if (callee.type === "MemberExpression" && !callee.computed && callee.property.type === "Identifier") return callee.object.type === "Identifier" && callee.object.name === "Object" ? `Object.${callee.property.name}` : callee.property.name;
+	return null;
+}
+/** A call to one of React's functions: `name()` or `React.name()`, not `document.name()`. */
+function reactCallName(callee) {
+	if (callee.type === "Identifier") return callee.name;
+	if (callee.type === "MemberExpression" && !callee.computed && callee.object.type === "Identifier" && callee.object.name === "React" && callee.property.type === "Identifier") return callee.property.name;
+	return null;
+}
+function isHashHref(value) {
+	if (!value) return false;
+	if (value.type === "Literal") return typeof value.value === "string" && value.value.startsWith("#");
+	if (value.type !== "JSXExpressionContainer") return false;
+	const expression = value.expression;
+	if (expression.type === "Literal") return typeof expression.value === "string" && expression.value.startsWith("#");
+	return expression.type === "TemplateLiteral" && String(expression.quasis[0]?.value?.cooked ?? "").startsWith("#");
+}
+/** What an HTML element does that an island waiting for a click would get wrong. */
+function hostElementProblem(element) {
+	if (element.name.type !== "JSXIdentifier") return null;
+	const tag = element.name.name;
+	if (!/^[a-z]/.test(tag)) return null;
+	if (FORM_CONTROLS.has(tag)) return `renders <${tag}>`;
+	let href;
+	let clicks = false;
+	for (const attribute of element.attributes ?? []) {
+		if (attribute.type === "JSXSpreadAttribute") return `spreads props onto <${tag}>`;
+		const name = attribute.name?.type === "JSXIdentifier" ? attribute.name.name : null;
+		if (name === null) continue;
+		if (name === "ref") return `sets a ref on <${tag}>`;
+		if (name === "autoFocus") return `sets autoFocus on <${tag}>`;
+		if (name === "contentEditable") return `makes <${tag}> editable`;
+		if (tag === "form" && name === "action") return "gives a form an action";
+		if (name === "formAction") return `sets formAction on <${tag}>`;
+		if (name === "href") href = attribute.value;
+		if (/^on[A-Z]/.test(name)) {
+			if (!HELD_EVENTS.has(name)) return `handles ${name}`;
+			if (name === "onClick") clicks = true;
+		}
+	}
+	if (tag === "a" && clicks && !isHashHref(href)) return "handles a click on a link";
+	return null;
+}
+function findProblem(node) {
+	switch (node.type) {
+		case "CallExpression": {
+			const name = reactCallName(node.callee);
+			if (name && (EFFECT_HOOKS.has(name) || UNREADABLE_CALLS.has(name))) return `calls ${name}`;
+			break;
+		}
+		case "JSXOpeningElement": {
+			const problem = hostElementProblem(node);
+			if (problem) return problem;
+			break;
+		}
+		case "ClassDeclaration":
+		case "ClassExpression": return "declares a class";
+		case "ImportExpression": return "imports a module at runtime";
+	}
+	for (const key of Object.keys(node)) {
+		if (key === "start" || key === "end" || key === "range" || key === "loc") continue;
+		const value = node[key];
+		if (Array.isArray(value)) {
+			for (const child of value) if (child && typeof child.type === "string") {
+				const problem = findProblem(child);
+				if (problem) return problem;
+			}
+		} else if (value && typeof value === "object" && typeof value.type === "string") {
+			const problem = findProblem(value);
+			if (problem) return problem;
+		}
+	}
+	return null;
+}
+export { transformActions as a, hasModuleDirective as i, ActionCompileError as n, getActionId as r, inferStrategy as t };

package/dist/_chunks/{island-DVOr-OUw.mjs → island-DXAGP4FN.mjs}

@@ -204,7 +204,7 @@ function isThenable(value) {
 * 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 createIsland(Component, src, exportName, declared = "load", options = {}) {
 	function Island(props) {
 		const { graph, render } = getContexts();
 		const insideIsland = React.useContext(graph);
@@ -215,9 +215,12 @@ function createIsland(Component, src, exportName, strategy = "load") {
 		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;
+		let strategy = declared;
 		try {
-			const { render: rendered, wire } = splitSlots(props, `${id}s`, { next: 0 });
+			const slots = { next: 0 };
+			const { render: rendered, wire } = splitSlots(props, `${id}s`, slots);
 			renderProps = rendered;
+			if (options.inferred && slots.next > 0) strategy = "load";
 			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);
@@ -231,7 +234,11 @@ function createIsland(Component, src, exportName, strategy = "load") {
 			}
 			return React.createElement(Component, props);
 		}
-		if (strategy === "load") for (const href of getBuildDefaults().modules?.[src] ?? []) ReactDOM.preloadModule?.(href, { as: "script" });
+		if (strategy === "load") {
+			const defaults = getBuildDefaults();
+			if (defaults.boot && defaults.entry) ReactDOM.preloadModule?.(defaults.entry, { as: "script" });
+			for (const href of defaults.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,

package/dist/_chunks/{prehydration-B1GLTLdk.mjs → prehydration-zEYsfFxW.mjs}

@@ -1,7 +1,8 @@
 // src/client/prehydration.ts
 /**
 * Holding interactions that happen before the islx script has run. An inline script in the page
-* captures a click or a submit on an island that has not hydrated (it is prevented and queued),
+* captures a click or a submit on an island that has not hydrated (it is prevented and queued; a
+* click on a link only when the link stays on the page, `#…`),
 * and announces a pointerdown or a focus (which go through). The runtime then hydrates those
 * islands first and replays what was held.
 *
@@ -14,7 +15,7 @@ const INTERACTION_EVENT = "f:island-interaction";
 /** Elements whose click is held and replayed rather than merely observed. */
 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. */
-const PREHYDRATION_SCRIPT = `(function(){if(window.${PENDING_INTERACTIONS})return;var q=window.${PENDING_INTERACTIONS}=[];function island(n){var i=n&&n.closest&&n.closest("f-island");return i&&!i.hasAttribute("hydrated")?i:null}function tell(t,k){document.dispatchEvent(new CustomEvent("${INTERACTION_EVENT}",{detail:{target:t,kind:k}}))}function hold(e,t,k){if(!q.some(function(p){return p.target===t})){q.push({target:t,kind:k});tell(t,k)}e.preventDefault();e.stopImmediatePropagation()}document.addEventListener("click",function(e){if(e.defaultPrevented||e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;var t=e.target&&e.target.closest&&e.target.closest(${JSON.stringify(REPLAYABLE_SELECTOR)});if(!t||t.closest("a[href]")||!island(t))return;hold(e,t,"click")},true);document.addEventListener("submit",function(e){var f=e.target;if(e.defaultPrevented||!f||f.nodeName!=="FORM"||!island(f))return;hold(e,f,"submit")},true);function seen(e){if(island(e.target))tell(e.target,null)}document.addEventListener("pointerdown",seen,true);document.addEventListener("focusin",seen,true)})();`;
+const PREHYDRATION_SCRIPT = `(function(){if(window.${PENDING_INTERACTIONS})return;var q=window.${PENDING_INTERACTIONS}=[];function island(n){var i=n&&n.closest&&n.closest("f-island");return i&&!i.hasAttribute("hydrated")?i:null}function tell(t,k){document.dispatchEvent(new CustomEvent("${INTERACTION_EVENT}",{detail:{target:t,kind:k}}))}function hold(e,t,k){if(!q.some(function(p){return p.target===t})){q.push({target:t,kind:k});tell(t,k)}e.preventDefault();e.stopImmediatePropagation()}document.addEventListener("click",function(e){if(e.defaultPrevented||e.button!==0||e.metaKey||e.altKey||e.ctrlKey||e.shiftKey)return;var n=e.target&&e.target.closest?e.target:null,a=n&&n.closest("a[href]"),t=a?(a.getAttribute("href").charAt(0)==="#"?a:null):n&&n.closest(${JSON.stringify(REPLAYABLE_SELECTOR)});if(!t||!island(t))return;hold(e,t,"click")},true);document.addEventListener("submit",function(e){var f=e.target;if(e.defaultPrevented||!f||f.nodeName!=="FORM"||!island(f))return;hold(e,f,"submit")},true);function seen(e){if(island(e.target))tell(e.target,null)}document.addEventListener("pointerdown",seen,true);document.addEventListener("focusin",seen,true)})();`;
 /** Takes the interactions the inline script held inside `container`, oldest first. */
 function takePendingInteractions(container) {
 	const queue = globalThis[PENDING_INTERACTIONS];

package/dist/_chunks/{schedule-CjoybS3b.mjs → schedule-Cwn9vQL0.mjs}

@@ -1,4 +1,4 @@
-import { a as hasPendingInteraction, o as takePendingInteractions, t as INTERACTION_EVENT } from "./prehydration-B1GLTLdk.mjs";
+import { a as hasPendingInteraction, o as takePendingInteractions, t as INTERACTION_EVENT } from "./prehydration-zEYsfFxW.mjs";
 import { m as HYDRATED_ATTRIBUTE } from "./wire-QEQWBr5s.mjs";
 // src/client/schedule.ts
 /**
@@ -24,6 +24,15 @@ function isIslandStrategy(value) {
 }
 /** Elements whose click is held and replayed rather than merely observed. */
 const REPLAYABLE = "button,[role=\"button\"],input[type=\"button\"],input[type=\"submit\"],input[type=\"reset\"]";
+/**
+* The element a click before hydration is held on: a control, or a same-page link, whose handler
+* the island may need (a table of contents marking its heading). Any other link navigates.
+*/
+function heldTarget(target) {
+	const link = target.closest("a[href]");
+	if (link) return link.getAttribute("href")?.startsWith("#") ? link : null;
+	return target.closest(REPLAYABLE);
+}
 function whenIdle(callback) {
 	const scope = window;
 	if (typeof scope.requestIdleCallback === "function") {
@@ -190,8 +199,8 @@ function scheduleHydration({ container, strategy, signal, hydrate }) {
 		};
 		const onClick = (event) => {
 			const mouse = event;
-			const target = event.target instanceof Element ? event.target.closest(REPLAYABLE) : null;
-			if (!target || !container.contains(target) || target.closest("a[href]") || mouse.button !== 0 || mouse.metaKey || mouse.altKey || mouse.ctrlKey || mouse.shiftKey) return;
+			const target = event.target instanceof Element ? heldTarget(event.target) : null;
+			if (!target || !container.contains(target) || mouse.button !== 0 || mouse.metaKey || mouse.altKey || mouse.ctrlKey || mouse.shiftKey) return;
 			hold(event, target, "click");
 		};
 		const onSubmit = (event) => {

package/dist/_chunks/{tree-C47p6khN.mjs → tree-BQphP23Y.mjs}

@@ -1,7 +1,7 @@
 import { i as decodeTagged, n as NOT_A_VALUE, o as encodeLeaf } from "./codec-C8to-RQW.mjs";
 import { M as VALUE_SCRIPT_TYPE, c as CHUNK_SCRIPT_TYPE, k as TREE_SCRIPT_TYPE, p as HTML_ELEMENT } from "./wire-QEQWBr5s.mjs";
 import { t as createServerReference, u as getValueStore } from "./actions-C-IwUCKU.mjs";
-import { a as getIslandServerHook, o as isolateIslands, r as getClientReference } from "./island-DVOr-OUw.mjs";
+import { a as getIslandServerHook, o as isolateIslands, r as getClientReference } from "./island-DXAGP4FN.mjs";
 import * as React from "react";
 // src/react/tree.ts
 /**

package/dist/_chunks/{tree-B4RMU2UX.d.mts → tree-CV13RsJv.d.mts}

@@ -52,7 +52,14 @@ interface IslandRenderState {
  * 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.
  */
-declare function createIsland<P extends object>(Component: React.ComponentType<P>, src: string, exportName: string, strategy?: IslandStrategy): React.ComponentType<P>;
+declare function createIsland<P extends object>(Component: React.ComponentType<P>, src: string, exportName: string, declared?: IslandStrategy,
+/**
+ * `inferred`: the compiler inferred `declared` (`"interaction"`). A render that passes the island
+ * server output hydrates at load instead: islands inside that output would wait with it.
+ */
+options?: {
+  inferred?: boolean;
+}): React.ComponentType<P>;
 /**
  * Marks a navigation response that carries only the page's payload. The browser rebuilds such a
  * page in its layout's React root and never shows its HTML, so the server leaves the HTML out.

package/dist/_chunks/{vite-BTzYlEiY.mjs → vite-0bH_ZDys.mjs}

@@ -1,5 +1,5 @@
-import { i as transformActions, r as hasModuleDirective, t as ActionCompileError } from "./actions-Eutk6UzT.mjs";
-import { t as ISLAND_STRATEGIES } from "./schedule-CjoybS3b.mjs";
+import { a as transformActions, i as hasModuleDirective, n as ActionCompileError, t as inferStrategy } from "./infer-BIVT5aDz.mjs";
+import { t as ISLAND_STRATEGIES } from "./schedule-Cwn9vQL0.mjs";
 import { randomBytes } from "node:crypto";
 import path from "node:path";
 import { walk } from "estree-walker";
@@ -78,10 +78,12 @@ function transformClientModule(options) {
 		throw new ActionCompileError(message, file, code, node.start);
 	};
 	const strategies = readStrategies(program, fail);
+	const inference = options.infer && strategies.all === void 0 && strategies.byName.size === 0 ? inferStrategy(file, code, options.infer) : void 0;
+	const inferred = (name) => options.strategy?.(name) === void 0 && inference?.strategy === "interaction";
 	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";
+		return configured ?? strategies.byName.get(name) ?? strategies.all ?? (inference?.strategy === "interaction" ? "interaction" : "load");
 	};
 	const output = new MagicString(code);
 	const wrapped = [];
@@ -140,7 +142,9 @@ function transformClientModule(options) {
 	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))});`;
+		const strategy = JSON.stringify(strategyOf(exportName));
+		const flags = inferred(exportName) ? ", { inferred: true }" : "";
+		return `const $$islx_island_${index} = $$islx_island(${local}, ${src}, ${JSON.stringify(exportName)}, ${strategy}${flags});`;
 	}), `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`);
@@ -154,7 +158,8 @@ function transformClientModule(options) {
 		islands: wrapped.map(({ exportName }) => ({
 			exportName,
 			strategy: strategyOf(exportName)
-		}))
+		})),
+		...inference ? { inference } : {}
 	};
 }
 // src/vite.ts
@@ -177,6 +182,8 @@ function transformClientModule(options) {
 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";
+/** The boot entry: pages start with it, and it loads ENTRY_ID when the page first needs it. */
+const BOOT_ID = "virtual:islx/boot";
 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";
@@ -244,6 +251,7 @@ function serializeHooks(hooks, where, parse) {
 * build until the browser build names them. */
 const ENTRY_PLACEHOLDER = "__islx_client_entry_url__";
 const MODULES_PLACEHOLDER = "__islx_client_modules__";
+const BOOT_PLACEHOLDER = "__islx_boot_url__";
 const SCRIPT = /\.[cm]?[jt]sx?$/;
 async function createParser() {
 	const withErrors = (result) => Object.assign(result.program, { errors: result.errors ?? [] });
@@ -315,6 +323,7 @@ function islx(options = {}, host = {}) {
 	const discovered = /* @__PURE__ */ new Set();
 	/** The browser entry's URL, once the browser build named it. */
 	let entryUrl;
+	let bootUrl;
 	/** 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). */
@@ -355,7 +364,8 @@ function islx(options = {}, host = {}) {
 							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
+								"islx-entry": ENTRY_ID,
+								...options.boot === false ? {} : { "islx-boot": BOOT_ID }
 							} }
 						}
 					} }
@@ -368,17 +378,18 @@ function islx(options = {}, host = {}) {
 			},
 			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}`;
+				if (id === RUNTIME_ID || id === "virtual:islx/client-entry" || id === "virtual:islx/boot" || 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 boot = host.frameworkEntry || options.boot === false ? void 0 : !isBuild() ? `${config.base}@id/__x00__${BOOT_ID}` : clientBuilt ? bootUrl : BOOT_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} });`,
+						`setBuildDefaults({ entry: ${JSON.stringify(entry)}, boot: ${JSON.stringify(boot)}, key: ${JSON.stringify(buildKey)}, modules: ${modules} });`,
 						`setServerHooks(hooks);`
 					].join("\n");
 				}
@@ -389,6 +400,7 @@ function islx(options = {}, host = {}) {
 					if (typeof hooks === "string") return `export { default } from ${JSON.stringify(path.resolve(config.root, hooks))};`;
 					return serializeHooks(hooks, where, parse);
 				}
+				if (id === `\0virtual:islx/boot`) return `import { startBoot } from "@farm.js/islx/boot";\nstartBoot();\n`;
 				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 [
@@ -428,8 +440,10 @@ function islx(options = {}, host = {}) {
 						},
 						sideEffects: [RUNTIME_ID],
 						directive: clientDirective,
-						...library ? { runtime: LIBRARY_RUNTIME_ID } : {}
+						...library ? { runtime: LIBRARY_RUNTIME_ID } : {},
+						...options.infer !== false && !library ? { infer: { parse } } : {}
 					});
+					for (const read of island?.inference?.files ?? []) if (read !== file) this.addWatchFile(read);
 					if (island) {
 						if (!library) transformActions({
 							code,
@@ -484,9 +498,9 @@ function islx(options = {}, host = {}) {
 					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;
+						if (!source.includes(ENTRY_PLACEHOLDER) && !source.includes(MODULES_PLACEHOLDER) && !source.includes(BOOT_PLACEHOLDER)) continue;
 						const modules = JSON.stringify(JSON.stringify(moduleFiles)).slice(1, -1);
-						await writeFile(file, source.replaceAll(ENTRY_PLACEHOLDER, entryUrl).replaceAll(MODULES_PLACEHOLDER, modules));
+						await writeFile(file, source.replaceAll(ENTRY_PLACEHOLDER, entryUrl).replaceAll(MODULES_PLACEHOLDER, modules).replaceAll(BOOT_PLACEHOLDER, bootUrl ?? ""));
 					}
 				}
 			},
@@ -496,6 +510,7 @@ function islx(options = {}, host = {}) {
 				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.isEntry && chunk.facadeModuleId === `\0virtual:islx/boot`) bootUrl = url(chunk.fileName);
 					else if (chunk.isDynamicEntry && !chunk.facadeModuleId.startsWith("\0")) moduleFiles[relativeOf(chunk.facadeModuleId)] = [chunk.fileName, ...chunk.imports].map(url);
 				}
 				clientBuilt = true;
@@ -503,4 +518,4 @@ function islx(options = {}, host = {}) {
 		}
 	];
 }
-export { serializeHooks as i, islx as n, resolveDirectives as r, ENTRY_ID as t };
+export { serializeHooks as a, resolveDirectives as i, ENTRY_ID as n, islx as r, BOOT_ID as t };

package/dist/boot.d.mts

@@ -0,0 +1,31 @@
+/**
+ * @farm.js/islx/boot: the first script of a page, in place of the browser entry. It loads the entry
+ * (the runtime: the renderer, islx's hydration, navigation and forms) when the page first needs
+ * it, so a page whose islands all wait loads only this script until one is used:
+ *
+ * - at once, when an island hydrates at load (`strategy="load"`, also one that streams in later)
+ *   or a Suspense boundary is left for the browser to finish;
+ * - otherwise on the first island trigger (`idle`; `visible`, with the scheduler's 200px margin;
+ *   an interaction the inline pre-hydration script saw) or on intent to follow a link (a pointer
+ *   over it, a press, a focus), or a focus in a form.
+ *
+ * The inline pre-hydration script holds the clicks and submits on waiting islands until then. A
+ * same-site link clicked before the entry has run is held too, and clicked again once it has, so
+ * navigation decides as for any click; if the entry fails to load, the link navigates natively.
+ *
+ * Renderer-neutral, and it imports nothing: a module it shared with the entry would change how the
+ * entry splits into chunks. The server names the entry in `window.__islxRuntime`.
+ */
+/** Kept equal to the island element (protocol/wire.ts); a test compares them. */
+declare const BOOT_ISLAND_ELEMENT = "f-island";
+/** Kept equal to HYDRATED_ATTRIBUTE (protocol/wire.ts). */
+declare const BOOT_HYDRATED_ATTRIBUTE = "hydrated";
+/** Kept equal to INTERACTION_EVENT (client/prehydration.ts). */
+declare const BOOT_INTERACTION_EVENT = "f:island-interaction";
+/** Kept equal to the scheduler's visibility margin (client/schedule.ts). */
+declare const BOOT_VISIBLE_MARGIN = "200px";
+/** Where the server names the browser entry for the boot. */
+declare const RUNTIME_GLOBAL = "__islxRuntime";
+/** Starts the runtime when the page first needs it. `load` runs it; it starts as it runs. */
+declare function startBoot(load?: () => Promise<unknown>): void;
+export { BOOT_HYDRATED_ATTRIBUTE, BOOT_INTERACTION_EVENT, BOOT_ISLAND_ELEMENT, BOOT_VISIBLE_MARGIN, RUNTIME_GLOBAL, startBoot };

package/dist/boot.mjs

@@ -0,0 +1,177 @@
+// src/boot.ts
+/**
+* @farm.js/islx/boot: the first script of a page, in place of the browser entry. It loads the entry
+* (the runtime: the renderer, islx's hydration, navigation and forms) when the page first needs
+* it, so a page whose islands all wait loads only this script until one is used:
+*
+* - at once, when an island hydrates at load (`strategy="load"`, also one that streams in later)
+*   or a Suspense boundary is left for the browser to finish;
+* - otherwise on the first island trigger (`idle`; `visible`, with the scheduler's 200px margin;
+*   an interaction the inline pre-hydration script saw) or on intent to follow a link (a pointer
+*   over it, a press, a focus), or a focus in a form.
+*
+* The inline pre-hydration script holds the clicks and submits on waiting islands until then. A
+* same-site link clicked before the entry has run is held too, and clicked again once it has, so
+* navigation decides as for any click; if the entry fails to load, the link navigates natively.
+*
+* Renderer-neutral, and it imports nothing: a module it shared with the entry would change how the
+* entry splits into chunks. The server names the entry in `window.__islxRuntime`.
+*/
+/** Kept equal to the island element (protocol/wire.ts); a test compares them. */
+const BOOT_ISLAND_ELEMENT = "f-island";
+/** Kept equal to HYDRATED_ATTRIBUTE (protocol/wire.ts). */
+const BOOT_HYDRATED_ATTRIBUTE = "hydrated";
+/** Kept equal to INTERACTION_EVENT (client/prehydration.ts). */
+const BOOT_INTERACTION_EVENT = "f:island-interaction";
+/** Kept equal to the scheduler's visibility margin (client/schedule.ts). */
+const BOOT_VISIBLE_MARGIN = "200px";
+/** Where the server names the browser entry for the boot. */
+const RUNTIME_GLOBAL = "__islxRuntime";
+function isModified(event) {
+	return event.metaKey || event.altKey || event.ctrlKey || event.shiftKey;
+}
+/** A link islx navigation takes: the same checks as its click handler. */
+function navigableLink(target) {
+	const link = target instanceof Element ? target.closest("a[href]") : null;
+	if (!(link instanceof HTMLAnchorElement)) return null;
+	if (link.target && link.target !== "_self") return null;
+	if (link.hasAttribute("download") || link.relList.contains("external")) return null;
+	const url = new URL(link.href);
+	if (url.origin !== location.origin || !/^https?:$/.test(url.protocol)) return null;
+	if (url.pathname === location.pathname && url.search === location.search && url.hash) return null;
+	return link;
+}
+/** Runs the browser entry the server named, as a module script: the same URL, so the same module. */
+function loadRuntime() {
+	const src = window[RUNTIME_GLOBAL];
+	if (typeof src !== "string" || src === "") return Promise.reject(/* @__PURE__ */ new Error(`islx: the page names no browser entry (${RUNTIME_GLOBAL}).`));
+	return new Promise((resolve, reject) => {
+		const script = document.createElement("script");
+		script.type = "module";
+		script.src = src;
+		const nonce = document.querySelector("script[nonce]")?.nonce;
+		if (nonce) script.nonce = nonce;
+		script.addEventListener("load", () => resolve(), { once: true });
+		script.addEventListener("error", () => reject(/* @__PURE__ */ new Error(`islx: ${src} failed to load.`)), { once: true });
+		document.head.append(script);
+	});
+}
+/** Starts the runtime when the page first needs it. `load` runs it; it starts as it runs. */
+function startBoot(load = loadRuntime) {
+	const cleanups = [];
+	let loading;
+	const release = () => {
+		for (const cleanup of cleanups.splice(0)) cleanup();
+	};
+	const start = () => {
+		if (!loading) {
+			loading = load().then(release, (error) => {
+				release();
+				throw error;
+			});
+			loading.catch((error) => console.error(error));
+		}
+		return loading;
+	};
+	const listen = (type, handler, capture) => {
+		document.addEventListener(type, handler, capture);
+		cleanups.push(() => document.removeEventListener(type, handler, capture));
+	};
+	listen(BOOT_INTERACTION_EVENT, () => void start(), false);
+	const intent = (event) => {
+		if (navigableLink(event.target)) start();
+		else if (event.type !== "mouseover" && event.target?.closest?.("form")) start();
+	};
+	for (const type of [
+		"pointerdown",
+		"focusin",
+		"mouseover"
+	]) listen(type, intent, true);
+	listen("click", (event) => {
+		const click = event;
+		if (click.defaultPrevented || click.button !== 0 || isModified(click)) return;
+		const link = navigableLink(click.target);
+		if (!link) return;
+		click.preventDefault();
+		start().then(() => {
+			if (link.isConnected) link.dispatchEvent(new MouseEvent("click", {
+				bubbles: true,
+				cancelable: true
+			}));
+			else location.assign(link.href);
+		}, () => location.assign(link.href));
+	}, false);
+	const visibility = typeof IntersectionObserver === "function" ? new IntersectionObserver((entries) => {
+		if (entries.some((entry) => entry.isIntersecting)) start();
+	}, { rootMargin: BOOT_VISIBLE_MARGIN }) : null;
+	if (visibility) cleanups.push(() => visibility.disconnect());
+	let idle = false;
+	const startWhenIdle = () => {
+		if (idle) return;
+		idle = true;
+		const scope = window;
+		if (typeof scope.requestIdleCallback === "function") {
+			const handle = scope.requestIdleCallback(() => void start(), { timeout: 2e3 });
+			cleanups.push(() => scope.cancelIdleCallback?.(handle));
+		} else {
+			const handle = window.setTimeout(() => void start(), 1);
+			cleanups.push(() => window.clearTimeout(handle));
+		}
+	};
+	const parsedVisible = [];
+	const observeVisible = (island) => {
+		const targets = island.getClientRects().length > 0 ? [island] : Array.from(island.children);
+		if (!visibility || targets.length === 0) start();
+		else for (const target of targets) visibility.observe(target);
+	};
+	const considerIsland = (island) => {
+		if (island.hasAttribute("hydrated")) return;
+		if (island.parentElement?.closest("f-island")) return;
+		const strategy = island.getAttribute("strategy");
+		if (strategy === "interaction") return;
+		if (strategy === "idle") startWhenIdle();
+		else if (strategy !== "visible") start();
+		else if (document.readyState === "loading") parsedVisible.push(island);
+		else observeVisible(island);
+	};
+	const consider = (node) => {
+		if (loading) return;
+		if (node.nodeType === Node.COMMENT_NODE) {
+			if (node.data === "$!") start();
+		} else if (node instanceof Element) {
+			if (node.matches("f-island")) considerIsland(node);
+			for (const island of Array.from(node.querySelectorAll(BOOT_ISLAND_ELEMENT))) considerIsland(island);
+		}
+	};
+	const pendingBoundary = () => {
+		const walker = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
+		while (walker.nextNode()) if (walker.currentNode.data === "$?") return true;
+		return false;
+	};
+	const walker = document.createTreeWalker(document, NodeFilter.SHOW_COMMENT);
+	while (!loading && walker.nextNode()) consider(walker.currentNode);
+	consider(document.documentElement);
+	const parsed = () => {
+		if (pendingBoundary()) start();
+		for (const island of parsedVisible.splice(0)) if (!loading) observeVisible(island);
+	};
+	if (!loading && document.readyState === "loading") {
+		const observer = new MutationObserver((records) => {
+			for (const record of records) for (const node of Array.from(record.addedNodes)) consider(node);
+		});
+		observer.observe(document, {
+			childList: true,
+			subtree: true
+		});
+		const done = () => {
+			observer.disconnect();
+			parsed();
+		};
+		document.addEventListener("DOMContentLoaded", done, { once: true });
+		cleanups.push(() => {
+			observer.disconnect();
+			document.removeEventListener("DOMContentLoaded", done);
+		});
+	} else if (!loading) parsed();
+}
+export { BOOT_HYDRATED_ATTRIBUTE, BOOT_INTERACTION_EVENT, BOOT_ISLAND_ELEMENT, BOOT_VISIBLE_MARGIN, RUNTIME_GLOBAL, startBoot };

package/dist/client.d.mts

@@ -57,7 +57,8 @@ declare function startNavigation(options: NavigationOptions): {
 declare function navigate(href: string, options?: NavigateOptions): Promise<void>;
 /**
  * Holding interactions that happen before the islx script has run. An inline script in the page
- * captures a click or a submit on an island that has not hydrated (it is prevented and queued),
+ * captures a click or a submit on an island that has not hydrated (it is prevented and queued; a
+ * click on a link only when the link stays on the page, `#…`),
  * and announces a pointerdown or a focus (which go through). The runtime then hydrates those
  * islands first and replays what was held.
  *

package/dist/client.mjs

@@ -1,6 +1,6 @@
 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";
+import { i as REPLAYABLE_SELECTOR, n as PENDING_INTERACTIONS, r as PREHYDRATION_SCRIPT, t as INTERACTION_EVENT } from "./_chunks/prehydration-zEYsfFxW.mjs";
 // src/client/forms.ts
 /**
 * Forms written in server components submit without reloading the page once JavaScript runs.

package/dist/compiler.d.mts

@@ -1,2 +1,24 @@
 import { a as getActionId, i as TransformActionsResult, n as AstNode, o as hasModuleDirective, r as TransformActionsOptions, s as transformActions, t as ActionCompileError } from "./_chunks/actions-BCtIGvrP.mjs";
-export { ActionCompileError, type AstNode, type TransformActionsOptions, type TransformActionsResult, getActionId, hasModuleDirective, transformActions };
+
+// src/compiler/infer.d.ts
+interface InferOptions {
+  /** Parses a module's source (TypeScript and JSX included) to an ESTree program. */
+  parse(file: string, code: string): AstNode;
+  /**
+   * Resolves an import to a source file of the app's own, or null for a package or anything
+   * unknown (which keeps `"load"`). Default: relative and root-absolute paths, with the usual
+   * extensions and index files.
+   */
+  resolve?(specifier: string, importer: string): string | null;
+}
+interface Inference {
+  /** `"interaction"` when the islands can wait; null to keep `"load"`. */
+  strategy: "interaction" | null;
+  /** The source files the result read, the module itself first. */
+  files: string[];
+  /** Why the islands keep `"load"`. */
+  reason?: string;
+}
+/** Infers when the islands `file` exports hydrate; `code` is its source. */
+declare function inferStrategy(file: string, code: string, options: InferOptions): Inference;
+export { ActionCompileError, type AstNode, type InferOptions, type Inference, type TransformActionsOptions, type TransformActionsResult, getActionId, hasModuleDirective, inferStrategy, transformActions };

package/dist/compiler.mjs

@@ -1 +1 @@
-export { t as ActionCompileError, n as getActionId, r as hasModuleDirective, i as transformActions } from "./_chunks/actions-Eutk6UzT.mjs";
+export { n as ActionCompileError, r as getActionId, i as hasModuleDirective, t as inferStrategy, a as transformActions } from "./_chunks/infer-BIVT5aDz.mjs";

package/dist/react/client.d.mts

@@ -1,7 +1,7 @@
 import { a as scheduleHydration, i as isIslandStrategy, n as IslandStrategy, r as ScheduleOptions, t as ISLAND_STRATEGIES } from "../_chunks/schedule-Dw14dW0H.mjs";
 import { m as HYDRATED_ATTRIBUTE } from "../_chunks/wire-Dipqh-EB.mjs";
 import { t as ValueStore } from "../_chunks/value-store-Dm-7xJ6W.mjs";
-import { a as ServerTreeLayoutOptions, c as createServerTreeLayout, g as isolateIslands, i as ServerTreeLayout, n as PAYLOAD_ONLY_ATTRIBUTE, r as ServerTreeElementOptions, s as createServerTreeElement, u as updateServerTrees, v as withinClientRoot } from "../_chunks/tree-B4RMU2UX.mjs";
+import { a as ServerTreeLayoutOptions, c as createServerTreeLayout, g as isolateIslands, i as ServerTreeLayout, n as PAYLOAD_ONLY_ATTRIBUTE, r as ServerTreeElementOptions, s as createServerTreeElement, u as updateServerTrees, v as withinClientRoot } from "../_chunks/tree-CV13RsJv.mjs";
 import * as React from "react";
 
 // src/react/hydrate.d.ts

package/dist/react/client.mjs

@@ -1,9 +1,9 @@
 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 { 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 { i as getContexts, o as isolateIslands, u as withinClientRoot } from "../_chunks/island-DXAGP4FN.mjs";
+import { i as createServerTreeLayout, n as PAYLOAD_ONLY_ATTRIBUTE, o as updateServerTrees, r as createServerTreeElement } from "../_chunks/tree-BQphP23Y.mjs";
+import { n as isIslandStrategy, r as scheduleHydration, t as ISLAND_STRATEGIES } from "../_chunks/schedule-Cwn9vQL0.mjs";
 import * as React from "react";
 import { hydrateRoot } from "react-dom/client";
 // src/react/hydrate.ts

package/dist/react/server.d.mts

@@ -1,5 +1,5 @@
 import { r as ReactFormState } from "../_chunks/handle-C0N9ZyNV.mjs";
-import { _ as setRenderStateResolver, d as ClientReference, f as IslandRenderState, g as isolateIslands, h as getClientReference, l as renderServerTree, m as createIsland, n as PAYLOAD_ONLY_ATTRIBUTE, o as ServerTreeRenderOptions, p as IslandsProvider, t as Outlet, v as withinClientRoot } from "../_chunks/tree-B4RMU2UX.mjs";
+import { _ as setRenderStateResolver, d as ClientReference, f as IslandRenderState, g as isolateIslands, h as getClientReference, l as renderServerTree, m as createIsland, n as PAYLOAD_ONLY_ATTRIBUTE, o as ServerTreeRenderOptions, p as IslandsProvider, t as Outlet, v as withinClientRoot } from "../_chunks/tree-CV13RsJv.mjs";
 import * as React from "react";
 import { RenderToReadableStreamOptions } from "react-dom/server";
 

package/dist/react/server.mjs

@@ -1,11 +1,12 @@
 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 { RUNTIME_GLOBAL } from "../boot.mjs";
+import { r as PREHYDRATION_SCRIPT } from "../_chunks/prehydration-zEYsfFxW.mjs";
 import { i as encodeActionReference } from "../_chunks/actions-CvQ0-zjg.mjs";
 import { t as getBuildDefaults } from "../_chunks/build-COIcs7wm.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 { 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-DXAGP4FN.mjs";
+import { a as renderServerTree, n as PAYLOAD_ONLY_ATTRIBUTE, t as Outlet } from "../_chunks/tree-BQphP23Y.mjs";
 import * as React from "react";
 // src/react/server.ts
 /**
@@ -88,9 +89,12 @@ async function renderToStream(element, { request, formState, bootstrap = true, p
 		held: held && held.size > 0 ? held : null,
 		sent: /* @__PURE__ */ new Set()
 	} }, element, formState ? React.createElement(FormStateScript, { formState }) : null);
-	const entry = bootstrap ? getBuildDefaults().entry : void 0;
-	const bootstrapModules = entry ? [...options.bootstrapModules ?? [], entry] : options.bootstrapModules;
-	const bootstrapScriptContent = prehydration ?? entry !== void 0 ? `${PREHYDRATION_SCRIPT}${options.bootstrapScriptContent ?? ""}` : options.bootstrapScriptContent;
+	const defaults = getBuildDefaults();
+	const entry = bootstrap ? defaults.entry : void 0;
+	const boot = entry !== void 0 ? defaults.boot : void 0;
+	const bootstrapModules = entry ? [...options.bootstrapModules ?? [], boot ?? entry] : options.bootstrapModules;
+	const runtime = boot ? `window.${RUNTIME_GLOBAL}=${escapeScriptJson(JSON.stringify(entry))};` : "";
+	const bootstrapScriptContent = prehydration ?? entry !== void 0 ? `${PREHYDRATION_SCRIPT}${runtime}${options.bootstrapScriptContent ?? ""}` : runtime || options.bootstrapScriptContent ? `${runtime}${options.bootstrapScriptContent ?? ""}` : void 0;
 	const { renderToReadableStream } = await import("react-dom/server");
 	const stream = await renderToReadableStream(tree, {
 		...options,

package/dist/react.d.mts

@@ -1,3 +1,3 @@
-import { f as IslandRenderState, g as isolateIslands, l as renderServerTree, m as createIsland, o as ServerTreeRenderOptions, p as IslandsProvider, t as Outlet, v as withinClientRoot } from "./_chunks/tree-B4RMU2UX.mjs";
+import { f as IslandRenderState, g as isolateIslands, l as renderServerTree, m as createIsland, o as ServerTreeRenderOptions, p as IslandsProvider, t as Outlet, v as withinClientRoot } from "./_chunks/tree-CV13RsJv.mjs";
 import { n as IslandStrategy } from "./_chunks/schedule-Dw14dW0H.mjs";
 export { type IslandRenderState, type IslandStrategy, IslandsProvider, Outlet, type ServerTreeRenderOptions, createIsland, isolateIslands, renderServerTree, withinClientRoot };

package/dist/react.mjs

@@ -1,3 +1,3 @@
-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";
+import { n as createIsland, o as isolateIslands, t as IslandsProvider, u as withinClientRoot } from "./_chunks/island-DXAGP4FN.mjs";
+import { a as renderServerTree, t as Outlet } from "./_chunks/tree-BQphP23Y.mjs";
 export { IslandsProvider, Outlet, createIsland, isolateIslands, renderServerTree, withinClientRoot };

package/dist/server.d.mts

@@ -187,6 +187,11 @@ declare function isSameOriginRequest(request: Request, allowedOrigins: readonly
 interface BuildDefaults {
   /** The URL of the browser entry `renderToStream` adds to pages. */
   entry?: string;
+  /**
+   * The URL of the boot entry (`@farm.js/islx/boot`): pages start with it instead, and it loads
+   * `entry` when the page first needs it. An island that hydrates at load preloads `entry`.
+   */
+  boot?: string;
   /** A key made for this build: every instance of one build shares it. */
   key?: string;
   /**

package/dist/tanstack-start/server.mjs

@@ -1,4 +1,4 @@
-import { t as IslandsProvider } from "../_chunks/island-DVOr-OUw.mjs";
+import { t as IslandsProvider } from "../_chunks/island-DXAGP4FN.mjs";
 import { A as VALUES_HEADER, C as RENDER_HEADER } from "../_chunks/wire-QEQWBr5s.mjs";
 import { a as parseHeldValues } from "../_chunks/values-37UIzxM0.mjs";
 import * as React from "react";

package/dist/tanstack-start.mjs

@@ -1,4 +1,4 @@
-import { n as islx, t as ENTRY_ID } from "./_chunks/vite-BTzYlEiY.mjs";
+import { n as ENTRY_ID, r as islx } from "./_chunks/vite-0bH_ZDys.mjs";
 import { normalizePath } from "vite";
 // src/tanstack-start/index.ts
 /**

package/dist/vite.d.mts

@@ -42,9 +42,24 @@ interface IslxOptions {
     client?: string | ClientHooks;
     server?: string | ServerHooks;
   };
+  /**
+   * A client module without a `hydrate` export waits for a click when its code provably does
+   * nothing before one (`inferStrategy` in `@farm.js/islx/compiler`): a page of such islands loads
+   * the runtime only when one is used. Default true; false hydrates them at load.
+   */
+  infer?: boolean;
+  /**
+   * Pages start with a small boot script (`@farm.js/islx/boot`) instead of the browser entry,
+   * and load the entry when the page first needs it: at once when an island hydrates at load,
+   * otherwise on an island's trigger or a link. Default true; false starts every page with the
+   * entry.
+   */
+  boot?: boolean;
 }
 /** @internal The browser entry, for a framework whose own entry imports it. */
 declare const ENTRY_ID = "virtual:islx/client-entry";
+/** The boot entry: pages start with it, and it loads ENTRY_ID when the page first needs it. */
+declare const BOOT_ID = "virtual:islx/boot";
 /**
  * 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.
@@ -73,4 +88,4 @@ interface IslxHost {
   frameworkBuild?: boolean;
 }
 declare function islx(options?: IslxOptions, host?: IslxHost): Plugin[];
-export { ENTRY_ID, IslxHost, IslxOptions, islx as default, islx, resolveDirectives, serializeHooks };
+export { BOOT_ID, ENTRY_ID, IslxHost, IslxOptions, islx as default, islx, resolveDirectives, serializeHooks };

package/dist/vite.mjs

@@ -1 +1 @@
-export { t as ENTRY_ID, n as default, n as islx, r as resolveDirectives, i as serializeHooks } from "./_chunks/vite-BTzYlEiY.mjs";
+export { t as BOOT_ID, n as ENTRY_ID, r as default, r as islx, i as resolveDirectives, a as serializeHooks } from "./_chunks/vite-0bH_ZDys.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farm.js/islx",
-  "version": "0.0.7",
+  "version": "0.0.8",
   "description": "A renderer-agnostic wire format for server-rendered islands: typed props, values sent once, server actions, and partial navigations.",
   "keywords": [
     "islands",
@@ -39,6 +39,10 @@
       "types": "./dist/client.d.mts",
       "default": "./dist/client.mjs"
     },
+    "./boot": {
+      "types": "./dist/boot.d.mts",
+      "default": "./dist/boot.mjs"
+    },
     "./server": {
       "types": "./dist/server.d.mts",
       "default": "./dist/server.mjs"