@farm.js/islx 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,44 @@
 # 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.
+
+- `@farm.js/islx/react/server` no longer generates random values while it loads. It made the
+  promise-name prefix with `crypto.getRandomValues` at module scope, which Workers reject
+  ("Disallowed operation called within global scope"), so no islx app started on Cloudflare
+  since promise props (0.0.4). The prefix is made at the first render now.
+- An inline `"use server"` function's captured values are sealed with format version 2: the key id
+  is the first 4 bytes of the key's SHA-256 instead of the first byte. With one byte, a deploy that
+  changed keys without keeping the old one gave the new key the same id one time in 256, and
+  values from pages rendered before it failed as invalid (`400`) instead of stale (the page
+  reloads). An app that does not set `ISLX_ACTIONS_KEY` gets a new key on every build, so this hit
+  about one deploy in 256.
+- Values sealed by 0.0.6 or earlier (format version 1) are stale: forms on pages open across the
+  upgrade reload once.
+
 ## 0.0.6
 
 Server action interceptor, early clicks on TanStack Start, library islands under pnpm.

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.6. 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/SPEC.md

@@ -198,14 +198,17 @@ travel with the action, sealed, so the browser can neither read nor change them:
 sealed = base64url( version ‖ key id ‖ IV ‖ AES-256-GCM(ciphertext ‖ tag) )
 ```
 
-- `version` is `1`; `key id` is the first byte of SHA-256 of the key; the IV is 12 random bytes;
+- `version` is `2` (one byte); `key id` is the first 4 bytes of SHA-256 of the key, big-endian;
+  the IV is 12 random bytes;
 - the additional data is `islx:action:<id>`, so values sealed for one action never open for
   another;
 - the plaintext is the captured values as a tagged JSON array.
 
-A value sealed with a key the server does not have is **stale** (the page reloads); anything that
-does not open is **invalid** (`400`). Servers may hold previous keys, so pages rendered before a
-key rotation keep working. Every server instance must share the keys.
+A value sealed with a key the server does not have, or in another `version`, is **stale** (the
+page reloads); anything that does not open is **invalid** (`400`). Servers may hold previous keys,
+so pages rendered before a key rotation keep working. Every server instance must share the keys.
+Version 1 named the key with one byte, so one key rotation in 256 made values from open pages
+invalid instead of stale; its values are stale now.
 
 ## Integration model
 

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

@@ -24,10 +24,11 @@ import { a as encode, r as decode, t as EncodeError } from "./codec-C8to-RQW.mjs
 * Sealing is asynchronous. React's server renderer waits for it: a form whose action's values
 * are still sealing suspends, and renders once they are ready.
 *
-*   sealed = base64url( version (1 byte) ‖ key id (1 byte) ‖ IV (12 bytes) ‖ ciphertext+tag )
+*   sealed = base64url( version (1 byte) ‖ key id (4 bytes) ‖ IV (12 bytes) ‖ ciphertext+tag )
 */
-const VERSION = 1;
+const VERSION = 2;
 const IV_BYTES = 12;
+const HEADER_BYTES = 5;
 const KEY_BYTES = 32;
 /** Thrown when a sealed value does not open: changed, made for another action, or stale. */
 var SealError = class extends Error {
@@ -58,7 +59,7 @@ function fromBase64url(text) {
 		return null;
 	}
 }
-/** A new random key, as base64url: what `FURROW_ACTIONS_KEY` holds. */
+/** A new random key, as base64url: what `ISLX_ACTIONS_KEY` holds. */
 function generateActionKey() {
 	return base64url(crypto.getRandomValues(new Uint8Array(KEY_BYTES)));
 }
@@ -67,10 +68,10 @@ async function importKey(secret) {
 	if (!bytes || bytes.length !== KEY_BYTES) throw new TypeError("an actions key must be 32 random bytes as base64url; create one with generateActionKey() from @farm.js/islx/server");
 	return crypto.subtle.importKey("raw", bytes, "AES-GCM", false, ["encrypt", "decrypt"]);
 }
-/** The key's id: its first byte of SHA-256, so a value names the key that sealed it. */
+/** The key's id: the first 4 bytes of its SHA-256, so a value names the key that sealed it. */
 async function keyId(secret) {
 	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(secret.trim()));
-	return new Uint8Array(digest)[0];
+	return new DataView(digest).getUint32(0);
 }
 /**
 * The keys values are sealed and opened with. `current` seals; `previous` keys still open
@@ -128,11 +129,11 @@ async function sealBound(keys, actionId, values, options = {}) {
 		iv,
 		additionalData: additionalData(actionId)
 	}, keys.current, new TextEncoder().encode(json)));
-	const sealed = new Uint8Array(14 + ciphertext.length);
+	const sealed = new Uint8Array(17 + ciphertext.length);
 	sealed[0] = VERSION;
-	sealed[1] = keys.currentId;
-	sealed.set(iv, 2);
-	sealed.set(ciphertext, 14);
+	new DataView(sealed.buffer).setUint32(1, keys.currentId);
+	sealed.set(iv, HEADER_BYTES);
+	sealed.set(ciphertext, 17);
 	return base64url(sealed);
 }
 /**
@@ -141,17 +142,17 @@ async function sealBound(keys, actionId, values, options = {}) {
 */
 async function unsealBound(keys, actionId, sealed, options = {}) {
 	const bytes = fromBase64url(sealed);
-	if (!bytes || bytes.length < 30) throw new SealError("invalid", "sealed action values are malformed");
-	if (bytes[0] !== VERSION) throw new SealError("stale", "sealed action values use another format version");
-	const candidates = keys.byId.get(bytes[1]);
+	if (bytes && bytes.length > 0 && bytes[0] !== VERSION) throw new SealError("stale", "sealed action values use another format version");
+	if (!bytes || bytes.length < 33) throw new SealError("invalid", "sealed action values are malformed");
+	const candidates = keys.byId.get(new DataView(bytes.buffer).getUint32(1));
 	if (!candidates) throw new SealError("stale", "sealed action values use a key this server does not have");
 	let plaintext;
 	for (const key of candidates) try {
 		plaintext = await crypto.subtle.decrypt({
 			name: "AES-GCM",
-			iv: bytes.subarray(2, 14),
+			iv: bytes.subarray(HEADER_BYTES, 17),
 			additionalData: additionalData(actionId)
-		}, key, bytes.subarray(14));
+		}, key, bytes.subarray(17));
 		break;
 	} catch {}
 	if (!plaintext) throw new SealError("invalid", "sealed action values do not open for this action");

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];