@farm.js/islx 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 0.0.9
+
+Islands behave as React Server Components do in four cases they did not.
+
+- `useId` in an island returns the ids its server HTML has, and two islands no longer share ids.
+  The props script carries the island's id position (`ids`), which the browser rebuilds before it
+  hydrates. The island wrapper no longer calls `useId` inside another island, where it moved every
+  id below it.
+- Client components in server output passed to an island (`children`, or any element prop) are
+  the island's descendants: they read its context, as a consumer below a provider does, and keep
+  their own state. Such output travels as a server tree named after its slot; plain HTML still
+  travels as HTML only.
+- An element prop the island does not render at first (a tab, a closed panel) renders when it
+  does. The server writes the slots it did not place in a `<template>` after the props.
+- `useFormStatus` in a client component inside a server component's `<form>` reports that form's
+  submit. The compiler points `useFormStatus` from `react-dom` at `@farm.js/islx/react`'s, which
+  is React's anywhere else; `rewriteFormStatusImports` in `@farm.js/islx/compiler` does it for
+  other plugins. A namespace import (`ReactDOM.useFormStatus`) keeps React's.
+
+## 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.9. 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

@@ -29,9 +29,10 @@ Anything that writes and reads it, in any language or framework, is a islx imple
 | Name | Meaning |
 | --- | --- |
 | `<f-island>` | A client component's server HTML. `src` names the module the browser imports (its path from the app root; the runtime maps it to a URL), `export` the component's export name, `props` the id of its props script, `strategy` when it hydrates: `load`, `idle`, `visible` or `interaction`. A hydrated island gets a `hydrated` attribute. |
-| `<script type="f/props" for>` | An island's props, as JSON. `for` names the island's `props` id. |
+| `<script type="f/props" for [ids]>` | An island's props, as JSON. `for` names the island's `props` id. `ids` is the `useId` React gave a probe the server renders first in the island, at index 0 of a two-child array whose second child is the component: its bits and length are the island's id position, which the browser rebuilds before it hydrates the component at index 1, so the component's `useId` calls match its HTML. Without it the browser hydrates with React's own ids. |
 | `<script type="f/value" name>` | A value sent once. `name` is its key. Written before the first island that uses it. |
-| `<f-slot name>` | Server output passed to an island as children. It stays server HTML; the island renders it in place. |
+| `<f-slot name>` | Server output passed to an island as children (or any element prop). Plain HTML stays server HTML, and the island renders it in place. Output holding client components, Suspense boundaries, actions or `<f-html>` parts carries a server tree (`<script type="f/tree" name>` named after the slot, inside it), which the browser rebuilds inside the island's root: its client components are the island's descendants and read its context. |
+| `<template for>` | After an island's props: the `<f-slot>`s the island did not place when the server rendered it (a closed panel, a tab not shown yet). `for` names the island's `props` id. The browser reads a slot from here when the island places it. |
 | `<script type="f/tree" [name] [partial]>` | A server tree, so the browser can rebuild the page inside an existing root without its HTML. A page's tree has no `name`; a layout's carries its scope and sits at its `children` outlet, or after the layout when it has none. `partial` marks a navigation that sent only the tree. |
 | `<script type="f/chunk" name>` | A part of a server tree that streamed in after the tree (a resolved Suspense boundary). `name` is its number, after `scope:` in a layout's tree. |
 | `<f-html name>` | Server HTML inside a server tree, named like a chunk. |
@@ -41,8 +42,8 @@ A value script's, props script's and promise script's JSON escapes `<`, U+2028 a
 
 ## JSON tags
 
-A tagged object is `{"$":tag}` or `{"$":tag,"v":data}`; an action may also carry `"b"`. An object
-with any other keys is data.
+A tagged object is `{"$":tag}` or `{"$":tag,"v":data}`; an action may also carry `"b"`, and a slot
+`"t":1` when it carries a server tree. An object with any other keys is data.
 
 | Tag | Stands for | Data |
 | --- | --- | --- |

package/dist/_chunks/{actions-C-IwUCKU.mjs → actions-DAzd4PpV.mjs}

