ilha 0.9.4 → 0.10.0

package/README.md

@@ -21,12 +21,14 @@ import ilha, { html } from "ilha";
 
 const Counter = ilha
   .state("count", 0)
-  .on("button@click", ({ state }) => state.count(state.count() + 1))
+  .action("increment", (_, { state }) => {
+    state.count((count) => count + 1);
+  })
   .render(
-    ({ state }) => html`
+    ({ state, action }) => html`
       <div>
         <p>Count: ${state.count()}</p>
-        <button>Increment</button>
+        <button onclick=${action.increment}>Increment</button>
       </div>
     `,
   );
@@ -42,15 +44,45 @@ Counter.mount(document.getElementById("app"));
 
 ## Core Concepts
 
-Islands are **self-contained reactive components** that know how to render themselves to an HTML string (SSR) and mount themselves into the DOM (client). You build an island using a fluent builder chain: declare inputs, state, events, effects, then call `.render()` to get a callable `Island` object.
+Islands are **self-contained reactive components** that know how to render themselves to an HTML string (SSR) and mount themselves into the DOM (client). Create one directly with `ilha(renderFn)`, or use the fluent builder when it needs local capabilities.
 
 State is managed with signals — when a signal changes, only the affected island re-renders using a minimal DOM morph. No virtual DOM diffing, no framework overhead.
 
+### Choose the smallest component form
+
+Ilha has two runtime modes with three authoring forms:
+
+| Form                                      | Use it when                                                                      |
+| ----------------------------------------- | -------------------------------------------------------------------------------- |
+| `const View = () => JSX`                  | You need reusable markup inside another island                                   |
+| `const View = ilha(() => JSX)`            | The component needs its own reactive scope, lifecycle, mount, or hydration       |
+| `ilha.state(...).action(...).render(...)` | The island needs local state, derived values, actions, input, or lifecycle hooks |
+
+Start with a plain component:
+
+```tsx
+const Status = () => <p>Ready</p>;
+```
+
+Promote it without changing its markup when it needs an island boundary:
+
+```tsx
+const Status = ilha(() => <p>Ready</p>);
+```
+
+Expand it into the builder when it needs local capabilities:
+
+```tsx
+const Status = ilha.state("message", "Ready").render(({ state }) => <p>{state.message()}</p>);
+```
+
+Both `ilha(() => JSX)` and the builder return a complete `Island`. A plain function remains transparent: its rendering, events, and cleanup belong to the containing island.
+
 ---
 
 ## Builder API
 
-Every island starts from the `ilha` builder object (or `ilha.input<T>()` / `ilha.input(schema)` if you need typed props).
+Use the `ilha` builder when an island needs capabilities such as typed input, state, derived values, actions, effects, or lifecycle hooks.
 
 ### `ilha.input<T>()` / `ilha.input(schema)`
 
@@ -99,7 +131,7 @@ state.count(); // → 0  (read)
 state.count(5); // → sets to 5 (write)
 ```
 
-Inside `html\`\``, you can interpolate signal accessors directly **without calling them** — `ilha` detects signal accessors and calls them for you, also applying HTML escaping:
+Inside `html\`\``, you can interpolate signal accessors directly **without calling them** —`ilha` detects signal accessors and calls them for you, also applying HTML escaping:
 
 ```ts
 html`<p>${state.count}</p>`; // same as html`<p>${state.count()}</p>`
@@ -129,15 +161,37 @@ Read with `derived.name()` like state. Each accessor also exposes `loading`, `va
 
 ---
 
+### `.action(key, fn)`
+
+Declares a reusable synchronous or asynchronous operation. Define actions before consumers, then call them from lowercase native event handlers:
+
+```tsx
+const Counter = ilha
+  .state("count", 0)
+  .action("increment", (amount: number, { state }) => {
+    state.count((count) => count + amount);
+    return state.count();
+  })
+  .render(({ state, action }) => (
+    <button onclick={() => action.increment(1)}>{state.count()}</button>
+  ));
+```
+
+Async actions expose reactive `pending`, `data`, and `error` properties. Action callbacks receive state, derived values, input, host, and an abort signal.
+
+---
+
 ### `.on(selector, handler)`
 
-Attaches a delegated event listener. The selector string uses the format `"cssSelector@eventName"`. Omit the selector part to target the island host itself.
+Prefer lowercase native event props for handlers owned by one rendered element. Use `.on()` when you need a CSS selector, an island-host listener, the full handler context, or combined modifiers.
+
+The selector string uses the format `"cssSelector@eventName"`. Omit the selector part to target the island host itself.
 
 ```ts
 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("@click", ({ state }) => state.count((count) => count + 1)) // host click
+  .on("button.inc@click", ({ state }) => state.count((count) => count + 1)) // child click
   .on("input@input", ({ state, event }) => {
     state.query((event.target as HTMLInputElement).value);
   })
@@ -301,7 +355,7 @@ ilha
   .state("count", 0)
   .on("@click", ({ state }) => {
     if (state.count() > 5) throw new Error("too many clicks");
-    state.count(state.count() + 1);
+    state.count((count) => count + 1);
   })
   .onError(({ error, source }) => {
     console.error(`[${source}] ${error.message}`);
@@ -388,12 +442,12 @@ ilha.css(styles).render(() => `<div class="card">…</div>`);
 
 ### Composing Islands
 
-Child islands are interpolated directly inside a parent's html&grave;&grave; template. During SSR the child's HTML is rendered inline; during client mount the child is activated independently inside its own host element.
+Child islands are interpolated directly inside a parent's html template. During SSR the child's HTML is rendered inline; during client mount the child is activated independently inside its own host element.
 
 ```ts
-const Icon = ilha.render(() => `<svg>…</svg>`);
+const Icon = ilha(() => `<svg>…</svg>`);
 
-const Card = ilha.render(
+const Card = ilha(
   () => html`
     <div class="card">
       ${Icon}
@@ -403,27 +457,27 @@ const Card = ilha.render(
 );
 ```
 
-**Passing props** — call the child island with a props object:
+**Passing props** — use JSX props when composing a child island:
 
-```ts
+```tsx
 const Badge = ilha
   .input(z.object({ label: z.string(), color: z.string().default("teal") }))
-  .render(({ input }) => html`<span style="background:${input.color}">${input.label}</span>`);
+  .render(({ input }) => <span style={{ background: input.color }}>{input.label}</span>);
 
-const Card = ilha.render(
-  () => html`
-    <div>
-      ${Badge({ label: "New", color: "coral" })}
-      <p>Content</p>
-    </div>
-  `,
-);
+const Card = ilha(() => (
+  <div>
+    <Badge label="New" color="coral" />
+    <p>Content</p>
+  </div>
+));
 ```
 
+Props (including JSX `children` and function callbacks) stay on the **live slot map** during parent render/mount. `data-ilha-props` only carries JSON-safe scalars for hydration hints — never rely on it for children or handlers. Nested islands under layout shells (`defineLayout` / `wrapLayout`) use the same path as page-level composition.
+
 **Keyed children** — use `.key()` when a child may reorder or appear conditionally. Keys must be unique within a parent render:
 
 ```ts
-const List = ilha.render(
+const List = ilha(
   () =>
     html`<ul>
       ${items.map((item) => html`<li>${Item.key(item.id)({ name: item.name })}</li>`)}
@@ -454,25 +508,32 @@ The `leave` transition is awaited before cleanup runs.
 
 ---
 
-### `.render(fn)`
+### `.render(fn)` and `ilha(fn)`
 
-Finalises the builder and returns an `Island`. The render function receives `{ state, derived, input }` and must return a string or `RawHtml`.
+`.render()` finalises a configured builder and returns an `Island`. The render function receives `{ state, derived, action, input }` and returns a string or `RawHtml`.
 
 ```ts
-const MyIsland = ilha.state("x", 1).render(({ state, input }) => html`<p>${state.x}</p>`);
+const MyIsland = ilha.state("x", 1).render(({ state }) => html`<p>${state.x()}</p>`);
+```
+
+For an island without builder configuration, `ilha(fn)` is shorthand for `ilha.render(fn)`:
+
+```tsx
+const StaticIsland = ilha(() => <p>Hello</p>);
+const Label = ilha<{ label: string }>(({ input }) => <p>{input.label}</p>);
 ```
 
 ---
 
 ## Island Interface
 
-Every island produced by `.render()` exposes:
+Every island produced by `.render()` or `ilha(fn)` exposes:
 
-### `island(props?)` / `island.toString(props?)`
+### `island.toString(props?)`
 
-Render the island to an HTML string synchronously. `island.toString()` is always synchronous. If `.derived()` entries have async functions, they render in `loading: true` state when called synchronously.
+Render the island to an HTML string synchronously. If `.derived()` entries have async functions, they render in `loading: true` state.
 
-Calling `island(props)` returns a `string` (or `Promise<string>` when derived values are async and awaited).
+Use `await island(props)` instead when asynchronous derived values must settle before rendering. Always include `await` when using the callable form so a possible `Promise<string>` is never mistaken for a string.
 
 ```ts
 MyIsland.toString(); // always sync
@@ -578,8 +639,8 @@ 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>`);
+const Header = ilha(() => html`<header>Hi, ${username()}!</header>`);
+const Footer = ilha(() => html`<footer>Logged in as ${username()}</footer>`);
 
 // Both islands re-render when `username` changes from anywhere.
 username("alice");
@@ -790,11 +851,13 @@ import ilha from "ilha";
 
 const Counter = ilha
   .state("count", 0)
-  .on("button@click", ({ state }) => state.count(state.count() + 1))
-  .render(({ state }) => (
+  .action("increment", (_, { state }) => {
+    state.count((count) => count + 1);
+  })
+  .render(({ state, action }) => (
     <div>
       <p>Count: {state.count}</p>
-      <button>Increment</button>
+      <button onclick={action.increment}>Increment</button>
     </div>
   ));
 ```
@@ -812,25 +875,25 @@ Interpolated children follow the same rules as the `html` tag — strings are es
 | `bind:*`              | Two-way bindings, same as in `html` templates — pass a signal accessor: `<input bind:value={state.name} />`        |
 | `key`                 | Keys a child island for reorder-safe rendering (same as `.key()`). Keys must be non-empty and must not contain `:` |
 
-For safety, `on*` attributes (e.g. `onclick`) and `srcdoc` are stripped — attach event listeners with `.on()` instead — and URL attributes (`href`, `src`, `action`, …) with unsafe schemes like `javascript:` are dropped.
+Lowercase native event props such as `onclick={handler}` attach with `addEventListener` during island mount; executable handlers never become inline SSR attributes. `srcdoc` is stripped, and URL attributes (`href`, `src`, `action`, …) with unsafe schemes such as `javascript:` are dropped.
 
 ### Islands as components
 
-Islands are plain functions, so they compose as JSX components — props and keys work as you'd expect:
+Islands are callable JSX components, so props and keys work as expected. Unlike transparent plain components, each island keeps its own reactive scope and lifecycle:
 
 ```tsx
 const Badge = ilha
   .input<{ label: string }>()
   .render(({ input }) => <span class="badge">{input.label}</span>);
 
-const Card = ilha.render(() => (
+const Card = ilha(() => (
   <div class="card">
     <Badge label="New" />
     <p>Card content</p>
   </div>
 ));
 
-const List = ilha.render(() => (
+const List = ilha(() => (
   <ul>
     {items.map((item) => (
       <li>

package/dist/{index-Dx_q_SGo.d.ts → index-Bi_I3qEL.d.ts}

@@ -56,9 +56,21 @@ interface IslandCall {
   props: Record<string, unknown> | undefined;
   key: string | undefined;
 }
-interface MarkedSignalAccessor<T> {
+type NativeEventModifier = "abortable" | "once" | "capture" | "passive";
+interface NativeEventContext {
+  readonly signal: AbortSignal;
+}
+type NativeEventHandler<E extends Event = Event> = (event: E, context: NativeEventContext) => unknown;
+type NonFunctionValue<T> = T extends ((...args: any[]) => any) ? never : T;
+type SignalSetter<T> = NonFunctionValue<T> | ((previous: T) => T);
+declare const SIGNAL_WRITER_TYPE: unique symbol;
+/** @internal Type-level write target carried by signal accessors. */
+interface SignalWriter<T> {
+  readonly [SIGNAL_WRITER_TYPE]?: (value: T) => void;
+}
+interface MarkedSignalAccessor<T> extends SignalWriter<T> {
   (): T;
-  (...args: [value: T]): void;
+  (...args: [value: SignalSetter<T>]): void;
   select<S>(selector: (state: T) => S): MarkedSignalAccessor<S>;
   [SIGNAL_ACCESSOR]: true;
 }
@@ -67,7 +79,7 @@ declare function ilhaCss(strings: TemplateStringsArray | string, ...values: (str
 declare function ilhaHtml(strings: TemplateStringsArray, ...values: unknown[]): RawHtml;
 type ContextSignal<T> = {
   (): T;
-  (value: T): void;
+  (value: SignalSetter<T>): void;
 };
 declare function ilhaContextFn<T>(key: string, initial: T): ContextSignal<T>;
 /**
@@ -149,11 +161,11 @@ interface DerivedEntry<TInput, TStateMap extends Record<string, unknown>> {
   key: string;
   fn: DerivedFn<TInput, TStateMap, unknown>;
 }
-type IslandDerived<TDerivedMap extends Record<string, unknown>> = { readonly [K in keyof TDerivedMap]: DerivedAccessor<TDerivedMap[K]> };
+type IslandDerived<TDerivedMap extends Record<string, unknown>> = { readonly [K in keyof TDerivedMap]: DerivedAccessor<TDerivedMap[K]>; };
 type ExternalSignal<T = unknown> = SignalAccessor<T>;
 type SignalAccessor<T> = MarkedSignalAccessor<T>;
 type MergeState<TStateMap extends Record<string, unknown>, K extends string, V> = Omit<TStateMap, K> & Record<K, V>;
-type IslandState<TStateMap extends Record<string, unknown>> = { readonly [K in keyof TStateMap]-?: SignalAccessor<TStateMap[K]> };
+type IslandState<TStateMap extends Record<string, unknown>> = { readonly [K in keyof TStateMap]-?: SignalAccessor<TStateMap[K]>; };
 interface HydratableOptions {
   name: string;
   as?: string;
@@ -187,14 +199,32 @@ interface KeyedIsland<TInput> {
   [ISLAND_CALL]: true;
 }
 type AnyIsland = Island<any, any>;
-type RenderContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> = {
+type AnyActionFn = (props: any, ctx: any) => unknown;
+type ActionMap = Record<string, AnyActionFn>;
+type ActionCall<P> = [P] extends [undefined] ? () => void : unknown extends P ? () => void : (props: P) => void;
+type ActionAccessor<P = undefined, R = void> = ActionCall<P> & {
+  readonly pending: boolean;
+  readonly data: Awaited<R> | undefined;
+  readonly error: Error | undefined;
+};
+type IslandActions<TActionMap extends ActionMap> = { readonly [K in keyof TActionMap]: TActionMap[K] extends ((props: infer P, ctx: any) => infer R) ? ActionAccessor<P, R> : never; };
+type ActionContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
   input: TInput;
+  host: Element;
+  signal: AbortSignal;
 };
-type EffectContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
+type RenderContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TActionMap extends ActionMap = Record<never, never>> = {
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
+  action: IslandActions<TActionMap>;
+  input: TInput;
+};
+type EffectContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> = {
+  state: IslandState<TStateMap>;
+  derived: IslandDerived<TDerivedMap>;
+  action: IslandActions<TActionMap>;
   input: TInput;
   host: Element;
   /**
@@ -205,16 +235,18 @@ type EffectContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMa
    */
   signal: AbortSignal;
 };
-type OnMountContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
+type OnMountContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> = {
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
+  action: IslandActions<TActionMap>;
   input: TInput;
   host: Element;
   hydrated: boolean;
 };
-type HandlerContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
+type HandlerContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> = {
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
+  action: IslandActions<TActionMap>;
   input: TInput;
   host: Element;
   target: Element;
@@ -231,9 +263,10 @@ type HandlerContext<TInput, TStateMap extends Record<string, unknown>, TDerivedM
 };
 type HTMLEventFor<E extends string> = E extends keyof HTMLElementEventMap ? HTMLElementEventMap[E] : Event;
 type HTMLTargetFor<E extends string> = E extends keyof HTMLElementEventMap ? NonNullable<HTMLElementEventMap[E]["target"]> extends Element ? NonNullable<HTMLElementEventMap[E]["target"]> : Element : Element;
-type HandlerContextFor<TInput, TStateMap extends Record<string, unknown>, TEventName extends string, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
+type HandlerContextFor<TInput, TStateMap extends Record<string, unknown>, TEventName extends string, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> = {
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
+  action: IslandActions<TActionMap>;
   input: TInput;
   host: Element;
   target: HTMLTargetFor<TEventName>;
@@ -250,20 +283,24 @@ interface StateEntry<TInput> {
   key: string;
   init: StateInit<TInput, unknown>;
 }
-interface OnEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> {
+interface ActionEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
+  key: string;
+  fn: (props: unknown, ctx: ActionContext<TInput, TStateMap, TDerivedMap>) => unknown;
+}
+interface OnEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> {
   selector: string;
   event: string;
   options: AddEventListenerOptions;
   abortable: boolean;
-  handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>;
+  handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap, TActionMap>) => void | Promise<void>;
 }
-interface EffectEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
-  fn: (ctx: EffectContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void;
+interface EffectEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TActionMap extends ActionMap = Record<never, never>> {
+  fn: (ctx: EffectContext<TInput, TStateMap, TDerivedMap, TActionMap>) => (() => 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" | "mount" | "transition";
+type ErrorSource = "on" | "effect" | "mount" | "transition" | "action";
 /**
  * Register a global error handler invoked when any island reports an error
  * (from .on, .effect, .onMount, or transitions) and has no local .onError()
@@ -271,19 +308,20 @@ type ErrorSource = "on" | "effect" | "mount" | "transition";
  * are handled locally and do not reach the global sink.
  */
 declare function onUncaughtError(fn: (error: Error, source: ErrorSource) => void): () => void;
-type ErrorContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> = {
+type ErrorContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> = {
   error: Error;
   source: ErrorSource;
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
+  action: IslandActions<TActionMap>;
   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 OnErrorEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TActionMap extends ActionMap = Record<never, never>> {
+  fn: (ctx: ErrorContext<TInput, TStateMap, TDerivedMap, TActionMap>) => void;
 }
-interface OnMountEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
-  fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void;
+interface OnMountEntry<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TActionMap extends ActionMap = Record<never, never>> {
+  fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap, TActionMap>) => (() => void) | void;
 }
 interface TransitionOptions {
   enter?: (host: Element) => Promise<void> | void;
@@ -296,48 +334,58 @@ interface MountOptions {
 interface MountResult {
   unmount: () => void | Promise<void>;
 }
-interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
+interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TActionMap extends ActionMap = Record<never, never>> {
   schema: StandardSchemaV1 | null;
   /** Shallow defaults merged before props (POJO `.input({ ... })` only). */
   defaultInput: Record<string, unknown> | null;
   states: StateEntry<TInput>[];
   deriveds: DerivedEntry<TInput, TStateMap>[];
-  ons: OnEntry<TInput, TStateMap, TDerivedMap>[];
-  effects: EffectEntry<TInput, TStateMap, TDerivedMap>[];
-  onMounts: OnMountEntry<TInput, TStateMap, TDerivedMap>[];
-  onErrors: OnErrorEntry<TInput, TStateMap, TDerivedMap>[];
+  actions: ActionEntry<TInput, TStateMap, TDerivedMap>[];
+  ons: OnEntry<TInput, TStateMap, TDerivedMap, TActionMap>[];
+  effects: EffectEntry<TInput, TStateMap, TDerivedMap, TActionMap>[];
+  onMounts: OnMountEntry<TInput, TStateMap, TDerivedMap, TActionMap>[];
+  onErrors: OnErrorEntry<TInput, TStateMap, TDerivedMap, TActionMap>[];
   transition: TransitionOptions | null;
   css: string | null;
   /** Slot wrapper tag when this island is embedded in a parent (default div). */
   as: string | null;
 }
-declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>> {
-  readonly _cfg: BuilderConfig<TInput, TStateMap, TDerivedMap>;
-  constructor(cfg: BuilderConfig<TInput, TStateMap, TDerivedMap>);
-  input<T extends Record<string, unknown>>(): IlhaBuilder<T, Record<never, never>, Record<never, never>>;
-  input<S extends StandardSchemaV1>(schema: S): IlhaBuilder<StandardSchemaV1.InferOutput<S> & Record<string, unknown>, Record<never, never>, Record<never, never>>;
-  input<T extends Record<string, unknown>>(defaults: T): IlhaBuilder<T, Record<never, never>, Record<never, never>>;
-  as<Tag extends string>(tag: Tag): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
-  state<V = undefined, K extends string = string>(key: K, init?: StateInit<TInput, V> | undefined): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap>;
-  derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>>;
-  on<S extends string>(selectorOrCombined: S, handler: (ctx: S extends `${string}@${infer E}:${string}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : S extends `${string}@${infer E}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
-  effect(fn: (ctx: EffectContext<TInput, TStateMap, TDerivedMap>) => (() => 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>;
+declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<never, never>, TActionMap extends ActionMap = Record<never, never>> {
+  readonly _cfg: BuilderConfig<TInput, TStateMap, TDerivedMap, TActionMap>;
+  constructor(cfg: BuilderConfig<TInput, TStateMap, TDerivedMap, TActionMap>);
+  input<T extends Record<string, unknown>>(): IlhaBuilder<T, Record<never, never>, Record<never, never>, Record<never, never>>;
+  input<S extends StandardSchemaV1>(schema: S): IlhaBuilder<StandardSchemaV1.InferOutput<S> & Record<string, unknown>, Record<never, never>, Record<never, never>, Record<never, never>>;
+  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>;
+  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>;
+  effect(fn: (ctx: EffectContext<TInput, TStateMap, TDerivedMap, TActionMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
+  onMount(fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap, TActionMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
+  onError(fn: (ctx: ErrorContext<TInput, TStateMap, TDerivedMap, TActionMap>) => void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
+  transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
+  css(strings: TemplateStringsArray | string, ...values: (string | number)[]): IlhaBuilder<TInput, TStateMap, TDerivedMap, TActionMap>;
+  render(fn: (ctx: RenderContext<TInput, TStateMap, TDerivedMap, TActionMap>) => string | RawHtml): Island<TInput, TStateMap>;
 }
 declare function ilhaFrom<TInput, TStateMap extends Record<string, unknown>>(selector: string | Element, island: Island<TInput, TStateMap>, props?: Partial<TInput>): (() => void) | null;
 type IslandRegistry = Record<string, AnyIsland>;
 declare function mountAll(registry: IslandRegistry, options?: MountOptions): MountResult;
-declare const ilha: IlhaBuilder<Record<string, unknown>, Record<never, never>, Record<never, never>> & {
+type RootInput = Record<string, unknown>;
+type RootState = Record<never, never>;
+type RootDerived = Record<never, never>;
+type RootActions = Record<never, never>;
+type RootBuilder = IlhaBuilder<RootInput, RootState, RootDerived, RootActions>;
+type DirectIslandFactory = <TInput extends Record<string, unknown> = RootInput>(fn: (ctx: RenderContext<TInput, RootState, RootDerived, RootActions>) => string | RawHtml) => Island<TInput, RootState>;
+declare const ilha: RootBuilder & DirectIslandFactory & {
   html: typeof ilhaHtml;
   raw: typeof ilhaRaw;
   mount: typeof mountAll;
   from: typeof ilhaFrom;
   context: typeof ilhaContextFn & {
-    /** Remove a context signal from the registry. Returns true if it existed. */delete(key: string): boolean; /** Remove all context signals from the registry (e.g. between tests). */
+    /** Remove a context signal from the registry. Returns true if it existed. */
+    delete(key: string): boolean;
+    /** Remove all context signals from the registry (e.g. between tests). */
     clear(): void;
   };
   signal: typeof ilhaSignal;
@@ -346,16 +394,28 @@ declare const ilha: IlhaBuilder<Record<string, unknown>, Record<never, never>, R
   untrack: typeof untrack;
   onUncaughtError: typeof onUncaughtError;
 };
+/** @internal Used by the separate JSX runtime to register a native event handler. */
+declare function __ilhaJsxEvent({ type, handler, modifier }: {
+  type: string;
+  handler: NativeEventHandler;
+  modifier?: NativeEventModifier;
+}): number | undefined;
 /** @internal Used by the separate JSX runtime entry to preserve island slot composition. */
-declare function __ilhaJsxSlot(island: unknown, props: Record<string, unknown> | undefined, key: string | undefined): RawHtml;
+declare function __ilhaJsxSlot({ island, props, key }: {
+  island: unknown;
+  props: Record<string, unknown> | undefined;
+  key: string | undefined;
+}): RawHtml;
 declare const html: typeof ilhaHtml;
 declare const raw: typeof ilhaRaw;
 declare const css: typeof ilhaCss;
 declare const mount: typeof mountAll;
 declare const from: typeof ilhaFrom;
 declare const context: typeof ilhaContextFn & {
-  /** Remove a context signal from the registry. Returns true if it existed. */delete(key: string): boolean; /** Remove all context signals from the registry (e.g. between tests). */
+  /** Remove a context signal from the registry. Returns true if it existed. */
+  delete(key: string): boolean;
+  /** Remove all context signals from the registry (e.g. between tests). */
   clear(): void;
 };
 //#endregion
-export { ilhaSignal as A, context as C, ilha as D, html as E, onUncaughtError as M, raw as N, ilhaComputed as O, untrack as P, batch as S, from as T, MountResult as _, ErrorSource as a, SignalAccessor as b, HandlerContextFor as c, ISLAND_MOUNT_INTERNAL as d, Island as f, MountOptions as g, KeyedIsland as h, ErrorContext as i, mount as j, ilhaEffect as k, HydratableOptions as l, IslandState as m, DerivedValue as n, ExternalSignal as o, IslandDerived as p, EffectContext as r, HandlerContext as s, DerivedAccessor as t, ISLAND_MOUNT_HANDLES as u, OnMountContext as v, css as w, __ilhaJsxSlot as x, RawHtml as y };
+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 };

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-import { A as ilhaSignal, C as context, D as ilha, E as html, M as onUncaughtError, N as raw, O as ilhaComputed, P as untrack, S as batch, T as from, _ as MountResult, a as ErrorSource, b as SignalAccessor, c as HandlerContextFor, d as ISLAND_MOUNT_INTERNAL, f as Island, g as MountOptions, h as KeyedIsland, i as ErrorContext, j as mount, k as ilhaEffect, l as HydratableOptions, m as IslandState, n as DerivedValue, o as ExternalSignal, p as IslandDerived, r as EffectContext, s as HandlerContext, t as DerivedAccessor, u as ISLAND_MOUNT_HANDLES, v as OnMountContext, w as css, x as __ilhaJsxSlot, y as RawHtml } from "./index-Dx_q_SGo.js";
-export { DerivedAccessor, DerivedValue, EffectContext, ErrorContext, ErrorSource, ExternalSignal, HandlerContext, HandlerContextFor, HydratableOptions, ISLAND_MOUNT_HANDLES, ISLAND_MOUNT_INTERNAL, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, __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 __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-Bi_I3qEL.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 };