effectweb 0.3.1 → 0.4.0

package/README.md

@@ -1,6 +1,6 @@
 # effectweb
 
-Immutable Effect models and JSX compiled to direct DOM updates, without signals, proxies, or virtual DOM.
+Immutable Effect models and JSX with direct DOM rendering.
 
 Use with `@effectweb/compiler/vite` and Effect `4.0.0-rc.112`. The package includes programs, named tasks, async presentation, query caching, DOM lifetimes, and `effectweb/testing` helpers.
 
@@ -8,6 +8,37 @@ See [setup and example](https://github.com/DerpyCrabs/EffectWeb#vite-setup).
 
 Runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.
 
+## Views and list identity
+
+`view(render)` evaluates `render(model, send)` as ordinary JavaScript on each immutable model publication. Calls, local variables, destructuring, loops, conditionals, and JSX helpers retain their JavaScript behavior. The renderer reconciles the returned content; the compiler does not infer dependencies or cache helper results.
+
+Use `list(rows, render)` to preserve domain identity:
+
+```tsx
+import { entities, list, view } from 'effectweb';
+
+type Todo = { id: string; title: string };
+const Todos = view<{ todos: Todo[] }>((model) => (
+  <ul>
+    {list(entities(model.todos), (todo) => (
+      <li>{todo.title}</li>
+    ))}
+  </ul>
+));
+```
+
+`collection(identity).from(items)` supplies a custom domain identity; `sequence(items)` supplies positional identity. `list(rawArray, render)` uses each item itself as its identity, so repeated values or references require an explicit collection identity. Duplicate identities throw with both positions. The callback receives the exact current item, including a replacement object with the same ID. `Rows.map` and ordinary array `.map` remain normal JavaScript mapping operations; their rendered arrays use positional identity.
+
+`slot(render)` is a typed render callback. Call it explicitly, including `footer()` for a `Slot<void>`; a function is not implicit JSX content. See the [0.4.0 migration guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/migration-0.4.0.md).
+
+## DOM and Effect lifetimes
+
+`domMount(acquire)` uses the acquisition function as its identity. Declare it outside the view body when its lifetime should survive model updates. `domBinding(data, acquire)` keeps a stable acquisition while supplying fresh data through `input()`. Return `{ update, dispose }` when the integration must apply changed data, or a scoped Effect that remains active for the lifetime. A new acquisition function replaces the old lifetime.
+
+Fresh event callbacks see current model data without canceling already running listener work. An Effect event's `replace` policy cancels the previous request when a new event submits work; removing the handler or unmounting disposes its owned work.
+
+`dispose()` interrupts owned work synchronously. `close()`, `awaitIdle()`, and `awaitStopped()` return Effects; merely creating or JavaScript-awaiting one does not execute it. Use `yield* owner.close()` inside an Effect or `await Effect.runPromise(owner.close())` at a Promise integration boundary. `close()` waits for finalizers; `awaitIdle()` waits without closing the owner. A mount returned by `mountView` also has `close()` for its DOM-owned work. The supplied program keeps its separate ownership.
+
 ## Query identity and account ownership
 
 A query definition has its own identity. Within one cache, all request arguments form its key automatically:
@@ -76,7 +107,7 @@ Queue progress continues after successes, typed failures, or defects. Component
 
 `<Portal mount={model.dialogHost}>...</Portal>` renders into a supplied HTML or SVG element. Omitting `mount` uses the document body. Portal content retains its owner, events, and cleanup; changing between HTML and SVG targets rebuilds content in the correct namespace.
 
-## Inspect source dependencies
+## Inspect source bindings
 
 Mount a development panel before mounting the application so it sees initial evaluations:
 
@@ -88,11 +119,11 @@ const removeInspector = mountBindingInspector(document.querySelector<HTMLElement
 // removeInspector();
 ```
 
-The live, filterable table shows original file/line/column, source expressions, inferred snapshot dependencies, the latest changed dependency names, and derive/binding evaluation counts. It uses development compiler metadata; production builds emit none. Counts include initial evaluations, aggregate instances of the same source expression, and measure evaluations rather than actual DOM writes. Change reasons use reference/value equality, without retaining previous or next values.
+The live, filterable table shows original file/line/column, source expressions, and binding evaluation counts. Development metadata records the expressions actually evaluated for text and attributes; it does not infer which model fields a helper reads. Production builds emit none. Counts include initial evaluations, aggregate instances of the same source expression, and measure binding evaluations rather than DOM writes. Change reasons compare evaluated values without retaining previous or next values.
 
 For custom tooling, `inspectBindings({ limit: 200 })` returns `entries()`, `subscribe(listener)`, `clear()`, and `dispose()`. Entries are immutable metadata, newest first, with at most 1000 source records. Least recently updated sources are evicted and start fresh if seen again. `dispose()` unsubscribes and clears retained metadata. `mountBindingInspector(element, inspector)` can share an inspector; removing that panel leaves the supplied inspector running. Low-level `observeBindings` remains available.
 
-The inspector covers instrumented derivations and text/attribute bindings; it is not a snapshot recorder, time-travel debugger, or complete profile of branch/list reconciliation. Source labels describe the compiler's inferred dependencies, not a proof that an opaque helper has no hidden state.
+The inspector covers instrumented text/attribute bindings; it is not a snapshot recorder, time-travel debugger, or complete profile of view evaluation and list reconciliation. Use application profiling for expensive render helpers.
 
 ## Immutable inputs and outputs
 

package/dist/AsyncContent.d.ts

@@ -1,4 +1,4 @@
-import { Cause } from 'effect';
+import * as Cause from 'effect/Cause';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import { type Slot, type View } from './index.js';
 import type { JSX } from './jsx.js';

package/dist/AsyncContent.js

@@ -1,6 +1,8 @@
 import * as _ew_dom from "./dom.js";
 import { commandSlot } from "./program.js";
-import { Cause, Effect, Option } from "effect";
+import * as Cause from "effect/Cause";
+import * as Effect from "effect/Effect";
+import * as Option from "effect/Option";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import { component } from "./component.js";
 import { view } from "./index.js";
@@ -47,40 +49,21 @@ const implementation = component({
             ...model,
             visible: true
         } }),
-    view: /* @__PURE__ */ _ew_dom.compiled((_ew_scope_1, _ew_parent_2, _ew_before_3) => {
-        const _ew_derived_4 = _ew_scope_1.derive(() => [_ew_scope_1.value?.props], () => {
-            const _ew_capture_6 = _ew_scope_1.value;
-            return _ew_dom.intrinsic(_ew_dom.intrinsic(_ew_capture_6, ["props", "content"], "@slot"), ["props", "failure"], "@slot").props;
-        });
-        const _ew_derived_7 = _ew_scope_1.derive(() => [_ew_derived_4()?.result], () => {
-            const _ew_capture_9 = _ew_derived_4();
-            return AsyncResult.value(_ew_capture_9.result);
-        });
-        const _ew_derived_10 = _ew_scope_1.derive(() => [_ew_derived_4()?.result, _ew_derived_4()?.result?.waiting], () => {
-            const _ew_capture_12 = _ew_derived_4();
-            return AsyncResult.isFailure(_ew_capture_12.result) && !_ew_capture_12.result.waiting ? _ew_capture_12.result : undefined;
-        });
-        _ew_dom.branch(_ew_scope_1, _ew_parent_2, _ew_before_3, () => Option.isSome(_ew_derived_7()), (_ew_scope_1, _ew_parent_13, _ew_before_14) => {
-            _ew_dom.text(_ew_scope_1, _ew_parent_13, _ew_before_14, () => [_ew_derived_4(), _ew_derived_7()?.value], () => _ew_derived_4().content(_ew_derived_7().value));
-            _ew_dom.branch(_ew_scope_1, _ew_parent_13, _ew_before_14, () => _ew_derived_4().result.waiting, (_ew_scope_1, _ew_parent_15, _ew_before_16) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_15, _ew_before_16, () => [_ew_derived_4()?.refreshing], () => _ew_derived_4().refreshing);
-            }, (_ew_scope_1, _ew_parent_15, _ew_before_16) => { });
-            _ew_dom.branch(_ew_scope_1, _ew_parent_13, _ew_before_14, () => _ew_derived_10() && _ew_derived_4().failure, (_ew_scope_1, _ew_parent_17, _ew_before_18) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_17, _ew_before_18, () => [_ew_derived_4(), _ew_derived_10()?.cause], () => _ew_derived_4().failure(_ew_derived_10().cause));
-            }, (_ew_scope_1, _ew_parent_17, _ew_before_18) => { });
-        }, (_ew_scope_1, _ew_parent_13, _ew_before_14) => {
-            _ew_dom.branch(_ew_scope_1, _ew_parent_13, _ew_before_14, () => _ew_derived_10() && _ew_derived_4().failure, (_ew_scope_1, _ew_parent_19, _ew_before_20) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_19, _ew_before_20, () => [_ew_derived_4(), _ew_derived_10()?.cause], () => _ew_derived_4().failure(_ew_derived_10().cause));
-            }, (_ew_scope_1, _ew_parent_19, _ew_before_20) => {
-                _ew_dom.branch(_ew_scope_1, _ew_parent_19, _ew_before_20, () => _ew_scope_1.value.pending, (_ew_scope_1, _ew_parent_21, _ew_before_22) => {
-                    _ew_dom.branch(_ew_scope_1, _ew_parent_21, _ew_before_22, () => _ew_scope_1.value.visible, (_ew_scope_1, _ew_parent_23, _ew_before_24) => {
-                        _ew_dom.text(_ew_scope_1, _ew_parent_23, _ew_before_24, () => [_ew_derived_4()?.pending], () => _ew_derived_4().pending);
-                    }, (_ew_scope_1, _ew_parent_23, _ew_before_24) => { });
-                }, (_ew_scope_1, _ew_parent_21, _ew_before_22) => {
-                    _ew_dom.text(_ew_scope_1, _ew_parent_21, _ew_before_22, () => [_ew_derived_4()?.empty], () => _ew_derived_4().empty);
-                });
-            });
-        });
+    view: view((model, _send) => {
+        const props = model.props;
+        const data = AsyncResult.value(props.result);
+        const failure = AsyncResult.isFailure(props.result) && !props.result.waiting ? props.result : undefined;
+        if (Option.isSome(data))
+            return [
+                props.content(data.value),
+                props.result.waiting ? props.refreshing : null,
+                failure && props.failure ? props.failure(failure.cause) : null
+            ];
+        if (failure && props.failure)
+            return props.failure(failure.cause);
+        if (model.pending)
+            return model.visible ? props.pending : null;
+        return props.empty;
     })
 });
 /** Presentation only: resource owners choose identity, loading, caching and cancellation. */

package/dist/cache.d.ts

@@ -1,5 +1,5 @@
 import { type Snapshot } from './snapshot.js';
-import { Effect } from 'effect';
+import * as Effect from 'effect/Effect';
 import { type Query, type QueryGroup } from './query.js';
 import type { UiRuntime } from './runtime.js';
 export { loadEffect, type UiLoad } from './load.js';
@@ -36,6 +36,6 @@ export interface QueryCache<R = never> {
     onReset(listener: () => void): () => void;
     resetResources(): void;
     /** Interrupt every request and wait for its finalizers, including previously canceled requests. */
-    close(): Promise<void>;
+    close(): Effect.Effect<void>;
     dispose(): void;
 }

package/dist/cache.js

@@ -1,6 +1,8 @@
 import { Settlement } from './settlement.js';
 import { protectSnapshot } from './snapshot.js';
-import { Deferred, Effect, Option } from 'effect';
+import * as Deferred from 'effect/Deferred';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import * as Atom from 'effect/unstable/reactivity/Atom';
 import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
@@ -292,8 +294,10 @@ function createQueryCache(runtime, options = {}) {
         },
         close() {
             if (!closing) {
-                cache.dispose();
-                closing = settlement.wait();
+                closing = Effect.suspend(() => {
+                    cache.dispose();
+                    return settlement.wait();
+                });
             }
             return closing;
         },

package/dist/collection.d.ts

@@ -9,7 +9,7 @@ export interface Rows<A> {
     slice(start?: number, end?: number): Rows<A>;
 }
 /** Validate without retaining values. Positions are zero-based array indices. */
-export declare function validateIdentities<A>(items: readonly A[], identity: (item: A, index: number) => Identity): Identity[];
+export declare function validateIdentities<A, K>(items: readonly A[], identity: (item: A, index: number) => K): K[];
 export interface Collection<A> {
     from(this: void, items: readonly (A | Snapshot<A>)[]): Rows<Snapshot<A>>;
     share<B extends A | Snapshot<A>>(this: void, previous: readonly B[], next: readonly B[]): readonly Snapshot<B>[];

package/dist/collection.js

@@ -2,10 +2,8 @@ import { shareData } from './sharing.js';
 /** Validate without retaining values. Positions are zero-based array indices. */
 export function validateIdentities(items, identity) {
     const seen = new Map();
-    return items.map((item, index) => {
+    return Array.from(items, (item, index) => {
         const key = identity(item, index);
-        if (typeof key !== 'string' && typeof key !== 'number')
-            throw new Error(`Invalid collection identity at index ${index}. Use a string or number domain identity, or sequence(items) for positional identity.`);
         const previous = seen.get(key);
         if (previous !== undefined)
             throw new Error(`Duplicate collection identity at indices ${previous} and ${index}. Identity must be unique within the collection; use a composite domain identity when IDs are only locally unique.`);

package/dist/component.js

@@ -1,3 +1,5 @@
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
 import { compiled, Scope, viewRegion } from './dom.js';
 import { mapCommand, program } from './program.js';
 import { patchModel } from './state.js';
@@ -82,9 +84,10 @@ function closeProgram(scope, source) {
     const finish = scope.settlement.begin();
     try {
         if (source.close) {
-            source.close().then(finish, (error) => {
+            Effect.runFork(source.close()).addObserver((exit) => {
                 finish();
-                reportSafely(scope.report, error);
+                if (exit._tag === 'Failure')
+                    reportSafely(scope.report, Cause.squash(exit.cause));
             });
         }
         else {

package/dist/dom.d.ts

@@ -1,3 +1,4 @@
+import * as Effect from 'effect/Effect';
 import type { Snapshot } from './snapshot.js';
 import { type ReportError } from './errors.js';
 import { type BindingSource } from './diagnostics.js';
@@ -7,6 +8,7 @@ import type { DomMount } from './mount.js';
 import { Settlement } from './settlement.js';
 import type { Program, Send } from './program.js';
 type Dependencies = () => readonly unknown[];
+type BindingLocation = BindingSource | (() => BindingSource | undefined);
 type Cleanup = () => void;
 type Build<M, E> = (scope: Scope<M, E>, parent: Node, before: Node | null) => void;
 /** Compiler implementation. No implicit tracking, proxies, or per-binding subscriptions. */
@@ -18,10 +20,8 @@ export declare class Scope<M, E> {
     readonly jobs: Cleanup[];
     readonly cleanups: Cleanup[];
     disposed: boolean;
-    private revision;
     constructor(value: M, send: Send<E>, report?: ReportError, settlement?: Settlement);
-    derive<A>(dependencies: Dependencies, compute: () => A, source?: BindingSource): () => A;
-    watch(dependencies: Dependencies, apply: () => void, source?: BindingSource): void;
+    watch(dependencies: Dependencies, apply: () => void, source?: BindingLocation): void;
     set(value: M): void;
     dispose(): void;
 }
@@ -29,8 +29,8 @@ export interface View<M, E> extends JSX.ComponentType {
     (this: never, props: [E] extends [never] ? M | Snapshot<M> : never): JSX.Element;
     readonly build: Build<M, E>;
 }
-/** Compiler marker for mounting a view with an explicit model and message dispatcher. */
-export declare const ViewBinding: (<M, E>(this: never, _props: {
+/** Mount a view with an explicit model and message dispatcher. */
+export declare const ViewBinding: (<M, E>(this: never, props: {
     view: View<M, E>;
     model: NoInfer<M> | Snapshot<NoInfer<M>>;
     send: Send<NoInfer<E>>;
@@ -44,18 +44,22 @@ declare const contentBrand: unique symbol;
 export interface CompiledContent {
     readonly [contentBrand]: true;
 }
-/** A compiled template with a typed placement value, captured in its declaring view. */
+/** An ordinary render callback with a typed input. Invoke it to produce content. */
 export interface Slot<A = void> {
     (value: A | Snapshot<A>): JSX.Element;
-    readonly [contentBrand]: [A] extends [void] ? true : false;
 }
-/** Compiler marker: declare inside view(), or directly in a compiled component prop. */
-export declare function slot<A = void>(_render: (value: Snapshot<A>) => JSX.Element): Slot<A>;
-/** Compiler output. Captures follow their declaring scope; placements own independent scopes. */
-export declare function compiledSlot<M, E, A>(owner: Scope<M, E>, build: Build<A, E>): Slot<A>;
-/** This declaration is a compiler marker, never a component setup callback. */
-export declare function view<M, E = never>(_render: (model: Snapshot<M>, send: Send<E>) => JSX.Element): View<M, E>;
+export declare function slot<A = void>(render: (value: Snapshot<A>) => JSX.Element): Slot<A>;
+/** Evaluate ordinary synchronous JavaScript for each immutable model publication. */
+export declare function view<M, E = never>(render: (model: Snapshot<M>, send: Send<E>) => JSX.Element): View<M, E>;
 export declare function compiled<M, E>(build: Build<M, E>): View<M, E>;
+type MarkupProps = Readonly<Record<string, unknown>> & {
+    readonly children?: JSX.Element;
+};
+/** JSX factories preserve host identity by element type; source locations are metadata only. */
+export declare function markup(tag: string, sources?: Readonly<Record<string, BindingSource>>): (props: MarkupProps) => JSX.Element;
+export declare function renderComponent(component: (props: never) => JSX.Element, props: Readonly<Record<string, unknown>>): JSX.Element;
+/** Preserve collection identity (or array reference identity) while rendering rows. */
+export declare function list<A>(rows: Rows<A> | readonly A[], render: (item: A, index: number) => JSX.Element): JSX.Element;
 export interface PortalProps {
     readonly children?: JSX.Element;
     readonly mount?: Element | undefined;
@@ -66,23 +70,22 @@ export declare function mountView<M, E>(parent: Node, definition: View<M, E>, so
     onError?: ReportError;
 }): (() => void) & {
     dispose: () => void;
-    close: () => Promise<void>;
+    close: () => Effect.Effect<void, never, never>;
 };
 export declare function element(parent: Node, before: Node | null, tag: string): Element;
 export declare function attribute(element: Element, name: string, value: unknown): void;
 /** Compiler output for attributes whose unchanged value needs no DOM refresh. */
-export declare function bindAttribute<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown, source?: BindingSource): void;
+export declare function bindAttribute<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown, source?: BindingLocation): void;
 /** Handled edits can change a control even when dispatch publishes no new model. */
-export declare function bindControl<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown, source?: BindingSource): void;
-export declare function text<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, dependencies: Dependencies, read: () => unknown, source?: BindingSource): void;
-export declare function event<M, E>(scope: Scope<M, E>, element: Element, name: string, handler: (event: Event) => unknown): void;
-/** One handler identity owns its requests, regardless of the JSX attribute spelling. */
-export declare function bindEvent<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown): void;
+export declare function bindControl<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => unknown, source?: BindingLocation): void;
+export declare function text<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, dependencies: Dependencies, read: () => JSX.Element, source?: BindingLocation): void;
+export declare function event<M, E>(scope: Scope<M, E>, element: Element, name: string, handler: (event: Event) => JSX.EventResult): void;
+/** The event binding owns its requests; snapshot renders may replace its callback. */
+export declare function bindEvent<M, E>(scope: Scope<M, E>, element: Element, name: string, dependencies: Dependencies, read: () => ((event: Event) => JSX.EventResult) | undefined): void;
 /** Reconcile merged JSX attributes. Each host, event and control owns its cleanup. */
-export declare function bindAttributes<M, E>(scope: Scope<M, E>, element: Element, dependencies: Dependencies, read: () => Readonly<Record<string, unknown>>): void;
+export declare function bindAttributes<M, E>(scope: Scope<M, E>, element: Element, dependencies: Dependencies, read: () => Readonly<Record<string, unknown>>, sources?: () => Readonly<Record<string, BindingSource>> | undefined): void;
 export declare function branch<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, choose: () => boolean, yes: Build<M, E>, no: Build<M, E>): void;
 export declare function each<M, E, A>(scope: Scope<M, E>, parent: Node, before: Node | null, read: () => Rows<A> | readonly A[], outer: Dependencies, indexUsed: boolean, build: Build<readonly [A, number], E>): void;
-export declare function invoke<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, dependencies: Dependencies, read: () => readonly unknown[], build: Build<readonly unknown[], E>): void;
 export declare function child<M, E, C, F>(scope: Scope<M, E>, parent: Node, before: Node | null, definition: View<C, F>, dependencies: Dependencies, model: () => C, send: Send<F>): void;
 /** A late-bound compiled definition owns one replaceable DOM region. */
 export declare function viewRegion<M, E>(scope: Scope<M, E>, parent: Node, before: Node | null, options?: {
@@ -94,4 +97,4 @@ export declare function portal<M, E>(scope: Scope<M, E>, build: Build<M, E>, mou
 /** Build static markup once per document/namespace, then clone native nodes at each use. */
 export declare function template(build: string | ((parent: Node, before: Node | null) => void), depth?: number): (parent: Node, before: Node | null) => Node;
 export declare function literal(parent: Node, before: Node | null, value: string): void;
-export { intrinsic } from './intrinsic.js';
+export {};