@slux/ripple 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# @slux/ripple
+
+## 0.1.0
+
+### Minor Changes
+
+- 首次公开发布 slux 的 25 个包，统一版本为 0.1.0。
+
+  - 提供框架无关的响应式核心与共享工具，以及 Store、Atom、Proxy、Flux、状态机和 RxJS 六种状态组织方式。
+  - 提供持久化、历史记录、跨标签页同步、遥测和开发工具五类 Store 扩展。
+  - 提供 React、Vue、Solid、Svelte、Angular、Preact、Ripple、Inferno、Octane、Vitarx、ActView 和 Viewfly 绑定。
+  - 提供各包文档与对应示例，并接入发布检查和文档部署工作流。
+
+### Patch Changes
+
+- Updated dependencies
+  - @slux/atom@0.1.0
+  - @slux/core@0.1.0
+  - @slux/flux@0.1.0
+  - @slux/proxy@0.1.0
+  - @slux/rxjs@0.1.0
+  - @slux/shared@0.1.0
+  - @slux/state-machine@0.1.0
+  - @slux/store@0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 itmanyong
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,187 @@
-# Temporary Holding Version
+# @slux/ripple
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Ripple（`ripple@^0.6.1`）的 slux 绑定，基于 `@slux/core` 的 `Subscribable<T>` 订阅模型。原生绑定形式是 **Ripple 原生 `track` / `effect`**：所有绑定返回 `Derived<T>`，以 **`.value` 读取**。`.` 入口按 `browser` / `default` 条件分流到客户端与服务端实现。所有写入仍走原实例，绑定只读。
+
+## 特性与适用场景
+
+| 项       | 说明                                                                                |
+| -------- | ----------------------------------------------------------------------------------- |
+| 绑定形式 | `useSignal(source)` 及六个子入口返回 `Derived<T>`，以 `.value` 读取                 |
+| 框架依赖 | `ripple` 的 `track`、`effect`、`Context`；服务端用 `ripple/server` 的 `render`      |
+| 范式覆盖 | core 主入口 + atom / store / proxy / flux / state-machine / rxjs 六个子入口         |
+| SSR      | `default` 条件 / `@slux/ripple/server` 提供不订阅的服务端 `useSignal`，读显式 Scope |
+
+| 场景                                              | 是否适合 | 说明                                                  |
+| ------------------------------------------------- | -------- | ----------------------------------------------------- |
+| 在 Ripple 编译组件里读 core `signal` / `computed` | 适合     | 订阅内 core `effect` 主动刷新惰性 computed            |
+| 用 atom / store / proxy 或新增三种范式            | 适合     | 各子入口返回 `Derived`，范式包按需安装                |
+| SSR 首屏读取 Scope 覆盖值                         | 适合     | 服务端 `useSignal` 读 `scope.get(source)`，不建立订阅 |
+| 需要绑定替你写入状态                              | 不适合   | `Derived<T>` 只读，写入走 `set` / `dispatch` / `send` |
+| 需要 CJS 消费                                     | 不适合   | 本包只发布 ESM                                        |
+| 未接入 Ripple 编译器                              | 不适合   | 组件 JSX 与 `.value` 读取需消费端编译器处理           |
+
+## 安装
+
+```sh
+pnpm add @slux/core @slux/ripple ripple@^0.6.1
+```
+
+- **必需 peer**：`@slux/core`（`workspace:^`）、`ripple@^0.6.1`。
+- **可选 peer（范式包）**：`@slux/atom`、`@slux/store`、`@slux/proxy`、`@slux/flux`、`@slux/state-machine`、`@slux/rxjs` 均为 `optional`，**只装实际使用的子入口**。
+- `@slux/shared` 是本包运行时依赖，安装时自动带入。
+- 本包只发布 ESM：`exports` 没有 `require` 条件，也没有 `.d.cts`；`main` 指向 `dist/server.js`，`module` 指向 `dist/index.js`。
+- 消费端组件（JSX 与 `.value` 读取）需按 Ripple 官方要求接入编译器，本包不内置编译器。
+
+`package.json` 的 `exports` 子入口（逐个列出）：
+
+| 子路径                       | 条件 / 产物                                                                   | 导出内容                                                                               |
+| ---------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `@slux/ripple`               | `browser` → `dist/index.js`（客户端）；`default` → `dist/server.js`（服务端） | `ScopeContext`、`provideScope`、`useScopeContext`、`useSignal`、`createAutoImportApis` |
+| `@slux/ripple/server`        | `default` → `dist/server.js`                                                  | `ScopeContext`、`provideScope`、`useScopeContext`、服务端 `useSignal`                  |
+| `@slux/ripple/atom`          | `default` → `dist/atom.js`                                                    | `useAtomValue`、`useSetAtom`、`useAtom`                                                |
+| `@slux/ripple/store`         | `default` → `dist/store.js`                                                   | `useStore`                                                                             |
+| `@slux/ripple/proxy`         | `default` → `dist/proxy.js`                                                   | `useSnapshot`                                                                          |
+| `@slux/ripple/flux`          | `default` → `dist/flux.js`                                                    | `useFluxStore`                                                                         |
+| `@slux/ripple/state-machine` | `default` → `dist/state-machine.js`                                           | `useMachine`                                                                           |
+| `@slux/ripple/rxjs`          | `default` → `dist/rxjs.js`                                                    | `useObservable`                                                                        |
+| `@slux/ripple/package.json`  | 包元数据（非 API）                                                            | —                                                                                      |
+
+## 快速开始
+
+```tsx
+import { signal } from "@slux/core";
+import { useSignal } from "@slux/ripple";
+
+const count = signal(0);
+
+export function Counter() {
+  const value = useSignal(count);
+  return <button onClick={() => count.set((n) => n + 1)}>{value.value}</button>;
+}
+```
+
+`useSignal(count)` 返回 `Derived<number>`，模板用 `.value` 读取；点击时仍通过 core 的 `count.set(recipe)` 写入。
+
+## 主入口 API
+
+主入口的运行时导出来自 `src/index.ts`（客户端）与 `src/scope.ts`；`scope.ts` 的三个导出在客户端与服务端入口都会重新导出。
+
+| 成员                             | 签名                                         | 行为                                                                                                                                                  |
+| -------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `useSignal`（客户端）            | `<T>(source: Subscribable<T>) => Derived<T>` | 基于 `useExternal`：`track` 状态 + `effect` 建立订阅并刷新；订阅内 `source.subscribe` 与 core `effect(() => { source.get(); })` 同时驱动惰性 computed |
+| `useSignal`（服务端，`/server`） | `<T>(source: Subscribable<T>) => Derived<T>` | `track(() => (scope ? scope.get(source) : source.get()))`，**不建立订阅**                                                                             |
+| `ScopeContext`                   | `new Context<Scope \| null>(null)`           | Ripple 原生 Context，默认 `null`                                                                                                                      |
+| `provideScope`                   | `(scope: Scope) => void`                     | `ScopeContext.set(scope)`，在父组件初始化中调用                                                                                                       |
+| `useScopeContext`                | `() => Scope \| null`                        | `ScopeContext.get()`                                                                                                                                  |
+| `createAutoImportApis`           | `(prefix?: string) => ImportsMap`            | 生成 `unplugin-auto-import` 配置，见「自动导入」                                                                                                      |
+
+内部 `useExternal`（`src/external.ts`，**不由 `exports` 暴露**）是所有客户端绑定的共同机制：用 `track({ value: read() })` 包裹值（避免 Ripple `track` 把函数类型的值误当作派生计算执行），在 `effect` 内订阅、刷新并把 `unsubscribe` 作为清理返回，最后返回 `track(() => state.value.value)` 形式的 `Derived<T>`。六个子入口都基于它。
+
+服务端 `useSignal` 与 Scope 用法：
+
+```ts
+import { render } from "ripple/server";
+import { createScope, signal } from "@slux/core";
+import { provideScope, useSignal } from "@slux/ripple/server";
+
+const source = signal(1);
+const scope = createScope();
+scope.set(source, 42);
+
+const result = await render(() => {
+  provideScope(scope);
+  return String(useSignal(source).value); // 读取 Scope 覆盖值
+});
+```
+
+## 子入口 API
+
+所有子入口返回 `Derived<T>`，以 `.value` 读取；**不返回写入 tuple，也不创建副本**。
+
+### `@slux/ripple/atom`
+
+| 导出           | 签名                                                     | 返回值 / 写入                                |
+| -------------- | -------------------------------------------------------- | -------------------------------------------- |
+| `useAtomValue` | `<T>(atom: AnyReadableAtom<T>) => Derived<T>`            | 只读派生值，支持只读派生 atom                |
+| `useSetAtom`   | `<T>(atom: Atom<T>) => (value: T) => void`               | setter；按 atom 替换契约写值，函数值不被执行 |
+| `useAtom`      | `<T>(atom: Atom<T>) => [Derived<T>, (value: T) => void]` | `[只读派生值, setter]`                       |
+
+### `@slux/ripple/store`
+
+`useStore` 有两个重载：
+
+| 调用                                     | 返回值                       |
+| ---------------------------------------- | ---------------------------- |
+| `useStore(store)`                        | `Derived<State>`（完整状态） |
+| `useStore(store, selector, equalityFn?)` | `Derived<Selection>`（选值） |
+
+`selector = (state: State) => Selection`；`equalityFn(previous, next)` 默认 `Object.is`。带 selector 时按 state 引用缓存选值，`equalityFn` 判定相等时保留旧选值引用。写入仍用 `store.setState(...)`。
+
+```tsx
+import { createStore } from "@slux/store";
+import { useStore } from "@slux/ripple/store";
+
+const store = createStore(() => ({ count: 1 }));
+
+export function Count() {
+  const count = useStore(store, (state) => state.count);
+  return <output>{count.value}</output>;
+}
+```
+
+### `@slux/ripple/proxy`
+
+| 导出          | 签名                                                   | 返回值                                        |
+| ------------- | ------------------------------------------------------ | --------------------------------------------- |
+| `useSnapshot` | `<T extends object>(proxy: T) => Derived<Snapshot<T>>` | 整个 proxy 的深只读、冻结快照，无字段访问追踪 |
+
+### 新增三种范式（只读）
+
+| 子路径                       | 导出            | 签名                                                                                                                                                        | 返回值        | 写入方式                 |
+| ---------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------ |
+| `@slux/ripple/flux`          | `useFluxStore`  | `<State, Action extends FluxAction>(store: FluxStore<State, Action>) => Derived<State>`                                                                     | Flux 完整状态 | `store.dispatch(action)` |
+| `@slux/ripple/state-machine` | `useMachine`    | `<Context, Event extends { type: string }, State extends string>(machine: StateMachine<Context, Event, State>) => Derived<MachineSnapshot<Context, State>>` | 状态机快照    | `machine.send(event)`    |
+| `@slux/ripple/rxjs`          | `useObservable` | `<T>(source: ObservableState<T>) => Derived<T>`                                                                                                             | 桥接最近值    | 桥接创建者持有上游       |
+
+三者都基于 `useExternal`：`read` 取各自实例的 `.get()`，`subscribe` 取各自实例的 `.subscribe(notify)`。
+
+## 专属语义与边界
+
+- **条件导出与 SSR**：`.` 入口的 `browser` 条件选客户端 `index.js`，`default` 条件选服务端 `server.js`；`main` 指向 `server.js`，`module` 指向 `index.js`，也可显式导入 `@slux/ripple/server`。服务端渲染时 Ripple **不执行 `effect`**，因此基于 `useExternal` 的所有子入口（以及客户端 `useSignal`）不会建立 `source.subscribe` 订阅，首值来自 `read()` 的同步求值；服务端 `useSignal` 进一步读取 `scope.get(source)` 覆盖值。子入口在服务端读各自实例的当前值，**不应用 core Scope**。
+- **客户端 Scope**：`ScopeContext` 用 Ripple 原生 `Context`；父组件初始化中 `provideScope(scope)`，后代用 `useScopeContext()` 取得。**客户端 `useSignal` 不读 Scope 覆盖值**，始终读取并跟随全局来源；覆盖值只由服务端入口的 `useSignal` 应用，或由调用方显式 `useScopeContext()?.get(source)` 读取。服务端按请求创建独立状态实例与 Scope，不自动序列化 / 恢复（通用约定见 [仓库根 README](../../README.md)）。
+- **订阅与清理**：`useExternal` 在 Ripple 原生 `effect` 内建立订阅并把 `unsubscribe` 作为清理函数返回，组件卸载时释放组件订阅；主入口 `useSignal` 额外建立 core `effect` 驱动惰性 computed。组件卸载**不销毁**业务 store / flux / machine / observable，桥接创建者负责 `dispose()`。
+- **数据源固定**：`useExternal` 的订阅在组件初始化时建立一次（Ripple `effect` 不接收依赖数组），**组件实例内数据源固定**；需要替换来源时重建该组件实例。这与用 `useCallback` / `componentDidUpdate` 可重连来源的框架绑定不同。
+- **快照相等判定**：订阅触发时 `useExternal` 重新 `read()` 并写入 `track` 状态；`useStore` 的 `equalityFn`（默认 `Object.is`）在选值相等时保留旧引用，`@slux/proxy` 的不可变快照保持未变分支引用。`external.ts` 用 `{ value: read() }` 包裹值，保证函数类型的值不被 `track` 当作派生计算执行。
+- **错误处理**：绑定层不新增错误包装；写入、通知与 `effect` 的错误行为遵循 `@slux/core`。RxJS 桥接的完成 / 错误状态由 `@slux/rxjs` 的 `status` / `error` 只读信号读取。
+- **通用约定**：跨框架的写入形式、Scope、SSR 与桥接生命周期约定见 [仓库根 README](../../README.md) 的「框架适配 · 通用约定」；仓库内验证命令见「本地开发」，本文不重复。
+
+## 自动导入
+
+```ts
+import AutoImport from "unplugin-auto-import/vite";
+import { createAutoImportApis } from "@slux/ripple";
+
+export default {
+  plugins: [AutoImport({ imports: [createAutoImportApis()] })],
+};
+```
+
+`createAutoImportApis(prefix = "")` 的登记清单以 `src/auto-import-api.ts` 的 `allImportApis` 为准，当前为 **`ScopeContext`、`provideScope`、`useScopeContext`、`useSignal`** 四项，来源名 `@slux/ripple`。传入前缀可生成别名，大写规则由 `@slux/shared` 的 `generateBatchAutoImports` 决定。清单**只含主入口运行时导出**，不含 `createAutoImportApis` 自身，也不含任何子入口导出。
+
+## 类型导出
+
+本包**没有显式 `export type`**：`Derived<T>` 与 `Context` 来自 `ripple`，`Scope` / `Subscribable<T>` 来自 `@slux/core`，`Snapshot<T>` 来自 `@slux/proxy`，其余范式类型（`AnyReadableAtom` / `Atom`、`StoreApi`、`FluxStore` / `FluxAction`、`MachineSnapshot` / `StateMachine`、`ObservableState`）都通过函数签名暴露，从各自包导入。`ScopeContext` 是 `Context<Scope | null>` 实例，其类型由 `ripple` 提供。
+
+## 不适用的场景
+
+- 需要在组件外（Node / 脚本）读写状态：用 `@slux/core`。
+- 需要绑定返回写入 tuple、selector 之外的写入接口或状态副本：返回的是只读 `Derived<T>`。
+- 需要在同一组件实例内切换数据源：数据源在初始化时固定，需重建组件实例。
+- 需要 CJS / `require` 消费：本包只发布 ESM。
+- 未接入 Ripple 编译器：组件 JSX 与 `.value` 读取无法在消费端工作。
+
+## 版本、许可与反馈
+
+- 版本：`0.1.0`（`package.json`）；许可：[MIT](../../LICENSE) © itmanyong。
+- 问题反馈：`https://github.com/itmanyong/slux/issues`。
+- 通用约定与本地开发命令见 [仓库根 README](../../README.md)。

