@farm.js/islx 0.0.0-stage → 0.0.1

package/dist/_chunks/codec-BTDkzzPP.mjs

@@ -0,0 +1,271 @@
+import { N as getTag } from "./wire-CXOodE06.mjs";
+// src/protocol/codec.ts
+/**
+* Values JSON cannot hold. Each travels as a tagged object: the reserved key `$` holds a short tag
+* and `v` holds the data.
+*
+*   undefined                 {"$":"u"}
+*   NaN, ±Infinity, -0        {"$":"n","v":"NaN"}
+*   12345678901234567890n     {"$":"B","v":"12345678901234567890"}
+*   new Date(…)               {"$":"D","v":"2026-10-28T09:00:00.000Z"}   (null for an invalid date)
+*   new Map([[k, v]])         {"$":"M","v":[[k, v]]}                      (keys and values tagged)
+*   new Set([v])              {"$":"S","v":[v]}
+*   new URL(…)                {"$":"U","v":"https://example.com/"}
+*   /ab+c/gi                  {"$":"R","v":["ab+c","gi"]}
+*   Uint8Array, ArrayBuffer…  {"$":"Y","v":["Uint8Array","base64…"]}
+*   app data with a "$" key   {"$":"o","v":{…}}                          (never read as a tag)
+*
+* Decoding accepts input from the browser (server action arguments): it builds plain objects
+* without assigning `__proto__`, and rejects unknown or malformed tags.
+*/
+const TYPED_ARRAYS = {
+	Int8Array,
+	Uint8Array,
+	Uint8ClampedArray,
+	Int16Array,
+	Uint16Array,
+	Int32Array,
+	Uint32Array,
+	Float32Array,
+	Float64Array,
+	BigInt64Array,
+	BigUint64Array
+};
+/** Standard base64 of bytes. */
+function toBase64(bytes) {
+	let binary = "";
+	for (let index = 0; index < bytes.length; index += 32768) binary += String.fromCharCode(...bytes.subarray(index, index + 32768));
+	return btoa(binary);
+}
+/** Bytes of standard base64. Throws on anything else. */
+function fromBase64(base64) {
+	const binary = atob(base64);
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index++) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+}
+/** A tagged object. */
+function tagged(tag, value) {
+	return value === void 0 ? { ["$"]: tag } : {
+		["$"]: tag,
+		["v"]: value
+	};
+}
+/** Whether a plain object must travel wrapped as `o`, because its own keys include `$`. */
+function needsObjectTag(object) {
+	return Object.prototype.hasOwnProperty.call(object, "$");
+}
+/**
+* The tag for a value JSON cannot hold and that has no children (everything above but `M`, `S`
+* and `o`), or undefined when the value needs none.
+*/
+function encodeLeaf(value) {
+	switch (typeof value) {
+		case "undefined": return tagged("u");
+		case "bigint": return tagged("B", value.toString());
+		case "number":
+			if (Number.isNaN(value)) return tagged("n", "NaN");
+			if (value === Infinity) return tagged("n", "Infinity");
+			if (value === -Infinity) return tagged("n", "-Infinity");
+			if (Object.is(value, -0)) return tagged("n", "-0");
+			return;
+		case "object": break;
+		default: return;
+	}
+	if (value === null) return void 0;
+	if (value instanceof Date) return tagged("D", Number.isNaN(value.getTime()) ? null : value.toISOString());
+	if (typeof URL === "function" && value instanceof URL) return tagged("U", value.href);
+	if (value instanceof RegExp) return tagged("R", [value.source, value.flags]);
+	if (value instanceof ArrayBuffer) return tagged("Y", ["ArrayBuffer", toBase64(new Uint8Array(value))]);
+	if (ArrayBuffer.isView(value)) {
+		const name = value instanceof DataView ? "DataView" : value.constructor.name;
+		if (name !== "DataView" && !(name in TYPED_ARRAYS)) return void 0;
+		return tagged("Y", [name, toBase64(new Uint8Array(value.buffer, value.byteOffset, value.byteLength))]);
+	}
+}
+/** Returned by `decodeTagged` for the runtime's reference tags (`r`, `s`, `a`). */
+const NOT_A_VALUE = Symbol.for("islx.codec.not-a-value");
+/** A plain object from entries; `defineProperty`, so a "__proto__" key stays an ordinary key. */
+function plainObject(entries) {
+	const object = {};
+	for (const [key, value] of entries) Object.defineProperty(object, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true
+	});
+	return object;
+}
+/**
+* The value a tagged object stands for, decoding children (a `Map`'s or `Set`'s entries, an `o`
+* object's properties) with `decodeChild`. Returns `NOT_A_VALUE` for the runtime's reference tags,
+* and throws for an unknown or malformed tag.
+*/
+function decodeTagged(object, decodeChild) {
+	const tag = object["$"];
+	const data = object["v"];
+	switch (tag) {
+		case "r":
+		case "s":
+		case "a":
+		case "F":
+		case "K": return NOT_A_VALUE;
+		case "o":
+			if (data && typeof data === "object" && !Array.isArray(data)) return plainObject(Object.entries(data).map(([key, value]) => [key, decodeChild(value)]));
+			break;
+		case "u": return;
+		case "n":
+			if (data === "NaN") return NaN;
+			if (data === "Infinity") return Infinity;
+			if (data === "-Infinity") return -Infinity;
+			if (data === "-0") return -0;
+			break;
+		case "B":
+			if (typeof data === "string" && /^-?\d+$/.test(data)) return BigInt(data);
+			break;
+		case "D":
+			if (data === null) return /* @__PURE__ */ new Date(NaN);
+			if (typeof data === "string") return new Date(data);
+			break;
+		case "U":
+			if (typeof data === "string") return new URL(data);
+			break;
+		case "R":
+			if (Array.isArray(data) && typeof data[0] === "string" && typeof data[1] === "string") return new RegExp(data[0], data[1]);
+			break;
+		case "Y": {
+			if (!Array.isArray(data) || typeof data[0] !== "string" || typeof data[1] !== "string") break;
+			const bytes = fromBase64(data[1]);
+			if (data[0] === "ArrayBuffer") return bytes.buffer;
+			if (data[0] === "DataView") return new DataView(bytes.buffer);
+			const TypedArray = Object.prototype.hasOwnProperty.call(TYPED_ARRAYS, data[0]) ? TYPED_ARRAYS[data[0]] : void 0;
+			if (!TypedArray || bytes.byteLength % TypedArray.BYTES_PER_ELEMENT !== 0) break;
+			return new TypedArray(bytes.buffer, 0, bytes.byteLength / TypedArray.BYTES_PER_ELEMENT);
+		}
+		case "M":
+			if (Array.isArray(data) && data.every((entry) => Array.isArray(entry) && entry.length === 2)) return new Map(data.map(([key, value]) => [decodeChild(key), decodeChild(value)]));
+			break;
+		case "S":
+			if (Array.isArray(data)) return new Set(data.map(decodeChild));
+			break;
+		default: throw new TypeError(`unknown ${JSON.stringify(tag)} tag`);
+	}
+	throw new TypeError(`malformed ${JSON.stringify(tag)} tag`);
+}
+/** Describes where in a value encoding failed, for error messages: `user.roles[2]`. */
+function describePath(path) {
+	return path.map((part, index) => typeof part === "number" ? `[${part}]` : /^[A-Za-z_$][\w$]*$/.test(part) ? `${index === 0 ? "" : "."}${part}` : `[${JSON.stringify(part)}]`).join("");
+}
+/** Thrown by `encode` for a value it cannot carry; names where the value sits. */
+var EncodeError = class extends TypeError {
+	/** Where the value sits, from the root: `["user", "roles", 2]`. */
+	path;
+	/** What is wrong with it: "functions are not serializable". */
+	reason;
+	constructor(reason, path) {
+		super(path.length > 0 ? `${describePath(path)}: ${reason}` : reason);
+		this.name = "EncodeError";
+		this.path = [...path];
+		this.reason = reason;
+	}
+	/** The path as written in code: `user.roles[2]`. */
+	get location() {
+		return describePath(this.path);
+	}
+};
+/**
+* Encodes a value for JSON with the tags above: plain objects, arrays and the types listed.
+* Symbols, class instances, circular values and (without `encodeFunction`) functions throw an
+* `EncodeError` that names where the value sits.
+*/
+function encode(value, options = {}) {
+	const seen = /* @__PURE__ */ new Set();
+	const path = [...options.path ?? []];
+	const fail = (reason) => {
+		throw new EncodeError(reason, path);
+	};
+	const visit = (value) => {
+		const leaf = encodeLeaf(value);
+		if (leaf) return leaf;
+		if (value === null || typeof value === "string" || typeof value === "boolean") return value;
+		if (typeof value === "number") return value;
+		if (typeof value === "function") {
+			const encoded = options.encodeFunction?.(value);
+			return encoded === void 0 ? fail("functions are not serializable") : encoded;
+		}
+		if (typeof value !== "object") return fail(`${typeof value} values are not serializable`);
+		if (seen.has(value)) return fail("circular values are not serializable");
+		seen.add(value);
+		try {
+			if (Array.isArray(value)) return value.map((entry, index) => {
+				path.push(index);
+				try {
+					return visit(entry);
+				} finally {
+					path.pop();
+				}
+			});
+			if (value instanceof Map) {
+				let index = 0;
+				return tagged("M", Array.from(value, ([key, entry]) => {
+					path.push(index++);
+					try {
+						return [visit(key), visit(entry)];
+					} finally {
+						path.pop();
+					}
+				}));
+			}
+			if (value instanceof Set) {
+				let index = 0;
+				return tagged("S", Array.from(value, (entry) => {
+					path.push(index++);
+					try {
+						return visit(entry);
+					} finally {
+						path.pop();
+					}
+				}));
+			}
+			if (typeof value.$$typeof === "symbol") return fail("elements (JSX) are not serializable");
+			const prototype = Object.getPrototypeOf(value);
+			if (prototype !== Object.prototype && prototype !== null) {
+				const special = options.encodeObject?.(value);
+				if (special !== void 0) return special;
+				const name = value.constructor?.name;
+				return fail(`class instances${name ? ` (${name})` : ""} are not serializable`);
+			}
+			const encoded = plainObject(Object.entries(value).map(([key, entry]) => {
+				path.push(key);
+				try {
+					return [key, visit(entry)];
+				} finally {
+					path.pop();
+				}
+			}));
+			return needsObjectTag(value) ? tagged("o", encoded) : encoded;
+		} finally {
+			seen.delete(value);
+		}
+	};
+	return visit(value);
+}
+/** Decodes what `encode` produced, after `JSON.parse`. Reference tags are rejected by default. */
+function decode(value, options = {}) {
+	const visit = (value) => {
+		if (Array.isArray(value)) return value.map(visit);
+		if (!value || typeof value !== "object") return value;
+		if (getTag(value) !== void 0) {
+			const object = value;
+			const decoded = decodeTagged(object, visit);
+			if (decoded !== NOT_A_VALUE) return decoded;
+			const reference = options.decodeReference?.(object);
+			if (reference !== void 0) return reference;
+			throw new TypeError(`a ${JSON.stringify(object["$"])} reference is not allowed here`);
+		}
+		if (needsObjectTag(value)) throw new TypeError("malformed \"$\" tag");
+		return plainObject(Object.entries(value).map(([key, entry]) => [key, visit(entry)]));
+	};
+	return visit(value);
+}
+export { encode as a, needsObjectTag as c, toBase64 as d, decodeTagged as i, plainObject as l, NOT_A_VALUE as n, encodeLeaf as o, decode as r, fromBase64 as s, EncodeError as t, tagged as u };

