ilha 0.15.1 → 0.16.0

package/dist/debug.js

@@ -0,0 +1,217 @@
+import { r as rootListeners, t as liveRoots } from "./start-B-e1dG5U.js";
+import { c as isObject, l as isString, o as isFunction, r as SLOT_ATTR } from "./shared-vpgYXytd.js";
+import * as Atom from "effect/reactivity/Atom";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
+
+//#region src/debug.ts
+/**
+* Introspection for tests, devtools, and coding agents (`ilha/debug`).
+*
+* `inspect()` returns JSON-serializable trees of the live roots, and
+* `onChange()` reports when a root settles. Nothing here runs unless you
+* import it: the core keeps only a set of live root fibers.
+*/
+const MAX_DEPTH = 6;
+const MAX_ITEMS = 100;
+const MAX_STRING = 2e3;
+const UNSAFE_KEY = /^(?:__proto__|constructor|prototype)$/u;
+const isNumber = (value) => typeof value === "number";
+const isBoolean = (value) => typeof value === "boolean";
+const isBigInt = (value) => typeof value === "bigint";
+const isSymbol = (value) => typeof value === "symbol";
+const isDomElement = (value) => "Element" in globalThis && value instanceof globalThis.Element;
+const nameOfFunction = (value) => {
+	if (!isFunction(value)) return "";
+	return Object.getOwnPropertyDescriptor(value, "name")?.value ?? "";
+};
+const constructorName = (value) => {
+	const proto = Object.getPrototypeOf(value);
+	return proto === null ? "Object" : nameOfFunction(Object.getOwnPropertyDescriptor(proto, "constructor")?.value) || "Object";
+};
+const isPlainObject = (value) => {
+	const proto = Object.getPrototypeOf(value);
+	return proto === null || proto === Object.prototype;
+};
+const walk = { summarize: () => null };
+const summarizeAsync = (value, depth, seen) => {
+	if (AsyncResult.isFailure(value)) {
+		const failure = AsyncResult.error(value);
+		return `<AsyncResult failure: ${failure._tag === "Some" ? String(failure.value) : "defect"}>`;
+	}
+	const payload = AsyncResult.value(value);
+	if (payload._tag === "Some") return walk.summarize(payload.value, depth, seen);
+	return AsyncResult.isWaiting(value) ? "<AsyncResult waiting>" : "<AsyncResult initial>";
+};
+const summarizeList = (items, depth, seen) => {
+	if (depth >= MAX_DEPTH) return `<Array(${items.length})>`;
+	const out = items.slice(0, MAX_ITEMS).map((item) => walk.summarize(item, depth + 1, seen));
+	if (items.length > MAX_ITEMS) out.push(`<${items.length - MAX_ITEMS} more>`);
+	return out;
+};
+const summarizeRecord = (value, depth, seen) => {
+	if (depth >= MAX_DEPTH) return "<Object>";
+	const out = {};
+	const entries = Object.entries(value).filter(([key]) => !UNSAFE_KEY.test(key));
+	for (const [key, item] of entries.slice(0, MAX_ITEMS)) out[key] = walk.summarize(item, depth + 1, seen);
+	if (entries.length > MAX_ITEMS) out["…"] = `<${entries.length - MAX_ITEMS} more>`;
+	return out;
+};
+/** Non-container values: scalars, functions, and anything else by name. */
+const summarizeLeaf = (value) => {
+	if (value === null) return null;
+	if (value === void 0) return "<undefined>";
+	if (isString(value)) return value.length > MAX_STRING ? `${value.slice(0, MAX_STRING)}…` : value;
+	if (isNumber(value)) return Number.isFinite(value) ? value : String(value);
+	if (isBoolean(value)) return value;
+	if (isBigInt(value)) return `<bigint ${value}>`;
+	if (isSymbol(value)) return `<symbol ${value.description ?? ""}>`.replace(" >", ">");
+	if (isFunction(value)) return `<function ${nameOfFunction(value) || "anonymous"}>`;
+	return `<${String(value)}>`;
+};
+/** Effect values and dates, maps, errors: named rather than expanded. */
+const summarizeOpaque = (value) => {
+	if (Atom.isAtom(value)) return "<Atom>";
+	if (Effect.isEffect(value)) return "<Effect>";
+	if (Stream.isStream(value)) return "<Stream>";
+	if (value instanceof Date) return Number.isNaN(value.getTime()) ? "<Invalid Date>" : value.toISOString();
+	if (value instanceof Map || value instanceof Set) return `<${constructorName(value)}(${value.size})>`;
+	if (value instanceof Error) return `<${constructorName(value)}: ${value.message}>`;
+};
+const summarizeContainer = (value, depth, seen) => {
+	if (AsyncResult.isAsyncResult(value)) return summarizeAsync(value, depth, seen);
+	const opaque = summarizeOpaque(value);
+	if (opaque !== void 0) return opaque;
+	if (seen.has(value)) return "<circular>";
+	seen.add(value);
+	try {
+		if (Array.isArray(value)) return summarizeList(value, depth, seen);
+		return isPlainObject(value) ? summarizeRecord(value, depth, seen) : `<${constructorName(value)}>`;
+	} finally {
+		seen.delete(value);
+	}
+};
+/** Reduce any value to JSON, naming what JSON cannot carry. */
+const summarize = (value, depth, seen) => isObject(value) || Array.isArray(value) ? summarizeContainer(value, depth, seen) : summarizeLeaf(value);
+walk.summarize = summarize;
+const ids = /* @__PURE__ */ new WeakMap();
+let lastId = 0;
+const idOf = (fiber) => {
+	let id = ids.get(fiber);
+	if (id === void 0) {
+		lastId += 1;
+		id = `i${lastId}`;
+		ids.set(fiber, id);
+	}
+	return id;
+};
+const describeHost = (el) => {
+	const tag = el.tagName.toLowerCase();
+	if (el.id) return `${tag}#${el.id}`;
+	const slot = el.getAttribute(SLOT_ATTR);
+	if (slot !== null) return `${tag}[${SLOT_ATTR}="${slot}"]`;
+	const [first] = el.classList;
+	return first ? `${tag}.${first}` : tag;
+};
+const componentName = (fiber) => nameOfFunction(fiber.componentType) || (fiber.parent === void 0 ? "Root" : "Anonymous");
+/** Read an atom without starting work: unread effect atoms stay unevaluated. */
+const readAtom = (fiber, atom) => {
+	const node = fiber.registry.getNodes().get(atom);
+	const state = node?.currentState();
+	if (!node || state === "uninitialized" || state === "removed") return "<unread>";
+	return summarize(node.value(), 0, /* @__PURE__ */ new WeakSet());
+};
+/** Hole fibers that are components; atom and stream holes are looked through. */
+const componentChildren = (fiber) => fiber.holes.flatMap(({ fiber: hole }) => {
+	if (!hole || hole.closed) return [];
+	return hole.componentType === void 0 ? componentChildren(hole) : [hole];
+});
+const toNode = (fiber) => {
+	const node = {
+		atoms: (fiber.primitives ?? []).map((atom, index) => ({
+			index,
+			value: readAtom(fiber, atom)
+		})),
+		children: componentChildren(fiber).map(toNode),
+		component: componentName(fiber),
+		id: idOf(fiber)
+	};
+	return isDomElement(fiber.root) ? {
+		...node,
+		host: describeHost(fiber.root)
+	} : node;
+};
+/** Every fiber under `fiber` (itself included) whose root is `host`. */
+const fibersAt = (fiber, host) => fiber.root === host ? [fiber] : fiber.holes.flatMap(({ fiber: hole }) => hole && !hole.closed ? fibersAt(hole, host) : []);
+/** The live component fiber that `inspect()` gave `id`. */
+const findFiber = (id) => {
+	const visit = (fiber) => {
+		if (ids.get(fiber) === id) return fiber;
+		for (const child of componentChildren(fiber)) {
+			const hit = visit(child);
+			if (hit) return hit;
+		}
+	};
+	for (const root of liveRoots) {
+		const hit = visit(root);
+		if (hit) return hit;
+	}
+};
+/**
+* JSON-serializable trees of the live roots: component names, atom values,
+* and child components. Pass `host` to inspect one root or component host.
+*/
+const inspect = (host) => {
+	return [...liveRoots].flatMap((root) => host === void 0 ? [root] : fibersAt(root, host)).map(toNode);
+};
+/** Host elements of the live DOM roots. SSR and custom-renderer roots have none. */
+const roots = () => [...liveRoots].map((fiber) => fiber.root).filter(isDomElement);
+/** The element an inspected component paints into, to highlight or measure. */
+const element = (id) => {
+	const root = findFiber(id)?.root;
+	return isDomElement(root) ? root : void 0;
+};
+/**
+* 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.
+*/
+const setAtom = (id, index, value) => {
+	const fiber = findFiber(id);
+	if (!fiber) return {
+		ok: false,
+		reason: `No live component has id "${id}". Call inspect() again.`
+	};
+	const atom = fiber.primitives?.[index];
+	if (!atom) return {
+		ok: false,
+		reason: `Component "${id}" has no atom at index ${index}.`
+	};
+	if (!Atom.isWritable(atom)) return {
+		ok: false,
+		reason: `Atom ${index} of "${id}" is derived and read-only.`
+	};
+	fiber.registry.set(atom, value);
+	return { ok: true };
+};
+/**
+* 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.
+*/
+const onChange = (listener) => {
+	const guarded = () => {
+		try {
+			listener();
+		} catch (error) {
+			console.error(error);
+		}
+	};
+	rootListeners.add(guarded);
+	return () => {
+		rootListeners.delete(guarded);
+	};
+};
+
+//#endregion
+export { element, inspect, onChange, roots, setAtom };

