ilha 0.15.2 → 0.16.0

package/AGENTS.md

@@ -0,0 +1,102 @@
+# ilha 0.16.0 — agent guide
+
+Generated from `src/index.ts` by `scripts/agent-docs.ts`. Do not edit by hand.
+
+ilha is a tiny, isomorphic islands UI library on Effect 4 (`effect` is the only peer dependency). A component is a function (sync, async, or generator) that returns JSX. State lives in order-based `atom()` slots. There is no virtual DOM and no compiler.
+
+```tsx
+import { atom, mount } from "ilha";
+
+const Counter = () => {
+  const count = atom(0);
+  return (
+    <button type="button" onclick={() => count.update((n) => n + 1)}>
+      Count: {count}
+    </button>
+  );
+};
+
+mount(document.getElementById("app")!, Counter);
+```
+
+## Pick exactly one API per task
+
+| Task | Use |
+| --- | --- |
+| Local state | `const n = atom(0)` |
+| Derived value | `atom(Atom.map(source.atom, fn))` or `atom(Atom.transform(...))` |
+| One-time init | `atom.lazy(() => expensive())` |
+| React to a change | `watch(source, fn)` |
+| Mount-only side effect | `watch.once(fn)` (return a cleanup) |
+| Async data | `atom(Effect)`, read as `AsyncResult` — see /guide/recipes/data-fetching |
+| Live data | `yield` an Effect `Stream` from a generator component |
+| Per-emission interruptible flow | `yield* when(stream, function* (v) {...})` |
+| Share values down the tree | `createContext()` + `context(ctx)` |
+| Handle failures | `<ErrorBoundary fallback={...}>` |
+| Server render | `await renderToString(Component)` |
+| Client render | `mount(host, Component)`, or `mount(host, Component, { hydrate: true })` over server HTML |
+| Raw trusted HTML | `unsafe(html)` |
+
+Full table: https://ilha.build/guide/getting-started/choose-an-api
+
+## Never do
+
+- Never call `atom()`, `watch()`, or `when()` conditionally, in loops, or after an early return: slots are order-based.
+- Never read an atom with `.value` or `.get()`: call `count()`, or pass `{count}` in JSX.
+- Never wrap Effect Atom APIs (`Atom.map`, `Atom.transform`, `Atom.fn`): pass `handle.atom` to them and wrap the result in `atom()`.
+- Never use `useState`, `useEffect`, or other React hooks: there is no hook layer.
+- Never pass untrusted input to `unsafe()`.
+- Never import removed APIs (`resource`, `invalidate`, `fromEventSource`, `ilha/define`, `structuralEqual`): see MIGRATIONS.md.
+- Never use an atom handle from another island: it throws ILHA003.
+
+## Public API (`ilha`)
+
+- `atom` — Declare reactive state in a component: `atom(0)`, `atom(effect | stream)` (handle holds an `AsyncResult`), `atom(Atom.map(...))` (derived), `atom.lazy(() => init)` (one-time init). Read `count()`, write `count.set(v)` / `count.update(fn)`.
+- `batch` — Group several atom writes into one rerender (re-export of Effect `Atom.batch`).
+- `context` — Read a context value as an atom handle.
+- `createContext` — `createContext(default)` returns a context whose `Provider` (`<Ctx.Provider value={v}>`) shares a value down the tree; read it with `context(ctx)`.
+- `ErrorBoundary` — Catch subtree failures and paint a fallback.
+- `Fragment` — Group children without a wrapper element (`<>...</>`).
+- `h` — Build a vnode by hand; JSX compiles to this.
+- `IlhaError` — Error thrown for misuse, with `code` (ILHA001..), `fix`, and `docs` fields.
+- `mount` — `mount(host, Component, { hydrate?, onError?, onIdle? })` renders in the browser and returns a dispose function. With `{ hydrate: true }` it adopts server HTML.
+- `renderToString` — `await renderToString(Component, { timeout?, snapshot?, markers? })` renders HTML on the server, awaiting async components and streams (first emission).
+- `unsafe` — Mark a string as pre-rendered HTML and paint it without escaping.
+- `untrack` — Read atoms inside `fn` without subscribing the active render.
+- `watch` — `watch(source, ({ signal }) => ...)` reacts to an atom, Effect atom, or Stream; `watch.once(fn)` runs once on mount and may return a cleanup. Both return `Instruction<void>` — call at the top level of the component, in the same order every render.
+- `when` — Rerun `body` for every value of `stream`, replacing the previous run.
+
+Types: `AtomEquality`, `AtomHandle`, `AtomLazyOptions`, `AtomOptions`, `Component`, `ContextProviderProps`, `ErrorBoundaryProps`, `ErrorFallback`, `ErrorFallbackProps`, `IlhaCode`, `IlhaContext`, `MountOptions`, `RenderToStringOptions`, `UnsafeHtml`, `View`, `WatchCallback`, `WatchContext`, `WatchOnceCleanup`.
+
+## Subpaths
+
+- `ilha/jsx-runtime` — JSX factory. Set `jsxImportSource: "ilha"` in tsconfig; also `ilha/jsx-dev-runtime`.
+- `ilha/renderer` — `createRenderer`/`PaintOps` seam for hosts that are not a DOM (native, test harness).
+- `ilha/test` — `render(component)` harness for unit tests — see /guide/recipes/testing.
+- `ilha/debug` — `inspect()` returns JSON-serializable trees of live islands; `roots()`, `onChange()` — see /guide/devtools.
+- `ilha/oxlint` — Oxlint JS plugin enforcing ilha rules — see /guide/recipes/oxlint.
+- `@ilha/devtools` — Separate package: in-browser inspector built on `ilha/debug` — see /guide/devtools.
+
+## Errors
+
+Every diagnostic is an `IlhaError` (or a console warning) with a stable code, a `fix` line, and a docs link.
+
+| Code | Meaning |
+| --- | --- |
+| [ILHA001](https://ilha.build/errors/ILHA001) | Primitive called with no active component |
+| [ILHA002](https://ilha.build/errors/ILHA002) | Atom/watch slot count changed between renders (warning) |
+| [ILHA003](https://ilha.build/errors/ILHA003) | Atom handle used from a different island |
+| [ILHA004](https://ilha.build/errors/ILHA004) | Generator resumed while an instruction is in flight |
+| [ILHA005](https://ilha.build/errors/ILHA005) | Duplicate key among sibling components (warning) |
+| [ILHA006](https://ilha.build/errors/ILHA006) | Hydration mismatch (warning) |
+| [ILHA007](https://ilha.build/errors/ILHA007) | Unsafe raw text in <script>/<style> during renderToString |
+
+Details and fixes: https://ilha.build/errors
+
+## Where to read more
+
+- Docs index for LLMs: https://ilha.build/llms.txt
+- Removed or changed APIs: `MIGRATIONS.md` / `MIGRATIONS.json` in this package
+- Testing: https://ilha.build/guide/recipes/testing
+- Devtools and `ilha/debug`: https://ilha.build/guide/devtools
+- Lint rules: https://ilha.build/guide/recipes/oxlint

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Ryuz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/MIGRATIONS.json

@@ -0,0 +1,96 @@
+{
+  "package": "ilha",
+  "docs": "https://ilha.build/llms.txt",
+  "changes": [
+    {
+      "id": "resource",
+      "kind": "removed",
+      "api": "resource, invalidate",
+      "import": "ilha",
+      "replacement": "An Effect Cache in a module, read through atom(Effect).",
+      "docs": "https://ilha.build/guide/recipes/data-fetching",
+      "before": "const user = resource(\"user\", (id, { signal }) => fetchUser(id, signal));\nuser.data();",
+      "after": "const users = Effect.runSync(Cache.make({ capacity: 100, lookup: loadUser, timeToLive: \"1 minute\" }));\nconst user = atom(Cache.get(users, id)); // AsyncResult"
+    },
+    {
+      "id": "from-event-source",
+      "kind": "removed",
+      "api": "fromEventSource",
+      "import": "ilha",
+      "replacement": "Stream.callback over EventSource with Stream.retry.",
+      "docs": "https://ilha.build/guide/recipes/server-sent-events",
+      "before": "const feed = fromEventSource(\"/events\");\nyield Stream.map(feed.stream, (m) => <p>{m}</p>);",
+      "after": "const events = Stream.callback<string>((queue) => { /* see recipe */ });\nyield Stream.map(events, (m) => <p>{m}</p>);"
+    },
+    {
+      "id": "define",
+      "kind": "removed",
+      "api": "define",
+      "import": "ilha/define",
+      "replacement": "Copy the define() helper from the custom-elements recipe; it calls mount() in connectedCallback.",
+      "docs": "https://ilha.build/guide/recipes/custom-elements",
+      "before": "import { define } from \"ilha/define\";\ndefine(\"ilha-counter\", Counter);",
+      "after": "import { define } from \"./define\"; // helper from the recipe\ndefine(\"ilha-counter\", Counter);"
+    },
+    {
+      "id": "structural-equal",
+      "kind": "removed",
+      "api": "structuralEqual",
+      "import": "ilha",
+      "replacement": "Equal.equals from effect, or the equals: \"structural\" atom option.",
+      "docs": "https://ilha.build/guide/ui/state",
+      "before": "atom(value, { equals: structuralEqual });",
+      "after": "atom(value, { equals: \"structural\" });\n// or: import * as Equal from \"effect/Equal\"; Equal.equals(a, b)"
+    },
+    {
+      "id": "capture-actions",
+      "kind": "removed",
+      "api": "renderToString option captureActions",
+      "import": "ilha",
+      "replacement": "Remove the option. SSR no longer captures actions; hydration restores state from the embedded snapshot.",
+      "docs": "https://ilha.build/guide/ui/render",
+      "before": "await renderToString(Component, { captureActions: true });",
+      "after": "await renderToString(Component);"
+    },
+    {
+      "id": "island-mount-hook",
+      "kind": "removed",
+      "api": "internal island mount hook (ISLAND_MOUNT_INTERNAL)",
+      "import": "ilha",
+      "replacement": "None. It was internal. Use mount(host, Component) for every root.",
+      "docs": "https://ilha.build/guide/ui/render",
+      "before": "",
+      "after": "mount(host, Component, { hydrate: true });"
+    },
+    {
+      "id": "watch-when-instruction",
+      "kind": "changed",
+      "api": "watch, watch.once, when",
+      "import": "ilha",
+      "replacement": "They return Instruction<void>. Call them at the top level of the component (yield* is optional in generators); do not read a return value.",
+      "docs": "https://ilha.build/guide/ui/state",
+      "before": "const result = yield* watch(count, fn); // loosely typed result",
+      "after": "watch(count, fn);"
+    },
+    {
+      "id": "atom-async-result",
+      "kind": "changed",
+      "api": "atom(effect | stream)",
+      "import": "ilha",
+      "replacement": "The handle is typed AtomHandle<AsyncResult<A, E>>. Branch on Initial, Success, and Failure instead of reading the value directly. Any atom handle is a valid View.",
+      "docs": "https://ilha.build/guide/recipes/data-fetching",
+      "before": "const user = atom(fetchUser); // typed as the value\nuser().name",
+      "after": "const user = atom(fetchUser); // AsyncResult<User, Error>\nAsyncResult.isSuccess(user()) && user().value.name"
+    },
+    {
+      "id": "renderer-paint-ops",
+      "kind": "changed",
+      "api": "PaintOps",
+      "import": "ilha/renderer",
+      "replacement": "appendRoot, asRoot, asNode, asElement, createSlotHost, and disconnect are removed. reuseNode, committed, setStyle, setFormControl, and bindEvents are optional. morph is added.",
+      "docs": "https://ilha.build/reference/ilha",
+      "before": "const ops: PaintOps<Node, El> = { createElement, createText, createRaw, placeChildren, appendRoot, asRoot, asNode, asElement, createSlotHost, disconnect, /* ... */ };",
+      "after": "const ops: PaintOps<Node, El> = { createElement, createText, createRaw, placeChildren, morph /* optional: reuseNode, committed, setStyle, setFormControl, bindEvents */ };"
+    }
+  ]
+}

package/MIGRATIONS.md

@@ -0,0 +1,198 @@
+# ilha migrations
+
+Generated from `MIGRATIONS.json` by `scripts/agent-docs.ts`. Do not edit by hand.
+
+Removed and changed APIs, each with its replacement. Machine-readable form: `MIGRATIONS.json`. Index for LLMs: https://ilha.build/llms.txt
+
+## resource, invalidate
+
+- Status: removed
+- Import: `ilha`
+- Replacement: An Effect Cache in a module, read through atom(Effect).
+- Docs: https://ilha.build/guide/recipes/data-fetching
+
+Before:
+
+```ts
+const user = resource("user", (id, { signal }) => fetchUser(id, signal));
+user.data();
+```
+
+After:
+
+```ts
+const users = Effect.runSync(
+  Cache.make({ capacity: 100, lookup: loadUser, timeToLive: "1 minute" })
+);
+const user = atom(Cache.get(users, id)); // AsyncResult
+```
+
+## fromEventSource
+
+- Status: removed
+- Import: `ilha`
+- Replacement: Stream.callback over EventSource with Stream.retry.
+- Docs: https://ilha.build/guide/recipes/server-sent-events
+
+Before:
+
+```ts
+const feed = fromEventSource("/events");
+yield Stream.map(feed.stream, (m) => <p>{m}</p>);
+```
+
+After:
+
+```ts
+const events = Stream.callback<string>((queue) => { /* see recipe */ });
+yield Stream.map(events, (m) => <p>{m}</p>);
+```
+
+## define
+
+- Status: removed
+- Import: `ilha/define`
+- Replacement: Copy the define() helper from the custom-elements recipe; it calls mount() in connectedCallback.
+- Docs: https://ilha.build/guide/recipes/custom-elements
+
+Before:
+
+```ts
+import { define } from "ilha/define";
+define("ilha-counter", Counter);
+```
+
+After:
+
+```ts
+import { define } from "./define"; // helper from the recipe
+define("ilha-counter", Counter);
+```
+
+## structuralEqual
+
+- Status: removed
+- Import: `ilha`
+- Replacement: Equal.equals from effect, or the equals: "structural" atom option.
+- Docs: https://ilha.build/guide/ui/state
+
+Before:
+
+```ts
+atom(value, { equals: structuralEqual });
+```
+
+After:
+
+```ts
+atom(value, { equals: "structural" });
+// or: import * as Equal from "effect/Equal"; Equal.equals(a, b)
+```
+
+## renderToString option captureActions
+
+- Status: removed
+- Import: `ilha`
+- Replacement: Remove the option. SSR no longer captures actions; hydration restores state from the embedded snapshot.
+- Docs: https://ilha.build/guide/ui/render
+
+Before:
+
+```ts
+await renderToString(Component, { captureActions: true });
+```
+
+After:
+
+```ts
+await renderToString(Component);
+```
+
+## internal island mount hook (ISLAND_MOUNT_INTERNAL)
+
+- Status: removed
+- Import: `ilha`
+- Replacement: None. It was internal. Use mount(host, Component) for every root.
+- Docs: https://ilha.build/guide/ui/render
+
+After:
+
+```ts
+mount(host, Component, { hydrate: true });
+```
+
+## watch, watch.once, when
+
+- Status: changed
+- Import: `ilha`
+- Replacement: They return Instruction<void>. Call them at the top level of the component (yield* is optional in generators); do not read a return value.
+- Docs: https://ilha.build/guide/ui/state
+
+Before:
+
+```ts
+const result = yield * watch(count, fn); // loosely typed result
+```
+
+After:
+
+```ts
+watch(count, fn);
+```
+
+## atom(effect | stream)
+
+- Status: changed
+- Import: `ilha`
+- Replacement: The handle is typed AtomHandle<AsyncResult<A, E>>. Branch on Initial, Success, and Failure instead of reading the value directly. Any atom handle is a valid View.
+- Docs: https://ilha.build/guide/recipes/data-fetching
+
+Before:
+
+```ts
+const user = atom(fetchUser); // typed as the value
+user().name;
+```
+
+After:
+
+```ts
+const user = atom(fetchUser); // AsyncResult<User, Error>
+AsyncResult.isSuccess(user()) && user().value.name;
+```
+
+## PaintOps
+
+- Status: changed
+- Import: `ilha/renderer`
+- Replacement: appendRoot, asRoot, asNode, asElement, createSlotHost, and disconnect are removed. reuseNode, committed, setStyle, setFormControl, and bindEvents are optional. morph is added.
+- Docs: https://ilha.build/reference/ilha
+
+Before:
+
+```ts
+const ops: PaintOps<Node, El> = {
+  createElement,
+  createText,
+  createRaw,
+  placeChildren,
+  appendRoot,
+  asRoot,
+  asNode,
+  asElement,
+  createSlotHost,
+  disconnect /* ... */,
+};
+```
+
+After:
+
+```ts
+const ops: PaintOps<Node, El> = {
+  createElement,
+  createText,
+  createRaw,
+  placeChildren,
+  morph /* optional: reuseNode, committed, setStyle, setFormControl, bindEvents */,
+};
+```

package/README.md

@@ -112,12 +112,11 @@ const host = document.querySelector("[data-ilha]");
 if (host) mount(host, Counter, { hydrate: true });
 ```
 
-| Option           | Default | Meaning                        |
-| ---------------- | ------- | ------------------------------ |
-| `snapshot`       | `true`  | Embed atom values              |
-| `markers`        | `true`  | Wrap in `<div data-ilha>`      |
-| `timeout`        | none    | Serialize after this many ms   |
-| `captureActions` | `false` | Probe handlers for server RPCs |
+| Option     | Default | Meaning                      |
+| ---------- | ------- | ---------------------------- |
+| `snapshot` | `true`  | Embed atom values            |
+| `markers`  | `true`  | Wrap in `<div data-ilha>`    |
+| `timeout`  | none    | Serialize after this many ms |
 
 `renderToString` builds HTML without a DOM — no polyfill in Node, Bun, or edge runtimes.
 
@@ -138,31 +137,15 @@ Event props are lowercase (`onclick`, `onchange`). Use `class`, not `className`.
 
 ---
 
-## Custom elements
+## Recipes
 
-```ts
-import { atom } from "ilha";
-import { define } from "ilha/define";
-
-define("ilha-counter", () => {
-  const count = atom(0);
-  return (
-    <button type="button" onclick={() => count.update((n: number) => n + 1)}>
-      {count}
-    </button>
-  );
-});
-```
-
-```html
-<ilha-counter data-ilha></ilha-counter>
-```
+Data fetching, server-sent events, and custom elements are short Effect recipes rather than exports: see [ilha.build/guide/recipes](https://ilha.build/guide/recipes/data-fetching).
 
 ---
 
-## Routing and Astro
+## Void and Astro
 
-- [`@ilha/router`](https://github.com/ilhajs/ilha/tree/main/packages/router) — file-system SPA routes and Oxide server islands.
+- [`@ilha/void`](https://github.com/ilhajs/ilha/tree/main/packages/void) — Void pages, layouts, forms, and islands.
 - [`@ilha/astro`](https://github.com/ilhajs/ilha/tree/main/packages/astro) — Astro renderer (`renderToString` + `mount`).
 
 Docs: [ilha.build](https://ilha.build)

package/dist/debug.d.ts

@@ -0,0 +1,45 @@
+import { t as SnapshotValue } from "./snapshot-BDC74QwI.js";
+//#region src/debug.d.ts
+/** An atom value made JSON-safe: functions and Effects become `<…>` strings. */
+export type InspectValue = SnapshotValue | string;
+export interface IlhaInspectAtom {
+  /** Position among the component's `atom()` slots, in declaration order. */
+  readonly index: number;
+  readonly value: InspectValue;
+}
+export interface IlhaInspectNode {
+  /** Stable while the component lives; pass it to `setAtom` and `element`. */
+  readonly id: string;
+  readonly component: string;
+  /** CSS-like description of the host element; absent for non-DOM roots. */
+  readonly host?: string;
+  readonly atoms: readonly IlhaInspectAtom[];
+  readonly children: readonly IlhaInspectNode[];
+}
+export type SetAtomResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * JSON-serializable trees of the live roots: component names, atom values,
+ * and child components. Pass `host` to inspect one root or component host.
+ */
+export declare const inspect: (host?: Element) => IlhaInspectNode[];
+/** Host elements of the live DOM roots. SSR and custom-renderer roots have none. */
+export declare const roots: () => Element[];
+/** The element an inspected component paints into, to highlight or measure. */
+export declare const element: (id: string) => Element | undefined;
+/**
+ * Replace atom `index` of component `id` with a JSON `value`. Only writable
+ * state atoms accept it; derived atoms and Effect atoms report why they cannot.
+ */
+export declare const setAtom: <T extends SnapshotValue>(id: string, index: number, value: T) => SetAtomResult;
+/**
+ * Call `listener` after any root settles, mounts, or unmounts. The listener
+ * runs synchronously, so coalesce in it if you re-read the whole tree.
+ * Returns an unsubscribe function.
+ */
+export declare const onChange: (listener: () => void) => (() => void);
+//#endregion