package/dist/6.js

@@ -0,0 +1,2 @@
+import{Context as e}from"ripple";let t=new e(null);function o(e){t.set(e)}function n(){return t.get()}export{t as ScopeContext,o as provideScope,n as useScopeContext};
+//# sourceMappingURL=6.js.map

package/dist/6.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"6.js","sources":["../src/scope.ts"],"sourcesContent":["import { Context } from \"ripple\";\nimport type { Scope } from \"@slux/core\";\n\nexport const ScopeContext = new Context<Scope | null>(null);\n\nexport function provideScope(scope: Scope): void {\n  ScopeContext.set(scope);\n}\n\nexport function useScopeContext(): Scope | null {\n  return ScopeContext.get();\n}\n"],"names":["ScopeContext","Context","provideScope","scope","useScopeContext"],"mappings":"iCAGO,IAAMA,EAAe,IAAIC,EAAsB,MAE/C,SAASC,EAAaC,CAAY,EACvCH,EAAa,GAAG,CAACG,EACnB,CAEO,SAASC,IACd,OAAOJ,EAAa,GAAG,EACzB,Q"}

package/dist/atom.d.ts

@@ -0,0 +1,11 @@
+import type { AnyReadableAtom } from '@slux/atom';
+import type { Atom } from '@slux/atom';
+import type { Derived } from 'ripple';
+
+export declare function useAtom<T>(atom: Atom<T>): [Derived<T>, (value: T) => void];
+
+export declare function useAtomValue<T>(atom: AnyReadableAtom<T>): Derived<T>;
+
+export declare function useSetAtom<T>(atom: Atom<T>): (value: T) => void;
+
+export { }