package/dist/_chunks/codec-CK8kZp4u.d.mts

@@ -0,0 +1,64 @@
+/** Standard base64 of bytes. */
+declare function toBase64(bytes: Uint8Array): string;
+/** Bytes of standard base64. Throws on anything else. */
+declare function fromBase64(base64: string): Uint8Array;
+/** A tagged object. */
+declare function tagged(tag: string, value?: unknown): Record<string, unknown>;
+/** Whether a plain object must travel wrapped as `o`, because its own keys include `$`. */
+declare function needsObjectTag(object: object): boolean;
+/**
+ * The tag for a value JSON cannot hold and that has no children (everything above but `M`, `S`
+ * and `o`), or undefined when the value needs none.
+ */
+declare function encodeLeaf(value: unknown): Record<string, unknown> | undefined;
+/** Returned by `decodeTagged` for the runtime's reference tags (`r`, `s`, `a`). */
+declare const NOT_A_VALUE: unique symbol;
+/** A plain object from entries; `defineProperty`, so a "__proto__" key stays an ordinary key. */
+declare function plainObject(entries: Iterable<[string, unknown]>): Record<string, unknown>;
+/**
+ * The value a tagged object stands for, decoding children (a `Map`'s or `Set`'s entries, an `o`
+ * object's properties) with `decodeChild`. Returns `NOT_A_VALUE` for the runtime's reference tags,
+ * and throws for an unknown or malformed tag.
+ */
+declare function decodeTagged(object: Record<string, unknown>, decodeChild: (value: unknown) => unknown): unknown;
+/** Thrown by `encode` for a value it cannot carry; names where the value sits. */
+declare class EncodeError extends TypeError {
+  /** Where the value sits, from the root: `["user", "roles", 2]`. */
+  readonly path: readonly (string | number)[];
+  /** What is wrong with it: "functions are not serializable". */
+  readonly reason: string;
+  constructor(reason: string, path: readonly (string | number)[]);
+  /** The path as written in code: `user.roles[2]`. */
+  get location(): string;
+}
+interface EncodeOptions {
+  /**
+   * Encodes a function, such as a server action, or returns undefined to refuse it. Without it,
+   * functions throw.
+   */
+  encodeFunction?: (value: Function) => unknown;
+  /**
+   * Encodes an object the codec cannot carry itself (`FormData`, a `Blob`), or returns
+   * undefined to refuse it.
+   */
+  encodeObject?: (value: object) => unknown;
+  /** Names the root of the value in error messages. */
+  path?: readonly (string | number)[];
+}
+/**
+ * Encodes a value for JSON with the tags above: plain objects, arrays and the types listed.
+ * Symbols, class instances, circular values and (without `encodeFunction`) functions throw an
+ * `EncodeError` that names where the value sits.
+ */
+declare function encode(value: unknown, options?: EncodeOptions): unknown;
+interface DecodeOptions {
+  /**
+   * Decodes one of the runtime's reference tags (`r`, `s`, `a`), or returns undefined to refuse
+   * it. Without it, every reference throws: input from a browser must not name the runtime's own
+   * references unless the caller checks them.
+   */
+  decodeReference?: (object: Record<string, unknown>) => unknown;
+}
+/** Decodes what `encode` produced, after `JSON.parse`. Reference tags are rejected by default. */
+declare function decode(value: unknown, options?: DecodeOptions): unknown;
+export { decode as a, encodeLeaf as c, plainObject as d, tagged as f, NOT_A_VALUE as i, fromBase64 as l, EncodeError as n, decodeTagged as o, toBase64 as p, EncodeOptions as r, encode as s, DecodeOptions as t, needsObjectTag as u };

