effectweb 0.2.2 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 TeleVecha contributors
+Copyright (c) 2026 EffectWeb contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -4,6 +4,98 @@ Immutable Effect models and JSX compiled to direct DOM updates, without signals,
 
 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.
 
-See [setup and example](https://github.com/DerpyCrabs/EffectWeb#vite-setup) and the [authoring guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/authoring.md).
+See [setup and example](https://github.com/DerpyCrabs/EffectWeb#vite-setup).
 
-Early API; runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.
+Runtime and compiler versions advance together. Client-side only. Persistence and multi-tab coordination belong to the application.
+
+## Query identity and account ownership
+
+A query definition has its own identity. Within one cache, all request arguments form its key automatically:
+
+```ts
+const page = query({
+  name: 'message-page',
+  load: (args: { accountId: string; threadId: string; cursor?: string }) =>
+    api.messages(args.accountId, args.threadId, args.cursor),
+});
+```
+
+Request arguments use the same canonical encoding for cache lookup, prefetch, writes, invalidation, and `queryResource.select`. Object property order is ignored; array order matters. Strings, finite numbers, booleans, `null`, and explicit `undefined` are supported recursively in dense arrays and plain objects. Missing properties differ from properties containing `undefined`, and `0` differs from `-0`. Functions, symbols, bigint, nonfinite numbers, cycles, class instances, accessors, nonenumerable properties, sparse arrays, and arrays with extra properties throw `TypeError`. Repeated references to the same plain object are supported. Published argument objects are frozen and are not cloned.
+
+Pass every load-relevant value as an argument, including account, filters, pagination, locale, and permissions when they affect the result. Custom `key` projections are rejected. Provide service instances through the Effect environment instead of query arguments. Separate query definitions do not share entries even if their names and arguments match. `select(undefined)` disables selection; an explicit `undefined` inside an argument object remains part of its identity. A query without arguments uses `true` for selection and prefetch.
+
+Give authenticated data an account lifetime:
+
+```ts
+const account = modelOwner({ accountId }, { runtime });
+const cache = account.own(makeQueryCache(runtime));
+const messages = observeQuery(account, cache, page, (result) => {
+  // Publish the immutable result into application state.
+});
+messages.select({ accountId, threadId });
+
+// Sign out or switch account: dispose this lifetime, then create the next one.
+account.dispose();
+```
+
+Independent caches isolate account data even when services derive authentication from their environment. If an application deliberately reuses a cache across accounts, include account identity in every authenticated query key and call `cache.resetResources()` at the boundary before selecting the new account. Reset interrupts old resources and returns existing query observers to their initial state; select again to enter the new generation. Disposing only a query observer releases its subscription; it does not erase shared cached values. Own shared caches at the account or application scope, not in individual views.
+
+Use `cache.setQueryData(query, args, value)` to seed or replace a cached success, and `cache.updateQueryData(query, args, update)` to change an existing success. The updater receives readonly data; returning `undefined` skips the write. Both publish to current observers and supersede pending loads for those arguments. Use `setQueryData` to store a successful `undefined` value. Query definitions and cache registries are opaque; use the public cache and observation methods.
+
+## Write concurrency
+
+`modelOwner.run(slot, effect, policy)` and `defineTasks(owner, definitions)` support these policies:
+
+| Policy          | Behavior for an occupied slot                                           |
+| --------------- | ----------------------------------------------------------------------- |
+| `drop`          | Ignore the new request.                                                 |
+| `replace`       | Cancel active work and discard pending requests; start the new request. |
+| `parallel`      | Start the new request alongside active work.                            |
+| `queue`         | Append the request; run it after earlier work finishes.                 |
+| `latest-queued` | Keep active work; replace all pending requests with the newest request. |
+
+Every command requires an explicit `policy`. Create stable operation identities with `commandSlot('save')`; equal diagnostic names do not share a slot. Component `defineTasks(...).tasks(...)` and `taskComponent` support all except `parallel`, since their single result slot represents serial work. Command mapping and runtime service provisioning preserve the policy. Actions sharing a slot share concurrency and cancellation. A queued request waits for every active request in that slot if policies are mixed; keep a consistent policy per slot for predictable write behavior.
+
+Use `queue` when each accepted operation matters, such as appending messages. Use `latest-queued` when saving complete document snapshots and only the newest pending snapshot matters:
+
+```ts
+const writes = defineTasks(owner, {
+  save: { policy: 'latest-queued', run: (document: Snapshot<Document>) => storage.save(document) },
+});
+
+writes.save(owner.read().document);
+```
+
+Component tasks capture the model snapshot and input when `Run` is submitted, including requests that wait in a queue. Editing fields afterward does not replace that captured model. Controller tasks retain their supplied arguments; their factories execute when work starts. Pass `owner.read()` data as arguments to capture submission state, or read inside the Effect when execution-time state is intended. Effects and inputs are retained, not deep-cloned; keep supplied data immutable. Dropped and coalesced pending factories are never invoked.
+
+Queue progress continues after successes, typed failures, or defects. Component results remain `waiting` while more work is pending, publish each settlement, and retain the latest successful value if a later write fails. Action failures use the owner's error reporter. `cancel`, component reset or identity change, and disposal discard pending requests and interrupt active work; stale command completions cannot publish afterward. `awaitIdle` includes pending work. Cancellation cannot undo an external write that already completed. Transactions admit their whole command batch before starting Effects, so replacements and cancellation can remove superseded work without executing it.
+
+## Lazy views and portals
+
+`lazyView(() => fromPromise(() => import('./Reader').then((module) => module.Reader)))` loads a view when mounted. It accepts typed `pending` and `failure` views and a `runtime` when the loader requires services. Each unresolved placement owns its load; unmounting interrupts it. Successful definitions are cached for future mounts. Render a lazy view through `ViewBinding` with its current model and sender.
+
+`<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
+
+Mount a development panel before mounting the application so it sees initial evaluations:
+
+```ts
+import { mountBindingInspector } from 'effectweb/diagnostics';
+
+const removeInspector = mountBindingInspector(document.querySelector<HTMLElement>('#inspector')!);
+// Mount the application here. On teardown or HMR:
+// 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.
+
+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.
+
+## Immutable inputs and outputs
+
+Published `Snapshot<T>` values are recursively readonly, including nested arrays/tuples and async success data. View/slot composition, component inputs, owner patches, and task field updates accept readonly branches without casts. Query cache reads, subscriptions, and prefetch publish the same readonly data. Plain objects and arrays are frozen before publication in every build; snapshot protection cannot be disabled.
+
+Functions, Effects, DOM nodes, and explicitly marked service classes retain their own API. See the [authoring guide](https://github.com/DerpyCrabs/EffectWeb/blob/main/docs/authoring.md) for migration examples, `SnapshotOpaque`, state ownership, form composition, and reconciling async loads with live updates.

package/dist/AsyncContent.d.ts

@@ -13,8 +13,8 @@ export interface AsyncContentProps<A, E> {
 }
 type Props = AsyncContentProps<unknown, unknown>;
 /** Presentation only: resource owners choose identity, loading, caching and cancellation. */
-export declare const AsyncContent: {
-    <A, E>(props: AsyncContentProps<A, E>): JSX.Element;
+export declare const AsyncContent: JSX.ComponentType & {
+    <A, E>(this: never, props: AsyncContentProps<A, E>): JSX.Element;
     readonly build: View<Props, never>["build"];
 };
 export {};

package/dist/AsyncContent.js

@@ -1,9 +1,11 @@
 import * as _ew_dom from "./dom.js";
+import { commandSlot } from "./program.js";
 import { Cause, Effect, Option } from "effect";
 import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
 import { component } from "./component.js";
 import { view } from "./index.js";
 import { effectCommand } from "./program.js";
+const commandPending = commandSlot("pending");
 const implementation = component({
     init: (props) => ({
         props,
@@ -19,7 +21,7 @@ const implementation = component({
                     pending: false,
                     visible: false
                 },
-                cancel: ["pending"]
+                cancel: [commandPending]
             };
         if (model.pending && model.props.pendingDelay === props.pendingDelay)
             return { model: {
@@ -33,8 +35,9 @@ const implementation = component({
                 pending: true,
                 visible: delay === 0
             },
-            cancel: ["pending"],
-            commands: delay === 0 ? [] : [effectCommand("pending", () => Effect.sleep(delay), {
+            cancel: [commandPending],
+            commands: delay === 0 ? [] : [effectCommand(commandPending, () => Effect.sleep(delay), {
+                    policy: "replace",
                     onSuccess: () => ({ type: "ShowPending" }),
                     onFailure: () => ({ type: "ShowPending" })
                 })]
@@ -45,27 +48,36 @@ const implementation = component({
             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], () => ((_ew_capture_5) => _ew_capture_5.props)(_ew_scope_1.value));
-        const _ew_derived_6 = _ew_scope_1.derive(() => [_ew_derived_4()?.result], () => ((_ew_capture_7) => AsyncResult.value(_ew_capture_7.result))(_ew_derived_4()));
-        const _ew_derived_8 = _ew_scope_1.derive(() => [_ew_derived_4()?.result, _ew_derived_4()?.result?.waiting], () => ((_ew_capture_9) => AsyncResult.isFailure(_ew_capture_9.result) && !_ew_capture_9.result.waiting ? _ew_capture_9.result : undefined)(_ew_derived_4()));
-        _ew_dom.branch(_ew_scope_1, _ew_parent_2, _ew_before_3, () => Option.isSome(_ew_derived_6()), (_ew_scope_1, _ew_parent_10, _ew_before_11) => {
-            _ew_dom.text(_ew_scope_1, _ew_parent_10, _ew_before_11, () => [_ew_derived_4(), _ew_derived_6()?.value], () => _ew_derived_4().content(_ew_derived_6().value));
-            _ew_dom.branch(_ew_scope_1, _ew_parent_10, _ew_before_11, () => _ew_derived_4().result.waiting, (_ew_scope_1, _ew_parent_12, _ew_before_13) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_12, _ew_before_13, () => [_ew_derived_4()?.refreshing], () => _ew_derived_4().refreshing);
-            }, (_ew_scope_1, _ew_parent_12, _ew_before_13) => { });
-            _ew_dom.branch(_ew_scope_1, _ew_parent_10, _ew_before_11, () => _ew_derived_8() && _ew_derived_4().failure, (_ew_scope_1, _ew_parent_14, _ew_before_15) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_14, _ew_before_15, () => [_ew_derived_4(), _ew_derived_8()?.cause], () => _ew_derived_4().failure(_ew_derived_8().cause));
-            }, (_ew_scope_1, _ew_parent_14, _ew_before_15) => { });
-        }, (_ew_scope_1, _ew_parent_10, _ew_before_11) => {
-            _ew_dom.branch(_ew_scope_1, _ew_parent_10, _ew_before_11, () => _ew_derived_8() && _ew_derived_4().failure, (_ew_scope_1, _ew_parent_16, _ew_before_17) => {
-                _ew_dom.text(_ew_scope_1, _ew_parent_16, _ew_before_17, () => [_ew_derived_4(), _ew_derived_8()?.cause], () => _ew_derived_4().failure(_ew_derived_8().cause));
-            }, (_ew_scope_1, _ew_parent_16, _ew_before_17) => {
-                _ew_dom.branch(_ew_scope_1, _ew_parent_16, _ew_before_17, () => _ew_scope_1.value.pending, (_ew_scope_1, _ew_parent_18, _ew_before_19) => {
-                    _ew_dom.branch(_ew_scope_1, _ew_parent_18, _ew_before_19, () => _ew_scope_1.value.visible, (_ew_scope_1, _ew_parent_20, _ew_before_21) => {
-                        _ew_dom.text(_ew_scope_1, _ew_parent_20, _ew_before_21, () => [_ew_derived_4()?.pending], () => _ew_derived_4().pending);
-                    }, (_ew_scope_1, _ew_parent_20, _ew_before_21) => { });
-                }, (_ew_scope_1, _ew_parent_18, _ew_before_19) => {
-                    _ew_dom.text(_ew_scope_1, _ew_parent_18, _ew_before_19, () => [_ew_derived_4()?.empty], () => _ew_derived_4().empty);
+        const _ew_derived_4 = _ew_scope_1.derive(() => [_ew_scope_1.value?.props], () => {
+            const _ew_capture_6 = _ew_scope_1.value;
+            return _ew_capture_6.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);
                 });
             });
         });

package/dist/actions.d.ts

@@ -1,5 +1,6 @@
 import type { Send, Transition } from './program.js';
-type Handler<Model> = (model: Model, ...args: never[]) => Transition<Model, unknown>;
+import type { Snapshot } from './snapshot.js';
+type Handler<Model, R> = (model: Snapshot<Model>, ...args: never[]) => Transition<Model, unknown, R>;
 type Arguments<F> = F extends (model: never, ...args: infer Args) => unknown ? Args : never;
 type HandlerMessage<Handlers> = {
     [Name in keyof Handlers]: {
@@ -18,10 +19,9 @@ type Creators<Handlers> = {
 type Dispatch<Handlers> = {
     [Name in keyof Handlers]: (...args: Arguments<Handlers[Name]>) => void;
 };
-/** Declare action names and payloads once. Dispatch still crosses the ordinary program message queue. */
-export declare function defineActions<Model>(): <Handlers extends Record<string, Handler<Model>>>(handlers: Handlers) => {
+export declare function defineActions<Model, R = never>(): <Handlers extends Record<string, Handler<Model, R>>>(handlers: Handlers) => {
     message: Creators<Handlers>;
     bind(this: void, send: Send<HandlerMessage<Handlers>>): Dispatch<Handlers>;
-    update(this: void, model: Model, action: HandlerMessage<Handlers>): ReturnType<Handlers[keyof Handlers]>;
+    update(this: void, model: Snapshot<Model>, action: HandlerMessage<Handlers>): ReturnType<Handlers[keyof Handlers]>;
 };
 export {};

package/dist/actions.js

@@ -1,4 +1,3 @@
-/** Declare action names and payloads once. Dispatch still crosses the ordinary program message queue. */
 export function defineActions() {
     return (handlers) => {
         const message = Object.create(null);
@@ -24,6 +23,7 @@ export function defineActions() {
                 if (!Object.hasOwn(handlers, action.type))
                     throw new Error(`Unknown action: ${String(action.type)}`);
                 const handler = handlers[action.type];
+                // oxlint-disable-next-line typescript/no-unsafe-return -- The indexed handler and ReturnType refer to the same validated generic member.
                 return handler(model, ...action.args);
             },
         };

package/dist/cache-internals.d.ts

@@ -0,0 +1,14 @@
+import type * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
+import type * as Atom from 'effect/unstable/reactivity/Atom';
+import type * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
+import type { QueryCache } from './cache.js';
+import type { Query } from './query.js';
+import type { Snapshot } from './snapshot.js';
+export interface CacheInternals<R> {
+    readonly registry: AtomRegistry.AtomRegistry;
+    readonly generation: Atom.Writable<number>;
+    query<Args, A, E>(definition: Query<Args, A, E, R>, args: Args | Snapshot<Args>): Atom.Atom<AsyncResult.AsyncResult<Snapshot<A>, E>>;
+}
+export declare function registerCache<R>(cache: QueryCache<R>, internals: CacheInternals<R>): void;
+/** Private implementation access; deliberately absent from package exports. */
+export declare function cacheInternals<R>(cache: QueryCache<R>): CacheInternals<R>;

package/dist/cache-internals.js

@@ -0,0 +1,11 @@
+const caches = new WeakMap();
+export function registerCache(cache, internals) {
+    caches.set(cache, internals);
+}
+/** Private implementation access; deliberately absent from package exports. */
+export function cacheInternals(cache) {
+    const internals = caches.get(cache);
+    if (!internals)
+        throw new TypeError('Use makeQueryCache() to create a cache.');
+    return internals;
+}

package/dist/cache.d.ts

@@ -1,23 +1,25 @@
+import { type Snapshot } from './snapshot.js';
 import { Effect } from 'effect';
-import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
-import * as Atom from 'effect/unstable/reactivity/Atom';
-import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
-import type { Query } from './query.js';
+import { type Query } from './query.js';
 import type { UiRuntime } from './runtime.js';
 export { loadEffect, type UiLoad } from './load.js';
 export { shareValue } from './share.js';
 export declare function makeQueryCache(): QueryCache<never>;
 export declare function makeQueryCache<R>(runtime: UiRuntime<R>): QueryCache<R>;
-declare function createQueryCache<R>(runtime?: UiRuntime<R>): {
-    registry: AtomRegistry.AtomRegistry;
-    generation: Atom.Writable<number, number>;
-    resource<A, E = unknown>(key: string, load: () => Effect.Effect<A, E>): Atom.Atom<AsyncResult.AsyncResult<A, E>>;
-    query: <Args, A, E>(definition: Query<Args, A, E, R>, args: Args) => Atom.Atom<AsyncResult.AsyncResult<A, E>>;
-    /** Prefetch and views observe the same atom; failure types and shared cancellation remain intact. */
-    prefetch<Args, A, E>(definition: Query<Args, A, E, R>, args: Args): Effect.Effect<A, E>;
-    invalidateQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [Args]): void;
-    invalidate(prefix: string): void;
+/** A cache owns one registry and the query resources published through it. */
+export interface QueryCache<R = never> {
+    prefetch<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>): Effect.Effect<Snapshot<A>, E>;
+    /** Publish a protected success, including undefined, and supersede any pending load for this key. */
+    setQueryData<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>, value: NoInfer<A> | Snapshot<NoInfer<A>>): Snapshot<A>;
+    /**
+     * Update an existing success, including one retained during refresh or failure, and supersede its load.
+     * No success or an undefined updater return skips the write. Use setQueryData to seed or store undefined.
+     * Updaters run synchronously on readonly data; a throw leaves the cached value unchanged.
+     */
+    updateQueryData<Args, A, E>(definition: Query<Args, A, E, R>, args: NoInfer<Args> | Snapshot<NoInfer<Args>>, update: (previous: Snapshot<A>) => NoInfer<A> | Snapshot<NoInfer<A>> | undefined): Snapshot<A> | undefined;
+    invalidateQuery<Args, A, E>(definition: Query<Args, A, E, R>, ...selected: [] | [NoInfer<Args> | Snapshot<NoInfer<Args>>]): void;
+    /** Observe account resets without exposing registry mutation. */
+    onReset(listener: () => void): () => void;
     resetResources(): void;
     dispose(): void;
-};
-export type QueryCache<R = never> = ReturnType<typeof createQueryCache<R>>;
+}

package/dist/cache.js

@@ -1,9 +1,13 @@
+import { protectSnapshot } from './snapshot.js';
 import { Effect, Option } from 'effect';
 import * as AsyncResult from 'effect/unstable/reactivity/AsyncResult';
 import * as Atom from 'effect/unstable/reactivity/Atom';
 import * as AtomRegistry from 'effect/unstable/reactivity/AtomRegistry';
 import { loadEffect } from './load.js';
-import { shareValue } from './share.js';
+import { shareData } from './sharing.js';
+import { encodeQueryKey } from './query.js';
+import { registerCache } from './cache-internals.js';
+import { queryDefinition } from './query-internals.js';
 export { loadEffect } from './load.js';
 export { shareValue } from './share.js';
 export function makeQueryCache(runtime) {
@@ -13,19 +17,44 @@ function createQueryCache(runtime) {
     const registry = AtomRegistry.make({ defaultIdleTTL: 30_000 });
     const generation = Atom.keepAlive(Atom.make(0));
     const resources = new Map();
-    const acquire = (key, load, share = shareValue) => {
+    // Follow registry-node lifetime; retaining definitions must not retain evicted data.
+    const values = new WeakMap();
+    const identities = new WeakMap();
+    let disposed = false;
+    let nextId = 0;
+    const identity = (definition) => {
+        let id = identities.get(definition);
+        if (id === undefined) {
+            id = ++nextId;
+            identities.set(definition, id);
+        }
+        return id;
+    };
+    const acquire = (key, load, share = (previous, next) => shareData(previous, next)) => {
         let entry = resources.get(key);
         if (entry)
             entry.load = load;
         else {
+            const loaded = Atom.make((get) => {
+                const previous = Option.flatMap(get.self(), AsyncResult.value);
+                return loadEffect(() => next.load()).pipe(Effect.map((value) => {
+                    const shared = Option.isSome(previous)
+                        ? share(previous.value, value)
+                        : value;
+                    const snapshot = protectSnapshot(shared);
+                    remember(next, snapshot);
+                    return snapshot;
+                }));
+            });
             const next = {
                 load,
-                atom: Atom.make((get) => {
-                    const previous = Option.flatMap(get.self(), AsyncResult.value);
-                    return loadEffect(() => next.load()).pipe(Effect.map((value) => {
-                        next.loadedAt = Date.now();
-                        return Option.isSome(previous) ? share(previous.value, value) : value;
-                    }));
+                atom: Atom.writable(loaded.read, (context, value) => {
+                    Atom.batch(() => {
+                        // Refresh disposes the load lifetime; setSelf publishes without starting another load.
+                        context.refreshSelf();
+                        remember(next, value);
+                        context.setSelf(AsyncResult.success(value));
+                    });
                 }),
             };
             entry = next;
@@ -42,33 +71,71 @@ function createQueryCache(runtime) {
         }
         return { entry, atom: entry.atom };
     };
-    const queryKey = (definition, args) => `query:${definition.id}:${definition.key(args)}`;
-    const selectQuery = (definition, args) => {
+    const remember = (entry, value) => {
+        entry.loadedAt = Date.now();
+        const node = registry.getNodes().get(entry.atom);
+        if (node)
+            values.set(node, { value });
+    };
+    const previousValue = (entry) => {
+        const node = entry && registry.getNodes().get(entry.atom);
+        return node ? values.get(node) : undefined;
+    };
+    const checkWritable = () => {
+        if (disposed)
+            throw new Error('Cannot write to a disposed query cache.');
+    };
+    const queryKey = (definition, args) => `query:${identity(definition)}:${encodeQueryKey(args)}`;
+    const acquireQuery = (definition, args) => {
+        const config = queryDefinition(definition);
+        protectSnapshot(args);
         const { entry, atom } = acquire(queryKey(definition, args), () => {
-            const effect = Effect.suspend(() => definition.load(args));
+            const effect = Effect.suspend(() => config.load(args));
             return runtime ? runtime.provide(effect) : effect;
-        }, definition.share);
-        entry.queryId = definition.id;
+        }, config.share);
+        entry.query = definition;
+        return { entry, atom, config };
+    };
+    const selectQuery = (definition, args) => {
+        const { entry, atom, config } = acquireQuery(definition, args);
         if (registry.getNodes().has(atom) &&
             entry.loadedAt !== undefined &&
-            Date.now() - entry.loadedAt >= definition.staleTime) {
+            Date.now() - entry.loadedAt >= config.staleTime) {
             const current = registry.get(atom);
             if (!current.waiting)
                 registry.refresh(atom);
         }
         return atom;
     };
-    return {
-        registry,
-        generation,
-        resource(key, load) {
-            return acquire(key, load).atom;
-        },
-        query: selectQuery,
-        /** Prefetch and views observe the same atom; failure types and shared cancellation remain intact. */
+    const cache = {
         prefetch(definition, args) {
             return Effect.suspend(() => AtomRegistry.getResult(registry, selectQuery(definition, args), { suspendOnWaiting: true }));
         },
+        setQueryData(definition, args, value) {
+            checkWritable();
+            const { entry, config } = acquireQuery(definition, args);
+            const previous = previousValue(entry);
+            const next = protectSnapshot(value);
+            const shared = previous
+                ? config.share
+                    ? config.share(previous.value, next)
+                    : shareData(previous.value, next)
+                : next;
+            const snapshot = protectSnapshot(shared);
+            checkWritable();
+            registry.set(entry.atom, snapshot);
+            return snapshot;
+        },
+        updateQueryData(definition, args, update) {
+            checkWritable();
+            queryDefinition(definition);
+            protectSnapshot(args);
+            const previous = previousValue(resources.get(queryKey(definition, args)));
+            if (!previous)
+                return undefined;
+            const next = update(previous.value);
+            return next === undefined ? undefined : cache.setQueryData(definition, args, next);
+        },
         invalidateQuery(definition, ...selected) {
             if (selected.length) {
                 const entry = resources.get(queryKey(definition, selected[0]));
@@ -77,14 +144,13 @@ function createQueryCache(runtime) {
             }
             else {
                 for (const entry of resources.values())
-                    if (entry.queryId === definition.id)
+                    if (entry.query === definition)
                         registry.refresh(entry.atom);
             }
         },
-        invalidate(prefix) {
-            for (const [key, entry] of resources)
-                if (key.startsWith(prefix))
-                    registry.refresh(entry.atom);
+        onReset(listener) {
+            registry.get(generation);
+            return registry.subscribe(generation, listener);
         },
         resetResources() {
             Atom.batch(() => {
@@ -97,8 +163,13 @@ function createQueryCache(runtime) {
             });
         },
         dispose() {
+            if (disposed)
+                return;
+            disposed = true;
             registry.dispose();
             resources.clear();
         },
     };
+    registerCache(cache, { registry, generation, query: selectQuery });
+    return Object.freeze(cache);
 }

package/dist/collection.d.ts

@@ -1,5 +1,5 @@
+import type { Snapshot } from './snapshot.js';
 export type Identity = string | number;
-/** Identity belongs to the domain collection, not to each place that renders it. */
 export interface Rows<A> {
     readonly items: readonly A[];
     readonly identity: (item: A, index: number) => Identity;
@@ -8,16 +8,16 @@ export interface Rows<A> {
     filter(predicate: (item: A, index: number) => boolean): Rows<A>;
     slice(start?: number, end?: number): Rows<A>;
 }
-export declare function collection<A>(identity: (item: A, index: number) => Identity): {
-    from: (items: readonly A[]) => Rows<A>;
-    share: {
-        <B extends A>(previous: readonly B[], next: B[]): B[];
-        <B extends A>(previous: readonly B[], next: readonly B[]): readonly B[];
-    };
-};
+/** 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 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>[];
+}
+export declare function collection<A>(identity: (item: Snapshot<A>, index: number) => Identity): Collection<A>;
 /** Use positional identity for ordered values without stable entity IDs. */
-export declare function sequence<A>(items: readonly A[]): Rows<A>;
+export declare function sequence<A>(items: readonly A[]): Rows<Snapshot<A>>;
 /** Rows keyed by their domain IDs. Reuses the wrapper for the same immutable array. */
 export declare function entities<A extends {
     readonly id: Identity;
-}>(items: readonly A[] | undefined): Rows<A>;
+}>(items: readonly A[] | undefined): Rows<Snapshot<A>>;

package/dist/collection.js

@@ -1,8 +1,30 @@
-import { shareValue } from './share.js';
-export function collection(identity) {
+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) => {
+        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.`);
+        seen.set(key, index);
+        return key;
+    });
+}
+function makeCollection(identity) {
     const cache = new WeakMap();
+    const validated = new WeakSet();
+    const validate = (items) => {
+        if (validated.has(items))
+            return;
+        validateIdentities(items, identity);
+        validated.add(items);
+    };
     const comparisons = new WeakMap();
     const from = (items) => {
+        validate(items);
         const cached = cache.get(items);
         if (cached)
             return cached;
@@ -18,6 +40,8 @@ export function collection(identity) {
         return rows;
     };
     function share(previous, next) {
+        validate(previous);
+        validate(next);
         if (previous === next)
             return previous;
         let pairs = comparisons.get(previous);
@@ -36,13 +60,10 @@ export function collection(identity) {
             if (index >= previous.length || !Object.is(identity(old, index), key)) {
                 if (!byIdentity) {
                     byIdentity = new Map(previous.map((value, i) => [identity(value, i), value]));
-                    const keys = next.map(identity);
-                    if (byIdentity.size !== previous.length || new Set(keys).size !== keys.length)
-                        throw new Error('Duplicate collection identity. Identity must be unique within the collection.');
                 }
                 old = byIdentity.get(key);
             }
-            const value = old === undefined ? item : shareValue(old, item);
+            const value = old === undefined ? item : shareData(old, item);
             if (!Object.is(value, previous[index]))
                 equal = false;
             if (!Object.is(value, item) && !result)
@@ -60,6 +81,11 @@ export function collection(identity) {
     }
     return { from, share };
 }
+export function collection(identity) {
+    // Snapshot changes access permissions, not runtime representation. The implementation
+    // only borrows supplied items, and never inserts values of a wider type.
+    return makeCollection(identity);
+}
 const positions = collection((_item, index) => index);
 /** Use positional identity for ordered values without stable entity IDs. */
 export function sequence(items) {