package/dist/atom.js

@@ -0,0 +1,2 @@
+import{useExternal as t}from"./t.js";function e(t){return[u(t),r(t)]}function u(e){return t(()=>e.get(),t=>e.subscribe(t))}function r(t){return e=>t.set(e)}export{e as useAtom,u as useAtomValue,r as useSetAtom};
+//# sourceMappingURL=atom.js.map

package/dist/atom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"atom.js","sources":["../src/atom.ts"],"sourcesContent":["import type { Atom, AnyReadableAtom } from \"@slux/atom\";\nimport type { Derived } from \"ripple\";\nimport { useExternal } from \"./external.js\";\n\nexport function useAtom<T>(atom: Atom<T>): [Derived<T>, (value: T) => void] {\n  return [useAtomValue(atom), useSetAtom(atom)];\n}\n\nexport function useAtomValue<T>(atom: AnyReadableAtom<T>): Derived<T> {\n  return useExternal(\n    () => atom.get(),\n    (notify) => atom.subscribe(notify),\n  );\n}\n\nexport function useSetAtom<T>(atom: Atom<T>): (value: T) => void {\n  return (value) => atom.set(value);\n}\n"],"names":["useAtom","atom","useAtomValue","useSetAtom","useExternal","notify","value"],"mappings":"mDAIO,SAASA,EAAWC,CAAa,EACtC,MAAO,CAACC,EAAaD,GAAOE,EAAWF,GAAM,AAC/C,CAEO,SAASC,EAAgBD,CAAwB,EACtD,OAAOG,EACL,IAAMH,EAAK,GAAG,GACd,AAACI,GAAWJ,EAAK,SAAS,CAACI,GAE/B,CAEO,SAASF,EAAcF,CAAa,EACzC,OAAO,AAACK,GAAUL,EAAK,GAAG,CAACK,EAC7B,Q"}