package/dist/_chunks/handle-C0N9ZyNV.d.mts

@@ -0,0 +1,35 @@
+/** React's form state: the result, the hook it belongs to, the action id, its bound count. */
+type ReactFormState = [state: unknown, key: string, referenceId: string, boundCount: number];
+interface ActionErrorOutcome {
+  /** Send the browser here: a 303 for forms, `{"redirect"}` for calls. */
+  redirect?: string;
+  /** Answer with this status (and no details). */
+  status?: number;
+}
+interface HandleActionOptions {
+  /** Origins or hosts, besides the request's own, that may post actions: `*.example.com`. */
+  allowedOrigins?: readonly string[];
+  /** The largest body accepted, in bytes. Default 1 MB. */
+  bodySizeLimit?: number;
+  /**
+   * Runs the action, so the framework can give it the request's context (cookies, headers,
+   * an abort signal).
+   */
+  run?<T>(request: Request, action: () => Promise<T>): Promise<T>;
+  /**
+   * Maps an error the action threw to a redirect or a status: the framework's `redirect()` and
+   * `notFound()`. Anything unmapped is a 500, logged with `onError`.
+   */
+  mapError?(error: unknown): ActionErrorOutcome | undefined;
+  /**
+   * Renders the page after a form posted from a `useActionState` hook, with the action's result
+   * as React's `formState` (`renderToReadableStream(…, { formState })`, and the same to
+   * `hydrateRoot`). Without it, the form redirects back and the result is not shown.
+   */
+  renderFormState?(formState: ReactFormState, request: Request): Response | Promise<Response>;
+  /** Reports an action that failed. Default `console.error`. */
+  onError?(error: unknown): void;
+}
+/** Runs the server action a request posts, or returns null when it posts none. */
+declare function handleAction(request: Request, options?: HandleActionOptions): Promise<Response | null>;
+export { handleAction as i, HandleActionOptions as n, ReactFormState as r, ActionErrorOutcome as t };