@@ -1,5 +1,5 @@
-import { A as VALUES_HEADER, F as getTag, M as VALUE_SCRIPT_TYPE, N as attachmentField, j as VALUE_KEY_PATTERN, o as BOUND_FIELD, s as CALL_FIELD, t as ACTION_HEADER } from "./wire-QEQWBr5s.mjs";
-import { a as encode, r as decode, u as setOwn } from "./codec-C8to-RQW.mjs";
+import { F as VALUE_SCRIPT_TYPE, I as attachmentField, N as VALUES_HEADER, P as VALUE_KEY_PATTERN, R as getTag, o as BOUND_FIELD, s as CALL_FIELD, t as ACTION_HEADER } from "./wire-UUwZlUJZ.mjs";
+import { a as encode, r as decode, u as setOwn } from "./codec-DDpUvgRo.mjs";
 // src/client/value-store.ts
 /**
 * The browser's store of values sent once. It keeps every value it has read, parses each once,

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

@@ -1,6 +1,6 @@
-import { P as formFieldName, d as FORM_REF_PREFIX } from "./wire-QEQWBr5s.mjs";
+import { L as formFieldName, d as FORM_REF_PREFIX } from "./wire-UUwZlUJZ.mjs";
 import { t as getBuildDefaults } from "./build-COIcs7wm.mjs";
-import { a as encode, r as decode, t as EncodeError } from "./codec-C8to-RQW.mjs";
+import { a as encode, r as decode, t as EncodeError } from "./codec-DDpUvgRo.mjs";
 // src/server/seal.ts
 /**
 * Sealing an action's captured values. An inline `"use server"` function that reads a variable of

package/dist/_chunks/{codec-C8to-RQW.mjs → codec-DDpUvgRo.mjs}

@@ -1,4 +1,4 @@
-import { F as getTag } from "./wire-QEQWBr5s.mjs";
+import { R as getTag } from "./wire-UUwZlUJZ.mjs";
 // src/protocol/codec.ts
 /**
 * Values JSON cannot hold. Each travels as a tagged object: the reserved key `$` holds a short tag

package/dist/_chunks/{actions-Eutk6UzT.mjs → form-status-CRfnB7WT.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,316 @@ 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;
+}
+// src/compiler/form-status.ts
+/**
+* Points a client module's `useFormStatus` import from `react-dom` at islx's hook, which also
+* reports a server component's form around an island (`@farm.js/islx/react` `useFormStatus`).
+* Both builds rewrite it, so the server and the browser render the same hook. A namespace import
+* (`ReactDOM.useFormStatus()`) keeps React's.
+*/
+const HOOK = "useFormStatus";
+function importedName(specifier) {
+	const imported = specifier.imported;
+	return imported?.type === "Identifier" ? imported.name : imported?.value;
+}
+/** Applies the rewrite to `output`; true when the module imported the hook. */
+function rewriteFormStatusImport(program, code, output, from) {
+	let changed = false;
+	for (const node of program.body ?? []) {
+		if (node.type !== "ImportDeclaration" || node.source?.value !== "react-dom") continue;
+		if (node.importKind === "type") continue;
+		const specifiers = node.specifiers ?? [];
+		const hooks = specifiers.filter((specifier) => specifier.type === "ImportSpecifier" && specifier.importKind !== "type" && importedName(specifier) === HOOK);
+		if (hooks.length === 0) continue;
+		const others = specifiers.filter((specifier) => !hooks.includes(specifier));
+		const defaults = others.filter((specifier) => specifier.type !== "ImportSpecifier");
+		const named = others.filter((specifier) => specifier.type === "ImportSpecifier");
+		const text = (specifier) => code.slice(specifier.start, specifier.end);
+		const clause = [...defaults.map(text), ...named.length > 0 ? [`{ ${named.map(text).join(", ")} }`] : []].join(", ");
+		const lines = [...clause ? [`import ${clause} from "react-dom";`] : [], `import { ${hooks.map((hook) => `${HOOK} as ${hook.local.name}`).join(", ")} } from ${JSON.stringify(from)};`];
+		output.overwrite(node.start, node.end, lines.join("\n"));
+		changed = true;
+	}
+	return changed;
+}
+/** The rewrite for a framework's own transform: the module's new code and map, or null. */
+function rewriteFormStatusImports(options) {
+	if (!options.code.includes(HOOK)) return null;
+	const output = new MagicString(options.code);
+	if (!rewriteFormStatusImport(options.parse(options.code), options.code, output, options.from ?? "@farm.js/islx/react")) return null;
+	return {
+		code: output.toString(),
+		map: output.generateMap({
+			source: options.id,
+			hires: true
+		})
+	};
+}
+export { getActionId as a, ActionCompileError as i, rewriteFormStatusImports as n, hasModuleDirective as o, inferStrategy as r, transformActions as s, rewriteFormStatusImport as t };

package/dist/_chunks/forms-CCDY9QHC.mjs

@@ -0,0 +1,63 @@
+import { B as stripRuntimeFields, z as readPostedAction } from "./wire-UUwZlUJZ.mjs";
+import { t as createServerReference } from "./actions-DAzd4PpV.mjs";
+// src/client/forms.ts
+/**
+* Forms written in server components submit without reloading the page once JavaScript runs.
+* No island owns them, so nothing else would: a submit of a form that posts an action is sent as
+* a call, and the page refreshes as after any action, keeping island state. Forms inside islands
+* are React's, which handles them first.
+*/
+let enhanced = false;
+/** No submission in flight. */
+const IDLE_FORM_STATUS = Object.freeze({
+	pending: false,
+	data: null,
+	method: null,
+	action: null
+});
+const statuses = /* @__PURE__ */ new WeakMap();
+const listeners = /* @__PURE__ */ new Set();
+function setStatus(form, status) {
+	if (status) statuses.set(form, status);
+	else statuses.delete(form);
+	for (const listener of listeners) listener();
+}
+/** The submission in flight for a server form, or the idle status. */
+function getServerFormStatus(form) {
+	return statuses.get(form) ?? IDLE_FORM_STATUS;
+}
+/** Calls `listener` whenever a server form starts or settles a submission. */
+function subscribeServerForms(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+/** Starts handling server-component forms on this page. Safe to call more than once. */
+function enhanceForms() {
+	if (enhanced) return;
+	enhanced = true;
+	document.addEventListener("submit", (event) => {
+		if (event.defaultPrevented || !(event.target instanceof HTMLFormElement)) return;
+		const form = event.target;
+		const submitter = event.submitter ?? null;
+		const data = new FormData(form, submitter);
+		const posted = readPostedAction(data);
+		if (!posted) return;
+		event.preventDefault();
+		stripRuntimeFields(data);
+		form.setAttribute("aria-busy", "true");
+		const action = createServerReference(posted.id, posted.token);
+		setStatus(form, {
+			pending: true,
+			data,
+			method: form.method || "get",
+			action
+		});
+		action(data).then(() => form.reset()).catch((error) => console.error("[islx] The form's action failed:", error)).finally(() => {
+			form.removeAttribute("aria-busy");
+			setStatus(form, null);
+		});
+	});
+}
+export { subscribeServerForms as i, enhanceForms as n, getServerFormStatus as r, IDLE_FORM_STATUS as t };