package/dist/flux.d.ts

@@ -0,0 +1,7 @@
+import type { Derived } from 'ripple';
+import type { FluxAction } from '@slux/flux';
+import type { FluxStore } from '@slux/flux';
+
+export declare function useFluxStore<State, Action extends FluxAction>(store: FluxStore<State, Action>): Derived<State>;
+
+export { }

package/dist/flux.js

@@ -0,0 +1,2 @@
+import{useExternal as r}from"./t.js";function t(t){return r(()=>t.get(),r=>t.subscribe(r))}export{t as useFluxStore};
+//# sourceMappingURL=flux.js.map

package/dist/flux.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flux.js","sources":["../src/flux.ts"],"sourcesContent":["import { useExternal } from \"./external.js\";\nimport type { FluxAction, FluxStore } from \"@slux/flux\";\nimport type { Derived } from \"ripple\";\n\nexport function useFluxStore<State, Action extends FluxAction>(store: FluxStore<State, Action>): Derived<State> {\n  return useExternal(\n    () => store.get(),\n    (notify) => store.subscribe(notify),\n  );\n}\n"],"names":["useFluxStore","store","useExternal","notify"],"mappings":"mDAIO,SAASA,EAA+CC,CAA+B,EAC5F,OAAOC,EACL,IAAMD,EAAM,GAAG,GACf,AAACE,GAAWF,EAAM,SAAS,CAACE,GAEhC,Q"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+import { Context } from 'ripple';
+import type { Derived } from 'ripple';
+import type { Scope } from '@slux/core';
+import type { Subscribable } from '@slux/core';
+
+export declare const createAutoImportApis: (prefix?: string) => {
+    [x: string]: (string | [string, string])[];
+};
+
+export declare function provideScope(scope: Scope): void;
+
+export declare const ScopeContext: Context<Scope | null>;
+
+export declare function useScopeContext(): Scope | null;
+
+export declare function useSignal<T>(source: Subscribable<T>): Derived<T>;
+
+export { }

