Merge pull request #44 from zeixcom/next

Version 1.3.1

Author: estherbrunner

.claude/skills/cause-effect-dev/references/api-facts.md

@@ -16,11 +16,11 @@ const value = createState<{ data: string } | never>({ data: '' })
 </type_constraint>
 
 <core_functions>
-**`createScope(fn)`**
+**`createScope(fn, options?)`**
 - Returns a single `Cleanup` function
-- `fn` receives no arguments
-- `fn` may return an optional cleanup that runs when the scope is disposed
-- Used to group effects and control their lifetime
+- `fn` receives no arguments and may return an optional cleanup that runs when the scope is disposed
+- Used to group effects and control their shared lifetime
+- `options.root = true` (`ScopeOptions`) — suppresses parent-owner registration; the returned `dispose` is the sole teardown mechanism. Use for scopes whose lifecycle is controlled externally (e.g. a web component's `disconnectedCallback`)
 
 **`createEffect(fn)`**
 - Returns a `Cleanup` function
@@ -40,7 +40,8 @@ const value = createState<{ data: string } | never>({ data: '' })
 
 **`unown(fn)`**
 - Runs `fn` without registering cleanups in the current owner (nulls `activeOwner`)
-- Use in `connectedCallback` and similar DOM lifecycle hooks where the DOM — not the reactive graph — owns the element's lifetime
+- For creating a scope with an external lifecycle authority, prefer `createScope(fn, { root: true })` — it is equivalent to `unown(() => createScope(fn))` but more readable
+- Use `unown` directly when detaching non-scope computations from the current owner
 </core_functions>
 
 <options>
@@ -91,7 +92,7 @@ Object.defineProperty(element, 'name', slot)
 <lifecycle_summary>
 | Function | Must be in owner? | Returns | Re-runs on dependency change? |
 |---|---|---|---|
-| `createScope(fn)` | No | `Cleanup` | No (fn runs once) |
+| `createScope(fn, options?)` | No | `Cleanup` | No (fn runs once) |
 | `createEffect(fn)` | **Yes** | `Cleanup` | Yes |
 | `createMemo(fn)` | No | `Memo<T>` | Lazily (on read) |
 | `createTask(fn)` | No | `Task<T>` | Yes (async) |

.claude/skills/cause-effect-dev/references/internal-types.md

@@ -29,7 +29,7 @@ Two independent global pointers are maintained by `src/graph.ts`:
 - Set to the currently-running Effect or Scope
 - Any cleanup registered while `activeOwner` is set is attached to that owner
 - Nulled by `unown(fn)` — cleanups registered inside `fn` are not owned by the current context
-- Use `unown` in `connectedCallback` for nodes whose lifecycle is managed by the DOM, not by the reactive graph
+- For web component `connectedCallback`, prefer `createScope(fn, { root: true })` over `unown(() => createScope(fn))` — both suppress parent registration, but `{ root: true }` is clearer at the call site
 </global_pointers>
 
 <ownership_vs_tracking>

.claude/skills/cause-effect/references/api-facts.md

@@ -19,10 +19,11 @@ const selected = createState<{ id: string } | { id: never }>({ id: '' })
 </type_constraint>
 
 <core_functions>
-**`createScope(fn)`**
+**`createScope(fn, options?)`**
 - Returns a single `Cleanup` function
 - `fn` receives no arguments and may return an optional cleanup
 - Use to group effects and control their shared lifetime
+- `options.root = true` (`ScopeOptions`) — suppresses parent-owner registration; the returned `dispose` is the sole teardown mechanism. Use when an external authority (e.g. a web component's `disconnectedCallback`) manages the scope's lifetime
 
 ```typescript
 const dispose = createScope(() => {
@@ -67,16 +68,18 @@ createEffect(() => {
 
 **`unown(fn)`**
 - Runs `fn` without registering cleanups in the current owner
-- Use in `connectedCallback` and similar DOM lifecycle methods where the DOM —
-  not the reactive graph — manages the element's lifetime
+- For DOM-managed lifecycles involving a scope, prefer `createScope(fn, { root: true })` — it is equivalent to `unown(() => createScope(fn))` but more readable
+- Use `unown` directly when detaching a single computation (e.g. `createEffect`) rather than a full scope
 
 ```typescript
 connectedCallback() {
-  // cleanup is tied to disconnectedCallback, not to a reactive owner
-  this.#cleanup = unown(() => createEffect(() => this.render()))
+  // preferred: createScope with root: true
+  this.#dispose = createScope(() => {
+    createEffect(() => this.render())
+  }, { root: true })
 }
 disconnectedCallback() {
-  this.#cleanup?.()
+  this.#dispose?.()
 }
 ```
 </core_functions>
@@ -194,7 +197,7 @@ Read all signals eagerly in the signals argument — not inside branches. See `n
 <lifecycle_summary>
 | Function | Requires owner? | Returns | Reactive? |
 |---|---|---|---|
