ilha 0.3.0 → 0.4.0

package/README.md

@@ -138,7 +138,7 @@ ilha
   .state("count", 0)
   .on("@click", ({ state }) => state.count(state.count() + 1)) // host click
   .on("button.inc@click", ({ state }) => state.count(state.count() + 1)) // child click
-  .on("input@input:debounce", ({ state, event }) => {
+  .on("input@input", ({ state, event }) => {
     state.query((event.target as HTMLInputElement).value);
   })
   .render(({ state }) => html`<div><button class="inc">+</button></div>`);
@@ -146,11 +146,12 @@ ilha
 
 **Event modifiers** — append after a `:` separator:
 
-| Modifier  | Description              |
-| --------- | ------------------------ |
-| `once`    | Listener fires only once |
-| `capture` | Capture phase            |
-| `passive` | `{ passive: true }`      |
+| Modifier    | Description                                                               |
+| ----------- | ------------------------------------------------------------------------- |
+| `once`      | Listener fires only once                                                  |
+| `capture`   | Capture phase                                                             |
+| `passive`   | `{ passive: true }`                                                       |
+| `abortable` | `ctx.signal` aborts when the same listener fires again on the same target |
 
 Multiple modifiers can be combined: `@click:once:capture`.
 
@@ -159,13 +160,62 @@ The handler receives a `HandlerContext`:
 ```ts
 {
   state: IslandState; // reactive state signals
+  derived: IslandDerived; // derived values
   input: TInput; // resolved input props
   host: Element; // island root element
   target: Element; // element that fired the event (typed per event name)
   event: Event; // the native event (typed per event name)
+  signal: AbortSignal; // aborts on unmount, and on next fire if `:abortable`
 }
 ```
 
+**Cancelling async work with `ctx.signal`** — pass it to `fetch` or any abort-aware API to cancel stale requests when the island unmounts:
+
+```ts
+ilha
+  .state("results", [])
+  .on("button@click", async ({ state, signal }) => {
+    const res = await fetch("/api/data", { signal });
+    state.results(await res.json());
+  })
+  .render(
+    () =>
+      html`<button>Load</button>
+        <ul></ul>`,
+  );
+```
+
+**Race-cancellation with `:abortable`** — when the same listener fires again on the same target, the previous invocation's signal aborts. Useful for search-as-you-type and other patterns where only the latest invocation should win:
+
+```ts
+ilha
+  .on("input@input:abortable", async ({ state, event, signal }) => {
+    const q = (event.target as HTMLInputElement).value;
+    const res = await fetch(`/search?q=${q}`, { signal }); // earlier requests cancelled
+    if (signal.aborted) return;
+    state.results(await res.json());
+  })
+  .render(
+    () =>
+      html`<input />
+        <ul></ul>`,
+  );
+```
+
+Race-cancellation is scoped per-target — clicking button A doesn't cancel an in-flight handler on button B.
+
+**Implicit batching** — multiple synchronous state writes in a single handler produce one re-render, not one per write:
+
+```ts
+.on("@click", ({ state }) => {
+  state.a(1);
+  state.b(2);
+  state.c(3); // → one render, not three
+})
+```
+
+`AbortError` rejections from cancelled async work are filtered out automatically — they do not reach `.onError()` or `console.error`.
+
 ---
 
 ### `.effect(fn)`
@@ -184,6 +234,42 @@ ilha
   .render(({ state }) => `<p>${state.title()}</p>`);
 ```
 
+The handler receives an `EffectContext`:
+
+```ts
+{
+  state: IslandState;
+  input: TInput;
+  host: Element;
+  signal: AbortSignal; // aborts when the effect re-runs OR the island unmounts
+}
+```
+
+**Cancelling async work with `ctx.signal`** — unlike `.on()`, race-cancellation is the **default** behaviour for effects (no opt-in modifier needed) because dependency changes invariably make the previous run stale. Pass `signal` to async work to bail out of stale invocations without needing a manual cleanup function:
+
+```ts
+ilha
+  .state("userId", 1)
+  .state("user", null)
+  .effect(({ state, signal }) => {
+    (async () => {
+      try {
+        const res = await fetch(`/api/users/${state.userId()}`, { signal });
+        if (signal.aborted) return;
+        state.user(await res.json());
+      } catch (err) {
+        if (err && (err as Error).name === "AbortError") return;
+        throw err;
+      }
+    })();
+  })
+  .render(({ state }) => html`<p>${state.user?.name ?? "Loading…"}</p>`);
+```
+
+Both the user-supplied cleanup function (if any) and the signal abort fire when the effect re-runs, so you can mix patterns.
+
+**Implicit batching** — multiple synchronous state writes inside an effect run produce a single propagation pass.
+
 ---
 
 ### `.onMount(fn)`
@@ -203,6 +289,43 @@ ilha
 
 ---
 
+### `.onError(fn)`
+
+Registers an error handler that catches errors thrown by `.on()` handlers (sync throws and async rejections) and `.effect()` runs (sync throws). Multiple `.onError()` calls compose — all run in declaration order. If no `.onError()` is registered, errors fall back to `console.error` so they are never silently swallowed.
+
+```ts
+ilha
+  .state("count", 0)
+  .on("@click", ({ state }) => {
+    if (state.count() > 5) throw new Error("too many clicks");
+    state.count(state.count() + 1);
+  })
+  .onError(({ error, source }) => {
+    console.error(`[${source}] ${error.message}`);
+    Sentry.captureException(error);
+  })
+  .render(({ state }) => `<button>${state.count()}</button>`);
+```
+
+The handler receives an `ErrorContext`:
+
+```ts
+{
+  error: Error; // always wrapped to Error if a non-Error was thrown
+  source: "on" | "effect";
+  state: IslandState;
+  derived: IslandDerived;
+  input: TInput;
+  host: Element;
+}
+```
+
+`AbortError` rejections from `.on()` handlers are **not** routed to `.onError()` — they are the expected outcome of cancellation (via `:abortable` race-cancel or unmount) and would otherwise pollute error tracking.
+
+An error thrown inside an `.onError()` handler does not break other registered handlers; it is logged to `console.error` and execution continues with the next handler.
+
+---
+
 ### `.bind(selector, stateKey | externalSignal)`
 
 Two-way binds a form element to a state key or an external signal. Handles `input`, `select`, `textarea`, `checkbox`, `radio`, and `number` inputs automatically.
@@ -224,10 +347,15 @@ ilha
   );
 ```
 
-You can also bind to an external signal created with `context()`:
+You can also bind to an external signal — either a free-standing one created with `signal()` or a named global one created with `context()`:
 
 ```ts
-.bind("input", myContextSignal)
+import { signal, context } from "ilha";
+
+const username = signal("");
+const theme = context("app.theme", "light");
+
+ilha.bind("input.name", username).bind("select.theme", theme).render(/* … */);
 ```
 
 ---
@@ -461,9 +589,40 @@ const unmount = from("#hero", HeroIsland, { title: "Welcome" });
 
 ---
 
+### `signal(initial)`
+
+Creates a free-standing reactive signal that lives outside any island. Useful for sharing state across multiple islands without prop drilling, or for binding form inputs to module-level state.
+
+```ts
+import { signal } from "ilha";
+
+const count = signal(0);
+
+count(); // → 0  (read)
+count(5); // → sets to 5 (write)
+```
+
+Reading the signal inside any reactive scope — `.render()`, `.derived()`, `.effect()` — automatically subscribes that scope, so when the signal changes, dependents re-run as if it were local state.
+
+```ts
+import ilha, { signal, html } from "ilha";
+
+const username = signal("anonymous");
+
+const Header = ilha.render(() => html`<header>Hi, ${username()}!</header>`);
+const Footer = ilha.render(() => html`<footer>Logged in as ${username()}</footer>`);
+
+// Both islands re-render when `username` changes from anywhere.
+username("alice");
+```
+
+Pairs naturally with `.bind()` for two-way form bindings against module-level state.
+
+---
+
 ### `context(key, initial)`
 
-Creates a **global context signal** — a named reactive signal shared across all islands. Identical keys always return the same signal instance.
+Creates a **global context signal** — a named reactive signal shared across all islands. Identical keys always return the same signal instance, which makes it useful for app-wide singletons (theme, locale, current user) where you want the registry semantics.
 
 ```ts
 import { context } from "ilha";
@@ -476,6 +635,58 @@ 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 passed to `.bind()`. 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.
+
+---
+
+### `batch(fn)`
+
+Runs `fn` as an atomic batch — multiple signal writes inside the callback produce a single propagation pass, so dependents see the final state and run once instead of once per write. Returns whatever `fn` returns.
+
+```ts
+import { signal, batch } from "ilha";
+
+const a = signal(0);
+const b = signal(0);
+
+// Without batch: each write triggers a propagation pass.
+a(1); // → effects re-run
+b(2); // → effects re-run
+
+// With batch: both writes flush together.
+batch(() => {
+  a(10);
+  b(20);
+}); // → effects re-run once
+```
+
+`.on()` handlers and `.effect()` runs are batched implicitly, so you only need `batch()` when triggering multiple writes from outside an island — e.g. from a top-level event listener, a `setTimeout` callback, or a WebSocket message handler. Nested `batch()` calls are safe and only flush when the outermost batch ends.
+
+---
+
+### `untrack(fn)`
+
+Runs `fn` with reactive tracking suspended. Reading signals inside `fn` returns their current value without subscribing the surrounding scope. Use this in effects or deriveds when you want to peek at state without causing a re-run on its changes.
+
+```ts
+import ilha, { signal, untrack } from "ilha";
+
+const tracked = signal(0);
+const peeked = signal("hello");
+
+ilha
+  .effect(() => {
+    // Re-runs when `tracked` changes, but NOT when `peeked` changes.
+    console.log(
+      tracked(),
+      untrack(() => peeked()),
+    );
+  })
+  .render(() => `<p>x</p>`);
+```
+
+Returns whatever `fn` returns.
+
 ---
 
 ### `html\`\`` tagged template
@@ -615,6 +826,9 @@ import type {
   OnMountContext,
   HandlerContext,
   HandlerContextFor,
+  ErrorContext,
+  ErrorSource,
+  ExternalSignal,
   MountOptions,
   MountResult,
 } from "ilha";

package/dist/index.d.ts

@@ -57,6 +57,35 @@ type ContextSignal<T> = {
   (value: T): void;
 };
 declare function ilhaContext<T>(key: string, initial: T): ContextSignal<T>;
+/**
+ * Create a free-standing reactive signal that lives outside any island.
+ * Useful for sharing state across islands without prop drilling, or for
+ * binding form inputs to module-level state via `.bind(selector, signal)`.
+ *
+ * The returned accessor is a getter when called with no arguments and a
+ * setter when called with one. Reading it inside a `.derived()`, `.effect()`,
+ * or `.render()` automatically subscribes the surrounding reactive scope —
+ * so when the signal changes, dependents re-run as if it were local state.
+ */
+declare function ilhaSignal<T>(initial: T): ExternalSignal<T>;
+/**
+ * Run `fn` with reactive tracking suspended. Reading signals inside `fn`
+ * returns their current value without subscribing the surrounding scope.
+ * Use this in effects/deriveds when you want to peek at state without
+ * causing a re-run on its changes.
+ */
+declare function untrack<T>(fn: () => T): T;
+/**
+ * Run `fn` as an atomic batch — multiple signal writes inside the callback
+ * produce a single propagation pass, so dependents (effects, deriveds,
+ * island re-renders) see the final state and run once instead of once per
+ * write. Returns whatever `fn` returns.
+ *
+ * Note: `.on()` handlers and `.effect()` runs are batched implicitly, so
+ * you only need this when triggering multiple writes from outside an
+ * island (e.g. from a top-level event listener or async callback).
+ */
+declare function batch<T>(fn: () => T): T;
 interface DerivedValue<T> {
   loading: boolean;
   value: T | undefined;
@@ -115,6 +144,13 @@ type EffectContext<TInput, TStateMap extends Record<string, unknown>> = {
   state: IslandState<TStateMap>;
   input: TInput;
   host: Element;
+  /**
+   * AbortSignal that aborts when the effect re-runs (because a dependency
+   * changed) or when the island unmounts. Pass to `fetch` or check
+   * `signal.aborted` after `await` boundaries to bail out of stale work
+   * without needing a manual cleanup function.
+   */
+  signal: AbortSignal;
 };
 type OnMountContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<string, never>> = {
   state: IslandState<TStateMap>;
@@ -130,9 +166,18 @@ type HandlerContext<TInput, TStateMap extends Record<string, unknown>, TDerivedM
   host: Element;
   target: Element;
   event: Event;
+  /**
+   * AbortSignal that fires when the island unmounts. If the handler's selector
+   * was registered with the `:abortable` modifier, the signal is also aborted
+   * when the same listener fires again on the same target (giving you free
+   * race-cancellation for things like search-as-you-type fetches). Pass this
+   * to `fetch`, `AbortController`-aware APIs, or check `signal.aborted`
+   * after `await` boundaries to bail out of stale work.
+   */
+  signal: AbortSignal;
 };
 type HTMLEventName = keyof HTMLElementEventMap & string;
-type Modifier = "once" | "capture" | "passive";
+type Modifier = "once" | "capture" | "passive" | "abortable";
 type WithModifiers<E extends string> = E | `${E}:${Modifier}` | `${E}:${Modifier}:${Modifier}` | `${E}:${Modifier}:${Modifier}:${Modifier}`;
 type OnSelectorString = `@${WithModifiers<HTMLEventName>}` | `${string}@${WithModifiers<HTMLEventName>}`;
 type HandlerContextFor<TInput, TStateMap extends Record<string, unknown>, TEventName extends string, TDerivedMap extends Record<string, unknown> = Record<string, never>> = {
@@ -142,6 +187,12 @@ type HandlerContextFor<TInput, TStateMap extends Record<string, unknown>, TEvent
   host: Element;
   target: TEventName extends keyof HTMLElementEventMap ? HTMLElementEventMap[TEventName]["target"] extends Element | null ? NonNullable<HTMLElementEventMap[TEventName]["target"]> : Element : Element;
   event: TEventName extends keyof HTMLElementEventMap ? HTMLElementEventMap[TEventName] : Event;
+  /**
+   * AbortSignal that fires when the island unmounts. If the handler's selector
+   * was registered with the `:abortable` modifier, the signal is also aborted
+   * when the same listener fires again on the same target.
+   */
+  signal: AbortSignal;
 };
 type StateInit<TInput, V> = V | ((input: TInput) => V);
 interface StateEntry<TInput> {
@@ -152,11 +203,27 @@ interface OnEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap
   selector: string;
   event: string;
   options: AddEventListenerOptions;
+  abortable: boolean;
   handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>;
 }
 interface EffectEntry<TInput, TStateMap extends Record<string, unknown>> {
   fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void;
 }
+/** 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";
+type ErrorContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<string, never>> = {
+  error: Error;
+  source: ErrorSource;
+  state: IslandState<TStateMap>;
+  derived: IslandDerived<TDerivedMap>;
+  input: TInput;
+  host: Element;
+};
+interface OnErrorEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
+  fn: (ctx: ErrorContext<TInput, TStateMap, TDerivedMap>) => void;
+}
 interface OnMountEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
   fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void;
 }
@@ -178,6 +245,7 @@ interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDeri
   ons: OnEntry<TInput, TStateMap, TDerivedMap>[];
   effects: EffectEntry<TInput, TStateMap>[];
   onMounts: OnMountEntry<TInput, TStateMap, TDerivedMap>[];
+  onErrors: OnErrorEntry<TInput, TStateMap, TDerivedMap>[];
   transition: TransitionOptions | null;
   binds: BindEntry<TStateMap>[];
   css: string | null;
@@ -195,6 +263,7 @@ declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap exte
   on(selectorOrCombined: string, handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   effect(fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   onMount(fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  onError(fn: (ctx: ErrorContext<TInput, TStateMap, TDerivedMap>) => void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   css(strings: TemplateStringsArray | string, ...values: (string | number)[]): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
   render(fn: (ctx: RenderContext<TInput, TStateMap, TDerivedMap>) => string | RawHtml): Island<TInput, TStateMap>;
@@ -208,6 +277,9 @@ declare const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>,
   mount: typeof mountAll;
   from: typeof ilhaFrom;
   context: typeof ilhaContext;
+  signal: typeof ilhaSignal;
+  batch: typeof batch;
+  untrack: typeof untrack;
 };
 declare const html: typeof ilhaHtml;
 declare const raw: typeof ilhaRaw;
@@ -216,4 +288,4 @@ declare const mount: typeof mountAll;
 declare const from: typeof ilhaFrom;
 declare const context: typeof ilhaContext;
 //#endregion
-export { DerivedValue, HandlerContext, HandlerContextFor, HydratableOptions, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, context, css, ilha as default, from, html, mount, raw };
+export { DerivedValue, ErrorContext, ErrorSource, ExternalSignal, HandlerContext, HandlerContextFor, HydratableOptions, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, batch, context, css, ilha as default, from, html, ilhaSignal, ilhaSignal as signal, mount, raw, untrack };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { effect, setActiveSub, signal } from "alien-signals";
+import { effect, endBatch, setActiveSub, signal, startBatch } from "alien-signals";
 //#region src/index.ts
 const __DEV__ = typeof process !== "undefined" ? process.env?.["NODE_ENV"] !== "production" : true;
 function warn(msg) {
@@ -212,6 +212,56 @@ function ilhaContext(key, initial) {
 	contextRegistry.set(key, accessor);
 	return accessor;
 }
+/**
+* Create a free-standing reactive signal that lives outside any island.
+* Useful for sharing state across islands without prop drilling, or for
+* binding form inputs to module-level state via `.bind(selector, signal)`.
+*
+* The returned accessor is a getter when called with no arguments and a
+* setter when called with one. Reading it inside a `.derived()`, `.effect()`,
+* or `.render()` automatically subscribes the surrounding reactive scope —
+* so when the signal changes, dependents re-run as if it were local state.
+*/
+function ilhaSignal(initial) {
+	const s = signal(initial);
+	const accessor = (...args) => {
+		if (args.length === 0) return s();
+		s(args[0]);
+	};
+	return accessor;
+}
+/**
+* Run `fn` with reactive tracking suspended. Reading signals inside `fn`
+* returns their current value without subscribing the surrounding scope.
+* Use this in effects/deriveds when you want to peek at state without
+* causing a re-run on its changes.
+*/
+function untrack(fn) {
+	const prev = setActiveSub(void 0);
+	try {
+		return fn();
+	} finally {
+		setActiveSub(prev);
+	}
+}
+/**
+* Run `fn` as an atomic batch — multiple signal writes inside the callback
+* produce a single propagation pass, so dependents (effects, deriveds,
+* island re-renders) see the final state and run once instead of once per
+* write. Returns whatever `fn` returns.
+*
+* Note: `.on()` handlers and `.effect()` runs are batched implicitly, so
+* you only need this when triggering multiple writes from outside an
+* island (e.g. from a top-level event listener or async callback).
+*/
+function batch(fn) {
+	startBatch();
+	try {
+		return fn();
+	} finally {
+		endBatch();
+	}
+}
 function buildDerivedSignals(entries, state, input, derivedSnapshot) {
 	const envelopes = /* @__PURE__ */ new Map();
 	const stops = [];
@@ -225,10 +275,6 @@ function buildDerivedSignals(entries, state, input, derivedSnapshot) {
 		let ac = new AbortController();
 		let skipFirst = derivedSnapshot != null && entry.key in derivedSnapshot;
 		const stopEffect = effect(() => {
-			if (skipFirst) {
-				skipFirst = false;
-				return;
-			}
 			ac.abort();
 			ac = new AbortController();
 			const currentAc = ac;
@@ -237,6 +283,11 @@ function buildDerivedSignals(entries, state, input, derivedSnapshot) {
 				input,
 				signal: currentAc.signal
 			});
+			if (skipFirst) {
+				skipFirst = false;
+				if (result instanceof Promise) result.catch(() => {});
+				return;
+			}
 			if (!(result instanceof Promise)) {
 				const prevSub = setActiveSub(void 0);
 				env({
@@ -362,9 +413,34 @@ function parseOnArgs(selectorOrCombined) {
 			once: modifiers.has("once"),
 			capture: modifiers.has("capture"),
 			passive: modifiers.has("passive")
-		}
+		},
+		abortable: modifiers.has("abortable")
 	};
 }
+/**
+* Combine multiple AbortSignals into one that aborts when any input aborts.
+* Uses native AbortSignal.any when available, falls back to a manual chain
+* otherwise (for older runtimes).
+*/
+function anySignal(signals) {
+	if (typeof AbortSignal.any === "function") return AbortSignal.any(signals);
+	const controller = new AbortController();
+	const cleanups = [];
+	for (const s of signals) {
+		if (s.aborted) {
+			controller.abort(s.reason);
+			cleanups.forEach((c) => c());
+			return controller.signal;
+		}
+		const handler = () => controller.abort(s.reason);
+		s.addEventListener("abort", handler, { once: true });
+		cleanups.push(() => s.removeEventListener("abort", handler));
+	}
+	if (!controller.signal.aborted) controller.signal.addEventListener("abort", () => {
+		cleanups.forEach((c) => c());
+	});
+	return controller.signal;
+}
 const _mountedHosts = __DEV__ ? /* @__PURE__ */ new WeakSet() : null;
 var IlhaBuilder = class IlhaBuilder {
 	_cfg;
@@ -379,6 +455,7 @@ var IlhaBuilder = class IlhaBuilder {
 			ons: [],
 			effects: [],
 			onMounts: [],
+			onErrors: [],
 			transition: null,
 			binds: [],
 			css: null
@@ -421,6 +498,7 @@ var IlhaBuilder = class IlhaBuilder {
 				selector: parsed.selector,
 				event: parsed.eventType,
 				options: parsed.options,
+				abortable: parsed.abortable,
 				handler
 			}]
 		});
@@ -437,6 +515,12 @@ var IlhaBuilder = class IlhaBuilder {
 			onMounts: [...this._cfg.onMounts, { fn }]
 		});
 	}
+	onError(fn) {
+		return new IlhaBuilder({
+			...this._cfg,
+			onErrors: [...this._cfg.onErrors, { fn }]
+		});
+	}
 	transition(opts) {
 		return new IlhaBuilder({
 			...this._cfg,
@@ -461,7 +545,7 @@ var IlhaBuilder = class IlhaBuilder {
 		});
 	}
 	render(fn) {
-		const { schema, states, deriveds, ons, effects, onMounts, transition, binds, css: cssSource } = this._cfg;
+		const { schema, states, deriveds, ons, effects, onMounts, onErrors, transition, binds, css: cssSource } = this._cfg;
 		const stylePrefix = cssSource != null ? buildScopedStyle(cssSource) : "";
 		function resolveInput(props) {
 			const value = props ?? {};
@@ -627,12 +711,33 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 			const shouldSkipOnMount = hydrated && snapshotRaw?.["_skipOnMount"] === true;
 			const state = buildSignalState(input, stateSnapshot);
 			const cleanups = [];
+			const unmountController = new AbortController();
+			cleanups.push(() => unmountController.abort());
 			if (transition?.enter) {
 				const result = transition.enter(host);
 				if (result instanceof Promise) result.catch(console.error);
 			}
 			const { proxy: derived, stop: stopDerived } = buildDerivedSignals(deriveds, state, input, derivedSnapshot);
 			cleanups.push(stopDerived);
+			function reportError(err, source) {
+				const error = err instanceof Error ? err : new Error(String(err));
+				if (onErrors.length === 0) {
+					console.error(error);
+					return;
+				}
+				for (const entry of onErrors) try {
+					entry.fn({
+						error,
+						source,
+						state,
+						derived,
+						input,
+						host
+					});
+				} catch (handlerErr) {
+					console.error(handlerErr);
+				}
+			}
 			const mountedSlots = /* @__PURE__ */ new Map();
 			function findSlot(id) {
 				const escaped = typeof CSS !== "undefined" && CSS.escape ? CSS.escape(id) : id.replace(/["\\]/g, "\\$&");
@@ -680,6 +785,7 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 			}
 			const listeners = [];
 			const firedOnce = /* @__PURE__ */ new Set();
+			const invocationControllers = /* @__PURE__ */ new WeakMap();
 			function attachListeners() {
 				for (const entry of ons) {
 					if (entry.options.once && firedOnce.has(entry)) continue;
@@ -693,15 +799,41 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 								listeners.splice(0, listeners.length, ...listeners.filter((l) => l.entry !== entry));
 							}
 							const eventTarget = event.target instanceof Element ? event.target : listenerTarget;
-							const result = entry.handler({
-								state,
-								derived,
-								input,
-								host,
-								target: eventTarget,
-								event
+							let handlerSignal;
+							if (entry.abortable) {
+								let entryMap = invocationControllers.get(entry);
+								if (!entryMap) {
+									entryMap = /* @__PURE__ */ new WeakMap();
+									invocationControllers.set(entry, entryMap);
+								}
+								const prev = entryMap.get(listenerTarget);
+								if (prev) prev.abort();
+								const invocationController = new AbortController();
+								entryMap.set(listenerTarget, invocationController);
+								handlerSignal = anySignal([unmountController.signal, invocationController.signal]);
+							} else handlerSignal = unmountController.signal;
+							let result;
+							startBatch();
+							try {
+								result = entry.handler({
+									state,
+									derived,
+									input,
+									host,
+									target: eventTarget,
+									event,
+									signal: handlerSignal
+								});
+							} catch (err) {
+								reportError(err, "on");
+								endBatch();
+								return;
+							}
+							endBatch();
+							if (result instanceof Promise) result.catch((err) => {
+								if (err && err.name === "AbortError") return;
+								reportError(err, "on");
 							});
-							if (result instanceof Promise) result.catch(console.error);
 						};
 						const opts = {
 							...entry.options,
@@ -793,20 +925,41 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 			cleanups.push(detachListeners);
 			for (const entry of effects) {
 				let userCleanup;
+				let runController = null;
 				const stopEffect = effect(() => {
 					if (userCleanup) {
-						userCleanup();
+						try {
+							userCleanup();
+						} catch (err) {
+							reportError(err, "effect");
+						}
 						userCleanup = void 0;
 					}
-					userCleanup = entry.fn({
-						state,
-						input,
-						host
-					});
+					if (runController) runController.abort();
+					runController = new AbortController();
+					const runSignal = anySignal([unmountController.signal, runController.signal]);
+					startBatch();
+					try {
+						userCleanup = entry.fn({
+							state,
+							input,
+							host,
+							signal: runSignal
+						});
+					} catch (err) {
+						reportError(err, "effect");
+					} finally {
+						endBatch();
+					}
 				});
 				cleanups.push(() => {
 					stopEffect();
-					if (userCleanup) userCleanup();
+					if (userCleanup) try {
+						userCleanup();
+					} catch (err) {
+						reportError(err, "effect");
+					}
+					if (runController) runController.abort();
 				});
 			}
 			let tornDown = false;
@@ -957,6 +1110,7 @@ const rootBuilder = new IlhaBuilder({
 	ons: [],
 	effects: [],
 	onMounts: [],
+	onErrors: [],
 	transition: null,
 	binds: [],
 	css: null
@@ -966,7 +1120,10 @@ const ilha = Object.assign(rootBuilder, {
 	raw: ilhaRaw,
 	mount: mountAll,
 	from: ilhaFrom,
-	context: ilhaContext
+	context: ilhaContext,
+	signal: ilhaSignal,
+	batch,
+	untrack
 });
 const html = ilhaHtml;
 const raw = ilhaRaw;
@@ -975,4 +1132,4 @@ const mount = mountAll;
 const from = ilhaFrom;
 const context = ilhaContext;
 //#endregion
-export { context, css, ilha as default, from, html, mount, raw };
+export { batch, context, css, ilha as default, from, html, ilhaSignal, ilhaSignal as signal, mount, raw, untrack };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilha",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "A tiny, framework-free island architecture library",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",
@@ -26,6 +26,6 @@
     "alien-signals": "3.1.2"
   },
   "devDependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.4.1"
   }
 }