package/dist/index.js

@@ -0,0 +1,2 @@
+import{effect as e}from"@slux/core";import{generateBatchAutoImports as o}from"@slux/shared";import{useExternal as t}from"./t.js";let r=["ScopeContext","provideScope","useScopeContext","useSignal"],p=(e="")=>o([{prefix:e,fromName:"@slux/ripple",imports:r}]);function i(o){return t(()=>o.get(),t=>{let r=o.subscribe(t),p=e(()=>{o.get()});return()=>{r(),p()}})}export{ScopeContext,provideScope,useScopeContext}from"./6.js";export{p as createAutoImportApis,i as useSignal};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/auto-import-api.ts","../src/index.ts"],"sourcesContent":["import { generateBatchAutoImports } from \"@slux/shared\";\n\nconst allImportApis: string[] = [\"ScopeContext\", \"provideScope\", \"useScopeContext\", \"useSignal\"];\n\nexport const createAutoImportApis = (prefix: string = \"\") => {\n  return generateBatchAutoImports([\n    {\n      prefix,\n      fromName: \"@slux/ripple\",\n      imports: allImportApis,\n    },\n  ]);\n};\n","import { effect } from \"@slux/core\";\nimport type { Subscribable } from \"@slux/core\";\nimport type { Derived } from \"ripple\";\nimport { useExternal } from \"./external.js\";\n\nexport { ScopeContext, provideScope, useScopeContext } from \"./scope.js\";\n\nexport function useSignal<T>(source: Subscribable<T>): Derived<T> {\n  return useExternal(\n    () => source.get(),\n    (notify) => {\n      const unsubscribe = source.subscribe(notify);\n      // computed 需要活跃读取才能向订阅者发布最新值。\n      const dispose = effect(() => {\n        source.get();\n      });\n      return () => {\n        unsubscribe();\n        dispose();\n      };\n    },\n  );\n}\nexport { createAutoImportApis } from \"./auto-import-api.js\";\n"],"names":["allImportApis","createAutoImportApis","prefix","generateBatchAutoImports","useSignal","source","useExternal","notify","unsubscribe","dispose","effect"],"mappings":"+IAEA,IAAMA,EAA0B,CAAC,eAAgB,eAAgB,kBAAmB,YAAY,CAEnFC,EAAuB,CAACC,EAAiB,EAAE,GAC/CC,EAAyB,CAC9B,CACED,OAAAA,EACA,SAAU,eACV,QAASF,CACX,EACD,ECJI,SAASI,EAAaC,CAAuB,EAClD,OAAOC,EACL,IAAMD,EAAO,GAAG,GAChB,AAACE,IACC,IAAMC,EAAcH,EAAO,SAAS,CAACE,GAE/BE,EAAUC,EAAO,KACrBL,EAAO,GAAG,EACZ,GACA,MAAO,KACLG,IACAC,GACF,CACF,EAEJ,C"}

