solid-deps 0.0.6 → 0.0.8

package/README.md

@@ -1,8 +1,13 @@
 # solid-deps
 
-Track additional dependencies for an existing **Solid 2 computation**, including reads performed after an `await`.
+Restore Solid 2's reactive **tracking or owner context** for synchronous callbacks after an `await`.
 
-`solid-deps` adds subscriptions to the original effect without immediately re-executing it. When those sources change later, Solid schedules the computation normally.
+By default, `createScope()` chooses **one of two behaviors at capture time**:
+
+- **Tracking observer present (effect or memo):** capture the observer cycle and attach late reactive reads to it. Stale and disposed scopes reject calls.
+- **Plain owner present (component/owner body without tracking):** restore that owner using `runWithOwner()` for synchronous callbacks. This restores context and owned cleanups/children **but does not subscribe signals**.
+
+For a strictly observer-only factory, use `createObserverScope()`. The explicit owner argument to `createScope(owner)` continues to require a tracking Computed for backwards compatibility. `createOwnerScope()` is unchanged.
 
 ## Install
 
@@ -16,9 +21,35 @@ Or with Bun:
 bun add solid-deps solid-js@2.0.0-rc.18 @solidjs/signals@2.0.0-rc.18
 ```
 
-**Compatibility:** Tested with Solid 2.0.0-rc.17 **and** 2.0.0-rc.18 production, development and observe builds (Node/ESM regression and package consumer tests, plus real Chromium owner-bound bridge scenarios). `solid-deps` recognizes validated descriptive development fields directly and discovers unknown or minified graph fields at runtime. Other Solid 2 versions may work if they retain compatible internal graph semantics, but are not yet verified. Your app and `solid-deps` must share one `@solidjs/signals` runtime instance. SSR is not supported.
+**Compatibility:** This hybrid feature is tested with Solid 2.0.0-rc.17 **and** 2.0.0-rc.18; rc.20 is pending verification. The preexisting package was tested with Solid 2.0.0-rc.17 **and** 2.0.0-rc.18 production, development and observe builds (Node/ESM regression and package consumer tests, plus real Chromium owner-bound bridge scenarios). `solid-deps` recognizes validated descriptive development fields directly and discovers unknown or minified graph fields at runtime. Other Solid 2 versions may work if they retain compatible internal graph semantics, but are not yet verified. Your app and `solid-deps` must share one `@solidjs/signals` runtime instance. SSR is not supported.
+
+## Quick start: hybrid `createScope()`
+
+**Component body (plain-owner fallback):**
 
-## Quick start: `createScope()`
+```tsx
+import { getOwner, onCleanup } from 'solid-js';
+import { createScope } from 'solid-deps';
+
+function Component() {
+  const scope = createScope(); // No tracking observer; captures component owner
+
+  async function load() {
+    await fetch('/api/items');
+    scope(() => {
+      console.log(getOwner() !== null); // restored owner
+      onCleanup(() => console.log('component disposed'));
+    });
+  }
+
+  void load();
+  return <div>Loaded asynchronously</div>;
+}
+```
+
+Read accessors under this plain-owner fallback **do not** create subscriptions in the component. `runWithOwner()` deliberately clears tracking. Children and cleanups created inside the callback belong to the captured owner and are disposed with it. The callback itself must be synchronous; if it contains `await`, context is **not** restored after the `await`. Promise-returning callbacks are rejected.
+
+**Tracked effect or memo:**
 
 Capture a dependency scope inside the tracked part of your computation. Call it after `await` to attach signal reads to that same computation:
 
@@ -52,7 +83,9 @@ export default function Counter() {
 }
 ```
 
-`scope(callback)` is a **callable function** whose result is exactly the callback's return value. It tracks every reactive source synchronously read by the callback. It does **not** execute the callback under the captured effect's original owner/context: reads run under a temporary tracking observer and their subscriptions are transferred.
+`scope(callback)` is a **callable function** whose result is the callback's return value. **Only in the tracked-observer branch**, it grafts reactive sources read synchronously by the callback into the captured observer. It does **not** restore that observer's original owner context: reads run under a temporary tracking observer and their subscriptions are transferred.
+
+In the plain-owner branch, it uses `runWithOwner()` and does **not** graft dependencies. The branch is fixed when `createScope()` is called, even if the wrapper is invoked from a different context later.
 
 A scope can be called multiple times while its captured observer cycle is still current:
 
