@farm.js/islx 0.0.0-stage → 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.0.1
+
+The first release: the islx wire format, server actions, React islands, and the Vite plugin.
+
+### Wire format (`@farm.js/islx`)
+
+- `f-` vocabulary: `<f-island>`, `f/props`, `f/value`, `<f-slot>`, `f/tree`, `f/chunk`, `<f-html>`,
+  `f/form-state`; headers `F-Values`, `F-Layouts`, `F-Render`, `F-Action`.
+- One reserved JSON key, `$`, with short tags: `Date`, `Map`, `Set`, `BigInt`, `URL`, `RegExp`,
+  bytes, `undefined`, special numbers, `FormData` and file arguments; app data with a `$` key
+  travels wrapped. Decoding refuses unknown tags and keeps `__proto__` an ordinary key.
+
+### Server (`@farm.js/islx/server`)
+
+- Values sent once: large props keyed by a hash of their JSON, left out for browsers that hold
+  them.
+- Server actions: `"use server"` modules and inline `"use server"` functions. Captured variables
+  and `.bind` arguments travel sealed (AES-GCM, bound to the action, key rotation).
+- `handleAction(request)`: calls and forms without JavaScript, `<button formAction>`,
+  `useActionState` form state, origin checks, a body limit, stale-deploy answers, errors that
+  never reach the browser.
+- Lifecycle hooks: `defineServerHooks({ action, actionError, error })`.
+
+### Browser (`@farm.js/islx/client`)
+
+- Action references: calls in order, refresh after each, redirects, stale-deploy reloads.
+- Client navigation, view transitions, server-component forms without reloads.
+- Lifecycle hooks and `f:` DOM events; the pre-hydration script that holds early interactions.
+
+### React (`@farm.js/islx/react`, `/react/server`, `/react/client`)
+
+- `createIsland`, `renderToStream`, the hydration runtime (`load`, `idle`, `visible`,
+  `interaction`), carry-over across refreshes, server HTML restored on failure.
+- Server trees for layouts that hydrate as one root, payload-only navigations.
+- For frameworks: `IslandsProvider`, `withinClientRoot`, `isolateIslands`, `createServerHtml`.
+
+### Build (`@farm.js/islx/compiler`, `@farm.js/islx/vite`)
+
+- `transformActions` and `transformClientModule`, with errors that say where and what to do.
+- `islx()` for Vite 6+: discovery, one chunk per client module, preloads, dev reloads,
+  `directives`, `hooks`, `navigation`, `clientComponents`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Farming Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# islx
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A wire format for server-rendered islands. Pages are plain server HTML; the interactive parts
+hydrate on their own, with typed props, values sent once, server actions, and navigations that
+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>
+```
+
+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.1, the first release. React and Vite are supported; other renderers and framework
+> integrations follow. The wire format is in [SPEC.md](./SPEC.md), changes in
+> [CHANGELOG.md](./CHANGELOG.md).
+
+```bash
+npm install @farm.js/islx
+```
+
+## What is here
+
+```ts
+import { encode, decode } from "@farm.js/islx";
+import { addressValues, selectValuesToSend, handleAction } from "@farm.js/islx/server";
+import { getValueStore, createServerReference, setActionNavigator } from "@farm.js/islx/client";
+import { transformActions } from "@farm.js/islx/compiler";
+```
+
+- **Typed values.** `Date`, `Map`, `Set`, `BigInt`, `URL`, `RegExp`, bytes, `undefined` and
+  special numbers survive the trip, in props and in action arguments and results.
+- **Values sent once.** Large props are keyed by a hash of their JSON. Islands and pages that
+  share one share its key, and a navigation leaves out what the browser holds.
+- **Server actions.** `"use server"` modules and inline `"use server"` functions, with:
+  - the variables an inline action reads from its component carried along, sealed (AES-GCM,
+    bound to the action) so the browser can neither read nor change them;
+  - forms that work before JavaScript loads, including `<button formAction>` and
+    `useActionState`;
+  - `.bind` on the server (sealed) and in the browser;
+  - calls run in order, then a page refresh; a redirect navigates; an action from an older
+    deploy reloads the page;
+  - same-origin checks, a body size limit, and errors that never reach the browser.
+- **React islands.** `createIsland` renders a client component as server HTML plus its props;
+  `renderToStream` renders a page (leaving out values the browser holds); the hydration runtime
+  starts each island as its own root when its strategy says (`load`, `idle`, `visible`,
+  `interaction`, which holds the first click or submit and replays it), restores the server HTML
+  if an island fails, keeps island state when the page renders again, and hydrates
+  `useActionState` with the form post's result.
+- **Compiler.** A pure function from source to source for each environment, with errors that
+  say where and what to do: an inline action in browser code, one that is not async, uses
+  `this`, or captures something that cannot travel.
+
+### Server actions in a framework
+
+```ts
+// The server: before rendering a page.
+const response = await handleAction(request, {
+  allowedOrigins: ["app.example.com"],
+  mapError: (error) => (isRedirect(error) ? { redirect: error.location } : undefined),
+  renderFormState: (formState) => renderPage(request, { formState }),
+});
+if (response) return response;
+
+// The browser: once.
+setActionNavigator({ refresh: () => router.refresh(), navigate: (href) => router.push(href) });
+```
+
+Every server instance must share the key captured values are sealed with: set
+`ISLX_ACTIONS_KEY` (make one with `generateActionKey()`), or call `configureActionKeys`. Keep a
+rotated-out key in `ISLX_ACTIONS_PREVIOUS_KEYS` so open pages keep working.
+
+### Known limits
+
+- Every registered action is a public endpoint, as in React and Next.js: check inputs and rights
+  inside it.
+- Arguments carry the typed values above, `FormData`, `File` and `Blob`.
+- Actions are not removed from the server build when nothing imports them yet.
+
+## On Vite
+
+```ts
+// vite.config.ts
+import react from "@vitejs/plugin-react";
+import { islx } from "@farm.js/islx/vite";
+
+export default defineConfig({
+  plugins: [react(), islx()],
+  environments: {
+    ssr: { build: { outDir: "dist/server", rollupOptions: { input: "src/entry-server.tsx" } } },
+  },
+});
+```
+
+```tsx
+// src/entry-server.tsx
+import { renderToStream } from "@farm.js/islx/react/server";
+import { handleAction } from "@farm.js/islx/server";
+
+export async function handle(request: Request) {
+  const action = await handleAction(request, {
+    renderFormState: (formState) => page(request, formState),
+  });
+  return action ?? page(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" } });
+}
+```
+
+```tsx
+// src/components/chart.tsx
+"use client";
+export const hydrate = "visible"; // or { Chart: "visible", Legend: "idle" }; default "load"
+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.
+- `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.
+- Forms in server components submit without a reload once JavaScript runs, and post normally
+  before.
+- Same-site links move between pages without loading a new document: the runtime, its code and
+  the values the browser holds stay, and the server leaves those values out. Back, forward,
+  scroll and focus behave as page loads do. `islx({ navigation: false })` turns it off;
+  `rel="external"` opts one link out; `navigate(href)` from `@farm.js/islx/client` navigates from
+  code.
+- `islx({ directives: { client: "use island", server: "use action" } })` renames the directives
+  your code uses, for apps where another tool already owns `"use client"` or `"use server"`.
+  Libraries keep `"use client"`: their components become islands when Vite bundles them for the
+  server (`ssr.noExternal`), and their `"use server"` never registers an action.
+- Lifecycle hooks go in the plugin's options:
+
+  ```ts
+  islx({
+    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); },
+        actionEnd({ name, ok, duration }) {},
+      },
+      server: {
+        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
+  arguments and globals; the build names anything else they use. Hooks that import app code (an
+  auth helper, an error reporter) go in a module: `hooks: { server: "./src/islx.server.ts" }`,
+  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.
+
+`examples/react` is a runnable app; `pnpm test:e2e` runs it in Chrome, in development and from
+its production build.
+
+## In a framework
+
+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 |
+| 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 |
+
+## License
+
+MIT

package/SPEC.md

@@ -0,0 +1,220 @@
+# islx wire format
+
+Version 1. This document is the contract between a islx server and a islx browser runtime.
+Anything that writes and reads it, in any language or framework, is a islx implementation.
+
+## Principles
+
+- **HTML first.** A page is ordinary server HTML. Interactive parts are marked where they sit;
+  nothing else is reserved.
+- **One prefix.** Every element, script type and header islx owns starts with `f`. Custom
+  elements need a hyphen (`f-island`), script types use a slash (`f/props`), headers start `F-`.
+- **One reserved JSON key.** Inside JSON, `$` holds a short tag. App data that has its own `$`
+  key is wrapped, so no key is off limits to apps.
+- **Untrusted by default.** Everything the browser sends back (headers, action arguments, sealed
+  values) is validated. References are never accepted from the browser unless the server checks
+  them.
+
+## HTML
+
+```html
+<f-island src="/src/toc.tsx" export="Toc" props="_R_b_" strategy="load">
+  …the component's server HTML…
+  <f-slot name="_R_5_s0">…server output passed as children…</f-slot>
+</f-island>
+<script type="f/value" name="04jiw29097x8ki">[…a value sent once…]</script>
+<script type="f/props" for="_R_b_">{"headings":[…],"tree":{"$":"r","v":"04jiw29097x8ki"}}</script>
+```
+
+| 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/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. |
+| `<script type="f/tree" [partial]>` | A page's server tree, so the browser can rebuild the page inside an existing root without its HTML. `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). |
+| `<f-html name>` | Server HTML inside a server tree. |
+
+A value script's and props script's JSON escapes `<`, U+2028 and U+2029.
+
+## 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.
+
+| Tag | Stands for | Data |
+| --- | --- | --- |
+| `r` | a value sent once | its key |
+| `s` | a slot | its name |
+| `a` | a server action | its id; `b`, when present, holds its sealed captured values |
+| `o` | app data with a `$` key | the object |
+| `u` | `undefined` | |
+| `n` | `NaN`, `Infinity`, `-Infinity`, `-0` | the name |
+| `B` | `BigInt` | decimal digits |
+| `D` | `Date` | ISO string, `null` for an invalid date |
+| `M` | `Map` | `[[key, value], …]`, both tagged |
+| `S` | `Set` | `[value, …]`, tagged |
+| `U` | `URL` | `href` |
+| `R` | `RegExp` | `[source, flags]` |
+| `Y` | bytes | `[type, base64]`; type is `ArrayBuffer`, `DataView` or a typed array name |
+| `p` | a Suspense boundary inside a server tree | |
+| `F` | a `FormData` action argument | its index among the call's attachments |
+| `K` | a `Blob` or `File` action argument | its index among the call's attachments |
+
+The browser resolves `r` first (from its value store), then decodes the rest. Inside `o`, only
+the object's properties are read; the object itself is never a tag. Unknown tags are errors.
+
+Decoders build plain objects with own properties, so a `__proto__` key stays an ordinary key.
+
+## Values sent once
+
+A value whose JSON reaches 512 characters travels in its own `f/value` script, keyed by a 64-bit
+hash of its JSON (14 base-36 characters), and props refer to it as `{"$":"r","v":key}`. Inner
+values are addressed first, so a value that changed in one place shares its unchanged parts. A
+thin wrapper around one addressed value is not addressed.
+
+The browser keeps every value it reads, up to 1024, and names the most recently used 128 in each
+navigation:
+
+```http
+GET /docs/p1
+F-Values: 04jiw29097x8ki,1kq0d3f7xg2m9a
+```
+
+The server leaves those values out. A response that left values out belongs to one browser: it
+must never enter a shared cache (CDN, ISR entry, PPR shell), and a cacheable response sends
+`Vary: F-Values`.
+
+## Navigations
+
+| Header | Meaning |
+| --- | --- |
+| `F-Values` | value keys the browser holds |
+| `F-Layouts` | the layouts on screen, as a JSON array of layout keys (pattern with params filled in) |
+| `F-Render: tree` | the browser can rebuild the page from its server tree; HTML may be left out |
+| `F-Render: document` | a navigation: the browser puts the whole page in place with DOM methods, so the server sends it in one piece (every Suspense boundary resolved, no streaming scripts) |
+
+Without a framework router, the browser runtime navigates itself: a same-site link click fetches
+the page with `F-Render: document` and `F-Values`, swaps the body in, starts the next page's
+islands, and handles history, scroll and focus. Anything unusual loads the page normally (another
+site, `target`, `download`, `rel="external"`, modifier keys, a non-HTML answer, or a page whose
+browser entry differs, as after a deploy).
+
+A server that leaves layouts out renders each kept layout as an empty boundary, and the browser
+keeps its own. If the response does not fit what is on screen, the browser loads the full
+document. All three headers make a response private, and the server sends `Vary` for each one
+it read.
+
+## Server actions
+
+An action id names one server function: a hash of its module's path from the app root and its
+export name (`inline:N` for the Nth inline action in the module). Ids are opaque to the browser.
+Every registered action is a public endpoint: anyone can call it with any arguments, so an
+action checks its inputs and the caller's rights like any other request handler.
+
+An action's **bound values** are the variables an inline action captured, then arguments added
+with `.bind` on the server. They travel sealed (below) and come before the call's own arguments.
+
+**Called from JavaScript:**
+
+```http
+POST /current/page
+F-Action: nSaHH8FImEr_M6
+Content-Type: text/plain;charset=UTF-8
+
+{"a":[…arguments, tagged…],"b":"…sealed…"}
+```
+
+A single `FormData` argument is sent as `multipart/form-data` instead, with the sealed values in
+the `$F_BOUND` field. Arguments that hold `FormData` or files anywhere (as `useActionState`'s
+`(previousState, formData)`) are sent as multipart too: the JSON goes in the `$F_CALL` field,
+attachment `n` is `{"$":"F","v":n}` or `{"$":"K","v":n}` in it, a file travels as field `$F_n`
+and a `FormData`'s fields as `$F_n_<name>`. The response is JSON: `{"result":…tagged…}` or `{"redirect":"/path"}`.
+Arguments may contain actions (`a`, with `b` when they carry sealed values) the server
+registered; never `r` or `s`. The browser runs calls one at a time, in order, and refreshes the
+page after each one (a redirect navigates instead).
+
+**Posted by a form without JavaScript:** React writes the fields while it renders the form, for
+`<form action>` and `<button formAction>`:
+
+```html
+<form action="" method="POST" enctype="multipart/form-data">
+  <input type="hidden" name="$F_REF_R_1_">
+  <input type="hidden" name="$F_R_1_:A" value="…action id…">
+  <input type="hidden" name="$F_R_1_:B" value="…sealed…">
+  <button name="$F_REF_R_2_">Delete</button>
+  <input type="hidden" name="$F_R_2_:A" value="…another action…">
+  …
+</form>
+```
+
+The last `$F_REF_` field a submission carries names the action, so a clicked button wins over
+its form. Every `$F_` field and `$ACTION_KEY` is removed before the action sees the form. The
+server answers `303 See Other` back to the page, or to the action's redirect. A form posted from
+a `useActionState` hook carries React's `$ACTION_KEY`; a server that can render the page renders
+it with React's form state `[result, $ACTION_KEY, id, bound count - 1]` instead of redirecting,
+and hydrates with the same.
+
+**Checks the server makes**, before running anything:
+
+- the method is `POST`, and the request names a same-origin source (`Origin`, then `Referer`,
+  then `Sec-Fetch-Site: same-origin`), or one from an origin the app allows;
+- the body is within the size limit (`413`); a form over the limit that does not post an action
+  is left to the app;
+- the id is registered; an unknown id is `404` with `F-Action-Stale: 1` for calls, and a `303`
+  back to the page for forms, so the browser loads the page this deploy renders;
+- arguments decode; malformed or unknown tags are `400`;
+- sealed values open for this id: values sealed with a key the server does not have are stale
+  (`409`, `F-Action-Stale: 1`), anything else that does not open is `400`, and so is an inline
+  action that captured values posted without them.
+
+A failing action answers `500` with no details; the error is reported on the server.
+
+**Forms in server components** belong to no island. Once the browser runtime runs, a submit of a
+form that posts an action is sent as a call (same fields, same checks) and the page refreshes,
+keeping island state; without JavaScript it posts as above.
+
+**Form state after a post.** A page rendered with React's form state carries it for hydration:
+`<script type="f/form-state">…tagged JSON…</script>`. Every island root hydrates with it.
+
+## Sealed captured values
+
+An action written inside a component may read variables of the render around it. Those values
+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;
+- 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.
+
+## Integration model
+
+islx is layered so each framework needs only a thin integration:
+
+| Layer | Package entry | Depends on |
+| --- | --- | --- |
+| Wire format and codec | `@farm.js/islx` | nothing (Web APIs) |
+| Server: values, sealing, action handling | `@farm.js/islx/server` | `@farm.js/islx` |
+| Browser: value store, hydration, navigation | `@farm.js/islx/client` | `@farm.js/islx` |
+| Renderer adapters | `@farm.js/islx/react` (then Preact, Vue, Svelte, Solid) | the renderer |
+| Compiler: `"use client"`, `"use server"`, inline actions | `@farm.js/islx/compiler` | a parser |
+| Bundler plugins | `@farm.js/islx/vite`, `@farm.js/islx/webpack`, `@farm.js/islx/rollup`, `@farm.js/islx/esbuild` | the compiler |
+| Frameworks | `@farm.js/islx/next`, `@farm.js/islx/astro`, `@farm.js/islx/nuxt`, … | the above |
+
+- **Request handling** is one function on Web `Request` and `Response`, so any server mounts it:
+  a Next.js route handler or middleware, a Nitro event handler, Astro middleware, Hono, Express
+  through an adapter.
+- **The compiler** is a pure function from source and environment (`server` or `client`) to
+  source, with no bundler in it. Each bundler plugin is a few lines around it, and Turbopack uses
+  the webpack loader.
+- **Conformance.** `@farm.js/islx/testing` will ship the contract suite: an implementation passes when its
+  fixture app passes it, in development and production.

package/dist/_chunks/actions-BCtIGvrP.d.mts

@@ -0,0 +1,58 @@
+import MagicString from "magic-string";
+
+// src/compiler/actions.d.ts
+/** An ESTree node with source offsets, as Rollup, Rolldown, oxc and acorn produce. */
+interface AstNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: any;
+}
+interface TransformActionsOptions {
+  /** The module's source. */
+  code: string;
+  /** The module's file path. */
+  id: string;
+  /** The app root: ids are made from paths relative to it, so they match on every machine. */
+  root: string;
+  /** Whether the output runs on the server or in the browser. */
+  environment: "server" | "client";
+  /** Parses JavaScript (or the language the plugin runs after) to an ESTree program. */
+  parse(code: string): AstNode;
+  /** Mixed into every id, so ids of one build are not guessable from another's. */
+  salt?: string;
+  /** The directive that marks actions, at the top of a module or a function. Default `"use server"`. */
+  directive?: string;
+  /** Where the runtime is imported from. */
+  runtime?: {
+    server?: string;
+    client?: string;
+  };
+}
+interface TransformActionsResult {
+  code: string;
+  map: ReturnType<MagicString["generateMap"]>;
+}
+/** A mistake in the source, with where it is. Bundlers show `loc` with a code frame. */
+declare class ActionCompileError extends Error {
+  readonly loc: {
+    file: string;
+    line: number;
+    column: number;
+  };
+  readonly id: string;
+  constructor(message: string, file: string, code: string, offset: number);
+}
+/**
+ * Whether the module's directive prologue (the strings before any other statement, after
+ * comments) holds `directive`. A linear scan, for a cheap check before parsing.
+ */
+declare function hasModuleDirective(code: string, directive: string): boolean;
+/** The id an action has on both sides: a hash of its module path from the root and its name. */
+declare function getActionId(root: string, file: string, name: string, salt?: string): string;
+/**
+ * Compiles a module's server actions, or returns null when it has none. Throws an
+ * `ActionCompileError` for a mistake, such as an inline action in browser code.
+ */
+declare function transformActions(options: TransformActionsOptions): TransformActionsResult | null;
+export { getActionId as a, TransformActionsResult as i, AstNode as n, hasModuleDirective as o, TransformActionsOptions as r, transformActions as s, ActionCompileError as t };