package/dist/_chunks/hooks-3VZV8f_d.d.mts

@@ -0,0 +1,30 @@
+import { t as ActionErrorOutcome } from "./handle-C0N9ZyNV.mjs";
+
+// src/server/hooks.d.ts
+
+interface ActionInfo {
+  request: Request;
+  /** The action's id. */
+  id: string;
+  /** Its export name, or the inline function's name. */
+  name: string;
+  /** Its module, from the app root. */
+  module: string;
+}
+interface ServerHooks {
+  /**
+   * Wraps every action: check the caller, rate-limit, log, time. Call `run` to run the action,
+   * and return what it returns; throw to refuse (`actionError` maps the error to a response).
+   */
+  action?(info: ActionInfo, run: () => Promise<unknown>): Promise<unknown>;
+  /** Maps an error an action threw to a redirect or a status: a framework's `redirect()`. */
+  actionError?(error: unknown, info: ActionInfo): ActionErrorOutcome | undefined;
+  /** Reports an action that failed with an error nothing mapped. */
+  error?(error: unknown, info: ActionInfo): void;
+}
+/** Types an app's server hooks. */
+declare function defineServerHooks(hooks: ServerHooks): ServerHooks;
+/** Installs the app's hooks; the plugin's server runtime calls it. */
+declare function setServerHooks(hooks: ServerHooks | undefined): void;
+declare function getServerHooks(): ServerHooks;
+export { setServerHooks as a, getServerHooks as i, ServerHooks as n, defineServerHooks as r, ActionInfo as t };