package/dist/proxy.d.ts

@@ -0,0 +1,6 @@
+import type { Derived } from 'ripple';
+import type { Snapshot } from '@slux/proxy';
+
+export declare function useSnapshot<T extends object>(proxy: T): Derived<Snapshot<T>>;
+
+export { }

package/dist/proxy.js

@@ -0,0 +1,2 @@
+import{snapshot as o,subscribe as r}from"@slux/proxy";import{useExternal as t}from"./t.js";function p(p){return t(()=>o(p),o=>r(p,o))}export{p as useSnapshot};
+//# sourceMappingURL=proxy.js.map

package/dist/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sources":["../src/proxy.ts"],"sourcesContent":["import { snapshot, subscribe } from \"@slux/proxy\";\nimport type { Snapshot } from \"@slux/proxy\";\nimport type { Derived } from \"ripple\";\nimport { useExternal } from \"./external.js\";\n\nexport function useSnapshot<T extends object>(proxy: T): Derived<Snapshot<T>> {\n  return useExternal(\n    () => snapshot(proxy),\n    (notify) => subscribe(proxy, notify),\n  );\n}\n"],"names":["useSnapshot","proxy","useExternal","snapshot","notify","subscribe"],"mappings":"yGAKO,SAASA,EAA8BC,CAAQ,EACpD,OAAOC,EACL,IAAMC,EAASF,GACf,AAACG,GAAWC,EAAUJ,EAAOG,GAEjC,Q"}

package/dist/rxjs.d.ts

@@ -0,0 +1,6 @@
+import type { Derived } from 'ripple';
+import type { ObservableState } from '@slux/rxjs';
+
+export declare function useObservable<T>(source: ObservableState<T>): Derived<T>;
+
+export { }

package/dist/rxjs.js

@@ -0,0 +1,2 @@
+import{useExternal as e}from"./t.js";function r(r){return e(()=>r.get(),e=>r.subscribe(e))}export{r as useObservable};
+//# sourceMappingURL=rxjs.js.map

package/dist/rxjs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rxjs.js","sources":["../src/rxjs.ts"],"sourcesContent":["import { useExternal } from \"./external.js\";\nimport type { ObservableState } from \"@slux/rxjs\";\nimport type { Derived } from \"ripple\";\n\nexport function useObservable<T>(source: ObservableState<T>): Derived<T> {\n  return useExternal(\n    () => source.get(),\n    (notify) => source.subscribe(notify),\n  );\n}\n"],"names":["useObservable","source","useExternal","notify"],"mappings":"mDAIO,SAASA,EAAiBC,CAA0B,EACzD,OAAOC,EACL,IAAMD,EAAO,GAAG,GAChB,AAACE,GAAWF,EAAO,SAAS,CAACE,GAEjC,Q"}

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+import { Context } from 'ripple';
+import type { Derived } from 'ripple';
+import type { Scope } from '@slux/core';
+import type { Subscribable } from '@slux/core';
+
+export declare function provideScope(scope: Scope): void;
+
+export declare const ScopeContext: Context<Scope | null>;
+
+export declare function useScopeContext(): Scope | null;
+
+/** 在 Ripple 服务端组件初始化中读取显式 Scope，不创建订阅。 */
+export declare function useSignal<T>(source: Subscribable<T>): Derived<T>;
+
+export { }

package/dist/server.js

@@ -0,0 +1,2 @@
+import{track as e}from"ripple";import{useScopeContext as o}from"./6.js";function t(t){let r=o();return e(()=>r?r.get(t):t.get())}export{ScopeContext,provideScope,useScopeContext}from"./6.js";export{t as useSignal};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sources":["../src/server.ts"],"sourcesContent":["import { track } from \"ripple\";\nimport type { Derived } from \"ripple\";\nimport type { Subscribable } from \"@slux/core\";\nimport { useScopeContext } from \"./scope.js\";\n\nexport { ScopeContext, provideScope, useScopeContext } from \"./scope.js\";\n\n/** 在 Ripple 服务端组件初始化中读取显式 Scope，不创建订阅。 */\nexport function useSignal<T>(source: Subscribable<T>): Derived<T> {\n  const scope = useScopeContext();\n  return track(() => (scope ? scope.get(source) : source.get()));\n}\n"],"names":["useSignal","source","scope","useScopeContext","track"],"mappings":"sFAQO,SAASA,EAAaC,CAAuB,EAClD,IAAMC,EAAQC,IACd,OAAOC,EAAM,IAAOF,EAAQA,EAAM,GAAG,CAACD,GAAUA,EAAO,GAAG,GAC5D,C"}