package/dist/index.d.ts

@@ -1,11 +1,12 @@
-import { C as WatchOnceCleanup, S as WatchContext, _ as ResourceOptions, b as View, c as EventSourceStatus, d as Instruction, g as ResourceFetcher, h as Resource, i as Component, l as Fragment, n as AtomHandle, o as EventSourceFeed, r as AtomOptions, s as EventSourceOptions, t as AtomEquality, v as UnsafeHtml, w as Yielded, x as WatchCallback } from "./types-DsdtZMhG.js";
-import { t as h } from "./vnode-CpSQZnLM.js";
-import { r as watch } from "./runtime-Baq7MtkE.js";
+import { _ as View, a as Component, b as WatchOnceCleanup, f as MountOptions, h as UnsafeHtml, i as AtomOptions, l as Instruction, n as AtomHandle, r as AtomLazyOptions, s as Fragment, t as AtomEquality, v as WatchCallback, x as Yielded, y as WatchContext } from "./types-NhEiBvwy.js";
+import { t as h } from "./vnode-DskooLPD.js";
+import { r as watch } from "./runtime-BCdKBqYp.js";
+import { n as mount, r as renderToString, t as RenderToStringOptions } from "./mount-3Ggg67T0.js";
 import * as Atom from "effect/reactivity/Atom";
