@logixjs/react 0.1.0

package/dist/chunk-UFFCJGSZ.js

@@ -0,0 +1,981 @@
+import {
+  RuntimeContext,
+  createRuntimeAdapter,
+  getModuleCache,
+  isDevEnv,
+  stableHash,
+  useLayerBinding
+} from "./chunk-2WFULYPJ.js";
+
+// src/internal/hooks/useRuntime.ts
+import { useContext, useEffect, useMemo, useRef } from "react";
+import { Layer } from "effect";
+
+// src/internal/provider/errors.ts
+var RuntimeProviderNotFoundError = class extends Error {
+  constructor(hookName) {
+    super(
+      `[${hookName}] RuntimeProvider not found.
+
+Fix:
+- Wrap your app (or the calling component subtree) with <RuntimeProvider runtime={runtime}>.
+- If using nested providers, ensure an ancestor RuntimeProvider provides \`runtime\`.
+- If you intended to call this hook outside React, use @logixjs/core directly.
+`
+    );
+    this.name = "RuntimeProviderNotFoundError";
+  }
+};
+
+// src/internal/hooks/useRuntime.ts
+function useRuntime(options) {
+  const context = useContext(RuntimeContext);
+  if (!context) {
+    throw new RuntimeProviderNotFoundError("useRuntime");
+  }
+  const mergedLayerCacheRef = useRef(null);
+  const mergedLayer = useMemo(() => {
+    if (!options) {
+      return void 0;
+    }
+    const { layer, layers } = options;
+    const hasLayersArray = Array.isArray(layers) && layers.length > 0;
+    if (!layer && !hasLayersArray) {
+      return void 0;
+    }
+    if (hasLayersArray) {
+      const all = layer ? [layer, ...layers] : layers;
+      const cached = mergedLayerCacheRef.current;
+      const shallowEqual = cached && cached.layers.length === all.length && cached.layers.every((item, idx) => item === all[idx]);
+      if (shallowEqual) {
+        return cached.merged;
+      }
+      const merged = Layer.mergeAll(...all);
+      mergedLayerCacheRef.current = { layers: all, merged };
+      return merged;
+    }
+    return layer;
+  }, [options?.layer, options?.layers]);
+  const lastLayersRef = useRef(null);
+  const shallowEqualLayers = (a, b) => !!a && !!b && a.length === b.length && a.every((item, idx) => item === b[idx]);
+  useEffect(() => {
+    if (!isDevEnv()) {
+      return;
+    }
+    if (options?.layers && lastLayersRef.current && lastLayersRef.current !== options.layers && !shallowEqualLayers(lastLayersRef.current, options.layers)) {
+      console.warn(
+        "[RuntimeProvider] useRuntime received a new layers reference. Memoize the layers array with useMemo to avoid rebuilding Layers on every render (performance jitter)."
+      );
+    }
+    lastLayersRef.current = options?.layers ?? null;
+  }, [options?.layers]);
+  const { binding } = useLayerBinding(context.runtime, mergedLayer, !!mergedLayer);
+  return useMemo(() => {
+    if (!binding) {
+      return context.runtime;
+    }
+    return createRuntimeAdapter(
+      context.runtime,
+      [binding.context],
+      [binding.scope],
+      [binding.loggers],
+      [binding.logLevel],
+      [binding.debugSinks]
+    );
+  }, [context.runtime, binding]);
+}
+
+// src/internal/hooks/shallow.ts
+var hasObjectShape = (value) => typeof value === "object" && value !== null;
+var hasIterator = (value) => hasObjectShape(value) && typeof value[Symbol.iterator] === "function";
+var shallow = (previous, next) => {
+  if (Object.is(previous, next)) return true;
+  if (!hasObjectShape(previous) || !hasObjectShape(next)) {
+    return false;
+  }
+  if (Array.isArray(previous) && Array.isArray(next)) {
+    if (previous.length !== next.length) return false;
+    for (let i = 0; i < previous.length; i++) {
+      if (!Object.is(previous[i], next[i])) return false;
+    }
+    return true;
+  }
+  if (previous instanceof Map && next instanceof Map) {
+    if (previous.size !== next.size) return false;
+    for (const [key, value] of previous) {
+      if (!next.has(key)) return false;
+      if (!Object.is(value, next.get(key))) return false;
+    }
+    return true;
+  }
+  if (previous instanceof Set && next instanceof Set) {
+    if (previous.size !== next.size) return false;
+    for (const value of previous) {
+      if (!next.has(value)) return false;
+    }
+    return true;
+  }
+  if (hasIterator(previous) && hasIterator(next)) {
+    const a = previous[Symbol.iterator]();
+    const b = next[Symbol.iterator]();
+    while (true) {
+      const ra = a.next();
+      const rb = b.next();
+      if (ra.done || rb.done) return ra.done === rb.done;
+      if (!Object.is(ra.value, rb.value)) return false;
+    }
+  }
+  const prevKeys = Object.keys(previous);
+  const nextKeys = Object.keys(next);
+  if (prevKeys.length !== nextKeys.length) return false;
+  for (const key of prevKeys) {
+    if (!Object.prototype.hasOwnProperty.call(next, key)) return false;
+    if (!Object.is(previous[key], next[key])) return false;
+  }
+  return true;
+};
+
+// src/internal/hooks/useSelector.ts
+import { useContext as useContext3, useEffect as useEffect3, useMemo as useMemo3 } from "react";
+import { useSyncExternalStoreWithSelector } from "use-sync-external-store/shim/with-selector";
+import * as Logix2 from "@logixjs/core";
+
+// src/internal/hooks/useModuleRuntime.ts
+import { useEffect as useEffect2, useMemo as useMemo2, useContext as useContext2 } from "react";
+import * as Logix from "@logixjs/core";
+import { Scope } from "effect";
+
+// src/internal/store/ModuleRef.ts
+var isModuleRef = (value) => typeof value === "object" && value !== null && "runtime" in value && "actions" in value && "dispatch" in value;
+var makeModuleActions = (dispatch) => {
+  const cache = /* @__PURE__ */ new Map();
+  const api = new Proxy(
+    {},
+    {
+      get: (_target, prop) => {
+        if (cache.has(prop)) {
+          return cache.get(prop);
+        }
+        if (prop === "dispatch") {
+          cache.set(prop, dispatch);
+          return dispatch;
+        }
+        if (prop === "then" || typeof prop !== "string") {
+          return void 0;
+        }
+        const fn = (...args) => {
+          const payload = args[0];
+          dispatch({ _tag: prop, payload });
+        };
+        cache.set(prop, fn);
+        return fn;
+      }
+    }
+  );
+  return api;
+};
+function makeModuleDispatchers(dispatch, tokens) {
+  const cache = /* @__PURE__ */ new Map();
+  if (tokens) {
+    const out = {};
+    for (const [key, token] of Object.entries(tokens)) {
+      const fn = Object.assign(
+        ((...args) => {
+          const action = token(...args);
+          dispatch(action);
+          return action;
+        }),
+        token
+      );
+      out[key] = fn;
+    }
+    return out;
+  }
+  const api = new Proxy(
+    {},
+    {
+      get: (_target, prop) => {
+        if (cache.has(prop)) {
+          return cache.get(prop);
+        }
+        if (prop === "then" || prop === "dispatch" || typeof prop !== "string") {
+          return void 0;
+        }
+        const fn = (...args) => {
+          const payload = args[0];
+          const action = { _tag: prop, payload };
+          dispatch(action);
+          return action;
+        };
+        cache.set(prop, fn);
+        return fn;
+      }
+    }
+  );
+  return api;
+}
+var HANDLE_EXTEND = /* @__PURE__ */ Symbol.for("logix.module.handle.extend");
+var isObjectLike = (value) => typeof value === "object" && value !== null || typeof value === "function";
+var applyHandleExtend = (tag, runtime, base) => {
+  if (!isObjectLike(tag)) {
+    return base;
+  }
+  const extend = tag[HANDLE_EXTEND];
+  if (typeof extend !== "function") {
+    return base;
+  }
+  const next = extend(
+    runtime,
+    base
+  );
+  if (!next || typeof next !== "object") {
+    return base;
+  }
+  return { ...base, ...next };
+};
+
+// src/internal/hooks/useModuleRuntime.ts
+var isModuleRuntime = (value) => typeof value === "object" && value !== null && "dispatch" in value && "getState" in value;
+function useModuleRuntime(handle) {
+  const runtime = useRuntime();
+  const runtimeContext = useContext2(RuntimeContext);
+  if (!runtimeContext) {
+    throw new RuntimeProviderNotFoundError("useModuleRuntime");
+  }
+  const cache = useMemo2(
+    () => getModuleCache(runtimeContext.runtime, runtimeContext.reactConfigSnapshot, runtimeContext.configVersion),
+    [runtimeContext.runtime, runtimeContext.reactConfigSnapshot, runtimeContext.configVersion]
+  );
+  const isTagHandle = !isModuleRef(handle) && !isModuleRuntime(handle);
+  const resolved = useMemo2(() => {
+    if (isModuleRef(handle)) {
+      return handle.runtime;
+    }
+    if (isModuleRuntime(handle)) {
+      return handle;
+    }
+    const tag = handle;
+    const tokenId = tag.id ?? "ModuleTag";
+    const preloadKey = runtimeContext.policy.preload?.keysByTagId.get(tokenId);
+    const key = preloadKey ?? `tag:${tokenId}`;
+    const mode = runtimeContext.policy.moduleTagMode;
+    const factory = (scope) => tag.pipe(Scope.extend(scope));
+    return mode === "suspend" ? cache.read(key, factory, void 0, tokenId, {
+      entrypoint: "react.useModuleRuntime",
+      policyMode: runtimeContext.policy.mode,
+      yield: runtimeContext.policy.yield
+    }) : cache.readSync(key, factory, void 0, tokenId, {
+      entrypoint: "react.useModuleRuntime",
+      policyMode: runtimeContext.policy.mode,
+      warnSyncBlockingThresholdMs: 5
+    });
+  }, [cache, runtimeContext.policy, handle]);
+  useEffect2(() => {
+    if (!isTagHandle) {
+      return;
+    }
+    if (!isDevEnv() && !Logix.Debug.isDevtoolsEnabled()) {
+      return;
+    }
+    const tokenId = handle?.id ?? "ModuleTag";
+    const effect = Logix.Debug.record({
+      type: "trace:react.moduleTag.resolve",
+      moduleId: resolved.moduleId,
+      instanceId: resolved.instanceId,
+      data: {
+        mode: runtimeContext.policy.moduleTagMode,
+        tokenId,
+        yieldStrategy: runtimeContext.policy.yield.strategy
+      }
+    });
+    runtime.runFork(effect);
+  }, [runtime, runtimeContext.policy, resolved, handle, isTagHandle]);
+  return resolved;
+}
+
+// src/internal/store/ModuleRuntimeExternalStore.ts
+import { Effect as Effect2, Fiber, Stream } from "effect";
+var storesByRuntime = /* @__PURE__ */ new WeakMap();
+var getStoreMapForRuntime = (runtime) => {
+  const cached = storesByRuntime.get(runtime);
+  if (cached) return cached;
+  const next = /* @__PURE__ */ new WeakMap();
+  storesByRuntime.set(runtime, next);
+  return next;
+};
+var getModuleRuntimeExternalStore = (runtime, moduleRuntime, options) => {
+  const byModule = getStoreMapForRuntime(runtime);
+  const cached = byModule.get(moduleRuntime);
+  if (cached) {
+    return cached;
+  }
+  let currentState;
+  const listeners = /* @__PURE__ */ new Set();
+  const lowPriorityDelayMs = options?.lowPriorityDelayMs ?? 16;
+  const lowPriorityMaxDelayMs = options?.lowPriorityMaxDelayMs ?? 50;
+  let notifyScheduled = false;
+  let notifyScheduledLow = false;
+  let lowTimeoutId;
+  let lowMaxTimeoutId;
+  let lowRafId;
+  const cancelLow = () => {
+    if (!notifyScheduledLow) return;
+    notifyScheduledLow = false;
+    if (lowTimeoutId != null) {
+      clearTimeout(lowTimeoutId);
+      lowTimeoutId = void 0;
+    }
+    if (lowMaxTimeoutId != null) {
+      clearTimeout(lowMaxTimeoutId);
+      lowMaxTimeoutId = void 0;
+    }
+    const cancel = globalThis.cancelAnimationFrame;
+    if (cancel && typeof lowRafId === "number") {
+      cancel(lowRafId);
+      lowRafId = void 0;
+    }
+  };
+  const flushNotify = () => {
+    notifyScheduled = false;
+    cancelLow();
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const scheduleNotify = (priority) => {
+    if (priority === "low") {
+      if (notifyScheduled) return;
+      if (notifyScheduledLow) return;
+      notifyScheduledLow = true;
+      const flush = () => {
+        if (!notifyScheduledLow) return;
+        flushNotify();
+      };
+      const raf = globalThis.requestAnimationFrame;
+      if (raf) {
+        lowRafId = raf(flush);
+      } else {
+        lowTimeoutId = setTimeout(flush, lowPriorityDelayMs);
+      }
+      lowMaxTimeoutId = setTimeout(flush, lowPriorityMaxDelayMs);
+      return;
+    }
+    cancelLow();
+    if (notifyScheduled) return;
+    notifyScheduled = true;
+    queueMicrotask(flushNotify);
+  };
+  let fiber;
+  const ensureSubscription = () => {
+    if (fiber) return;
+    fiber = runtime.runFork(
+      Stream.runForEach(
+        moduleRuntime.changesWithMeta((state) => state),
+        ({ value: state, meta }) => Effect2.sync(() => {
+          currentState = state;
+          scheduleNotify(meta.priority);
+        })
+      )
+    );
+  };
+  const refreshSnapshotIfStale = () => {
+    if (currentState === void 0) {
+      return;
+    }
+    try {
+      const latest = runtime.runSync(moduleRuntime.getState);
+      if (currentState === void 0 || !Object.is(currentState, latest)) {
+        currentState = latest;
+        scheduleNotify("normal");
+      }
+    } catch {
+    }
+  };
+  const getSnapshot = () => {
+    if (currentState !== void 0) return currentState;
+    currentState = runtime.runSync(moduleRuntime.getState);
+    return currentState;
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    ensureSubscription();
+    refreshSnapshotIfStale();
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size > 0) return;
+      const running = fiber;
+      if (!running) return;
+      fiber = void 0;
+      cancelLow();
+      runtime.runFork(Fiber.interrupt(running));
+    };
+  };
+  const store = { getSnapshot, subscribe };
+  byModule.set(moduleRuntime, store);
+  return store;
+};
+
+// src/internal/store/ModuleRuntimeSelectorExternalStore.ts
+import { Effect as Effect3, Fiber as Fiber2, Stream as Stream2 } from "effect";
+var storesByRuntime2 = /* @__PURE__ */ new WeakMap();
+var getStoreMapForRuntime2 = (runtime) => {
+  const cached = storesByRuntime2.get(runtime);
+  if (cached) return cached;
+  const next = /* @__PURE__ */ new WeakMap();
+  storesByRuntime2.set(runtime, next);
+  return next;
+};
+var getOrCreateSelectorMapForModule = (byModule, moduleRuntime) => {
+  const cached = byModule.get(moduleRuntime);
+  if (cached) return cached;
+  const next = /* @__PURE__ */ new Map();
+  byModule.set(moduleRuntime, next);
+  return next;
+};
+var equalsValue = (readQuery, a, b) => {
+  if (readQuery.equalsKind === "custom" && typeof readQuery.equals === "function") {
+    return readQuery.equals(a, b);
+  }
+  if (readQuery.equalsKind === "shallowStruct") {
+    return shallow(a, b);
+  }
+  return Object.is(a, b);
+};
+var getModuleRuntimeSelectorExternalStore = (runtime, moduleRuntime, selectorReadQuery, options) => {
+  const byModule = getStoreMapForRuntime2(runtime);
+  const bySelector = getOrCreateSelectorMapForModule(byModule, moduleRuntime);
+  const cached = bySelector.get(selectorReadQuery.selectorId);
+  if (cached) {
+    return cached;
+  }
+  let currentValue;
+  const listeners = /* @__PURE__ */ new Set();
+  const lowPriorityDelayMs = options?.lowPriorityDelayMs ?? 16;
+  const lowPriorityMaxDelayMs = options?.lowPriorityMaxDelayMs ?? 50;
+  let notifyScheduled = false;
+  let notifyScheduledLow = false;
+  let lowTimeoutId;
+  let lowMaxTimeoutId;
+  let lowRafId;
+  const cancelLow = () => {
+    if (!notifyScheduledLow) return;
+    notifyScheduledLow = false;
+    if (lowTimeoutId != null) {
+      clearTimeout(lowTimeoutId);
+      lowTimeoutId = void 0;
+    }
+    if (lowMaxTimeoutId != null) {
+      clearTimeout(lowMaxTimeoutId);
+      lowMaxTimeoutId = void 0;
+    }
+    const cancel = globalThis.cancelAnimationFrame;
+    if (cancel && typeof lowRafId === "number") {
+      cancel(lowRafId);
+      lowRafId = void 0;
+    }
+  };
+  const flushNotify = () => {
+    notifyScheduled = false;
+    cancelLow();
+    for (const listener of listeners) {
+      listener();
+    }
+  };
+  const scheduleNotify = (priority) => {
+    if (priority === "low") {
+      if (notifyScheduled) return;
+      if (notifyScheduledLow) return;
+      notifyScheduledLow = true;
+      const flush = () => {
+        if (!notifyScheduledLow) return;
+        flushNotify();
+      };
+      const raf = globalThis.requestAnimationFrame;
+      if (raf) {
+        lowRafId = raf(flush);
+      } else {
+        lowTimeoutId = setTimeout(flush, lowPriorityDelayMs);
+      }
+      lowMaxTimeoutId = setTimeout(flush, lowPriorityMaxDelayMs);
+      return;
+    }
+    cancelLow();
+    if (notifyScheduled) return;
+    notifyScheduled = true;
+    queueMicrotask(flushNotify);
+  };
+  let fiber;
+  const ensureSubscription = () => {
+    if (fiber) return;
+    fiber = runtime.runFork(
+      Stream2.runForEach(
+        moduleRuntime.changesReadQueryWithMeta(selectorReadQuery),
+        ({ value, meta }) => Effect3.sync(() => {
+          currentValue = value;
+          scheduleNotify(meta.priority);
+        })
+      )
+    );
+  };
+  const refreshSnapshotIfStale = () => {
+    if (currentValue === void 0) {
+      return;
+    }
+    try {
+      const state = runtime.runSync(moduleRuntime.getState);
+      const next = selectorReadQuery.select(state);
+      if (currentValue === void 0 || !equalsValue(selectorReadQuery, currentValue, next)) {
+        currentValue = next;
+        scheduleNotify("normal");
+      }
+    } catch {
+    }
+  };
+  const getSnapshot = () => {
+    if (currentValue !== void 0) return currentValue;
+    const state = runtime.runSync(moduleRuntime.getState);
+    currentValue = selectorReadQuery.select(state);
+    return currentValue;
+  };
+  const subscribe = (listener) => {
+    listeners.add(listener);
+    ensureSubscription();
+    refreshSnapshotIfStale();
+    return () => {
+      listeners.delete(listener);
+      if (listeners.size > 0) return;
+      const running = fiber;
+      if (!running) return;
+      fiber = void 0;
+      cancelLow();
+      runtime.runFork(Fiber2.interrupt(running));
+    };
+  };
+  const store = { getSnapshot, subscribe };
+  bySelector.set(selectorReadQuery.selectorId, store);
+  return store;
+};
+
+// src/internal/hooks/useSelector.ts
+function useSelector(handle, selector, equalityFn) {
+  const runtimeContext = useContext3(RuntimeContext);
+  if (!runtimeContext) {
+    throw new RuntimeProviderNotFoundError("useSelector");
+  }
+  const runtime = runtimeContext.runtime;
+  const moduleRuntime = useModuleRuntime(handle);
+  const actualSelector = selector ?? ((state) => state);
+  const selectorReadQuery = useMemo3(
+    () => typeof selector === "function" ? Logix2.ReadQuery.compile(selector) : void 0,
+    [selector]
+  );
+  const actualEqualityFn = useMemo3(() => {
+    if (typeof equalityFn === "function") return equalityFn;
+    if (typeof selector !== "function") return Object.is;
+    return selectorReadQuery?.equalsKind === "shallowStruct" ? shallow : Object.is;
+  }, [equalityFn, selector, selectorReadQuery?.equalsKind]);
+  const useStaticLane = typeof selector === "function" && selectorReadQuery?.lane === "static";
+  const store = useMemo3(
+    () => useStaticLane && selectorReadQuery ? getModuleRuntimeSelectorExternalStore(
+      runtime,
+      moduleRuntime,
+      selectorReadQuery,
+      {
+        lowPriorityDelayMs: runtimeContext.reactConfigSnapshot.lowPriorityDelayMs,
+        lowPriorityMaxDelayMs: runtimeContext.reactConfigSnapshot.lowPriorityMaxDelayMs
+      }
+    ) : getModuleRuntimeExternalStore(
+      runtime,
+      moduleRuntime,
+      {
+        lowPriorityDelayMs: runtimeContext.reactConfigSnapshot.lowPriorityDelayMs,
+        lowPriorityMaxDelayMs: runtimeContext.reactConfigSnapshot.lowPriorityMaxDelayMs
+      }
+    ),
+    [
+      moduleRuntime,
+      runtime,
+      runtimeContext.reactConfigSnapshot.lowPriorityDelayMs,
+      runtimeContext.reactConfigSnapshot.lowPriorityMaxDelayMs,
+      selectorReadQuery,
+      useStaticLane
+    ]
+  );
+  const selected = useSyncExternalStoreWithSelector(
+    store.subscribe,
+    store.getSnapshot,
+    store.getSnapshot,
+    useStaticLane ? (snapshot) => snapshot : (snapshot) => actualSelector(snapshot),
+    actualEqualityFn
+  );
+  useEffect3(() => {
+    if (!isDevEnv() && !Logix2.Debug.isDevtoolsEnabled()) {
+      return;
+    }
+    const instanceId = moduleRuntime.instanceId;
+    let fieldPaths;
+    let selectorKey;
+    if (typeof selector === "function") {
+      const meta = selector;
+      const rawFieldPaths = meta.fieldPaths;
+      if (Array.isArray(rawFieldPaths)) {
+        const paths = rawFieldPaths.filter((p) => typeof p === "string");
+        fieldPaths = paths.length > 0 ? paths.slice() : void 0;
+      }
+      const rawDebugKey = meta.debugKey;
+      selectorKey = typeof rawDebugKey === "string" && rawDebugKey.length > 0 ? rawDebugKey : typeof selector.name === "string" && selector.name.length > 0 ? selector.name : void 0;
+    }
+    const effect = Logix2.Debug.record({
+      type: "trace:react-selector",
+      moduleId: moduleRuntime.moduleId,
+      instanceId,
+      data: {
+        componentLabel: "useSelector",
+        selectorKey,
+        fieldPaths,
+        selectorId: selectorReadQuery?.selectorId,
+        lane: selectorReadQuery?.lane,
+        producer: selectorReadQuery?.producer,
+        fallbackReason: selectorReadQuery?.fallbackReason,
+        readsDigest: selectorReadQuery?.readsDigest,
+        equalsKind: selectorReadQuery?.equalsKind,
+        strictModePhase: "commit"
+      }
+    });
+    runtime.runFork(effect);
+  }, [runtime, moduleRuntime, selector, selected, selectorReadQuery]);
+  return selected;
+}
+
+// src/internal/hooks/useModule.ts
+import React2 from "react";
+import * as Logix4 from "@logixjs/core";
+import { Context, Effect as Effect4, Layer as Layer2 } from "effect";
+
+// src/internal/store/resolveImportedModuleRef.ts
+import * as Logix3 from "@logixjs/core";
+var getOrCreateWeakMap = (map, key, make) => {
+  const cached = map.get(key);
+  if (cached) return cached;
+  const next = make();
+  map.set(key, next);
+  return next;
+};
+var cacheByRuntime = /* @__PURE__ */ new WeakMap();
+var resolveImportedModuleRef = (runtime, parentRuntime, module) => {
+  const byParent = getOrCreateWeakMap(
+    cacheByRuntime,
+    runtime,
+    () => /* @__PURE__ */ new WeakMap()
+  );
+  const byModule = getOrCreateWeakMap(
+    byParent,
+    parentRuntime,
+    () => /* @__PURE__ */ new WeakMap()
+  );
+  const cached = byModule.get(module);
+  if (cached) {
+    return cached;
+  }
+  const importsScope = Logix3.InternalContracts.getImportsScope(parentRuntime);
+  const childRuntime = importsScope.get(module);
+  if (childRuntime) {
+    const dispatch = Object.assign(
+      (action) => {
+        runtime.runFork(childRuntime.dispatch(action));
+      },
+      {
+        batch: (actions2) => {
+          runtime.runFork(
+            childRuntime.dispatchBatch(
+              actions2
+            )
+          );
+        },
+        lowPriority: (action) => {
+          runtime.runFork(
+            childRuntime.dispatchLowPriority(action)
+          );
+        }
+      }
+    );
+    const actions = makeModuleActions(dispatch);
+    const dispatchers = makeModuleDispatchers(dispatch, module.actions);
+    const ref = {
+      def: module,
+      runtime: childRuntime,
+      dispatch,
+      actions,
+      dispatchers,
+      imports: {
+        get: (m) => resolveImportedModuleRef(runtime, childRuntime, m)
+      },
+      getState: childRuntime.getState,
+      setState: childRuntime.setState,
+      actions$: childRuntime.actions$,
+      changes: childRuntime.changes,
+      ref: childRuntime.ref
+    };
+    byModule.set(module, ref);
+    return ref;
+  }
+  const parentId = parentRuntime.moduleId;
+  const tokenId = String(module.id);
+  const parentInstanceId = parentRuntime.instanceId;
+  const fix = isDevEnv() ? [
+    "- Ensure the child is imported in the same scope.",
+    `  Example: ${parentId}.implement({ imports: [${tokenId}.impl], ... })`,
+    "- Ensure parentRuntime is an instance scope (not a ModuleTag singleton).",
+    "  Example: useModule(ParentImpl, { key }) / useModule(ParentImpl) / useLocalModule(ParentModule, ...)",
+    "- If you intentionally want a singleton (not an imported child), use useModule(Child.tag) (ModuleTag) in the current React runtime environment.",
+    "- If you intentionally want the root provider singleton (ignore RuntimeProvider.layer overrides), use runtime.runSync(Root.resolve(Child.tag))."
+  ] : [];
+  const err = new Error(
+    isDevEnv() ? [
+      "[MissingImportedModuleError] Cannot resolve imported module from parent imports scope.",
+      "",
+      `tokenId: ${tokenId}`,
+      "entrypoint: react.useImportedModule/imports.get",
+      "mode: strict",
+      `startScope: moduleId=${parentId}, instanceId=${parentInstanceId}`,
+      "",
+      "fix:",
+      ...fix
+    ].join("\n") : "[MissingImportedModuleError] imported module runtime not found"
+  );
+  err.tokenId = tokenId;
+  err.entrypoint = "react.useImportedModule/imports.get";
+  err.mode = "strict";
+  err.startScope = {
+    moduleId: parentId,
+    instanceId: parentInstanceId
+  };
+  err.fix = fix;
+  err.name = "MissingImportedModuleError";
+  throw err;
+};
+
+// src/internal/hooks/useStableId.ts
+import React from "react";
+var useStableId = () => {
+  return React.useId();
+};
+
+// src/internal/hooks/useModule.ts
+var isModuleImpl = (handle) => Boolean(handle) && typeof handle === "object" && handle._tag === "ModuleImpl";
+var isModule = (handle) => Logix4.Module.hasImpl(handle);
+var isModuleDef = (handle) => Logix4.Module.is(handle) && handle._kind === "ModuleDef";
+function useModule(handle, selectorOrOptions, equalityFn) {
+  const runtimeBase = useRuntime();
+  const runtimeContext = React2.useContext(RuntimeContext);
+  if (!runtimeContext) {
+    throw new RuntimeProviderNotFoundError("useModule");
+  }
+  const normalizedHandle = isModule(handle) ? handle.impl : isModuleDef(handle) ? handle.tag : handle;
+  let selector;
+  let options;
+  if (isModuleImpl(normalizedHandle)) {
+    if (typeof selectorOrOptions === "function") {
+      selector = selectorOrOptions;
+    } else if (selectorOrOptions && typeof selectorOrOptions === "object") {
+      options = selectorOrOptions;
+    }
+  } else {
+    if (typeof selectorOrOptions === "function" || selectorOrOptions === void 0) {
+      selector = selectorOrOptions;
+    } else if (selectorOrOptions && typeof selectorOrOptions === "object") {
+      throw new Error("useModule(handle, options) \u4EC5\u652F\u6301 ModuleImpl \u53E5\u67C4");
+    }
+  }
+  let runtime;
+  if (isModuleImpl(normalizedHandle)) {
+    const cache = React2.useMemo(
+      () => getModuleCache(runtimeBase, runtimeContext.reactConfigSnapshot, runtimeContext.configVersion),
+      [runtimeBase, runtimeContext.reactConfigSnapshot, runtimeContext.configVersion]
+    );
+    const deps = options?.deps ?? [];
+    const depsHash = stableHash(deps);
+    const explicitSuspend = options?.suspend === true;
+    const suspend = explicitSuspend || options?.suspend !== false && runtimeContext.policy.moduleImplMode === "suspend";
+    const gcTime = options?.gcTime ?? runtimeContext.reactConfigSnapshot.gcTime;
+    let initTimeoutMs = suspend ? options?.initTimeoutMs : void 0;
+    if (suspend && initTimeoutMs === void 0) {
+      initTimeoutMs = runtimeContext.reactConfigSnapshot.initTimeoutMs;
+    }
+    if (explicitSuspend && (!options || !options.key)) {
+      if (isDevEnv()) {
+        throw new Error(
+          "[useModule] suspend:true \u6A21\u5F0F\u5FC5\u987B\u663E\u5F0F\u63D0\u4F9B options.key\uFF1B\u8BF7\u5728 Suspense \u8FB9\u754C\u5916\u751F\u6210\u7A33\u5B9A ID\uFF08\u4F8B\u5982 useId() \u6216\u4E1A\u52A1 id\uFF09\uFF0C\u5E76\u5728 useModule(Impl, { suspend: true, key }) \u4E2D\u4F20\u5165\u8BE5\u503C\u3002"
+        );
+      }
+    }
+    const componentId = useStableId();
+    const moduleId = normalizedHandle.module.id ?? "ModuleImpl";
+    const preloadKey = runtimeContext.policy.preload?.keysByModuleId.get(moduleId);
+    const baseKey = preloadKey ?? options?.key ?? (suspend ? `impl:${moduleId}` : `impl:${moduleId}:${componentId}`);
+    const key = depsHash ? `${baseKey}:${depsHash}` : baseKey;
+    const ownerId = moduleId;
+    const baseFactory = React2.useMemo(
+      () => (scope) => Layer2.buildWithScope(normalizedHandle.layer, scope).pipe(
+        Effect4.map(
+          (context) => Context.get(context, normalizedHandle.module)
+        )
+      ),
+      [normalizedHandle]
+    );
+    const factory = React2.useMemo(() => {
+      if (!suspend || initTimeoutMs === void 0) {
+        return baseFactory;
+      }
+      return (scope) => baseFactory(scope).pipe(
+        Effect4.timeoutFail({
+          duration: initTimeoutMs,
+          onTimeout: () => new Error(`[useModule] Module "${ownerId}" initialization timed out after ${initTimeoutMs}ms`)
+        })
+      );
+    }, [baseFactory, suspend, initTimeoutMs, ownerId]);
+    const moduleRuntime = suspend ? cache.read(key, factory, gcTime, ownerId, {
+      entrypoint: "react.useModule",
+      policyMode: runtimeContext.policy.mode,
+      yield: runtimeContext.policy.yield
+    }) : cache.readSync(key, factory, gcTime, ownerId, {
+      entrypoint: "react.useModule",
+      policyMode: runtimeContext.policy.mode,
+      warnSyncBlockingThresholdMs: 5
+    });
+    React2.useEffect(() => cache.retain(key), [cache, key]);
+    runtime = moduleRuntime;
+  } else {
+    runtime = useModuleRuntime(normalizedHandle);
+  }
+  React2.useEffect(() => {
+    if (!isModuleImpl(normalizedHandle)) {
+      return;
+    }
+    const opt = options;
+    const label = opt && "label" in opt && opt.label || opt && opt.key;
+    if (!label) {
+      return;
+    }
+    const effect = Logix4.Debug.record({
+      type: "trace:instanceLabel",
+      moduleId: normalizedHandle.module.id,
+      instanceId: runtime.instanceId,
+      data: { label }
+    });
+    runtimeBase.runFork(effect);
+  }, [runtimeBase, runtime, normalizedHandle, options]);
+  React2.useEffect(() => {
+    if (!isDevEnv() && !Logix4.Debug.isDevtoolsEnabled()) {
+      return;
+    }
+    if (!runtime.instanceId) {
+      return;
+    }
+    const effect = Logix4.Debug.record({
+      type: "trace:react-render",
+      moduleId: runtime.moduleId,
+      instanceId: runtime.instanceId,
+      data: {
+        componentLabel: "useModule",
+        strictModePhase: "commit"
+      }
+    });
+    runtimeBase.runFork(effect);
+  }, [runtimeBase, runtime]);
+  if (selector) {
+    if (isModuleImpl(normalizedHandle)) {
+      return useSelector(runtime, selector, equalityFn);
+    }
+    return useSelector(normalizedHandle, selector, equalityFn);
+  }
+  const def = React2.useMemo(() => {
+    if (isModule(handle) || isModuleDef(handle)) {
+      return handle;
+    }
+    if (isModuleRef(handle)) {
+      return handle.def;
+    }
+    if (isModuleImpl(handle)) {
+      return handle.module;
+    }
+    if (handle && (typeof handle === "object" || typeof handle === "function") && handle._kind === "ModuleTag") {
+      return handle;
+    }
+    if (isModuleImpl(normalizedHandle)) {
+      return normalizedHandle.module;
+    }
+    if (isModuleRef(normalizedHandle)) {
+      return normalizedHandle.def;
+    }
+    if (normalizedHandle && (typeof normalizedHandle === "object" || typeof normalizedHandle === "function") && normalizedHandle._kind === "ModuleTag") {
+      return normalizedHandle;
+    }
+    return void 0;
+  }, [handle, normalizedHandle]);
+  const tokens = React2.useMemo(() => {
+    if (!def || typeof def !== "object" && typeof def !== "function") {
+      return void 0;
+    }
+    const candidate = def;
+    if (!candidate.actions || typeof candidate.actions !== "object") {
+      return void 0;
+    }
+    return candidate.actions;
+  }, [def]);
+  const dispatch = React2.useMemo(() => {
+    const base = (action) => {
+      runtimeBase.runFork(runtime.dispatch(action));
+    };
+    return Object.assign(base, {
+      batch: (actions2) => {
+        runtimeBase.runFork(runtime.dispatchBatch(actions2));
+      },
+      lowPriority: (action) => {
+        runtimeBase.runFork(runtime.dispatchLowPriority(action));
+      }
+    });
+  }, [runtimeBase, runtime]);
+  const extendTag = React2.useMemo(() => {
+    if (isModuleImpl(normalizedHandle)) {
+      return normalizedHandle.module;
+    }
+    return normalizedHandle;
+  }, [normalizedHandle]);
+  const actions = React2.useMemo(() => makeModuleActions(dispatch), [dispatch]);
+  const dispatchers = React2.useMemo(
+    () => tokens ? makeModuleDispatchers(dispatch, tokens) : makeModuleDispatchers(dispatch),
+    [dispatch, tokens]
+  );
+  return React2.useMemo(() => {
+    const base = {
+      def,
+      runtime,
+      dispatch,
+      actions,
+      dispatchers,
+      imports: {
+        get: (module) => resolveImportedModuleRef(runtimeBase, runtime, module)
+      },
+      getState: runtime.getState,
+      setState: runtime.setState,
+      actions$: runtime.actions$,
+      changes: runtime.changes,
+      ref: runtime.ref
+    };
+    return applyHandleExtend(extendTag, runtime, base);
+  }, [runtimeBase, runtime, dispatch, actions, dispatchers, extendTag, def]);
+}
+
+export {
+  RuntimeProviderNotFoundError,
+  useRuntime,
+  makeModuleActions,
+  makeModuleDispatchers,
+  useModuleRuntime,
+  shallow,
+  useSelector,
+  resolveImportedModuleRef,
+  useStableId,
+  useModule
+};