ilha 0.10.3 → 0.11.1

package/README.md

@@ -331,7 +331,7 @@ Both the user-supplied cleanup function (if any) and the signal abort fire when
 
 ### `.onMount(fn)`
 
-Runs once after the island is mounted into the DOM. Receives `{ state, derived, input, host, hydrated }` where `hydrated` is `true` when the island was mounted over existing SSR content. Optionally returns a cleanup function called on unmount.
+Runs once after the island is mounted into the DOM. **Client-only** — SSR never invokes it (matching `.on()` and `.effect()`), so server-rendered markup must not depend on onMount side effects. Receives `{ state, derived, input, host, hydrated }` where `hydrated` is `true` when the island was mounted over existing SSR content. Optionally returns a cleanup function called on unmount.
 
 ```ts
 ilha
@@ -538,7 +538,8 @@ Use `await island(props)` instead when asynchronous derived values must settle b
 ```ts
 MyIsland.toString(); // always sync
 MyIsland.toString({ name: "Ilha" }); // with props
-await MyIsland({ name: "Ilha" }); // async — awaits derived
+await MyIsland.toStringAsync({ name: "Ilha" }); // async SSR — awaits async derived values
+await MyIsland({ name: "Ilha" }); // callable async form (also used for JSX/html slot composition)
 ```
 
 ---
@@ -666,6 +667,8 @@ theme("dark"); // → sets to "dark"
 Safe to call in both SSR and browser environments.
 
 > **`signal()` vs `context()`** — both return the same accessor shape and can be used with `bind:` template syntax. Use `signal()` for one-off shared state where you'd hold the reference yourself; use `context()` when you want a name-keyed registry so the same signal can be looked up from anywhere by string key.
+>
+> **SSR caveat** — `context()` is process-global, not request-scoped. It is safe to read in SSR **only for app-wide singletons** (theme, locale, feature flags). Per-request state (current user, session) must not live in `context()`: concurrent SSR requests would leak it across requests. Pass per-request data through island props / loaders or use `@ilha/router`'s request-scope instead.
 
 ---
 

package/dist/{index-BDM797j2.d.ts → index-DnoM0M8S.d.ts}

@@ -178,6 +178,12 @@ interface HydratableOptions {
 interface Island<TInput = Record<string, unknown>, _TStateMap extends Record<string, unknown> = Record<string, unknown>> {
   (props?: Partial<TInput>): string | Promise<string>;
   toString(props?: Partial<TInput>): string;
+  /**
+   * Async SSR: renders the island and awaits async `.derived()` values before
+   * returning the HTML string. Always returns a Promise — prefer this over
+   * `await island(props)` when you need the async SSR form by name.
+   */
+  toStringAsync(props?: Partial<TInput>): Promise<string>;
   mount(host: Element, props?: Partial<TInput>): () => void;
   hydratable(props: Partial<TInput>, options: HydratableOptions): Promise<string>;
   key(key: string): KeyedIsland<TInput>;
@@ -285,6 +291,20 @@ interface StateEntry<TInput> {
   key: string;
   init: StateInit<TInput, unknown>;
 }
+/** A state key fed by a generator (`.stream()`). The runtime iterates the
+ * generator and writes each yielded value into the state signal. During SSR
+ * only the first value is pulled so it can render inline; on the client the
+ * generator is consumed continuously. */
+interface StreamEntry<TInput> {
+  key: string;
+  fn: StreamFn<TInput>;
+}
+type StreamFnContext<TInput> = {
+  input: TInput;
+  /** Aborts when the island unmounts. Pass through to fetch/SSE layers. */
+  signal: AbortSignal;
+};
+type StreamFn<TInput, V = unknown> = (ctx: StreamFnContext<TInput>) => AsyncGenerator<V> | Generator<V>;
 interface ActionEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
   key: string;
   fn: (props: unknown, ctx: ActionContext<TInput, TStateMap, TDerivedMap>) => unknown;
@@ -302,7 +322,7 @@ interface EffectEntry<TInput, TStateMap extends Record<string, unknown>, TDerive
 /** Where the error originated. `"on"` covers sync throws and async rejections
  *  from `.on()` handlers; `"effect"` covers sync throws from `.effect()` runs
  *  (async work spawned inside an effect is not awaited by the runtime). */
-type ErrorSource = "on" | "effect" | "mount" | "transition" | "action";
+type ErrorSource = "on" | "effect" | "mount" | "transition" | "action" | "stream";
 /**
  * Register a global error handler invoked when any island reports an error
  * (from .on, .effect, .onMount, or transitions) and has no local .onError()
@@ -341,6 +361,7 @@ interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDeri
   /** Shallow defaults merged before props (POJO `.input({ ... })` only). */
   defaultInput: Record<string, unknown> | null;
   states: StateEntry<TInput>[];
+  streams: StreamEntry<TInput>[];
   deriveds: DerivedEntry<TInput, TStateMap>[];
   actions: ActionEntry<TInput, TStateMap, TDerivedMap>[];
   ons: OnEntry<TInput, TStateMap, TDerivedMap, TActionMap>[];
@@ -360,6 +381,7 @@ declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap exte
   input<T extends Record<string, unknown>>(defaults: T): IlhaBuilder<T, Record<never, never>, Record<never, never>, Record<never, never>>;
   as<Tag extends string>(tag: Tag): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
   state<V = undefined, K extends string = string>(key: K, init?: StateInit<TInput, V> | undefined): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap, TActionMap>;
+  stream<K extends string, V>(key: K, fn: StreamFn<TInput, V>): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap, TActionMap>;
   derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>, TActionMap>;
   action<K extends string, P = undefined, R = void>(key: K, fn: (props: P, ctx: ActionContext<TInput, TStateMap, TDerivedMap>) => R): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap & Record<K, typeof fn>>;
   on<S extends string>(selectorOrCombined: S, handler: (ctx: S extends `${string}@${infer E}:${string}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap, TActionMap> : S extends `${string}@${infer E}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap, TActionMap> : HandlerContext<TInput, TStateMap, TDerivedMap, TActionMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
@@ -392,6 +414,7 @@ declare const ilha: RootBuilder & DirectIslandFactory & {
   };
   signal: typeof ilhaSignal;
   computed: typeof ilhaComputed;
+  morph: typeof morph;
   batch: typeof batch;
   untrack: typeof untrack;
   onUncaughtError: typeof onUncaughtError;
@@ -408,6 +431,12 @@ declare function __ilhaJsxSlot({ island, props, key }: {
   props: Record<string, unknown> | undefined;
   key: string | undefined;
 }): RawHtml;
+/**
+ * Morph an element's children toward `html`, patching in place: surviving
+ * elements keep their identity, listeners, and focus (see the morph engine).
+ * Falls back to an innerHTML write when the root tags don't match.
+ */
+declare function morph(host: Element, html: string): void;
 declare const html: typeof ilhaHtml;
 declare const raw: typeof ilhaRaw;
 declare const css: typeof ilhaCss;
@@ -420,4 +449,4 @@ declare const context: typeof ilhaContextFn & {
   clear(): void;
 };
 //#endregion
-export { __ilhaJsxSlot as A, mount as B, NativeEventModifier as C, SignalSetter as D, SignalAccessor as E, html as F, raw as H, ilha as I, ilhaComputed as L, context as M, css as N, SignalWriter as O, from as P, ilhaEffect as R, NativeEventHandler as S, RawHtml as T, untrack as U, onUncaughtError as V, IslandState as _, EffectContext as a, MountResult as b, ExternalSignal as c, HydratableOptions as d, ISLAND_MOUNT_HANDLES as f, IslandDerived as g, IslandActions as h, DerivedValue as i, batch as j, __ilhaJsxEvent as k, HandlerContext as l, Island as m, ActionContext as n, ErrorContext as o, ISLAND_MOUNT_INTERNAL as p, DerivedAccessor as r, ErrorSource as s, ActionAccessor as t, HandlerContextFor as u, KeyedIsland as v, OnMountContext as w, NativeEventContext as x, MountOptions as y, ilhaSignal as z };
+export { StreamFnContext as A, ilhaEffect as B, NativeEventModifier as C, SignalSetter as D, SignalAccessor as E, css as F, raw as G, morph as H, from as I, untrack as K, html as L, __ilhaJsxSlot as M, batch as N, SignalWriter as O, context as P, ilha as R, NativeEventHandler as S, RawHtml as T, mount as U, ilhaSignal as V, onUncaughtError as W, IslandState as _, EffectContext as a, MountResult as b, ExternalSignal as c, HydratableOptions as d, ISLAND_MOUNT_HANDLES as f, IslandDerived as g, IslandActions as h, DerivedValue as i, __ilhaJsxEvent as j, StreamFn as k, HandlerContext as l, Island as m, ActionContext as n, ErrorContext as o, ISLAND_MOUNT_INTERNAL as p, DerivedAccessor as r, ErrorSource as s, ActionAccessor as t, HandlerContextFor as u, KeyedIsland as v, OnMountContext as w, NativeEventContext as x, MountOptions as y, ilhaComputed as z };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { A as __ilhaJsxSlot, B as mount, C as NativeEventModifier, D as SignalSetter, E as SignalAccessor, F as html, H as raw, I as ilha, L as ilhaComputed, M as context, N as css, O as SignalWriter, P as from, R as ilhaEffect, S as NativeEventHandler, T as RawHtml, U as untrack, V as onUncaughtError, _ as IslandState, a as EffectContext, b as MountResult, c as ExternalSignal, d as HydratableOptions, f as ISLAND_MOUNT_HANDLES, g as IslandDerived, h as IslandActions, i as DerivedValue, j as batch, k as __ilhaJsxEvent, l as HandlerContext, m as Island, n as ActionContext, o as ErrorContext, p as ISLAND_MOUNT_INTERNAL, r as DerivedAccessor, s as ErrorSource, t as ActionAccessor, u as HandlerContextFor, v as KeyedIsland, w as OnMountContext, x as NativeEventContext, y as MountOptions, z as ilhaSignal } from "./index-BDM797j2.js";
-export { ActionAccessor, ActionContext, DerivedAccessor, DerivedValue, EffectContext, ErrorContext, ErrorSource, ExternalSignal, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_HANDLES, ISLAND_MOUNT_INTERNAL, Island, IslandActions, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, NativeEventContext, NativeEventHandler, NativeEventModifier, OnMountContext, RawHtml, SignalAccessor, SignalSetter, SignalWriter, __ilhaJsxEvent, __ilhaJsxSlot, batch, ilhaComputed as computed, context, css, ilha as default, ilhaEffect as effect, from, html, ilhaSignal, ilhaSignal as signal, mount, onUncaughtError, raw, untrack };
+import { A as StreamFnContext, B as ilhaEffect, C as NativeEventModifier, D as SignalSetter, E as SignalAccessor, F as css, G as raw, H as morph, I as from, K as untrack, L as html, M as __ilhaJsxSlot, N as batch, O as SignalWriter, P as context, R as ilha, S as NativeEventHandler, T as RawHtml, U as mount, V as ilhaSignal, W as onUncaughtError, _ as IslandState, a as EffectContext, b as MountResult, c as ExternalSignal, d as HydratableOptions, f as ISLAND_MOUNT_HANDLES, g as IslandDerived, h as IslandActions, i as DerivedValue, j as __ilhaJsxEvent, k as StreamFn, l as HandlerContext, m as Island, n as ActionContext, o as ErrorContext, p as ISLAND_MOUNT_INTERNAL, r as DerivedAccessor, s as ErrorSource, t as ActionAccessor, u as HandlerContextFor, v as KeyedIsland, w as OnMountContext, x as NativeEventContext, y as MountOptions, z as ilhaComputed } from "./index-DnoM0M8S.js";
+export { ActionAccessor, ActionContext, DerivedAccessor, DerivedValue, EffectContext, ErrorContext, ErrorSource, ExternalSignal, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_HANDLES, ISLAND_MOUNT_INTERNAL, Island, IslandActions, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, NativeEventContext, NativeEventHandler, NativeEventModifier, OnMountContext, RawHtml, SignalAccessor, SignalSetter, SignalWriter, StreamFn, StreamFnContext, __ilhaJsxEvent, __ilhaJsxSlot, batch, ilhaComputed as computed, context, css, ilhaEffect as effect, from, html, ilha, ilhaSignal, ilhaSignal as signal, morph, mount, onUncaughtError, raw, untrack };

package/dist/index.js

@@ -127,13 +127,21 @@ function isStableInlineSlotMount({ initialHtml, renderedHtml, slotIds }) {
 * map (client) and/or the inlined SSR subtree — never depend on the attr for them.
 * RawHtml is tagged so a rare attr-only mount can revive `Symbol.for("ilha.raw")`.
 */
-function slotPropsForAttr(props) {
+function slotPropsForAttr(props, captureActions = false) {
 	if (props === void 0) return void 0;
 	let out;
 	for (const key of Object.keys(props)) {
 		if (key === "children") continue;
 		const value = props[key];
-		if (typeof value === "function" || typeof value === "symbol") continue;
+		if (typeof value === "function") {
+			const action = captureActions ? captureHandlerActions(value) : void 0;
+			if (action) (out ??= {})[key] = {
+				__ilha: "action",
+				...action
+			};
+			continue;
+		}
+		if (typeof value === "symbol") continue;
 		const encoded = encodeSlotPropValue(value);
 		if (encoded === void 0 && value !== void 0 && value !== null) continue;
 		(out ??= {})[key] = encoded;
@@ -471,11 +479,25 @@ const ASTRO_RENDERER_GLOBAL = Symbol.for("ilha.astroRenderer");
 * re-renders. Not part of the public surface. */
 const ISLAND_MOUNT_INTERNAL = Symbol.for("ilha.islandMountInternal");
 const ISLAND_SLOT_TAG = Symbol.for("ilha.islandSlotTag");
+const ISLAND_CLIENT_REF = Symbol.for("ilha.clientRef");
 /** @internal Live mount handles keyed by host element. Lets @ilha/router adopt
 * islands hydrated by `ilha.mount()` (whose handles it never saw) and push new
 * loader props into them in place instead of remounting. Entries are removed
 * on unmount. Not part of the public surface. */
 const ISLAND_MOUNT_HANDLES = /* @__PURE__ */ new WeakMap();
+/** @internal Sync re-render of an island from a state snapshot. Attached by
+* render(); used by server-frame endpoints to produce HTML for streamed
+* updates without a live mount. Not part of the public surface. */
+const ISLAND_RENDER_STATE = Symbol.for("ilha.renderState");
+/** @internal Async SSR render that records the event→action manifest into the
+* provided map. Used by emitIslandSlot so nested server islands ship their
+* interactive surface alongside their inlined HTML. */
+const ISLAND_SSR_MANIFEST = Symbol.for("ilha.ssrManifest");
+function manifestTemplatePrefix(manifest) {
+	if (manifest.size === 0) return "";
+	const json = escapeHtml(JSON.stringify(Object.fromEntries(manifest)));
+	return `<template ${ACTIONS_ATTR}='${json}'></template>`;
+}
 const SLOT_ATTR = "data-ilha-slot";
 /** Marks a slot host whose child island is mid leave-transition: it has been
 * unmounted (and its slot id stripped) but stays connected so the leave
@@ -483,25 +505,63 @@ const SLOT_ATTR = "data-ilha-slot";
 * or mutating them. */
 const LEAVING_ATTR = "data-ilha-leaving";
 const PROPS_ATTR = "data-ilha-props";
+const CLIENT_REF_ATTR = "data-ilha-client-ref";
 const STATE_ATTR = "data-ilha-state";
 const CSS_ATTR = "data-ilha-css";
+/** Hydration manifest mapping `${type}:${index}` event-sentinel pairs to the
+* action keys that own them. Emitted by hydratable(); lets server-owned
+* islands (whose render fn never ships to the client) reconnect their
+* interactive surface. */
+const ACTIONS_ATTR = "data-ilha-actions";
 function buildScopedStyle(css) {
 	const safeCss = css.replace(/<\/style/gi, "<\\/style");
 	return `<style ${CSS_ATTR}>@scope (:scope) to ([data-ilha]){${safeCss}}</style>`;
 }
+/** Marks SSR action stubs so event registration never capture-invokes them
+* (invoking the real action body during render would run its side effects). */
+const SSR_ACTION_STUB = Symbol.for("ilha.ssrActionStub");
+const captureStack = [];
+/**
+* Invoke a forwarding closure once against sentinel arguments so any
+* `action.x(...)` call inside it is RECORDED, not executed. Returns the first
+* recorded call, or undefined when the closure throws or calls no action.
+*
+* ponytail: the closure body really executes once per manifest render (SSR
+* and every frame) — only the action call is intercepted. Handlers must be
+* pure "call one action" thunks; side effects before/around the action call
+* run server-side on every frame. Upgrade path: static-scan the closure
+* instead of invoking it.
+*/
+function captureHandlerActions(handler) {
+	const frame = [];
+	captureStack.push(frame);
+	try {
+		const result = handler({
+			preventDefault: () => {},
+			stopPropagation: () => {},
+			stopImmediatePropagation: () => {},
+			persist: () => {}
+		}, { signal: new AbortController().signal });
+		Promise.resolve(result).catch(() => {});
+	} catch {} finally {
+		captureStack.pop();
+	}
+	return frame[0];
+}
 const RENDER_CTX_STACK = Symbol.for("ilha.renderCtxStack");
 function renderCtxStack() {
 	const g = globalThis;
 	return g[RENDER_CTX_STACK] ??= [];
 }
-function pushRenderCtx(liveHost, asyncChildren) {
+function pushRenderCtx(liveHost, asyncChildren, manifest) {
 	const ctx = {
 		slots: /* @__PURE__ */ new Map(),
 		positional: 0,
 		liveHost,
 		pending: asyncChildren ? /* @__PURE__ */ new Map() : void 0,
 		binds: [],
-		events: []
+		events: [],
+		manifest
 	};
 	renderCtxStack().push(ctx);
 	return ctx;
@@ -531,8 +591,9 @@ function emitIslandSlot({ island, props, key }) {
 		props
 	});
 	const slotTag = getIslandSlotTag(island);
-	const attrProps = slotPropsForAttr(props);
-	const propsAttr = attrProps ? ` ${PROPS_ATTR}='${escapeHtml(JSON.stringify(attrProps))}'` : "";
+	const clientRef = island[ISLAND_CLIENT_REF];
+	const attrProps = slotPropsForAttr(props, typeof clientRef === "string" && ctx?.manifest === true);
+	const propsAttr = (attrProps ? ` ${PROPS_ATTR}='${escapeHtml(JSON.stringify(attrProps))}'` : "") + (typeof clientRef === "string" ? ` ${CLIENT_REF_ATTR}="${escapeHtml(clientRef)}"` : "");
 	if (ctx?.liveHost) return wrapIslandSlotHtml({
 		tag: slotTag,
 		id,
@@ -542,9 +603,12 @@ function emitIslandSlot({ island, props, key }) {
 	if (ctx?.pending) {
 		popRenderCtx();
 		try {
-			const result = island(props);
+			const manifest = /* @__PURE__ */ new Map();
+			const ssrWithManifest = island[ISLAND_SSR_MANIFEST];
+			const result = ssrWithManifest ? ssrWithManifest(props, manifest) : island(props);
+			const prefix = () => manifestTemplatePrefix(manifest);
 			if (result instanceof Promise) {
-				ctx.pending.set(id, result.then(String));
+				ctx.pending.set(id, result.then(String).then((html) => prefix() + html));
 				return wrapIslandSlotHtml({
 					tag: slotTag,
 					id,
@@ -556,7 +620,7 @@ function emitIslandSlot({ island, props, key }) {
 				tag: slotTag,
 				id,
 				propsAttr,
-				inner: String(result)
+				inner: prefix() + String(result)
 			});
 		} finally {
 			renderCtxStack().push(ctx);
@@ -853,6 +917,8 @@ function ilhaHtml(strings, ...values) {
 			const modifier = NATIVE_EVENT_MODIFIERS.has(rawModifier) ? rawModifier : void 0;
 			const openQuote = eventMatch[3] ?? null;
 			const cleanPrefix = chunk.slice(0, eventMatchStart).replace(/\s+$/, "");
+			const isActionStub = typeof value === "function" && SSR_ACTION_STUB in value;
+			const capture = ctx?.manifest && typeof value === "function" && !isActionStub ? captureHandlerActions(value) : void 0;
 			result += cleanPrefix;
 			if (ctx && typeof value === "function") {
 				const index = ctx.events.length;
@@ -860,7 +926,8 @@ function ilhaHtml(strings, ...values) {
 					ctx.events.push({
 						type: eventName,
 						handler: value,
-						modifier
+						modifier,
+						capture
 					});
 					pendingEventSpecs += (pendingEventSpecs ? "," : "") + `${eventName}:${index}`;
 				}
@@ -1623,12 +1690,15 @@ var IlhaBuilder = class IlhaBuilder {
 	input(initialOrSchema) {
 		let schema = null;
 		let defaultInput = null;
-		if (initialOrSchema !== void 0) if (isStandardSchema(initialOrSchema)) schema = initialOrSchema;
-		else defaultInput = initialOrSchema;
+		if (initialOrSchema !== void 0) {
+			if (isStandardSchema(initialOrSchema)) schema = initialOrSchema;
+			else defaultInput = initialOrSchema;
+		}
 		return new IlhaBuilder({
 			schema,
 			defaultInput,
 			states: [],
+			streams: [],
 			deriveds: [],
 			actions: [],
 			ons: [],
@@ -1656,6 +1726,21 @@ var IlhaBuilder = class IlhaBuilder {
 			}]
 		});
 	}
+	stream(key, fn) {
+		const cfg = this._cfg;
+		const states = cfg.states.some((entry) => entry.key === key) ? cfg.states : [...cfg.states, {
+			key,
+			init: void 0
+		}];
+		return new IlhaBuilder({
+			...cfg,
+			states,
+			streams: [...cfg.streams.filter((entry) => entry.key !== key), {
+				key,
+				fn
+			}]
+		});
+	}
 	derived(key, fn) {
 		const cfg = this._cfg;
 		return new IlhaBuilder({
@@ -1729,7 +1814,7 @@ var IlhaBuilder = class IlhaBuilder {
 		});
 	}
 	render(fn) {
-		const { schema, defaultInput, states, deriveds, actions, ons, effects, onMounts, onErrors, transition, css: cssSource, as: slotAs } = this._cfg;
+		const { schema, defaultInput, states, streams, deriveds, actions, ons, effects, onMounts, onErrors, transition, css: cssSource, as: slotAs } = this._cfg;
 		const stylePrefix = cssSource == null ? "" : buildScopedStyle(cssSource);
 		const configuredSlotTag = slotAs ?? "div";
 		function resolveInput(props) {
@@ -1740,8 +1825,8 @@ var IlhaBuilder = class IlhaBuilder {
 			if (!schema) return merged;
 			return validateSchema(schema, merged);
 		}
-		function renderWithCtx({ render, liveHost, asyncChildren }) {
-			const ctx = pushRenderCtx(liveHost, asyncChildren);
+		function renderWithCtx({ render, liveHost, asyncChildren, manifest }) {
+			const ctx = pushRenderCtx(liveHost, asyncChildren, manifest);
 			try {
 				const html = unwrapHtml(render());
 				const slots = ctx.slots;
@@ -1794,8 +1879,19 @@ var IlhaBuilder = class IlhaBuilder {
 		}
 		function buildSsrActions() {
 			const out = {};
+			const lookup = /* @__PURE__ */ new Map();
 			for (const entry of actions) {
-				const invoke = () => {};
+				const invoke = (...callArgs) => {
+					const frame = captureStack[captureStack.length - 1];
+					if (frame) {
+						if (!frame.some((r) => r.k === entry.key)) frame.push({
+							k: entry.key,
+							a: callArgs
+						});
+						return;
+					}
+				};
+				invoke[SSR_ACTION_STUB] = true;
 				Object.defineProperties(invoke, {
 					pending: {
 						get: () => false,
@@ -1811,80 +1907,52 @@ var IlhaBuilder = class IlhaBuilder {
 					}
 				});
 				out[entry.key] = invoke;
+				lookup.set(invoke, entry.key);
 			}
-			return out;
-		}
-		/** Detached host for SSR setup hooks; must not be `{}` (Areia/components call host.matches). */
-		function createSsrOnMountHost() {
-			if (typeof document !== "undefined") return document.createElement("div");
-			const stub = {
-				matches: () => false,
-				querySelector: () => null,
-				querySelectorAll: () => [],
-				setAttribute: () => {},
-				getAttribute: () => null,
-				removeAttribute: () => {},
-				appendChild: () => stub
+			return {
+				action: out,
+				lookup
 			};
-			return stub;
 		}
-		/** Run .onMount() before top-level SSR only (seed module/external state from `input`). */
-		function runOnMountForRender({ input, state, derived, action }) {
-			if (onMounts.length === 0) return;
-			if (currentRenderCtx()) return;
-			const host = createSsrOnMountHost();
-			const controller = new AbortController();
-			const ssrCleanups = [];
-			for (const entry of onMounts) {
-				const prevSub = setActiveSub(void 0);
-				let userCleanup;
-				try {
-					userCleanup = entry.fn({
-						state,
-						derived,
-						action,
-						input,
-						host,
-						hydrated: false,
-						signal: controller.signal
-					});
-				} catch (err) {
-					const error = err instanceof Error ? err : new Error(String(err));
-					if (onErrors.length === 0) {
-						if (!reportToGlobal(error, "mount")) console.error(error);
-					} else for (const oe of onErrors) try {
-						oe.fn({
-							error,
-							source: "mount",
-							state,
-							derived,
-							action,
+		function renderToString(props, sync = false, streamOut, eventsOut, stateOverride, forceAsyncChildren = false) {
+			const input = resolveInput(props);
+			const state = buildSignalState(input, stateOverride);
+			const { action, lookup: actionLookup } = buildSsrActions();
+			const recordEventsManifest = (events) => {
+				if (!eventsOut || events.length === 0) return;
+				events.forEach((record, index) => {
+					if (record.capture) {
+						eventsOut.set(`${record.type}:${index}`, record.capture);
+						return;
+					}
+					const key = actionLookup.get(record.handler);
+					if (key) eventsOut.set(`${record.type}:${index}`, key);
+				});
+			};
+			const pullStreamInitials = async (streamOut) => {
+				for (const entry of streams) {
+					const controller = new AbortController();
+					try {
+						const gen = await entry.fn({
 							input,
-							host
+							signal: controller.signal
 						});
-					} catch (handlerErr) {
-						console.error(handlerErr);
-					}
-				} finally {
-					setActiveSub(prevSub);
-				}
-				if (typeof userCleanup === "function") ssrCleanups.push(userCleanup);
-			}
-			controller.abort();
-			for (const teardown of ssrCleanups.reverse()) try {
-				teardown();
-			} catch (err) {
-				const error = err instanceof Error ? err : new Error(String(err));
-				if (onErrors.length === 0) {
-					if (!reportToGlobal(error, "mount")) console.error(error);
+						const first = await gen.next();
+						controller.abort();
+						await gen.return?.(void 0);
+						if (first.done) continue;
+						if (streamOut) streamOut[entry.key] = first.value;
+						const prevSub = setActiveSub(void 0);
+						try {
+							const setter = state[entry.key];
+							setter?.(first.value);
+						} finally {
+							setActiveSub(prevSub);
+						}
+					} catch {}
 				}
-			}
-		}
-		function renderToString(props, sync = false) {
-			const input = resolveInput(props);
-			const state = buildSignalState(input);
-			const action = buildSsrActions();
-			const results = deriveds.map((entry) => {
+			};
+			const computeDerivedResults = () => deriveds.map((entry) => {
 				const prevSub = setActiveSub(void 0);
 				try {
 					return {
@@ -1904,84 +1972,83 @@ var IlhaBuilder = class IlhaBuilder {
 					setActiveSub(prevSub);
 				}
 			});
-			if (!results.some((r) => r.result instanceof Promise) || sync) {
-				const envelopes = {};
-				for (const r of results) if (r.result instanceof Promise) envelopes[r.key] = {
-					loading: true,
-					value: void 0,
-					error: void 0
-				};
-				else envelopes[r.key] = {
-					loading: false,
-					value: r.result,
-					error: void 0
-				};
-				const derived = buildDerivedAccessors(envelopes);
-				if (!currentRenderCtx()) runOnMountForRender({
-					input,
-					state,
-					derived,
-					action
-				});
-				const prevSub = setActiveSub(void 0);
-				try {
-					const { html } = renderWithCtx({ render: () => fn({
-						state,
-						derived,
-						action,
-						input
-					}) });
-					return stylePrefix + html;
-				} finally {
-					setActiveSub(prevSub);
-				}
-			}
-			return Promise.all(results.map(async (r) => {
-				try {
-					return {
-						key: r.key,
-						envelope: {
-							loading: false,
-							value: await Promise.resolve(r.result),
-							error: void 0
-						}
+			if (!sync && (streams.length > 0 || forceAsyncChildren)) return pullStreamInitials(streamOut).then(() => renderToStringTail());
+			return renderToStringTail();
+			function renderToStringTail() {
+				const results = computeDerivedResults();
+				if (!(forceAsyncChildren || results.some((r) => r.result instanceof Promise)) || sync) {
+					const envelopes = {};
+					for (const r of results) if (r.result instanceof Promise) envelopes[r.key] = {
+						loading: true,
+						value: void 0,
+						error: void 0
 					};
-				} catch (err) {
-					return {
-						key: r.key,
-						envelope: {
-							loading: false,
-							value: void 0,
-							error: err instanceof Error ? err : new Error(String(err))
-						}
+					else envelopes[r.key] = {
+						loading: false,
+						value: r.result,
+						error: void 0
 					};
+					const derived = buildDerivedAccessors(envelopes);
+					const prevSub = setActiveSub(void 0);
+					try {
+						const { html, events } = renderWithCtx({
+							render: () => fn({
+								state,
+								derived,
+								action,
+								input
+							}),
+							manifest: eventsOut !== void 0
+						});
+						recordEventsManifest(events);
+						return stylePrefix + html;
+					} finally {
+						setActiveSub(prevSub);
+					}
 				}
-			})).then(async (resolved) => {
-				const envelopes = {};
-				for (const r of resolved) envelopes[r.key] = r.envelope;
-				const derived = buildDerivedAccessors(envelopes);
-				if (!currentRenderCtx()) runOnMountForRender({
-					input,
-					state,
-					derived,
-					action
+				return Promise.all(results.map(async (r) => {
+					try {
+						return {
+							key: r.key,
+							envelope: {
+								loading: false,
+								value: await Promise.resolve(r.result),
+								error: void 0
+							}
+						};
+					} catch (err) {
+						return {
+							key: r.key,
+							envelope: {
+								loading: false,
+								value: void 0,
+								error: err instanceof Error ? err : new Error(String(err))
+							}
+						};
+					}
+				})).then(async (resolved) => {
+					const envelopes = {};
+					for (const r of resolved) envelopes[r.key] = r.envelope;
+					const derived = buildDerivedAccessors(envelopes);
+					const prevSub = setActiveSub(void 0);
+					try {
+						const { html, events } = await renderWithCtx({
+							render: () => fn({
+								state,
+								derived,
+								action,
+								input
+							}),
+							asyncChildren: true,
+							manifest: eventsOut !== void 0
+						});
+						recordEventsManifest(events);
+						return stylePrefix + html;
+					} finally {
+						setActiveSub(prevSub);
+					}
 				});
-				const prevSub = setActiveSub(void 0);
-				try {
-					const { html } = await renderWithCtx({
-						render: () => fn({
-							state,
-							derived,
-							action,
-							input
-						}),
-						asyncChildren: true
-					});
-					return stylePrefix + html;
-				} finally {
-					setActiveSub(prevSub);
-				}
-			});
+			}
 		}
 		function mountIsland(host, props) {
 			return mountIslandInternal(host, props).unmount;
@@ -2025,7 +2092,7 @@ var IlhaBuilder = class IlhaBuilder {
 				const parsed = safeParseSnapshot(rawState, STATE_ATTR);
 				if (parsed !== void 0) snapshotRaw = parsed;
 			}
-			const stateSnapshot = snapshotRaw ? Object.fromEntries(Object.entries(snapshotRaw).filter(([k]) => k !== "_derived" && k !== "_skipOnMount")) : void 0;
+			const stateSnapshot = snapshotRaw ? Object.fromEntries(Object.entries(snapshotRaw).filter(([k]) => k !== "_derived" && k !== "_skipOnMount" && k !== "_streams")) : void 0;
 			const derivedSnapshotRaw = snapshotRaw?._derived;
 			let derivedSnapshot;
 			if (derivedSnapshotRaw) {
@@ -2454,6 +2521,36 @@ var IlhaBuilder = class IlhaBuilder {
 			}
 			stopDerived = setupDerived();
 			cleanups.push(stopDerived);
+			for (const entry of streams) {
+				let streamAborted = false;
+				const streamController = new AbortController();
+				const runStream = async () => {
+					try {
+						const gen = await entry.fn({
+							input,
+							signal: streamController.signal
+						});
+						while (!streamAborted && !streamController.signal.aborted) {
+							const { done, value } = await gen.next();
+							if (streamAborted || streamController.signal.aborted || done) break;
+							const prevSub = setActiveSub(void 0);
+							try {
+								const setter = state[entry.key];
+								setter?.(value);
+							} finally {
+								setActiveSub(prevSub);
+							}
+						}
+					} catch (err) {
+						if (!streamAborted && !streamController.signal.aborted && err?.name !== "AbortError") reportError(err, "stream");
+					}
+				};
+				runStream();
+				cleanups.push(() => {
+					streamAborted = true;
+					streamController.abort();
+				});
+			}
 			let initialized = false;
 			const initialRenderedHtml = initial.html;
 			let lastRendered = null;
@@ -2630,9 +2727,16 @@ var IlhaBuilder = class IlhaBuilder {
 			return renderToString(props);
 		});
 		island.toString = (props) => renderToString(props, true);
+		island.toStringAsync = (props) => Promise.resolve(renderToString(props, false));
 		island.mount = (host, props) => mountIsland(host, props);
 		island[ISLAND_MOUNT_INTERNAL] = (host, props) => mountIslandInternal(host, props);
 		island[ISLAND_SLOT_TAG] = configuredSlotTag;
+		island[ISLAND_RENDER_STATE] = async (props) => {
+			const manifest = /* @__PURE__ */ new Map();
+			const html = await renderToString(props ?? void 0, false, void 0, manifest, void 0, true);
+			return manifestTemplatePrefix(manifest) + html;
+		};
+		island[ISLAND_SSR_MANIFEST] = (props, eventsOut) => renderToString(props, false, void 0, eventsOut, void 0, true);
 		island.key = (key) => {
 			if (typeof key !== "string" || key.trim().length === 0) throw new Error("island.key() requires a non-empty string.");
 			if (key.includes(":")) throw new Error(`island.key() key cannot contain the slot separator ":" (got "${key}").`);
@@ -2732,7 +2836,9 @@ var IlhaBuilder = class IlhaBuilder {
 			const { name, as: rawTag = "div", snapshot = false, skipOnMount: explicitSkipOnMount } = opts;
 			const tag = assertValidSlotTagName(rawTag);
 			const resolvedProps = props ?? {};
-			const inner = await renderToString(resolvedProps);
+			const streamValues = {};
+			const eventsManifest = /* @__PURE__ */ new Map();
+			const inner = await renderToString(resolvedProps, false, streamValues, eventsManifest, void 0, true);
 			const encodedProps = escapeHtml(JSON.stringify(resolvedProps));
 			let stateAttr = "";
 			if (snapshot !== false) {
@@ -2742,7 +2848,9 @@ var IlhaBuilder = class IlhaBuilder {
 				const snapshotData = {};
 				const input = resolveInput(resolvedProps);
 				const plainState = buildPlainState(input);
-				if (doState) for (const entry of states) snapshotData[entry.key] = plainState[entry.key]();
+				const stateForDerived = { ...plainState };
+				for (const [k, v] of Object.entries(streamValues)) stateForDerived[k] = () => v;
+				if (doState) for (const entry of states) snapshotData[entry.key] = entry.key in streamValues ? streamValues[entry.key] : plainState[entry.key]();
 				if (doDerived) {
 					const derivedResults = {};
 					for (const entry of deriveds) {
@@ -2752,7 +2860,7 @@ var IlhaBuilder = class IlhaBuilder {
 						let threw = false;
 						try {
 							resultPromise = entry.fn({
-								state: plainState,
+								state: stateForDerived,
 								input,
 								signal: new AbortController().signal
 							});
@@ -2788,9 +2896,12 @@ var IlhaBuilder = class IlhaBuilder {
 					snapshotData["_derived"] = derivedResults;
 				}
 				if (doSkipOnMount) snapshotData["_skipOnMount"] = true;
+				if (streams.length > 0) snapshotData["_streams"] = Object.fromEntries(streams.map((entry) => [entry.key, true]));
 				stateAttr = ` ${STATE_ATTR}='${escapeHtml(JSON.stringify(snapshotData))}'`;
 			}
-			return `<${tag} data-ilha="${escapeHtml(name)}" ${PROPS_ATTR}='${encodedProps}'${stateAttr}>${inner}</${tag}>`;
+			let actionsAttr = "";
+			if (eventsManifest.size > 0) actionsAttr = ` ${ACTIONS_ATTR}='${escapeHtml(JSON.stringify(Object.fromEntries(eventsManifest)))}'`;
+			return `<${tag} data-ilha="${escapeHtml(name)}" ${PROPS_ATTR}='${encodedProps}'${stateAttr}${actionsAttr}>${inner}</${tag}>`;
 		};
 		return island;
 	}
@@ -2852,6 +2963,7 @@ const rootBuilder = new IlhaBuilder({
 	schema: null,
 	defaultInput: null,
 	states: [],
+	streams: [],
 	deriveds: [],
 	actions: [],
 	ons: [],
@@ -2880,6 +2992,7 @@ const ilha = Object.assign(callableRoot, {
 	context: ilhaContext,
 	signal: ilhaSignal,
 	computed: ilhaComputed,
+	morph,
 	batch,
 	untrack,
 	onUncaughtError
@@ -2888,11 +3001,14 @@ const ilha = Object.assign(callableRoot, {
 function __ilhaJsxEvent({ type, handler, modifier }) {
 	const ctx = currentRenderCtx();
 	if (!ctx) return void 0;
+	const isActionStub = SSR_ACTION_STUB in handler;
+	const capture = ctx.manifest && !isActionStub ? captureHandlerActions(handler) : void 0;
 	const index = ctx.events.length;
 	ctx.events.push({
 		type,
 		handler,
-		modifier
+		modifier,
+		capture
 	});
 	return index;
 }
@@ -2904,6 +3020,27 @@ function __ilhaJsxSlot({ island, props, key }) {
 		key
 	}));
 }
+/**
+* Morph an element's children toward `html`, patching in place: surviving
+* elements keep their identity, listeners, and focus (see the morph engine).
+* Falls back to an innerHTML write when the root tags don't match.
+*/
+function morph(host, html) {
+	if (typeof document === "undefined") return;
+	const openTag = host.localName ?? "div";
+	const tpl = document.createElement("template");
+	tpl.innerHTML = `<${openTag}>${html}</${openTag}>`;
+	const next = tpl.content.firstElementChild;
+	if (!next || next.localName !== host.localName) {
+		host.innerHTML = html;
+		return;
+	}
+	try {
+		morphInner(host, next);
+	} catch {
+		host.innerHTML = html;
+	}
+}
 const html = ilhaHtml;
 const raw = ilhaRaw;
 const css = ilhaCss;
@@ -2912,4 +3049,4 @@ const from = ilhaFrom;
 const context = ilhaContext;
 
 //#endregion
-export { ISLAND_MOUNT_HANDLES, ISLAND_MOUNT_INTERNAL, __ilhaJsxEvent, __ilhaJsxSlot, batch, ilhaComputed as computed, context, css, ilha as default, ilhaEffect as effect, from, html, ilhaSignal, ilhaSignal as signal, mount, onUncaughtError, raw, untrack };
+export { ISLAND_MOUNT_HANDLES, ISLAND_MOUNT_INTERNAL, __ilhaJsxEvent, __ilhaJsxSlot, batch, ilhaComputed as computed, context, css, ilhaEffect as effect, from, html, ilha, ilhaSignal, ilhaSignal as signal, morph, mount, onUncaughtError, raw, untrack };

package/dist/jsx-dev-runtime.d.ts

@@ -1,2 +1,2 @@
-import { a as JSX, r as jsxDEV, t as Fragment } from "./jsx-runtime-C6R6IiOD.js";
+import { a as JSX, r as jsxDEV, t as Fragment } from "./jsx-runtime-DMkplizR.js";
 export { Fragment, type JSX, jsxDEV };

package/dist/{jsx-runtime-C6R6IiOD.d.ts → jsx-runtime-DMkplizR.d.ts}

@@ -1,4 +1,4 @@
-import { C as NativeEventModifier, E as SignalAccessor, O as SignalWriter, S as NativeEventHandler, T as RawHtml } from "./index-BDM797j2.js";
+import { C as NativeEventModifier, E as SignalAccessor, O as SignalWriter, S as NativeEventHandler, T as RawHtml } from "./index-DnoM0M8S.js";
 //#region src/jsx-types.d.ts
 declare namespace JSX {
   export type Child = unknown;

package/dist/jsx-runtime.d.ts

@@ -1,2 +1,2 @@
-import { a as JSX, i as jsxs, n as jsx, r as jsxDEV, t as Fragment } from "./jsx-runtime-C6R6IiOD.js";
+import { a as JSX, i as jsxs, n as jsx, r as jsxDEV, t as Fragment } from "./jsx-runtime-DMkplizR.js";
 export { Fragment, type JSX, jsx, jsxDEV, jsxs };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilha",
-  "version": "0.10.3",
+  "version": "0.11.1",
   "description": "A tiny, framework-free island architecture library",
   "keywords": [
     "framework-free",