ilha 0.0.1

package/README.md

@@ -0,0 +1,300 @@
+# ilha
+
+A tiny, framework-free island architecture library. Define interactive islands with typed props, reactive state, async-derived data, and slots — render them as plain HTML strings on the server, mount them on the client.
+
+Built on [alien-signals](https://github.com/stackblitz/alien-signals) for fine-grained reactivity. Supports any [Standard Schema](https://standardschema.dev) validator (Zod, Valibot, ArkType, …).
+
+## Install
+
+```bash
+bun add ilha
+# or
+npm install ilha
+```
+
+## Quick start
+
+```ts
+import ilha, { html, mount } from "ilha";
+import { z } from "zod";
+
+const counter = ilha
+  .input(z.object({ count: z.number().default(0) }))
+  .state("count", ({ count }) => count)
+  .on("[data-inc]@click", ({ state }) => state.count(state.count() + 1))
+  .render(
+    ({ state }) => html`
+      <p>${state.count}</p>
+      <button data-inc>+</button>
+    `,
+  );
+
+// SSR — sync islands return a string immediately
+counter({ count: 5 }); // → "<p>5</p><button data-inc>+</button>"
+
+// Client — mount onto a DOM element
+mount({ counter });
+```
+
+```html
+<div data-ilha="counter" data-props='{"count": 5}'></div>
+```
+
+## Builder API
+
+Every island is built with a chainable builder. All methods return a new builder — nothing is mutated.
+
+| Method                          | Description                                                        |
+| ------------------------------- | ------------------------------------------------------------------ |
+| `.input(schema)`                | Declare typed props via any Standard Schema validator              |
+| `.state(key, init)`             | Add a reactive signal; `init` can be a value or `(input) => value` |
+| `.derived(key, fn)`             | Derive reactive data from state/input — sync or async              |
+| `.bind(selector, stateKey)`     | Two-way bind a form element to a state key                         |
+| `.on(selector@event, handler)`  | Attach a delegated event listener                                  |
+| `.effect(fn)`                   | Run a reactive side effect on mount; return a cleanup function     |
+| `.slot(name, island)`           | Nest a child island                                                |
+| `.transition({ enter, leave })` | Async-safe mount/unmount animations                                |
+| `.render(fn)`                   | Finalize — returns an `Island`                                     |
+
+## Events
+
+The `.on()` selector string uses `selector@event` syntax with optional modifiers:
+
+```ts
+.on("[data-btn]@click", handler)                   // delegated click
+.on("@click", handler)                             // bind to root element
+.on("[data-btn]@click:once", handler)              // fires once
+.on("[data-btn]@click:passive:capture", handler)
+```
+
+## Two-way binding
+
+`.bind(selector, stateKey)` creates a two-way link between a form element and a state key — no event handler boilerplate needed:
+
+```ts
+const form = ilha
+  .state("email", "")
+  .state("subscribe", false)
+  .bind("[data-email]", "email")
+  .bind("[data-sub]", "subscribe")
+  .render(
+    ({ state }) => html`
+      <input data-email value="${state.email()}" />
+      <input type="checkbox" data-sub ${state.subscribe() ? "checked" : ""} />
+      <p>Email: ${state.email()}, Subscribe: ${state.subscribe()}</p>
+    `,
+  );
+```
+
+Both directions are handled automatically:
+
+- **DOM → state** — when the user types or toggles, the signal updates immediately
+- **state → DOM** — when the signal changes programmatically, the element's value/checked syncs
+
+The DOM value is automatically coerced to match the type of the state key — no manual conversion needed:
+
+```ts
+.state("count", 0)
+.bind("[data-count]", "count") // input string coerced to number automatically
+```
+
+If the input is cleared and the state is a number, the value falls back to `0` rather than `NaN`.
+
+Element types and their behaviour:
+
+| Element                  | Event              | Property          |
+| ------------------------ | ------------------ | ----------------- |
+| `input` (text, email, …) | `input`            | `.value`          |
+| `input[type=number]`     | `input`            | `.valueAsNumber`  |
+| `input[type=checkbox]`   | `change`           | `.checked`        |
+| `input[type=radio]`      | `change`           | selected `.value` |
+| `select`, `textarea`     | `change` / `input` | `.value`          |
+
+For radio groups, bind all radios in the group to the same state key, typically via a shared selector like `[name=plan]`. The state stores the selected radio's `value`:
+
+`.bind()` is a no-op during SSR — it only activates on mount.
+
+### Stale element references
+
+Every time bound state changes, the island re-renders and replaces `el.innerHTML`. Any element reference captured before a state change becomes stale. Always re-query from `el` after dispatching events or triggering state changes:
+
+```ts
+// ✗ — reference captured before re-render, may be a detached element
+const input = el.querySelector("[data-q]")!;
+input.dispatchEvent(new Event("input"));
+input.value; // stale
+
+// ✓ — always re-query after a state-changing interaction
+el.querySelector<HTMLInputElement>("[data-q]")!.dispatchEvent(new Event("input"));
+el.querySelector<HTMLInputElement>("[data-q]")!.value; // fresh
+```
+
+## Derived data
+
+`.derived()` computes values from state or input. It can be sync or async.
+
+### Sync derived
+
+Sync derived is a pure computation — `value` is available immediately with no loading state, and updates synchronously whenever its dependencies change:
+
+```ts
+const island = ilha
+  .state("count", 0)
+  .derived("doubled", ({ state }) => state.count() * 2)
+  .on("[data-inc]@click", ({ state }) => state.count(state.count() + 1))
+  .render(
+    ({ state, derived }) => html`
+      <p>${state.count()} × 2 = ${derived.doubled.value}</p>
+      <button data-inc>+</button>
+    `,
+  );
+```
+
+### Async derived
+
+Async derived wraps the result in a `{ loading, value, error }` envelope. Previous `value` is preserved while re-fetching (stale-while-revalidate). Each run gets an `AbortSignal` — stale requests are cancelled automatically when dependencies change:
+
+```ts
+const pokemon = ilha
+  .state("name", "charizard")
+  .derived("data", async ({ state, signal }) => {
+    const res = await fetch(`https://pokeapi.co/api/v2/pokemon/${state.name()}`, { signal });
+    return res.json() as Promise<{ name: string }>;
+  })
+  .render(({ derived }) => {
+    const { loading, value, error } = derived.data;
+    if (loading) return `<p>Loading${value ? ` (was: ${value.name})` : ""}…</p>`;
+    if (error) return `<p>Error: ${error.message}</p>`;
+    return `<p>${value!.name}</p>`;
+  });
+```
+
+### Async SSR
+
+On the server, islands with async derived values can be used in two ways:
+
+- **`await island()`** — resolves all async derived values before rendering final HTML
+- **`island.toString()`** or implicit template interpolation — stays synchronous and uses the loading fallback for async derived values
+
+```ts
+const page = ilha
+  .derived("user", async () => ({ name: "Ada" }))
+  .render(({ derived }) => {
+    if (derived.user.loading) return "<p>Loading…</p>";
+    if (derived.user.error) return `<p>Error: ${derived.user.error.message}</p>`;
+    return `<p>${derived.user.value!.name}</p>`;
+  });
+
+// async SSR
+await page(); // → "<p>Ada</p>"
+
+// sync fallback
+page.toString(); // → "<p>Loading…</p>"
+`${page}`; // → "<p>Loading…</p>"
+```
+
+This keeps SSR flexible:
+
+- sync islands remain zero-overhead and return a plain string
+- async islands can be awaited when the server runtime supports async rendering
+- template literals remain safe and synchronous
+
+### Derived envelope
+
+Every `.derived()` value — sync or async — is accessed as:
+
+```ts
+derived.key.loading; // boolean — always false for sync
+derived.key.value; // T | undefined
+derived.key.error; // Error | undefined — always undefined for sync
+```
+
+### Derived context
+
+The `fn` passed to `.derived()` receives:
+
+```ts
+({ state, input, signal }) => ...
+//                ^^^^^^  AbortSignal — only meaningful for async
+```
+
+## Slots
+
+Compose islands by nesting them as slots:
+
+```ts
+const app = ilha
+  .slot("counter", counter)
+  .render(
+    ({ slots }) => html`
+      <div>${slots.counter} // default props ${slots.counter({ count: 10 })} // with props</div>
+    `,
+  );
+```
+
+Or declaratively in HTML:
+
+```html
+<div data-ilha-slot="counter" data-props='{"count": 10}'></div>
+```
+
+## Shared state
+
+`context()` creates a module-level signal shared across all islands. The same key always returns the same signal — the initial value from the first registration wins.
+
+```ts
+import { context } from "ilha";
+
+const theme = context("theme", "light");
+
+theme(); // → "light"
+theme("dark"); // updates all subscribed islands
+```
+
+> **Note:** Context signals are global for the lifetime of the page. There is no per-instance scoping or cleanup.
+
+## Mounting
+
+```ts
+// Auto-discover all [data-ilha] elements
+mount({ counter, app });
+mount({ counter }, { root: document.querySelector("#app") });
+mount({ counter }, { lazy: true }); // IntersectionObserver
+mount({ counter }, { hydrate: true }); // preserve SSR HTML
+
+// Mount a single island by selector or element
+import { from } from "ilha";
+from("#my-counter", counter, { count: 5 });
+```
+
+## SSR hydration
+
+Set `data-ilha-state` on the element to restore serialised state client-side without re-running validation:
+
+```html
+<div data-ilha="counter" data-ilha-state='{"count": 42}'>
+  <p>42</p>
+  <button data-inc>+</button>
+</div>
+```
+
+## `html` template tag
+
+Safe HTML template helper — escapes all interpolations by default:
+
+```ts
+import { html, raw } from "ilha";
+
+html`<p>${userInput}</p>`; // escaped
+html`<p>${raw("<b>bold</b>")}</p>`; // explicit raw passthrough
+html`<p>${state.count}</p>`; // signal accessor — calls getter + escapes
+```
+
+## Known limitations
+
+- `context()` signals are global with no scoping or cleanup mechanism
+- Implicit string interpolation of islands (`${island}`) is always synchronous, so async derived values fall back to `loading`
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+//#region src/index.d.ts
+interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly "~standard": StandardSchemaV1.Props<Input, Output>;
+}
+declare namespace StandardSchemaV1 {
+  interface Props<Input = unknown, Output = Input> {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly types?: Types<Input, Output> | undefined;
+    readonly validate: (value: unknown) => Result<Output> | Promise<Result<Output>>;
+  }
+  type Result<Output> = SuccessResult<Output> | FailureResult;
+  interface SuccessResult<Output> {
+    readonly value: Output;
+    readonly issues?: undefined;
+  }
+  interface FailureResult {
+    readonly issues: ReadonlyArray<Issue>;
+  }
+  interface Issue {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | PathSegment> | undefined;
+  }
+  interface PathSegment {
+    readonly key: PropertyKey;
+  }
+  interface Types<Input = unknown, Output = Input> {
+    readonly input: Input;
+    readonly output: Output;
+  }
+  type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
+}
+declare const RAW: unique symbol;
+declare const SLOT_ACCESSOR: unique symbol;
+declare const SIGNAL_ACCESSOR: unique symbol;
+interface RawHtml {
+  [RAW]: true;
+  value: string;
+}
+interface SlotAccessor {
+  (props?: Record<string, unknown>): RawHtml;
+  toString(): string;
+  [SLOT_ACCESSOR]: true;
+}
+interface MarkedSignalAccessor<T> {
+  (): T;
+  (value: T): void;
+  [SIGNAL_ACCESSOR]: true;
+}
+declare function ilhaRaw(value: string): RawHtml;
+declare function ilhaHtml(strings: TemplateStringsArray, ...values: unknown[]): string;
+type ContextSignal<T> = {
+  (): T;
+  (value: T): void;
+};
+declare function ilhaContext<T>(key: string, initial: T): ContextSignal<T>;
+interface DerivedValue<T> {
+  loading: boolean;
+  value: T | undefined;
+  error: Error | undefined;
+}
+type DerivedFnContext<TInput, TStateMap extends Record<string, unknown>> = {
+  state: IslandState<TStateMap>;
+  input: TInput;
+  signal: AbortSignal;
+};
+type DerivedFn<TInput, TStateMap extends Record<string, unknown>, V> = (ctx: DerivedFnContext<TInput, TStateMap>) => V | Promise<V>;
+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]: DerivedValue<TDerivedMap[K]> };
+interface BindEntry<TStateMap extends Record<string, unknown>> {
+  selector: string;
+  stateKey: keyof TStateMap & string;
+}
+type SignalAccessor<T> = MarkedSignalAccessor<T>;
+type IslandState<TStateMap extends Record<string, unknown>> = { [K in keyof TStateMap]: SignalAccessor<TStateMap[K]> };
+interface Island<TInput, TStateMap extends Record<string, unknown>> {
+  (props?: Partial<TInput>): string | Promise<string>;
+  toString(props?: Partial<TInput>): string;
+  mount(el: Element, props?: Partial<TInput>): () => void;
+}
+type AnyIsland = Island<Record<string, unknown>, Record<string, unknown>>;
+type SlotMap = Record<string, AnyIsland>;
+type SlotsProxy<TSlots extends SlotMap> = { readonly [K in keyof TSlots]: SlotAccessor };
+type RenderContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TSlots extends SlotMap> = {
+  state: IslandState<TStateMap>;
+  derived: IslandDerived<TDerivedMap>;
+  input: TInput;
+  slots: SlotsProxy<TSlots>;
+};
+type EffectContext<TInput, TStateMap extends Record<string, unknown>> = {
+  state: IslandState<TStateMap>;
+  input: TInput;
+  el: Element;
+};
+type HandlerContext<TInput, TStateMap extends Record<string, unknown>> = {
+  state: IslandState<TStateMap>;
+  input: TInput;
+  el: Element;
+  event: Event;
+};
+type StateInit<TInput, V> = V | ((input: TInput) => V);
+interface StateEntry<TInput> {
+  key: string;
+  init: StateInit<TInput, unknown>;
+}
+interface OnEntry<TInput, TStateMap extends Record<string, unknown>> {
+  selector: string;
+  event: string;
+  options: AddEventListenerOptions;
+  handler: (ctx: HandlerContext<TInput, TStateMap>) => void | Promise<void>;
+}
+interface EffectEntry<TInput, TStateMap extends Record<string, unknown>> {
+  fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void;
+}
+interface TransitionOptions {
+  enter?: (el: Element) => Promise<void> | void;
+  leave?: (el: Element) => Promise<void> | void;
+}
+interface MountOptions {
+  root?: Element;
+  hydrate?: boolean;
+  lazy?: boolean;
+}
+interface MountResult {
+  unmount: () => void;
+}
+declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<string, never>, TSlots extends SlotMap = Record<string, never>> {
+  private readonly _schema;
+  private readonly _states;
+  private readonly _deriveds;
+  private readonly _ons;
+  private readonly _effects;
+  private readonly _slots;
+  private readonly _transition;
+  private readonly _binds;
+  constructor(_schema: StandardSchemaV1 | null, _states: StateEntry<TInput>[], _deriveds: DerivedEntry<TInput, TStateMap>[], _ons: OnEntry<TInput, TStateMap>[], _effects: EffectEntry<TInput, TStateMap>[], _slots: Record<string, AnyIsland>, _transition: TransitionOptions | null, _binds: BindEntry<TStateMap>[]);
+  input<S extends StandardSchemaV1>(schema: S): IlhaBuilder<StandardSchemaV1.InferOutput<S> & Record<string, unknown>, Record<string, never>, Record<string, never>, Record<string, never>>;
+  state<K extends string, V>(key: K, init: StateInit<TInput, V>): IlhaBuilder<TInput, TStateMap & Record<K, V>, TDerivedMap, TSlots>;
+  derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>, TSlots>;
+  bind(selector: string, stateKey: keyof TStateMap & string): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
+  on(selectorOrCombined: string, callbackOrEventType: ((ctx: HandlerContext<TInput, TStateMap>) => void | Promise<void>) | string, handler?: (ctx: HandlerContext<TInput, TStateMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
+  effect(fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
+  slot<K extends string>(name: K, island: AnyIsland): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots & Record<K, AnyIsland>>;
+  transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
+  render(fn: (ctx: RenderContext<TInput, TStateMap, TDerivedMap, TSlots>) => string): 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<string, never>, Record<string, never>, Record<string, never>> & {
+  html: typeof ilhaHtml;
+  raw: typeof ilhaRaw;
+  mount: typeof mountAll;
+  from: typeof ilhaFrom;
+  context: typeof ilhaContext;
+};
+declare const html: typeof ilhaHtml;
+declare const raw: typeof ilhaRaw;
+declare const mount: typeof mountAll;
+declare const from: typeof ilhaFrom;
+declare const context: typeof ilhaContext;
+//#endregion
+export { DerivedValue, HandlerContext, Island, IslandDerived, IslandState, MountOptions, MountResult, SignalAccessor, SlotAccessor, context, ilha as default, from, html, mount, raw };

package/dist/index.js

@@ -0,0 +1,658 @@
+import { effect, setActiveSub, signal } from "alien-signals";
+//#region src/index.ts
+function validateSchema(schema, value) {
+	const result = schema["~standard"].validate(value);
+	if (result instanceof Promise) throw new Error("[ilha] Async schemas are not supported.");
+	if (result.issues) throw new Error(`[ilha] Validation failed:\n${result.issues.map((i) => `  - ${i.message}`).join("\n")}`);
+	return result.value;
+}
+function escapeHtml(value) {
+	return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function dedentString(str) {
+	const lines = str.split("\n");
+	while (lines.length && lines[0].trim() === "") lines.shift();
+	while (lines.length && lines[lines.length - 1].trim() === "") lines.pop();
+	if (!lines.length) return "";
+	const indent = Math.min(...lines.filter((l) => l.trim() !== "").map((l) => l.match(/^(\s*)/)[1].length));
+	return lines.map((l) => l.slice(indent)).join("\n");
+}
+const RAW = Symbol("ilha.raw");
+const SLOT_ACCESSOR = Symbol("ilha.slotAccessor");
+const SIGNAL_ACCESSOR = Symbol("ilha.signalAccessor");
+const SLOT_ATTR = "data-ilha-slot";
+const SLOT_PROPS_ATTR = "data-ilha-props";
+const STATE_ATTR = "data-ilha-state";
+function makeSlotAccessor(render) {
+	const fn = (props) => ({
+		[RAW]: true,
+		value: render(props)
+	});
+	fn.toString = () => render(void 0);
+	fn[SLOT_ACCESSOR] = true;
+	return fn;
+}
+function isSlotAccessor(v) {
+	return typeof v === "function" && SLOT_ACCESSOR in v;
+}
+function markSignalAccessor(fn) {
+	fn[SIGNAL_ACCESSOR] = true;
+	return fn;
+}
+function isSignalAccessor(v) {
+	return typeof v === "function" && SIGNAL_ACCESSOR in v;
+}
+function ilhaRaw(value) {
+	return {
+		[RAW]: true,
+		value
+	};
+}
+function ilhaHtml(strings, ...values) {
+	let result = "";
+	for (let i = 0; i < strings.length; i++) {
+		result += strings[i];
+		if (i < values.length) {
+			const v = values[i];
+			if (v == null) continue;
+			if (typeof v === "object" && RAW in v) result += v.value;
+			else if (isSlotAccessor(v)) result += v.toString();
+			else if (isSignalAccessor(v)) result += escapeHtml(v());
+			else if (typeof v === "function") result += escapeHtml(v());
+			else result += escapeHtml(v);
+		}
+	}
+	return dedentString(result);
+}
+const contextRegistry = /* @__PURE__ */ new Map();
+function ilhaContext(key, initial) {
+	if (contextRegistry.has(key)) return contextRegistry.get(key);
+	const s = signal(initial);
+	const accessor = (...args) => {
+		if (args.length === 0) return s();
+		s(args[0]);
+	};
+	contextRegistry.set(key, accessor);
+	return accessor;
+}
+function makePlainDerived(entries, state, input) {
+	const derived = {};
+	for (const entry of entries) {
+		const result = entry.fn({
+			state,
+			input,
+			signal: new AbortController().signal
+		});
+		if (result instanceof Promise) derived[entry.key] = {
+			loading: true,
+			value: void 0,
+			error: void 0
+		};
+		else derived[entry.key] = {
+			loading: false,
+			value: result,
+			error: void 0
+		};
+	}
+	return derived;
+}
+function buildDerivedSignals(entries, state, input) {
+	const envelopes = /* @__PURE__ */ new Map();
+	const stops = [];
+	for (const entry of entries) {
+		const env = signal({
+			loading: true,
+			value: void 0,
+			error: void 0
+		});
+		envelopes.set(entry.key, env);
+		let ac = new AbortController();
+		const stopEffect = effect(() => {
+			ac.abort();
+			ac = new AbortController();
+			const currentAc = ac;
+			const result = entry.fn({
+				state,
+				input,
+				signal: currentAc.signal
+			});
+			if (!(result instanceof Promise)) {
+				const prevSub = setActiveSub(void 0);
+				env({
+					loading: false,
+					value: result,
+					error: void 0
+				});
+				setActiveSub(prevSub);
+				return;
+			}
+			const prevSub = setActiveSub(void 0);
+			env({
+				loading: true,
+				value: env().value,
+				error: void 0
+			});
+			setActiveSub(prevSub);
+			result.then((value) => {
+				if (currentAc.signal.aborted) return;
+				env({
+					loading: false,
+					value,
+					error: void 0
+				});
+			}).catch((err) => {
+				if (currentAc.signal.aborted) return;
+				env({
+					loading: false,
+					value: void 0,
+					error: err instanceof Error ? err : new Error(String(err))
+				});
+			});
+		});
+		stops.push(() => {
+			stopEffect();
+			ac.abort();
+		});
+	}
+	return {
+		proxy: new Proxy({}, { get(_, key) {
+			const env = envelopes.get(key);
+			if (!env) return {
+				loading: false,
+				value: void 0,
+				error: void 0
+			};
+			return env();
+		} }),
+		stop: () => stops.forEach((s) => s())
+	};
+}
+function resolveBindConfig(el) {
+	const tag = el.tagName.toLowerCase();
+	const type = el.type?.toLowerCase() ?? "";
+	if (tag === "input" && type === "checkbox") return {
+		prop: "checked",
+		event: "change",
+		read: (el) => el.checked,
+		write: (el, v) => el.checked = Boolean(v)
+	};
+	if (tag === "input" && type === "radio") return {
+		prop: "checked",
+		event: "change",
+		read: (el) => {
+			const input = el;
+			return input.checked ? input.value : void 0;
+		},
+		write: (el, v) => {
+			const input = el;
+			input.checked = String(v ?? "") === input.value;
+		}
+	};
+	if (tag === "input" && type === "number") return {
+		prop: "valueAsNumber",
+		event: "input",
+		read: (el) => el.valueAsNumber,
+		write: (el, v) => el.value = String(v ?? "")
+	};
+	return {
+		prop: "value",
+		event: tag === "select" ? "change" : "input",
+		read: (el) => el.value,
+		write: (el, v) => el.value = String(v ?? "")
+	};
+}
+function applyBindings(el, bindings, state) {
+	const cleanups = [];
+	for (const binding of bindings) {
+		const targets = binding.selector === "" ? [el] : Array.from(el.querySelectorAll(binding.selector));
+		for (const target of targets) {
+			const { event, read, write } = resolveBindConfig(target);
+			const accessor = state[binding.stateKey];
+			const input = target;
+			const isRadio = input.tagName.toLowerCase() === "input" && input.type?.toLowerCase() === "radio";
+			write(target, accessor());
+			const listener = () => {
+				const raw = read(target);
+				if (isRadio && raw === void 0) return;
+				const currentVal = accessor();
+				let value;
+				if (typeof currentVal === "number") {
+					const n = Number(raw);
+					value = isNaN(n) ? 0 : n;
+				} else if (typeof currentVal === "boolean") value = Boolean(raw);
+				else value = raw;
+				accessor(value);
+			};
+			target.addEventListener(event, listener);
+			cleanups.push(() => target.removeEventListener(event, listener));
+		}
+	}
+	return () => cleanups.forEach((c) => c());
+}
+function parseOnArgs(selectorOrCombined, callbackOrEventType) {
+	let selector;
+	let rawEvent;
+	if (typeof callbackOrEventType === "function") {
+		const atIdx = selectorOrCombined.lastIndexOf("@");
+		if (atIdx === -1) {
+			selector = "";
+			rawEvent = selectorOrCombined.startsWith("@") ? selectorOrCombined.slice(1) : selectorOrCombined;
+		} else {
+			selector = selectorOrCombined.slice(0, atIdx);
+			rawEvent = selectorOrCombined.slice(atIdx + 1);
+		}
+	} else {
+		selector = selectorOrCombined;
+		rawEvent = callbackOrEventType;
+	}
+	const parts = rawEvent.split(":");
+	const eventType = parts[0];
+	const modifiers = new Set(parts.slice(1));
+	const options = {
+		once: modifiers.has("once"),
+		capture: modifiers.has("capture"),
+		passive: modifiers.has("passive")
+	};
+	return {
+		selector,
+		eventType,
+		options
+	};
+}
+var IlhaBuilder = class IlhaBuilder {
+	constructor(_schema, _states, _deriveds, _ons, _effects, _slots, _transition, _binds) {
+		this._schema = _schema;
+		this._states = _states;
+		this._deriveds = _deriveds;
+		this._ons = _ons;
+		this._effects = _effects;
+		this._slots = _slots;
+		this._transition = _transition;
+		this._binds = _binds;
+	}
+	input(schema) {
+		return new IlhaBuilder(schema, [], [], [], [], {}, null, []);
+	}
+	state(key, init) {
+		return new IlhaBuilder(this._schema, [...this._states, {
+			key,
+			init
+		}], this._deriveds, this._ons, this._effects, this._slots, this._transition, this._binds);
+	}
+	derived(key, fn) {
+		return new IlhaBuilder(this._schema, this._states, [...this._deriveds, {
+			key,
+			fn
+		}], this._ons, this._effects, this._slots, this._transition, this._binds);
+	}
+	bind(selector, stateKey) {
+		return new IlhaBuilder(this._schema, this._states, this._deriveds, this._ons, this._effects, this._slots, this._transition, [...this._binds, {
+			selector,
+			stateKey
+		}]);
+	}
+	on(selectorOrCombined, callbackOrEventType, handler) {
+		const parsed = parseOnArgs(selectorOrCombined, callbackOrEventType);
+		const resolvedHandler = typeof callbackOrEventType === "function" ? callbackOrEventType : handler;
+		return new IlhaBuilder(this._schema, this._states, this._deriveds, [...this._ons, {
+			selector: parsed.selector,
+			event: parsed.eventType,
+			options: parsed.options,
+			handler: resolvedHandler
+		}], this._effects, this._slots, this._transition, this._binds);
+	}
+	effect(fn) {
+		return new IlhaBuilder(this._schema, this._states, this._deriveds, this._ons, [...this._effects, { fn }], this._slots, this._transition, this._binds);
+	}
+	slot(name, island) {
+		return new IlhaBuilder(this._schema, this._states, this._deriveds, this._ons, this._effects, {
+			...this._slots,
+			[name]: island
+		}, this._transition, this._binds);
+	}
+	transition(opts) {
+		return new IlhaBuilder(this._schema, this._states, this._deriveds, this._ons, this._effects, this._slots, opts, this._binds);
+	}
+	render(fn) {
+		const schema = this._schema;
+		const states = this._states;
+		const deriveds = this._deriveds;
+		const ons = this._ons;
+		const effects = this._effects;
+		const slotDefs = this._slots;
+		const transition = this._transition;
+		const binds = this._binds;
+		function resolveInput(props) {
+			const value = props ?? {};
+			if (!schema) return value;
+			return validateSchema(schema, value);
+		}
+		function makeSlotsProxy(ssr) {
+			return new Proxy({}, { get(_, prop) {
+				const name = String(prop);
+				if (!slotDefs[name]) return makeSlotAccessor(() => "");
+				if (ssr) return makeSlotAccessor((props) => slotDefs[name].toString(props));
+				return makeSlotAccessor((props) => {
+					const json = props ? ` data-props='${escapeHtml(JSON.stringify(props))}'` : "";
+					return `<div data-ilha-slot="${escapeHtml(name)}"${json}></div>`;
+				});
+			} });
+		}
+		function buildPlainState(input) {
+			const state = {};
+			for (const entry of states) {
+				const value = typeof entry.init === "function" ? entry.init(input) : entry.init;
+				const accessor = markSignalAccessor((...args) => {
+					if (args.length === 0) return value;
+				});
+				state[entry.key] = accessor;
+			}
+			return state;
+		}
+		function buildSignalState(input, snapshot) {
+			const state = {};
+			for (const entry of states) {
+				const s = signal(snapshot && entry.key in snapshot ? snapshot[entry.key] : typeof entry.init === "function" ? entry.init(input) : entry.init);
+				const accessor = markSignalAccessor((...args) => {
+					if (args.length === 0) return s();
+					s(args[0]);
+				});
+				state[entry.key] = accessor;
+			}
+			return state;
+		}
+		function renderToString(props) {
+			const input = resolveInput(props);
+			const state = buildPlainState(input);
+			const slots = makeSlotsProxy(true);
+			const results = deriveds.map((entry) => {
+				try {
+					return {
+						key: entry.key,
+						result: entry.fn({
+							state,
+							input,
+							signal: new AbortController().signal
+						})
+					};
+				} catch (err) {
+					return {
+						key: entry.key,
+						result: Promise.reject(err)
+					};
+				}
+			});
+			if (!results.some((r) => r.result instanceof Promise)) {
+				const derived = {};
+				for (const r of results) derived[r.key] = {
+					loading: false,
+					value: r.result,
+					error: void 0
+				};
+				return fn({
+					state,
+					derived,
+					input,
+					slots
+				});
+			}
+			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((resolved) => {
+				const derived = {};
+				for (const r of resolved) derived[r.key] = r.envelope;
+				return fn({
+					state,
+					derived,
+					input,
+					slots
+				});
+			});
+		}
+		function renderToStringSyncOnly(props) {
+			const input = resolveInput(props);
+			const state = buildPlainState(input);
+			const slots = makeSlotsProxy(true);
+			return fn({
+				state,
+				derived: makePlainDerived(deriveds, state, input),
+				input,
+				slots
+			});
+		}
+		function mountIsland(el, props) {
+			const input = resolveInput(props);
+			let snapshot;
+			const rawState = el.getAttribute(STATE_ATTR);
+			if (rawState) try {
+				snapshot = JSON.parse(rawState);
+			} catch {
+				console.warn("[ilha] Failed to parse data-ilha-state");
+			}
+			const state = buildSignalState(input, snapshot);
+			const cleanups = [];
+			if (transition?.enter) {
+				const result = transition.enter(el);
+				if (result instanceof Promise) result.catch(console.error);
+			}
+			const { proxy: derived, stop: stopDerived } = buildDerivedSignals(deriveds, state, input);
+			cleanups.push(stopDerived);
+			const slotEls = /* @__PURE__ */ new Map();
+			function snapshotSlots() {
+				slotEls.clear();
+				for (const name of Object.keys(slotDefs)) {
+					const existing = el.querySelector(`[${SLOT_ATTR}="${name}"]`);
+					if (existing) slotEls.set(name, existing);
+				}
+			}
+			function restoreSlots() {
+				for (const [name, slotEl] of slotEls) {
+					const placeholder = el.querySelector(`[${SLOT_ATTR}="${name}"]`);
+					if (placeholder) placeholder.replaceWith(slotEl);
+				}
+			}
+			const listeners = [];
+			const firedOnce = /* @__PURE__ */ new Set();
+			function attachListeners() {
+				for (const entry of ons) {
+					if (entry.options.once && firedOnce.has(entry)) continue;
+					(entry.selector === "" ? [el] : Array.from(el.querySelectorAll(entry.selector))).forEach((target) => {
+						const listener = (event) => {
+							if (entry.options.once) {
+								firedOnce.add(entry);
+								for (const l of listeners.filter((l) => l.entry === entry)) l.target.removeEventListener(l.type, l.fn, l.options);
+								listeners.splice(0, listeners.length, ...listeners.filter((l) => l.entry !== entry));
+							}
+							const result = entry.handler({
+								state,
+								input,
+								el,
+								event
+							});
+							if (result instanceof Promise) result.catch(console.error);
+						};
+						const opts = {
+							...entry.options,
+							once: false
+						};
+						target.addEventListener(entry.event, listener, opts);
+						listeners.push({
+							target,
+							type: entry.event,
+							fn: listener,
+							options: opts,
+							entry
+						});
+					});
+				}
+			}
+			function detachListeners() {
+				for (const l of listeners) l.target.removeEventListener(l.type, l.fn, l.options);
+				listeners.length = 0;
+			}
+			const slots = makeSlotsProxy(false);
+			el.innerHTML = fn({
+				state,
+				derived,
+				input,
+				slots
+			});
+			attachListeners();
+			let stopBindings = applyBindings(el, binds, state);
+			cleanups.push(() => stopBindings());
+			for (const [name, childIsland] of Object.entries(slotDefs)) {
+				const slotEl = el.querySelector(`[${SLOT_ATTR}="${name}"]`);
+				if (!slotEl) continue;
+				slotEls.set(name, slotEl);
+				let slotProps;
+				const ilhaProps = slotEl.getAttribute(SLOT_PROPS_ATTR);
+				const dataProps = slotEl.getAttribute("data-props");
+				if (ilhaProps) try {
+					slotProps = JSON.parse(ilhaProps);
+				} catch {
+					console.warn(`[ilha] Failed to parse ${SLOT_PROPS_ATTR} on [${SLOT_ATTR}="${name}"]`);
+				}
+				else if (dataProps) try {
+					slotProps = JSON.parse(dataProps);
+				} catch {
+					console.warn(`[ilha] Failed to parse data-props on [${SLOT_ATTR}="${name}"]`);
+				}
+				cleanups.push(childIsland.mount(slotEl, slotProps));
+			}
+			let initialized = false;
+			const stopRender = effect(() => {
+				const html = fn({
+					state,
+					derived,
+					input,
+					slots
+				});
+				if (!initialized) {
+					initialized = true;
+					return;
+				}
+				snapshotSlots();
+				detachListeners();
+				stopBindings();
+				el.innerHTML = html;
+				restoreSlots();
+				attachListeners();
+				stopBindings = applyBindings(el, binds, state);
+			});
+			cleanups.push(stopRender);
+			cleanups.push(detachListeners);
+			for (const entry of effects) {
+				let userCleanup;
+				const stopEffect = effect(() => {
+					if (userCleanup) {
+						userCleanup();
+						userCleanup = void 0;
+					}
+					userCleanup = entry.fn({
+						state,
+						input,
+						el
+					});
+				});
+				cleanups.push(() => {
+					stopEffect();
+					if (userCleanup) userCleanup();
+				});
+			}
+			return () => {
+				if (transition?.leave) {
+					const result = transition.leave(el);
+					if (result instanceof Promise) {
+						result.then(() => cleanups.forEach((c) => c())).catch(console.error);
+						return;
+					}
+				}
+				cleanups.forEach((c) => c());
+			};
+		}
+		const island = function(props) {
+			return renderToString(props);
+		};
+		island.toString = (props) => renderToStringSyncOnly(props);
+		island.mount = (el, props) => mountIsland(el, props);
+		return island;
+	}
+};
+function ilhaFrom(selector, island, props) {
+	const el = typeof selector === "string" ? document.querySelector(selector) : selector;
+	if (!el) {
+		console.warn(`[ilha] from(): element not found: ${selector}`);
+		return null;
+	}
+	return island.mount(el, props);
+}
+function mountAll(registry, options = {}) {
+	const root = options.root ?? document.body;
+	const lazy = options.lazy ?? false;
+	const hydrate = options.hydrate ?? false;
+	const unmounts = [];
+	function activateEl(el) {
+		const name = el.getAttribute("data-ilha");
+		if (!name) return;
+		const island = registry[name];
+		if (!island) return;
+		let props = {};
+		const rawProps = el.getAttribute("data-props");
+		if (rawProps) try {
+			props = JSON.parse(rawProps);
+		} catch {
+			console.warn(`[ilha] Failed to parse data-props on [data-ilha="${name}"]`);
+		}
+		if (hydrate) {
+			const snapshot = el.innerHTML;
+			const unmount = island.mount(el, props);
+			if (!el.innerHTML) el.innerHTML = snapshot;
+			unmounts.push(unmount);
+		} else unmounts.push(island.mount(el, props));
+	}
+	const els = Array.from(root.querySelectorAll("[data-ilha]"));
+	if (lazy && typeof IntersectionObserver !== "undefined") {
+		const io = new IntersectionObserver((entries) => {
+			for (const entry of entries) if (entry.isIntersecting) {
+				activateEl(entry.target);
+				io.unobserve(entry.target);
+			}
+		});
+		els.forEach((el) => io.observe(el));
+		unmounts.push(() => io.disconnect());
+	} else els.forEach(activateEl);
+	return { unmount: () => unmounts.forEach((u) => u()) };
+}
+const rootBuilder = new IlhaBuilder(null, [], [], [], [], {}, null, []);
+const ilha = Object.assign(rootBuilder, {
+	html: ilhaHtml,
+	raw: ilhaRaw,
+	mount: mountAll,
+	from: ilhaFrom,
+	context: ilhaContext
+});
+const html = ilhaHtml;
+const raw = ilhaRaw;
+const mount = mountAll;
+const from = ilhaFrom;
+const context = ilhaContext;
+//#endregion
+export { context, ilha as default, from, html, mount, raw };

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "ilha",
+  "version": "0.0.1",
+  "description": "A tiny, framework-free island architecture library",
+  "license": "MIT",
+  "author": "Ryuz <ryuzer@proton.me>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/guarana-studio/ilha.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "module": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && tsdown",
+    "test": "bun test",
+    "playground": "bun playground/index.html",
+    "lint": "oxlint",
+    "fmt": "oxfmt",
+    "prepare": "husky",
+    "docs:dev": "bunx docsome dev DOCS.md",
+    "docs:build": "bunx docsome build DOCS.md --outDir docs_dist"
+  },
+  "dependencies": {
+    "alien-signals": "^3.1.2"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.7",
+    "@types/bun": "latest",
+    "docsome": "^0.0.6",
+    "husky": "^9.1.7",
+    "oxfmt": "^0.41.0",
+    "oxlint": "^1.56.0",
+    "tsdown": "^0.21.4",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  }
+}