-import { Equal } from "effect";
-import * as Effect$1 from "effect/Effect";
-import * as Stream$1 from "effect/Stream";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
 import { AtomRegistry } from "effect/reactivity/AtomRegistry";
+import * as AsyncResult from "effect/reactivity/AsyncResult";
 //#region src/context.d.ts
 interface ContextProviderProps<A> {
   value: A;
@@ -20,6 +21,17 @@ export declare const createContext: <A>(defaultValue: A) => IlhaContext<A>;
 /** Read a context value as an atom handle. Subscribes the active fiber on read. */
 export declare const context: <A>(ctx: IlhaContext<A>) => AtomHandle<A>;
 //#endregion
+//#region src/diagnostics.d.ts
+/** Stable diagnostic codes. Each one has a page at `https://ilha.build/errors/<code>`. */
+type IlhaCode = "ILHA001" | "ILHA002" | "ILHA003" | "ILHA004" | "ILHA005" | "ILHA006" | "ILHA007";
+/** Error thrown by ilha with a stable `code`, a `fix` hint and a `docs` URL. */
+export declare class IlhaError extends Error {
+  readonly code: IlhaCode;
+  readonly fix: string;
+  readonly docs: string;
+  constructor(code: IlhaCode, detail?: string);
+}
+//#endregion
 //#region src/error-boundary.d.ts
 interface ErrorFallbackProps {
   error: Error;
@@ -35,57 +47,25 @@ interface ErrorBoundaryProps {
 export declare const ErrorBoundary: (props: ErrorBoundaryProps) => View;
 //#endregion
 //#region src/atom.d.ts
-/** Key-order-insensitive deep equality for JSON-shaped values. */
-export declare const structuralEqual: typeof Equal.equals;
 /** Read atoms inside `fn` without subscribing the active render. Sync only. */
 export declare const untrack: <A>(fn: () => A) => A;
 interface AtomFn {
-  <A>(init: A | Atom.Atom<A> | Effect$1.Effect<A, unknown, AtomRegistry> | Stream$1.Stream<A, unknown, AtomRegistry>, options?: AtomOptions<A>): AtomHandle<A>;
-  lazy: <A>(init: () => A) => AtomHandle<A>;
+  /** An effect or stream runs once; the handle holds its `AsyncResult`. */
+  <A, E>(init: Effect.Effect<A, E, AtomRegistry> | Stream.Stream<A, E, AtomRegistry>, options?: AtomOptions<AsyncResult.AsyncResult<A, E>>): AtomHandle<AsyncResult.AsyncResult<A, E>>;
+  /**
+   * An existing Effect atom, or a plain value. Store a function with
+   * `atom.lazy(() => fn)`; the `ilha/oxlint` rule `function-in-atom` flags
+   * `atom(fn)`.
+   */
+  <A>(init: Atom.Atom<A> | A, options?: AtomOptions<A>): AtomHandle<A>;
+  lazy: <A>(init: () => A, options?: AtomLazyOptions) => AtomHandle<A>;
 }
 export declare const atom: AtomFn;
 export declare const batch: (f: () => void) => void;
 //#endregion
-//#region src/resource.d.ts
-/** Drop the cached value for `key` and refetch it in live components. */
-export declare const invalidate: (key: string) => void;
-/**
- * Fetch-once, share-everywhere async state for `key`. Concurrent mounts
- * dedupe on one in-flight request; remounts seed from the shared cache
- * (and revalidate when `staleWhileRevalidate` holds). Call unconditionally
- * at the top level of a sync component, before any `await`.
- */
-export declare const resource: <T>(key: string, fetcher: ResourceFetcher<T>, opts?: ResourceOptions) => Resource<T>;
-//#endregion
-//#region src/sse.d.ts
-/**
- * Subscribe to server-sent events. Opens one connection per `(url, event)`
- * per component, reconnects with backoff, and closes on unmount. SSR renders
- * an empty stream with status `"closed"`. Call unconditionally at the top
- * level of a component.
- */
-export declare const fromEventSource: <T = string>(url: string, opts?: EventSourceOptions<T>) => EventSourceFeed<T>;
-//#endregion
 //#region src/when.d.ts
-export declare const when: <A, E = never, R = never>(stream: Stream$1.Stream<A, E, R>, body: (value: A) => Generator<Yielded, View | undefined, View>) => Instruction<undefined, E>;
-//#endregion
-//#region src/mount.d.ts
-interface RenderToStringOptions {
-  snapshot?: boolean;
-  markers?: boolean;
-  timeout?: number;
-  captureActions?: boolean;
-}
-interface MountOptions {
-  hydrate?: boolean;
-  /**
-   * Called with a failing root component, and with a nested component no
-   * `ErrorBoundary` caught, before the error view paints.
-   */
-  onError?: (error: Error) => void;
-}
-export declare const mount: (el: Element, fn: Component, opts?: MountOptions) => (() => void);
-export declare const renderToString: (fn: Component, opts?: RenderToStringOptions) => Promise<string>;
+/** Rerun `body` for every value of `stream`, replacing the previous run. */
+export declare const when: <A, E = never, R = never>(stream: Stream.Stream<A, E, R>, body: (value: A) => Generator<Yielded, View | undefined, View>) => Instruction<void, E>;
 //#endregion
 //#region src/unsafe.d.ts
 /**
@@ -98,4 +78,4 @@ export declare const renderToString: (fn: Component, opts?: RenderToStringOption
  */
 export declare const unsafe: (html: string) => UnsafeHtml;
 //#endregion
-export { type AtomEquality, type AtomHandle, type AtomOptions, type Component, type ContextProviderProps, type ErrorBoundaryProps, type ErrorFallback, type ErrorFallbackProps, type EventSourceFeed, type EventSourceOptions, type EventSourceStatus, Fragment, type IlhaContext, type MountOptions, type RenderToStringOptions, type Resource, type ResourceFetcher, type ResourceOptions, type UnsafeHtml, type View, type WatchCallback, type WatchContext, type WatchOnceCleanup, h, watch };
+export { type AtomEquality, type AtomHandle, type AtomLazyOptions, type AtomOptions, type Component, type ContextProviderProps, type ErrorBoundaryProps, type ErrorFallback, type ErrorFallbackProps, Fragment, type IlhaCode, type IlhaContext, type MountOptions, type RenderToStringOptions, type UnsafeHtml, type View, type WatchCallback, type WatchContext, type WatchOnceCleanup, h, mount, renderToString, watch };