package/dist/state-machine.d.ts

@@ -0,0 +1,9 @@
+import type { Derived } from 'ripple';
+import type { MachineSnapshot } from '@slux/state-machine';
+import type { StateMachine } from '@slux/state-machine';
+
+export declare function useMachine<Context, Event extends {
+    type: string;
+}, State extends string>(machine: StateMachine<Context, Event, State>): Derived<MachineSnapshot<Context, State>>;
+
+export { }

package/dist/state-machine.js

@@ -0,0 +1,2 @@
+import{useExternal as e}from"./t.js";function r(r){return e(()=>r.get(),e=>r.subscribe(e))}export{r as useMachine};
+//# sourceMappingURL=state-machine.js.map

package/dist/state-machine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state-machine.js","sources":["../src/state-machine.ts"],"sourcesContent":["import { useExternal } from \"./external.js\";\nimport type { MachineSnapshot, StateMachine } from \"@slux/state-machine\";\nimport type { Derived } from \"ripple\";\n\nexport function useMachine<Context, Event extends { type: string }, State extends string>(\n  machine: StateMachine<Context, Event, State>,\n): Derived<MachineSnapshot<Context, State>> {\n  return useExternal(\n    () => machine.get(),\n    (notify) => machine.subscribe(notify),\n  );\n}\n"],"names":["useMachine","machine","useExternal","notify"],"mappings":"mDAIO,SAASA,EACdC,CAA4C,EAE5C,OAAOC,EACL,IAAMD,EAAQ,GAAG,GACjB,AAACE,GAAWF,EAAQ,SAAS,CAACE,GAElC,Q"}

package/dist/store.d.ts

@@ -0,0 +1,8 @@
+import type { Derived } from 'ripple';
+import type { StoreApi } from '@slux/store';
+
+export declare function useStore<State extends object>(store: StoreApi<State>): Derived<State>;
+
+export declare function useStore<State extends object, Selection>(store: StoreApi<State>, selector: (state: State) => Selection, equalityFn?: (previous: Selection, next: Selection) => boolean): Derived<Selection>;
+
+export { }

package/dist/store.js

@@ -0,0 +1,2 @@
+import{useExternal as e}from"./t.js";function t(r,i,n=Object.is){let s;return e(()=>{let e=r.getState();if(!i)return e;if(s&&Object.is(s.state,e))return s.selection;let t=i(e),o=s&&n(s.selection,t)?s.selection:t;return s={state:e,selection:o},o},e=>r.subscribe(e))}export{t as useStore};
+//# sourceMappingURL=store.js.map

package/dist/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sources":["../src/store.ts"],"sourcesContent":["import type { StoreApi } from \"@slux/store\";\nimport type { Derived } from \"ripple\";\nimport { useExternal } from \"./external.js\";\n\nexport function useStore<State extends object>(store: StoreApi<State>): Derived<State>;\nexport function useStore<State extends object, Selection>(\n  store: StoreApi<State>,\n  selector: (state: State) => Selection,\n  equalityFn?: (previous: Selection, next: Selection) => boolean,\n): Derived<Selection>;\nexport function useStore<State extends object, Selection>(\n  store: StoreApi<State>,\n  selector?: (state: State) => Selection,\n  equalityFn: (previous: Selection, next: Selection) => boolean = Object.is,\n): Derived<State | Selection> {\n  let cache: { state: State; selection: Selection } | undefined;\n  return useExternal(\n    () => {\n      const state = store.getState();\n      if (!selector) return state;\n      if (cache && Object.is(cache.state, state)) return cache.selection;\n      const next = selector(state);\n      const selection = cache && equalityFn(cache.selection, next) ? cache.selection : next;\n      cache = { state, selection };\n      return selection;\n    },\n    (notify) => store.subscribe(notify),\n  );\n}\n"],"names":["useStore","store","selector","equalityFn","Object","cache","useExternal","state","next","selection","notify"],"mappings":"mDAUO,SAASA,EACdC,CAAsB,CACtBC,CAAsC,CACtCC,EAAgEC,OAAO,EAAE,EAEzE,IAAIC,EACJ,OAAOC,EACL,KACE,IAAMC,EAAQN,EAAM,QAAQ,GAC5B,GAAI,CAACC,EAAU,OAAOK,EACtB,GAAIF,GAASD,OAAO,EAAE,CAACC,EAAM,KAAK,CAAEE,GAAQ,OAAOF,EAAM,SAAS,CAClE,IAAMG,EAAON,EAASK,GAChBE,EAAYJ,GAASF,EAAWE,EAAM,SAAS,CAAEG,GAAQH,EAAM,SAAS,CAAGG,EAEjF,OADAH,EAAQ,CAAEE,MAAAA,EAAOE,UAAAA,CAAU,EACpBA,CACT,EACA,AAACC,GAAWT,EAAM,SAAS,CAACS,GAEhC,Q"}