@@ -108,7 +141,7 @@ A later pending transition behaves differently from an initial pending read. If
 
 ## Alternative: `createOwnerScope()`
 
-`createScope()` is **cycle-bound**: when the effect recomputes, an earlier scope becomes stale. Use `createOwnerScope()` when an older asynchronous callback deliberately needs to attach reads to the **same still-live effect**, even after that effect has rerun.
+`createScope()` is **cycle-bound when an observer is captured**: when the effect recomputes, an earlier scope becomes stale. Use `createOwnerScope()` when an older asynchronous callback deliberately needs to attach reads to the **same still-live effect**, even after that effect has rerun.
 
 ```tsx
 import { createEffect, createSignal } from 'solid-js';
@@ -139,7 +172,7 @@ This example deliberately leaves the timeout running to demonstrate owner-bound
 
 Comparison:
 
-| | `createScope()` | `createOwnerScope()` |
+| | `createScope()` (observer branch) | `createOwnerScope()` |
 | --- | --- | --- |
 | Captures | Computation and dependency generation | Computation identity only |
 | Reusable after a normal effect rerun | No — throws `StaleScopeError` | Yes, while the effect is alive |
@@ -151,9 +184,15 @@ Owner-bound callbacks do **not** restore Solid ownership context, transfer to a
 
 ## API
 
-### `createScope(owner?)`
+### `createScope(owner?)` / `createHybridScope(owner?)`
+
+The default and explicit hybrid alias are the same function. Without arguments, capture the current tracking observer if present; otherwise capture the current plain owner. If neither exists, throw immediately. With an **explicit owner** argument, preserve the preexisting strict observer-only behavior: the supplied owner must be a tracking Computed.
+
+When an observer is captured, calls attach reads to its captured dependency generation. When only a plain owner is captured, calls restore owner/context synchronously, without tracking reactive dependencies. A disposed owner throws `DisposedScopeError` before the callback executes.
+
+### `createObserverScope(owner?)`
 
-Create a callable scope that captures an observer and its current dependency generation.
+The strict observer-only equivalent of the pre-hybrid `createScope()`. Use it when a missing tracking computation must be an error even inside a component owner. It has the same stale-cycle and disposed behavior as the original graph attachment factory.
 
 ```ts
 const scope = createScope();       // Capture current tracked observer implicitly