-| `createScope(fn)` | No | `Cleanup` | No (fn runs once) |
+| `createScope(fn, options?)` | No | `Cleanup` | No (fn runs once) |
 | `createEffect(fn)` | **Yes** | `Cleanup` | Yes — re-runs on dependency change |
 | `createMemo(fn)` | No | `Memo<T>` | Lazy — recomputes on read if stale |
 | `createTask(fn)` | No | `Task<T>` | Yes — re-runs async on dependency change |

.claude/skills/cause-effect/references/error-classes.md

@@ -117,9 +117,10 @@ const dispose = createScope(() => {
 })
 ```
 
-**Exception:** use `unown` when the DOM manages the element's lifetime (e.g. inside
-`connectedCallback`/`disconnectedCallback`) and you intentionally want to bypass owner
-registration.
+**Exception:** use `createScope(fn, { root: true })` when the DOM manages the element's
+lifetime (e.g. inside `connectedCallback`/`disconnectedCallback`) and you intentionally
+want to bypass owner registration. `unown(() => createScope(fn))` achieves the same effect
+but is the legacy pattern.
 </RequiredOwnerError>
 
 <CircularDependencyError>

.claude/skills/cause-effect/references/signal-types.md

@@ -95,7 +95,7 @@ const results = createTask(async (prev, signal) => {
 - **Must be created inside an owner** (`createScope` or another effect) — throws `RequiredOwnerError` otherwise
 - Runs immediately on creation, then re-runs on dependency changes
 - Returns a `Cleanup` function; calling it disposes the effect and all its children
-- Use `unown` inside `connectedCallback` / `disconnectedCallback` when the DOM manages the element's lifetime
+- Use `createScope(fn, { root: true })` in `connectedCallback` for DOM-managed lifetimes — the returned `dispose` goes in `disconnectedCallback`; the scope is never silently disposed by a re-running outer effect
 
 ```typescript
 const dispose = createScope(() => {

.claude/skills/cause-effect/workflows/debug.md

@@ -31,7 +31,7 @@ Read the specific section in references/non-obvious-behaviors.md or references/e
 If the symptom does not match a known gotcha, read references/api-facts.md to confirm:
 - Signal generics use `T extends {}` (no `null` or `undefined`)
 - `createEffect` is inside an owner (`createScope` or another effect)
-- `unown` is used only for DOM-owned lifecycles, not to bypass ownership generally
+- For DOM-owned lifecycles involving a scope: use `createScope(fn, { root: true })`, not `unown(() => createScope(fn))`. `unown` is still correct for non-scope cases (e.g. detaching a single `createEffect`)
 - `batch` is used if multiple state writes should coalesce
 
 ## Step 4: Inspect library source (last resort)

.claude/skills/cause-effect/workflows/use-api.md

@@ -13,7 +13,7 @@ Read references/signal-types.md. Match the task to the appropriate signal(s) usi
 
 Before writing any `createEffect` call, confirm there is an active owner in scope:
 - Top-level effects must be wrapped in `createScope`
-- Effects in Web Component lifecycle methods that use DOM-managed lifetime should use `unown`
+- Effects in Web Component lifecycle methods that use DOM-managed lifetime: use `createScope(fn, { root: true })` — the returned `dispose` goes in `disconnectedCallback`. This suppresses parent-owner registration so the scope is never disposed by a re-running outer effect
 
 See references/api-facts.md → `<core_functions>` for the rules.
 

ARCHITECTURE.md

@@ -170,9 +170,11 @@ Cleanup functions are stored on the `cleanup` field of owner nodes. The field is
 
 `registerCleanup()` promotes from `null` → function → array as needed. `runCleanup()` executes all registered cleanups and resets the field to `null`.
 
-### `createScope(fn)`
+### `createScope(fn, options?)`
 
-Creates an ownership scope without an effect. The scope becomes `activeOwner` during `fn` execution. Returns a `dispose` function. If the scope is created inside another owner, its disposal is automatically registered on the parent.
+Creates an ownership scope without an effect. The scope becomes `activeOwner` during `fn` execution. Returns a `dispose` function. Unless `options.root` is `true`, the scope's disposal is automatically registered on the parent owner (if any).
+
+`{ root: true }` (via `ScopeOptions`) suppresses that registration, making the returned `dispose` the sole mechanism for tearing down the scope. This is the correct pattern for any owner with an external lifecycle authority (e.g. a web component whose `disconnectedCallback` is the only teardown point) — without it, a scope created inside a re-runnable effect would be disposed on the next effect re-run.
 
 ## Signal Types
 
@@ -358,3 +360,4 @@ The first-subscriber path is the key to `watched` lifecycle propagation: when an
 | `isEqual` placement | Implementation in `graph.ts`; public preset exported as `DEEP_EQUALITY` from `graph.ts` | `util.ts` (blocked by circular import: `errors.ts` → `util.ts`); keep in `list.ts` | `isEqual` needs `CircularDependencyError`, which lives in `errors.ts`; `errors.ts` already imports `util.ts`, so `util.ts` cannot import back. `graph.ts` already imports `CircularDependencyError` and is the correct home for all equality constants. |
 | `isEqual` public export | Deprecated alias re-exported from `index.ts` pointing to the implementation in `graph.ts` | Remove immediately | No known downstream consumers, but it was part of the public API — a deprecation cycle is the correct path to removal. |
 | Cycle detection in `isEqual` / `DEEP_EQUALITY` | No cycle detection — plain recursion, no `WeakSet` | (a) Keep `WeakSet` per call; (b) import `fast-deep-equal` or `dequal` | `WeakSet` allocation on every `List.set()` / `Store.set()` call is unnecessary overhead for the common case (plain JSON-like signal values). Circular signal data is a user bug; a stack overflow is an acceptable outcome. Importing an external package for a 20-line function contradicts the zero-dependency policy and bundle-size constraints. `DEEP_EQUALITY` has never shipped; deprecated `isEqual` has no known consumers — no major version required. |
+| `createScope` root option | `ScopeOptions { root?: boolean }` as second argument to `createScope` | Standalone `createRoot(fn)` export | One-line implementation difference; extending the existing function avoids adding a new export. `ScopeOptions` follows the `*Options` pattern used by every other creation function in the library (`SignalOptions`, `ListOptions`, `SensorOptions`, etc.). Positional boolean (`createScope(fn, true)`) was rejected: readable only with IDE hover support; an options object is self-documenting in code review. |

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 1.3.1
+
+### Added
+- `createScope` now accepts an optional `ScopeOptions` second argument; `{ root: true }` creates a root scope that is not registered on the current parent owner – the returned `dispose` is the sole teardown mechanism. Export new `ScopeOptions` type.
+
+### Changed
+- Improved type inference for `createList` and `createCollection` when providing a custom `createItem` factory (e.g. `createStore`). The generic type of the returned item signal is now properly inferred without requiring type assertions.
+
 ## 1.3.0
 
 ### Added

CLAUDE.md

@@ -29,4 +29,4 @@ These are easy to get wrong and not derivable from reading the source without pr
 
 **`Slot` is a valid property descriptor** with `get`, `set`, `configurable`, and `enumerable` — pass directly to `Object.defineProperty()`. `slot.replace(nextSignal)` swaps the backing signal. Slot has no `update()` — it is a forwarding layer, not a mutable cell.
 
-**`unown()` is the correct fix for DOM-owned component lifecycles.** `createScope` inside `connectedCallback` registers its `dispose` on the parent effect's cleanup list — disposing the component on the next parent re-run. Wrap with `unown(() => createScope(...))` to leave `disconnectedCallback` as the sole lifecycle authority.
+**`createScope(fn, { root: true })` is the correct fix for DOM-owned component lifecycles.** `createScope` inside `connectedCallback` registers its `dispose` on the parent effect's cleanup list — disposing the component on the next parent re-run. Pass `{ root: true }` (via `ScopeOptions`) to suppress that registration and leave `disconnectedCallback` as the sole lifecycle authority. `unown(() => createScope(...))` achieves the same effect but is the legacy pattern; `{ root: true }` is preferred because the intent is explicit at the call site. `unown()` remains useful for detaching arbitrary computations from the current owner when no new scope is needed.