package/dist/_chunks/hooks-De0gNpOn.d.mts

@@ -0,0 +1,64 @@
+import { n as IslandStrategy } from "./schedule-Dw14dW0H.mjs";
+
+// src/client/hooks.d.ts
+
+interface ClientHookEvents {
+  /** Before the next page is fetched. `preventDefault()` stays on this page. */
+  navigate: {
+    url: URL;
+    from: URL;
+    kind: "link" | "history" | "code";
+  };
+  /** The next page is in place. */
+  navigated: {
+    url: URL;
+    duration: number;
+  };
+  /** A navigation fell back to loading the page the ordinary way. */
+  navigateError: {
+    url: URL;
+    reason: string;
+  };
+  /** An island became interactive: `duration` runs from scheduling to React's first commit. */
+  hydrate: {
+    element: Element;
+    src: string;
+    export: string;
+    strategy: IslandStrategy;
+    duration: number;
+  };
+  /** An island failed; its server HTML was restored. */
+  islandError: {
+    element: Element;
+    src: string;
+    export: string;
+    error: unknown;
+  };
+  /** A server action call starts. `name` is the export (or inline function) name when known. */
+  action: {
+    id: string;
+    name?: string;
+  };
+  /** A server action call finished. */
+  actionEnd: {
+    id: string;
+    name?: string;
+    ok: boolean;
+    duration: number;
+    redirect?: string;
+    error?: unknown;
+  };
+}
+type ClientHookEvent<Name extends keyof ClientHookEvents> = ClientHookEvents[Name] & {
+  /** Only `navigate` can be cancelled. */
+  preventDefault(): void;
+  readonly defaultPrevented: boolean;
+};
+type ClientHooks = { [Name in keyof ClientHookEvents]?: (event: ClientHookEvent<Name>) => void };
+/** Types an app's hooks module. */
+declare function defineClientHooks(hooks: ClientHooks): ClientHooks;
+/** Installs the app's hooks; the plugin's browser entry calls it. */
+declare function setClientHooks(hooks: ClientHooks | undefined): void;
+/** The DOM event name of a hook: `navigateError` → `f:navigate-error`. */
+declare function hookEventName(name: keyof ClientHookEvents): string;
+export { hookEventName as a, defineClientHooks as i, ClientHookEvents as n, setClientHooks as o, ClientHooks as r, ClientHookEvent as t };

package/dist/_chunks/prehydration-B1GLTLdk.mjs

@@ -0,0 +1,36 @@
+// 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),
+* and announces a pointerdown or a focus (which go through). The runtime then hydrates those
+* islands first and replays what was held.
+*
+* The script is inlined into every page, so it stays hand-minified and imports nothing.
+*/
+/** Where the inline script queues held interactions: `{ target, kind }`. */
+const PENDING_INTERACTIONS = "__islxPending";
+/** The DOM event the script dispatches for each interaction it sees. */
+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)})();`;
+/** Takes the interactions the inline script held inside `container`, oldest first. */
+function takePendingInteractions(container) {
+	const queue = globalThis[PENDING_INTERACTIONS];
+	if (!Array.isArray(queue)) return [];
+	const taken = [];
+	for (let index = queue.length - 1; index >= 0; index--) {
+		const item = queue[index];
+		if (!(item?.target instanceof Element) || !container.contains(item.target)) continue;
+		queue.splice(index, 1);
+		taken.unshift(item);
+	}
+	return taken;
+}
+/** Whether the inline script holds an interaction inside `container`. */
+function hasPendingInteraction(container) {
+	const queue = globalThis[PENDING_INTERACTIONS];
+	return Array.isArray(queue) && queue.some((item) => item?.target instanceof Element && container.contains(item.target));
+}
+export { hasPendingInteraction as a, REPLAYABLE_SELECTOR as i, PENDING_INTERACTIONS as n, takePendingInteractions as o, PREHYDRATION_SCRIPT as r, INTERACTION_EVENT as t };