solid22 0.0.1

package/README.md

@@ -0,0 +1,1299 @@
+# solid2
+
+Experimental Solid 2 primitives and helpers, organized as focused subpath modules.
+
+The first module is `solid2/effects`, which provides an explicit-dependency effect API built on `@solidjs/signals`.
+
+```ts
+import { createEffect, on } from "solid2/effects";
+```
+
+> Because the npm package is named `solid2`, the subpath is `solid2/effects`. An import such as `solid/effects` would refer to a different npm package named `solid`.
+
+## Goals
+
+`solid2` is structured as a collection of independent primitive families rather than one large flat module.
+
+```text
+solid2/
+  src/
+    effects/
+      createEffect.ts
+      index.ts
+    index.ts
+```
+
+That structure is intended to grow naturally:
+
+```text
+src/
+  effects/
+    index.ts
+  loading/
+    index.ts
+  signals/
+    index.ts
+  helpers/
+    index.ts
+```
+
+The package uses a wildcard subpath export, so adding `src/loading/index.ts` produces the public import `solid2/loading` after build without requiring another `package.json` export entry.
+
+The root `solid2` entry is a convenience barrel. Focused subpath imports such as `solid2/effects` are preferred because they make module ownership and future API growth clearer.
+
+---
+
+# `solid2/effects`
+
+`solid2/effects` wraps Solid 2's two-phase effect model with:
+
+- explicit dependencies,
+- accessor-array dependency syntax,
+- dependency callback syntax,
+- tuple inference,
+- async dependency callbacks,
+- async iterable dependencies,
+- per-invocation ownership,
+- async owner restoration through `context.scope`,
+- synchronous and asynchronous returned cleanup functions,
+- `once`,
+- `defer`,
+- explicit untracking control,
+- optional ownerless callbacks,
+- an `on(...)` DSL,
+- and the effect-first `createEffect2(...)` compatibility form.
+
+## Installation
+
+```sh
+npm install solid2 @solidjs/signals
+```
+
+The package declares `@solidjs/signals` as a peer dependency so the application and `solid2` share the same reactive runtime.
+
+Current peer range:
+
+```text
+@solidjs/signals >=2.0.0-rc.8 <3.0.0
+```
+
+## Import
+
+```ts
+import {
+  createEffect,
+  createEffect2,
+  on,
+  type Cleanup,
+  type CreateEffectOptions,
+  type DeferredEffectOptions,
+  type EffectContext,
+  type EffectResult,
+  type EffectScope,
+  type OnBuilder
+} from "solid2/effects";
+```
+
+The same exports are currently available from the root convenience barrel:
+
+```ts
+import { createEffect, on } from "solid2";
+```
+
+The canonical import for this primitive family is still:
+
+```ts
+import { createEffect, on } from "solid2/effects";
+```
+
+---
+
+# Quick start
+
+```ts
+import { createSignal, onCleanup } from "solid-js";
+import { createEffect } from "solid2/effects";
+
+const [count, setCount] = createSignal(0);
+
+createEffect(
+  [count],
+  ([value]) => {
+    console.log("count", value);
+
+    onCleanup(() => {
+      console.log("cleanup", value);
+    });
+  }
+);
+
+setCount(1);
+```
+
+The dependency list is explicit. Reads made in the effect body do not become new dependencies.
+
+---
+
+# API surface
+
+## `createEffect(dependencies, effect, options?)`
+
+The primary API is dependency-first:
+
+```ts
+createEffect(dependencies, effect, options?);
+```
+
+It accepts two dependency forms.
+
+### Accessor-array dependencies
+
+```ts
+createEffect(
+  [count, name, enabled],
+  ([countValue, nameValue, enabledValue]) => {
+    // number, string, boolean
+  }
+);
+```
+
+Each entry must be an accessor function. The callback receives a tuple containing the corresponding accessor values.
+
+Derived accessors can be mixed into the array:
+
+```ts
+createEffect(
+  [count, name, () => count() * 2],
+  ([countValue, nameValue, doubled]) => {
+    // number, string, number
+  }
+);
+```
+
+Do not pass already-read values:
+
+```ts
+// Wrong: count() and name() execute before createEffect sees them.
+createEffect([count(), name()], () => {});
+```
+
+Use accessors instead:
+
+```ts
+createEffect([count, name], ([countValue, nameValue]) => {
+  // ...
+});
+```
+
+### Dependency callback
+
+The dependency callback form is useful when dependencies need to be derived together:
+
+```ts
+createEffect(
+  () => [count(), user()?.id, count() * 2],
+  ([countValue, userId, doubled]) => {
+    // tuple values are inferred from the dependency callback
+  }
+);
+```
+
+This form can return:
+
+```ts
+readonly unknown[]
+PromiseLike<readonly unknown[]>
+AsyncIterable<readonly unknown[]>
+```
+
+The callback dependency path is materialized through Solid's computed/async signal path. That lets Solid handle pending values, stale async result suppression, and repeated async-iterable publications before the effect callback receives a ready tuple.
+
+---
+
+# Effect callback
+
+The callback receives two arguments:
+
+```ts
+(values, context) => result
+```
+
+Example:
+
+```ts
+createEffect(
+  [count],
+  ([value], context) => {
+    console.log(value);
+    console.log(context.scope.active);
+  }
+);
+```
+
+The common form destructures `scope`:
+
+```ts
+createEffect(
+  [count],
+  ([value], { scope }) => {
+    scope(() => {
+      // run under this invocation's owner
+    });
+  }
+);
+```
+
+The second parameter is an `EffectContext`; it is not directly callable.
+
+Incorrect:
+
+```ts
+createEffect([count], ([value], scope) => {
+  scope(() => {}); // EffectContext is not callable
+});
+```
+
+Correct:
+
+```ts
+createEffect([count], ([value], { scope }) => {
+  scope(() => {});
+});
+```
+
+---
+
+# `EffectContext`
+
+```ts
+interface EffectContext {
+  readonly scope: EffectScope;
+}
+```
+
+`EffectContext` is created once for each effect invocation.
+
+`context.scope` is lazy and memoized. The `EffectScope` function is only allocated if user code actually reads the property, and repeated reads during the same invocation return the same scope object.
+
+```ts
+createEffect([count], (_values, context) => {
+  const first = context.scope;
+  const second = context.scope;
+
+  console.log(first === second); // true
+});
+```
+
+This allows ordinary effects that never use `scope` to avoid allocating the scope closure.
+
+---
+
+# `EffectScope`
+
+```ts
+interface EffectScope {
+  <T>(fn: () => T): T | undefined;
+  readonly active: boolean;
+}
+```
+
+An `EffectScope` represents one specific invocation of an effect.
+
+## `scope(fn)`
+
+`scope(fn)` re-enters the owner belonging to that invocation.
+
+```ts
+createEffect([count], ([value], { scope }) => {
+  scope(() => {
+    onCleanup(() => console.log("cleanup", value));
+  });
+});
+```
+
+The callback result is returned:
+
+```ts
+createEffect([count], (_values, { scope }) => {
+  const result = scope(() => 42);
+  // result: number | undefined
+});
+```
+
+`undefined` is possible because the invocation may already have been disposed.
+
+## `scope.active`
+
+```ts
+createEffect([count], (_values, { scope }) => {
+  console.log(scope.active);
+});
+```
+
+`scope.active` is `true` while that exact invocation's owner is live.
+
+When an invocation is replaced or disposed, its previously captured scope becomes inactive:
+
+```ts
+let previousScope: EffectScope | undefined;
+
+createEffect([count], (_values, { scope }) => {
+  if (previousScope) {
+    console.log(previousScope.active); // false after replacement
+  }
+
+  previousScope = scope;
+});
+```
+
+Calling an inactive scope is a no-op and returns `undefined`.
+
+---
+
+# Ownership
+
+Each effect execution gets its own disposable invocation root.
+
+By default, the user callback executes under that invocation owner:
+
+```ts
+createEffect([count], ([value]) => {
+  onCleanup(() => {
+    console.log("cleanup", value);
+  });
+
+  createEffect([other], ([otherValue]) => {
+    console.log(value, otherValue);
+  });
+});
+```
+
+When `count` changes:
+
+1. the previous invocation root is disposed,
+2. its cleanup functions run,
+3. its nested reactive work is disposed,
+4. a new invocation root is created,
+5. the callback executes for the new dependency value.
+
+This prevents nested effects from accumulating across parent reruns.
+
+---
+
+# Async effect callbacks
+
+An effect callback may return a promise:
+
+```ts
+createEffect(
+  [userId],
+  async ([id], { scope }) => {
+    const user = await loadUser(id);
+
+    scope(() => {
+      console.log("resolved user", user);
+    });
+  }
+);
+```
+
+Do not rely on ambient ownership surviving an `await`. Capture `scope` and explicitly re-enter the invocation owner afterward.
+
+```ts
+createEffect(
+  [userId],
+  async ([id], { scope }) => {
+    const resource = await openResource(id);
+
+    scope(() => {
+      onCleanup(() => resource.close());
+    });
+  }
+);
+```
+
+If the dependency changes while the operation is pending, the old invocation is disposed. When its asynchronous work later resumes:
+
+```ts
+scope.active === false
+```
+
+and:
+
+```ts
+scope(() => {
+  // this will not execute for a stale invocation
+});
+```
+
+This makes it possible to prevent stale async work from attaching new owned resources to an obsolete invocation.
+
+---
+
+# Cleanup behavior
+
+There are three supported cleanup patterns.
+
+## `onCleanup()`
+
+With the default `owned: true`, native Solid cleanup works directly inside the callback:
+
+```ts
+createEffect([count], ([value]) => {
+  const resource = open(value);
+
+  onCleanup(() => {
+    resource.close();
+  });
+});
+```
+
+## Return a cleanup function
+
+```ts
+createEffect([count], ([value]) => {
+  const resource = open(value);
+
+  return () => {
+    resource.close();
+  };
+});
+```
+
+The wrapper registers the returned cleanup on the current invocation.
+
+## Return a promise of a cleanup function
+
+```ts
+createEffect([count], async ([value]) => {
+  const resource = await openAsync(value);
+
+  return () => {
+    resource.close();
+  };
+});
+```
+
+If the invocation is still active when the promise resolves, the cleanup is registered normally.
+
+If the invocation was already replaced, the late cleanup is executed immediately because there is no longer a valid invocation owner on which to register it.
+
+This prevents resources created by stale async work from leaking.
+
+## Combining cleanup styles
+
+`onCleanup()` and a returned cleanup may both be used:
+
+```ts
+createEffect([count], ([value]) => {
+  onCleanup(() => console.log("hook cleanup", value));
+
+  return () => {
+    console.log("returned cleanup", value);
+  };
+});
+```
+
+Both belong to the same invocation lifecycle.
+
+---
+
+# Dependency selection and snapshot reads
+
+Dependencies are determined only by the explicit dependency input.
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    console.log(value, other());
+  }
+);
+```
+
+`count` is a dependency.
+
+`other()` is a snapshot read inside the effect body and does not become another dependency.
+
+Changing `other` by itself does not rerun the effect. The newest `other()` value will be observed the next time `count` causes the effect to run.
+
+---
+
+# Options
+
+```ts
+export type CreateEffectOptions = EffectOptions & {
+  untrack?: boolean;
+  owned?: boolean;
+  once?: boolean;
+};
+```
+
+All native `EffectOptions` supported by the underlying Solid effect may be passed through, plus the options documented below.
+
+## `defer`
+
+Inherited from Solid's effect options.
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    console.log(value);
+  },
+  { defer: true }
+);
+```
+
+With `defer: true`, the initial callback execution is skipped. The effect begins applying on a dependency change.
+
+## `once`
+
+Default:
+
+```ts
+once: false
+```
+
+Without `defer`:
+
+```ts
+createEffect(
+  [count],
+  ([value]) => console.log(value),
+  { once: true }
+);
+```
+
+Behavior:
+
+```text
+initial execution
+first changed execution
+unsubscribe
+```
+
+So `{ once: true }` means **initial + one change**.
+
+With `defer`:
+
+```ts
+createEffect(
+  [count],
+  ([value]) => console.log(value),
+  { defer: true, once: true }
+);
+```
+
+Behavior:
+
+```text
+skip initial execution
+first changed execution
+unsubscribe
+```
+
+So `{ defer: true, once: true }` means **one changed execution only**.
+
+For a terminal async invocation, dependency observation is removed immediately, but that final invocation stays alive until the returned promise settles. This lets its captured `scope` remain usable during the final async operation.
+
+## `untrack`
+
+Default:
+
+```ts
+untrack: true
+```
+
+The user callback is explicitly wrapped in `untrack()` by default.
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    console.log(value, other());
+  },
+  { untrack: true }
+);
+```
+
+This makes effect-body reads explicit snapshot reads and suppresses Solid 2's strict untracked-read diagnostic for them.
+
+Set it to `false` to preserve the native diagnostic behavior:
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    console.log(value, other());
+  },
+  { untrack: false }
+);
+```
+
+Dependency selection does not change: body reads still do not become dependencies. The option controls the read/diagnostic policy of the callback body.
+
+`scope()` follows the same `untrack` choice when it restores the invocation owner.
+
+## `owned`
+
+Default:
+
+```ts
+owned: true
+```
+
+With the default, the callback runs under the invocation owner:
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    onCleanup(() => console.log("cleanup"));
+
+    createEffect([other], () => {
+      // nested effect belongs to this invocation
+    });
+  },
+  { owned: true }
+);
+```
+
+Set `owned: false` to run the callback with no owner:
+
+```ts
+createEffect(
+  [count],
+  ([value], { scope }) => {
+    // callback body itself has no owner
+
+    scope(() => {
+      // exact invocation owner restored here
+      onCleanup(() => console.log("cleanup"));
+    });
+  },
+  { owned: false }
+);
+```
+
+The invocation root still exists when `owned: false`; otherwise `context.scope()` would have nothing to restore.
+
+Returned cleanup functions continue to work with `owned: false` because returned cleanup registration is managed by the wrapper:
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    const resource = open(value);
+    return () => resource.close();
+  },
+  { owned: false }
+);
+```
+
+Direct `onCleanup()` and direct nested owned primitives should not be used in an ownerless callback. Put that work inside `scope()` instead.
+
+## `owned` and `untrack` are independent
+
+| `owned` | `untrack` | callback owner | callback read policy |
+| --- | --- | --- | --- |
+| `true` | `true` | invocation owner | explicit snapshot/untracked reads |
+| `true` | `false` | invocation owner | native strict-read diagnostics |
+| `false` | `true` | no owner | explicit snapshot/untracked reads |
+| `false` | `false` | no owner | native strict-read diagnostics |
+
+---
+
+# `on(dependencies)` DSL
+
+`on()` captures dependencies first and returns an `OnBuilder`.
+
+```ts
+const builder = on([count, name]);
+```
+
+Most code uses it inline:
+
+```ts
+on([count, name]).effect(([countValue, nameValue]) => {
+  console.log(countValue, nameValue);
+});
+```
+
+It supports both dependency forms accepted by `createEffect`.
+
+## Accessor arrays
+
+```ts
+on([count, name]).effect(([countValue, nameValue]) => {
+  // ...
+});
+```
+
+## Dependency callback
+
+```ts
+on(() => [count(), name()]).effect(([countValue, nameValue]) => {
+  // ...
+});
+```
+
+## `.effect(effect, options?)`
+
+Equivalent to the primary `createEffect` behavior for the captured dependencies:
+
+```ts
+on([count]).effect(
+  ([value]) => {
+    console.log(value);
+  },
+  {
+    once: true,
+    untrack: true,
+    owned: true
+  }
+);
+```
+
+The callback receives the same `EffectContext`:
+
+```ts
+on([count]).effect(([value], { scope }) => {
+  scope(() => {
+    // ...
+  });
+});
+```
+
+## `.deferEffect(effect, options?)`
+
+```ts
+on([count]).deferEffect(([value]) => {
+  console.log(value);
+});
+```
+
+This is equivalent to:
+
+```ts
+on([count]).effect(
+  ([value]) => {
+    console.log(value);
+  },
+  { defer: true }
+);
+```
+
+`deferEffect()` uses `DeferredEffectOptions`, which omits the `defer` property so callers cannot accidentally provide a conflicting value.
+
+It composes with `once`:
+
+```ts
+on([count]).deferEffect(
+  ([value]) => {
+    console.log(value);
+  },
+  { once: true }
+);
+```
+
+That runs exactly once, on the first dependency change.
+
+---
+
+# `createEffect2(effect, dependencies, options?)`
+
+`createEffect2` provides the earlier effect-first argument order:
+
+```ts
+createEffect2(
+  ([value]) => {
+    console.log(value);
+  },
+  [count]
+);
+```
+
+It has the same semantics as `createEffect`; only argument order differs.
+
+Dependency callback form:
+
+```ts
+createEffect2(
+  ([doubled]) => {
+    console.log(doubled);
+  },
+  () => [count() * 2]
+);
+```
+
+Options work identically:
+
+```ts
+createEffect2(
+  ([value], { scope }) => {
+    scope(() => {
+      // ...
+    });
+  },
+  [count],
+  {
+    defer: true,
+    once: true
+  }
+);
+```
+
+`createEffect` is the preferred public form for new code.
+
+---
+
+# Async dependencies
+
+Dependency callbacks can be asynchronous.
+
+## Promise dependency
+
+```ts
+createEffect(
+  async () => {
+    const id = userId();
+    const user = await loadUser(id);
+    return [id, user] as const;
+  },
+  ([id, user]) => {
+    console.log(id, user);
+  }
+);
+```
+
+The effect callback does not run until the dependency tuple is ready.
+
+When the dependency callback recomputes, stale promise results are handled by the underlying Solid async signal path rather than manually applied by this wrapper.
+
+## Async iterable dependency
+
+```ts
+createEffect(
+  async function* () {
+    yield [1] as const;
+    yield [2] as const;
+    yield [3] as const;
+  },
+  ([value]) => {
+    console.log(value);
+  }
+);
+```
+
+Each published tuple can produce another effect invocation.
+
+## Pending / NotReady dependencies
+
+Accessor dependencies can also be pending Solid async signals.
+
+```ts
+createEffect(
+  [asyncValue],
+  ([value]) => {
+    console.log(value);
+  }
+);
+```
+
+The effect body is not invoked with a partial tuple while one of its dependency reads is NotReady. Once the dependency is ready, the coherent tuple is applied.
+
+---
+
+# Nested effects
+
+Nested `solid2/effects` effects belong to the current invocation by default:
+
+```ts
+createEffect([outer], ([outerValue]) => {
+  createEffect([inner], ([innerValue]) => {
+    console.log(outerValue, innerValue);
+  });
+});
+```
+
+When `outer` changes, the old outer invocation is disposed, which disposes the old nested effect. A replacement nested effect is then created under the new invocation.
+
+This works recursively for deeper nested trees.
+
+---
+
+# Exported types
+
+## `Cleanup`
+
+```ts
+export type Cleanup = () => void;
+```
+
+A synchronous disposer.
+
+## `EffectScope`
+
+```ts
+export interface EffectScope {
+  <T>(fn: () => T): T | undefined;
+  readonly active: boolean;
+}
+```
+
+A callable handle for re-entering one specific invocation owner.
+
+## `EffectContext`
+
+```ts
+export interface EffectContext {
+  readonly scope: EffectScope;
+}
+```
+
+The context passed as the second effect callback argument.
+
+## `EffectResult`
+
+```ts
+export type EffectResult =
+  | void
+  | Cleanup
+  | PromiseLike<void | Cleanup>;
+```
+
+The supported result of an effect callback.
+
+## `CreateEffectOptions`
+
+Conceptually:
+
+```ts
+export type CreateEffectOptions = EffectOptions & {
+  untrack?: boolean;
+  owned?: boolean;
+  once?: boolean;
+};
+```
+
+The native Solid effect options are forwarded along with `solid2/effects` options.
+
+## `DeferredEffectOptions`
+
+```ts
+export type DeferredEffectOptions = Omit<CreateEffectOptions, "defer">;
+```
+
+Used by `OnBuilder.deferEffect()` because that method always sets `defer: true` itself.
+
+## `OnBuilder<T>`
+
+```ts
+export interface OnBuilder<T extends readonly unknown[]> {
+  effect(
+    effect: (values: T, context: EffectContext) => EffectResult,
+    options?: CreateEffectOptions
+  ): void;
+
+  deferEffect(
+    effect: (values: T, context: EffectContext) => EffectResult,
+    options?: DeferredEffectOptions
+  ): void;
+}
+```
+
+The actual source uses the package's internal effect function type, but this is the public shape exposed by the builder.
+
+---
+
+# Practical examples
+
+## Watch selected state but snapshot other state
+
+```ts
+createEffect([count], ([countValue]) => {
+  console.log({
+    count: countValue,
+    currentTheme: theme()
+  });
+});
+```
+
+Only `count` causes reruns.
+
+## One changed execution only
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    console.log("first change", value);
+  },
+  {
+    defer: true,
+    once: true
+  }
+);
+```
+
+## Initial execution plus one changed execution
+
+```ts
+createEffect(
+  [count],
+  ([value]) => {
+    console.log(value);
+  },
+  {
+    once: true
+  }
+);
+```
+
+## Restore ownership after `await`
+
+```ts
+createEffect(
+  [userId],
+  async ([id], { scope }) => {
+    const controller = new AbortController();
+    const response = await fetch(`/users/${id}`, {
+      signal: controller.signal
+    });
+
+    scope(() => {
+      onCleanup(() => controller.abort());
+    });
+
+    console.log(await response.json());
+  }
+);
+```
+
+## Explicitly ownerless callback
+
+```ts
+createEffect(
+  [count],
+  ([value], { scope }) => {
+    console.log("ownerless work", value);
+
+    scope(() => {
+      onCleanup(() => {
+        console.log("owned cleanup");
+      });
+    });
+  },
+  {
+    owned: false
+  }
+);
+```
+
+## Return cleanup instead of using `onCleanup`
+
+```ts
+createEffect([roomId], ([id]) => {
+  const socket = connect(id);
+  return () => socket.close();
+});
+```
+
+## Async resource with returned cleanup
+
+```ts
+createEffect([roomId], async ([id]) => {
+  const socket = await connectAsync(id);
+  return () => socket.close();
+});
+```
+
+---
+
+# Package layout
+
+```text
+solid2/
+├─ src/
+│  ├─ index.ts
+│  └─ effects/
+│     ├─ createEffect.ts
+│     └─ index.ts
+├─ tests/
+│  ├─ effects.test.ts
+│  ├─ test-utils.ts
+│  └─ runner.ts
+├─ examples/
+│  ├─ basic.tsx
+│  └─ async-scope.ts
+├─ package.json
+├─ tsconfig.json
+├─ tsconfig.build.json
+├─ CHANGELOG.md
+└─ README.md
+```
+
+The npm package only publishes the compiled `dist` tree plus documentation files.
+
+---
+
+# Adding another primitive family
+
+Suppose you add loading helpers.
+
+Create:
+
+```text
+src/loading/index.ts
+src/loading/createLoadingBoundary.ts
+```
+
+Then export from the module barrel:
+
+```ts
+// src/loading/index.ts
+export * from "./createLoadingBoundary.js";
+```
+
+After `npm run build`, the wildcard package export makes this available automatically:
+
+```ts
+import {
+  createLoadingBoundary
+} from "solid2/loading";
+```
+
+No new `package.json` export entry is required.
+
+If you also want the primitive available from the root convenience barrel, add it manually:
+
+```ts
+// src/index.ts
+export * from "./effects/index.js";
+export * from "./loading/index.js";
+```
+
+Keeping the root barrel manual prevents new module families from unexpectedly changing the flat root namespace.
+
+---
+
+# Build
+
+```sh
+npm install
+npm run build
+```
+
+The build uses TypeScript directly and preserves the module folder structure:
+
+```text
+dist/
+  index.js
+  index.d.ts
+  effects/
+    index.js
+    index.d.ts
+    createEffect.js
+    createEffect.d.ts
+```
+
+That structure maps directly to the package subpath exports.
+
+## Typecheck
+
+```sh
+npm run typecheck
+```
+
+## Tests
+
+```sh
+npm test
+```
+
+The repository retains the behavioral test suite used while developing the effect helper. Tests are not part of the published npm `files` list.
+
+## Pack locally
+
+```sh
+npm pack
+```
+
+`prepack` automatically runs the build before npm creates the tarball.
+
+---
+
+# Design notes
+
+## Why explicit dependencies?
+
+The dependency computation and side-effect body have different jobs:
+
+```ts
+createEffect(
+  () => [a(), b()],
+  ([aValue, bValue]) => {
+    // side effects
+  }
+);
+```
+
+The first phase explicitly describes what should cause the effect to update. The second phase receives a stable snapshot of those values and performs side effects without accidentally widening the dependency set.
+
+## Why a context object instead of passing `scope` directly?
+
+The callback shape is:
+
+```ts
+(values, context)
+```
+
+rather than:
+
+```ts
+(values, scope)
+```
+
+This leaves room for invocation-scoped helpers to be added later without changing callback arity or turning the second argument into an overloaded callable object.
+
+It also lets `scope` be lazy. Effects that never read `context.scope` do not allocate the `EffectScope` closure.
+
+## Why is `scope` invocation-specific?
+
+A scope from an old invocation must not be able to attach new resources after that invocation has been replaced.
+
+That is especially important for asynchronous work:
+
+```ts
+createEffect([id], async ([id], { scope }) => {
+  const result = await load(id);
+
+  scope(() => {
+    // only runs if this exact invocation is still alive
+  });
+});
+```
+
+The scope therefore captures one invocation owner rather than merely re-entering whichever owner happens to be current later.
+
+## Why keep returned cleanup support when `onCleanup` exists?
+
+Returned cleanup gives the effect callback a resource-oriented style:
+
+```ts
+createEffect([id], ([id]) => {
+  const resource = open(id);
+  return () => resource.close();
+});
+```
+
+It is also useful for `owned: false`, because the wrapper can register returned cleanups on the invocation owner without requiring the callback itself to run under that owner.
+
+Async returned cleanup additionally gives the wrapper a deterministic way to immediately release a resource that resolves after its invocation has already become stale.
+
+---
+
+# Status
+
+`solid2/effects` is experimental and targets the Solid 2 signals APIs. Its semantics are deliberately explicit and are covered by the included regression suite, but the package should be versioned conservatively while Solid 2 APIs are still evolving.