package/dist/t.js

@@ -0,0 +1,2 @@
+import{effect as e,track as l}from"ripple";function r(r,u){let t=l({value:r()});return e(()=>{let e=()=>{t.value={value:r()}},l=u(e);return e(),l}),l(()=>t.value.value)}export{r as useExternal};
+//# sourceMappingURL=t.js.map

package/dist/t.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"t.js","sources":["../src/external.ts"],"sourcesContent":["import { effect, track } from \"ripple\";\nimport type { Derived } from \"ripple\";\n\nexport function useExternal<T>(read: () => T, subscribe: (notify: () => void) => () => void): Derived<T> {\n  // 包裹函数值，避免 track 将用户函数误当作派生计算执行。\n  const state = track({ value: read() });\n  effect(() => {\n    const refresh = () => {\n      state.value = { value: read() };\n    };\n    const unsubscribe = subscribe(refresh);\n    refresh();\n    return unsubscribe;\n  });\n  return track(() => state.value.value);\n}\n"],"names":["useExternal","read","subscribe","state","track","effect","refresh","unsubscribe"],"mappings":"2CAGO,SAASA,EAAeC,CAAa,CAAEC,CAA6C,EAEzF,IAAMC,EAAQC,EAAM,CAAE,MAAOH,GAAO,GASpC,OARAI,EAAO,KACL,IAAMC,EAAU,KACdH,EAAM,KAAK,CAAG,CAAE,MAAOF,GAAO,CAChC,EACMM,EAAcL,EAAUI,GAE9B,OADAA,IACOC,CACT,GACOH,EAAM,IAAMD,EAAM,KAAK,CAAC,KAAK,CACtC,Q"}

package/package.json

@@ -1,6 +1,124 @@
 {
   "name": "@slux/ripple",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "slux ripple bindings",
+  "keywords": [
+    "slux",
+    "ripple",
+    "bindings",
+    "state-management"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "license": "MIT",
+  "author": "itmanyong <itmanyong@gmail.com>",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/itmanyong/slux.git",
+    "directory": "packages/ripple"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "package.json"
+  ],
+  "main": "./dist/server.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/index.js",
+      "default": "./dist/server.js"
+    },
+    "./atom": {
+      "types": "./dist/atom.d.ts",
+      "default": "./dist/atom.js"
+    },
+    "./store": {
+      "types": "./dist/store.d.ts",
+      "default": "./dist/store.js"
+    },
+    "./proxy": {
+      "types": "./dist/proxy.d.ts",
+      "default": "./dist/proxy.js"
+    },
+    "./package.json": "./package.json",
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "default": "./dist/server.js"
+    },
+    "./flux": {
+      "types": "./dist/flux.d.ts",
+      "default": "./dist/flux.js"
+    },
+    "./state-machine": {
+      "types": "./dist/state-machine.d.ts",
+      "default": "./dist/state-machine.js"
+    },
+    "./rxjs": {
+      "types": "./dist/rxjs.d.ts",
+      "default": "./dist/rxjs.js"
+    }
+  },
+  "peerDependencies": {
+    "@slux/atom": "^0.1.0",
+    "@slux/core": "^0.1.0",
+    "@slux/proxy": "^0.1.0",
+    "@slux/store": "^0.1.0",
+    "ripple": ">=0.6.0",
+    "@slux/flux": "^0.1.0",
+    "@slux/state-machine": "^0.1.0",
+    "@slux/rxjs": "^0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "@slux/atom": {
+      "optional": true
+    },
+    "@slux/proxy": {
+      "optional": true
+    },
+    "@slux/store": {
+      "optional": true
+    },
+    "@slux/flux": {
+      "optional": true
+    },
+    "@slux/state-machine": {
+      "optional": true
+    },
+    "@slux/rxjs": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@slux/atom": "0.1.0",
+    "@slux/core": "0.1.0",
+    "@slux/proxy": "0.1.0",
+    "@slux/store": "0.1.0",
+    "jsdom": "30.1.3",
+    "rstack": "0.9.0",
+    "typescript": "7.1.0-beta",
+    "ripple": "0.6.1",
+    "@slux/flux": "0.1.0",
+    "@slux/state-machine": "0.1.0",
+    "@slux/rxjs": "0.1.0",
+    "rxjs": "7.8.2"
+  },
+  "dependencies": {
+    "@slux/shared": "0.1.0"
+  },
+  "scripts": {
+    "dev": "rs lib -w",
+    "build": "rs lib",
+    "test": "rs test",
+    "lint": "rs lint",
+    "fmt": "rs fmt",
+    "typecheck": "tsc --noEmit --project tsconfig.typecheck.json",
+    "clean": "rm -rf dist node_modules .turbo"
+  }
 }