@@ -162,7 +201,7 @@ const scope2 = createScope(owner); // Explicit existing computation owner
 const value = scope(() => signal());
 ```
 
-The implicit form must be invoked while an observer is actively tracking, generally at the start of the effect's computation, before `await`. The explicit owner must be a tracking computation, not an arbitrary Solid root/component owner.
+The implicit form must be invoked **before `await`**, while the intended observer or owner is active. The explicit owner parameter remains strictly observer-only; it must be a tracking computation, not a plain root/component owner.
 
 A scope call:
 
@@ -286,6 +325,8 @@ export interface AttachReadResult<T> {
 }
 
 export declare function createScope(owner?: Owner | null): Scope;
+export declare function createHybridScope(owner?: Owner | null): Scope;
+export declare function createObserverScope(owner?: Owner | null): Scope;
 export declare function createOwnerScope(owner?: Owner | null): Scope;
 export declare function captureOwnerCycle(owner?: Owner | null): OwnerCycle;
 export declare function attachRead<T>(
@@ -549,7 +590,7 @@ Target: Solid 2 with `@solidjs/signals` compatible with `>=2.0.0-rc.17 <3.0.0`.
 
 ## Online Solid playground check
 
-A copy-pasteable `main.tsx` is available in the source ZIP at `examples/online-playground/main.tsx`. Install `solid-deps@0.0.5`, ensure the playground runs a Solid 2 browser build with a shared signals runtime, and use **Run runtime checks**. It reports successful automatic layout discovery, async dependency attachment, deduplication, future updates, stale cycles, and disposal.
+A copy-pasteable `main.tsx` is available in the source ZIP at `examples/online-playground/main.tsx`. Install `solid-deps@0.0.6`, ensure the playground runs a Solid 2 browser build with a shared signals runtime, and use **Run runtime checks**. It reports successful automatic layout discovery, async dependency attachment, deduplication, future updates, stale cycles, and disposal.
 
 ## Opt-in native pending parity: `createRetainedScope()`
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "solid-deps",
-  "version": "0.0.6",
-  "description": "Experimental late dependency tracking for Solid 2 via graph attachment or delegated scopes",
+  "version": "0.0.8",
+  "description": "Experimental Solid 2 late-dependency tracking and hybrid owner fallback",
   "type": "module",
   "license": "MIT",
   "engines": {
@@ -23,6 +23,7 @@
     "src/discover.mjs",
     "src/retained-scope.mjs",
     "src/index.mjs",
+    "src/hybrid-scope.mjs",
     "types/index.d.mts",
     "README.md",
     "LICENSE",
@@ -44,9 +45,9 @@
   ],
   "scripts": {
     "setup": "node scripts/setup.mjs",
-    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs",
-    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs",
-    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs",
+    "test": "node --conditions=browser --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs test/test-hybrid-scope.mjs",
+    "test:dev": "node --conditions=browser --conditions=development --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs test/test-hybrid-scope.mjs",
+    "test:observe": "node --conditions=browser --conditions=observe --test test/test.mjs test/test-async.mjs test/test-return.mjs test/test-scope.mjs test/test-manifest.mjs test/test-graph-hardening.mjs test/test-async-transitions.mjs test/test-transaction-integrity.mjs test/test-scheduler-lifecycle.mjs test/test-release-hardening.mjs test/test-discovery.mjs test/test-fastpath.mjs test/test-owner-bound-research.mjs test/test-owner-scope.mjs test/test-notready-lifecycle.mjs test/test-loading-suspension.mjs test/test-loading-recovery-research.mjs test/test-native-notready-parity.mjs test/test-pending-status-propagation.mjs test/test-retained-scope.mjs test/test-research-retained.mjs test/test-parallel-parity.mjs test/test-batched-reads.mjs test/test-direct-links-research.mjs test/test-delegated-scope-research.mjs test/test-owner-cached-delegated.mjs test/test-sharded-delegated.mjs test/test-memory-conformance.mjs test/test-optimized-delegated.mjs test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs test/test-delegated-pending-bridge-dev25.mjs test/test-hybrid-scope.mjs",
     "test:all": "node scripts/run-tests.mjs",
     "test:package": "node scripts/smoke-package.mjs",
     "test:browser": "node --test test/browser/playwright.test.mjs",
@@ -57,11 +58,21 @@
     "test:unified-contract": "node --conditions=browser --test test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs && node --conditions=browser --conditions=development --test test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs && node --conditions=browser --conditions=observe --test test/test-unified-scope-contract.mjs test/test-unified-advanced-contract.mjs test/test-delegated-retention-contract.mjs test/test-delegated-default-dev19.mjs",
     "bench:realistic": "node --conditions=browser --expose-gc research/benchmark-realistic-scopes-dev17.mjs",
     "test:matrix": "node scripts/test-matrix.mjs",
-    "setup:browser": "node scripts/setup-browser.mjs"
+    "setup:browser": "node scripts/setup-browser.mjs",
+    "test:hybrid:browser": "node scripts/browser-hybrid-chromium.mjs --rc=17 && node scripts/browser-hybrid-chromium.mjs --rc=18 && node scripts/setup.mjs --rc=17",
+    "test:rc20": "node scripts/test-matrix.mjs --rc=20",
+    "test:hybrid:types": "tsc -p tsconfig.hybrid.json"
   },
   "devDependencies": {
     "@solidjs/signals": "2.0.0-rc.17",
     "solid-js": "2.0.0-rc.17",
     "playwright-core": "^1.56.0"
+  },
+  "typesVersions": {
+    "*": {
+      "delegated": [
+        "types/delegated.d.mts"
+      ]
+    }
   }
 }

package/src/hybrid-scope.mjs

@@ -0,0 +1,47 @@
+/**
+ * One factory for two explicitly separate execution contexts:
+ *  - tracked computation: attach reads to its captured observer cycle;
+ *  - plain owned scope: re-enter its owner without reactive attachment.
+ *
+ * Never mix both semantics in a single invocation. An explicitly supplied
+ * observer retains the legacy strict observer-only behavior.
+ */
+import { getObserver, getOwner, isDisposed, runWithOwner } from '@solidjs/signals';
+import {
+  createScope as createTrackedScope,
+  DisposedScopeError
+} from './attach-read.mjs';
+
+/** Original strict, cycle-bound, observer-only factory. */
+export const createObserverScope = createTrackedScope;
+
+function ownerFallback(owner) {
+  return function scope(callback) {
+    if (typeof callback !== 'function') throw new TypeError('scope requires a synchronous callback');
+    if (isDisposed(owner)) throw new DisposedScopeError();
+    const value = runWithOwner(owner, callback);
+    if (value != null && typeof value.then === 'function')
+      throw new TypeError('scope callback must be synchronous; split at await before calling scope');
+    return value;
+  };
+}
+
+/**
+ * Capture either the current tracking observer or, if none, the current owner.
+ * An explicit target preserves the legacy createScope(observer) contract:
+ * it MUST be a tracking Computed, not a plain owner.
+ */
+export function createHybridScope(owner) {
+  if (arguments.length !== 0) return createTrackedScope(owner);
+  const observer = getObserver();
+  if (observer) return createTrackedScope(observer);
+  const capturedOwner = getOwner();
+  if (!capturedOwner) {
+    throw new Error('createScope requires an active Solid tracking observer or owner');
+  }
+  if (isDisposed(capturedOwner)) throw new DisposedScopeError();
+  return ownerFallback(capturedOwner);
+}
+
+/** Default factory for owner-scope transforms. */
+export const createScope = createHybridScope;

package/src/index.mjs

@@ -1,2 +1,3 @@
 export { createRetainedScope } from './retained-scope.mjs';
-export { attachRead, attachReads, captureOwnerCycle, createScope, createOwnerScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';
+export { createScope, createHybridScope, createObserverScope } from './hybrid-scope.mjs';
+export { attachRead, attachReads, captureOwnerCycle, createOwnerScope, inspectDeps, StaleScopeError, DisposedScopeError } from './attach-read.mjs';

package/types/index.d.mts

@@ -42,11 +42,22 @@ export declare class DisposedScopeError extends Error {
 export declare function captureOwnerCycle(owner?: Owner | null): OwnerCycle;
 
 /**
- * Create a callable dependency scope for a tracked observer cycle.
- * Throws StaleScopeError / DisposedScopeError rather than returning a silent undefined.
+ * Hybrid default: capture a tracking observer cycle when available, otherwise
+ * capture a plain Solid owner and restore it using runWithOwner() for each
+ * synchronous callback. The owner-only branch does not subscribe signal reads.
+ * An explicitly passed owner must still be a tracking Computed (the legacy
+ * createScope(observer) behavior); plain-owner fallback is implicit only.
+ * Calls after observer supersession throw StaleScopeError; calls after
+ * either owner is disposed throw DisposedScopeError.
  */
 export declare function createScope(owner?: Owner | null): Scope;
 
+/** Same implementation as createScope: explicit name for the hybrid factory. */
+export declare function createHybridScope(owner?: Owner | null): Scope;
+
+/** Strict legacy factory: requires a tracking observer, even under a plain owner. */
+export declare function createObserverScope(owner?: Owner | null): Scope;
+
 /**
  * Create an owner-bound callable scope. Unlike createScope(), it stays valid
  * across normal reruns of the same computation and rejects final disposal.