From 828683ea96d677d550fa7d41142f9cf4eda23532 Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 24 Dec 2025 00:33:35 +0900 Subject: [PATCH 001/101] docs: add React package spec and implementation plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update spec-react.md with dialectFactory code examples - Replace emoji with Japanese text (悪い例/良い例) - Add detailed implementation plan for @coji/durably-react 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/implementation-plan-react.md | 581 ++++++++++++++++++++++++++++++ docs/spec-react.md | 16 +- 2 files changed, 595 insertions(+), 2 deletions(-) create mode 100644 docs/implementation-plan-react.md diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md new file mode 100644 index 00000000..09866e5a --- /dev/null +++ b/docs/implementation-plan-react.md @@ -0,0 +1,581 @@ +# @coji/durably-react 実装計画 + +## 概要 + +この文書は `@coji/durably-react` パッケージの実装計画を定義する。仕様は `docs/spec-react.md` に基づく。 + +--- + +## 1. パッケージ構成 + +### ディレクトリ構造 + +``` +packages/durably-react/ +├── src/ +│ ├── index.ts # Public exports +│ ├── context.tsx # DurablyContext & DurablyProvider +│ ├── hooks/ +│ │ ├── use-durably.ts # useDurably hook +│ │ ├── use-job.ts # useJob hook +│ │ ├── use-job-run.ts # useJobRun hook +│ │ └── use-job-logs.ts # useJobLogs hook +│ └── types.ts # Shared types +├── tests/ +│ ├── provider.test.tsx # DurablyProvider tests +│ ├── use-job.test.tsx # useJob tests +│ ├── use-job-run.test.tsx # useJobRun tests +│ ├── use-job-logs.test.tsx # useJobLogs tests +│ └── strict-mode.test.tsx # React StrictMode tests +├── package.json +├── tsconfig.json +├── tsup.config.ts +├── vitest.config.ts +└── README.md +``` + +### package.json + +```json +{ + "name": "@coji/durably-react", + "version": "0.1.0", + "description": "React bindings for Durably - step-oriented resumable batch execution", + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + } + }, + "files": ["dist", "README.md"], + "peerDependencies": { + "@coji/durably": ">=0.4.0", + "react": ">=18.0.0", + "react-dom": ">=18.0.0" + }, + "devDependencies": { + "@coji/durably": "workspace:*", + "@testing-library/react": "^16.x", + "@types/react": "^19.x", + "@types/react-dom": "^19.x", + "@vitejs/plugin-react": "^5.x", + "jsdom": "^27.x", + "react": "^19.x", + "react-dom": "^19.x", + "sqlocal": "^0.16.x", + "tsup": "^8.x", + "typescript": "^5.x", + "vitest": "^4.x" + } +} +``` + +--- + +## 2. 実装フェーズ + +### Phase 0: コア修正 - run:progress イベント追加 + +**目標**: `step.progress()` 呼び出し時に `run:progress` イベントを emit する + +**タスク**: +1. `packages/durably/src/events.ts` に `RunProgressEvent` インターフェースを追加 + ```ts + interface RunProgressEvent extends BaseEvent { + type: 'run:progress' + runId: string + jobName: string + progress: { current: number; total?: number; message?: string } + } + ``` + +2. `DurablyEvent` union 型に `RunProgressEvent` を追加 + +3. `EventType`, `AnyEventInput` の更新 + +4. `packages/durably/src/context.ts` の `progress()` メソッドを修正 + ```ts + progress(current: number, total?: number, message?: string): void { + const progressData = { current, total, message } + // DB 更新 + storage.updateRun(run.id, { progress: progressData }) + // イベント emit + emit({ + type: 'run:progress', + runId: run.id, + jobName: run.jobName, + progress: progressData, + }) + } + ``` + +5. テスト追加: `run:progress` イベントが正しく emit されることを確認 + +6. ドキュメント更新 + - `website/api/events.md` - `run:progress` イベントをRun Eventsセクションに追加 + - `website/guide/events.md` - Available Events テーブルに追加 + - `packages/durably/docs/llms.md` - Events セクションに `run:progress` を追加 + +**成果物**: +- `run:progress` イベントが利用可能になる +- 既存のテストがパスする +- ドキュメントが更新されている + +--- + +### Phase 1: 基盤構築 + +**目標**: パッケージ構造の作成とビルド環境の整備 + +**タスク**: +1. `packages/durably-react/` ディレクトリ作成 +2. `package.json` 作成（peerDependencies 設定） +3. `tsconfig.json` 作成（durably と同様の設定） +4. `tsup.config.ts` 作成（ESM ビルド） +5. `vitest.config.ts` 作成（jsdom 環境） +6. `src/index.ts` に空のエクスポート +7. ビルド確認 + +**成果物**: +- 空の durably-react パッケージがビルドできる状態 + +### Phase 2: Context & Provider 実装 + +**目標**: DurablyProvider と useDurably の実装 + +**タスク**: +1. `src/types.ts` - 共有型定義 + - `DurablyContextValue` + - `DurablyProviderProps` + - `UseJobOptions`, `UseJobLogsOptions` など + +2. `src/context.tsx` - DurablyContext & DurablyProvider + ```tsx + interface DurablyContextValue { + durably: Durably | null + isReady: boolean + error: Error | null + } + + interface DurablyProviderProps { + dialectFactory: () => Dialect + options?: DurablyOptions + autoStart?: boolean // default: true + autoMigrate?: boolean // default: true + children: ReactNode + } + ``` + + **実装ポイント**: + - `useRef` で初期化済みフラグを管理（StrictMode 対応） + - `dialectFactory()` は一度だけ実行 + - マウント時: `createDurably()` → `migrate()` → `start()` + - アンマウント時: `stop()` + +3. `src/hooks/use-durably.ts` + - Context から値を取得するシンプルなフック + - Provider 外で使用時はエラーをスロー + +**テスト**: +- `tests/provider.test.tsx` + - 正常な初期化フロー + - StrictMode での二重マウント + - autoStart/autoMigrate オプション + - アンマウント時のクリーンアップ + +### Phase 3: useJob 実装 + +**目標**: ジョブ実行と状態管理フック + +**タスク**: +1. `src/hooks/use-job.ts` + ```tsx + interface UseJobState { + status: RunStatus | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null + currentRunId: string | null + } + + function useJob( + job: JobDefinition, + options?: UseJobOptions + ): { + isReady: boolean + trigger: (input: TInput, opts?: TriggerOptions) => Promise + triggerAndWait: (input: TInput, opts?: TriggerOptions) => Promise<{id: string, output: TOutput}> + ...state, + isRunning: boolean + isPending: boolean + isCompleted: boolean + isFailed: boolean + reset: () => void + } + ``` + + **実装ポイント**: + - `useDurably()` で context を取得 + - `useEffect` で `durably.register(job)` を実行 + - `useRef` で `JobHandle` を保持 + - `trigger()` 呼び出し時にイベントリスナーを登録 + - Run 完了/失敗時にリスナーを解除 + - アンマウント時にもリスナーを解除 + - `initialRunId` オプションで既存 Run を購読 + +2. イベント購読の実装 + ```tsx + // trigger 内でリスナーを登録 + const unsubs = [ + durably.on('run:start', (e) => { + if (e.runId === run.id) setState(s => ({...s, status: 'running'})) + }), + durably.on('run:complete', (e) => { + if (e.runId === run.id) { + setState(s => ({...s, status: 'completed', output: e.output})) + cleanup() + } + }), + durably.on('run:fail', (e) => { + if (e.runId === run.id) { + setState(s => ({...s, status: 'failed', error: e.error})) + cleanup() + } + }), + durably.on('log:write', (e) => { + if (e.runId === run.id) { + setState(s => ({...s, logs: [...s.logs, e]})) + } + }), + ] + ``` + +**テスト**: +- `tests/use-job.test.tsx` + - trigger でジョブ実行 + - 状態更新（pending → running → completed） + - エラー時の状態 + - ログ収集 + - 進捗更新 + - アンマウント時のリスナー解除 + - initialRunId による復元 + +### Phase 4: useJobRun & useJobLogs 実装 + +**目標**: 単独の Run 購読とログ購読フック + +**タスク**: +1. `src/hooks/use-job-run.ts` + - `runId` を受け取り、その Run の状態を購読 + - `useJob` の戻り値から `trigger` 系を除いたもの + - DB ポーリングでステータス取得（イベントだけでは初期状態が取れないため） + + ```tsx + function useJobRun(runId: string | null): { + status: RunStatus | null + output: unknown + error: string | null + logs: LogEntry[] + progress: Progress | null + } + ``` + +2. `src/hooks/use-job-logs.ts` + - グローバルまたは特定 Run のログを購読 + - `maxLogs` でログ数を制限 + + ```tsx + interface UseJobLogsOptions { + runId?: string + maxLogs?: number // default: 100 + } + + function useJobLogs(options?: UseJobLogsOptions): { + logs: LogEntry[] + clear: () => void + } + ``` + +**テスト**: +- `tests/use-job-run.test.tsx` + - 既存 Run の購読 + - null runId の扱い + - 状態更新の購読 + +- `tests/use-job-logs.test.tsx` + - ログ収集 + - maxLogs 制限 + - clear 機能 + - runId フィルタリング + +### Phase 5: 型安全性とエッジケース + +**目標**: 型推論の改善とエッジケース対応 + +**タスク**: +1. 型推論の確認 + - `useJob` の `output` が `TOutput` として型推論されること + - `trigger` の引数が `TInput` として型推論されること + +2. エッジケース対応 + - Provider 外での hook 使用時のエラーメッセージ + - `isReady: false` 時の `trigger()` 呼び出しでエラー + - 同じ `JobDefinition` を複数回登録した場合の動作 + - コンポーネントのアンマウント中に trigger が呼ばれた場合 + +3. SSR 対応 + - サーバーサイドでは `isReady: false` を返す + - `typeof window === 'undefined'` チェック + +### Phase 6: ドキュメントと例 + +**目標**: README とサンプルコードの整備 + +**タスク**: +1. `packages/durably-react/README.md` 作成 + - インストール方法 + - 基本的な使い方 + - API リファレンス + +2. `examples/react` の更新 + - `@coji/durably-react` を使用するように変更 + - カスタム hook を削除 + +3. `packages/durably-react/docs/llms.md` 作成 + - LLM 向けドキュメント + +### Phase 7: テストと品質保証 + +**目標**: 完全なテストカバレッジと品質確認 + +**タスク**: +1. テストの実行と修正 + - jsdom 環境でのテスト + - StrictMode テスト + +2. TypeScript 型チェック +3. ESLint / Biome チェック +4. ビルド確認 + +### Phase 8: パブリッシュ準備 + +**目標**: npm パブリッシュの準備（パブリッシュは手動で行う） + +**タスク**: +1. version を 0.1.0 に設定 +2. CHANGELOG.md 作成 +3. ルートの package.json にスクリプト追加 + ```json + "test:react-pkg": "pnpm --filter @coji/durably-react test" + ``` +4. 最終ビルド確認 +5. dry-run で publish 確認 (`pnpm publish --dry-run`) + +--- + +## 3. 技術的な決定事項 + +### StrictMode 対応 + +React 19 の StrictMode では、開発モードで useEffect が二重に実行される。以下のパターンで対応: + +```tsx +function DurablyProvider({ dialectFactory, children }: Props) { + const [state, setState] = useState({ durably: null, isReady: false, error: null }) + const initializedRef = useRef(false) + + useEffect(() => { + // 二重初期化を防止 + if (initializedRef.current) return + initializedRef.current = true + + const dialect = dialectFactory() + const durably = createDurably({ dialect }) + + let cancelled = false + + async function init() { + try { + await durably.migrate() + if (cancelled) return + durably.start() + setState({ durably, isReady: true, error: null }) + } catch (error) { + if (!cancelled) { + setState(s => ({ ...s, error: error as Error })) + } + } + } + + init() + + return () => { + cancelled = true + durably.stop() + // initializedRef はリセットしない（再マウント時に再初期化しない） + } + }, [dialectFactory]) + + return {children} +} +``` + +### イベントリスナーのライフサイクル + +``` +trigger() 呼び出し + ↓ +リスナー登録 (run:start, run:complete, run:fail, log:write) + ↓ +イベント受信 → 状態更新 + ↓ +run:complete または run:fail + ↓ +リスナー解除 (cleanup) + +※ コンポーネントアンマウント時も cleanup を呼ぶ +``` + +### dialectFactory パターン + +仕様書の説明通り、`dialect` を直接渡すと毎回新しいインスタンスが生成されてしまう問題を回避するため、`dialectFactory` 関数を受け取る: + +```tsx +// 悪い例: 毎回新しい dialect が生成される + + +// 良い例: 一度だけ実行される + new SQLocalKysely('app.sqlite3').dialect}> +``` + +--- + +## 4. コア側の要件確認 + +仕様書に記載のコア側要件を確認: + +### 1. イベントリスナーの解除機能 ✅ + +現在のコードで確認済み: +```ts +// packages/durably/src/events.ts +export type Unsubscribe = () => void + +// Durably.on() は Unsubscribe を返す +on(type: T, listener: EventListener): Unsubscribe +``` + +### 2. register メソッド ✅ + +現在のコードで確認済み: +```ts +// packages/durably/src/durably.ts +register( + jobDef: JobDefinition, +): JobHandle +``` + +→ コア側の変更は不要。現在のAPIで実装可能。 + +### 3. progress イベント ⚠️ (Phase 0 で対応) + +現在のコアには `run:progress` イベントが存在しない。Phase 0 で追加する。 + +**追加するイベント**: +```ts +interface RunProgressEvent extends BaseEvent { + type: 'run:progress' + runId: string + jobName: string + progress: { current: number; total?: number; message?: string } +} +``` + +これにより、React 側でリアルタイムに progress を購読できるようになる。 + +--- + +## 5. 依存関係 + +``` +@coji/durably-react +├── @coji/durably (peer dependency >= 0.4.0) +├── react (peer dependency >= 18.0.0) +└── react-dom (peer dependency >= 18.0.0) + +開発時: +├── kysely (テストで必要) +├── sqlocal (テストで必要) +└── zod (テストで必要) +``` + +--- + +## 6. 公開 API + +```ts +// @coji/durably-react + +// Context & Provider +export { DurablyProvider } from './context' +export type { DurablyProviderProps } from './types' + +// Hooks +export { useDurably } from './hooks/use-durably' +export { useJob } from './hooks/use-job' +export { useJobRun } from './hooks/use-job-run' +export { useJobLogs } from './hooks/use-job-logs' + +// Types (re-export convenience types) +export type { + UseJobOptions, + UseJobResult, + UseJobRunResult, + UseJobLogsOptions, + UseJobLogsResult, +} from './types' +``` + +--- + +## 7. 実装順序のまとめ + +| Phase | 内容 | 依存 | +|-------|------|------| +| **0** | **コア修正: run:progress イベント追加** | - | +| 1 | 基盤構築 | Phase 0 | +| 2 | DurablyProvider, useDurably | Phase 1 | +| 3 | useJob | Phase 2 | +| 4 | useJobRun, useJobLogs | Phase 2 | +| 5 | 型安全性、エッジケース | Phase 3, 4 | +| 6 | ドキュメント、例 | Phase 5 | +| 7 | テスト、品質保証 | Phase 6 | +| 8 | パブリッシュ準備 | Phase 7 | + +--- + +## 8. リスクと対策 + +| リスク | 対策 | +|--------|------| +| StrictMode での予期せぬ動作 | 二重マウントテストを十分に行う | +| イベントリスナーのメモリリーク | useEffect cleanup で確実に解除 | +| 型推論が複雑で失敗 | ジェネリクスの型テストを追加 | +| ブラウザ環境でのテスト失敗 | jsdom で基本テスト、必要なら Playwright | + +--- + +## 9. 完了条件 + +- [ ] コア: `run:progress` イベントが追加されている +- [ ] すべてのフック（useDurably, useJob, useJobRun, useJobLogs）が実装されている +- [ ] DurablyProvider が StrictMode で正しく動作する +- [ ] 型推論が正しく機能する（TypeScript エラーなし） +- [ ] テストがすべてパスする +- [ ] ドキュメントが整備されている +- [ ] examples/react が新パッケージを使用するように更新されている +- [ ] `pnpm publish --dry-run` が成功する diff --git a/docs/spec-react.md b/docs/spec-react.md index cb450bc5..71d0fe83 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -134,9 +134,21 @@ function App() { #### なぜ `dialectFactory` なのか -コアライブラリの `createDurably({ dialect })` は dialect インスタンスを直接受け取る。これはアプリケーション起動時に一度だけ呼ばれるためである。 +コアライブラリの `createDurably({ dialect })` は dialect インスタンスを直接受け取る。 -一方、React コンポーネントは再レンダリングのたびに関数が実行される。`dialect` を直接渡すと毎回新しいインスタンスが生成されてしまう。`dialectFactory` はファクトリ関数を受け取り、Provider 内部で一度だけ実行することでこの問題を回避する。 +React コンポーネントでは、JSX 内でインスタンスを生成するパターンがよく使われる： + +```tsx +// 悪い例: レンダリングのたびに new SQLocalKysely() が実行される + +``` + +`dialectFactory` はファクトリ関数を受け取り、Provider 内部で一度だけ実行することでこの問題を回避する： + +```tsx +// 良い例: ファクトリ関数は Provider 内部で一度だけ実行される + new SQLocalKysely('app.sqlite3').dialect}> +``` #### ライフサイクル From cd0c4d3fba369f019a0e12cecf063ee41b6a7119 Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 24 Dec 2025 09:30:12 +0900 Subject: [PATCH 002/101] docs: rewrite spec-react.md with AI SDK v5 style architecture MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add two operation modes: browser-complete and server-integration - Browser-complete: DurablyProvider + dialectFactory (same as before) - Server-integration: @coji/durably-react/client (lightweight, no @coji/durably dependency) - Server-side: createDurablyHandler with Web Standard API (Request/Response) - Define SSE event format for real-time updates - Add durably.subscribe(runId) and durably.getJob(jobName) as new requirements 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/spec-react.md | 882 ++++++++++++++++++--------------------------- 1 file changed, 342 insertions(+), 540 deletions(-) diff --git a/docs/spec-react.md b/docs/spec-react.md index 71d0fe83..cc773658 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -1,42 +1,56 @@ # @coji/durably-react 仕様書 -## Why: なぜ React 統合が必要か +## 概要 -Durably をブラウザの React アプリケーションで使用する場合、以下の課題が発生する。 +`@coji/durably-react` は、Durably を React アプリケーションで使うためのバインディングである。 -1. **ライフサイクル管理の複雑さ**: Durably インスタンスの初期化・終了を React のライフサイクルに合わせる必要がある -2. **イベントリスナーの蓄積**: コンポーネントのマウント/アンマウントでリスナーが適切にクリーンアップされない -3. **状態管理のボイラープレート**: Run のステータス、進捗、ログを React の状態として管理するコードが冗長 -4. **型安全性の欠如**: イベントハンドラやジョブ出力の型が失われやすい +Vercel AI SDK v5 のアーキテクチャを参考に、以下の2つの動作モードをサポートする: -React 統合パッケージはこれらを解決し、宣言的で型安全な API を提供する。 +| モード | 説明 | サーバー | クライアント | +|--------|------|----------|--------------| +| **ブラウザ完結** | ブラウザ内で Durably を実行 | 不要 | `@coji/durably-react` + `@coji/durably` | +| **サーバー連携** | サーバーで Durably を実行、クライアントで購読 | `@coji/durably` | `@coji/durably-react/client`（軽量） | --- -## What: これは何か +## パッケージ構成 -`@coji/durably-react` は、Durably を React アプリケーションで使うためのバインディングである。 +``` +@coji/durably-react +├── index.ts # ブラウザ完結モード用（DurablyProvider + hooks） +└── client.ts # サーバー連携モード用（軽量、@coji/durably 不要） -### 提供するもの +@coji/durably +└── server.ts # サーバー側ヘルパー（Web 標準 API） +``` -| Export | 説明 | -| ------------------ | -------------------------------------------- | -| `DurablyProvider` | Durably インスタンスのライフサイクル管理 | -| `useDurably()` | Durably インスタンスと初期化状態へのアクセス | -| `useJob(job)` | ジョブの実行とステータス管理 | -| `useJobRun(runId)` | 特定の Run のステータス購読 | -| `useJobLogs()` | リアルタイムログ購読 | +--- -※ `defineJob` は `@coji/durably` から直接 import する。 +## パターン A: ブラウザ完結モード ---- +ブラウザ内で SQLite（OPFS）を使い、Durably を完全にクライアントサイドで実行する。 -## 基本的な使い方 +### セットアップ ```tsx -// ======================================== -// 1. ジョブ定義（React の外、静的） -// ======================================== +// root.tsx +import { DurablyProvider } from '@coji/durably-react' +import { SQLocalKysely } from 'sqlocal/kysely' + +export default function App() { + return ( + new SQLocalKysely('app.sqlite3').dialect} + > + + + ) +} +``` + +### ジョブ定義 + +```ts // jobs.ts import { defineJob } from '@coji/durably' import { z } from 'zod' @@ -47,37 +61,23 @@ export const processTask = defineJob({ output: z.object({ success: z.boolean() }), run: async (step, payload) => { await step.run('validate', () => validate(payload.taskId)) + step.progress(1, 2, 'Validating...') await step.run('process', () => process(payload.taskId)) + step.progress(2, 2, 'Processing...') return { success: true } }, }) +``` -// ======================================== -// 2. Provider（root） -// ======================================== -// root.tsx -import { DurablyProvider } from '@coji/durably-react' -import { SQLocalKysely } from 'sqlocal/kysely' +### 使用 -export default function App() { - return ( - new SQLocalKysely('app.sqlite3').dialect} - > - - - ) -} - -// ======================================== -// 3. 使用（シンプル） -// ======================================== +```tsx // component.tsx import { useJob } from '@coji/durably-react' import { processTask } from './jobs' function TaskRunner() { - const { trigger, status, output, isRunning } = useJob(processTask) + const { trigger, status, output, progress, isRunning } = useJob(processTask) return (
@@ -88,7 +88,11 @@ function TaskRunner() { {isRunning ? 'Processing...' : 'Process Task'} - {status === 'completed' &&
Done: {output?.success ? '✓' : '✗'}
} + {progress && ( + + )} + + {status === 'completed' &&
Done: {output?.success ? 'Yes' : 'No'}
}
) } @@ -96,314 +100,231 @@ function TaskRunner() { --- -## API 仕様 - -### DurablyProvider - -Durably インスタンスを作成し、子コンポーネントに提供する。 - -```tsx -import { DurablyProvider } from '@coji/durably-react' -import { SQLocalKysely } from 'sqlocal/kysely' - -function App() { - return ( - new SQLocalKysely('app.sqlite3').dialect} - options={{ - pollingInterval: 1000, - heartbeatInterval: 5000, - staleThreshold: 30000, - }} - > - - - ) -} -``` - -#### Props - -| Prop | 型 | 必須 | 説明 | -| ---------------- | ------------------ | ---- | -------------------------------------------------------------- | -| `dialectFactory` | `() => Dialect` | ✓ | Dialect を生成するファクトリ関数（Provider 内部で一度だけ実行）| -| `options` | `DurablyOptions` | - | Durably 設定オプション | -| `autoStart` | `boolean` | - | マウント時に自動で `start()` を呼ぶ（デフォルト: true） | -| `autoMigrate` | `boolean` | - | マウント時に自動で `migrate()` を呼ぶ（デフォルト: true） | -| `children` | `ReactNode` | ✓ | 子コンポーネント | +## パターン B: サーバー連携モード -#### なぜ `dialectFactory` なのか +サーバーで Durably を実行し、クライアントは HTTP/SSE で接続する。 -コアライブラリの `createDurably({ dialect })` は dialect インスタンスを直接受け取る。 +### サーバー側（Web 標準 API） -React コンポーネントでは、JSX 内でインスタンスを生成するパターンがよく使われる： +```ts +// app/routes/api.durably.ts (Remix example) +import { createDurablyHandler } from '@coji/durably/server' +import { durably } from '~/lib/durably.server' -```tsx -// 悪い例: レンダリングのたびに new SQLocalKysely() が実行される - -``` +const handler = createDurablyHandler(durably) -`dialectFactory` はファクトリ関数を受け取り、Provider 内部で一度だけ実行することでこの問題を回避する： +// POST /api/durably - ジョブ起動 +export async function action({ request }: ActionFunctionArgs) { + return handler.trigger(request) +} -```tsx -// 良い例: ファクトリ関数は Provider 内部で一度だけ実行される - new SQLocalKysely('app.sqlite3').dialect}> +// GET /api/durably?runId=xxx - SSE 購読 +export async function loader({ request }: LoaderFunctionArgs) { + return handler.subscribe(request) +} ``` -#### ライフサイクル - -1. **マウント時**: `dialectFactory()` → `createDurably()` → `migrate()` → `start()` の順で初期化 -2. **アンマウント時**: `stop()` を呼び、イベントリスナーをすべて解除 -3. **Strict Mode**: 二重マウントでも正しく動作（ref で初期化済みフラグを管理） +または手動で実装: -### useDurably - -Durably インスタンスと初期化状態を取得する。通常は `useJob` を使うため、直接使用することは少ない。 - -```tsx -import { useDurably } from '@coji/durably-react' +```ts +// POST /api/durably +export async function action({ request }: ActionFunctionArgs) { + const { jobName, input } = await request.json() + const job = durably.getJob(jobName) + const run = await job.trigger(input) + return Response.json({ runId: run.id }) +} -function MyComponent() { - const { durably, isReady, error } = useDurably() +// GET /api/durably?runId=xxx +export async function loader({ request }: LoaderFunctionArgs) { + const url = new URL(request.url) + const runId = url.searchParams.get('runId') - if (error) return
Error: {error.message}
- if (!isReady) return
Loading...
+ const stream = durably.subscribe(runId) - // durably インスタンスを直接使用 + return new Response(stream, { + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + 'Connection': 'keep-alive', + }, + }) } ``` -#### 戻り値 - -| プロパティ | 型 | 説明 | -| ---------- | ---------------- | --------------------------------------- | -| `durably` | `Durably \| null`| Durably インスタンス（未初期化時は null）| -| `isReady` | `boolean` | 初期化完了フラグ | -| `error` | `Error \| null` | 初期化エラー | - -### useJob - -ジョブの実行とステータス管理を行う。`JobDefinition` を受け取り、自動で durably に登録する。 +### クライアント側（軽量） ```tsx -import { useJob } from '@coji/durably-react' -import { processTask } from './jobs' +// component.tsx +import { useJob } from '@coji/durably-react/client' function TaskRunner() { - const { - isReady, - trigger, - status, - output, - error, - logs, - progress, - isRunning, - isPending, - isCompleted, - isFailed, - currentRunId, - reset, - } = useJob(processTask) + const { trigger, status, output, progress, isRunning } = useJob({ + api: '/api/durably', + jobName: 'process-task', + }) return (
{progress && ( )} - {isCompleted &&
Result: {JSON.stringify(output)}
} - {isFailed &&
Error: {error}
} - -
    - {logs.map((log) => ( -
  • {log.message}
    • - ))} -
+ {status === 'completed' &&
Done!
}
) } ``` -#### 引数 +--- -| 引数 | 型 | 説明 | -| --------- | --------------------------------------- | ------------------------------------------------ | -| `job` | `JobDefinition` | ジョブ定義 | -| `options` | `UseJobOptions` | オプション設定（省略可） | +## API 仕様 + +### ブラウザ完結モード (`@coji/durably-react`) -#### UseJobOptions +#### DurablyProvider -| プロパティ | 型 | 説明 | -| -------------- | -------- | -------------------------------------------------------- | -| `initialRunId` | `string` | 初期状態で購読する Run ID（ページリロード時の復元に使用）| +```tsx + dialect} + options={{ pollingInterval: 1000 }} + autoStart={true} + autoMigrate={true} +> + {children} + +``` -#### 戻り値 +| Prop | 型 | 必須 | 説明 | +|------|-----|------|------| +| `dialectFactory` | `() => Dialect` | Yes | Dialect ファクトリ（一度だけ実行） | +| `options` | `DurablyOptions` | - | Durably 設定 | +| `autoStart` | `boolean` | - | 自動 start()（デフォルト: true） | +| `autoMigrate` | `boolean` | - | 自動 migrate()（デフォルト: true） | -| プロパティ | 型 | 説明 | -| ---------------- | --------------------------------------------------------------- | ------------------------------------ | -| `isReady` | `boolean` | Durably 初期化完了フラグ | -| `trigger` | `(input: TInput, options?: TriggerOptions) => Promise` | ジョブを実行 | -| `triggerAndWait` | `(input: TInput, options?: TriggerOptions) => Promise<{...}>` | 実行して完了を待つ | -| `status` | `RunStatus \| null` | 現在の Run のステータス | -| `output` | `TOutput \| null` | 完了時の出力（型安全） | -| `error` | `string \| null` | 失敗時のエラーメッセージ | -| `logs` | `LogEntry[]` | リアルタイムログ | -| `progress` | `Progress \| null` | 進捗情報 | -| `isRunning` | `boolean` | 実行中かどうか | -| `isPending` | `boolean` | 待機中かどうか | -| `isCompleted` | `boolean` | 完了したかどうか | -| `isFailed` | `boolean` | 失敗したかどうか | -| `currentRunId` | `string \| null` | 現在の Run ID | -| `reset` | `() => void` | 状態をリセット | +#### useDurably -※ `isReady` が `false` の間は `trigger()` を呼ばないこと。呼んだ場合は例外がスローされる。 +```tsx +const { durably, isReady, error } = useDurably() +``` -#### 動作 +| 戻り値 | 型 | 説明 | +|--------|-----|------| +| `durably` | `Durably \| null` | インスタンス | +| `isReady` | `boolean` | 初期化完了 | +| `error` | `Error \| null` | 初期化エラー | -- `useJob` 呼び出し時に、内部で `durably.register(job)` を実行 -- `trigger()` 呼び出し時にイベントリスナーを登録 -- Run の完了/失敗時に自動でリスナーを解除 -- コンポーネントのアンマウント時にもリスナーを解除 +#### useJob -### useJobRun +```tsx +const { + isReady, + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning, + isPending, + isCompleted, + isFailed, + currentRunId, + reset, +} = useJob(jobDefinition, options?) +``` -特定の Run ID のステータスを購読する。ページリロード後に既存の Run を再購読する場合に使用。 +| 引数 | 型 | 説明 | +|------|-----|------| +| `jobDefinition` | `JobDefinition` | ジョブ定義 | +| `options.initialRunId` | `string` | 初期購読 Run ID | -> **Note**: ページリロード時の Run 復元には `useJob` の `initialRunId` オプションを使うことを推奨。 -> `useJobRun` は、ジョブ定義なしで Run ID のみで購読したい場合に使用する。 +#### useJobRun ```tsx -// 推奨: useJob + initialRunId（trigger も使える） -import { useJob } from '@coji/durably-react' -import { useSearchParams } from 'react-router' -import { processTask } from './jobs' - -function TaskRunner() { - const [searchParams, setSearchParams] = useSearchParams() - const runId = searchParams.get('runId') +const { status, output, error, logs, progress } = useJobRun(runId) +``` - const { isReady, trigger, status, output } = useJob(processTask, { - initialRunId: runId ?? undefined, - }) +Run ID のみで購読（trigger なし）。 - const handleRun = async () => { - const run = await trigger({ taskId: '123' }) - setSearchParams({ runId: run.id }) - } +#### useJobLogs - return ( -
- - {status === 'completed' &&
Result: {JSON.stringify(output)}
} -
- ) -} +```tsx +const { logs, clear } = useJobLogs({ runId?, maxLogs? }) ``` -```tsx -// useJobRun: Run ID のみで購読（trigger なし） -import { useJobRun } from '@coji/durably-react' -import { useSearchParams } from 'react-router' +--- -function RunStatus() { - const [searchParams] = useSearchParams() - const runId = searchParams.get('runId') +### サーバー連携モード - const { status, output, error, logs, progress } = useJobRun(runId) +#### サーバー側 (`@coji/durably/server`) - if (!runId) return
No run ID
+```ts +import { createDurablyHandler } from '@coji/durably/server' - return ( -
-

Run: {runId}

-

Status: {status}

+const handler = createDurablyHandler(durably) - {progress && ( - - )} +// Request handlers +handler.trigger(request: Request): Promise // POST +handler.subscribe(request: Request): Response // GET (SSE) +``` - {status === 'completed' && ( - 
{JSON.stringify(output, null, 2)}
- )} +**API 規約**: - {status === 'failed' && ( -
{error}
- )} -
- ) -} -``` +| エンドポイント | メソッド | リクエスト | レスポンス | +|---------------|---------|-----------|-----------| +| `/api/durably` | POST | `{ jobName, input }` | `{ runId }` | +| `/api/durably?runId=xxx` | GET | - | SSE stream | -#### 引数 +**SSE イベント形式**: -| 引数 | 型 | 説明 | -| ------- | ---------------- | --------------- | -| `runId` | `string \| null` | 購読する Run ID | +``` +data: {"type":"run:start","runId":"xxx","jobName":"process-task",...} -#### 戻り値 +data: {"type":"run:progress","runId":"xxx","progress":{"current":1,"total":2}} -`useJob` の戻り値から `trigger` 系を除いたもの。 +data: {"type":"run:complete","runId":"xxx","output":{"success":true}} -### useJobLogs +``` -ログをリアルタイムで購読する。 +#### クライアント側 (`@coji/durably-react/client`) ```tsx -import { useJobLogs } from '@coji/durably-react' +import { useJob, useJobRun } from '@coji/durably-react/client' -function LogViewer({ runId }: { runId?: string }) { - const { logs, clear } = useJobLogs({ runId, maxLogs: 100 }) +// ジョブ実行 + 購読 +const { trigger, status, progress, output } = useJob({ + api: '/api/durably', + jobName: 'process-task', +}) - return ( -
- -
    - {logs.map((log) => ( -
  • - [{log.timestamp}] {log.message} -
    • - ))} -
-
- ) -} +// 既存 Run の購読のみ +const { status, progress, output } = useJobRun({ + api: '/api/durably', + runId: 'xxx', +}) ``` -#### オプション - -| オプション | 型 | 説明 | -| ---------- | -------- | ----------------------------------------- | -| `runId` | `string` | 特定の Run のログのみ購読（省略時は全ログ）| -| `maxLogs` | `number` | 保持する最大ログ数（デフォルト: 100） | - -#### 戻り値 - -| プロパティ | 型 | 説明 | -| ---------- | ------------ | ------------------ | -| `logs` | `LogEntry[]` | ログエントリの配列 | -| `clear` | `() => void` | ログをクリア | +| オプション | 型 | 必須 | 説明 | +|-----------|-----|------|------| +| `api` | `string` | Yes | API エンドポイント | +| `jobName` | `string` | Yes (useJob) | ジョブ名 | +| `runId` | `string` | Yes (useJobRun) | Run ID | --- ## 型定義 ```ts -interface DurablyOptions { - pollingInterval?: number - heartbeatInterval?: number - staleThreshold?: number -} - +// 共通 type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' interface Progress { @@ -422,63 +343,79 @@ interface LogEntry { timestamp: string } -interface Run { - id: string - jobName: string - status: RunStatus - output: TOutput | null - error: string | null - progress: Progress | null - createdAt: string - updatedAt: string -} +// イベント（SSE で送信される） +type DurablyEvent = + | { type: 'run:start'; runId: string; jobName: string; payload: unknown } + | { type: 'run:complete'; runId: string; jobName: string; output: unknown; duration: number } + | { type: 'run:fail'; runId: string; jobName: string; error: string } + | { type: 'run:progress'; runId: string; jobName: string; progress: Progress } + | { type: 'step:start'; runId: string; stepName: string; stepIndex: number } + | { type: 'step:complete'; runId: string; stepName: string; stepIndex: number; output: unknown } + | { type: 'log:write'; runId: string; level: string; message: string; data: unknown } +``` + +--- + +## 依存関係 + +### ブラウザ完結モード + +``` +@coji/durably-react +├── @coji/durably (peer dependency) +├── react (peer dependency, >= 18.0.0) +└── react-dom (peer dependency, >= 18.0.0) +``` + +```bash +npm install @coji/durably-react @coji/durably kysely zod sqlocal react react-dom +``` + +### サーバー連携モード + +**サーバー**: +```bash +npm install @coji/durably kysely zod better-sqlite3 +``` + +**クライアント**（軽量、`@coji/durably` 不要）: +```bash +npm install @coji/durably-react react react-dom ``` --- ## 使用例 -### 進捗表示付きバッチ処理 +### 進捗表示付きバッチ処理（ブラウザ完結） ```tsx // jobs.ts -import { defineJob } from '@coji/durably' -import { z } from 'zod' - export const batchProcess = defineJob({ name: 'batch-process', input: z.object({ items: z.array(z.string()) }), output: z.object({ processed: z.number() }), run: async (step, payload) => { const { items } = payload - let processed = 0 - for (let i = 0; i < items.length; i++) { - await step.run(`process-${items[i]}`, async () => { - await processItem(items[i]) - }) - processed++ - step.progress(processed, items.length, `Processing ${items[i]}`) + await step.run(`process-${i}`, () => processItem(items[i])) + step.progress(i + 1, items.length, `Processing ${items[i]}`) } - - return { processed } + return { processed: items.length } }, }) // component.tsx -import { useJob } from '@coji/durably-react' -import { batchProcess } from './jobs' - function BatchProcessor() { const { trigger, progress, isRunning, output } = useJob(batchProcess) return (
{progress && ( @@ -488,299 +425,164 @@ function BatchProcessor() {
)} - {output &&
Processed: {output.processed} items
} + {output &&
Processed: {output.processed}
} ) } ``` -### ページリロード後の再接続 +### AI エージェント（サーバー連携） ```tsx -import { useJob, useJobRun } from '@coji/durably-react' -import { useSearchParams, useNavigate } from 'react-router' -import { processTask } from './jobs' +// サーバー: jobs.server.ts +export const aiAgent = defineJob({ + name: 'ai-agent', + input: z.object({ prompt: z.string() }), + output: z.object({ response: z.string() }), + run: async (step, { prompt }) => { + step.log.info('Processing prompt', { prompt }) -function TaskPage() { - const [searchParams] = useSearchParams() - const navigate = useNavigate() - const existingRunId = searchParams.get('runId') + const plan = await step.run('plan', () => generatePlan(prompt)) + step.progress(1, 3, 'Planning...') - // 新規実行用 - const { trigger, currentRunId } = useJob(processTask) + const research = await step.run('research', () => doResearch(plan)) + step.progress(2, 3, 'Researching...') - // 既存 Run の購読用 - const { status, progress, output } = useJobRun(existingRunId ?? currentRunId) + const response = await step.run('generate', () => generate(research)) + step.progress(3, 3, 'Generating...') - const handleStart = async () => { - const run = await trigger({ taskId: 'task-1' }) - navigate(`?runId=${run.id}`) // URL に runId を保存 - } + return { response } + }, +}) + +// クライアント: component.tsx +import { useJob } from '@coji/durably-react/client' + +function AIChat() { + const { trigger, status, progress, output, logs } = useJob({ + api: '/api/durably', + jobName: 'ai-agent', + }) return (
- - {status &&

Status: {status}

} - {progress && } - {output && 
{JSON.stringify(output, null, 2)}
} + {progress &&
{progress.message}
} + +
+ {logs.map((log, i) => ( +
[{log.level}] {log.message}
+ ))} +
+ + {output &&
{output.response}
}
) } ``` ---- - -## 内部実装指針 - -### useJob の実装 +### ページリロード後の再接続 ```tsx -function useJob( - jobDef: JobDefinition -) { - const { durably, isReady } = useDurably() - const [state, setState] = useState(initialState) - const listenersRef = useRef void>>([]) - const jobHandleRef = useRef | null>(null) - - // ジョブを登録 - useEffect(() => { - if (!durably || !isReady) return - jobHandleRef.current = durably.register(jobDef) - }, [durably, isReady, jobDef.name]) - - const trigger = useCallback(async (input: TInput, options?: TriggerOptions) => { - const jobHandle = jobHandleRef.current - if (!durably || !jobHandle) { - throw new Error('Durably not initialized') - } - - const run = await jobHandle.trigger(input, options) - setState(s => ({ ...s, currentRunId: run.id, status: 'pending' })) - - // リスナー登録 - const unsubs = [ - durably.on('run:start', (e) => { - if (e.runId === run.id) { - setState(s => ({ ...s, status: 'running' })) - } - }), - durably.on('run:complete', (e) => { - if (e.runId === run.id) { - setState(s => ({ ...s, status: 'completed', output: e.output })) - cleanup() - } - }), - durably.on('run:fail', (e) => { - if (e.runId === run.id) { - setState(s => ({ ...s, status: 'failed', error: e.error })) - cleanup() - } - }), - durably.on('log:write', (e) => { - if (e.runId === run.id) { - setState(s => ({ ...s, logs: [...s.logs, e] })) - } - }), - ] - - listenersRef.current = unsubs - return run - }, [durably]) - - const cleanup = useCallback(() => { - listenersRef.current.forEach(unsub => unsub()) - listenersRef.current = [] - }, []) - - useEffect(() => cleanup, [cleanup]) - - return { trigger, ...state } -} -``` - ---- - -## Durably コア側の要件 - -React 統合を実現するために、コアライブラリに以下が必要。 - -### 1. イベントリスナーの解除機能 - -`on()` が unsubscribe 関数を返す必要がある。 - -```ts -const unsubscribe = durably.on('run:complete', handler) -unsubscribe() // リスナーを解除 -``` - -### 2. register メソッド - -`JobDefinition` を受け取り、`JobHandle` を返す。 - -```ts -const jobHandle = durably.register(jobDef) -``` - ---- - -## 依存関係 +import { useJob } from '@coji/durably-react/client' +import { useSearchParams } from 'react-router' -``` -@coji/durably-react -├── @coji/durably (peer dependency) -├── react (peer dependency, >= 18.0.0) -└── react-dom (peer dependency, >= 18.0.0) +function TaskPage() { + const [searchParams, setSearchParams] = useSearchParams() + const runId = searchParams.get('runId') -@coji/durably -├── kysely (peer dependency) -└── zod (peer dependency) -``` + const { trigger, status, output } = useJob({ + api: '/api/durably', + jobName: 'process-task', + initialRunId: runId ?? undefined, // 既存 Run を再購読 + }) -インストール（ブラウザ環境）: + const handleStart = async () => { + const { runId } = await trigger({ taskId: '123' }) + setSearchParams({ runId }) // URL に保存 + } -```bash -npm install @coji/durably-react @coji/durably kysely zod sqlocal react react-dom + return ( +
+ + {status === 'completed' && 
{JSON.stringify(output)}
} +
+ ) +} ``` --- -## 検討事項 +## 内部実装指針 -### SSR 対応 +### ブラウザ完結モード -- `DurablyProvider` はクライアントサイドのみで動作 -- SSR 時は `isReady: false` を返し、ハイドレーション後に初期化 +- `DurablyProvider` で `createDurably()` → `migrate()` → `start()` +- `useJob` は `durably.on()` でイベント購読 +- アンマウント時に `stop()` とリスナー解除 -### React 19 の Strict Mode +### サーバー連携モード -- 開発モードでの二重マウントに対応 -- ref を使った初期化済みフラグで重複初期化を防止 +- `useJob` は `fetch()` で trigger、`EventSource` で購読 +- SSE の再接続は自動（EventSource の標準動作） +- `@coji/durably` に依存しない -### エラーバウンダリ +### Strict Mode 対応 -- Provider 初期化エラーは `error` として公開 -- 子コンポーネントでエラーバウンダリを使用することを推奨 +- ref で初期化済みフラグを管理 +- 二重マウントでも正しく動作 --- -## 将来拡張への準備 +## Durably コア側の要件 -### Streaming 対応 (spec-streaming.md 参照) +### 既存（実装済み） -v2 で `durably.subscribe()` が実装された際、以下の拡張を予定している。現在の設計はこれらを妨げないよう考慮されている。 +- `durably.on()` が unsubscribe 関数を返す +- `durably.register(jobDef)` で JobHandle を取得 -#### 1. useJob の events 追加 +### 新規（サーバー連携用） -```tsx -// v1（現在） -const { trigger, status, output, logs, progress } = useJob(job) +1. **`durably.subscribe(runId): ReadableStream`** + - Run のイベントを ReadableStream で返す + - SSE に変換可能 -// v2（将来）- events を追加 -const { trigger, status, output, logs, progress, events } = useJob(job) +2. **`durably.getJob(jobName): JobHandle`** + - 登録済みジョブを名前で取得 -// events は AsyncIterable -for await (const event of events) { - if (event.type === 'stream') { - // トークン単位のストリーミングデータ - console.log(event.data) - } -} -``` - -`events` は v1 では `null` を返す。v2 で追加しても破壊的変更にならない。 +3. **`createDurablyHandler(durably)`** (`@coji/durably/server`) + - Web 標準の Request/Response を扱うヘルパー -#### 2. 内部実装の切り替え - -| バージョン | イベント購読方式 | -| ---------- | ----------------------------------------------------------- | -| v1 | `durably.on()` ベース（同期的、プロセス内のみ） | -| v2 | `durably.subscribe()` ベース（ReadableStream、再接続対応） | +--- -外部 API は変わらない。内部で使用するイベントソースを切り替える。 +## 将来拡張 -#### 3. useJobStream フック（新規、v2） +### Streaming 対応 -streaming 専用のフック。`step.stream()` の emit をリアルタイムで消費する。 +`step.stream()` でトークン単位のストリーミングを追加予定。 ```tsx -import { useJobStream } from '@coji/durably-react' - -function AIChat() { - const { trigger, isStreaming, chunks, fullText } = useJobStream(chatJob) - - return ( -
- - - {isStreaming && ( -
- {chunks.map((chunk, i) => ( - {chunk.text} - ))} -
- )} - - {!isStreaming && fullText && ( -
{fullText}
- )} -
- ) -} +// 将来 +const { trigger, chunks, fullText, isStreaming } = useJobStream({ + api: '/api/durably', + jobName: 'ai-chat', +}) ``` -#### 4. サーバー実行 + クライアント購読 - -サーバーサイドで Durably を実行し、クライアントで購読するパターン。常駐サーバー（非 Serverless）を前提とする。 +### カスタム API アダプター ```tsx -// サーバー側: Resource Route で SSE エンドポイント -// app/routes/api.runs.$runId.stream.ts -export async function loader({ params }: LoaderFunctionArgs) { - const stream = await durably.subscribe(params.runId) - - const sseStream = stream.pipeThrough(new TransformStream({ - transform(event, controller) { - controller.enqueue(`data: ${JSON.stringify(event)}\n\n`) - } - })) - - return new Response(sseStream, { - headers: { 'Content-Type': 'text-event-stream' }, - }) -} -``` - -```tsx -// クライアント側: SSE を消費するフック -import { useEventSource } from '@coji/durably-react/client' - -function TaskStatus({ runId }: { runId: string }) { - const { status, progress, output } = useEventSource( - `/api/runs/${runId}/stream` - ) - - return
Status: {status}
-} +// 将来: カスタム API 実装 +const { trigger, status } = useJob({ + trigger: async (input) => { + const res = await fetch('/custom/trigger', { ... }) + return res.json() + }, + subscribe: (runId) => new EventSource(`/custom/subscribe/${runId}`), +}) ``` - -`@coji/durably-react/client` は Durably 本体に依存しない軽量なフック集として提供予定。 - -### 設計上の考慮事項 - -1. **useJob の戻り値は拡張可能** - - 新しいプロパティを追加しても既存コードは壊れない - - `events` など将来のプロパティは `null` または `undefined` を返す - -2. **Provider の props は安定** - - `dialect` と `options` の構造は変わらない - - 新しいオプションは追加されるが、既存は維持 - -3. **内部でのイベントソース抽象化** - - `on()` から `subscribe()` への移行を内部で吸収 - - フック利用者は実装の詳細を意識しない From 1ced54023d3a8bb45e82b615b449353dc011564b Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 24 Dec 2025 10:28:01 +0900 Subject: [PATCH 003/101] docs: add language identifiers to fenced code blocks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address CodeRabbit review feedback: - Add 'text' language identifier to package structure block - Add 'text' language identifier to SSE event format block 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/spec-react.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/spec-react.md b/docs/spec-react.md index cc773658..056df595 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -15,7 +15,7 @@ Vercel AI SDK v5 のアーキテクチャを参考に、以下の2つの動作 ## パッケージ構成 -``` +```text @coji/durably-react ├── index.ts # ブラウザ完結モード用（DurablyProvider + hooks） └── client.ts # サーバー連携モード用（軽量、@coji/durably 不要） @@ -286,7 +286,7 @@ handler.subscribe(request: Request): Response // GET (SSE) **SSE イベント形式**: -``` +```text data: {"type":"run:start","runId":"xxx","jobName":"process-task",...} data: {"type":"run:progress","runId":"xxx","progress":{"current":1,"total":2}} From 2af91fc9f8b67000482998266a55fb2d08a53206 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 22:49:57 +0900 Subject: [PATCH 004/101] docs: fix API specification inconsistencies in spec-react.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Address code review feedback: - Fix useJobRun signature to use object form: useJobRun({ runId }) - Add 400 Bad Request handling for missing runId in server example - Fix SSE event samples to include jobName in all events - Add trigger/triggerAndWait return type definitions - Add initialRunId to client useJob options table - Fix log:write level type to use union instead of string - Add security (auth/CORS/CSRF) out of scope note - Add cancel API to future extensions section 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/spec-react.md | 55 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/docs/spec-react.md b/docs/spec-react.md index 056df595..0fb805db 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -140,6 +140,10 @@ export async function loader({ request }: LoaderFunctionArgs) { const url = new URL(request.url) const runId = url.searchParams.get('runId') + if (!runId) { + return new Response('Missing runId', { status: 400 }) + } + const stream = durably.subscribe(runId) return new Response(stream, { @@ -247,14 +251,25 @@ const { | `jobDefinition` | `JobDefinition` | ジョブ定義 | | `options.initialRunId` | `string` | 初期購読 Run ID | +**戻り値の詳細**: + +| メソッド | 戻り値 | 説明 | +|-------------------------|-----------------------------------------------|-----------------------------| +| `trigger(input)` | `Promise<{ runId: string }>` | ジョブを実行、Run ID を返す | +| `triggerAndWait(input)` | `Promise<{ runId: string; output: TOutput }>` | 実行して完了を待つ | + #### useJobRun ```tsx -const { status, output, error, logs, progress } = useJobRun(runId) +const { status, output, error, logs, progress } = useJobRun({ runId }) ``` Run ID のみで購読（trigger なし）。 +| 引数 | 型 | 説明 | +|---------|------------------|-----------------| +| `runId` | `string \| null` | 購読する Run ID | + #### useJobLogs ```tsx @@ -284,14 +299,18 @@ handler.subscribe(request: Request): Response // GET (SSE) | `/api/durably` | POST | `{ jobName, input }` | `{ runId }` | | `/api/durably?runId=xxx` | GET | - | SSE stream | +> **Note**: 認証・認可、CORS、CSRF の扱いは本仕様のスコープ外。アプリケーション側で適切に実装すること。 + **SSE イベント形式**: ```text -data: {"type":"run:start","runId":"xxx","jobName":"process-task",...} +data: {"type":"run:start","runId":"xxx","jobName":"process-task","payload":{...}} + +data: {"type":"run:progress","runId":"xxx","jobName":"process-task","progress":{"current":1,"total":2}} -data: {"type":"run:progress","runId":"xxx","progress":{"current":1,"total":2}} +data: {"type":"run:complete","runId":"xxx","jobName":"process-task","output":{"success":true},"duration":1234} -data: {"type":"run:complete","runId":"xxx","output":{"success":true}} +data: {"type":"run:fail","runId":"xxx","jobName":"process-task","error":"Something went wrong"} ``` @@ -313,11 +332,12 @@ const { status, progress, output } = useJobRun({ }) ``` -| オプション | 型 | 必須 | 説明 | -|-----------|-----|------|------| -| `api` | `string` | Yes | API エンドポイント | -| `jobName` | `string` | Yes (useJob) | ジョブ名 | -| `runId` | `string` | Yes (useJobRun) | Run ID | +| オプション | 型 | 必須 | 説明 | +|----------------|----------|-----------------|--------------------------------| +| `api` | `string` | Yes | API エンドポイント | +| `jobName` | `string` | Yes (useJob) | ジョブ名 | +| `runId` | `string` | Yes (useJobRun) | Run ID | +| `initialRunId` | `string` | - | 初期購読 Run ID（再接続用） | --- @@ -351,7 +371,7 @@ type DurablyEvent = | { type: 'run:progress'; runId: string; jobName: string; progress: Progress } | { type: 'step:start'; runId: string; stepName: string; stepIndex: number } | { type: 'step:complete'; runId: string; stepName: string; stepIndex: number; output: unknown } - | { type: 'log:write'; runId: string; level: string; message: string; data: unknown } + | { type: 'log:write'; runId: string; level: 'info' | 'warn' | 'error'; message: string; data: unknown } ``` --- @@ -562,6 +582,21 @@ function TaskPage() { ## 将来拡張 +### キャンセル API + +Run のキャンセル機能を追加予定。 + +```tsx +// useJob に cancel を追加 +const { trigger, cancel, status } = useJob(job) +await cancel() // 現在の Run をキャンセル + +// サーバー API +DELETE /api/durably?runId=xxx → { success: true } +``` + +> **Note**: キャンセルは cooperative。ステップ実行中は即座に止められず、次のステップに進む前にチェックされる。 + ### Streaming 対応 `step.stream()` でトークン単位のストリーミングを追加予定。 From afb9629ed553935ee71b8723bafbdc935234f970 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 22:55:54 +0900 Subject: [PATCH 005/101] docs: unify API consistency across browser and server modes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Unify useJob return values (add all fields to server mode example) - Unify useJobRun return values (add error, logs to server mode) - Add useJobLogs to server mode with api/runId/maxLogs options - Add jobName to step:start, step:complete, log:write events for consistency - Add DurablyOptions type definition (pollingInterval, heartbeatInterval, staleThreshold) - Separate options tables for useJob, useJobRun, useJobLogs in server mode - Add 'text' language identifier to dependency tree code block 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/spec-react.md | 69 +++++++++++++++++++++++++++++++++++++--------- 1 file changed, 56 insertions(+), 13 deletions(-) diff --git a/docs/spec-react.md b/docs/spec-react.md index 0fb805db..83f14e6f 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -317,27 +317,64 @@ data: {"type":"run:fail","runId":"xxx","jobName":"process-task","error":"Somethi #### クライアント側 (`@coji/durably-react/client`) ```tsx -import { useJob, useJobRun } from '@coji/durably-react/client' +import { useJob, useJobRun, useJobLogs } from '@coji/durably-react/client' // ジョブ実行 + 購読 -const { trigger, status, progress, output } = useJob({ +const { + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isReady, + isRunning, + isPending, + isCompleted, + isFailed, + currentRunId, + reset, +} = useJob({ api: '/api/durably', jobName: 'process-task', }) // 既存 Run の購読のみ -const { status, progress, output } = useJobRun({ +const { status, output, error, logs, progress } = useJobRun({ + api: '/api/durably', + runId: 'xxx', +}) + +// ログ購読 +const { logs, clear } = useJobLogs({ api: '/api/durably', runId: 'xxx', }) ``` -| オプション | 型 | 必須 | 説明 | -|----------------|----------|-----------------|--------------------------------| -| `api` | `string` | Yes | API エンドポイント | -| `jobName` | `string` | Yes (useJob) | ジョブ名 | -| `runId` | `string` | Yes (useJobRun) | Run ID | -| `initialRunId` | `string` | - | 初期購読 Run ID（再接続用） | +**useJob オプション**: + +| オプション | 型 | 必須 | 説明 | +|----------------|----------|------|-----------------------------| +| `api` | `string` | Yes | API エンドポイント | +| `jobName` | `string` | Yes | ジョブ名 | +| `initialRunId` | `string` | - | 初期購読 Run ID（再接続用） | + +**useJobRun オプション**: + +| オプション | 型 | 必須 | 説明 | +|------------|----------|------|--------------------| +| `api` | `string` | Yes | API エンドポイント | +| `runId` | `string` | Yes | Run ID | + +**useJobLogs オプション**: + +| オプション | 型 | 必須 | 説明 | +|------------|----------|------|---------------------------------------| +| `api` | `string` | Yes | API エンドポイント | +| `runId` | `string` | - | 特定 Run のログのみ（省略時は全ログ） | +| `maxLogs` | `number` | - | 保持する最大ログ数（デフォルト: 100） | --- @@ -347,6 +384,12 @@ const { status, progress, output } = useJobRun({ // 共通 type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' +interface DurablyOptions { + pollingInterval?: number // デフォルト: 1000ms + heartbeatInterval?: number // デフォルト: 5000ms + staleThreshold?: number // デフォルト: 30000ms +} + interface Progress { current: number total?: number @@ -369,9 +412,9 @@ type DurablyEvent = | { type: 'run:complete'; runId: string; jobName: string; output: unknown; duration: number } | { type: 'run:fail'; runId: string; jobName: string; error: string } | { type: 'run:progress'; runId: string; jobName: string; progress: Progress } - | { type: 'step:start'; runId: string; stepName: string; stepIndex: number } - | { type: 'step:complete'; runId: string; stepName: string; stepIndex: number; output: unknown } - | { type: 'log:write'; runId: string; level: 'info' | 'warn' | 'error'; message: string; data: unknown } + | { type: 'step:start'; runId: string; jobName: string; stepName: string; stepIndex: number } + | { type: 'step:complete'; runId: string; jobName: string; stepName: string; stepIndex: number; output: unknown } + | { type: 'log:write'; runId: string; jobName: string; level: 'info' | 'warn' | 'error'; message: string; data: unknown } ``` --- @@ -380,7 +423,7 @@ type DurablyEvent = ### ブラウザ完結モード -``` +```text @coji/durably-react ├── @coji/durably (peer dependency) ├── react (peer dependency, >= 18.0.0) From b1dcdae50f528d64115cb3ecb74de8587fd8fc8f Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 22:59:21 +0900 Subject: [PATCH 006/101] docs: remove AI SDK v5 reference from spec-react.md --- docs/spec-react.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/spec-react.md b/docs/spec-react.md index 83f14e6f..53ad8901 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -4,7 +4,7 @@ `@coji/durably-react` は、Durably を React アプリケーションで使うためのバインディングである。 -Vercel AI SDK v5 のアーキテクチャを参考に、以下の2つの動作モードをサポートする: +以下の2つの動作モードをサポートする: | モード | 説明 | サーバー | クライアント | |--------|------|----------|--------------| From da2cf427914357dcd89072151ada41e0520c65f4 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:15:15 +0900 Subject: [PATCH 007/101] docs: clarify useJobLogs runId requirement and isReady behavior --- docs/spec-react.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/spec-react.md b/docs/spec-react.md index 53ad8901..92086663 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -253,10 +253,11 @@ const { **戻り値の詳細**: -| メソッド | 戻り値 | 説明 | -|-------------------------|-----------------------------------------------|-----------------------------| -| `trigger(input)` | `Promise<{ runId: string }>` | ジョブを実行、Run ID を返す | -| `triggerAndWait(input)` | `Promise<{ runId: string; output: TOutput }>` | 実行して完了を待つ | +| プロパティ | 型 | 説明 | +|-------------------------|-----------------------------------------------|----------------------------------------------------------------------| +| `isReady` | `boolean` | 準備完了（ブラウザ: 初期化完了、サーバー連携: 常に `true`） | +| `trigger(input)` | `Promise<{ runId: string }>` | ジョブを実行、Run ID を返す | +| `triggerAndWait(input)` | `Promise<{ runId: string; output: TOutput }>` | 実行して完了を待つ | #### useJobRun @@ -273,7 +274,7 @@ Run ID のみで購読（trigger なし）。 #### useJobLogs ```tsx -const { logs, clear } = useJobLogs({ runId?, maxLogs? }) +const { logs, clear } = useJobLogs({ runId, maxLogs? }) ``` --- @@ -373,7 +374,7 @@ const { logs, clear } = useJobLogs({ | オプション | 型 | 必須 | 説明 | |------------|----------|------|---------------------------------------| | `api` | `string` | Yes | API エンドポイント | -| `runId` | `string` | - | 特定 Run のログのみ（省略時は全ログ） | +| `runId` | `string` | Yes | Run ID | | `maxLogs` | `number` | - | 保持する最大ログ数（デフォルト: 100） | --- From d3301468d37f4accd9ff077ebd47673d1316a690 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:19:31 +0900 Subject: [PATCH 008/101] docs: rewrite implementation plan for durably-react with dual mode support --- docs/implementation-plan-react.md | 848 +++++++++++++++--------------- 1 file changed, 438 insertions(+), 410 deletions(-) diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md index 09866e5a..e74838bc 100644 --- a/docs/implementation-plan-react.md +++ b/docs/implementation-plan-react.md @@ -4,6 +4,10 @@ この文書は `@coji/durably-react` パッケージの実装計画を定義する。仕様は `docs/spec-react.md` に基づく。 +2つの動作モードをサポート: +- **ブラウザ完結モード**: ブラウザ内で Durably を実行 +- **サーバー連携モード**: サーバーで Durably を実行、クライアントは SSE で購読 + --- ## 1. パッケージ構成 @@ -13,25 +17,26 @@ ``` packages/durably-react/ ├── src/ -│ ├── index.ts # Public exports +│ ├── index.ts # ブラウザ完結モード (DurablyProvider + hooks) +│ ├── client.ts # サーバー連携モード (軽量、@coji/durably 不要) │ ├── context.tsx # DurablyContext & DurablyProvider │ ├── hooks/ │ │ ├── use-durably.ts # useDurably hook -│ │ ├── use-job.ts # useJob hook -│ │ ├── use-job-run.ts # useJobRun hook -│ │ └── use-job-logs.ts # useJobLogs hook -│ └── types.ts # Shared types +│ │ ├── use-job.ts # useJob hook (ブラウザ) +│ │ ├── use-job-run.ts # useJobRun hook (ブラウザ) +│ │ └── use-job-logs.ts # useJobLogs hook (ブラウザ) +│ ├── client/ +│ │ ├── use-job.ts # useJob hook (サーバー連携) +│ │ ├── use-job-run.ts # useJobRun hook (サーバー連携) +│ │ └── use-job-logs.ts # useJobLogs hook (サーバー連携) +│ └── types.ts # 共有型定義 ├── tests/ -│ ├── provider.test.tsx # DurablyProvider tests -│ ├── use-job.test.tsx # useJob tests -│ ├── use-job-run.test.tsx # useJobRun tests -│ ├── use-job-logs.test.tsx # useJobLogs tests -│ └── strict-mode.test.tsx # React StrictMode tests +│ ├── browser/ # ブラウザ完結モードのテスト +│ └── client/ # サーバー連携モードのテスト ├── package.json ├── tsconfig.json ├── tsup.config.ts -├── vitest.config.ts -└── README.md +└── vitest.config.ts ``` ### package.json @@ -40,348 +45,473 @@ packages/durably-react/ { "name": "@coji/durably-react", "version": "0.1.0", - "description": "React bindings for Durably - step-oriented resumable batch execution", "type": "module", - "main": "./dist/index.js", - "types": "./dist/index.d.ts", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" + }, + "./client": { + "types": "./dist/client.d.ts", + "import": "./dist/client.js" } }, - "files": ["dist", "README.md"], "peerDependencies": { - "@coji/durably": ">=0.4.0", "react": ">=18.0.0", "react-dom": ">=18.0.0" }, + "peerDependenciesMeta": { + "@coji/durably": { + "optional": true + } + }, "devDependencies": { "@coji/durably": "workspace:*", "@testing-library/react": "^16.x", - "@types/react": "^19.x", - "@types/react-dom": "^19.x", - "@vitejs/plugin-react": "^5.x", - "jsdom": "^27.x", "react": "^19.x", "react-dom": "^19.x", - "sqlocal": "^0.16.x", - "tsup": "^8.x", - "typescript": "^5.x", "vitest": "^4.x" } } ``` +**ポイント**: +- `@coji/durably` は optional peer dependency（サーバー連携モードでは不要） +- 2つのエントリポイント: `.` と `./client` + --- -## 2. 実装フェーズ +## 2. コア側の要件 -### Phase 0: コア修正 - run:progress イベント追加 +### 既存（実装済み） -**目標**: `step.progress()` 呼び出し時に `run:progress` イベントを emit する +- `durably.on()` が unsubscribe 関数を返す ✅ +- `durably.register(jobDef)` で JobHandle を取得 ✅ +- `run:progress` イベント ✅ (Phase 0 で実装済み) -**タスク**: -1. `packages/durably/src/events.ts` に `RunProgressEvent` インターフェースを追加 - ```ts - interface RunProgressEvent extends BaseEvent { - type: 'run:progress' - runId: string - jobName: string - progress: { current: number; total?: number; message?: string } - } - ``` - -2. `DurablyEvent` union 型に `RunProgressEvent` を追加 - -3. `EventType`, `AnyEventInput` の更新 - -4. `packages/durably/src/context.ts` の `progress()` メソッドを修正 - ```ts - progress(current: number, total?: number, message?: string): void { - const progressData = { current, total, message } - // DB 更新 - storage.updateRun(run.id, { progress: progressData }) - // イベント emit - emit({ - type: 'run:progress', - runId: run.id, - jobName: run.jobName, - progress: progressData, - }) - } - ``` - -5. テスト追加: `run:progress` イベントが正しく emit されることを確認 - -6. ドキュメント更新 - - `website/api/events.md` - `run:progress` イベントをRun Eventsセクションに追加 - - `website/guide/events.md` - Available Events テーブルに追加 - - `packages/durably/docs/llms.md` - Events セクションに `run:progress` を追加 +### 新規（サーバー連携用） -**成果物**: -- `run:progress` イベントが利用可能になる -- 既存のテストがパスする -- ドキュメントが更新されている +1. **`durably.subscribe(runId): ReadableStream`** + - Run のイベントを ReadableStream で返す + - SSE に変換可能 + +2. **`durably.getJob(jobName): JobHandle`** + - 登録済みジョブを名前で取得 + +3. **`createDurablyHandler(durably)`** (`@coji/durably/server`) + - Web 標準の Request/Response を扱うヘルパー --- +## 3. 実装フェーズ + ### Phase 1: 基盤構築 -**目標**: パッケージ構造の作成とビルド環境の整備 +**目標**: パッケージ構造とビルド環境の整備 **タスク**: 1. `packages/durably-react/` ディレクトリ作成 -2. `package.json` 作成（peerDependencies 設定） -3. `tsconfig.json` 作成（durably と同様の設定） -4. `tsup.config.ts` 作成（ESM ビルド） -5. `vitest.config.ts` 作成（jsdom 環境） -6. `src/index.ts` に空のエクスポート -7. ビルド確認 +2. `package.json` 作成（2つのエントリポイント） +3. `tsconfig.json` 作成 +4. `tsup.config.ts` 作成（`index.ts` と `client.ts` を両方ビルド） +5. `vitest.config.ts` 作成 +6. 空のエクスポートでビルド確認 **成果物**: - 空の durably-react パッケージがビルドできる状態 -### Phase 2: Context & Provider 実装 +--- + +### Phase 2: 共通型定義 + +**目標**: 両モードで共有する型を定義 + +**タスク**: +`src/types.ts`: +```ts +// 共通 +export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' + +export interface Progress { + current: number + total?: number + message?: string +} + +export interface LogEntry { + id: string + runId: string + stepName: string | null + level: 'info' | 'warn' | 'error' + message: string + data: unknown + timestamp: string +} + +// useJob 戻り値（共通部分） +export interface UseJobState { + status: RunStatus | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null + currentRunId: string | null +} +``` + +--- + +### Phase 3: ブラウザ完結モード - Provider **目標**: DurablyProvider と useDurably の実装 **タスク**: -1. `src/types.ts` - 共有型定義 - - `DurablyContextValue` - - `DurablyProviderProps` - - `UseJobOptions`, `UseJobLogsOptions` など - -2. `src/context.tsx` - DurablyContext & DurablyProvider - ```tsx - interface DurablyContextValue { - durably: Durably | null - isReady: boolean - error: Error | null - } - - interface DurablyProviderProps { - dialectFactory: () => Dialect - options?: DurablyOptions - autoStart?: boolean // default: true - autoMigrate?: boolean // default: true - children: ReactNode - } - ``` - - **実装ポイント**: - - `useRef` で初期化済みフラグを管理（StrictMode 対応） - - `dialectFactory()` は一度だけ実行 - - マウント時: `createDurably()` → `migrate()` → `start()` - - アンマウント時: `stop()` - -3. `src/hooks/use-durably.ts` - - Context から値を取得するシンプルなフック - - Provider 外で使用時はエラーをスロー + +1. `src/context.tsx`: +```tsx +interface DurablyContextValue { + durably: Durably | null + isReady: boolean + error: Error | null +} + +interface DurablyProviderProps { + dialectFactory: () => Dialect + options?: DurablyOptions + autoStart?: boolean // default: true + autoMigrate?: boolean // default: true + children: ReactNode +} +``` + +**実装ポイント**: +- `useRef` で初期化済みフラグを管理（StrictMode 対応） +- `dialectFactory()` は一度だけ実行 +- マウント時: `createDurably()` → `migrate()` → `start()` +- アンマウント時: `stop()` + +2. `src/hooks/use-durably.ts`: +- Context から値を取得 +- Provider 外で使用時はエラー + +**テスト**: +- 正常な初期化フロー +- StrictMode での二重マウント +- autoStart/autoMigrate オプション + +--- + +### Phase 4: ブラウザ完結モード - useJob + +**目標**: ジョブ実行と状態管理 + +**タスク**: + +`src/hooks/use-job.ts`: +```tsx +function useJob( + job: JobDefinition, + options?: { initialRunId?: string } +): { + isReady: boolean + trigger: (input: TInput) => Promise<{ runId: string }> + triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> + status: RunStatus | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null + isRunning: boolean + isPending: boolean + isCompleted: boolean + isFailed: boolean + currentRunId: string | null + reset: () => void +} +``` + +**実装ポイント**: +- `useDurably()` で context を取得 +- `durably.register(job)` で JobHandle 取得 +- `trigger()` 時に `durably.on()` でイベント購読 +- Run 完了時にリスナー解除 +- `initialRunId` で既存 Run を購読 **テスト**: -- `tests/provider.test.tsx` - - 正常な初期化フロー - - StrictMode での二重マウント - - autoStart/autoMigrate オプション - - アンマウント時のクリーンアップ +- trigger でジョブ実行 +- 状態遷移 (pending → running → completed/failed) +- ログ・進捗の収集 +- アンマウント時のクリーンアップ -### Phase 3: useJob 実装 +--- + +### Phase 5: ブラウザ完結モード - useJobRun & useJobLogs -**目標**: ジョブ実行と状態管理フック +**目標**: 単独の Run 購読とログ購読 **タスク**: -1. `src/hooks/use-job.ts` - ```tsx - interface UseJobState { - status: RunStatus | null - output: TOutput | null - error: string | null - logs: LogEntry[] - progress: Progress | null - currentRunId: string | null - } - - function useJob( - job: JobDefinition, - options?: UseJobOptions - ): { - isReady: boolean - trigger: (input: TInput, opts?: TriggerOptions) => Promise - triggerAndWait: (input: TInput, opts?: TriggerOptions) => Promise<{id: string, output: TOutput}> - ...state, - isRunning: boolean - isPending: boolean - isCompleted: boolean - isFailed: boolean - reset: () => void - } - ``` - - **実装ポイント**: - - `useDurably()` で context を取得 - - `useEffect` で `durably.register(job)` を実行 - - `useRef` で `JobHandle` を保持 - - `trigger()` 呼び出し時にイベントリスナーを登録 - - Run 完了/失敗時にリスナーを解除 - - アンマウント時にもリスナーを解除 - - `initialRunId` オプションで既存 Run を購読 - -2. イベント購読の実装 - ```tsx - // trigger 内でリスナーを登録 - const unsubs = [ - durably.on('run:start', (e) => { - if (e.runId === run.id) setState(s => ({...s, status: 'running'})) - }), - durably.on('run:complete', (e) => { - if (e.runId === run.id) { - setState(s => ({...s, status: 'completed', output: e.output})) - cleanup() - } - }), - durably.on('run:fail', (e) => { - if (e.runId === run.id) { - setState(s => ({...s, status: 'failed', error: e.error})) - cleanup() - } - }), - durably.on('log:write', (e) => { - if (e.runId === run.id) { - setState(s => ({...s, logs: [...s.logs, e]})) - } - }), - ] - ``` + +1. `src/hooks/use-job-run.ts`: +```tsx +function useJobRun(options: { runId: string | null }): { + status: RunStatus | null + output: unknown + error: string | null + logs: LogEntry[] + progress: Progress | null +} +``` + +2. `src/hooks/use-job-logs.ts`: +```tsx +function useJobLogs(options: { runId: string; maxLogs?: number }): { + logs: LogEntry[] + clear: () => void +} +``` **テスト**: -- `tests/use-job.test.tsx` - - trigger でジョブ実行 - - 状態更新（pending → running → completed） - - エラー時の状態 - - ログ収集 - - 進捗更新 - - アンマウント時のリスナー解除 - - initialRunId による復元 +- 既存 Run の購読 +- null runId の扱い +- maxLogs 制限 + +--- -### Phase 4: useJobRun & useJobLogs 実装 +### Phase 6: コア拡張 - サーバー連携用 API -**目標**: 単独の Run 購読とログ購読フック +**目標**: `@coji/durably` にサーバー連携用 API を追加 **タスク**: -1. `src/hooks/use-job-run.ts` - - `runId` を受け取り、その Run の状態を購読 - - `useJob` の戻り値から `trigger` 系を除いたもの - - DB ポーリングでステータス取得（イベントだけでは初期状態が取れないため） - - ```tsx - function useJobRun(runId: string | null): { - status: RunStatus | null - output: unknown - error: string | null - logs: LogEntry[] - progress: Progress | null - } - ``` - -2. `src/hooks/use-job-logs.ts` - - グローバルまたは特定 Run のログを購読 - - `maxLogs` でログ数を制限 - - ```tsx - interface UseJobLogsOptions { - runId?: string - maxLogs?: number // default: 100 - } - - function useJobLogs(options?: UseJobLogsOptions): { - logs: LogEntry[] - clear: () => void - } - ``` + +1. `packages/durably/src/durably.ts` に追加: +```ts +// 登録済みジョブを名前で取得 +getJob(jobName: string): JobHandle | undefined + +// Run のイベントを ReadableStream で返す +subscribe(runId: string): ReadableStream +``` + +2. `packages/durably/src/server.ts` 新規作成: +```ts +export function createDurablyHandler(durably: Durably) { + return { + // POST: ジョブ起動 + async trigger(request: Request): Promise { + const { jobName, input } = await request.json() + const job = durably.getJob(jobName) + if (!job) return new Response('Job not found', { status: 404 }) + const run = await job.trigger(input) + return Response.json({ runId: run.id }) + }, + + // GET: SSE 購読 + subscribe(request: Request): Response { + const url = new URL(request.url) + const runId = url.searchParams.get('runId') + if (!runId) return new Response('Missing runId', { status: 400 }) + + const stream = durably.subscribe(runId) + return new Response(stream, { + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + 'Connection': 'keep-alive', + }, + }) + }, + } +} +``` + +3. `packages/durably/package.json` の exports に追加: +```json +"./server": { + "types": "./dist/server.d.ts", + "import": "./dist/server.js" +} +``` **テスト**: -- `tests/use-job-run.test.tsx` - - 既存 Run の購読 - - null runId の扱い - - 状態更新の購読 +- `getJob()` で登録済みジョブを取得 +- `subscribe()` が ReadableStream を返す +- `createDurablyHandler` の trigger/subscribe -- `tests/use-job-logs.test.tsx` - - ログ収集 - - maxLogs 制限 - - clear 機能 - - runId フィルタリング +--- -### Phase 5: 型安全性とエッジケース +### Phase 7: サーバー連携モード - useJob -**目標**: 型推論の改善とエッジケース対応 +**目標**: サーバー連携用の軽量 useJob **タスク**: -1. 型推論の確認 - - `useJob` の `output` が `TOutput` として型推論されること - - `trigger` の引数が `TInput` として型推論されること -2. エッジケース対応 - - Provider 外での hook 使用時のエラーメッセージ - - `isReady: false` 時の `trigger()` 呼び出しでエラー - - 同じ `JobDefinition` を複数回登録した場合の動作 - - コンポーネントのアンマウント中に trigger が呼ばれた場合 +`src/client/use-job.ts`: +```tsx +function useJob(options: { + api: string + jobName: string + initialRunId?: string +}): { + isReady: true // 常に true + trigger: (input: TInput) => Promise<{ runId: string }> + triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> + status: RunStatus | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null + isRunning: boolean + isPending: boolean + isCompleted: boolean + isFailed: boolean + currentRunId: string | null + reset: () => void +} +``` + +**実装ポイント**: +- `fetch()` で trigger +- `EventSource` で SSE 購読 +- `@coji/durably` に依存しない +- `isReady` は常に `true` + +**テスト**: +- fetch mock で trigger テスト +- EventSource mock で購読テスト -3. SSR 対応 - - サーバーサイドでは `isReady: false` を返す - - `typeof window === 'undefined'` チェック +--- -### Phase 6: ドキュメントと例 +### Phase 8: サーバー連携モード - useJobRun & useJobLogs -**目標**: README とサンプルコードの整備 +**目標**: サーバー連携用の useJobRun と useJobLogs **タスク**: -1. `packages/durably-react/README.md` 作成 - - インストール方法 - - 基本的な使い方 - - API リファレンス -2. `examples/react` の更新 - - `@coji/durably-react` を使用するように変更 - - カスタム hook を削除 +1. `src/client/use-job-run.ts`: +```tsx +function useJobRun(options: { + api: string + runId: string +}): { + status: RunStatus | null + output: unknown + error: string | null + logs: LogEntry[] + progress: Progress | null +} +``` + +2. `src/client/use-job-logs.ts`: +```tsx +function useJobLogs(options: { + api: string + runId: string + maxLogs?: number +}): { + logs: LogEntry[] + clear: () => void +} +``` + +**実装ポイント**: +- `EventSource` で SSE 購読 +- API エンドポイントからイベントを受信 + +--- + +### Phase 9: エントリポイント整備 + +**目標**: 公開 API の整備 + +**タスク**: + +1. `src/index.ts` (ブラウザ完結モード): +```ts +// Provider +export { DurablyProvider } from './context' +export type { DurablyProviderProps } from './types' + +// Hooks +export { useDurably } from './hooks/use-durably' +export { useJob } from './hooks/use-job' +export { useJobRun } from './hooks/use-job-run' +export { useJobLogs } from './hooks/use-job-logs' + +// Types +export type { Progress, LogEntry, RunStatus } from './types' +``` + +2. `src/client.ts` (サーバー連携モード): +```ts +// Hooks only (no Provider needed) +export { useJob } from './client/use-job' +export { useJobRun } from './client/use-job-run' +export { useJobLogs } from './client/use-job-logs' + +// Types +export type { Progress, LogEntry, RunStatus } from './types' +``` -3. `packages/durably-react/docs/llms.md` 作成 - - LLM 向けドキュメント +--- -### Phase 7: テストと品質保証 +### Phase 10: ドキュメントと例 -**目標**: 完全なテストカバレッジと品質確認 +**目標**: README とサンプルの整備 **タスク**: -1. テストの実行と修正 - - jsdom 環境でのテスト - - StrictMode テスト +1. `packages/durably-react/README.md` 作成 +2. `packages/durably-react/docs/llms.md` 作成 +3. `examples/react-browser/` - ブラウザ完結モードの例 +4. `examples/react-server/` - サーバー連携モードの例 -2. TypeScript 型チェック -3. ESLint / Biome チェック -4. ビルド確認 +--- -### Phase 8: パブリッシュ準備 +### Phase 11: テストと品質保証 -**目標**: npm パブリッシュの準備（パブリッシュは手動で行う） +**目標**: 完全なテストカバレッジ + +**タスク**: +1. ブラウザモードのテスト (jsdom) +2. サーバー連携モードのテスト (fetch/EventSource mock) +3. StrictMode テスト +4. TypeScript 型チェック +5. Biome lint + +--- + +### Phase 12: パブリッシュ準備 + +**目標**: npm パブリッシュの準備 **タスク**: 1. version を 0.1.0 に設定 2. CHANGELOG.md 作成 -3. ルートの package.json にスクリプト追加 - ```json - "test:react-pkg": "pnpm --filter @coji/durably-react test" - ``` -4. 最終ビルド確認 -5. dry-run で publish 確認 (`pnpm publish --dry-run`) +3. `pnpm publish --dry-run` で確認 --- -## 3. 技術的な決定事項 +## 4. 実装順序のまとめ -### StrictMode 対応 +| Phase | 内容 | 依存 | +|-------|------|------| +| 1 | 基盤構築 | - | +| 2 | 共通型定義 | Phase 1 | +| 3 | ブラウザ: Provider | Phase 2 | +| 4 | ブラウザ: useJob | Phase 3 | +| 5 | ブラウザ: useJobRun, useJobLogs | Phase 3 | +| 6 | コア拡張: サーバー連携用 API | - | +| 7 | サーバー連携: useJob | Phase 2, 6 | +| 8 | サーバー連携: useJobRun, useJobLogs | Phase 7 | +| 9 | エントリポイント整備 | Phase 5, 8 | +| 10 | ドキュメント | Phase 9 | +| 11 | テスト・品質保証 | Phase 10 | +| 12 | パブリッシュ準備 | Phase 11 | + +--- + +## 5. 技術的な決定事項 -React 19 の StrictMode では、開発モードで useEffect が二重に実行される。以下のパターンで対応: +### StrictMode 対応 ```tsx function DurablyProvider({ dialectFactory, children }: Props) { @@ -389,13 +519,11 @@ function DurablyProvider({ dialectFactory, children }: Props) { const initializedRef = useRef(false) useEffect(() => { - // 二重初期化を防止 if (initializedRef.current) return initializedRef.current = true const dialect = dialectFactory() const durably = createDurably({ dialect }) - let cancelled = false async function init() { @@ -405,9 +533,7 @@ function DurablyProvider({ dialectFactory, children }: Props) { durably.start() setState({ durably, isReady: true, error: null }) } catch (error) { - if (!cancelled) { - setState(s => ({ ...s, error: error as Error })) - } + if (!cancelled) setState(s => ({ ...s, error: error as Error })) } } @@ -416,7 +542,6 @@ function DurablyProvider({ dialectFactory, children }: Props) { return () => { cancelled = true durably.stop() - // initializedRef はリセットしない（再マウント時に再初期化しない） } }, [dialectFactory]) @@ -424,158 +549,61 @@ function DurablyProvider({ dialectFactory, children }: Props) { } ``` -### イベントリスナーのライフサイクル - -``` -trigger() 呼び出し - ↓ -リスナー登録 (run:start, run:complete, run:fail, log:write) - ↓ -イベント受信 → 状態更新 - ↓ -run:complete または run:fail - ↓ -リスナー解除 (cleanup) - -※ コンポーネントアンマウント時も cleanup を呼ぶ -``` - -### dialectFactory パターン - -仕様書の説明通り、`dialect` を直接渡すと毎回新しいインスタンスが生成されてしまう問題を回避するため、`dialectFactory` 関数を受け取る: +### SSE 購読の実装 ```tsx -// 悪い例: 毎回新しい dialect が生成される - - -// 良い例: 一度だけ実行される - new SQLocalKysely('app.sqlite3').dialect}> -``` - ---- - -## 4. コア側の要件確認 - -仕様書に記載のコア側要件を確認: - -### 1. イベントリスナーの解除機能 ✅ - -現在のコードで確認済み: -```ts -// packages/durably/src/events.ts -export type Unsubscribe = () => void - -// Durably.on() は Unsubscribe を返す -on(type: T, listener: EventListener): Unsubscribe -``` - -### 2. register メソッド ✅ - -現在のコードで確認済み: -```ts -// packages/durably/src/durably.ts -register( - jobDef: JobDefinition, -): JobHandle -``` - -→ コア側の変更は不要。現在のAPIで実装可能。 - -### 3. progress イベント ⚠️ (Phase 0 で対応) - -現在のコアには `run:progress` イベントが存在しない。Phase 0 で追加する。 +// サーバー連携モードの useJob 内部 +function subscribeToRun(runId: string) { + const eventSource = new EventSource(`${api}?runId=${runId}`) + + eventSource.onmessage = (event) => { + const data = JSON.parse(event.data) as DurablyEvent + + switch (data.type) { + case 'run:start': + setState(s => ({ ...s, status: 'running' })) + break + case 'run:complete': + setState(s => ({ ...s, status: 'completed', output: data.output })) + eventSource.close() + break + case 'run:fail': + setState(s => ({ ...s, status: 'failed', error: data.error })) + eventSource.close() + break + case 'run:progress': + setState(s => ({ ...s, progress: data.progress })) + break + case 'log:write': + setState(s => ({ ...s, logs: [...s.logs, data] })) + break + } + } -**追加するイベント**: -```ts -interface RunProgressEvent extends BaseEvent { - type: 'run:progress' - runId: string - jobName: string - progress: { current: number; total?: number; message?: string } + return () => eventSource.close() } ``` -これにより、React 側でリアルタイムに progress を購読できるようになる。 - ---- - -## 5. 依存関係 - -``` -@coji/durably-react -├── @coji/durably (peer dependency >= 0.4.0) -├── react (peer dependency >= 18.0.0) -└── react-dom (peer dependency >= 18.0.0) - -開発時: -├── kysely (テストで必要) -├── sqlocal (テストで必要) -└── zod (テストで必要) -``` - ---- - -## 6. 公開 API - -```ts -// @coji/durably-react - -// Context & Provider -export { DurablyProvider } from './context' -export type { DurablyProviderProps } from './types' - -// Hooks -export { useDurably } from './hooks/use-durably' -export { useJob } from './hooks/use-job' -export { useJobRun } from './hooks/use-job-run' -export { useJobLogs } from './hooks/use-job-logs' - -// Types (re-export convenience types) -export type { - UseJobOptions, - UseJobResult, - UseJobRunResult, - UseJobLogsOptions, - UseJobLogsResult, -} from './types' -``` - ---- - -## 7. 実装順序のまとめ - -| Phase | 内容 | 依存 | -|-------|------|------| -| **0** | **コア修正: run:progress イベント追加** | - | -| 1 | 基盤構築 | Phase 0 | -| 2 | DurablyProvider, useDurably | Phase 1 | -| 3 | useJob | Phase 2 | -| 4 | useJobRun, useJobLogs | Phase 2 | -| 5 | 型安全性、エッジケース | Phase 3, 4 | -| 6 | ドキュメント、例 | Phase 5 | -| 7 | テスト、品質保証 | Phase 6 | -| 8 | パブリッシュ準備 | Phase 7 | - --- -## 8. リスクと対策 +## 6. リスクと対策 | リスク | 対策 | |--------|------| | StrictMode での予期せぬ動作 | 二重マウントテストを十分に行う | -| イベントリスナーのメモリリーク | useEffect cleanup で確実に解除 | +| EventSource の再接続ループ | エラー時の適切なハンドリング | +| SSE が終了しない | Run 完了時に必ず close() | | 型推論が複雑で失敗 | ジェネリクスの型テストを追加 | -| ブラウザ環境でのテスト失敗 | jsdom で基本テスト、必要なら Playwright | --- -## 9. 完了条件 +## 7. 完了条件 -- [ ] コア: `run:progress` イベントが追加されている -- [ ] すべてのフック（useDurably, useJob, useJobRun, useJobLogs）が実装されている -- [ ] DurablyProvider が StrictMode で正しく動作する -- [ ] 型推論が正しく機能する（TypeScript エラーなし） +- [ ] ブラウザ完結モードの全フックが実装されている +- [ ] サーバー連携モードの全フックが実装されている +- [ ] コア側に `getJob`, `subscribe`, `createDurablyHandler` が追加されている +- [ ] 2つのエントリポイント (`.` と `./client`) が機能する +- [ ] StrictMode で正しく動作する +- [ ] 型推論が正しく機能する - [ ] テストがすべてパスする - [ ] ドキュメントが整備されている -- [ ] examples/react が新パッケージを使用するように更新されている -- [ ] `pnpm publish --dry-run` が成功する From dbaa0f2a9e8cb32c2d4b8f7e5a9e5830a503565f Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:22:50 +0900 Subject: [PATCH 009/101] docs: rewrite implementation plan with TDD approach (30 phases) --- docs/implementation-plan-react.md | 1020 ++++++++++++++++++----------- 1 file changed, 645 insertions(+), 375 deletions(-) diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md index e74838bc..0abc5050 100644 --- a/docs/implementation-plan-react.md +++ b/docs/implementation-plan-react.md @@ -4,6 +4,11 @@ この文書は `@coji/durably-react` パッケージの実装計画を定義する。仕様は `docs/spec-react.md` に基づく。 +**開発手法**: TDD（テスト駆動開発） +- 各フェーズで「テスト → 実装 → リファクタ」のサイクルを回す +- 小さなステップで確実に進める +- 機能単位で垂直スライス + 2つの動作モードをサポート: - **ブラウザ完結モード**: ブラウザ内で Durably を実行 - **サーバー連携モード**: サーバーで Durably を実行、クライアントは SSE で購読 @@ -17,18 +22,11 @@ ``` packages/durably-react/ ├── src/ -│ ├── index.ts # ブラウザ完結モード (DurablyProvider + hooks) -│ ├── client.ts # サーバー連携モード (軽量、@coji/durably 不要) -│ ├── context.tsx # DurablyContext & DurablyProvider -│ ├── hooks/ -│ │ ├── use-durably.ts # useDurably hook -│ │ ├── use-job.ts # useJob hook (ブラウザ) -│ │ ├── use-job-run.ts # useJobRun hook (ブラウザ) -│ │ └── use-job-logs.ts # useJobLogs hook (ブラウザ) -│ ├── client/ -│ │ ├── use-job.ts # useJob hook (サーバー連携) -│ │ ├── use-job-run.ts # useJobRun hook (サーバー連携) -│ │ └── use-job-logs.ts # useJobLogs hook (サーバー連携) +│ ├── index.ts # ブラウザ完結モード +│ ├── client.ts # サーバー連携モード +│ ├── context.tsx # DurablyProvider +│ ├── hooks/ # ブラウザ完結モード用 hooks +│ ├── client/ # サーバー連携モード用 hooks │ └── types.ts # 共有型定義 ├── tests/ │ ├── browser/ # ブラウザ完結モードのテスト @@ -64,21 +62,10 @@ packages/durably-react/ "@coji/durably": { "optional": true } - }, - "devDependencies": { - "@coji/durably": "workspace:*", - "@testing-library/react": "^16.x", - "react": "^19.x", - "react-dom": "^19.x", - "vitest": "^4.x" } } ``` -**ポイント**: -- `@coji/durably` は optional peer dependency（サーバー連携モードでは不要） -- 2つのエントリポイント: `.` と `./client` - --- ## 2. コア側の要件 @@ -87,49 +74,48 @@ packages/durably-react/ - `durably.on()` が unsubscribe 関数を返す ✅ - `durably.register(jobDef)` で JobHandle を取得 ✅ -- `run:progress` イベント ✅ (Phase 0 で実装済み) +- `run:progress` イベント ✅ ### 新規（サーバー連携用） -1. **`durably.subscribe(runId): ReadableStream`** - - Run のイベントを ReadableStream で返す - - SSE に変換可能 +1. `durably.getJob(jobName): JobHandle | undefined` +2. `durably.subscribe(runId): ReadableStream` +3. `createDurablyHandler(durably)` (`@coji/durably/server`) -2. **`durably.getJob(jobName): JobHandle`** - - 登録済みジョブを名前で取得 +--- -3. **`createDurablyHandler(durably)`** (`@coji/durably/server`) - - Web 標準の Request/Response を扱うヘルパー +## 3. 実装フェーズ（TDD） ---- +各フェーズで以下のサイクルを回す: +1. **Red**: テストを書く（失敗する） +2. **Green**: 最小限の実装で通す +3. **Refactor**: コードを整理 -## 3. 実装フェーズ +--- ### Phase 1: 基盤構築 -**目標**: パッケージ構造とビルド環境の整備 +**目標**: パッケージ構造とビルド環境 **タスク**: -1. `packages/durably-react/` ディレクトリ作成 -2. `package.json` 作成（2つのエントリポイント） -3. `tsconfig.json` 作成 -4. `tsup.config.ts` 作成（`index.ts` と `client.ts` を両方ビルド） -5. `vitest.config.ts` 作成 +1. ディレクトリ作成 +2. package.json（2エントリポイント） +3. tsconfig.json +4. tsup.config.ts +5. vitest.config.ts 6. 空のエクスポートでビルド確認 -**成果物**: -- 空の durably-react パッケージがビルドできる状態 +**成果物**: 空パッケージがビルドできる --- -### Phase 2: 共通型定義 +### Phase 2: 型定義 -**目標**: 両モードで共有する型を定義 +**目標**: 共有型の定義 **タスク**: `src/types.ts`: ```ts -// 共通 export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' export interface Progress { @@ -147,463 +133,747 @@ export interface LogEntry { data: unknown timestamp: string } - -// useJob 戻り値（共通部分） -export interface UseJobState { - status: RunStatus | null - output: TOutput | null - error: string | null - logs: LogEntry[] - progress: Progress | null - currentRunId: string | null -} ``` +**成果物**: 型定義ファイル + --- -### Phase 3: ブラウザ完結モード - Provider +### Phase 3: DurablyProvider - 初期化 -**目標**: DurablyProvider と useDurably の実装 +**目標**: Provider が Durably を初期化できる -**タスク**: +**テスト（Red）**: +```tsx +// tests/browser/provider.test.tsx +describe('DurablyProvider', () => { + it('initializes Durably and provides isReady=true', async () => { + const dialectFactory = () => createMockDialect() + + const { result } = renderHook(() => useDurably(), { + wrapper: ({ children }) => ( + + {children} + + ), + }) + + await waitFor(() => { + expect(result.current.isReady).toBe(true) + }) + expect(result.current.durably).not.toBeNull() + }) +}) +``` + +**実装（Green）**: +- `src/context.tsx`: DurablyContext, DurablyProvider +- `src/hooks/use-durably.ts`: useDurably + +**Refactor**: StrictMode 対応 -1. `src/context.tsx`: +--- + +### Phase 4: DurablyProvider - オプション + +**目標**: autoStart, autoMigrate オプション + +**テスト（Red）**: ```tsx -interface DurablyContextValue { - durably: Durably | null - isReady: boolean - error: Error | null -} +it('respects autoStart=false', async () => { + // start() が呼ばれないことを確認 +}) -interface DurablyProviderProps { - dialectFactory: () => Dialect - options?: DurablyOptions - autoStart?: boolean // default: true - autoMigrate?: boolean // default: true - children: ReactNode -} +it('respects autoMigrate=false', async () => { + // migrate() が呼ばれないことを確認 +}) ``` -**実装ポイント**: -- `useRef` で初期化済みフラグを管理（StrictMode 対応） -- `dialectFactory()` は一度だけ実行 -- マウント時: `createDurably()` → `migrate()` → `start()` -- アンマウント時: `stop()` +**実装（Green）**: オプション処理 + +--- + +### Phase 5: DurablyProvider - クリーンアップ -2. `src/hooks/use-durably.ts`: -- Context から値を取得 -- Provider 外で使用時はエラー +**目標**: アンマウント時に stop() が呼ばれる -**テスト**: -- 正常な初期化フロー -- StrictMode での二重マウント -- autoStart/autoMigrate オプション +**テスト（Red）**: +```tsx +it('calls stop() on unmount', async () => { + const stopSpy = vi.fn() + // ... + unmount() + expect(stopSpy).toHaveBeenCalled() +}) +``` + +**実装（Green）**: cleanup 処理 --- -### Phase 4: ブラウザ完結モード - useJob +### Phase 6: DurablyProvider - StrictMode -**目標**: ジョブ実行と状態管理 +**目標**: StrictMode で二重初期化しない -**タスク**: +**テスト（Red）**: +```tsx +it('does not double-initialize in StrictMode', async () => { + const dialectFactory = vi.fn(() => createMockDialect()) + + render( + + + + + + ) + + await waitFor(() => {}) + expect(dialectFactory).toHaveBeenCalledTimes(1) +}) +``` + +**実装（Green）**: useRef で初期化フラグ管理 + +--- -`src/hooks/use-job.ts`: +### Phase 7: useJob - trigger + +**目標**: trigger でジョブを実行し runId を返す + +**テスト（Red）**: ```tsx -function useJob( - job: JobDefinition, - options?: { initialRunId?: string } -): { - isReady: boolean - trigger: (input: TInput) => Promise<{ runId: string }> - triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> - status: RunStatus | null - output: TOutput | null - error: string | null - logs: LogEntry[] - progress: Progress | null - isRunning: boolean - isPending: boolean - isCompleted: boolean - isFailed: boolean - currentRunId: string | null - reset: () => void -} +describe('useJob', () => { + it('returns trigger function that executes job', async () => { + const { result } = renderHook(() => useJob(testJob), { wrapper }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const { runId } = await result.current.trigger({ input: 'test' }) + + expect(runId).toBeDefined() + expect(typeof runId).toBe('string') + }) +}) ``` -**実装ポイント**: -- `useDurably()` で context を取得 -- `durably.register(job)` で JobHandle 取得 -- `trigger()` 時に `durably.on()` でイベント購読 -- Run 完了時にリスナー解除 -- `initialRunId` で既存 Run を購読 +**実装（Green）**: +- `src/hooks/use-job.ts`: trigger 関数のみ -**テスト**: -- trigger でジョブ実行 -- 状態遷移 (pending → running → completed/failed) -- ログ・進捗の収集 -- アンマウント時のクリーンアップ +--- + +### Phase 8: useJob - status 購読 + +**目標**: trigger 後に status が更新される + +**テスト（Red）**: +```tsx +it('updates status from pending to running to completed', async () => { + const { result } = renderHook(() => useJob(testJob), { wrapper }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + expect(result.current.status).toBeNull() + + act(() => { + result.current.trigger({ input: 'test' }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('completed') + }) +}) +``` + +**実装（Green）**: イベント購読で status 更新 --- -### Phase 5: ブラウザ完結モード - useJobRun & useJobLogs +### Phase 9: useJob - output 取得 -**目標**: 単独の Run 購読とログ購読 +**目標**: 完了時に output が取得できる -**タスク**: +**テスト（Red）**: +```tsx +it('provides output when completed', async () => { + const { result } = renderHook(() => useJob(testJob), { wrapper }) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.output).toEqual({ success: true }) + }) +}) +``` + +**実装（Green）**: run:complete で output を設定 -1. `src/hooks/use-job-run.ts`: +--- + +### Phase 10: useJob - error 取得 + +**目標**: 失敗時に error が取得できる + +**テスト（Red）**: ```tsx -function useJobRun(options: { runId: string | null }): { - status: RunStatus | null - output: unknown - error: string | null - logs: LogEntry[] - progress: Progress | null -} +it('provides error when failed', async () => { + const { result } = renderHook(() => useJob(failingJob), { wrapper }) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.status).toBe('failed') + expect(result.current.error).toBe('Something went wrong') + }) +}) ``` -2. `src/hooks/use-job-logs.ts`: +**実装（Green）**: run:fail で error を設定 + +--- + +### Phase 11: useJob - progress 購読 + +**目標**: progress が更新される + +**テスト（Red）**: ```tsx -function useJobLogs(options: { runId: string; maxLogs?: number }): { - logs: LogEntry[] - clear: () => void -} +it('updates progress during execution', async () => { + const { result } = renderHook(() => useJob(progressJob), { wrapper }) + + result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.progress).toEqual({ + current: 1, + total: 3, + message: 'Step 1', + }) + }) +}) ``` -**テスト**: -- 既存 Run の購読 -- null runId の扱い -- maxLogs 制限 +**実装（Green）**: run:progress で progress を設定 --- -### Phase 6: コア拡張 - サーバー連携用 API +### Phase 12: useJob - logs 購読 -**目標**: `@coji/durably` にサーバー連携用 API を追加 +**目標**: logs が収集される -**タスク**: +**テスト（Red）**: +```tsx +it('collects logs during execution', async () => { + const { result } = renderHook(() => useJob(loggingJob), { wrapper }) -1. `packages/durably/src/durably.ts` に追加: -```ts -// 登録済みジョブを名前で取得 -getJob(jobName: string): JobHandle | undefined + await result.current.trigger({ input: 'test' }) -// Run のイベントを ReadableStream で返す -subscribe(runId: string): ReadableStream + await waitFor(() => { + expect(result.current.logs).toHaveLength(2) + expect(result.current.logs[0].message).toBe('Starting') + }) +}) ``` -2. `packages/durably/src/server.ts` 新規作成: -```ts -export function createDurablyHandler(durably: Durably) { - return { - // POST: ジョブ起動 - async trigger(request: Request): Promise { - const { jobName, input } = await request.json() - const job = durably.getJob(jobName) - if (!job) return new Response('Job not found', { status: 404 }) - const run = await job.trigger(input) - return Response.json({ runId: run.id }) - }, +**実装（Green）**: log:write で logs に追加 - // GET: SSE 購読 - subscribe(request: Request): Response { - const url = new URL(request.url) - const runId = url.searchParams.get('runId') - if (!runId) return new Response('Missing runId', { status: 400 }) - - const stream = durably.subscribe(runId) - return new Response(stream, { - headers: { - 'Content-Type': 'text/event-stream', - 'Cache-Control': 'no-cache', - 'Connection': 'keep-alive', - }, - }) - }, - } -} -``` +--- -3. `packages/durably/package.json` の exports に追加: -```json -"./server": { - "types": "./dist/server.d.ts", - "import": "./dist/server.js" -} +### Phase 13: useJob - boolean ヘルパー + +**目標**: isRunning, isPending, isCompleted, isFailed + +**テスト（Red）**: +```tsx +it('provides boolean helpers', async () => { + const { result } = renderHook(() => useJob(testJob), { wrapper }) + + expect(result.current.isRunning).toBe(false) + expect(result.current.isPending).toBe(false) + + act(() => { + result.current.trigger({ input: 'test' }) + }) + + // pending 状態 + expect(result.current.isPending).toBe(true) + + await waitFor(() => { + expect(result.current.isCompleted).toBe(true) + }) +}) ``` -**テスト**: -- `getJob()` で登録済みジョブを取得 -- `subscribe()` が ReadableStream を返す -- `createDurablyHandler` の trigger/subscribe +**実装（Green）**: 派生状態を計算 --- -### Phase 7: サーバー連携モード - useJob +### Phase 14: useJob - triggerAndWait -**目標**: サーバー連携用の軽量 useJob +**目標**: 完了まで待つ関数 -**タスク**: +**テスト（Red）**: +```tsx +it('triggerAndWait resolves with output', async () => { + const { result } = renderHook(() => useJob(testJob), { wrapper }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const { runId, output } = await result.current.triggerAndWait({ input: 'test' }) + + expect(runId).toBeDefined() + expect(output).toEqual({ success: true }) +}) +``` + +**実装（Green）**: Promise でラップ + +--- + +### Phase 15: useJob - reset -`src/client/use-job.ts`: +**目標**: 状態をリセット + +**テスト（Red）**: ```tsx -function useJob(options: { - api: string - jobName: string - initialRunId?: string -}): { - isReady: true // 常に true - trigger: (input: TInput) => Promise<{ runId: string }> - triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> - status: RunStatus | null - output: TOutput | null - error: string | null - logs: LogEntry[] - progress: Progress | null - isRunning: boolean - isPending: boolean - isCompleted: boolean - isFailed: boolean - currentRunId: string | null - reset: () => void -} +it('reset clears all state', async () => { + const { result } = renderHook(() => useJob(testJob), { wrapper }) + + await result.current.trigger({ input: 'test' }) + await waitFor(() => expect(result.current.isCompleted).toBe(true)) + + act(() => { + result.current.reset() + }) + + expect(result.current.status).toBeNull() + expect(result.current.output).toBeNull() + expect(result.current.currentRunId).toBeNull() +}) ``` -**実装ポイント**: -- `fetch()` で trigger -- `EventSource` で SSE 購読 -- `@coji/durably` に依存しない -- `isReady` は常に `true` +**実装（Green）**: 初期状態に戻す + +--- -**テスト**: -- fetch mock で trigger テスト -- EventSource mock で購読テスト +### Phase 16: useJob - initialRunId + +**目標**: 既存 Run を購読 + +**テスト（Red）**: +```tsx +it('subscribes to existing run with initialRunId', async () => { + // 先にジョブを実行して runId を取得 + const existingRunId = await triggerJobDirectly() + + const { result } = renderHook( + () => useJob(testJob, { initialRunId: existingRunId }), + { wrapper } + ) + + await waitFor(() => { + expect(result.current.currentRunId).toBe(existingRunId) + }) +}) +``` + +**実装（Green）**: 初期化時に購読開始 --- -### Phase 8: サーバー連携モード - useJobRun & useJobLogs +### Phase 17: useJob - クリーンアップ -**目標**: サーバー連携用の useJobRun と useJobLogs +**目標**: アンマウント時にリスナー解除 -**タスク**: +**テスト（Red）**: +```tsx +it('unsubscribes on unmount', async () => { + const { result, unmount } = renderHook(() => useJob(testJob), { wrapper }) + + await result.current.trigger({ input: 'test' }) + + // まだ running 中にアンマウント + unmount() + + // メモリリークがないことを確認（エラーが出ないこと） +}) +``` + +**実装（Green）**: useEffect の cleanup で解除 + +--- + +### Phase 18: useJobRun - 基本 -1. `src/client/use-job-run.ts`: +**目標**: runId で購読 + +**テスト（Red）**: ```tsx -function useJobRun(options: { - api: string - runId: string -}): { - status: RunStatus | null - output: unknown - error: string | null - logs: LogEntry[] - progress: Progress | null -} +describe('useJobRun', () => { + it('subscribes to run by id', async () => { + const runId = await triggerJobDirectly() + + const { result } = renderHook( + () => useJobRun({ runId }), + { wrapper } + ) + + await waitFor(() => { + expect(result.current.status).not.toBeNull() + }) + }) + + it('handles null runId', () => { + const { result } = renderHook( + () => useJobRun({ runId: null }), + { wrapper } + ) + + expect(result.current.status).toBeNull() + }) +}) ``` -2. `src/client/use-job-logs.ts`: +**実装（Green）**: `src/hooks/use-job-run.ts` + +--- + +### Phase 19: useJobLogs - 基本 + +**目標**: ログを購読 + +**テスト（Red）**: ```tsx -function useJobLogs(options: { - api: string - runId: string - maxLogs?: number -}): { - logs: LogEntry[] - clear: () => void -} +describe('useJobLogs', () => { + it('collects logs for run', async () => { + const runId = await triggerLoggingJob() + + const { result } = renderHook( + () => useJobLogs({ runId }), + { wrapper } + ) + + await waitFor(() => { + expect(result.current.logs.length).toBeGreaterThan(0) + }) + }) + + it('respects maxLogs limit', async () => { + const { result } = renderHook( + () => useJobLogs({ runId, maxLogs: 5 }), + { wrapper } + ) + + // 多くのログを生成しても 5 件まで + await waitFor(() => { + expect(result.current.logs.length).toBeLessThanOrEqual(5) + }) + }) + + it('clear removes all logs', async () => { + const { result } = renderHook( + () => useJobLogs({ runId }), + { wrapper } + ) + + await waitFor(() => expect(result.current.logs.length).toBeGreaterThan(0)) + + act(() => { + result.current.clear() + }) + + expect(result.current.logs).toHaveLength(0) + }) +}) ``` -**実装ポイント**: -- `EventSource` で SSE 購読 -- API エンドポイントからイベントを受信 +**実装（Green）**: `src/hooks/use-job-logs.ts` --- -### Phase 9: エントリポイント整備 +### Phase 20: コア拡張 - getJob -**目標**: 公開 API の整備 +**目標**: 登録済みジョブを名前で取得 -**タスク**: +**テスト（Red）**: +```tsx +// packages/durably/tests/durably.test.ts +describe('getJob', () => { + it('returns registered job by name', () => { + const durably = createDurably({ dialect }) + durably.register(testJob) -1. `src/index.ts` (ブラウザ完結モード): -```ts -// Provider -export { DurablyProvider } from './context' -export type { DurablyProviderProps } from './types' - -// Hooks -export { useDurably } from './hooks/use-durably' -export { useJob } from './hooks/use-job' -export { useJobRun } from './hooks/use-job-run' -export { useJobLogs } from './hooks/use-job-logs' - -// Types -export type { Progress, LogEntry, RunStatus } from './types' -``` + const job = durably.getJob('test-job') -2. `src/client.ts` (サーバー連携モード): -```ts -// Hooks only (no Provider needed) -export { useJob } from './client/use-job' -export { useJobRun } from './client/use-job-run' -export { useJobLogs } from './client/use-job-logs' + expect(job).toBeDefined() + expect(job?.name).toBe('test-job') + }) + + it('returns undefined for unknown job', () => { + const durably = createDurably({ dialect }) -// Types -export type { Progress, LogEntry, RunStatus } from './types' + expect(durably.getJob('unknown')).toBeUndefined() + }) +}) ``` +**実装（Green）**: `packages/durably/src/durably.ts` に追加 + --- -### Phase 10: ドキュメントと例 +### Phase 21: コア拡張 - subscribe -**目標**: README とサンプルの整備 +**目標**: Run のイベントを ReadableStream で返す -**タスク**: -1. `packages/durably-react/README.md` 作成 -2. `packages/durably-react/docs/llms.md` 作成 -3. `examples/react-browser/` - ブラウザ完結モードの例 -4. `examples/react-server/` - サーバー連携モードの例 +**テスト（Red）**: +```tsx +describe('subscribe', () => { + it('returns ReadableStream of events', async () => { + const durably = createDurably({ dialect }) + durably.register(testJob) + await durably.migrate() + durably.start() ---- + const job = durably.getJob('test-job')! + const run = await job.trigger({ input: 'test' }) -### Phase 11: テストと品質保証 + const stream = durably.subscribe(run.id) + const reader = stream.getReader() -**目標**: 完全なテストカバレッジ + const events: DurablyEvent[] = [] + while (true) { + const { done, value } = await reader.read() + if (done) break + events.push(value) + } -**タスク**: -1. ブラウザモードのテスト (jsdom) -2. サーバー連携モードのテスト (fetch/EventSource mock) -3. StrictMode テスト -4. TypeScript 型チェック -5. Biome lint + expect(events.some(e => e.type === 'run:complete')).toBe(true) + }) +}) +``` + +**実装（Green）**: `packages/durably/src/durably.ts` に追加 --- -### Phase 12: パブリッシュ準備 +### Phase 22: コア拡張 - createDurablyHandler -**目標**: npm パブリッシュの準備 +**目標**: Web 標準の Request/Response ヘルパー -**タスク**: -1. version を 0.1.0 に設定 -2. CHANGELOG.md 作成 -3. `pnpm publish --dry-run` で確認 +**テスト（Red）**: +```tsx +// packages/durably/tests/server.test.ts +describe('createDurablyHandler', () => { + it('trigger returns runId', async () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api', { + method: 'POST', + body: JSON.stringify({ jobName: 'test-job', input: { value: 1 } }), + }) + + const response = await handler.trigger(request) + const { runId } = await response.json() + + expect(runId).toBeDefined() + }) + + it('subscribe returns SSE stream', async () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api?runId=xxx') + const response = handler.subscribe(request) + + expect(response.headers.get('Content-Type')).toBe('text/event-stream') + }) +}) +``` + +**実装（Green）**: `packages/durably/src/server.ts` 新規作成 --- -## 4. 実装順序のまとめ +### Phase 23: サーバー連携 - useJob trigger + +**目標**: fetch で trigger + +**テスト（Red）**: +```tsx +// tests/client/use-job.test.tsx +describe('useJob (client)', () => { + it('triggers via fetch', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'test-run-id' }), + }) + global.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }) + ) + + const { runId } = await result.current.trigger({ input: 'test' }) + + expect(fetchMock).toHaveBeenCalledWith('/api/durably', expect.objectContaining({ + method: 'POST', + body: JSON.stringify({ jobName: 'test-job', input: { input: 'test' } }), + })) + expect(runId).toBe('test-run-id') + }) +}) +``` -| Phase | 内容 | 依存 | -|-------|------|------| -| 1 | 基盤構築 | - | -| 2 | 共通型定義 | Phase 1 | -| 3 | ブラウザ: Provider | Phase 2 | -| 4 | ブラウザ: useJob | Phase 3 | -| 5 | ブラウザ: useJobRun, useJobLogs | Phase 3 | -| 6 | コア拡張: サーバー連携用 API | - | -| 7 | サーバー連携: useJob | Phase 2, 6 | -| 8 | サーバー連携: useJobRun, useJobLogs | Phase 7 | -| 9 | エントリポイント整備 | Phase 5, 8 | -| 10 | ドキュメント | Phase 9 | -| 11 | テスト・品質保証 | Phase 10 | -| 12 | パブリッシュ準備 | Phase 11 | +**実装（Green）**: `src/client/use-job.ts` --- -## 5. 技術的な決定事項 +### Phase 24: サーバー連携 - useJob SSE 購読 -### StrictMode 対応 +**目標**: EventSource で購読 +**テスト（Red）**: ```tsx -function DurablyProvider({ dialectFactory, children }: Props) { - const [state, setState] = useState({ durably: null, isReady: false, error: null }) - const initializedRef = useRef(false) +it('subscribes via EventSource', async () => { + const mockEventSource = createMockEventSource() + global.EventSource = mockEventSource - useEffect(() => { - if (initializedRef.current) return - initializedRef.current = true + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }) + ) - const dialect = dialectFactory() - const durably = createDurably({ dialect }) - let cancelled = false - - async function init() { - try { - await durably.migrate() - if (cancelled) return - durably.start() - setState({ durably, isReady: true, error: null }) - } catch (error) { - if (!cancelled) setState(s => ({ ...s, error: error as Error })) - } - } + await result.current.trigger({ input: 'test' }) - init() + // SSE イベントをシミュレート + mockEventSource.emit({ type: 'run:start', runId: 'xxx' }) - return () => { - cancelled = true - durably.stop() - } - }, [dialectFactory]) + await waitFor(() => { + expect(result.current.status).toBe('running') + }) - return {children} -} + mockEventSource.emit({ type: 'run:complete', runId: 'xxx', output: { ok: true } }) + + await waitFor(() => { + expect(result.current.status).toBe('completed') + expect(result.current.output).toEqual({ ok: true }) + }) +}) ``` -### SSE 購読の実装 +**実装（Green）**: EventSource 購読 + +--- + +### Phase 25: サーバー連携 - useJob 完全実装 +**目標**: progress, logs, エラー処理 + +**テスト（Red）**: ```tsx -// サーバー連携モードの useJob 内部 -function subscribeToRun(runId: string) { - const eventSource = new EventSource(`${api}?runId=${runId}`) - - eventSource.onmessage = (event) => { - const data = JSON.parse(event.data) as DurablyEvent - - switch (data.type) { - case 'run:start': - setState(s => ({ ...s, status: 'running' })) - break - case 'run:complete': - setState(s => ({ ...s, status: 'completed', output: data.output })) - eventSource.close() - break - case 'run:fail': - setState(s => ({ ...s, status: 'failed', error: data.error })) - eventSource.close() - break - case 'run:progress': - setState(s => ({ ...s, progress: data.progress })) - break - case 'log:write': - setState(s => ({ ...s, logs: [...s.logs, data] })) - break - } - } +it('handles progress events', async () => { + // ... +}) - return () => eventSource.close() -} +it('handles log events', async () => { + // ... +}) + +it('handles connection errors', async () => { + // ... +}) ``` +**実装（Green）**: 残りのイベント処理 + +--- + +### Phase 26: サーバー連携 - useJobRun + +**目標**: runId で購読 + +**テスト（Red）**: +```tsx +describe('useJobRun (client)', () => { + it('subscribes to run via SSE', async () => { + // ... + }) +}) +``` + +**実装（Green）**: `src/client/use-job-run.ts` + --- -## 6. リスクと対策 +### Phase 27: サーバー連携 - useJobLogs + +**目標**: ログ購読 + +**テスト（Red）**: +```tsx +describe('useJobLogs (client)', () => { + it('collects logs from SSE', async () => { + // ... + }) +}) +``` + +**実装（Green）**: `src/client/use-job-logs.ts` + +--- + +### Phase 28: エントリポイント整備 + +**目標**: 公開 API の整備 + +**タスク**: +1. `src/index.ts` - ブラウザ完結モード +2. `src/client.ts` - サーバー連携モード +3. ビルド確認 + +--- + +### Phase 29: ドキュメント + +**目標**: README と LLM ドキュメント + +**タスク**: +1. `packages/durably-react/README.md` +2. `packages/durably-react/docs/llms.md` + +--- + +### Phase 30: パブリッシュ準備 + +**目標**: npm パブリッシュの準備 + +**タスク**: +1. version を 0.1.0 に設定 +2. CHANGELOG.md 作成 +3. `pnpm publish --dry-run` で確認 + +--- + +## 4. 実装順序のまとめ -| リスク | 対策 | -|--------|------| -| StrictMode での予期せぬ動作 | 二重マウントテストを十分に行う | -| EventSource の再接続ループ | エラー時の適切なハンドリング | -| SSE が終了しない | Run 完了時に必ず close() | -| 型推論が複雑で失敗 | ジェネリクスの型テストを追加 | +| Phase | 内容 | TDD | +|-------|----------------------------------|-----| +| 1-2 | 基盤・型定義 | - | +| 3-6 | DurablyProvider | ✅ | +| 7-17 | useJob（ブラウザ） | ✅ | +| 18-19 | useJobRun, useJobLogs（ブラウザ）| ✅ | +| 20-22 | コア拡張 | ✅ | +| 23-27 | サーバー連携 hooks | ✅ | +| 28-30 | 整備・ドキュメント | - | --- -## 7. 完了条件 +## 5. 完了条件 +- [ ] 全フェーズでテストが先に書かれている +- [ ] 全テストがパスする - [ ] ブラウザ完結モードの全フックが実装されている - [ ] サーバー連携モードの全フックが実装されている - [ ] コア側に `getJob`, `subscribe`, `createDurablyHandler` が追加されている - [ ] 2つのエントリポイント (`.` と `./client`) が機能する - [ ] StrictMode で正しく動作する - [ ] 型推論が正しく機能する -- [ ] テストがすべてパスする - [ ] ドキュメントが整備されている From 5c45a0f581d7183c5b6ec9dc47778ed75d4c17c0 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:27:35 +0900 Subject: [PATCH 010/101] docs: improve implementation plan based on review feedback - Merge StrictMode test into Phase 3 (remove Phase 6) - Add Phase 17 for shared logic extraction - Add detailed test code for Phase 24-26 (server mode hooks) - Add Phase 28 for type inference tests - Update summary table --- docs/implementation-plan-react.md | 262 ++++++++++++++++++++++-------- 1 file changed, 197 insertions(+), 65 deletions(-) diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md index 0abc5050..d1f011a1 100644 --- a/docs/implementation-plan-react.md +++ b/docs/implementation-plan-react.md @@ -139,9 +139,9 @@ export interface LogEntry { --- -### Phase 3: DurablyProvider - 初期化 +### Phase 3: DurablyProvider - 初期化 & StrictMode -**目標**: Provider が Durably を初期化できる +**目標**: Provider が Durably を初期化できる、StrictMode で二重初期化しない **テスト（Red）**: ```tsx @@ -163,14 +163,28 @@ describe('DurablyProvider', () => { }) expect(result.current.durably).not.toBeNull() }) + + it('does not double-initialize in StrictMode', async () => { + const dialectFactory = vi.fn(() => createMockDialect()) + + render( + + + + + + ) + + await waitFor(() => {}) + expect(dialectFactory).toHaveBeenCalledTimes(1) + }) }) ``` **実装（Green）**: - `src/context.tsx`: DurablyContext, DurablyProvider - `src/hooks/use-durably.ts`: useDurably - -**Refactor**: StrictMode 対応 +- `useRef` で初期化フラグ管理（StrictMode 対応） --- @@ -211,33 +225,7 @@ it('calls stop() on unmount', async () => { --- -### Phase 6: DurablyProvider - StrictMode - -**目標**: StrictMode で二重初期化しない - -**テスト（Red）**: -```tsx -it('does not double-initialize in StrictMode', async () => { - const dialectFactory = vi.fn(() => createMockDialect()) - - render( - - - - - - ) - - await waitFor(() => {}) - expect(dialectFactory).toHaveBeenCalledTimes(1) -}) -``` - -**実装（Green）**: useRef で初期化フラグ管理 - ---- - -### Phase 7: useJob - trigger +### Phase 6: useJob - trigger **目標**: trigger でジョブを実行し runId を返す @@ -262,7 +250,7 @@ describe('useJob', () => { --- -### Phase 8: useJob - status 購読 +### Phase 7: useJob - status 購読 **目標**: trigger 後に status が更新される @@ -289,7 +277,7 @@ it('updates status from pending to running to completed', async () => { --- -### Phase 9: useJob - output 取得 +### Phase 8: useJob - output 取得 **目標**: 完了時に output が取得できる @@ -310,7 +298,7 @@ it('provides output when completed', async () => { --- -### Phase 10: useJob - error 取得 +### Phase 9: useJob - error 取得 **目標**: 失敗時に error が取得できる @@ -332,7 +320,7 @@ it('provides error when failed', async () => { --- -### Phase 11: useJob - progress 購読 +### Phase 10: useJob - progress 購読 **目標**: progress が更新される @@ -357,7 +345,7 @@ it('updates progress during execution', async () => { --- -### Phase 12: useJob - logs 購読 +### Phase 11: useJob - logs 購読 **目標**: logs が収集される @@ -379,7 +367,7 @@ it('collects logs during execution', async () => { --- -### Phase 13: useJob - boolean ヘルパー +### Phase 12: useJob - boolean ヘルパー **目標**: isRunning, isPending, isCompleted, isFailed @@ -408,7 +396,7 @@ it('provides boolean helpers', async () => { --- -### Phase 14: useJob - triggerAndWait +### Phase 13: useJob - triggerAndWait **目標**: 完了まで待つ関数 @@ -430,7 +418,7 @@ it('triggerAndWait resolves with output', async () => { --- -### Phase 15: useJob - reset +### Phase 14: useJob - reset **目標**: 状態をリセット @@ -456,7 +444,7 @@ it('reset clears all state', async () => { --- -### Phase 16: useJob - initialRunId +### Phase 15: useJob - initialRunId **目標**: 既存 Run を購読 @@ -481,7 +469,7 @@ it('subscribes to existing run with initialRunId', async () => { --- -### Phase 17: useJob - クリーンアップ +### Phase 16: useJob - クリーンアップ **目標**: アンマウント時にリスナー解除 @@ -503,6 +491,28 @@ it('unsubscribes on unmount', async () => { --- +### Phase 17: 共通ロジック抽出 + +**目標**: useJob と useJobRun/useJobLogs で共有するロジックを抽出 + +**タスク**: +- `src/hooks/use-run-subscription.ts`: Run 購読の共通ロジック + - イベントリスナー登録/解除 + - 状態管理（status, output, error, logs, progress） + +```ts +// 共通フック（内部用） +function useRunSubscription(runId: string | null) { + // status, output, error, logs, progress の状態管理 + // durably.on() でイベント購読 + // cleanup でリスナー解除 +} +``` + +**Refactor**: useJob から共通部分を抽出 + +--- + ### Phase 18: useJobRun - 基本 **目標**: runId で購読 @@ -538,7 +548,7 @@ describe('useJobRun', () => { --- -### Phase 19: useJobLogs - 基本 +### Phase 18: useJobLogs - 基本 **目標**: ログを購読 @@ -591,7 +601,7 @@ describe('useJobLogs', () => { --- -### Phase 20: コア拡張 - getJob +### Phase 19: コア拡張 - getJob **目標**: 登録済みジョブを名前で取得 @@ -621,7 +631,7 @@ describe('getJob', () => { --- -### Phase 21: コア拡張 - subscribe +### Phase 20: コア拡張 - subscribe **目標**: Run のイベントを ReadableStream で返す @@ -656,7 +666,7 @@ describe('subscribe', () => { --- -### Phase 22: コア拡張 - createDurablyHandler +### Phase 21: コア拡張 - createDurablyHandler **目標**: Web 標準の Request/Response ヘルパー @@ -693,7 +703,7 @@ describe('createDurablyHandler', () => { --- -### Phase 23: サーバー連携 - useJob trigger +### Phase 22: サーバー連携 - useJob trigger **目標**: fetch で trigger @@ -727,7 +737,7 @@ describe('useJob (client)', () => { --- -### Phase 24: サーバー連携 - useJob SSE 購読 +### Phase 23: サーバー連携 - useJob SSE 購読 **目標**: EventSource で購読 @@ -763,22 +773,41 @@ it('subscribes via EventSource', async () => { --- -### Phase 25: サーバー連携 - useJob 完全実装 +### Phase 24: サーバー連携 - useJob 完全実装 **目標**: progress, logs, エラー処理 **テスト（Red）**: ```tsx it('handles progress events', async () => { - // ... + mockEventSource.emit({ type: 'run:progress', runId: 'xxx', progress: { current: 1, total: 3 } }) + + await waitFor(() => { + expect(result.current.progress).toEqual({ current: 1, total: 3 }) + }) }) it('handles log events', async () => { - // ... + mockEventSource.emit({ + type: 'log:write', + runId: 'xxx', + level: 'info', + message: 'Processing', + data: null, + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(1) + expect(result.current.logs[0].message).toBe('Processing') + }) }) it('handles connection errors', async () => { - // ... + mockEventSource.triggerError(new Error('Connection failed')) + + await waitFor(() => { + expect(result.current.error).toBe('Connection failed') + }) }) ``` @@ -786,7 +815,7 @@ it('handles connection errors', async () => { --- -### Phase 26: サーバー連携 - useJobRun +### Phase 25: サーバー連携 - useJobRun **目標**: runId で購読 @@ -794,7 +823,30 @@ it('handles connection errors', async () => { ```tsx describe('useJobRun (client)', () => { it('subscribes to run via SSE', async () => { - // ... + const mockEventSource = createMockEventSource() + global.EventSource = mockEventSource + + const { result } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'existing-run' }) + ) + + mockEventSource.emit({ type: 'run:start', runId: 'existing-run' }) + + await waitFor(() => { + expect(result.current.status).toBe('running') + }) + }) + + it('closes EventSource on unmount', () => { + const closeSpy = vi.fn() + const mockEventSource = createMockEventSource({ onClose: closeSpy }) + + const { unmount } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'xxx' }) + ) + + unmount() + expect(closeSpy).toHaveBeenCalled() }) }) ``` @@ -803,7 +855,7 @@ describe('useJobRun (client)', () => { --- -### Phase 27: サーバー連携 - useJobLogs +### Phase 26: サーバー連携 - useJobLogs **目標**: ログ購読 @@ -811,7 +863,45 @@ describe('useJobRun (client)', () => { ```tsx describe('useJobLogs (client)', () => { it('collects logs from SSE', async () => { - // ... + const mockEventSource = createMockEventSource() + global.EventSource = mockEventSource + + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'xxx' }) + ) + + mockEventSource.emit({ + type: 'log:write', + runId: 'xxx', + level: 'info', + message: 'Log 1', + }) + mockEventSource.emit({ + type: 'log:write', + runId: 'xxx', + level: 'warn', + message: 'Log 2', + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(2) + }) + }) + + it('respects maxLogs limit', async () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'xxx', maxLogs: 2 }) + ) + + // 3つのログを送信 + for (let i = 0; i < 3; i++) { + mockEventSource.emit({ type: 'log:write', runId: 'xxx', message: `Log ${i}` }) + } + + await waitFor(() => { + expect(result.current.logs).toHaveLength(2) + expect(result.current.logs[0].message).toBe('Log 1') // 最初のログは削除される + }) }) }) ``` @@ -820,7 +910,7 @@ describe('useJobLogs (client)', () => { --- -### Phase 28: エントリポイント整備 +### Phase 27: エントリポイント整備 **目標**: 公開 API の整備 @@ -831,6 +921,45 @@ describe('useJobLogs (client)', () => { --- +### Phase 28: 型テスト + +**目標**: 型推論が正しく機能することを確認 + +**テスト**: +```ts +// tests/types.test.ts +import { expectTypeOf } from 'vitest' +import { useJob } from '../src' +import { testJob } from './fixtures' + +describe('Type inference', () => { + it('infers output type from job definition', () => { + const { output, trigger } = useJob(testJob) + + // output は TOutput | null + expectTypeOf(output).toEqualTypeOf<{ success: boolean } | null>() + + // trigger の引数は TInput + expectTypeOf(trigger).parameter(0).toEqualTypeOf<{ taskId: string }>() + }) + + it('triggerAndWait returns typed output', async () => { + const { triggerAndWait } = useJob(testJob) + + const result = await triggerAndWait({ taskId: '123' }) + + expectTypeOf(result.output).toEqualTypeOf<{ success: boolean }>() + }) +}) +``` + +**確認事項**: +- `useJob(jobDef)` で input/output の型が推論される +- `trigger()` の引数が型チェックされる +- `output` が正しい型で返される + +--- + ### Phase 29: ドキュメント **目標**: README と LLM ドキュメント @@ -854,15 +983,18 @@ describe('useJobLogs (client)', () => { ## 4. 実装順序のまとめ -| Phase | 内容 | TDD | -|-------|----------------------------------|-----| -| 1-2 | 基盤・型定義 | - | -| 3-6 | DurablyProvider | ✅ | -| 7-17 | useJob（ブラウザ） | ✅ | -| 18-19 | useJobRun, useJobLogs（ブラウザ）| ✅ | -| 20-22 | コア拡張 | ✅ | -| 23-27 | サーバー連携 hooks | ✅ | -| 28-30 | 整備・ドキュメント | - | +| Phase | 内容 | TDD | +|-------|-----------------------------------|-----| +| 1-2 | 基盤・型定義 | - | +| 3-5 | DurablyProvider | ✅ | +| 6-16 | useJob（ブラウザ） | ✅ | +| 17 | 共通ロジック抽出 | - | +| 18-19 | useJobRun, useJobLogs（ブラウザ） | ✅ | +| 20-22 | コア拡張 | ✅ | +| 23-26 | サーバー連携 hooks | ✅ | +| 27 | エントリポイント整備 | - | +| 28 | 型テスト | ✅ | +| 29-30 | ドキュメント・パブリッシュ | - | --- From a403aece7924bcbea2b82537f8328595d2da7dbd Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:31:52 +0900 Subject: [PATCH 011/101] docs: fix phase numbering in implementation plan MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix duplicate Phase 18 (useJobRun and useJobLogs) - Renumber phases 19-30 → 20-31 - Update summary table to reflect 31 total phases 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- docs/implementation-plan-react.md | 34 +++++++++++++++---------------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md index d1f011a1..05deb1ed 100644 --- a/docs/implementation-plan-react.md +++ b/docs/implementation-plan-react.md @@ -548,7 +548,7 @@ describe('useJobRun', () => { --- -### Phase 18: useJobLogs - 基本 +### Phase 19: useJobLogs - 基本 **目標**: ログを購読 @@ -601,7 +601,7 @@ describe('useJobLogs', () => { --- -### Phase 19: コア拡張 - getJob +### Phase 20: コア拡張 - getJob **目標**: 登録済みジョブを名前で取得 @@ -631,7 +631,7 @@ describe('getJob', () => { --- -### Phase 20: コア拡張 - subscribe +### Phase 21: コア拡張 - subscribe **目標**: Run のイベントを ReadableStream で返す @@ -666,7 +666,7 @@ describe('subscribe', () => { --- -### Phase 21: コア拡張 - createDurablyHandler +### Phase 22: コア拡張 - createDurablyHandler **目標**: Web 標準の Request/Response ヘルパー @@ -703,7 +703,7 @@ describe('createDurablyHandler', () => { --- -### Phase 22: サーバー連携 - useJob trigger +### Phase 23: サーバー連携 - useJob trigger **目標**: fetch で trigger @@ -737,7 +737,7 @@ describe('useJob (client)', () => { --- -### Phase 23: サーバー連携 - useJob SSE 購読 +### Phase 24: サーバー連携 - useJob SSE 購読 **目標**: EventSource で購読 @@ -773,7 +773,7 @@ it('subscribes via EventSource', async () => { --- -### Phase 24: サーバー連携 - useJob 完全実装 +### Phase 25: サーバー連携 - useJob 完全実装 **目標**: progress, logs, エラー処理 @@ -815,7 +815,7 @@ it('handles connection errors', async () => { --- -### Phase 25: サーバー連携 - useJobRun +### Phase 26: サーバー連携 - useJobRun **目標**: runId で購読 @@ -855,7 +855,7 @@ describe('useJobRun (client)', () => { --- -### Phase 26: サーバー連携 - useJobLogs +### Phase 27: サーバー連携 - useJobLogs **目標**: ログ購読 @@ -910,7 +910,7 @@ describe('useJobLogs (client)', () => { --- -### Phase 27: エントリポイント整備 +### Phase 28: エントリポイント整備 **目標**: 公開 API の整備 @@ -921,7 +921,7 @@ describe('useJobLogs (client)', () => { --- -### Phase 28: 型テスト +### Phase 29: 型テスト **目標**: 型推論が正しく機能することを確認 @@ -960,7 +960,7 @@ describe('Type inference', () => { --- -### Phase 29: ドキュメント +### Phase 30: ドキュメント **目標**: README と LLM ドキュメント @@ -970,7 +970,7 @@ describe('Type inference', () => { --- -### Phase 30: パブリッシュ準備 +### Phase 31: パブリッシュ準備 **目標**: npm パブリッシュの準備 @@ -991,10 +991,10 @@ describe('Type inference', () => { | 17 | 共通ロジック抽出 | - | | 18-19 | useJobRun, useJobLogs（ブラウザ） | ✅ | | 20-22 | コア拡張 | ✅ | -| 23-26 | サーバー連携 hooks | ✅ | -| 27 | エントリポイント整備 | - | -| 28 | 型テスト | ✅ | -| 29-30 | ドキュメント・パブリッシュ | - | +| 23-27 | サーバー連携 hooks | ✅ | +| 28 | エントリポイント整備 | - | +| 29 | 型テスト | ✅ | +| 30-31 | ドキュメント・パブリッシュ | - | --- From b471c0faddbc8095079eec2ce1cba9231fbc7d49 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:42:34 +0900 Subject: [PATCH 012/101] docs: update implementation plan and specifications for runId handling and event source mock --- docs/implementation-plan-react.md | 57 +++++++++++++++++++++++++++++-- docs/spec-react.md | 6 ++-- 2 files changed, 57 insertions(+), 6 deletions(-) diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md index 05deb1ed..6c28d8a8 100644 --- a/docs/implementation-plan-react.md +++ b/docs/implementation-plan-react.md @@ -116,7 +116,7 @@ packages/durably-react/ **タスク**: `src/types.ts`: ```ts -export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' +export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' export interface Progress { current: number @@ -201,6 +201,10 @@ it('respects autoStart=false', async () => { it('respects autoMigrate=false', async () => { // migrate() が呼ばれないことを確認 }) + +it('passes options to createDurably', async () => { + // createDurably に DurablyOptions が渡されることを確認 +}) ``` **実装（Green）**: オプション処理 @@ -252,7 +256,7 @@ describe('useJob', () => { ### Phase 7: useJob - status 購読 -**目標**: trigger 後に status が更新される +**目標**: trigger 後に status が更新される（初期は `null`、trigger 時に `pending`） **テスト（Red）**: ```tsx @@ -267,6 +271,8 @@ it('updates status from pending to running to completed', async () => { result.current.trigger({ input: 'test' }) }) + expect(result.current.status).toBe('pending') + await waitFor(() => { expect(result.current.status).toBe('completed') }) @@ -412,9 +418,19 @@ it('triggerAndWait resolves with output', async () => { expect(runId).toBeDefined() expect(output).toEqual({ success: true }) }) + +it('triggerAndWait rejects on failure', async () => { + const { result } = renderHook(() => useJob(failingJob), { wrapper }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + await expect(result.current.triggerAndWait({ input: 'test' })).rejects.toThrow( + 'Something went wrong' + ) +}) ``` -**実装（Green）**: Promise でラップ +**実装（Green）**: `run:complete` で resolve、`run:fail` で reject --- @@ -505,6 +521,7 @@ it('unsubscribes on unmount', async () => { function useRunSubscription(runId: string | null) { // status, output, error, logs, progress の状態管理 // durably.on() でイベント購読 + // runId が null の場合は購読しない（idle） // cleanup でリスナー解除 } ``` @@ -703,6 +720,31 @@ describe('createDurablyHandler', () => { --- +### テストユーティリティ: createMockEventSource + +**目標**: サーバー連携テストで使う EventSource モックを仕様化 + +**API 仕様**: +```ts +type MockEventSourceController = { + instances: MockEventSourceInstance[] + emit: (event: DurablyEvent) => void + triggerError: (error: Error) => void +} + +function createMockEventSource(opts?: { onClose?: () => void }): typeof EventSource & MockEventSourceController +``` + +**挙動**: +- `new EventSource(url)` でインスタンスを生成し `instances` に追加 +- `emit(event)` は最新インスタンスへ `message` を配送（`data` は JSON 文字列） +- `triggerError(error)` は最新インスタンスへ `error` を配送 +- `close()` が呼ばれたら `onClose` を実行 + +**実装（Green）**: `tests/client/mock-event-source.ts` + +--- + ### Phase 23: サーバー連携 - useJob trigger **目標**: fetch で trigger @@ -837,6 +879,15 @@ describe('useJobRun (client)', () => { }) }) + it('does not subscribe when runId is null', () => { + const mockEventSource = createMockEventSource() + global.EventSource = mockEventSource + + renderHook(() => useJobRun({ api: '/api/durably', runId: null })) + + expect(mockEventSource.instances).toHaveLength(0) + }) + it('closes EventSource on unmount', () => { const closeSpy = vi.fn() const mockEventSource = createMockEventSource({ onClose: closeSpy }) diff --git a/docs/spec-react.md b/docs/spec-react.md index 92086663..2a72644d 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -265,7 +265,7 @@ const { const { status, output, error, logs, progress } = useJobRun({ runId }) ``` -Run ID のみで購読（trigger なし）。 +Run ID のみで購読（trigger なし）。`runId` が `null` の場合は購読せず待機する。 | 引数 | 型 | 説明 | |---------|------------------|-----------------| @@ -367,7 +367,7 @@ const { logs, clear } = useJobLogs({ | オプション | 型 | 必須 | 説明 | |------------|----------|------|--------------------| | `api` | `string` | Yes | API エンドポイント | -| `runId` | `string` | Yes | Run ID | +| `runId` | `string \| null` | Yes | Run ID（`null` の場合は購読しない） | **useJobLogs オプション**: @@ -383,7 +383,7 @@ const { logs, clear } = useJobLogs({ ```ts // 共通 -type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' +type RunStatus = 'pending' | 'running' | 'completed' | 'failed' interface DurablyOptions { pollingInterval?: number // デフォルト: 1000ms From 2efac2481a0788132bd5bb19069c5a922af5c4f3 Mon Sep 17 00:00:00 2001 From: coji Date: Sun, 28 Dec 2025 23:48:26 +0900 Subject: [PATCH 013/101] feat(durably-react): add package foundation and DurablyProvider (Phase 1-5) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase 1: Package setup with dual entry points (index.ts, client.ts) - Phase 2: Type definitions (RunStatus, Progress, LogEntry, DurablyEvent) - Phase 3-5: DurablyProvider with StrictMode support - dialectFactory for Kysely dialect injection - autoStart/autoMigrate options - Proper cleanup on unmount - Error handling 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/package.json | 82 ++++++++ packages/durably-react/src/client.ts | 5 + packages/durably-react/src/context.tsx | 134 +++++++++++++ packages/durably-react/src/index.ts | 6 + packages/durably-react/src/types.ts | 60 ++++++ .../tests/browser/provider.test.tsx | 189 ++++++++++++++++++ .../tests/helpers/browser-dialect.ts | 10 + packages/durably-react/tsconfig.json | 19 ++ packages/durably-react/tsup.config.ts | 13 ++ packages/durably-react/vitest.config.ts | 41 ++++ pnpm-lock.yaml | 60 ++++++ 11 files changed, 619 insertions(+) create mode 100644 packages/durably-react/package.json create mode 100644 packages/durably-react/src/client.ts create mode 100644 packages/durably-react/src/context.tsx create mode 100644 packages/durably-react/src/index.ts create mode 100644 packages/durably-react/src/types.ts create mode 100644 packages/durably-react/tests/browser/provider.test.tsx create mode 100644 packages/durably-react/tests/helpers/browser-dialect.ts create mode 100644 packages/durably-react/tsconfig.json create mode 100644 packages/durably-react/tsup.config.ts create mode 100644 packages/durably-react/vitest.config.ts diff --git a/packages/durably-react/package.json b/packages/durably-react/package.json new file mode 100644 index 00000000..df2bfda1 --- /dev/null +++ b/packages/durably-react/package.json @@ -0,0 +1,82 @@ +{ + "name": "@coji/durably-react", + "version": "0.1.0", + "description": "React bindings for Durably - step-oriented resumable batch execution", + "type": "module", + "main": "./dist/index.js", + "types": "./dist/index.d.ts", + "exports": { + ".": { + "types": "./dist/index.d.ts", + "import": "./dist/index.js" + }, + "./client": { + "types": "./dist/client.d.ts", + "import": "./dist/client.js" + } + }, + "files": [ + "dist", + "README.md" + ], + "scripts": { + "build": "tsup", + "test": "pnpm test:react", + "test:react": "vitest run --config vitest.config.ts", + "typecheck": "tsc --noEmit", + "lint": "biome lint .", + "lint:fix": "biome lint --write .", + "format": "prettier --experimental-cli --check .", + "format:fix": "prettier --experimental-cli --write ." + }, + "keywords": [ + "react", + "hooks", + "durably", + "batch", + "job", + "queue", + "workflow", + "durable" + ], + "author": "coji", + "license": "MIT", + "repository": { + "type": "git", + "url": "git+https://github.com/coji/durably.git" + }, + "bugs": { + "url": "https://github.com/coji/durably/issues" + }, + "homepage": "https://github.com/coji/durably#readme", + "peerDependencies": { + "react": ">=18.0.0", + "react-dom": ">=18.0.0" + }, + "peerDependenciesMeta": { + "@coji/durably": { + "optional": true + } + }, + "devDependencies": { + "@biomejs/biome": "^2.3.10", + "@coji/durably": "workspace:*", + "@testing-library/react": "^16.3.1", + "@types/react": "^19.2.7", + "@types/react-dom": "^19.2.3", + "@vitejs/plugin-react": "^5.1.2", + "@vitest/browser": "^4.0.16", + "@vitest/browser-playwright": "4.0.16", + "kysely": "^0.28.9", + "playwright": "^1.57.0", + "prettier": "^3.7.4", + "prettier-plugin-organize-imports": "^4.3.0", + "react": "^19.2.3", + "react-dom": "^19.2.3", + "sqlocal": "^0.16.0", + "tsup": "^8.5.1", + "typescript": "^5.9.3", + "vitest": "^4.0.16", + "zod": "^4.2.1" + } +} diff --git a/packages/durably-react/src/client.ts b/packages/durably-react/src/client.ts new file mode 100644 index 00000000..42789a98 --- /dev/null +++ b/packages/durably-react/src/client.ts @@ -0,0 +1,5 @@ +// @coji/durably-react/client - Server-connected mode +// This entry point is for connecting to a Durably server via HTTP/SSE +// It does not require @coji/durably as a dependency + +export {} diff --git a/packages/durably-react/src/context.tsx b/packages/durably-react/src/context.tsx new file mode 100644 index 00000000..4b6d8df9 --- /dev/null +++ b/packages/durably-react/src/context.tsx @@ -0,0 +1,134 @@ +import { createDurably, type Durably, type DurablyOptions } from '@coji/durably' +import type { Dialect } from 'kysely' +import { + createContext, + useContext, + useEffect, + useRef, + useState, + type ReactNode, +} from 'react' + +interface DurablyContextValue { + durably: Durably | null + isReady: boolean + error: Error | null +} + +const DurablyContext = createContext(null) + +/** + * Options for DurablyProvider (dialect is provided separately via dialectFactory) + */ +export type DurablyProviderOptions = Omit + +export interface DurablyProviderProps { + /** + * Factory function to create a Kysely dialect. + * Called only once during initialization. + */ + dialectFactory: () => Dialect + /** + * Durably options (pollingInterval, heartbeatInterval, etc.) + */ + options?: DurablyProviderOptions + /** + * Whether to automatically call start() after initialization. + * @default true + */ + autoStart?: boolean + /** + * Whether to automatically call migrate() during initialization. + * @default true + */ + autoMigrate?: boolean + /** + * Callback when Durably instance is ready. + * Useful for testing to track instances. + */ + onReady?: (durably: Durably) => void + children: ReactNode +} + +export function DurablyProvider({ + dialectFactory, + options, + autoStart = true, + autoMigrate = true, + onReady, + children, +}: DurablyProviderProps) { + const [durably, setDurably] = useState(null) + const [isReady, setIsReady] = useState(false) + const [error, setError] = useState(null) + + // Use ref to track initialization state for StrictMode safety + const initializedRef = useRef(false) + const instanceRef = useRef(null) + + useEffect(() => { + // Prevent double initialization in StrictMode + if (initializedRef.current) { + // If already initialized, just use the existing instance + if (instanceRef.current) { + setDurably(instanceRef.current) + setIsReady(true) + } + return + } + + initializedRef.current = true + let cleanedUp = false + + async function init() { + try { + const dialect = dialectFactory() + const instance = createDurably({ dialect, ...options }) + instanceRef.current = instance + + if (cleanedUp) return + + if (autoMigrate) { + await instance.migrate() + if (cleanedUp) return + } + + if (autoStart) { + instance.start() + } + + if (cleanedUp) return + + setDurably(instance) + setIsReady(true) + onReady?.(instance) + } catch (err) { + if (cleanedUp) return + setError(err instanceof Error ? err : new Error(String(err))) + } + } + + init() + + return () => { + cleanedUp = true + if (instanceRef.current) { + instanceRef.current.stop() + } + } + }, [dialectFactory, options, autoStart, autoMigrate, onReady]) + + return ( + + {children} + + ) +} + +export function useDurably(): DurablyContextValue { + const context = useContext(DurablyContext) + if (!context) { + throw new Error('useDurably must be used within a DurablyProvider') + } + return context +} diff --git a/packages/durably-react/src/index.ts b/packages/durably-react/src/index.ts new file mode 100644 index 00000000..3e46c738 --- /dev/null +++ b/packages/durably-react/src/index.ts @@ -0,0 +1,6 @@ +// @coji/durably-react - Browser-complete mode +// This entry point is for running Durably entirely in the browser with OPFS + +export { DurablyProvider, useDurably } from './context' +export type { DurablyProviderProps } from './context' +export type { DurablyEvent, LogEntry, Progress, RunStatus } from './types' diff --git a/packages/durably-react/src/types.ts b/packages/durably-react/src/types.ts new file mode 100644 index 00000000..90fa90ee --- /dev/null +++ b/packages/durably-react/src/types.ts @@ -0,0 +1,60 @@ +// Shared type definitions for @coji/durably-react + +export type RunStatus = 'pending' | 'running' | 'completed' | 'failed' + +export interface Progress { + current: number + total?: number + message?: string +} + +export interface LogEntry { + id: string + runId: string + stepName: string | null + level: 'info' | 'warn' | 'error' + message: string + data: unknown + timestamp: string +} + +// SSE event types (sent from server) +export type DurablyEvent = + | { type: 'run:start'; runId: string; jobName: string; payload: unknown } + | { + type: 'run:complete' + runId: string + jobName: string + output: unknown + duration: number + } + | { type: 'run:fail'; runId: string; jobName: string; error: string } + | { + type: 'run:progress' + runId: string + jobName: string + progress: Progress + } + | { + type: 'step:start' + runId: string + jobName: string + stepName: string + stepIndex: number + } + | { + type: 'step:complete' + runId: string + jobName: string + stepName: string + stepIndex: number + output: unknown + } + | { + type: 'log:write' + runId: string + jobName: string + level: 'info' | 'warn' | 'error' + message: string + data: unknown + } diff --git a/packages/durably-react/tests/browser/provider.test.tsx b/packages/durably-react/tests/browser/provider.test.tsx new file mode 100644 index 00000000..e6cda902 --- /dev/null +++ b/packages/durably-react/tests/browser/provider.test.tsx @@ -0,0 +1,189 @@ +/** + * DurablyProvider Tests + * + * Phase 3-5: Test DurablyProvider initialization, options, and cleanup + */ + +import type { Durably } from '@coji/durably' +import { render, renderHook, waitFor } from '@testing-library/react' +import { type ReactNode, StrictMode } from 'react' +import { afterEach, describe, expect, it, vi } from 'vitest' +import { DurablyProvider, useDurably } from '../../src' +import { createBrowserDialect } from '../helpers/browser-dialect' + +describe('DurablyProvider', () => { + // Track all instances created during tests for cleanup + const instances: Durably[] = [] + + afterEach(async () => { + for (const instance of instances) { + try { + await instance.stop() + } catch { + // Ignore errors from already stopped instances + } + } + instances.length = 0 + await new Promise((r) => setTimeout(r, 200)) + }) + + // Helper to create wrapper with cleanup tracking + const createWrapper = + (options?: { + autoStart?: boolean + autoMigrate?: boolean + durablyOptions?: { pollingInterval?: number } + }) => + ({ children }: { children: ReactNode }) => { + return ( + createBrowserDialect()} + autoStart={options?.autoStart} + autoMigrate={options?.autoMigrate} + options={options?.durablyOptions} + onReady={(durably) => instances.push(durably)} + > + {children} + + ) + } + + it('initializes Durably and provides isReady=true', async () => { + const { result } = renderHook(() => useDurably(), { + wrapper: createWrapper(), + }) + + await waitFor(() => { + expect(result.current.isReady).toBe(true) + }) + expect(result.current.durably).not.toBeNull() + expect(result.current.error).toBeNull() + }) + + it('does not double-initialize in StrictMode', async () => { + const dialectFactory = vi.fn(() => createBrowserDialect()) + + function TestComponent() { + const { isReady, durably } = useDurably() + if (durably) instances.push(durably) + return
{isReady ? 'ready' : 'loading'}
+ } + + const { getByTestId } = render( + + + + + , + ) + + await waitFor(() => { + expect(getByTestId('status').textContent).toBe('ready') + }) + + // dialectFactory should only be called once even with StrictMode double mount + expect(dialectFactory).toHaveBeenCalledTimes(1) + }) + + it('respects autoStart=false', async () => { + const { result } = renderHook(() => useDurably(), { + wrapper: createWrapper({ autoStart: false }), + }) + + await waitFor(() => { + expect(result.current.isReady).toBe(true) + }) + + // Instance should exist but worker should not be running + expect(result.current.durably).not.toBeNull() + // Note: We can't easily verify start() wasn't called without mocking, + // but the instance should still be usable + }) + + it('respects autoMigrate=false', async () => { + const { result } = renderHook(() => useDurably(), { + wrapper: createWrapper({ autoMigrate: false, autoStart: false }), + }) + + await waitFor( + () => { + expect(result.current.isReady).toBe(true) + }, + { timeout: 1000 }, + ) + + // Instance should exist but may not be migrated + expect(result.current.durably).not.toBeNull() + }) + + it('passes options to createDurably', async () => { + const { result } = renderHook(() => useDurably(), { + wrapper: createWrapper({ durablyOptions: { pollingInterval: 500 } }), + }) + + await waitFor(() => { + expect(result.current.isReady).toBe(true) + }) + + // The durably instance should be created with custom options + expect(result.current.durably).not.toBeNull() + }) + + it('calls stop() on unmount', async () => { + const stopSpy = vi.fn() + let durablyRef: Durably | null = null + + const { result, unmount } = renderHook(() => useDurably(), { + wrapper: ({ children }) => ( + createBrowserDialect()} + onReady={(durably) => { + durablyRef = durably + instances.push(durably) + // Wrap stop to track calls + const originalStop = durably.stop.bind(durably) + durably.stop = async () => { + stopSpy() + return originalStop() + } + }} + > + {children} + + ), + }) + + await waitFor(() => { + expect(result.current.isReady).toBe(true) + }) + + expect(durablyRef).not.toBeNull() + + unmount() + + // stop() should be called on unmount + expect(stopSpy).toHaveBeenCalled() + }) + + it('provides error when initialization fails', async () => { + const failingDialectFactory = () => { + throw new Error('Dialect creation failed') + } + + const { result } = renderHook(() => useDurably(), { + wrapper: ({ children }) => ( + + {children} + + ), + }) + + await waitFor(() => { + expect(result.current.error).not.toBeNull() + }) + + expect(result.current.isReady).toBe(false) + expect(result.current.durably).toBeNull() + expect(result.current.error?.message).toBe('Dialect creation failed') + }) +}) diff --git a/packages/durably-react/tests/helpers/browser-dialect.ts b/packages/durably-react/tests/helpers/browser-dialect.ts new file mode 100644 index 00000000..0d57c9b5 --- /dev/null +++ b/packages/durably-react/tests/helpers/browser-dialect.ts @@ -0,0 +1,10 @@ +import { SQLocalKysely } from 'sqlocal/kysely' + +let counter = 0 + +export function createBrowserDialect() { + // Use unique DB name for each test (parallel test isolation) + const dbName = `test-${Date.now()}-${counter++}.sqlite3` + const { dialect } = new SQLocalKysely(dbName) + return dialect +} diff --git a/packages/durably-react/tsconfig.json b/packages/durably-react/tsconfig.json new file mode 100644 index 00000000..d60b2f41 --- /dev/null +++ b/packages/durably-react/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ESNext", + "moduleResolution": "bundler", + "lib": ["ES2022", "DOM"], + "jsx": "react-jsx", + "declaration": true, + "declarationMap": true, + "sourceMap": true, + "outDir": "./dist", + "strict": true, + "skipLibCheck": true, + "esModuleInterop": true, + "forceConsistentCasingInFileNames": true + }, + "include": ["src/**/*", "tests/**/*"], + "exclude": ["node_modules", "dist"] +} diff --git a/packages/durably-react/tsup.config.ts b/packages/durably-react/tsup.config.ts new file mode 100644 index 00000000..b05419bf --- /dev/null +++ b/packages/durably-react/tsup.config.ts @@ -0,0 +1,13 @@ +import { defineConfig } from 'tsup' + +export default defineConfig({ + entry: { + index: 'src/index.ts', + client: 'src/client.ts', + }, + format: ['esm'], + dts: true, + clean: true, + sourcemap: true, + external: ['react', 'react-dom', '@coji/durably'], +}) diff --git a/packages/durably-react/vitest.config.ts b/packages/durably-react/vitest.config.ts new file mode 100644 index 00000000..5380273f --- /dev/null +++ b/packages/durably-react/vitest.config.ts @@ -0,0 +1,41 @@ +import react from '@vitejs/plugin-react' +import { playwright } from '@vitest/browser-playwright' +import { defineConfig } from 'vitest/config' + +export default defineConfig({ + plugins: [ + react(), + // COOP/COEP headers for OPFS support + { + name: 'configure-response-headers', + configureServer: (server) => { + server.middlewares.use((_req, res, next) => { + res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp') + res.setHeader('Cross-Origin-Opener-Policy', 'same-origin') + next() + }) + }, + }, + ], + test: { + include: ['tests/**/*.test.tsx', 'tests/**/*.test.ts'], + retry: 2, + browser: { + enabled: true, + provider: playwright(), + instances: [{ browser: 'chromium' }], + headless: true, + }, + }, + optimizeDeps: { + exclude: ['sqlocal'], + include: [ + 'react', + 'react-dom', + '@testing-library/react', + 'zod', + 'kysely', + 'ulidx', + ], + }, +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5e019bb4..5890eaca 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -205,6 +205,66 @@ importers: specifier: ^4.2.1 version: 4.2.1 + packages/durably-react: + devDependencies: + '@biomejs/biome': + specifier: ^2.3.10 + version: 2.3.10 + '@coji/durably': + specifier: workspace:* + version: link:../durably + '@testing-library/react': + specifier: ^16.3.1 + version: 16.3.1(@testing-library/dom@10.4.1)(@types/react-dom@19.2.3(@types/react@19.2.7))(@types/react@19.2.7)(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + '@types/react': + specifier: ^19.2.7 + version: 19.2.7 + '@types/react-dom': + specifier: ^19.2.3 + version: 19.2.3(@types/react@19.2.7) + '@vitejs/plugin-react': + specifier: ^5.1.2 + version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + '@vitest/browser': + specifier: ^4.0.16 + version: 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + '@vitest/browser-playwright': + specifier: 4.0.16 + version: 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + kysely: + specifier: ^0.28.9 + version: 0.28.9 + playwright: + specifier: ^1.57.0 + version: 1.57.0 + prettier: + specifier: ^3.7.4 + version: 3.7.4 + prettier-plugin-organize-imports: + specifier: ^4.3.0 + version: 4.3.0(prettier@3.7.4)(typescript@5.9.3) + react: + specifier: ^19.2.3 + version: 19.2.3 + react-dom: + specifier: ^19.2.3 + version: 19.2.3(react@19.2.3) + sqlocal: + specifier: ^0.16.0 + version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) + tsup: + specifier: ^8.5.1 + version: 8.5.1(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3) + typescript: + specifier: ^5.9.3 + version: 5.9.3 + vitest: + specifier: ^4.0.16 + version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + zod: + specifier: ^4.2.1 + version: 4.2.1 + website: devDependencies: vitepress: From 05e6ae073e64acf7302fe8ea02ee3f6475f5564f Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 08:01:42 +0900 Subject: [PATCH 014/101] feat(durably-react): add useJob hook for browser-complete mode (Phase 6-16) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Phase 6: trigger function to execute jobs - Phase 7: status subscription (pending/running/completed/failed) - Phase 8: output retrieval on completion - Phase 9: error handling on failure - Phase 10: progress updates during execution - Phase 11: log collection - Phase 12: boolean helpers (isRunning, isPending, isCompleted, isFailed) - Phase 13: triggerAndWait for sync-style usage - Phase 14: reset function to clear state - Phase 15: initialRunId for reconnection scenarios - Phase 16: proper cleanup on unmount 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/src/hooks/use-job.ts | 285 ++++++++++++++++ packages/durably-react/src/index.ts | 4 +- .../tests/browser/use-job.test.tsx | 310 ++++++++++++++++++ 3 files changed, 598 insertions(+), 1 deletion(-) create mode 100644 packages/durably-react/src/hooks/use-job.ts create mode 100644 packages/durably-react/tests/browser/use-job.test.tsx diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts new file mode 100644 index 00000000..2ebd5672 --- /dev/null +++ b/packages/durably-react/src/hooks/use-job.ts @@ -0,0 +1,285 @@ +import type { JobDefinition, JobHandle } from '@coji/durably' +import { useCallback, useEffect, useRef, useState } from 'react' +import { useDurably } from '../context' +import type { LogEntry, Progress, RunStatus } from '../types' + +export interface UseJobOptions { + /** + * Initial Run ID to subscribe to (for reconnection scenarios) + */ + initialRunId?: string +} + +export interface UseJobResult { + /** + * Whether the hook is ready (Durably is initialized) + */ + isReady: boolean + /** + * Trigger the job with the given input + */ + trigger: (input: TInput) => Promise<{ runId: string }> + /** + * Trigger and wait for completion + */ + triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> + /** + * Current run status + */ + status: RunStatus | null + /** + * Output from completed run + */ + output: TOutput | null + /** + * Error message from failed run + */ + error: string | null + /** + * Logs collected during execution + */ + logs: LogEntry[] + /** + * Current progress + */ + progress: Progress | null + /** + * Whether a run is currently running + */ + isRunning: boolean + /** + * Whether a run is pending + */ + isPending: boolean + /** + * Whether the run completed successfully + */ + isCompleted: boolean + /** + * Whether the run failed + */ + isFailed: boolean + /** + * Current run ID + */ + currentRunId: string | null + /** + * Reset all state + */ + reset: () => void +} + +export function useJob< + TName extends string, + TInput extends Record, + TOutput extends Record | void, +>( + jobDefinition: JobDefinition, + options?: UseJobOptions, +): UseJobResult { + const { durably, isReady: isDurablyReady } = useDurably() + + const [status, setStatus] = useState(null) + const [output, setOutput] = useState(null) + const [error, setError] = useState(null) + const [logs, setLogs] = useState([]) + const [progress, setProgress] = useState(null) + const [currentRunId, setCurrentRunId] = useState( + options?.initialRunId ?? null, + ) + + const jobHandleRef = useRef | null>(null) + // Use ref to track the latest runId for event filtering + const currentRunIdRef = useRef(currentRunId) + currentRunIdRef.current = currentRunId + + // Register job and set up event listeners + useEffect(() => { + if (!durably || !isDurablyReady) return + + // Register the job + const jobHandle = durably.register(jobDefinition) + jobHandleRef.current = jobHandle + + // Subscribe to each event type separately + const unsubscribes: (() => void)[] = [] + + unsubscribes.push( + durably.on('run:start', (event) => { + if (event.runId !== currentRunIdRef.current) return + setStatus('running') + }), + ) + + unsubscribes.push( + durably.on('run:complete', (event) => { + if (event.runId !== currentRunIdRef.current) return + setStatus('completed') + setOutput(event.output as TOutput) + }), + ) + + unsubscribes.push( + durably.on('run:fail', (event) => { + if (event.runId !== currentRunIdRef.current) return + setStatus('failed') + setError(event.error) + }), + ) + + unsubscribes.push( + durably.on('run:progress', (event) => { + if (event.runId !== currentRunIdRef.current) return + setProgress(event.progress) + }), + ) + + unsubscribes.push( + durably.on('log:write', (event) => { + if (event.runId !== currentRunIdRef.current) return + setLogs((prev) => [ + ...prev, + { + id: crypto.randomUUID(), + runId: event.runId, + stepName: event.stepName, + level: event.level, + message: event.message, + data: event.data, + timestamp: new Date().toISOString(), + }, + ]) + }), + ) + + // If we have an initialRunId, fetch its current state + if (options?.initialRunId && currentRunIdRef.current) { + jobHandle.getRun(currentRunIdRef.current).then((run) => { + if (run) { + setStatus(run.status as RunStatus) + if (run.status === 'completed' && run.output) { + setOutput(run.output as TOutput) + } + if (run.status === 'failed' && run.error) { + setError(run.error) + } + } + }) + } + + return () => { + for (const unsubscribe of unsubscribes) { + unsubscribe() + } + } + }, [durably, isDurablyReady, jobDefinition, options?.initialRunId]) + + // Update state when currentRunId changes (for initialRunId scenario) + useEffect(() => { + if (!durably || !currentRunId) return + + const jobHandle = jobHandleRef.current + if (jobHandle && options?.initialRunId) { + jobHandle.getRun(currentRunId).then((run) => { + if (run) { + setStatus(run.status as RunStatus) + if (run.status === 'completed' && run.output) { + setOutput(run.output as TOutput) + } + if (run.status === 'failed' && run.error) { + setError(run.error) + } + } + }) + } + }, [durably, currentRunId, options?.initialRunId]) + + const trigger = useCallback( + async (input: TInput): Promise<{ runId: string }> => { + const jobHandle = jobHandleRef.current + if (!jobHandle) { + throw new Error('Job not ready') + } + + // Reset state + setOutput(null) + setError(null) + setLogs([]) + setProgress(null) + + const run = await jobHandle.trigger(input) + setCurrentRunId(run.id) + setStatus('pending') + + return { runId: run.id } + }, + [], + ) + + const triggerAndWait = useCallback( + async (input: TInput): Promise<{ runId: string; output: TOutput }> => { + const jobHandle = jobHandleRef.current + if (!jobHandle || !durably) { + throw new Error('Job not ready') + } + + // Reset state + setOutput(null) + setError(null) + setLogs([]) + setProgress(null) + + const run = await jobHandle.trigger(input) + setCurrentRunId(run.id) + setStatus('pending') + + // Wait for completion + return new Promise((resolve, reject) => { + const checkCompletion = async () => { + const updatedRun = await jobHandle.getRun(run.id) + if (!updatedRun) { + reject(new Error('Run not found')) + return + } + + if (updatedRun.status === 'completed') { + resolve({ runId: run.id, output: updatedRun.output as TOutput }) + } else if (updatedRun.status === 'failed') { + reject(new Error(updatedRun.error ?? 'Job failed')) + } else { + // Still running, check again + setTimeout(checkCompletion, 50) + } + } + checkCompletion() + }) + }, + [durably], + ) + + const reset = useCallback(() => { + setStatus(null) + setOutput(null) + setError(null) + setLogs([]) + setProgress(null) + setCurrentRunId(null) + }, []) + + return { + isReady: isDurablyReady, + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning: status === 'running', + isPending: status === 'pending', + isCompleted: status === 'completed', + isFailed: status === 'failed', + currentRunId, + reset, + } +} diff --git a/packages/durably-react/src/index.ts b/packages/durably-react/src/index.ts index 3e46c738..3de1d59c 100644 --- a/packages/durably-react/src/index.ts +++ b/packages/durably-react/src/index.ts @@ -2,5 +2,7 @@ // This entry point is for running Durably entirely in the browser with OPFS export { DurablyProvider, useDurably } from './context' -export type { DurablyProviderProps } from './context' +export type { DurablyProviderOptions, DurablyProviderProps } from './context' +export { useJob } from './hooks/use-job' +export type { UseJobOptions, UseJobResult } from './hooks/use-job' export type { DurablyEvent, LogEntry, Progress, RunStatus } from './types' diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx new file mode 100644 index 00000000..f93df0d4 --- /dev/null +++ b/packages/durably-react/tests/browser/use-job.test.tsx @@ -0,0 +1,310 @@ +/** + * useJob Tests + * + * Phase 6-16: Test useJob hook for browser-complete mode + */ + +import { defineJob, type Durably } from '@coji/durably' +import { renderHook, waitFor } from '@testing-library/react' +import type { ReactNode } from 'react' +import { afterEach, describe, expect, it } from 'vitest' +import { z } from 'zod' +import { DurablyProvider, useJob } from '../../src' +import { createBrowserDialect } from '../helpers/browser-dialect' + +// Test job definitions +const testJob = defineJob({ + name: 'test-job', + input: z.object({ input: z.string() }), + output: z.object({ success: z.boolean() }), + run: async (_context, payload) => { + return { success: payload.input === 'test' } + }, +}) + +const failingJob = defineJob({ + name: 'failing-job', + input: z.object({ input: z.string() }), + run: async () => { + throw new Error('Something went wrong') + }, +}) + +const progressJob = defineJob({ + name: 'progress-job', + input: z.object({ input: z.string() }), + output: z.object({ done: z.boolean() }), + run: async (context) => { + context.progress(1, 3, 'Step 1') + await context.run('step1', () => 'done') + context.progress(2, 3, 'Step 2') + await context.run('step2', () => 'done') + context.progress(3, 3, 'Step 3') + return { done: true } + }, +}) + +const loggingJob = defineJob({ + name: 'logging-job', + input: z.object({ input: z.string() }), + run: async (context) => { + context.log.info('Starting') + await context.run('work', () => 'done') + context.log.info('Completed') + }, +}) + +describe('useJob', () => { + // Track all instances created during tests for cleanup + const instances: Durably[] = [] + + afterEach(async () => { + for (const instance of instances) { + try { + await instance.stop() + } catch { + // Ignore errors from already stopped instances + } + } + instances.length = 0 + await new Promise((r) => setTimeout(r, 200)) + }) + + // Helper to create wrapper + const createWrapper = + () => + ({ children }: { children: ReactNode }) => ( + createBrowserDialect()} + options={{ pollingInterval: 50 }} + onReady={(durably) => instances.push(durably)} + > + {children} + + ) + + // Phase 6: trigger + it('returns trigger function that executes job', async () => { + const { result } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const { runId } = await result.current.trigger({ input: 'test' }) + + expect(runId).toBeDefined() + expect(typeof runId).toBe('string') + }) + + // Phase 7: status subscription + it('updates status from pending to running to completed', async () => { + const { result } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + expect(result.current.status).toBeNull() + + result.current.trigger({ input: 'test' }) + + // Status should be pending or already progressing + // (fast execution may skip pending state) + await waitFor(() => { + expect(result.current.status).not.toBeNull() + }) + + // Then eventually complete + await waitFor(() => { + expect(result.current.status).toBe('completed') + }) + }) + + // Phase 8: output + it('provides output when completed', async () => { + const { result } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.output).toEqual({ success: true }) + }) + }) + + // Phase 9: error + it('provides error when failed', async () => { + const { result } = renderHook(() => useJob(failingJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.status).toBe('failed') + expect(result.current.error).toBe('Something went wrong') + }) + }) + + // Phase 10: progress + it('updates progress during execution', async () => { + const { result } = renderHook(() => useJob(progressJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + result.current.trigger({ input: 'test' }) + + // Eventually should see progress (may not catch all intermediate states) + await waitFor(() => { + expect(result.current.progress).not.toBeNull() + }) + + // Wait for completion + await waitFor(() => { + expect(result.current.status).toBe('completed') + }) + }) + + // Phase 11: logs + it('collects logs during execution', async () => { + const { result } = renderHook(() => useJob(loggingJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.logs.length).toBeGreaterThanOrEqual(1) + }) + + // Check log structure + const log = result.current.logs[0] + expect(log.message).toBeDefined() + expect(log.level).toBe('info') + }) + + // Phase 12: boolean helpers + it('provides boolean helpers', async () => { + const { result } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + expect(result.current.isRunning).toBe(false) + expect(result.current.isPending).toBe(false) + expect(result.current.isCompleted).toBe(false) + expect(result.current.isFailed).toBe(false) + + result.current.trigger({ input: 'test' }) + + // Wait for some state (may skip pending if fast) + await waitFor(() => { + expect( + result.current.isPending || + result.current.isRunning || + result.current.isCompleted, + ).toBe(true) + }) + + // completed state + await waitFor(() => { + expect(result.current.isCompleted).toBe(true) + }) + + expect(result.current.isRunning).toBe(false) + expect(result.current.isPending).toBe(false) + expect(result.current.isFailed).toBe(false) + }) + + // Phase 13: triggerAndWait + it('triggerAndWait resolves with output', async () => { + const { result } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const { runId, output } = await result.current.triggerAndWait({ + input: 'test', + }) + + expect(runId).toBeDefined() + expect(output).toEqual({ success: true }) + }) + + it('triggerAndWait rejects on failure', async () => { + const { result } = renderHook(() => useJob(failingJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + await expect( + result.current.triggerAndWait({ input: 'test' }), + ).rejects.toThrow('Something went wrong') + }) + + // Phase 14: reset + it('reset clears all state', async () => { + const { result } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + await result.current.trigger({ input: 'test' }) + await waitFor(() => expect(result.current.isCompleted).toBe(true)) + + result.current.reset() + + // Wait for reset to take effect + await waitFor(() => { + expect(result.current.status).toBeNull() + }) + expect(result.current.output).toBeNull() + expect(result.current.currentRunId).toBeNull() + }) + + // Phase 15: initialRunId + it('sets initialRunId as currentRunId', async () => { + const fakeRunId = 'test-run-123' + + const { result } = renderHook( + () => useJob(testJob, { initialRunId: fakeRunId }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // Should have the initial runId set + expect(result.current.currentRunId).toBe(fakeRunId) + }) + + // Phase 16: cleanup + it('unsubscribes on unmount', async () => { + const { result, unmount } = renderHook(() => useJob(testJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + result.current.trigger({ input: 'test' }) + + // Unmount while running + unmount() + + // No errors should occur (memory leak test) + await new Promise((r) => setTimeout(r, 100)) + }) +}) From de50eef27b198e1ee9462e3bf1c9ddf3be60e3a3 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 08:27:03 +0900 Subject: [PATCH 015/101] feat(durably-react): add useJobRun, useJobLogs hooks and common subscription logic (Phase 17-19) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Extract common run subscription logic into use-run-subscription.ts - Add useJobRun hook for subscribing to existing runs by ID - Add useJobLogs hook for subscribing to logs with maxLogs limit - Add tests for both new hooks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../durably-react/src/hooks/use-job-logs.ts | 46 +++ .../durably-react/src/hooks/use-job-run.ts | 94 ++++++ packages/durably-react/src/hooks/use-job.ts | 1 + .../src/hooks/use-run-subscription.ts | 141 ++++++++ packages/durably-react/src/index.ts | 4 + .../tests/browser/use-job-logs.test.tsx | 213 ++++++++++++ .../tests/browser/use-job-run.test.tsx | 303 ++++++++++++++++++ 7 files changed, 802 insertions(+) create mode 100644 packages/durably-react/src/hooks/use-job-logs.ts create mode 100644 packages/durably-react/src/hooks/use-job-run.ts create mode 100644 packages/durably-react/src/hooks/use-run-subscription.ts create mode 100644 packages/durably-react/tests/browser/use-job-logs.test.tsx create mode 100644 packages/durably-react/tests/browser/use-job-run.test.tsx diff --git a/packages/durably-react/src/hooks/use-job-logs.ts b/packages/durably-react/src/hooks/use-job-logs.ts new file mode 100644 index 00000000..fd4cf83b --- /dev/null +++ b/packages/durably-react/src/hooks/use-job-logs.ts @@ -0,0 +1,46 @@ +import { useDurably } from '../context' +import type { LogEntry } from '../types' +import { useRunSubscription } from './use-run-subscription' + +export interface UseJobLogsOptions { + /** + * The run ID to subscribe to logs for + */ + runId: string | null + /** + * Maximum number of logs to keep (default: unlimited) + */ + maxLogs?: number +} + +export interface UseJobLogsResult { + /** + * Whether the hook is ready (Durably is initialized) + */ + isReady: boolean + /** + * Logs collected during execution + */ + logs: LogEntry[] + /** + * Clear all logs + */ + clearLogs: () => void +} + +/** + * Hook for subscribing to logs from a run. + * Use this when you only need logs, not full run status. + */ +export function useJobLogs(options: UseJobLogsOptions): UseJobLogsResult { + const { durably, isReady: isDurablyReady } = useDurably() + const { runId, maxLogs } = options + + const subscription = useRunSubscription(durably, runId, { maxLogs }) + + return { + isReady: isDurablyReady, + logs: subscription.logs, + clearLogs: subscription.clearLogs, + } +} diff --git a/packages/durably-react/src/hooks/use-job-run.ts b/packages/durably-react/src/hooks/use-job-run.ts new file mode 100644 index 00000000..34f92803 --- /dev/null +++ b/packages/durably-react/src/hooks/use-job-run.ts @@ -0,0 +1,94 @@ +import { useEffect, useRef } from 'react' +import { useDurably } from '../context' +import type { LogEntry, Progress, RunStatus } from '../types' +import { useRunSubscription } from './use-run-subscription' + +export interface UseJobRunOptions { + /** + * The run ID to subscribe to + */ + runId: string | null +} + +export interface UseJobRunResult { + /** + * Whether the hook is ready (Durably is initialized) + */ + isReady: boolean + /** + * Current run status + */ + status: RunStatus | null + /** + * Output from completed run + */ + output: TOutput | null + /** + * Error message from failed run + */ + error: string | null + /** + * Logs collected during execution + */ + logs: LogEntry[] + /** + * Current progress + */ + progress: Progress | null + /** + * Whether a run is currently running + */ + isRunning: boolean + /** + * Whether a run is pending + */ + isPending: boolean + /** + * Whether the run completed successfully + */ + isCompleted: boolean + /** + * Whether the run failed + */ + isFailed: boolean +} + +/** + * Hook for subscribing to an existing run by ID. + * Use this when you have a runId and want to track its status. + */ +export function useJobRun( + options: UseJobRunOptions, +): UseJobRunResult { + const { durably, isReady: isDurablyReady } = useDurably() + const { runId } = options + + const subscription = useRunSubscription(durably, runId) + + // Fetch initial state when runId changes + const fetchedRef = useRef>(new Set()) + + useEffect(() => { + if (!durably || !runId || fetchedRef.current.has(runId)) return + + // Mark as fetched to avoid duplicate fetches + fetchedRef.current.add(runId) + + // Try to fetch current run state + // Note: We need to use internal APIs or polling here + // For now, we rely on event-based updates + }, [durably, runId]) + + return { + isReady: isDurablyReady, + status: subscription.status, + output: subscription.output, + error: subscription.error, + logs: subscription.logs, + progress: subscription.progress, + isRunning: subscription.status === 'running', + isPending: subscription.status === 'pending', + isCompleted: subscription.status === 'completed', + isFailed: subscription.status === 'failed', + } +} diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts index 2ebd5672..53acad77 100644 --- a/packages/durably-react/src/hooks/use-job.ts +++ b/packages/durably-react/src/hooks/use-job.ts @@ -72,6 +72,7 @@ export interface UseJobResult { export function useJob< TName extends string, TInput extends Record, + // biome-ignore lint/suspicious/noConfusingVoidType: TOutput can be void for jobs without return value TOutput extends Record | void, >( jobDefinition: JobDefinition, diff --git a/packages/durably-react/src/hooks/use-run-subscription.ts b/packages/durably-react/src/hooks/use-run-subscription.ts new file mode 100644 index 00000000..d41bfb61 --- /dev/null +++ b/packages/durably-react/src/hooks/use-run-subscription.ts @@ -0,0 +1,141 @@ +import type { Durably } from '@coji/durably' +import { useEffect, useRef, useState } from 'react' +import type { LogEntry, Progress, RunStatus } from '../types' + +export interface RunSubscriptionState { + status: RunStatus | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null +} + +export interface UseRunSubscriptionOptions { + /** + * Maximum number of logs to keep (0 = unlimited) + */ + maxLogs?: number +} + +export interface UseRunSubscriptionResult< + TOutput = unknown, +> extends RunSubscriptionState { + /** + * Clear all logs + */ + clearLogs: () => void + /** + * Reset all state + */ + reset: () => void +} + +/** + * Internal hook for subscribing to run events. + * Shared by useJob, useJobRun, and useJobLogs. + */ +export function useRunSubscription( + durably: Durably | null, + runId: string | null, + options?: UseRunSubscriptionOptions, +): UseRunSubscriptionResult { + const [status, setStatus] = useState(null) + const [output, setOutput] = useState(null) + const [error, setError] = useState(null) + const [logs, setLogs] = useState([]) + const [progress, setProgress] = useState(null) + + // Use ref to track the latest runId for event filtering + const runIdRef = useRef(runId) + runIdRef.current = runId + + const maxLogs = options?.maxLogs ?? 0 + + // Subscribe to events + useEffect(() => { + if (!durably || !runId) return + + const unsubscribes: (() => void)[] = [] + + unsubscribes.push( + durably.on('run:start', (event) => { + if (event.runId !== runIdRef.current) return + setStatus('running') + }), + ) + + unsubscribes.push( + durably.on('run:complete', (event) => { + if (event.runId !== runIdRef.current) return + setStatus('completed') + setOutput(event.output as TOutput) + }), + ) + + unsubscribes.push( + durably.on('run:fail', (event) => { + if (event.runId !== runIdRef.current) return + setStatus('failed') + setError(event.error) + }), + ) + + unsubscribes.push( + durably.on('run:progress', (event) => { + if (event.runId !== runIdRef.current) return + setProgress(event.progress) + }), + ) + + unsubscribes.push( + durably.on('log:write', (event) => { + if (event.runId !== runIdRef.current) return + setLogs((prev) => { + const newLog: LogEntry = { + id: crypto.randomUUID(), + runId: event.runId, + stepName: event.stepName, + level: event.level, + message: event.message, + data: event.data, + timestamp: new Date().toISOString(), + } + const newLogs = [...prev, newLog] + // Apply maxLogs limit if set + if (maxLogs > 0 && newLogs.length > maxLogs) { + return newLogs.slice(-maxLogs) + } + return newLogs + }) + }), + ) + + return () => { + for (const unsubscribe of unsubscribes) { + unsubscribe() + } + } + }, [durably, runId, maxLogs]) + + const clearLogs = () => { + setLogs([]) + } + + const reset = () => { + setStatus(null) + setOutput(null) + setError(null) + setLogs([]) + setProgress(null) + } + + return { + status, + output, + error, + logs, + progress, + clearLogs, + reset, + } +} diff --git a/packages/durably-react/src/index.ts b/packages/durably-react/src/index.ts index 3de1d59c..e39f30ea 100644 --- a/packages/durably-react/src/index.ts +++ b/packages/durably-react/src/index.ts @@ -5,4 +5,8 @@ export { DurablyProvider, useDurably } from './context' export type { DurablyProviderOptions, DurablyProviderProps } from './context' export { useJob } from './hooks/use-job' export type { UseJobOptions, UseJobResult } from './hooks/use-job' +export { useJobLogs } from './hooks/use-job-logs' +export type { UseJobLogsOptions, UseJobLogsResult } from './hooks/use-job-logs' +export { useJobRun } from './hooks/use-job-run' +export type { UseJobRunOptions, UseJobRunResult } from './hooks/use-job-run' export type { DurablyEvent, LogEntry, Progress, RunStatus } from './types' diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx new file mode 100644 index 00000000..2acbf621 --- /dev/null +++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx @@ -0,0 +1,213 @@ +/** + * useJobLogs Tests + * + * Phase 19: Test useJobLogs hook for subscribing to logs + */ + +import { defineJob, type Durably } from '@coji/durably' +import { renderHook, waitFor } from '@testing-library/react' +import type { ReactNode } from 'react' +import { useState } from 'react' +import { afterEach, describe, expect, it } from 'vitest' +import { z } from 'zod' +import { DurablyProvider, useDurably, useJobLogs } from '../../src' +import { createBrowserDialect } from '../helpers/browser-dialect' + +// Test job that generates logs with delay to ensure we can subscribe +const loggingJob = defineJob({ + name: 'logging-job-logs', + input: z.object({ count: z.number() }), + run: async (context, payload) => { + for (let i = 0; i < payload.count; i++) { + context.log.info(`Log ${i + 1}`) + await context.run(`step${i}`, async () => { + await new Promise((r) => setTimeout(r, 30)) + return `done${i}` + }) + } + }, +}) + +describe('useJobLogs', () => { + // Track all instances created during tests for cleanup + const instances: Durably[] = [] + + // Create a shared dialect for tests that need to share the same Durably instance + let sharedDialect: ReturnType | null = null + + const getSharedDialect = () => { + if (!sharedDialect) { + sharedDialect = createBrowserDialect() + } + return sharedDialect + } + + // Helper to create wrapper with shared dialect + const createSharedWrapper = + () => + ({ children }: { children: ReactNode }) => ( + { + if (!instances.includes(durably)) { + instances.push(durably) + } + }} + > + {children} + + ) + + // Helper to create wrapper with new dialect + const createWrapper = + () => + ({ children }: { children: ReactNode }) => ( + createBrowserDialect()} + options={{ pollingInterval: 50 }} + onReady={(durably) => instances.push(durably)} + > + {children} + + ) + + afterEach(async () => { + for (const instance of instances) { + try { + await instance.stop() + } catch { + // Ignore errors from already stopped instances + } + } + instances.length = 0 + sharedDialect = null + await new Promise((r) => setTimeout(r, 200)) + }) + + it('collects logs for run', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobLogs({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(loggingJob) + const run = await handle.trigger({ count: 3 }) + result.current.setRunId(run.id) + + await waitFor( + () => { + expect(result.current.logs.length).toBeGreaterThan(0) + }, + { timeout: 3000 }, + ) + + // Check log structure + const log = result.current.logs[0] + expect(log.message).toBeDefined() + expect(log.level).toBe('info') + expect(log.runId).toBe(run.id) + }) + + it('handles null runId', async () => { + const { result } = renderHook(() => useJobLogs({ runId: null }), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // With null runId, logs should be empty + expect(result.current.logs).toEqual([]) + }) + + it('respects maxLogs limit', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobLogs({ runId, maxLogs: 5 }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(loggingJob) + const run = await handle.trigger({ count: 10 }) + result.current.setRunId(run.id) + + // Wait for job to complete + await new Promise((r) => setTimeout(r, 500)) + + // Should have at most 5 logs + expect(result.current.logs.length).toBeLessThanOrEqual(5) + }) + + it('clears logs on clearLogs call', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobLogs({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(loggingJob) + const run = await handle.trigger({ count: 3 }) + result.current.setRunId(run.id) + + // Wait for job to complete and logs to be collected + await new Promise((r) => setTimeout(r, 500)) + + await waitFor( + () => { + expect(result.current.logs.length).toBeGreaterThan(0) + }, + { timeout: 3000 }, + ) + + // Clear logs after job is done + result.current.clearLogs() + + // Wait for the state update to propagate + await waitFor(() => { + expect(result.current.logs.length).toBe(0) + }) + }) +}) diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx new file mode 100644 index 00000000..6fcaa9ff --- /dev/null +++ b/packages/durably-react/tests/browser/use-job-run.test.tsx @@ -0,0 +1,303 @@ +/** + * useJobRun Tests + * + * Phase 18: Test useJobRun hook for subscribing to existing runs + */ + +import { defineJob, type Durably } from '@coji/durably' +import { renderHook, waitFor } from '@testing-library/react' +import type { ReactNode } from 'react' +import { useState } from 'react' +import { afterEach, describe, expect, it } from 'vitest' +import { z } from 'zod' +import { DurablyProvider, useDurably, useJobRun } from '../../src' +import { createBrowserDialect } from '../helpers/browser-dialect' + +// Test job definitions - use slow jobs to ensure we can subscribe before completion +const testJob = defineJob({ + name: 'test-job-run', + input: z.object({ input: z.string() }), + output: z.object({ result: z.string() }), + run: async (context, payload) => { + await context.run('process', async () => { + await new Promise((r) => setTimeout(r, 50)) + }) + return { result: `processed: ${payload.input}` } + }, +}) + +const failingJob = defineJob({ + name: 'failing-job-run', + input: z.object({ input: z.string() }), + run: async (context) => { + await context.run('fail', async () => { + await new Promise((r) => setTimeout(r, 50)) + }) + throw new Error('Job failed') + }, +}) + +const progressJob = defineJob({ + name: 'progress-job-run', + input: z.object({ input: z.string() }), + output: z.object({ done: z.boolean() }), + run: async (context) => { + context.progress(1, 2, 'Step 1') + await context.run('step1', async () => { + await new Promise((r) => setTimeout(r, 50)) + }) + context.progress(2, 2, 'Step 2') + return { done: true } + }, +}) + +describe('useJobRun', () => { + // Track all instances created during tests for cleanup + const instances: Durably[] = [] + + // Create a shared dialect for tests that need to share the same Durably instance + let sharedDialect: ReturnType | null = null + + const getSharedDialect = () => { + if (!sharedDialect) { + sharedDialect = createBrowserDialect() + } + return sharedDialect + } + + // Helper to create wrapper with shared dialect + const createSharedWrapper = + () => + ({ children }: { children: ReactNode }) => ( + { + if (!instances.includes(durably)) { + instances.push(durably) + } + }} + > + {children} + + ) + + // Helper to create wrapper with new dialect + const createWrapper = + () => + ({ children }: { children: ReactNode }) => ( + createBrowserDialect()} + options={{ pollingInterval: 50 }} + onReady={(durably) => instances.push(durably)} + > + {children} + + ) + + afterEach(async () => { + for (const instance of instances) { + try { + await instance.stop() + } catch { + // Ignore errors from already stopped instances + } + } + instances.length = 0 + sharedDialect = null + await new Promise((r) => setTimeout(r, 200)) + }) + + it('subscribes to run by id', async () => { + // Use a combined hook that triggers then subscribes + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobRun({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // Trigger job and set runId + const handle = result.current.durably!.register(testJob) + const run = await handle.trigger({ input: 'test' }) + + // Update runId to start subscription + result.current.setRunId(run.id) + + // Should eventually see the run complete + await waitFor( + () => { + expect(result.current.status).not.toBeNull() + }, + { timeout: 3000 }, + ) + }) + + it('handles null runId', async () => { + const { result } = renderHook(() => useJobRun({ runId: null }), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // With null runId, status should remain null + expect(result.current.status).toBeNull() + expect(result.current.output).toBeNull() + expect(result.current.error).toBeNull() + }) + + it('provides output when run completes', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobRun<{ result: string }>({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(testJob) + const run = await handle.trigger({ input: 'hello' }) + result.current.setRunId(run.id) + + await waitFor( + () => { + expect(result.current.status).toBe('completed') + expect(result.current.output).toEqual({ result: 'processed: hello' }) + }, + { timeout: 3000 }, + ) + }) + + it('provides error when run fails', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobRun({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(failingJob) + const run = await handle.trigger({ input: 'test' }) + result.current.setRunId(run.id) + + await waitFor( + () => { + expect(result.current.status).toBe('failed') + expect(result.current.error).toBe('Job failed') + }, + { timeout: 3000 }, + ) + }) + + it('tracks progress updates', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobRun({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(progressJob) + const run = await handle.trigger({ input: 'test' }) + result.current.setRunId(run.id) + + // Should eventually see progress or complete + await waitFor( + () => { + expect( + result.current.progress !== null || + result.current.status === 'completed', + ).toBe(true) + }, + { timeout: 3000 }, + ) + }) + + it('provides boolean helpers', async () => { + function useTriggerAndSubscribe() { + const { durably, isReady: durablyReady } = useDurably() + const [runId, setRunId] = useState(null) + const subscription = useJobRun({ runId }) + + return { + ...subscription, + isReady: durablyReady && subscription.isReady, + durably, + runId, + setRunId, + } + } + + const { result } = renderHook(() => useTriggerAndSubscribe(), { + wrapper: createSharedWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const handle = result.current.durably!.register(testJob) + const run = await handle.trigger({ input: 'test' }) + result.current.setRunId(run.id) + + await waitFor( + () => { + expect(result.current.isCompleted).toBe(true) + }, + { timeout: 3000 }, + ) + + expect(result.current.isRunning).toBe(false) + expect(result.current.isPending).toBe(false) + expect(result.current.isFailed).toBe(false) + }) +}) From 97bfae70abf4180bdad5c27c9e574807cadf128c Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 08:37:03 +0900 Subject: [PATCH 016/101] feat(durably): add getJob, subscribe, and createDurablyHandler (Phase 20-22) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add getJob method to retrieve registered job by name - Add subscribe method returning ReadableStream for SSE support - Create createDurablyHandler for HTTP endpoints (trigger + subscribe) - Export DurablyHandler types from index 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably/src/durably.ts | 118 ++++++++++ packages/durably/src/index.ts | 4 + packages/durably/src/server.ts | 132 +++++++++++ .../tests/node/core-extensions.test.ts | 210 ++++++++++++++++++ 4 files changed, 464 insertions(+) create mode 100644 packages/durably/src/server.ts create mode 100644 packages/durably/tests/node/core-extensions.test.ts diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts index a5f9ca86..0ac9de78 100644 --- a/packages/durably/src/durably.ts +++ b/packages/durably/src/durably.ts @@ -3,6 +3,7 @@ import { Kysely } from 'kysely' import type { JobDefinition } from './define-job' import { type AnyEventInput, + type DurablyEvent, type ErrorHandler, type EventListener, type EventType, @@ -135,6 +136,20 @@ export interface Durably { * Register a plugin */ use(plugin: DurablyPlugin): void + + /** + * Get a registered job handle by name + * Returns undefined if job is not registered + */ + getJob( + name: TName, + ): JobHandle, unknown> | undefined + + /** + * Subscribe to events for a specific run + * Returns a ReadableStream that can be used for SSE + */ + subscribe(runId: string): ReadableStream } /** @@ -179,6 +194,109 @@ export function createDurably(options: DurablyOptions): Durably { plugin.install(durably) }, + getJob( + name: TName, + ): JobHandle, unknown> | undefined { + const registeredJob = jobRegistry.get(name) + if (!registeredJob) { + return undefined + } + return registeredJob.handle as JobHandle< + TName, + Record, + unknown + > + }, + + subscribe(runId: string): ReadableStream { + return new ReadableStream({ + start: (controller) => { + // Track if stream is closed + let closed = false + + // Subscribe to all events that match this runId + const unsubscribeStart = eventEmitter.on('run:start', (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + } + }) + + const unsubscribeComplete = eventEmitter.on( + 'run:complete', + (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + // Close stream on completion + closed = true + cleanup() + controller.close() + } + }, + ) + + const unsubscribeFail = eventEmitter.on('run:fail', (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + // Close stream on failure + closed = true + cleanup() + controller.close() + } + }) + + const unsubscribeProgress = eventEmitter.on( + 'run:progress', + (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + } + }, + ) + + const unsubscribeStepStart = eventEmitter.on( + 'step:start', + (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + } + }, + ) + + const unsubscribeStepComplete = eventEmitter.on( + 'step:complete', + (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + } + }, + ) + + const unsubscribeStepFail = eventEmitter.on('step:fail', (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + } + }) + + const unsubscribeLog = eventEmitter.on('log:write', (event) => { + if (!closed && event.runId === runId) { + controller.enqueue(event) + } + }) + + const cleanup = () => { + unsubscribeStart() + unsubscribeComplete() + unsubscribeFail() + unsubscribeProgress() + unsubscribeStepStart() + unsubscribeStepComplete() + unsubscribeStepFail() + unsubscribeLog() + } + }, + }) + }, + async retry(runId: string): Promise { const run = await storage.getRun(runId) if (!run) { diff --git a/packages/durably/src/index.ts b/packages/durably/src/index.ts index 407f1245..eef11b3b 100644 --- a/packages/durably/src/index.ts +++ b/packages/durably/src/index.ts @@ -46,3 +46,7 @@ export type { Log, Run, RunFilter, Step } from './storage' // Errors export { CancelledError } from './errors' + +// Server +export { createDurablyHandler } from './server' +export type { DurablyHandler, TriggerRequest, TriggerResponse } from './server' diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts new file mode 100644 index 00000000..dc350485 --- /dev/null +++ b/packages/durably/src/server.ts @@ -0,0 +1,132 @@ +import type { Durably } from './durably' +import type { AnyEventInput } from './events' + +/** + * Request body for triggering a job + */ +export interface TriggerRequest { + jobName: string + input: Record + idempotencyKey?: string + concurrencyKey?: string +} + +/** + * Response for trigger endpoint + */ +export interface TriggerResponse { + runId: string +} + +/** + * Handler interface for HTTP endpoints + */ +export interface DurablyHandler { + /** + * Handle job trigger request + * Expects POST with JSON body: { jobName, input, idempotencyKey?, concurrencyKey? } + * Returns JSON: { runId } + */ + trigger(request: Request): Promise + + /** + * Handle subscription request + * Expects GET with query param: runId + * Returns SSE stream of events + */ + subscribe(request: Request): Response +} + +/** + * Create HTTP handlers for Durably + * Uses Web Standard Request/Response for framework-agnostic usage + */ +export function createDurablyHandler(durably: Durably): DurablyHandler { + return { + async trigger(request: Request): Promise { + try { + const body = (await request.json()) as TriggerRequest + + if (!body.jobName) { + return new Response( + JSON.stringify({ error: 'jobName is required' }), + { status: 400, headers: { 'Content-Type': 'application/json' } }, + ) + } + + const job = durably.getJob(body.jobName) + if (!job) { + return new Response( + JSON.stringify({ error: `Job not found: ${body.jobName}` }), + { status: 404, headers: { 'Content-Type': 'application/json' } }, + ) + } + + const run = await job.trigger(body.input ?? {}, { + idempotencyKey: body.idempotencyKey, + concurrencyKey: body.concurrencyKey, + }) + + const response: TriggerResponse = { runId: run.id } + return new Response(JSON.stringify(response), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) + } catch (error) { + const message = error instanceof Error ? error.message : 'Unknown error' + return new Response(JSON.stringify({ error: message }), { + status: 500, + headers: { 'Content-Type': 'application/json' }, + }) + } + }, + + subscribe(request: Request): Response { + const url = new URL(request.url) + const runId = url.searchParams.get('runId') + + if (!runId) { + return new Response( + JSON.stringify({ error: 'runId query parameter is required' }), + { status: 400, headers: { 'Content-Type': 'application/json' } }, + ) + } + + const stream = durably.subscribe(runId) + + // Transform stream to SSE format + const encoder = new TextEncoder() + const sseStream = new ReadableStream({ + async start(controller) { + const reader = stream.getReader() + + try { + while (true) { + const { done, value } = await reader.read() + if (done) { + controller.close() + break + } + + // Format as SSE + const event = value as AnyEventInput + const data = `data: ${JSON.stringify(event)}\n\n` + controller.enqueue(encoder.encode(data)) + } + } catch (error) { + controller.error(error) + } + }, + }) + + return new Response(sseStream, { + status: 200, + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + Connection: 'keep-alive', + }, + }) + }, + } +} diff --git a/packages/durably/tests/node/core-extensions.test.ts b/packages/durably/tests/node/core-extensions.test.ts new file mode 100644 index 00000000..a214243c --- /dev/null +++ b/packages/durably/tests/node/core-extensions.test.ts @@ -0,0 +1,210 @@ +/** + * Core Extensions Tests + * + * Phase 20-22: Test getJob, subscribe, and createDurablyHandler + */ + +import { afterEach, beforeEach, describe, expect, it } from 'vitest' +import { z } from 'zod' +import { + createDurably, + createDurablyHandler, + defineJob, + type Durably, +} from '../../src' +import type { DurablyEvent } from '../../src/events' +import { createNodeDialect } from '../helpers/node-dialect' + +describe('Core Extensions', () => { + let durably: Durably + + beforeEach(async () => { + const dialect = createNodeDialect() + durably = createDurably({ dialect, pollingInterval: 50 }) + await durably.migrate() + }) + + afterEach(async () => { + await durably.stop() + }) + + describe('getJob (Phase 20)', () => { + const testJob = defineJob({ + name: 'test-job-getjob', + input: z.object({ value: z.number() }), + output: z.object({ result: z.number() }), + run: async (_ctx, payload) => ({ result: payload.value * 2 }), + }) + + it('returns registered job by name', () => { + durably.register(testJob) + + const job = durably.getJob('test-job-getjob') + + expect(job).toBeDefined() + expect(job?.name).toBe('test-job-getjob') + }) + + it('returns undefined for unknown job', () => { + expect(durably.getJob('unknown-job')).toBeUndefined() + }) + + it('can trigger job via getJob handle', async () => { + durably.register(testJob) + + const job = durably.getJob('test-job-getjob') + const run = await job!.trigger({ value: 5 }) + + expect(run.id).toBeDefined() + expect(run.status).toBe('pending') + }) + }) + + describe('subscribe (Phase 21)', () => { + const testJob = defineJob({ + name: 'test-job-subscribe', + input: z.object({ input: z.string() }), + output: z.object({ result: z.string() }), + run: async (ctx, payload) => { + await ctx.run('step1', () => 'done') + return { result: `processed: ${payload.input}` } + }, + }) + + it('returns ReadableStream of events', async () => { + durably.register(testJob) + durably.start() + + const job = durably.getJob('test-job-subscribe')! + const run = await job.trigger({ input: 'test' }) + + const stream = durably.subscribe(run.id) + const reader = stream.getReader() + + const events: DurablyEvent[] = [] + while (true) { + const { done, value } = await reader.read() + if (done) break + events.push(value) + } + + expect(events.some((e) => e.type === 'run:complete')).toBe(true) + }) + + it('emits run:start event', async () => { + durably.register(testJob) + durably.start() + + const job = durably.getJob('test-job-subscribe')! + const run = await job.trigger({ input: 'test' }) + + const stream = durably.subscribe(run.id) + const reader = stream.getReader() + + const events: DurablyEvent[] = [] + while (true) { + const { done, value } = await reader.read() + if (done) break + events.push(value) + } + + expect(events.some((e) => e.type === 'run:start')).toBe(true) + }) + + it('emits step events', async () => { + durably.register(testJob) + durably.start() + + const job = durably.getJob('test-job-subscribe')! + const run = await job.trigger({ input: 'test' }) + + const stream = durably.subscribe(run.id) + const reader = stream.getReader() + + const events: DurablyEvent[] = [] + while (true) { + const { done, value } = await reader.read() + if (done) break + events.push(value) + } + + expect(events.some((e) => e.type === 'step:start')).toBe(true) + expect(events.some((e) => e.type === 'step:complete')).toBe(true) + }) + }) + + describe('createDurablyHandler (Phase 22)', () => { + const testJob = defineJob({ + name: 'test-job-handler', + input: z.object({ value: z.number() }), + output: z.object({ result: z.number() }), + run: async (_ctx, payload) => ({ result: payload.value * 2 }), + }) + + beforeEach(() => { + durably.register(testJob) + }) + + it('trigger returns runId', async () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api', { + method: 'POST', + body: JSON.stringify({ + jobName: 'test-job-handler', + input: { value: 5 }, + }), + }) + + const response = await handler.trigger(request) + const body = (await response.json()) as { runId: string } + + expect(response.status).toBe(200) + expect(body.runId).toBeDefined() + }) + + it('trigger returns 404 for unknown job', async () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api', { + method: 'POST', + body: JSON.stringify({ jobName: 'unknown-job', input: {} }), + }) + + const response = await handler.trigger(request) + + expect(response.status).toBe(404) + }) + + it('trigger returns 400 for missing jobName', async () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api', { + method: 'POST', + body: JSON.stringify({ input: {} }), + }) + + const response = await handler.trigger(request) + + expect(response.status).toBe(400) + }) + + it('subscribe returns SSE stream', () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api?runId=test-run-id') + const response = handler.subscribe(request) + + expect(response.headers.get('Content-Type')).toBe('text/event-stream') + }) + + it('subscribe returns 400 for missing runId', () => { + const handler = createDurablyHandler(durably) + + const request = new Request('http://localhost/api') + const response = handler.subscribe(request) + + expect(response.status).toBe(400) + }) + }) +}) From dc9f0d04e5d9e33fff3cd08ab865cda114a2267b Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 16:15:10 +0900 Subject: [PATCH 017/101] feat(durably-react): add client-mode hooks for server integration (Phase 23-27) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add useSSESubscription for shared SSE event handling - Add client-mode useJob with fetch trigger and EventSource subscription - Add client-mode useJobRun for subscribing to existing runs via SSE - Add client-mode useJobLogs for log subscription via SSE - Add MockEventSource test utility for SSE testing - 25 new tests covering all client-mode scenarios 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/src/client/index.ts | 22 ++ .../durably-react/src/client/use-job-logs.ts | 50 +++ .../durably-react/src/client/use-job-run.ts | 81 +++++ packages/durably-react/src/client/use-job.ts | 167 +++++++++ .../src/client/use-sse-subscription.ts | 137 ++++++++ .../tests/client/mock-event-source.ts | 104 ++++++ .../tests/client/use-job-logs.test.tsx | 211 ++++++++++++ .../tests/client/use-job-run.test.tsx | 200 +++++++++++ .../tests/client/use-job.test.tsx | 316 ++++++++++++++++++ 9 files changed, 1288 insertions(+) create mode 100644 packages/durably-react/src/client/index.ts create mode 100644 packages/durably-react/src/client/use-job-logs.ts create mode 100644 packages/durably-react/src/client/use-job-run.ts create mode 100644 packages/durably-react/src/client/use-job.ts create mode 100644 packages/durably-react/src/client/use-sse-subscription.ts create mode 100644 packages/durably-react/tests/client/mock-event-source.ts create mode 100644 packages/durably-react/tests/client/use-job-logs.test.tsx create mode 100644 packages/durably-react/tests/client/use-job-run.test.tsx create mode 100644 packages/durably-react/tests/client/use-job.test.tsx diff --git a/packages/durably-react/src/client/index.ts b/packages/durably-react/src/client/index.ts new file mode 100644 index 00000000..afa9e6cc --- /dev/null +++ b/packages/durably-react/src/client/index.ts @@ -0,0 +1,22 @@ +/** + * Server-connected (client mode) exports + * Use these when connecting to a remote Durably server via HTTP/SSE + */ + +export { useJob } from './use-job' +export type { UseJobClientOptions, UseJobClientResult } from './use-job' + +export { useJobRun } from './use-job-run' +export type { + UseJobRunClientOptions, + UseJobRunClientResult, +} from './use-job-run' + +export { useJobLogs } from './use-job-logs' +export type { + UseJobLogsClientOptions, + UseJobLogsClientResult, +} from './use-job-logs' + +// Re-export types for convenience +export type { LogEntry, Progress, RunStatus } from '../types' diff --git a/packages/durably-react/src/client/use-job-logs.ts b/packages/durably-react/src/client/use-job-logs.ts new file mode 100644 index 00000000..a8b22089 --- /dev/null +++ b/packages/durably-react/src/client/use-job-logs.ts @@ -0,0 +1,50 @@ +import type { LogEntry } from '../types' +import { useSSESubscription } from './use-sse-subscription' + +export interface UseJobLogsClientOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string + /** + * The run ID to subscribe to logs for + */ + runId: string | null + /** + * Maximum number of logs to keep (default: unlimited) + */ + maxLogs?: number +} + +export interface UseJobLogsClientResult { + /** + * Whether the hook is ready (always true for client mode) + */ + isReady: boolean + /** + * Logs collected during execution + */ + logs: LogEntry[] + /** + * Clear all logs + */ + clearLogs: () => void +} + +/** + * Hook for subscribing to logs from a run via server API. + * Uses EventSource for SSE subscription. + */ +export function useJobLogs( + options: UseJobLogsClientOptions, +): UseJobLogsClientResult { + const { api, runId, maxLogs } = options + + const subscription = useSSESubscription(api, runId, { maxLogs }) + + return { + isReady: true, + logs: subscription.logs, + clearLogs: subscription.clearLogs, + } +} diff --git a/packages/durably-react/src/client/use-job-run.ts b/packages/durably-react/src/client/use-job-run.ts new file mode 100644 index 00000000..fdad33bb --- /dev/null +++ b/packages/durably-react/src/client/use-job-run.ts @@ -0,0 +1,81 @@ +import type { LogEntry, Progress, RunStatus } from '../types' +import { useSSESubscription } from './use-sse-subscription' + +export interface UseJobRunClientOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string + /** + * The run ID to subscribe to + */ + runId: string | null +} + +export interface UseJobRunClientResult { + /** + * Whether the hook is ready (always true for client mode) + */ + isReady: boolean + /** + * Current run status + */ + status: RunStatus | null + /** + * Output from completed run + */ + output: TOutput | null + /** + * Error message from failed run + */ + error: string | null + /** + * Logs collected during execution + */ + logs: LogEntry[] + /** + * Current progress + */ + progress: Progress | null + /** + * Whether a run is currently running + */ + isRunning: boolean + /** + * Whether a run is pending + */ + isPending: boolean + /** + * Whether the run completed successfully + */ + isCompleted: boolean + /** + * Whether the run failed + */ + isFailed: boolean +} + +/** + * Hook for subscribing to an existing run via server API. + * Uses EventSource for SSE subscription. + */ +export function useJobRun( + options: UseJobRunClientOptions, +): UseJobRunClientResult { + const { api, runId } = options + + const subscription = useSSESubscription(api, runId) + + return { + isReady: true, + status: subscription.status, + output: subscription.output, + error: subscription.error, + logs: subscription.logs, + progress: subscription.progress, + isRunning: subscription.status === 'running', + isPending: subscription.status === 'pending', + isCompleted: subscription.status === 'completed', + isFailed: subscription.status === 'failed', + } +} diff --git a/packages/durably-react/src/client/use-job.ts b/packages/durably-react/src/client/use-job.ts new file mode 100644 index 00000000..56e13d96 --- /dev/null +++ b/packages/durably-react/src/client/use-job.ts @@ -0,0 +1,167 @@ +import { useCallback, useState } from 'react' +import type { LogEntry, Progress, RunStatus } from '../types' +import { useSSESubscription } from './use-sse-subscription' + +export interface UseJobClientOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string + /** + * Job name to trigger + */ + jobName: string +} + +export interface UseJobClientResult { + /** + * Whether the hook is ready (always true for client mode) + */ + isReady: boolean + /** + * Trigger the job with the given input + */ + trigger: (input: TInput) => Promise<{ runId: string }> + /** + * Trigger and wait for completion + */ + triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> + /** + * Current run status + */ + status: RunStatus | null + /** + * Output from completed run + */ + output: TOutput | null + /** + * Error message from failed run + */ + error: string | null + /** + * Logs collected during execution + */ + logs: LogEntry[] + /** + * Current progress + */ + progress: Progress | null + /** + * Whether a run is currently running + */ + isRunning: boolean + /** + * Whether a run is pending + */ + isPending: boolean + /** + * Whether the run completed successfully + */ + isCompleted: boolean + /** + * Whether the run failed + */ + isFailed: boolean + /** + * Current run ID + */ + currentRunId: string | null + /** + * Reset all state + */ + reset: () => void +} + +/** + * Hook for triggering and subscribing to jobs via server API. + * Uses fetch for triggering and EventSource for SSE subscription. + */ +export function useJob< + TInput extends Record = Record, + TOutput extends Record = Record, +>(options: UseJobClientOptions): UseJobClientResult { + const { api, jobName } = options + + const [currentRunId, setCurrentRunId] = useState(null) + const [isPending, setIsPending] = useState(false) + + const subscription = useSSESubscription(api, currentRunId) + + const trigger = useCallback( + async (input: TInput): Promise<{ runId: string }> => { + // Reset state + subscription.reset() + setIsPending(true) + + const response = await fetch(`${api}/trigger`, { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + }, + body: JSON.stringify({ jobName, input }), + }) + + if (!response.ok) { + setIsPending(false) + const errorText = await response.text() + throw new Error(errorText || `HTTP ${response.status}`) + } + + const { runId } = (await response.json()) as { runId: string } + setCurrentRunId(runId) + + return { runId } + }, + [api, jobName, subscription.reset], + ) + + const triggerAndWait = useCallback( + async (input: TInput): Promise<{ runId: string; output: TOutput }> => { + const { runId } = await trigger(input) + + return new Promise((resolve, reject) => { + const checkInterval = setInterval(() => { + if (subscription.status === 'completed' && subscription.output) { + clearInterval(checkInterval) + resolve({ runId, output: subscription.output }) + } else if (subscription.status === 'failed') { + clearInterval(checkInterval) + reject(new Error(subscription.error ?? 'Job failed')) + } + }, 50) + }) + }, + [trigger, subscription.status, subscription.output, subscription.error], + ) + + const reset = useCallback(() => { + subscription.reset() + setCurrentRunId(null) + setIsPending(false) + }, [subscription.reset]) + + // Compute effective status (pending overrides null when we've triggered but SSE hasn't started) + const effectiveStatus = subscription.status ?? (isPending ? 'pending' : null) + + // Clear pending when we get a real status + if (subscription.status && isPending) { + setIsPending(false) + } + + return { + isReady: true, + trigger, + triggerAndWait, + status: effectiveStatus, + output: subscription.output, + error: subscription.error, + logs: subscription.logs, + progress: subscription.progress, + isRunning: effectiveStatus === 'running', + isPending: effectiveStatus === 'pending', + isCompleted: effectiveStatus === 'completed', + isFailed: effectiveStatus === 'failed', + currentRunId, + reset, + } +} diff --git a/packages/durably-react/src/client/use-sse-subscription.ts b/packages/durably-react/src/client/use-sse-subscription.ts new file mode 100644 index 00000000..5047a350 --- /dev/null +++ b/packages/durably-react/src/client/use-sse-subscription.ts @@ -0,0 +1,137 @@ +import { useCallback, useEffect, useRef, useState } from 'react' +import type { DurablyEvent, LogEntry, Progress, RunStatus } from '../types' + +export interface SSESubscriptionState { + status: RunStatus | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null +} + +export interface UseSSESubscriptionOptions { + /** + * Maximum number of logs to keep (0 = unlimited) + */ + maxLogs?: number +} + +export interface UseSSESubscriptionResult< + TOutput = unknown, +> extends SSESubscriptionState { + /** + * Clear all logs + */ + clearLogs: () => void + /** + * Reset all state + */ + reset: () => void +} + +/** + * Internal hook for subscribing to run events via SSE. + * Used by client-mode hooks (useJob, useJobRun, useJobLogs). + */ +export function useSSESubscription( + api: string | null, + runId: string | null, + options?: UseSSESubscriptionOptions, +): UseSSESubscriptionResult { + const [status, setStatus] = useState(null) + const [output, setOutput] = useState(null) + const [error, setError] = useState(null) + const [logs, setLogs] = useState([]) + const [progress, setProgress] = useState(null) + + const eventSourceRef = useRef(null) + const runIdRef = useRef(runId) + runIdRef.current = runId + + const maxLogs = options?.maxLogs ?? 0 + + // Subscribe to SSE events + useEffect(() => { + if (!api || !runId) return + + const url = `${api}/subscribe?runId=${encodeURIComponent(runId)}` + const eventSource = new EventSource(url) + eventSourceRef.current = eventSource + + eventSource.onmessage = (event) => { + try { + const data = JSON.parse(event.data) as DurablyEvent + if (data.runId !== runIdRef.current) return + + switch (data.type) { + case 'run:start': + setStatus('running') + break + case 'run:complete': + setStatus('completed') + setOutput(data.output as TOutput) + break + case 'run:fail': + setStatus('failed') + setError(data.error) + break + case 'run:progress': + setProgress(data.progress) + break + case 'log:write': + setLogs((prev) => { + const newLog: LogEntry = { + id: crypto.randomUUID(), + runId: data.runId, + stepName: null, + level: data.level, + message: data.message, + data: data.data, + timestamp: new Date().toISOString(), + } + const newLogs = [...prev, newLog] + if (maxLogs > 0 && newLogs.length > maxLogs) { + return newLogs.slice(-maxLogs) + } + return newLogs + }) + break + } + } catch { + // Ignore parse errors + } + } + + eventSource.onerror = () => { + setError('Connection failed') + eventSource.close() + } + + return () => { + eventSource.close() + eventSourceRef.current = null + } + }, [api, runId, maxLogs]) + + const clearLogs = useCallback(() => { + setLogs([]) + }, []) + + const reset = useCallback(() => { + setStatus(null) + setOutput(null) + setError(null) + setLogs([]) + setProgress(null) + }, []) + + return { + status, + output, + error, + logs, + progress, + clearLogs, + reset, + } +} diff --git a/packages/durably-react/tests/client/mock-event-source.ts b/packages/durably-react/tests/client/mock-event-source.ts new file mode 100644 index 00000000..c87a76cc --- /dev/null +++ b/packages/durably-react/tests/client/mock-event-source.ts @@ -0,0 +1,104 @@ +/** + * Mock EventSource for testing SSE connections + */ + +import type { DurablyEvent } from '@coji/durably' + +export interface MockEventSourceInstance { + url: string + readyState: number + onopen: ((event: Event) => void) | null + onmessage: ((event: MessageEvent) => void) | null + onerror: ((event: Event) => void) | null + close: () => void +} + +export interface MockEventSourceController { + instances: MockEventSourceInstance[] + emit: (event: Partial) => void + triggerError: (error: Error) => void + triggerOpen: () => void +} + +export type MockEventSourceConstructor = (new ( + url: string, +) => MockEventSourceInstance) & + MockEventSourceController + +export function createMockEventSource(opts?: { + onClose?: () => void +}): MockEventSourceConstructor { + const instances: MockEventSourceInstance[] = [] + + function MockEventSource( + this: MockEventSourceInstance, + url: string, + ): MockEventSourceInstance { + this.url = url + this.readyState = 0 // CONNECTING + this.onopen = null + this.onmessage = null + this.onerror = null + + this.close = () => { + this.readyState = 2 // CLOSED + opts?.onClose?.() + } + + instances.push(this) + + // Simulate async open + queueMicrotask(() => { + this.readyState = 1 // OPEN + if (this.onopen) { + this.onopen(new Event('open')) + } + }) + + return this + } + + // Static properties for controller + Object.defineProperty(MockEventSource, 'instances', { + get: () => instances, + }) + + Object.defineProperty(MockEventSource, 'emit', { + value: (event: Partial) => { + const latestInstance = instances[instances.length - 1] + if (latestInstance?.onmessage) { + const messageEvent = new MessageEvent('message', { + data: JSON.stringify(event), + }) + latestInstance.onmessage(messageEvent) + } + }, + }) + + Object.defineProperty(MockEventSource, 'triggerError', { + value: (error: Error) => { + const latestInstance = instances[instances.length - 1] + if (latestInstance?.onerror) { + const errorEvent = new Event('error') + Object.defineProperty(errorEvent, 'message', { value: error.message }) + latestInstance.onerror(errorEvent) + } + }, + }) + + Object.defineProperty(MockEventSource, 'triggerOpen', { + value: () => { + const latestInstance = instances[instances.length - 1] + if (latestInstance?.onopen) { + latestInstance.onopen(new Event('open')) + } + }, + }) + + // Add CONNECTING, OPEN, CLOSED constants + Object.defineProperty(MockEventSource, 'CONNECTING', { value: 0 }) + Object.defineProperty(MockEventSource, 'OPEN', { value: 1 }) + Object.defineProperty(MockEventSource, 'CLOSED', { value: 2 }) + + return MockEventSource as unknown as MockEventSourceConstructor +} diff --git a/packages/durably-react/tests/client/use-job-logs.test.tsx b/packages/durably-react/tests/client/use-job-logs.test.tsx new file mode 100644 index 00000000..46eddb99 --- /dev/null +++ b/packages/durably-react/tests/client/use-job-logs.test.tsx @@ -0,0 +1,211 @@ +/** + * Client mode useJobLogs tests + * + * Phase 27: Test log subscription via SSE + */ + +import { act, renderHook, waitFor } from '@testing-library/react' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { useJobLogs } from '../../src/client/use-job-logs' +import { + createMockEventSource, + type MockEventSourceConstructor, +} from './mock-event-source' + +describe('useJobLogs (client)', () => { + let mockEventSource: MockEventSourceConstructor + let originalEventSource: typeof EventSource + + beforeEach(() => { + mockEventSource = createMockEventSource() + originalEventSource = globalThis.EventSource + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + }) + + afterEach(() => { + globalThis.EventSource = originalEventSource + vi.restoreAllMocks() + }) + + it('collects logs from SSE', async () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'log-run' }), + ) + + expect(result.current.isReady).toBe(true) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'log-run', + level: 'info', + message: 'Log 1', + data: null, + }) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'log-run', + level: 'warn', + message: 'Log 2', + data: { warning: true }, + }) + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(2) + expect(result.current.logs[0].message).toBe('Log 1') + expect(result.current.logs[0].level).toBe('info') + expect(result.current.logs[1].message).toBe('Log 2') + expect(result.current.logs[1].level).toBe('warn') + }) + }) + + it('handles null runId', () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: null }), + ) + + expect(result.current.logs).toHaveLength(0) + expect(mockEventSource.instances).toHaveLength(0) + }) + + it('respects maxLogs limit', async () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'max-logs-run', maxLogs: 2 }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + // Emit 3 logs + for (let i = 0; i < 3; i++) { + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'max-logs-run', + level: 'info', + message: `Log ${i}`, + data: null, + }) + }) + } + + await waitFor(() => { + expect(result.current.logs).toHaveLength(2) + // First log should be removed, keep the last 2 + expect(result.current.logs[0].message).toBe('Log 1') + expect(result.current.logs[1].message).toBe('Log 2') + }) + }) + + it('clears logs on clearLogs call', async () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'clear-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'clear-run', + level: 'info', + message: 'Test log', + data: null, + }) + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(1) + }) + + act(() => { + result.current.clearLogs() + }) + + expect(result.current.logs).toHaveLength(0) + }) + + it('ignores logs for different runId', async () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'my-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'other-run', + level: 'info', + message: 'Wrong log', + data: null, + }) + }) + + // Wait a bit and check logs are still empty + await new Promise((r) => setTimeout(r, 50)) + expect(result.current.logs).toHaveLength(0) + }) + + it('closes EventSource on unmount', async () => { + const closeSpy = vi.fn() + mockEventSource = createMockEventSource({ onClose: closeSpy }) + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + + const { unmount } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'unmount-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + unmount() + + expect(closeSpy).toHaveBeenCalled() + }) + + it('provides log metadata', async () => { + const { result } = renderHook(() => + useJobLogs({ api: '/api/durably', runId: 'metadata-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'metadata-run', + level: 'error', + message: 'Error occurred', + data: { code: 500 }, + }) + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(1) + const log = result.current.logs[0] + expect(log.id).toBeDefined() + expect(log.runId).toBe('metadata-run') + expect(log.level).toBe('error') + expect(log.message).toBe('Error occurred') + expect(log.data).toEqual({ code: 500 }) + expect(log.timestamp).toBeDefined() + }) + }) +}) diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx new file mode 100644 index 00000000..364d55e1 --- /dev/null +++ b/packages/durably-react/tests/client/use-job-run.test.tsx @@ -0,0 +1,200 @@ +/** + * Client mode useJobRun tests + * + * Phase 26: Test SSE subscription for existing runs + */ + +import { act, renderHook, waitFor } from '@testing-library/react' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { useJobRun } from '../../src/client/use-job-run' +import { + createMockEventSource, + type MockEventSourceConstructor, +} from './mock-event-source' + +describe('useJobRun (client)', () => { + let mockEventSource: MockEventSourceConstructor + let originalEventSource: typeof EventSource + + beforeEach(() => { + mockEventSource = createMockEventSource() + originalEventSource = globalThis.EventSource + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + }) + + afterEach(() => { + globalThis.EventSource = originalEventSource + vi.restoreAllMocks() + }) + + it('subscribes to run via SSE', async () => { + const { result } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'existing-run' }), + ) + + expect(result.current.isReady).toBe(true) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + // Check URL is correct + expect(mockEventSource.instances[0].url).toBe( + '/api/durably/subscribe?runId=existing-run', + ) + + act(() => { + mockEventSource.emit({ type: 'run:start', runId: 'existing-run' }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('running') + expect(result.current.isRunning).toBe(true) + }) + }) + + it('does not subscribe when runId is null', () => { + renderHook(() => useJobRun({ api: '/api/durably', runId: null })) + + expect(mockEventSource.instances).toHaveLength(0) + }) + + it('provides output when run completes', async () => { + const { result } = renderHook(() => + useJobRun<{ value: number }>({ + api: '/api/durably', + runId: 'complete-run', + }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:complete', + runId: 'complete-run', + output: { value: 42 }, + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('completed') + expect(result.current.output).toEqual({ value: 42 }) + expect(result.current.isCompleted).toBe(true) + }) + }) + + it('provides error when run fails', async () => { + const { result } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'fail-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:fail', + runId: 'fail-run', + error: 'Something went wrong', + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('failed') + expect(result.current.error).toBe('Something went wrong') + expect(result.current.isFailed).toBe(true) + }) + }) + + it('tracks progress updates', async () => { + const { result } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'progress-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:progress', + runId: 'progress-run', + progress: { current: 5, total: 10, message: 'Processing' }, + }) + }) + + await waitFor(() => { + expect(result.current.progress).toEqual({ + current: 5, + total: 10, + message: 'Processing', + }) + }) + }) + + it('collects logs', async () => { + const { result } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'log-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'log-run', + level: 'info', + message: 'Step 1 complete', + data: { step: 1 }, + }) + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(1) + expect(result.current.logs[0].message).toBe('Step 1 complete') + expect(result.current.logs[0].level).toBe('info') + }) + }) + + it('closes EventSource on unmount', async () => { + const closeSpy = vi.fn() + mockEventSource = createMockEventSource({ onClose: closeSpy }) + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + + const { unmount } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'unmount-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + unmount() + + expect(closeSpy).toHaveBeenCalled() + }) + + it('ignores events for different runId', async () => { + const { result } = renderHook(() => + useJobRun({ api: '/api/durably', runId: 'my-run' }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ type: 'run:start', runId: 'other-run' }) + }) + + // Status should remain null since event is for a different run + await new Promise((r) => setTimeout(r, 50)) + expect(result.current.status).toBeNull() + }) +}) diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx new file mode 100644 index 00000000..d9be7adf --- /dev/null +++ b/packages/durably-react/tests/client/use-job.test.tsx @@ -0,0 +1,316 @@ +/** + * Client mode useJob tests + * + * Phase 23-25: Test trigger via fetch and SSE subscription + */ + +import { act, renderHook, waitFor } from '@testing-library/react' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { useJob } from '../../src/client/use-job' +import { + createMockEventSource, + type MockEventSourceConstructor, +} from './mock-event-source' + +describe('useJob (client)', () => { + let mockEventSource: MockEventSourceConstructor + let originalEventSource: typeof EventSource + let originalFetch: typeof fetch + + beforeEach(() => { + mockEventSource = createMockEventSource() + originalEventSource = globalThis.EventSource + originalFetch = globalThis.fetch + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + }) + + afterEach(() => { + globalThis.EventSource = originalEventSource + globalThis.fetch = originalFetch + vi.restoreAllMocks() + }) + + it('triggers via fetch', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'test-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + expect(result.current.isReady).toBe(true) + + const { runId } = await result.current.trigger({ input: 'test' }) + + expect(fetchMock).toHaveBeenCalledWith( + '/api/durably/trigger', + expect.objectContaining({ + method: 'POST', + body: JSON.stringify({ jobName: 'test-job', input: { input: 'test' } }), + }), + ) + expect(runId).toBe('test-run-id') + }) + + it('subscribes via EventSource after trigger', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'sse-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await result.current.trigger({ input: 'test' }) + + // Wait for EventSource to be created + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + // Emit run:start event + act(() => { + mockEventSource.emit({ type: 'run:start', runId: 'sse-run-id' }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('running') + }) + }) + + it('updates status on run:complete', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'complete-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob<{ input: string }, { result: string }>({ + api: '/api/durably', + jobName: 'test-job', + }), + ) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:complete', + runId: 'complete-run-id', + output: { result: 'done' }, + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('completed') + expect(result.current.output).toEqual({ result: 'done' }) + expect(result.current.isCompleted).toBe(true) + }) + }) + + it('updates status on run:fail', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'fail-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:fail', + runId: 'fail-run-id', + error: 'Something went wrong', + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('failed') + expect(result.current.error).toBe('Something went wrong') + expect(result.current.isFailed).toBe(true) + }) + }) + + it('handles progress events', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'progress-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:progress', + runId: 'progress-run-id', + progress: { current: 1, total: 3 }, + }) + }) + + await waitFor(() => { + expect(result.current.progress).toEqual({ current: 1, total: 3 }) + }) + }) + + it('handles log events', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'log-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'log-run-id', + level: 'info', + message: 'Processing', + data: null, + }) + }) + + await waitFor(() => { + expect(result.current.logs).toHaveLength(1) + expect(result.current.logs[0].message).toBe('Processing') + }) + }) + + it('handles connection errors', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'error-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.triggerError(new Error('Connection failed')) + }) + + await waitFor(() => { + expect(result.current.error).toBe('Connection failed') + }) + }) + + it('reset clears all state', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'reset-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:complete', + runId: 'reset-run-id', + output: { result: 'done' }, + }) + }) + + await waitFor(() => { + expect(result.current.isCompleted).toBe(true) + }) + + act(() => { + result.current.reset() + }) + + expect(result.current.status).toBeNull() + expect(result.current.output).toBeNull() + expect(result.current.currentRunId).toBeNull() + }) + + it('provides currentRunId after trigger', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'current-run-id' }), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + expect(result.current.currentRunId).toBeNull() + + await result.current.trigger({ input: 'test' }) + + await waitFor(() => { + expect(result.current.currentRunId).toBe('current-run-id') + }) + }) + + it('throws on fetch error', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: false, + status: 404, + text: () => Promise.resolve('Job not found'), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'unknown-job' }), + ) + + await expect(result.current.trigger({ input: 'test' })).rejects.toThrow( + 'Job not found', + ) + }) +}) From 3789515983c64b0e589f294f22c2fc88912d7c30 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 16:20:41 +0900 Subject: [PATCH 018/101] feat(durably-react): add client entry point and type tests (Phase 28-29) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Complete client.ts entry point with all server-connected hook exports - Add type inference tests to verify proper type checking - Build produces both index.js and client.js entry points 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/src/client.ts | 21 +++- packages/durably-react/tests/types.test.ts | 138 +++++++++++++++++++++ 2 files changed, 156 insertions(+), 3 deletions(-) create mode 100644 packages/durably-react/tests/types.test.ts diff --git a/packages/durably-react/src/client.ts b/packages/durably-react/src/client.ts index 42789a98..c3c821ca 100644 --- a/packages/durably-react/src/client.ts +++ b/packages/durably-react/src/client.ts @@ -1,5 +1,20 @@ // @coji/durably-react/client - Server-connected mode -// This entry point is for connecting to a Durably server via HTTP/SSE -// It does not require @coji/durably as a dependency +// This entry point is for connecting to a remote Durably server via HTTP/SSE -export {} +export { useJob } from './client/use-job' +export type { UseJobClientOptions, UseJobClientResult } from './client/use-job' + +export { useJobRun } from './client/use-job-run' +export type { + UseJobRunClientOptions, + UseJobRunClientResult, +} from './client/use-job-run' + +export { useJobLogs } from './client/use-job-logs' +export type { + UseJobLogsClientOptions, + UseJobLogsClientResult, +} from './client/use-job-logs' + +// Re-export shared types +export type { LogEntry, Progress, RunStatus } from './types' diff --git a/packages/durably-react/tests/types.test.ts b/packages/durably-react/tests/types.test.ts new file mode 100644 index 00000000..8cc5bc73 --- /dev/null +++ b/packages/durably-react/tests/types.test.ts @@ -0,0 +1,138 @@ +/** + * Type inference tests + * + * Phase 29: Verify that types are correctly inferred from job definitions + * + * These tests use vitest's expectTypeOf to verify compile-time type inference + * rather than runtime behavior. + */ + +import { defineJob } from '@coji/durably' +import { describe, expectTypeOf, it } from 'vitest' +import { z } from 'zod' +import type { UseJobResult } from '../src/hooks/use-job' +import type { UseJobLogsResult } from '../src/hooks/use-job-logs' +import type { UseJobRunResult } from '../src/hooks/use-job-run' + +// Test job definitions +const typedJob = defineJob({ + name: 'typed-job', + input: z.object({ taskId: z.string() }), + output: z.object({ success: z.boolean() }), + run: async (_ctx, payload) => ({ success: payload.taskId.length > 0 }), +}) + +const voidOutputJob = defineJob({ + name: 'void-output-job', + input: z.object({ value: z.number() }), + run: async () => {}, +}) + +describe('Type inference', () => { + describe('useJob', () => { + it('infers correct return type', () => { + type Result = UseJobResult<{ taskId: string }, { success: boolean }> + + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf< + 'pending' | 'running' | 'completed' | 'failed' | null + >() + expectTypeOf().toEqualTypeOf<{ + success: boolean + } | null>() + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + expectTypeOf().toEqualTypeOf() + }) + + it('trigger accepts TInput and returns Promise<{ runId: string }>', () => { + type Result = UseJobResult<{ taskId: string }, { success: boolean }> + + expectTypeOf().toBeFunction() + expectTypeOf().parameter(0).toEqualTypeOf<{ + taskId: string + }>() + expectTypeOf().returns.toEqualTypeOf< + Promise<{ runId: string }> + >() + }) + + it('triggerAndWait returns Promise with typed output', () => { + type Result = UseJobResult<{ taskId: string }, { success: boolean }> + + expectTypeOf().toBeFunction() + expectTypeOf().parameter(0).toEqualTypeOf<{ + taskId: string + }>() + expectTypeOf().returns.toEqualTypeOf< + Promise<{ runId: string; output: { success: boolean } }> + >() + }) + + it('reset is a function with no arguments', () => { + type Result = UseJobResult<{ taskId: string }, { success: boolean }> + + expectTypeOf().toBeFunction() + expectTypeOf().returns.toEqualTypeOf() + }) + }) + + describe('useJobRun', () => { + it('infers output type from generic', () => { + type Result = UseJobRunResult<{ data: number[] }> + + expectTypeOf().toEqualTypeOf<{ + data: number[] + } | null>() + expectTypeOf().toEqualTypeOf< + 'pending' | 'running' | 'completed' | 'failed' | null + >() + expectTypeOf().toEqualTypeOf() + }) + + it('defaults to unknown output type', () => { + type Result = UseJobRunResult + + expectTypeOf().toEqualTypeOf() + }) + }) + + describe('useJobLogs', () => { + it('returns logs array and clearLogs function', () => { + type Result = UseJobLogsResult + + expectTypeOf().toBeArray() + expectTypeOf().toBeFunction() + expectTypeOf().toEqualTypeOf() + }) + }) + + describe('Job definition type inference', () => { + it('useJob infers types from job definition', () => { + // This is a compile-time test - if it compiles, types are correct + // In actual usage, the hook would be called inside a React component + + // Verify the job definition has correct types + expectTypeOf(typedJob.name).toEqualTypeOf<'typed-job'>() + + // The input schema should accept the correct type + expectTypeOf(typedJob.input.parse({ taskId: 'test' })).toEqualTypeOf<{ + taskId: string + }>() + + // The output schema should accept the correct type + expectTypeOf(typedJob.output?.parse({ success: true })).toEqualTypeOf< + { success: boolean } | undefined + >() + }) + + it('handles void output jobs', () => { + // Void output job returns void, so no output schema is defined + // We just verify the job compiles correctly without explicit output + expectTypeOf(voidOutputJob.name).toEqualTypeOf<'void-output-job'>() + }) + }) +}) From 8b3f2e2eb2e66a22b6700b77fba455205a6e6203 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 16:27:06 +0900 Subject: [PATCH 019/101] chore: remove implementation plan phase references from test files MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clean up Phase number comments from all source code and test files after completing the durably-react implementation. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../durably-react/tests/browser/provider.test.tsx | 2 +- .../tests/browser/use-job-logs.test.tsx | 2 +- .../tests/browser/use-job-run.test.tsx | 2 +- .../durably-react/tests/browser/use-job.test.tsx | 13 +------------ .../tests/client/use-job-logs.test.tsx | 2 +- .../durably-react/tests/client/use-job-run.test.tsx | 2 +- .../durably-react/tests/client/use-job.test.tsx | 2 +- packages/durably-react/tests/types.test.ts | 2 +- packages/durably/tests/node/core-extensions.test.ts | 8 ++++---- 9 files changed, 12 insertions(+), 23 deletions(-) diff --git a/packages/durably-react/tests/browser/provider.test.tsx b/packages/durably-react/tests/browser/provider.test.tsx index e6cda902..feac4878 100644 --- a/packages/durably-react/tests/browser/provider.test.tsx +++ b/packages/durably-react/tests/browser/provider.test.tsx @@ -1,7 +1,7 @@ /** * DurablyProvider Tests * - * Phase 3-5: Test DurablyProvider initialization, options, and cleanup + * Test DurablyProvider initialization, options, and cleanup */ import type { Durably } from '@coji/durably' diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx index 2acbf621..a27049c3 100644 --- a/packages/durably-react/tests/browser/use-job-logs.test.tsx +++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx @@ -1,7 +1,7 @@ /** * useJobLogs Tests * - * Phase 19: Test useJobLogs hook for subscribing to logs + * Test useJobLogs hook for subscribing to logs */ import { defineJob, type Durably } from '@coji/durably' diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx index 6fcaa9ff..9fc2c4c2 100644 --- a/packages/durably-react/tests/browser/use-job-run.test.tsx +++ b/packages/durably-react/tests/browser/use-job-run.test.tsx @@ -1,7 +1,7 @@ /** * useJobRun Tests * - * Phase 18: Test useJobRun hook for subscribing to existing runs + * Test useJobRun hook for subscribing to existing runs */ import { defineJob, type Durably } from '@coji/durably' diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx index f93df0d4..e88dde87 100644 --- a/packages/durably-react/tests/browser/use-job.test.tsx +++ b/packages/durably-react/tests/browser/use-job.test.tsx @@ -1,7 +1,7 @@ /** * useJob Tests * - * Phase 6-16: Test useJob hook for browser-complete mode + * Test useJob hook for browser-complete mode */ import { defineJob, type Durably } from '@coji/durably' @@ -83,7 +83,6 @@ describe('useJob', () => { ) - // Phase 6: trigger it('returns trigger function that executes job', async () => { const { result } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), @@ -97,7 +96,6 @@ describe('useJob', () => { expect(typeof runId).toBe('string') }) - // Phase 7: status subscription it('updates status from pending to running to completed', async () => { const { result } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), @@ -121,7 +119,6 @@ describe('useJob', () => { }) }) - // Phase 8: output it('provides output when completed', async () => { const { result } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), @@ -136,7 +133,6 @@ describe('useJob', () => { }) }) - // Phase 9: error it('provides error when failed', async () => { const { result } = renderHook(() => useJob(failingJob), { wrapper: createWrapper(), @@ -152,7 +148,6 @@ describe('useJob', () => { }) }) - // Phase 10: progress it('updates progress during execution', async () => { const { result } = renderHook(() => useJob(progressJob), { wrapper: createWrapper(), @@ -173,7 +168,6 @@ describe('useJob', () => { }) }) - // Phase 11: logs it('collects logs during execution', async () => { const { result } = renderHook(() => useJob(loggingJob), { wrapper: createWrapper(), @@ -193,7 +187,6 @@ describe('useJob', () => { expect(log.level).toBe('info') }) - // Phase 12: boolean helpers it('provides boolean helpers', async () => { const { result } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), @@ -227,7 +220,6 @@ describe('useJob', () => { expect(result.current.isFailed).toBe(false) }) - // Phase 13: triggerAndWait it('triggerAndWait resolves with output', async () => { const { result } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), @@ -255,7 +247,6 @@ describe('useJob', () => { ).rejects.toThrow('Something went wrong') }) - // Phase 14: reset it('reset clears all state', async () => { const { result } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), @@ -276,7 +267,6 @@ describe('useJob', () => { expect(result.current.currentRunId).toBeNull() }) - // Phase 15: initialRunId it('sets initialRunId as currentRunId', async () => { const fakeRunId = 'test-run-123' @@ -291,7 +281,6 @@ describe('useJob', () => { expect(result.current.currentRunId).toBe(fakeRunId) }) - // Phase 16: cleanup it('unsubscribes on unmount', async () => { const { result, unmount } = renderHook(() => useJob(testJob), { wrapper: createWrapper(), diff --git a/packages/durably-react/tests/client/use-job-logs.test.tsx b/packages/durably-react/tests/client/use-job-logs.test.tsx index 46eddb99..c17ff799 100644 --- a/packages/durably-react/tests/client/use-job-logs.test.tsx +++ b/packages/durably-react/tests/client/use-job-logs.test.tsx @@ -1,7 +1,7 @@ /** * Client mode useJobLogs tests * - * Phase 27: Test log subscription via SSE + * Test log subscription via SSE */ import { act, renderHook, waitFor } from '@testing-library/react' diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx index 364d55e1..4cf3c507 100644 --- a/packages/durably-react/tests/client/use-job-run.test.tsx +++ b/packages/durably-react/tests/client/use-job-run.test.tsx @@ -1,7 +1,7 @@ /** * Client mode useJobRun tests * - * Phase 26: Test SSE subscription for existing runs + * Test SSE subscription for existing runs */ import { act, renderHook, waitFor } from '@testing-library/react' diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx index d9be7adf..ddd9ea0a 100644 --- a/packages/durably-react/tests/client/use-job.test.tsx +++ b/packages/durably-react/tests/client/use-job.test.tsx @@ -1,7 +1,7 @@ /** * Client mode useJob tests * - * Phase 23-25: Test trigger via fetch and SSE subscription + * Test trigger via fetch and SSE subscription */ import { act, renderHook, waitFor } from '@testing-library/react' diff --git a/packages/durably-react/tests/types.test.ts b/packages/durably-react/tests/types.test.ts index 8cc5bc73..f0826bd8 100644 --- a/packages/durably-react/tests/types.test.ts +++ b/packages/durably-react/tests/types.test.ts @@ -1,7 +1,7 @@ /** * Type inference tests * - * Phase 29: Verify that types are correctly inferred from job definitions + * Verify that types are correctly inferred from job definitions * * These tests use vitest's expectTypeOf to verify compile-time type inference * rather than runtime behavior. diff --git a/packages/durably/tests/node/core-extensions.test.ts b/packages/durably/tests/node/core-extensions.test.ts index a214243c..16f1093e 100644 --- a/packages/durably/tests/node/core-extensions.test.ts +++ b/packages/durably/tests/node/core-extensions.test.ts @@ -1,7 +1,7 @@ /** * Core Extensions Tests * - * Phase 20-22: Test getJob, subscribe, and createDurablyHandler + * Test getJob, subscribe, and createDurablyHandler */ import { afterEach, beforeEach, describe, expect, it } from 'vitest' @@ -28,7 +28,7 @@ describe('Core Extensions', () => { await durably.stop() }) - describe('getJob (Phase 20)', () => { + describe('getJob', () => { const testJob = defineJob({ name: 'test-job-getjob', input: z.object({ value: z.number() }), @@ -60,7 +60,7 @@ describe('Core Extensions', () => { }) }) - describe('subscribe (Phase 21)', () => { + describe('subscribe', () => { const testJob = defineJob({ name: 'test-job-subscribe', input: z.object({ input: z.string() }), @@ -133,7 +133,7 @@ describe('Core Extensions', () => { }) }) - describe('createDurablyHandler (Phase 22)', () => { + describe('createDurablyHandler', () => { const testJob = defineJob({ name: 'test-job-handler', input: z.object({ value: z.number() }), From 561d8b2c9e87aa1691dc3389a9877048721a3648 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 16:36:40 +0900 Subject: [PATCH 020/101] chore(durably-react): bump version to 0.5.0 to match durably MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Align package versions for easier compatibility tracking. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/package.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/durably-react/package.json b/packages/durably-react/package.json index df2bfda1..88fd7775 100644 --- a/packages/durably-react/package.json +++ b/packages/durably-react/package.json @@ -1,6 +1,6 @@ { "name": "@coji/durably-react", - "version": "0.1.0", + "version": "0.5.0", "description": "React bindings for Durably - step-oriented resumable batch execution", "type": "module", "main": "./dist/index.js", From 60489c9b22d54bc6c7db6bece1c6fa76686df7ef Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 16:41:40 +0900 Subject: [PATCH 021/101] docs(durably-react): add README and LLM documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Phase 30: Add documentation for @coji/durably-react package - README.md: Installation, usage examples for both browser and client modes - docs/llms.md: Comprehensive API documentation for LLMs/AI agents 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/README.md | 239 ++++++++++++++ packages/durably-react/docs/llms.md | 477 ++++++++++++++++++++++++++++ 2 files changed, 716 insertions(+) create mode 100644 packages/durably-react/README.md create mode 100644 packages/durably-react/docs/llms.md diff --git a/packages/durably-react/README.md b/packages/durably-react/README.md new file mode 100644 index 00000000..52e5fce3 --- /dev/null +++ b/packages/durably-react/README.md @@ -0,0 +1,239 @@ +# @coji/durably-react + +React bindings for [Durably](https://github.com/coji/durably) - step-oriented resumable batch execution. + +**[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)** + +## Features + +- React hooks for triggering and monitoring Durably jobs +- Real-time status updates, progress, and logs +- Type-safe with full TypeScript support +- Two operation modes: + - **Browser-complete mode**: Run Durably entirely in the browser with OPFS + - **Server-connected mode**: Connect to a remote Durably server via SSE + +## Installation + +```bash +# Browser-complete mode (with SQLocal) +npm install @coji/durably-react @coji/durably kysely zod sqlocal + +# Server-connected mode (client only) +npm install @coji/durably-react +``` + +## Browser-Complete Mode + +Run Durably entirely in the browser using SQLite WASM with OPFS backend. + +### Setup + +```tsx +import { DurablyProvider } from '@coji/durably-react' +import { SQLocalKysely } from 'sqlocal/kysely' + +function App() { + return ( + new SQLocalKysely('app.sqlite3').dialect} + > + + + ) +} +``` + +### useJob Hook + +Trigger and monitor a job's execution: + +```tsx +import { defineJob } from '@coji/durably' +import { useJob } from '@coji/durably-react' +import { z } from 'zod' + +const syncJob = defineJob({ + name: 'sync-data', + input: z.object({ userId: z.string() }), + output: z.object({ count: z.number() }), + run: async (step, payload) => { + const data = await step.run('fetch', () => api.fetch(payload.userId)) + await step.run('save', () => db.save(data)) + return { count: data.length } + }, +}) + +function SyncButton() { + const { trigger, status, output, error, progress, isRunning, isCompleted } = + useJob(syncJob) + + return ( +
+ + + {progress && ( +

+ Progress: {progress.current}/{progress.total} +

+ )} + + {isCompleted &&

Synced {output?.count} items

} + {error &&

Error: {error}

} +
+ ) +} +``` + +### useJobRun Hook + +Subscribe to an existing run by ID: + +```tsx +import { useJobRun } from '@coji/durably-react' + +function RunStatus({ runId }: { runId: string }) { + const { status, output, error, progress } = useJobRun({ runId }) + + return ( +
+

Status: {status}

+ {progress &&

Progress: {progress.message}

} +
+ ) +} +``` + +### useJobLogs Hook + +Subscribe to logs from a run: + +```tsx +import { useJobLogs } from '@coji/durably-react' + +function LogViewer({ runId }: { runId: string }) { + const { logs, clearLogs } = useJobLogs({ runId, maxLogs: 100 }) + + return ( +
+ + {logs.map((log) => ( +
+ [{log.level}] {log.message} +
+ ))} +
+ ) +} +``` + +## Server-Connected Mode + +Connect to a Durably server via HTTP/SSE. No `@coji/durably` dependency needed on the client. + +### Client Setup + +```tsx +import { useJob, useJobRun, useJobLogs } from '@coji/durably-react/client' + +function SyncButton() { + const { trigger, status, output } = useJob< + { userId: string }, + { count: number } + >({ + api: '/api/durably', + jobName: 'sync-data', + }) + + return +} +``` + +### Server Setup + +On your server, use `createDurablyHandler` to expose the API: + +```ts +// server.ts +import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' + +const durably = createDurably({ dialect }) +const handler = createDurablyHandler(durably) + +// Register jobs +durably.register(syncJob) + +// Route handlers +app.post('/api/durably/trigger', (req) => handler.trigger(req)) +app.get('/api/durably/subscribe', (req) => handler.subscribe(req)) +``` + +## API Reference + +### DurablyProvider + +| Prop | Type | Default | Description | +| ---------------- | ---------------- | -------- | ----------------------------- | +| `dialectFactory` | `() => Dialect` | required | Factory for Kysely dialect | +| `options` | `DurablyOptions` | - | Durably configuration options | +| `autoStart` | `boolean` | `true` | Auto-start the worker | +| `autoMigrate` | `boolean` | `true` | Auto-run migrations | + +### useJob (Browser Mode) + +```ts +const result = useJob(jobDefinition, options?) +``` + +**Returns:** + +- `isReady`: Whether Durably is initialized +- `trigger(input)`: Trigger job, returns `{ runId }` +- `triggerAndWait(input)`: Trigger and wait for completion +- `status`: `'pending' | 'running' | 'completed' | 'failed' | null` +- `output`: Job output (when completed) +- `error`: Error message (when failed) +- `progress`: `{ current, total?, message? }` +- `logs`: Array of log entries +- `isRunning`, `isPending`, `isCompleted`, `isFailed`: Boolean helpers +- `currentRunId`: Current run ID +- `reset()`: Reset all state + +### useJob (Client Mode) + +```ts +const result = useJob({ api, jobName }) +``` + +Same return type as browser mode. + +### useJobRun + +```ts +const result = useJobRun({ runId }) // Browser mode +const result = useJobRun({ api, runId }) // Client mode +``` + +**Returns:** Same as `useJob` except no `trigger` functions. + +### useJobLogs + +```ts +const result = useJobLogs({ runId, maxLogs? }) // Browser mode +const result = useJobLogs({ api, runId, maxLogs? }) // Client mode +``` + +**Returns:** + +- `isReady`: Whether ready +- `logs`: Array of log entries +- `clearLogs()`: Clear collected logs + +## License + +MIT diff --git a/packages/durably-react/docs/llms.md b/packages/durably-react/docs/llms.md new file mode 100644 index 00000000..a2941da4 --- /dev/null +++ b/packages/durably-react/docs/llms.md @@ -0,0 +1,477 @@ +# Durably React - LLM Documentation + +> React bindings for Durably - step-oriented resumable batch execution. + +## Overview + +`@coji/durably-react` provides React hooks for triggering and monitoring Durably jobs. It supports two modes: + +1. **Browser-complete mode**: Run Durably entirely in the browser with SQLite WASM +2. **Server-connected mode**: Connect to a remote Durably server via SSE + +## Installation + +```bash +# Browser-complete mode +npm install @coji/durably-react @coji/durably kysely zod sqlocal + +# Server-connected mode (client only) +npm install @coji/durably-react +``` + +## Browser-Complete Mode + +### DurablyProvider + +Wraps your app and initializes Durably: + +```tsx +import { DurablyProvider } from '@coji/durably-react' +import { SQLocalKysely } from 'sqlocal/kysely' + +function App() { + return ( + new SQLocalKysely('app.sqlite3').dialect} + options={{ pollingInterval: 100 }} + autoStart={true} + autoMigrate={true} + > + + + ) +} +``` + +**Props:** + +- `dialectFactory: () => Dialect` - Factory for Kysely dialect +- `options?: DurablyOptions` - Durably configuration +- `autoStart?: boolean` - Auto-start worker (default: true) +- `autoMigrate?: boolean` - Auto-run migrations (default: true) +- `onReady?: (durably: Durably) => void` - Callback when ready + +### useDurably + +Access the Durably instance directly: + +```tsx +import { useDurably } from '@coji/durably-react' + +function Component() { + const { durably, isReady, error } = useDurably() + + if (!isReady) return
Loading...
+ if (error) return
Error: {error.message}
+ + // Use durably instance directly +} +``` + +### useJob + +Trigger and monitor a job: + +```tsx +import { defineJob } from '@coji/durably' +import { useJob } from '@coji/durably-react' +import { z } from 'zod' + +const myJob = defineJob({ + name: 'my-job', + input: z.object({ value: z.string() }), + output: z.object({ result: z.number() }), + run: async (step, payload) => { + const data = await step.run('process', () => process(payload.value)) + return { result: data.length } + }, +}) + +function Component() { + const { + isReady, + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning, + isPending, + isCompleted, + isFailed, + currentRunId, + reset, + } = useJob(myJob, { initialRunId: undefined }) + + // Trigger job + const handleClick = async () => { + const { runId } = await trigger({ value: 'test' }) + console.log('Started:', runId) + } + + // Or trigger and wait for result + const handleSync = async () => { + const { runId, output } = await triggerAndWait({ value: 'test' }) + console.log('Result:', output.result) + } + + return ( +
+ +

Status: {status}

+ {progress && ( +

+ Progress: {progress.current}/{progress.total} +

+ )} + {isCompleted &&

Result: {output?.result}

} + {isFailed &&

Error: {error}

} + +
+ ) +} +``` + +**Return type:** + +```ts +interface UseJobResult { + isReady: boolean + trigger: (input: TInput) => Promise<{ runId: string }> + triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> + status: 'pending' | 'running' | 'completed' | 'failed' | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null + isRunning: boolean + isPending: boolean + isCompleted: boolean + isFailed: boolean + currentRunId: string | null + reset: () => void +} +``` + +### useJobRun + +Subscribe to an existing run by ID: + +```tsx +import { useJobRun } from '@coji/durably-react' + +function RunMonitor({ runId }: { runId: string | null }) { + const { + isReady, + status, + output, + error, + progress, + logs, + isRunning, + isCompleted, + isFailed, + } = useJobRun<{ result: number }>({ runId }) + + if (!runId) return
No run selected
+ + return ( +
+

Status: {status}

+ {isCompleted &&

Output: {JSON.stringify(output)}

} +
+ ) +} +``` + +**Return type:** + +```ts +interface UseJobRunResult { + isReady: boolean + status: RunStatus | null + output: TOutput | null + error: string | null + progress: Progress | null + logs: LogEntry[] + isRunning: boolean + isPending: boolean + isCompleted: boolean + isFailed: boolean +} +``` + +### useJobLogs + +Subscribe to logs from a run: + +```tsx +import { useJobLogs } from '@coji/durably-react' + +function LogViewer({ runId }: { runId: string | null }) { + const { isReady, logs, clearLogs } = useJobLogs({ + runId, + maxLogs: 100, // Optional: limit stored logs + }) + + return ( +
+ +
    + {logs.map((log) => ( +
  • + [{log.level}] {log.message} + {log.data && 
    {JSON.stringify(log.data)}
    } +
    • + ))} +
+
+ ) +} +``` + +**Return type:** + +```ts +interface UseJobLogsResult { + isReady: boolean + logs: LogEntry[] + clearLogs: () => void +} + +interface LogEntry { + id: string + runId: string + stepName: string | null + level: 'info' | 'warn' | 'error' + message: string + data: unknown + timestamp: string +} +``` + +## Server-Connected Mode + +Import hooks from `@coji/durably-react/client` for server-connected mode. + +### Client useJob + +```tsx +import { useJob } from '@coji/durably-react/client' + +function Component() { + const { + isReady, // Always true in client mode + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning, + isCompleted, + currentRunId, + reset, + } = useJob< + { userId: string }, // Input type + { count: number } // Output type + >({ + api: '/api/durably', + jobName: 'sync-data', + }) + + const handleClick = async () => { + const { runId } = await trigger({ userId: 'user_123' }) + console.log('Started:', runId) + } + + return +} +``` + +### Client useJobRun + +```tsx +import { useJobRun } from '@coji/durably-react/client' + +function Component({ runId }: { runId: string }) { + const { status, output, error, progress, logs } = useJobRun<{ + count: number + }>({ + api: '/api/durably', + runId, + }) + + return
Status: {status}
+} +``` + +### Client useJobLogs + +```tsx +import { useJobLogs } from '@coji/durably-react/client' + +function Component({ runId }: { runId: string }) { + const { logs, clearLogs } = useJobLogs({ + api: '/api/durably', + runId, + maxLogs: 50, + }) + + return ( +
    + {logs.map((log) => ( +
  • {log.message}
    • + ))} +
+ ) +} +``` + +### Server Handler Setup + +On your server, use `createDurablyHandler` from `@coji/durably`: + +```ts +import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' +import { LibsqlDialect } from '@libsql/kysely-libsql' +import { createClient } from '@libsql/client' + +const client = createClient({ url: 'file:local.db' }) +const dialect = new LibsqlDialect({ client }) + +const durably = createDurably({ dialect }) +const handler = createDurablyHandler(durably) + +// Register jobs +const syncJob = defineJob({ + name: 'sync-data', + input: z.object({ userId: z.string() }), + output: z.object({ count: z.number() }), + run: async (step, payload) => { + // Job logic + }, +}) +durably.register(syncJob) + +await durably.migrate() +durably.start() + +// Express/Hono/etc route handlers +app.post('/api/durably/trigger', async (req) => { + return handler.trigger(req) +}) + +app.get('/api/durably/subscribe', (req) => { + return handler.subscribe(req) +}) +``` + +## Type Definitions + +```ts +type RunStatus = 'pending' | 'running' | 'completed' | 'failed' + +interface Progress { + current: number + total?: number + message?: string +} + +interface LogEntry { + id: string + runId: string + stepName: string | null + level: 'info' | 'warn' | 'error' + message: string + data: unknown + timestamp: string +} +``` + +## Common Patterns + +### Loading States + +```tsx +function Component() { + const { isReady, isRunning, trigger } = useJob(myJob) + + if (!isReady) return + + return ( + + ) +} +``` + +### Error Handling + +```tsx +function Component() { + const { trigger, error, isFailed, reset } = useJob(myJob) + + const handleClick = async () => { + try { + await trigger({ value: 'test' }) + } catch (e) { + console.error('Trigger failed:', e) + } + } + + if (isFailed) { + return ( +
+

Error: {error}

+ +
+ ) + } + + return +} +``` + +### Progress Tracking + +```tsx +function Component() { + const { trigger, progress, isRunning } = useJob(progressJob) + + return ( +
+ + {isRunning && progress && ( +
+ +

{progress.message}

+
+ )} +
+ ) +} +``` + +### Reconnecting to Existing Run + +```tsx +function Component({ existingRunId }: { existingRunId?: string }) { + const { status, output } = useJob(myJob, { + initialRunId: existingRunId, + }) + + // Will automatically subscribe to the existing run + return
Status: {status}
+} +``` + +## License + +MIT From 3226d4cacd1df47f142e496162bbbccd6de207e6 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 16:45:25 +0900 Subject: [PATCH 022/101] docs(durably): add Advanced APIs section to LLM documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the following APIs: - getJob: Retrieve a registered job by name - subscribe: Subscribe to run events as ReadableStream - createDurablyHandler: Create HTTP handlers for client/server architecture 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably/docs/llms.md | 89 +++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) diff --git a/packages/durably/docs/llms.md b/packages/durably/docs/llms.md index dba8d90f..0b483e6a 100644 --- a/packages/durably/docs/llms.md +++ b/packages/durably/docs/llms.md @@ -200,6 +200,95 @@ durably.on('step:skip', (e) => durably.on('log:write', (e) => console.log(`[${e.level}]`, e.message)) ``` +## Advanced APIs + +### getJob + +Get a registered job by name: + +```ts +const job = durably.getJob('sync-users') +if (job) { + const run = await job.trigger({ orgId: 'org_123' }) +} +``` + +### subscribe + +Subscribe to events for a specific run as a ReadableStream: + +```ts +const stream = durably.subscribe(runId) +const reader = stream.getReader() + +while (true) { + const { done, value } = await reader.read() + if (done) break + + switch (value.type) { + case 'run:start': + console.log('Started') + break + case 'run:complete': + console.log('Completed:', value.output) + break + case 'run:fail': + console.error('Failed:', value.error) + break + case 'run:progress': + console.log('Progress:', value.progress) + break + case 'log:write': + console.log(`[${value.level}]`, value.message) + break + } +} +``` + +### createDurablyHandler + +Create HTTP handlers for client/server architecture using Web Standard Request/Response: + +```ts +import { createDurablyHandler } from '@coji/durably' + +const handler = createDurablyHandler(durably) + +// Trigger endpoint (POST) +// Request body: { jobName, input, idempotencyKey?, concurrencyKey? } +// Response: { runId } +app.post('/api/durably/trigger', async (req) => { + return await handler.trigger(req) +}) + +// Subscribe endpoint (GET with SSE) +// Query param: runId +// Response: Server-Sent Events stream +app.get('/api/durably/subscribe', (req) => { + return handler.subscribe(req) +}) +``` + +**Handler Interface:** + +```ts +interface DurablyHandler { + trigger(request: Request): Promise + subscribe(request: Request): Response +} + +interface TriggerRequest { + jobName: string + input: Record + idempotencyKey?: string + concurrencyKey?: string +} + +interface TriggerResponse { + runId: string +} +``` + ## Plugins ### Log Persistence From 2d10bb4ad893645048cd9750535d743b08ea6a9b Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 17:02:38 +0900 Subject: [PATCH 023/101] docs: comprehensive documentation update for durably-react MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CHANGELOG.md: Add durably-react 0.5.0 release notes and new core APIs - README.md: Add Packages section with monorepo structure - website/guide/react.md: Add @coji/durably-react as recommended approach - website/api/durably-react.md: New React API reference page - website/api/index.md: Add React API section - website/.vitepress/config.ts: Add durably-react to sidebar 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 18 ++ README.md | 7 + website/.vitepress/config.ts | 6 +- website/api/durably-react.md | 342 +++++++++++++++++++++++++++++++++++ website/api/index.md | 14 +- website/guide/react.md | 113 +++++++++++- 6 files changed, 496 insertions(+), 4 deletions(-) create mode 100644 website/api/durably-react.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 43271f0f..97fc4fa0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,9 +9,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ### Added +#### @coji/durably + - `run:progress` event: Now emitted when `step.progress()` is called - Enables real-time progress tracking via event subscription - Event payload: `{ runId, jobName, progress: { current, total?, message? } }` +- `getJob(name)`: Retrieve a registered job by name +- `subscribe(runId)`: Subscribe to run events as a ReadableStream +- `createDurablyHandler(durably)`: Create HTTP handlers for client/server architecture + +#### @coji/durably-react (New Package) + +- Initial release of React bindings for Durably +- **Browser-complete mode**: Run Durably entirely in the browser with SQLite WASM + - `DurablyProvider`: React context provider for Durably instance + - `useDurably`: Access the Durably instance directly + - `useJob`: Trigger and monitor a job with real-time updates + - `useJobRun`: Subscribe to an existing run by ID + - `useJobLogs`: Subscribe to logs from a run +- **Server-connected mode**: Connect to a remote Durably server via SSE + - `useJob`, `useJobRun`, `useJobLogs` from `@coji/durably-react/client` + - Works with `createDurablyHandler` on the server ## [0.4.0] - 2025-12-23 diff --git a/README.md b/README.md index c8e581e6..12e3ac28 100644 --- a/README.md +++ b/README.md @@ -4,6 +4,13 @@ Step-oriented resumable batch execution for Node.js and browsers using SQLite. **[Documentation](https://coji.github.io/durably/)** | **[Live Demo](https://durably-demo.vercel.app)** +## Packages + +| Package | Description | +|---------|-------------| +| [@coji/durably](./packages/durably) | Core library - job definitions, steps, and persistence | +| [@coji/durably-react](./packages/durably-react) | React bindings - hooks for triggering and monitoring jobs | + ## Features - Resumable batch processing with step-level persistence diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts index d2266c8b..6ddfedd9 100644 --- a/website/.vitepress/config.ts +++ b/website/.vitepress/config.ts @@ -46,7 +46,7 @@ export default defineConfig({ ], '/api/': [ { - text: 'API Reference', + text: 'Core API', items: [ { text: 'Overview', link: '/api/' }, { text: 'createDurably', link: '/api/create-durably' }, @@ -55,6 +55,10 @@ export default defineConfig({ { text: 'Events', link: '/api/events' }, ], }, + { + text: 'React API', + items: [{ text: 'durably-react', link: '/api/durably-react' }], + }, ], }, diff --git a/website/api/durably-react.md b/website/api/durably-react.md new file mode 100644 index 00000000..08a1e811 --- /dev/null +++ b/website/api/durably-react.md @@ -0,0 +1,342 @@ +# durably-react + +React bindings for Durably - hooks for triggering and monitoring jobs. + +## Installation + +```bash +# Browser-complete mode +npm install @coji/durably-react @coji/durably kysely zod sqlocal + +# Server-connected mode (client only) +npm install @coji/durably-react +``` + +## Browser-Complete Mode + +Run Durably entirely in the browser using SQLite WASM. + +### DurablyProvider + +Wraps your app and initializes Durably. + +```tsx +import { DurablyProvider } from '@coji/durably-react' +import { SQLocalKysely } from 'sqlocal/kysely' + +function App() { + return ( + new SQLocalKysely('app.sqlite3').dialect} + options={{ pollingInterval: 100 }} + autoStart={true} + autoMigrate={true} + > + + + ) +} +``` + +**Props:** + +| Prop | Type | Default | Description | +|------|------|---------|-------------| +| `dialectFactory` | `() => Dialect` | required | Factory for Kysely dialect | +| `options` | `DurablyOptions` | - | Durably configuration | +| `autoStart` | `boolean` | `true` | Auto-start worker | +| `autoMigrate` | `boolean` | `true` | Auto-run migrations | +| `onReady` | `(durably: Durably) => void` | - | Callback when ready | + +### useDurably + +Access the Durably instance directly. + +```tsx +import { useDurably } from '@coji/durably-react' + +function Component() { + const { durably, isReady, error } = useDurably() + + if (!isReady) return
Loading...
+ if (error) return
Error: {error.message}
+ + // Use durably instance directly +} +``` + +### useJob + +Trigger and monitor a job. + +```tsx +import { defineJob } from '@coji/durably' +import { useJob } from '@coji/durably-react' +import { z } from 'zod' + +const myJob = defineJob({ + name: 'my-job', + input: z.object({ value: z.string() }), + output: z.object({ result: z.number() }), + run: async (step, payload) => { + const data = await step.run('process', () => process(payload.value)) + return { result: data.length } + }, +}) + +function Component() { + const { + isReady, + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning, + isPending, + isCompleted, + isFailed, + currentRunId, + reset, + } = useJob(myJob, { initialRunId: undefined }) + + const handleClick = async () => { + const { runId } = await trigger({ value: 'test' }) + console.log('Started:', runId) + } + + return ( +
+ +

Status: {status}

+ {progress &&

Progress: {progress.current}/{progress.total}

} + {isCompleted &&

Result: {output?.result}

} + {isFailed &&

Error: {error}

} + +
+ ) +} +``` + +**Return Type:** + +```ts +interface UseJobResult { + isReady: boolean + trigger: (input: TInput) => Promise<{ runId: string }> + triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }> + status: 'pending' | 'running' | 'completed' | 'failed' | null + output: TOutput | null + error: string | null + logs: LogEntry[] + progress: Progress | null + isRunning: boolean + isPending: boolean + isCompleted: boolean + isFailed: boolean + currentRunId: string | null + reset: () => void +} +``` + +### useJobRun + +Subscribe to an existing run by ID. + +```tsx +import { useJobRun } from '@coji/durably-react' + +function RunMonitor({ runId }: { runId: string | null }) { + const { + isReady, + status, + output, + error, + progress, + logs, + isRunning, + isCompleted, + isFailed, + } = useJobRun<{ result: number }>({ runId }) + + if (!runId) return
No run selected
+ + return ( +
+

Status: {status}

+ {isCompleted &&

Output: {JSON.stringify(output)}

} +
+ ) +} +``` + +### useJobLogs + +Subscribe to logs from a run. + +```tsx +import { useJobLogs } from '@coji/durably-react' + +function LogViewer({ runId }: { runId: string | null }) { + const { isReady, logs, clearLogs } = useJobLogs({ + runId, + maxLogs: 100, + }) + + return ( +
+ +
    + {logs.map((log) => ( +
  • + [{log.level}] {log.message} + {log.data && 
    {JSON.stringify(log.data)}
    } +
    • + ))} +
+
+ ) +} +``` + +## Server-Connected Mode + +Import hooks from `@coji/durably-react/client` for server-connected mode. + +### useJob (Client) + +```tsx +import { useJob } from '@coji/durably-react/client' + +function Component() { + const { + isReady, // Always true in client mode + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning, + isCompleted, + currentRunId, + reset, + } = useJob< + { userId: string }, // Input type + { count: number } // Output type + >({ + api: '/api/durably', + jobName: 'sync-data', + }) + + const handleClick = async () => { + const { runId } = await trigger({ userId: 'user_123' }) + console.log('Started:', runId) + } + + return +} +``` + +### useJobRun (Client) + +```tsx +import { useJobRun } from '@coji/durably-react/client' + +function Component({ runId }: { runId: string }) { + const { status, output, error, progress, logs } = useJobRun<{ count: number }>({ + api: '/api/durably', + runId, + }) + + return
Status: {status}
+} +``` + +### useJobLogs (Client) + +```tsx +import { useJobLogs } from '@coji/durably-react/client' + +function Component({ runId }: { runId: string }) { + const { logs, clearLogs } = useJobLogs({ + api: '/api/durably', + runId, + maxLogs: 50, + }) + + return ( +
    + {logs.map((log) => ( +
  • {log.message}
    • + ))} +
+ ) +} +``` + +### Server Setup + +On your server, use `createDurablyHandler` from `@coji/durably`: + +```ts +import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' +import { LibsqlDialect } from '@libsql/kysely-libsql' +import { createClient } from '@libsql/client' + +const client = createClient({ url: 'file:local.db' }) +const dialect = new LibsqlDialect({ client }) + +const durably = createDurably({ dialect }) +const handler = createDurablyHandler(durably) + +// Register jobs +const syncJob = defineJob({ + name: 'sync-data', + input: z.object({ userId: z.string() }), + output: z.object({ count: z.number() }), + run: async (step, payload) => { + // Job logic + }, +}) +durably.register(syncJob) + +await durably.migrate() +durably.start() + +// Route handlers (Express/Hono/etc) +app.post('/api/durably/trigger', async (req) => { + return handler.trigger(req) +}) + +app.get('/api/durably/subscribe', (req) => { + return handler.subscribe(req) +}) +``` + +## Type Definitions + +```ts +type RunStatus = 'pending' | 'running' | 'completed' | 'failed' + +interface Progress { + current: number + total?: number + message?: string +} + +interface LogEntry { + id: string + runId: string + stepName: string | null + level: 'info' | 'warn' | 'error' + message: string + data: unknown + timestamp: string +} +``` diff --git a/website/api/index.md b/website/api/index.md index 82900325..1c0add7c 100644 --- a/website/api/index.md +++ b/website/api/index.md @@ -2,7 +2,7 @@ This section provides detailed API documentation for Durably. -## Core API +## Core API (@coji/durably) | Export | Description | |--------|-------------| @@ -11,6 +11,18 @@ This section provides detailed API documentation for Durably. | [`Step`](/api/step) | Step context for job handlers | | [`Events`](/api/events) | Event types and subscriptions | +## React API (@coji/durably-react) + +| Export | Description | +|--------|-------------| +| [`DurablyProvider`](/api/durably-react#durablyprovider) | React context provider | +| [`useJob`](/api/durably-react#usejob) | Trigger and monitor a job | +| [`useJobRun`](/api/durably-react#usejobrun) | Subscribe to an existing run | +| [`useJobLogs`](/api/durably-react#usejoblogs) | Subscribe to logs from a run | +| [`useDurably`](/api/durably-react#usedurably) | Access Durably instance directly | + +See the [durably-react API reference](/api/durably-react) for detailed documentation. + ## Quick Reference ### Creating an Instance diff --git a/website/guide/react.md b/website/guide/react.md index a78ed101..cfb518ce 100644 --- a/website/guide/react.md +++ b/website/guide/react.md @@ -1,8 +1,117 @@ # React -This guide covers using Durably in React applications with best practices for hooks, StrictMode, and state management. +This guide covers using Durably in React applications. -## Basic Setup +## Using @coji/durably-react (Recommended) + +The `@coji/durably-react` package provides ready-to-use React hooks for triggering and monitoring Durably jobs. + +### Installation + +```bash +# Browser-complete mode (run Durably entirely in the browser) +npm install @coji/durably-react @coji/durably kysely zod sqlocal + +# Server-connected mode (connect to a Durably server) +npm install @coji/durably-react +``` + +### Browser-Complete Mode + +Run Durably entirely in the browser using SQLite WASM with OPFS backend. + +```tsx +import { DurablyProvider, useJob } from '@coji/durably-react' +import { defineJob } from '@coji/durably' +import { SQLocalKysely } from 'sqlocal/kysely' +import { z } from 'zod' + +// Define job outside component +const syncJob = defineJob({ + name: 'sync-data', + input: z.object({ userId: z.string() }), + output: z.object({ count: z.number() }), + run: async (step, payload) => { + const data = await step.run('fetch', () => api.fetch(payload.userId)) + await step.run('save', () => db.save(data)) + return { count: data.length } + }, +}) + +function SyncButton() { + const { trigger, status, output, error, progress, isRunning, isCompleted } = + useJob(syncJob) + + return ( +
+ + + {progress && ( +

+ Progress: {progress.current}/{progress.total} +

+ )} + + {isCompleted &&

Synced {output?.count} items

} + {error &&

Error: {error}

} +
+ ) +} + +function App() { + return ( + new SQLocalKysely('app.sqlite3').dialect} + > + + + ) +} +``` + +### Server-Connected Mode + +Connect to a Durably server via HTTP/SSE. No `@coji/durably` dependency needed on the client. + +```tsx +import { useJob } from '@coji/durably-react/client' + +function SyncButton() { + const { trigger, status, output } = useJob< + { userId: string }, + { count: number } + >({ + api: '/api/durably', + jobName: 'sync-data', + }) + + return ( + + ) +} +``` + +### Available Hooks + +| Hook | Description | +|------|-------------| +| `useJob` | Trigger and monitor a job with real-time status, progress, and logs | +| `useJobRun` | Subscribe to an existing run by ID | +| `useJobLogs` | Subscribe to logs from a run with optional limit | +| `useDurably` | Access the Durably instance directly (browser mode only) | + +See the [API Reference](/api/durably-react) for detailed documentation. + +--- + +## Low-Level Integration + +If you need more control or can't use `@coji/durably-react`, you can integrate Durably directly using React hooks and the event system. ### Creating a Durably Instance From 4b5d61a4447dbc4c530659773b561337a3790fff Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 17:04:46 +0900 Subject: [PATCH 024/101] docs(website): remove redundant Low-Level Integration section from React guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The @coji/durably-react package now provides all necessary hooks, making the manual integration patterns unnecessary. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- website/guide/react.md | 429 +---------------------------------------- 1 file changed, 2 insertions(+), 427 deletions(-) diff --git a/website/guide/react.md b/website/guide/react.md index cfb518ce..8babdd61 100644 --- a/website/guide/react.md +++ b/website/guide/react.md @@ -2,11 +2,9 @@ This guide covers using Durably in React applications. -## Using @coji/durably-react (Recommended) +The `@coji/durably-react` package provides React hooks for triggering and monitoring Durably jobs. -The `@coji/durably-react` package provides ready-to-use React hooks for triggering and monitoring Durably jobs. - -### Installation +## Installation ```bash # Browser-complete mode (run Durably entirely in the browser) @@ -106,426 +104,3 @@ function SyncButton() { | `useDurably` | Access the Durably instance directly (browser mode only) | See the [API Reference](/api/durably-react) for detailed documentation. - ---- - -## Low-Level Integration - -If you need more control or can't use `@coji/durably-react`, you can integrate Durably directly using React hooks and the event system. - -### Creating a Durably Instance - -Create a singleton instance outside of React components: - -```tsx -// lib/durably.ts -import { createDurably } from '@coji/durably' -import { SQLocalKysely } from 'sqlocal/kysely' - -const { dialect } = new SQLocalKysely('app.sqlite3') - -export const durably = createDurably({ - dialect, - pollingInterval: 100, - heartbeatInterval: 500, - staleThreshold: 3000, -}) -``` - -### Initialization Hook - -```tsx -// hooks/useDurably.ts -import { useEffect, useState } from 'react' -import { durably } from '../lib/durably' - -export function useDurably() { - const [ready, setReady] = useState(false) - - useEffect(() => { - let cancelled = false - - async function init() { - await durably.migrate() - if (!cancelled) { - durably.start() - setReady(true) - } - } - init() - - return () => { - cancelled = true - durably.stop() - } - }, []) - - return { ready, durably } -} -``` - -## StrictMode Compatibility - -React StrictMode mounts and unmounts components twice in development. Durably handles this gracefully, but you should follow these patterns: - -### Use a Cancelled Flag - -```tsx -useEffect(() => { - let cancelled = false - - async function init() { - await durably.migrate() - if (cancelled) return // Check before state updates - - durably.start() - setReady(true) - } - init() - - return () => { - cancelled = true - durably.stop() - } -}, []) -``` - -### Singleton Pattern - -For shared state across components: - -```tsx -// lib/durably.ts -let instance: Durably | null = null -let initPromise: Promise | null = null - -export async function getDurably() { - if (!instance) { - const { dialect } = new SQLocalKysely('app.sqlite3') - instance = createDurably({ dialect }) - initPromise = instance.migrate() - } - await initPromise - return instance -} - -// hooks/useDurably.ts -export function useDurably() { - const [durably, setDurably] = useState(null) - - useEffect(() => { - let cancelled = false - - getDurably().then((d) => { - if (!cancelled) { - d.start() - setDurably(d) - } - }) - - return () => { - cancelled = true - } - }, []) - - return durably -} -``` - -## Job Status Tracking - -### Track Individual Job Runs - -```tsx -function useJobStatus(job: JobHandle) { - const [runs, setRuns] = useState([]) - - useEffect(() => { - // Load initial runs - job.getRuns().then(setRuns) - - // Subscribe to updates - const unsubs = [ - durably.on('run:start', async (e) => { - const run = await job.getRun(e.runId) - if (run) setRuns((prev) => [...prev, run]) - }), - durably.on('run:complete', async (e) => { - setRuns((prev) => - prev.map((r) => - r.id === e.runId ? { ...r, status: 'completed', output: e.output } : r - ) - ) - }), - durably.on('run:fail', async (e) => { - setRuns((prev) => - prev.map((r) => - r.id === e.runId ? { ...r, status: 'failed', error: e.error } : r - ) - ) - }), - ] - - return () => unsubs.forEach((fn) => fn()) - }, [job]) - - return runs -} -``` - -### Processing State Hook - -```tsx -function useProcessingState() { - const [processing, setProcessing] = useState(false) - const [currentRunId, setCurrentRunId] = useState(null) - - useEffect(() => { - const unsubs = [ - durably.on('run:start', (e) => { - setProcessing(true) - setCurrentRunId(e.runId) - }), - durably.on('run:complete', () => { - setProcessing(false) - setCurrentRunId(null) - }), - durably.on('run:fail', () => { - setProcessing(false) - setCurrentRunId(null) - }), - ] - - return () => unsubs.forEach((fn) => fn()) - }, []) - - return { processing, currentRunId } -} -``` - -## Progress Tracking - -### With Progress Events - -```tsx -function useProgress(runId: string | null) { - const [progress, setProgress] = useState<{ - current: number - total?: number - message?: string - } | null>(null) - - useEffect(() => { - if (!runId) { - setProgress(null) - return - } - - const unsub = durably.on('run:progress', (e) => { - if (e.runId === runId) { - setProgress({ - current: e.current, - total: e.total, - message: e.message, - }) - } - }) - - return unsub - }, [runId]) - - return progress -} -``` - -### Progress UI Component - -```tsx -function ProgressBar({ runId }: { runId: string | null }) { - const progress = useProgress(runId) - - if (!progress) return null - - const percent = progress.total - ? Math.round((progress.current / progress.total) * 100) - : null - - return ( -
- {percent !== null && ( -
- )} - {progress.message || `${progress.current}/${progress.total || '?'}`} -
- ) -} -``` - -## Complete Example - -```tsx -import { useEffect, useState } from 'react' -import { defineJob } from '@coji/durably' -import { z } from 'zod' -import { durably } from './lib/durably' - -// Define job outside component -const processDataJobDef = defineJob({ - name: 'process-data', - input: z.object({ items: z.array(z.string()) }), - output: z.object({ processed: z.number() }), - run: async (step, payload) => { - let processed = 0 - - for (const item of payload.items) { - await step.run(`process-${item}`, async () => { - // Simulate work - await new Promise((r) => setTimeout(r, 500)) - processed++ - }) - step.progress(processed, payload.items.length) - } - - return { processed } - }, -}) - -// Register the job -const processDataJob = durably.register(processDataJobDef) - -function App() { - const [ready, setReady] = useState(false) - const [processing, setProcessing] = useState(false) - const [result, setResult] = useState<{ processed: number } | null>(null) - - useEffect(() => { - let cancelled = false - - async function init() { - await durably.migrate() - if (cancelled) return - durably.start() - setReady(true) - } - init() - - const unsubs = [ - durably.on('run:start', () => setProcessing(true)), - durably.on('run:complete', (e) => { - setProcessing(false) - setResult(e.output as { processed: number }) - }), - durably.on('run:fail', () => setProcessing(false)), - ] - - return () => { - cancelled = true - unsubs.forEach((fn) => fn()) - durably.stop() - } - }, []) - - const handleProcess = async () => { - setResult(null) - await processDataJob.trigger({ - items: ['item-1', 'item-2', 'item-3'], - }) - } - - if (!ready) { - return
Initializing...
- } - - return ( -
- - - {result &&

Processed {result.processed} items

} -
- ) -} -``` - -## Context Provider Pattern - -For larger applications: - -```tsx -// context/DurablyContext.tsx -import { createContext, useContext, useEffect, useState, ReactNode } from 'react' -import { durably, type Durably } from '../lib/durably' - -interface DurablyContextValue { - durably: Durably - ready: boolean -} - -const DurablyContext = createContext(null) - -export function DurablyProvider({ children }: { children: ReactNode }) { - const [ready, setReady] = useState(false) - - useEffect(() => { - let cancelled = false - - durably.migrate().then(() => { - if (!cancelled) { - durably.start() - setReady(true) - } - }) - - return () => { - cancelled = true - durably.stop() - } - }, []) - - return ( - - {children} - - ) -} - -export function useDurablyContext() { - const context = useContext(DurablyContext) - if (!context) { - throw new Error('useDurablyContext must be used within DurablyProvider') - } - return context -} -``` - -Usage: - -```tsx -// App.tsx -import { DurablyProvider, useDurablyContext } from './context/DurablyContext' - -function JobRunner() { - const { ready } = useDurablyContext() - - if (!ready) return
Loading...
- - return -} - -function App() { - return ( - - - - ) -} -``` - -## Best Practices - -1. **Create durably instance outside components** - Avoid creating instances inside useEffect -2. **Use cancelled flags** - Prevent state updates after unmount -3. **Clean up event listeners** - Always unsubscribe in cleanup -4. **Define jobs at module level** - Jobs should be defined once, not per render -5. **Handle StrictMode** - Test your app in development mode to catch issues early From 21d9b29092dcdf62ecd8335df58c08398899e519 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 17:10:52 +0900 Subject: [PATCH 025/101] docs: remove browser guide and consolidate content into react guide MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Merge Secure Context, COOP/COEP Headers, Vite config into React guide - Add Limitations and Tab Suspension sections to React guide - Remove Browser from Platforms navigation - Update Deployment guide to link to React instead of Browser 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- website/.vitepress/config.ts | 1 - website/guide/browser.md | 124 ----------------------------------- website/guide/deployment.md | 4 +- website/guide/react.md | 64 +++++++++++++++++- 4 files changed, 63 insertions(+), 130 deletions(-) delete mode 100644 website/guide/browser.md diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts index 6ddfedd9..b534d854 100644 --- a/website/.vitepress/config.ts +++ b/website/.vitepress/config.ts @@ -38,7 +38,6 @@ export default defineConfig({ text: 'Platforms', items: [ { text: 'Node.js', link: '/guide/nodejs' }, - { text: 'Browser', link: '/guide/browser' }, { text: 'React', link: '/guide/react' }, { text: 'Deployment', link: '/guide/deployment' }, ], diff --git a/website/guide/browser.md b/website/guide/browser.md deleted file mode 100644 index 6f94cceb..00000000 --- a/website/guide/browser.md +++ /dev/null @@ -1,124 +0,0 @@ -# Browser - -This guide covers using Durably in browser environments. - -## Requirements - -### Secure Context - -Durably requires a [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS or localhost) for OPFS access. - -### COOP/COEP Headers - -SQLite WASM requires cross-origin isolation: - -``` -Cross-Origin-Embedder-Policy: require-corp -Cross-Origin-Opener-Policy: same-origin -``` - -#### Vite Configuration - -```ts -// vite.config.ts -export default defineConfig({ - plugins: [ - { - name: 'configure-response-headers', - configureServer: (server) => { - server.middlewares.use((_req, res, next) => { - res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp') - res.setHeader('Cross-Origin-Opener-Policy', 'same-origin') - next() - }) - }, - }, - ], - worker: { - format: 'es', - }, - optimizeDeps: { - exclude: ['sqlocal'], - }, -}) -``` - -## SQLite Setup - -Using [SQLocal](https://sqlocal.dev/) with OPFS: - -```ts -import { SQLocalKysely } from 'sqlocal/kysely' - -const { dialect, deleteDatabaseFile } = new SQLocalKysely('app.sqlite3') - -const durably = createDurably({ - dialect, - pollingInterval: 100, - heartbeatInterval: 500, - staleThreshold: 3000, -}) -``` - -## Browser-Specific Configuration - -Lower intervals for responsive UI: - -```ts -const durably = createDurably({ - dialect, - pollingInterval: 100, // Check every 100ms - heartbeatInterval: 500, // Heartbeat every 500ms - staleThreshold: 3000, // Stale after 3 seconds -}) -``` - -## React Integration - -For React-specific patterns including hooks, StrictMode compatibility, and state management, see the dedicated [React guide](/guide/react). - -## Tab Suspension - -Browsers can suspend inactive tabs. Durably handles this: - -1. Tab becomes inactive → heartbeat stops -2. Job is marked stale after `staleThreshold` -3. Tab becomes active → worker restarts -4. Stale job is picked up and resumed - -### Testing Resumption - -1. Start a job -2. Reload the page mid-execution -3. The job resumes from the last completed step - -## Database Management - -### Reset Database - -```ts -import { SQLocalKysely } from 'sqlocal/kysely' - -const { dialect, deleteDatabaseFile } = new SQLocalKysely('app.sqlite3') - -// To reset: -await durably.stop() -await deleteDatabaseFile() -location.reload() -``` - -### Database Size - -OPFS has storage limits. Monitor usage: - -```ts -const estimate = await navigator.storage.estimate() -console.log(`Used: ${estimate.usage} / ${estimate.quota}`) -``` - -## Limitations - -1. **Single tab**: OPFS has exclusive access - only one tab can use the database -2. **No SharedWorker**: Workers must be in the same tab -3. **Storage limits**: Browser storage quotas apply -4. **No background sync**: Jobs only run when the tab is active diff --git a/website/guide/deployment.md b/website/guide/deployment.md index 9a303507..686e8ea5 100644 --- a/website/guide/deployment.md +++ b/website/guide/deployment.md @@ -99,9 +99,9 @@ For browser-based workers (using SQLite WASM with OPFS): - Host your static site anywhere (Vercel, Netlify, GitHub Pages) - The worker runs entirely in the user's browser - Data persists in OPFS (Origin Private File System) -- Requires HTTPS (Secure Context) +- Requires HTTPS (Secure Context) and COOP/COEP headers -See [Browser Guide](/guide/browser) for details. +See [React Guide](/guide/react#browser-complete-mode) for details. ## Database Considerations diff --git a/website/guide/react.md b/website/guide/react.md index 8babdd61..7f5bad7e 100644 --- a/website/guide/react.md +++ b/website/guide/react.md @@ -14,10 +14,53 @@ npm install @coji/durably-react @coji/durably kysely zod sqlocal npm install @coji/durably-react ``` -### Browser-Complete Mode +## Browser-Complete Mode Run Durably entirely in the browser using SQLite WASM with OPFS backend. +### Requirements + +#### Secure Context + +Browser-complete mode requires a [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS or localhost) for OPFS access. + +#### COOP/COEP Headers + +SQLite WASM requires cross-origin isolation: + +```http +Cross-Origin-Embedder-Policy: require-corp +Cross-Origin-Opener-Policy: same-origin +``` + +**Vite Configuration:** + +```ts +// vite.config.ts +export default defineConfig({ + plugins: [ + { + name: 'configure-response-headers', + configureServer: (server) => { + server.middlewares.use((_req, res, next) => { + res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp') + res.setHeader('Cross-Origin-Opener-Policy', 'same-origin') + next() + }) + }, + }, + ], + worker: { + format: 'es', + }, + optimizeDeps: { + exclude: ['sqlocal'], + }, +}) +``` + +### Usage + ```tsx import { DurablyProvider, useJob } from '@coji/durably-react' import { defineJob } from '@coji/durably' @@ -72,7 +115,22 @@ function App() { } ``` -### Server-Connected Mode +### Limitations + +- **Single tab**: OPFS has exclusive access - only one tab can use the database +- **Storage limits**: Browser storage quotas apply +- **No background sync**: Jobs only run when the tab is active + +### Tab Suspension + +Browsers can suspend inactive tabs. Durably handles this automatically: + +1. Tab becomes inactive → heartbeat stops +2. Job is marked stale after `staleThreshold` +3. Tab becomes active → worker restarts +4. Stale job is picked up and resumed + +## Server-Connected Mode Connect to a Durably server via HTTP/SSE. No `@coji/durably` dependency needed on the client. @@ -94,7 +152,7 @@ function SyncButton() { } ``` -### Available Hooks +## Available Hooks | Hook | Description | |------|-------------| From 311f619d44cc5f8a425c038a2aa442054b332954 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 17:22:53 +0900 Subject: [PATCH 026/101] docs: reorganize guides by usage pattern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Restructure documentation from technology-based (Node.js/React) to usage-based organization for better user understanding: - Server: Run jobs on Node.js server - Full-Stack: Server execution with React frontend monitoring - Browser-Only: Run entirely in browser without server Changes: - Rename nodejs.md to server.md - Create full-stack.md for client/server architecture - Create browser-only.md for browser-complete mode - Delete react.md (content split into new guides) - Update sidebar: "Platforms" → "Usage" - Fix deployment.md links 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- website/.vitepress/config.ts | 7 +- website/guide/{react.md => browser-only.md} | 76 +++---- website/guide/deployment.md | 2 +- website/guide/full-stack.md | 230 ++++++++++++++++++++ website/guide/{nodejs.md => server.md} | 4 +- 5 files changed, 262 insertions(+), 57 deletions(-) rename website/guide/{react.md => browser-only.md} (70%) create mode 100644 website/guide/full-stack.md rename website/guide/{nodejs.md => server.md} (98%) diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts index b534d854..394e70af 100644 --- a/website/.vitepress/config.ts +++ b/website/.vitepress/config.ts @@ -35,10 +35,11 @@ export default defineConfig({ ], }, { - text: 'Platforms', + text: 'Usage', items: [ - { text: 'Node.js', link: '/guide/nodejs' }, - { text: 'React', link: '/guide/react' }, + { text: 'Server', link: '/guide/server' }, + { text: 'Full-Stack', link: '/guide/full-stack' }, + { text: 'Browser-Only', link: '/guide/browser-only' }, { text: 'Deployment', link: '/guide/deployment' }, ], }, diff --git a/website/guide/react.md b/website/guide/browser-only.md similarity index 70% rename from website/guide/react.md rename to website/guide/browser-only.md index 7f5bad7e..e3ee6d61 100644 --- a/website/guide/react.md +++ b/website/guide/browser-only.md @@ -1,30 +1,26 @@ -# React +# Browser-Only -This guide covers using Durably in React applications. +Run Durably entirely in the browser without a server. Jobs execute in the browser using SQLite WASM with OPFS for persistence. -The `@coji/durably-react` package provides React hooks for triggering and monitoring Durably jobs. +## When to Use + +- Offline-capable applications +- Local-first apps where data stays on the user's device +- Prototyping without backend infrastructure ## Installation ```bash -# Browser-complete mode (run Durably entirely in the browser) npm install @coji/durably-react @coji/durably kysely zod sqlocal - -# Server-connected mode (connect to a Durably server) -npm install @coji/durably-react ``` -## Browser-Complete Mode - -Run Durably entirely in the browser using SQLite WASM with OPFS backend. +## Requirements -### Requirements +### Secure Context -#### Secure Context +Browser-only mode requires a [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS or localhost) for OPFS access. -Browser-complete mode requires a [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS or localhost) for OPFS access. - -#### COOP/COEP Headers +### COOP/COEP Headers SQLite WASM requires cross-origin isolation: @@ -59,7 +55,7 @@ export default defineConfig({ }) ``` -### Usage +## Usage ```tsx import { DurablyProvider, useJob } from '@coji/durably-react' @@ -115,13 +111,24 @@ function App() { } ``` -### Limitations +## Available Hooks + +| Hook | Description | +|------|-------------| +| `useJob` | Trigger and monitor a job with real-time status, progress, and logs | +| `useJobRun` | Subscribe to an existing run by ID | +| `useJobLogs` | Subscribe to logs from a run with optional limit | +| `useDurably` | Access the Durably instance directly | + +See the [API Reference](/api/durably-react) for detailed documentation. + +## Limitations - **Single tab**: OPFS has exclusive access - only one tab can use the database - **Storage limits**: Browser storage quotas apply - **No background sync**: Jobs only run when the tab is active -### Tab Suspension +## Tab Suspension Browsers can suspend inactive tabs. Durably handles this automatically: @@ -129,36 +136,3 @@ Browsers can suspend inactive tabs. Durably handles this automatically: 2. Job is marked stale after `staleThreshold` 3. Tab becomes active → worker restarts 4. Stale job is picked up and resumed - -## Server-Connected Mode - -Connect to a Durably server via HTTP/SSE. No `@coji/durably` dependency needed on the client. - -```tsx -import { useJob } from '@coji/durably-react/client' - -function SyncButton() { - const { trigger, status, output } = useJob< - { userId: string }, - { count: number } - >({ - api: '/api/durably', - jobName: 'sync-data', - }) - - return ( - - ) -} -``` - -## Available Hooks - -| Hook | Description | -|------|-------------| -| `useJob` | Trigger and monitor a job with real-time status, progress, and logs | -| `useJobRun` | Subscribe to an existing run by ID | -| `useJobLogs` | Subscribe to logs from a run with optional limit | -| `useDurably` | Access the Durably instance directly (browser mode only) | - -See the [API Reference](/api/durably-react) for detailed documentation. diff --git a/website/guide/deployment.md b/website/guide/deployment.md index 686e8ea5..f267cd23 100644 --- a/website/guide/deployment.md +++ b/website/guide/deployment.md @@ -101,7 +101,7 @@ For browser-based workers (using SQLite WASM with OPFS): - Data persists in OPFS (Origin Private File System) - Requires HTTPS (Secure Context) and COOP/COEP headers -See [React Guide](/guide/react#browser-complete-mode) for details. +See [Browser-Only Guide](/guide/browser-only) for details. ## Database Considerations diff --git a/website/guide/full-stack.md b/website/guide/full-stack.md new file mode 100644 index 00000000..af9fe61f --- /dev/null +++ b/website/guide/full-stack.md @@ -0,0 +1,230 @@ +# Full-Stack + +Run jobs on the server and monitor them from a React frontend. The server handles job execution while the client provides real-time status updates via SSE. + +## When to Use + +- Web applications with long-running background jobs +- Apps that need reliable server-side execution +- When you want to show job progress in a React UI + +## Architecture + +``` +┌─────────────────┐ HTTP/SSE ┌─────────────────┐ +│ React Client │ ◄──────────────► │ Node.js Server │ +│ (useJob hooks) │ │ (Durably) │ +└─────────────────┘ └─────────────────┘ +``` + +## Installation + +**Client:** + +```bash +npm install @coji/durably-react +``` + +**Server:** + +```bash +npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql +``` + +## Server Setup + +### 1. Create Durably Instance + +```ts +// server/durably.ts +import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' +import { LibsqlDialect } from '@libsql/kysely-libsql' +import { createClient } from '@libsql/client' +import { z } from 'zod' + +const client = createClient({ url: 'file:local.db' }) +const dialect = new LibsqlDialect({ client }) + +export const durably = createDurably({ dialect }) +export const handler = createDurablyHandler(durably) + +// Define and register jobs +export const syncJob = defineJob({ + name: 'sync-data', + input: z.object({ userId: z.string() }), + output: z.object({ count: z.number() }), + run: async (step, payload) => { + const users = await step.run('fetch-users', async () => { + return await api.fetchUsers(payload.userId) + }) + + await step.run('save-to-db', async () => { + await db.saveUsers(users) + }) + + return { count: users.length } + }, +}) + +durably.register(syncJob) +``` + +### 2. Create API Routes + +**Express:** + +```ts +import express from 'express' +import { durably, handler } from './durably' + +const app = express() +app.use(express.json()) + +// Trigger a job +app.post('/api/durably/trigger', async (req, res) => { + const result = await handler.trigger(req) + res.json(result) +}) + +// Subscribe to job events (SSE) +app.get('/api/durably/subscribe', (req, res) => { + return handler.subscribe(req, res) +}) + +// Start server and worker +await durably.migrate() +durably.start() +app.listen(3000) +``` + +**Hono:** + +```ts +import { Hono } from 'hono' +import { durably, handler } from './durably' + +const app = new Hono() + +app.post('/api/durably/trigger', async (c) => { + const result = await handler.trigger(c.req.raw) + return c.json(result) +}) + +app.get('/api/durably/subscribe', (c) => { + return handler.subscribe(c.req.raw) +}) + +await durably.migrate() +durably.start() +export default app +``` + +## Client Setup + +### useJob Hook + +```tsx +import { useJob } from '@coji/durably-react/client' + +function SyncButton() { + const { + trigger, + triggerAndWait, + status, + output, + error, + logs, + progress, + isRunning, + isCompleted, + isFailed, + currentRunId, + reset, + } = useJob< + { userId: string }, // Input type + { count: number } // Output type + >({ + api: '/api/durably', + jobName: 'sync-data', + }) + + return ( +
+ + + {progress && ( +

Progress: {progress.current}/{progress.total}

+ )} + + {isCompleted &&

Synced {output?.count} items

} + {isFailed &&

Error: {error}

} +
+ ) +} +``` + +### useJobRun Hook + +Subscribe to an existing run by ID: + +```tsx +import { useJobRun } from '@coji/durably-react/client' + +function RunMonitor({ runId }: { runId: string }) { + const { status, output, error, progress, logs } = useJobRun<{ count: number }>({ + api: '/api/durably', + runId, + }) + + return ( +
+

Status: {status}

+ {output &&

Result: {output.count} items

} +
+ ) +} +``` + +### useJobLogs Hook + +Subscribe to logs from a run: + +```tsx +import { useJobLogs } from '@coji/durably-react/client' + +function LogViewer({ runId }: { runId: string }) { + const { logs, clearLogs } = useJobLogs({ + api: '/api/durably', + runId, + maxLogs: 100, + }) + + return ( +
+ +
    + {logs.map((log) => ( +
  • + [{log.level}] {log.message} +
    • + ))} +
+
+ ) +} +``` + +## Available Hooks + +| Hook | Description | +|------|-------------| +| `useJob` | Trigger and monitor a job with real-time status, progress, and logs | +| `useJobRun` | Subscribe to an existing run by ID | +| `useJobLogs` | Subscribe to logs from a run with optional limit | + +See the [API Reference](/api/durably-react#server-connected-mode) for detailed documentation. diff --git a/website/guide/nodejs.md b/website/guide/server.md similarity index 98% rename from website/guide/nodejs.md rename to website/guide/server.md index 754cca0e..a558d90d 100644 --- a/website/guide/nodejs.md +++ b/website/guide/server.md @@ -1,6 +1,6 @@ -# Node.js +# Server -This guide covers using Durably in Node.js environments. +This guide covers running Durably on the server (Node.js). ## SQLite Drivers From c4321e1b144e84ae6eb937d5c26a5920275384b4 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 17:33:14 +0900 Subject: [PATCH 027/101] docs: improve introduction pages with clear use cases MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rewrite index.md with 3 clear use cases and guide links - Simplify getting-started.md with setup table and server example - Update full-stack.md for React Router v7 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- website/guide/full-stack.md | 96 +++++++++------------ website/guide/getting-started.md | 143 ++++++++++--------------------- website/guide/index.md | 101 +++++++++++----------- 3 files changed, 136 insertions(+), 204 deletions(-) diff --git a/website/guide/full-stack.md b/website/guide/full-stack.md index af9fe61f..2b8ed17f 100644 --- a/website/guide/full-stack.md +++ b/website/guide/full-stack.md @@ -2,6 +2,8 @@ Run jobs on the server and monitor them from a React frontend. The server handles job execution while the client provides real-time status updates via SSE. +This guide uses [React Router v7](https://reactrouter.com/) as the full-stack framework. + ## When to Use - Web applications with long-running background jobs @@ -12,23 +14,28 @@ Run jobs on the server and monitor them from a React frontend. The server handle ``` ┌─────────────────┐ HTTP/SSE ┌─────────────────┐ -│ React Client │ ◄──────────────► │ Node.js Server │ -│ (useJob hooks) │ │ (Durably) │ +│ React Client │ ◄──────────────► │ React Router │ +│ (useJob hooks) │ │ Server (Durably)│ └─────────────────┘ └─────────────────┘ ``` ## Installation -**Client:** - ```bash -npm install @coji/durably-react +npm install @coji/durably @coji/durably-react kysely zod @libsql/client @libsql/kysely-libsql ``` -**Server:** - -```bash -npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql +## Project Structure + +```txt +app/ +├── .server/ +│ └── durably.ts # Durably instance and jobs +├── routes/ +│ ├── api.durably.trigger.ts # POST /api/durably/trigger +│ └── api.durably.subscribe.ts # GET /api/durably/subscribe +└── routes/ + └── _index.tsx # Client component with useJob ``` ## Server Setup @@ -36,7 +43,7 @@ npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql ### 1. Create Durably Instance ```ts -// server/durably.ts +// app/.server/durably.ts import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' import { LibsqlDialect } from '@libsql/kysely-libsql' import { createClient } from '@libsql/client' @@ -67,56 +74,36 @@ export const syncJob = defineJob({ }) durably.register(syncJob) + +// Initialize on server start +await durably.migrate() +durably.start() ``` ### 2. Create API Routes -**Express:** +**Trigger Route:** ```ts -import express from 'express' -import { durably, handler } from './durably' - -const app = express() -app.use(express.json()) - -// Trigger a job -app.post('/api/durably/trigger', async (req, res) => { - const result = await handler.trigger(req) - res.json(result) -}) - -// Subscribe to job events (SSE) -app.get('/api/durably/subscribe', (req, res) => { - return handler.subscribe(req, res) -}) +// app/routes/api.durably.trigger.ts +import type { Route } from './+types/api.durably.trigger' +import { handler } from '~/.server/durably' -// Start server and worker -await durably.migrate() -durably.start() -app.listen(3000) +export async function action({ request }: Route.ActionArgs) { + return handler.trigger(request) +} ``` -**Hono:** +**Subscribe Route (SSE):** ```ts -import { Hono } from 'hono' -import { durably, handler } from './durably' - -const app = new Hono() - -app.post('/api/durably/trigger', async (c) => { - const result = await handler.trigger(c.req.raw) - return c.json(result) -}) +// app/routes/api.durably.subscribe.ts +import type { Route } from './+types/api.durably.subscribe' +import { handler } from '~/.server/durably' -app.get('/api/durably/subscribe', (c) => { - return handler.subscribe(c.req.raw) -}) - -await durably.migrate() -durably.start() -export default app +export async function loader({ request }: Route.LoaderArgs) { + return handler.subscribe(request) +} ``` ## Client Setup @@ -124,25 +111,22 @@ export default app ### useJob Hook ```tsx +// app/routes/_index.tsx import { useJob } from '@coji/durably-react/client' -function SyncButton() { +export default function Index() { const { trigger, - triggerAndWait, status, output, error, - logs, progress, isRunning, isCompleted, isFailed, - currentRunId, - reset, } = useJob< - { userId: string }, // Input type - { count: number } // Output type + { userId: string }, + { count: number } >({ api: '/api/durably', jobName: 'sync-data', @@ -176,7 +160,7 @@ Subscribe to an existing run by ID: import { useJobRun } from '@coji/durably-react/client' function RunMonitor({ runId }: { runId: string }) { - const { status, output, error, progress, logs } = useJobRun<{ count: number }>({ + const { status, output, error, progress } = useJobRun<{ count: number }>({ api: '/api/durably', runId, }) diff --git a/website/guide/getting-started.md b/website/guide/getting-started.md index f4931145..55cdb84f 100644 --- a/website/guide/getting-started.md +++ b/website/guide/getting-started.md @@ -1,141 +1,86 @@ # Getting Started -## Installation +## Choose Your Setup -::: code-group +| Setup | Description | Guide | +|-------|-------------|-------| +| **Server** | Run jobs on Node.js server | [→](/guide/server) | +| **Full-Stack** | Server execution + React UI for monitoring | [→](/guide/full-stack) | +| **Browser-Only** | Run entirely in the browser (no server) | [→](/guide/browser-only) | -```bash [npm] -npm install @coji/durably kysely zod -``` - -```bash [pnpm] -pnpm add @coji/durably kysely zod -``` - -```bash [yarn] -yarn add @coji/durably kysely zod -``` +## Quick Start (Server) -::: +The simplest way to get started. -### Node.js - -For Node.js, you'll also need a SQLite driver: - -::: code-group - -```bash [libsql (recommended)] -npm install @libsql/client @libsql/kysely-libsql -``` - -```bash [better-sqlite3] -npm install better-sqlite3 -``` - -::: - -### Browser - -For browsers, use SQLite WASM with OPFS: +### 1. Install ```bash -npm install sqlocal +npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql ``` -## Quick Start - -### Node.js Example +### 2. Define a Job ```ts +// jobs.ts import { createDurably, defineJob } from '@coji/durably' -import { createClient } from '@libsql/client' import { LibsqlDialect } from '@libsql/kysely-libsql' +import { createClient } from '@libsql/client' import { z } from 'zod' -// Create SQLite client +// Create Durably instance const client = createClient({ url: 'file:local.db' }) const dialect = new LibsqlDialect({ client }) - -// Initialize Durably const durably = createDurably({ dialect }) // Define a job -const processOrderJob = defineJob({ - name: 'process-order', - input: z.object({ orderId: z.string() }), - output: z.object({ status: z.string() }), +const syncUsersJob = defineJob({ + name: 'sync-users', + input: z.object({ orgId: z.string() }), + output: z.object({ count: z.number() }), run: async (step, payload) => { - // Step 1: Validate order - const order = await step.run('validate', async () => { - return await validateOrder(payload.orderId) - }) - - // Step 2: Process payment - await step.run('payment', async () => { - await processPayment(order) + // Step 1: Fetch users + const users = await step.run('fetch', async () => { + const res = await fetch(`https://api.example.com/orgs/${payload.orgId}/users`) + return res.json() }) - // Step 3: Send confirmation - await step.run('notify', async () => { - await sendConfirmation(order) + // Step 2: Save to database + await step.run('save', async () => { + // Your database logic here + console.log(`Saving ${users.length} users`) }) - return { status: 'completed' } + return { count: users.length } }, }) // Register the job -const processOrder = durably.register(processOrderJob) +const syncUsers = durably.register(syncUsersJob) -// Start the worker and run migrations +// Initialize and start await durably.migrate() durably.start() // Trigger a job -await processOrder.trigger({ orderId: 'order_123' }) +await syncUsers.trigger({ orgId: 'org_123' }) ``` -### Browser Example - -```ts -import { createDurably, defineJob } from '@coji/durably' -import { SQLocalKysely } from 'sqlocal/kysely' -import { z } from 'zod' - -// Create SQLite client with OPFS -const { dialect } = new SQLocalKysely('app.sqlite3') +### 3. Run -// Initialize Durably -const durably = createDurably({ - dialect, - pollingInterval: 100, - heartbeatInterval: 500, - staleThreshold: 3000, -}) - -// Define and register jobs the same way as Node.js -const syncData = durably.register( - defineJob({ - name: 'sync-data', - input: z.object({ userId: z.string() }), - run: async (step, payload) => { - const data = await step.run('fetch', async () => { - return await fetchUserData(payload.userId) - }) - - await step.run('save', async () => { - await saveLocally(data) - }) - }, - }), -) - -await durably.migrate() -durably.start() +```bash +npx tsx jobs.ts ``` +If the process crashes after step 1, restarting will skip the fetch and continue from step 2. + ## Next Steps -- [Jobs and Steps](/guide/jobs-and-steps) - Learn about defining jobs and steps -- [Resumability](/guide/resumability) - Understand how resumption works -- [Events](/guide/events) - Monitor job execution with events +Learn the concepts: +- [Jobs and Steps](/guide/jobs-and-steps) - How jobs and steps work +- [Resumability](/guide/resumability) - How resumption works +- [Events](/guide/events) - Monitor job execution + +Choose your setup: +- [Server](/guide/server) - Detailed server-side guide +- [Full-Stack](/guide/full-stack) - React Router v7 + React hooks +- [Browser-Only](/guide/browser-only) - Browser-only with SQLite WASM diff --git a/website/guide/index.md b/website/guide/index.md index 8cfea182..e325e62d 100644 --- a/website/guide/index.md +++ b/website/guide/index.md @@ -1,75 +1,78 @@ # What is Durably? -Durably is a step-oriented batch execution framework that enables **resumable workflows** in both Node.js and browsers. +Durably is a **resumable job execution** library for Node.js and browsers. Split long-running tasks into steps, and if interrupted, resume from the last successful step. -## The Problem +## Use Cases -When running batch jobs or workflows, failures can happen at any point: -- Network errors during API calls -- Process crashes -- Browser tab closures -- Server restarts +### Long-Running Jobs with Progress UI -Traditional approaches require you to either: -- Re-run the entire job from the beginning -- Implement complex checkpointing logic manually +Execute jobs on the server and show real-time progress in your React app via SSE. -## The Solution +```tsx +const { trigger, progress, isRunning } = useJob({ + api: '/api/durably', + jobName: 'sync-data', +}) + +// Progress: 50/100 +``` -Durably automatically persists the result of each step to SQLite. If a job is interrupted, it resumes from the last successful step. Durably uses [Kysely](https://kysely.dev) for database access—you provide a dialect for your SQLite implementation. +[Full-Stack Guide →](/guide/full-stack) -```ts -import { createDurably, defineJob } from '@coji/durably' -import { LibsqlDialect } from '@libsql/kysely-libsql' // or your SQLite dialect -import { z } from 'zod' +### Data Sync & Batch Processing -// Create durably instance with SQLite dialect -const dialect = new LibsqlDialect({ url: 'file:app.db' }) -const durably = createDurably({ dialect }) +Fetch data from APIs, transform, and save. If the process fails midway, it resumes from where it left off. -// Define job (static, can be in a separate file) -const syncUsersJob = defineJob({ +```ts +const syncJob = defineJob({ name: 'sync-users', - input: z.object({ orgId: z.string() }), run: async (step, payload) => { - // Step 1: Fetch users (persisted after completion) - const users = await step.run('fetch-users', async () => { - return api.fetchUsers(payload.orgId) - }) - - // Step 2: Save to database (skipped if already done) - await step.run('save-to-db', async () => { - await db.upsertUsers(users) - }) + // Step 1: Fetch (persisted after completion) + const users = await step.run('fetch', () => api.getUsers()) - return { syncedCount: users.length } + // Step 2: Save (skipped if already done) + await step.run('save', () => db.saveUsers(users)) }, }) +``` + +[Server Guide →](/guide/server) -// Register and trigger -const syncUsers = durably.register(syncUsersJob) -await syncUsers.trigger({ orgId: 'org_123' }) +### Offline-Capable Apps + +Run Durably entirely in the browser with SQLite WASM. Works offline, survives tab closes. + +```tsx + new SQLocalKysely('app.db').dialect}> + + ``` -## Key Features +[Browser-Only Guide →](/guide/browser-only) -- **Step-level persistence**: Each `step.run()` call creates a checkpoint -- **Automatic resumption**: Interrupted jobs resume from the last successful step -- **Cross-platform**: Same code runs in Node.js and browsers -- **Minimal dependencies**: Just Kysely and Zod -- **Type-safe**: Full TypeScript support with schema validation +## How It Works -## When to Use Durably +Each `step.run()` persists its result to SQLite. On resume, completed steps return their cached results instantly. + +```ts +// First run: executes all steps +// Second run (after crash): step 1 returns cached result, step 2 executes + +const result = await step.run('expensive-api-call', async () => { + return await fetch('/api/data').then((r) => r.json()) +}) +``` -Durably is ideal for: +## Features -- **Data synchronization jobs** - Fetching and processing data from external APIs -- **Batch processing** - Processing large datasets in steps -- **Browser workflows** - Long-running operations that survive page reloads -- **Offline-first applications** - Operations that need to resume after connectivity is restored +- **Step-level persistence** - Each step is a checkpoint +- **Automatic resumption** - Resume from last successful step +- **Cross-platform** - Node.js and browsers +- **TypeScript** - Full type safety with Zod schemas +- **Minimal dependencies** - Just Kysely and Zod ## Next Steps -- [Getting Started](/guide/getting-started) - Install and create your first job -- [Jobs and Steps](/guide/jobs-and-steps) - Learn about the core concepts +- [Getting Started](/guide/getting-started) - Install and run your first job +- [Jobs and Steps](/guide/jobs-and-steps) - Core concepts - [Live Demo](https://durably-demo.vercel.app) - Try it in your browser From 1c6c86360ada315f79b0f758544c312d27a57025 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 21:10:19 +0900 Subject: [PATCH 028/101] docs: update biome configuration and add biomejs dependency --- biome.json | 57 +++++++++++++++++++++++++------------------------- package.json | 1 + pnpm-lock.yaml | 3 +++ 3 files changed, 33 insertions(+), 28 deletions(-) diff --git a/biome.json b/biome.json index 0761b8ba..0095410c 100644 --- a/biome.json +++ b/biome.json @@ -1,30 +1,31 @@ { - "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", - "files": { - "includes": ["**"] - }, - "assist": { "actions": { "source": { "organizeImports": "off" } } }, - "vcs": { - "enabled": true, - "clientKind": "git", - "useIgnoreFile": true - }, - "linter": { - "enabled": true, - "rules": { - "recommended": true - } - }, - "overrides": [ - { - "includes": ["**/tests/**"], - "linter": { - "rules": { - "style": { - "noNonNullAssertion": "off" - } - } - } - } - ] + "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", + "root": true, + "files": { + "includes": ["**"] + }, + "assist": { "actions": { "source": { "organizeImports": "off" } } }, + "vcs": { + "enabled": true, + "clientKind": "git", + "useIgnoreFile": true + }, + "linter": { + "enabled": true, + "rules": { + "recommended": true + } + }, + "overrides": [ + { + "includes": ["**/tests/**"], + "linter": { + "rules": { + "style": { + "noNonNullAssertion": "off" + } + } + } + } + ] } diff --git a/package.json b/package.json index 06d282d9..5d4df473 100644 --- a/package.json +++ b/package.json @@ -21,6 +21,7 @@ "validate": "pnpm format && pnpm lint && pnpm typecheck && pnpm test" }, "devDependencies": { + "@biomejs/biome": "^2.3.10", "@types/node": "^25.0.3", "cc-hooks-ts": "2.0.70", "tsx": "^4.21.0", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 5890eaca..a89b7545 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -8,6 +8,9 @@ importers: .: devDependencies: + '@biomejs/biome': + specifier: ^2.3.10 + version: 2.3.10 '@types/node': specifier: ^25.0.3 version: 25.0.3 From 4d6e4660294419ec100d549661807430bd713e6f Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 21:28:09 +0900 Subject: [PATCH 029/101] refactor: rename registerAll to register and update docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Rename `registerAll` to `register` as the primary job registration API - Remove single-job `register(jobDef)` signature - New API: `const { job } = durably.register({ job: jobDef })` - Update all documentation (guides, API reference, specs, LLM docs) - Update all test files to use new API pattern - Rebuild @coji/durably package to update type definitions 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 20 +- docs/implementation-plan-react.md | 6 +- docs/spec-react.md | 2 +- docs/spec-streaming.md | 4 +- docs/spec.md | 8 +- packages/durably-react/README.md | 2 +- packages/durably-react/docs/llms.md | 2 +- .../src/client/create-durably-client.ts | 132 +++++++++++ .../src/client/create-job-hooks.ts | 109 +++++++++ packages/durably-react/src/client/index.ts | 10 + packages/durably-react/src/hooks/use-job.ts | 6 +- .../tests/browser/use-job-logs.test.tsx | 6 +- .../tests/browser/use-job-run.test.tsx | 10 +- packages/durably/docs/llms.md | 12 +- packages/durably/src/define-job.ts | 20 ++ packages/durably/src/durably.ts | 62 +++++- packages/durably/src/index.ts | 2 +- .../tests/node/core-extensions.test.ts | 18 +- .../durably/tests/react/strict-mode.test.tsx | 12 +- .../tests/shared/concurrency.shared.ts | 8 +- packages/durably/tests/shared/job.shared.ts | 57 +++-- packages/durably/tests/shared/log.shared.ts | 12 +- .../durably/tests/shared/plugin.shared.ts | 24 +- .../durably/tests/shared/recovery.shared.ts | 120 +++++----- .../durably/tests/shared/run-api.shared.ts | 120 +++++----- packages/durably/tests/shared/step.shared.ts | 18 +- .../durably/tests/shared/worker.shared.ts | 14 +- website/api/define-job.md | 24 +- website/api/durably-react.md | 2 +- website/api/index.md | 6 +- website/api/step.md | 4 +- website/guide/full-stack.md | 206 +++++++++++------- website/guide/getting-started.md | 33 +-- website/guide/index.md | 20 +- website/guide/jobs-and-steps.md | 4 +- 35 files changed, 768 insertions(+), 347 deletions(-) create mode 100644 packages/durably-react/src/client/create-durably-client.ts create mode 100644 packages/durably-react/src/client/create-job-hooks.ts diff --git a/CHANGELOG.md b/CHANGELOG.md index 97fc4fa0..987c5741 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,8 +37,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - **New API pattern**: `defineJob()` + `durably.register()` replaces `durably.defineJob()` - `defineJob()` is now a standalone function that creates a `JobDefinition` - - `durably.register(jobDef)` registers the definition and returns a `JobHandle` + - `durably.register({ name: jobDef })` registers jobs and returns an object of `JobHandle`s - This enables idempotent registration (safe for React StrictMode) + - Supports registering multiple jobs in a single call ### Migration @@ -52,15 +53,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - }, async (step, payload) => { - // ... - }) -+ const myJob = durably.register( -+ defineJob({ -+ name: 'my-job', -+ input: z.object({ id: z.string() }), -+ run: async (step, payload) => { -+ // ... -+ }, -+ }) -+ ) ++ const myJobDef = defineJob({ ++ name: 'my-job', ++ input: z.object({ id: z.string() }), ++ run: async (step, payload) => { ++ // ... ++ }, ++ }) ++ const { myJob } = durably.register({ myJob: myJobDef }) ``` ### Removed diff --git a/docs/implementation-plan-react.md b/docs/implementation-plan-react.md index 6c28d8a8..92a312cb 100644 --- a/docs/implementation-plan-react.md +++ b/docs/implementation-plan-react.md @@ -73,7 +73,7 @@ packages/durably-react/ ### 既存（実装済み） - `durably.on()` が unsubscribe 関数を返す ✅ -- `durably.register(jobDef)` で JobHandle を取得 ✅ +- `durably.register({ name: jobDef })` で JobHandle のオブジェクトを取得 ✅ - `run:progress` イベント ✅ ### 新規（サーバー連携用） @@ -628,7 +628,7 @@ describe('useJobLogs', () => { describe('getJob', () => { it('returns registered job by name', () => { const durably = createDurably({ dialect }) - durably.register(testJob) + durably.register({ testJob }) const job = durably.getJob('test-job') @@ -657,7 +657,7 @@ describe('getJob', () => { describe('subscribe', () => { it('returns ReadableStream of events', async () => { const durably = createDurably({ dialect }) - durably.register(testJob) + durably.register({ testJob }) await durably.migrate() durably.start() diff --git a/docs/spec-react.md b/docs/spec-react.md index 2a72644d..5a4e7b26 100644 --- a/docs/spec-react.md +++ b/docs/spec-react.md @@ -608,7 +608,7 @@ function TaskPage() { ### 既存（実装済み） - `durably.on()` が unsubscribe 関数を返す -- `durably.register(jobDef)` で JobHandle を取得 +- `durably.register({ name: jobDef })` で JobHandle のオブジェクトを取得 ### 新規（サーバー連携用） diff --git a/docs/spec-streaming.md b/docs/spec-streaming.md index d8a4e21f..4ef1be31 100644 --- a/docs/spec-streaming.md +++ b/docs/spec-streaming.md @@ -499,7 +499,9 @@ import { createDurably } from '@coji/durably' import { codingAssistant } from './jobs' const durably = createDurably({ dialect }) -const codingAssistantJob = durably.register(codingAssistant) +const { codingAssistant: codingAssistantJob } = durably.register({ + codingAssistant, +}) const run = await codingAssistantJob.trigger({ task: 'Add user authentication', diff --git a/docs/spec.md b/docs/spec.md index a415a1c3..bd385041 100644 --- a/docs/spec.md +++ b/docs/spec.md @@ -112,7 +112,9 @@ await durably.migrate() durably.start() // ジョブを登録して JobHandle を取得 -const syncUsersJob = durably.register(syncUsers) +const { syncUsers: syncUsersJob } = durably.register({ + syncUsers, +}) // trigger で実行 await syncUsersJob.trigger({ orgId: "org_123" }) @@ -367,7 +369,7 @@ const durably = createDurably({ dialect }) await durably.migrate() // ジョブを登録 -durably.register(syncUsers) +durably.register({ syncUsers }) // ワーカーを起動 durably.start() @@ -891,7 +893,7 @@ await durably.migrate() durably.start() // ジョブを登録してトリガー -const syncUsersJob = durably.register(syncUsers) +const { syncUsers: syncUsersJob } = durably.register({ syncUsers }) await syncUsersJob.trigger({ orgId: 'org_123' }) ``` diff --git a/packages/durably-react/README.md b/packages/durably-react/README.md index 52e5fce3..f6a05b54 100644 --- a/packages/durably-react/README.md +++ b/packages/durably-react/README.md @@ -166,7 +166,7 @@ const durably = createDurably({ dialect }) const handler = createDurablyHandler(durably) // Register jobs -durably.register(syncJob) +durably.register({ syncJob }) // Route handlers app.post('/api/durably/trigger', (req) => handler.trigger(req)) diff --git a/packages/durably-react/docs/llms.md b/packages/durably-react/docs/llms.md index a2941da4..7edb63be 100644 --- a/packages/durably-react/docs/llms.md +++ b/packages/durably-react/docs/llms.md @@ -357,7 +357,7 @@ const syncJob = defineJob({ // Job logic }, }) -durably.register(syncJob) +durably.register({ syncJob }) await durably.migrate() durably.start() diff --git a/packages/durably-react/src/client/create-durably-client.ts b/packages/durably-react/src/client/create-durably-client.ts new file mode 100644 index 00000000..df2b6665 --- /dev/null +++ b/packages/durably-react/src/client/create-durably-client.ts @@ -0,0 +1,132 @@ +import type { JobDefinition } from '@coji/durably' +import { useJob, type UseJobClientResult } from './use-job' +import { useJobLogs, type UseJobLogsClientResult } from './use-job-logs' +import { useJobRun, type UseJobRunClientResult } from './use-job-run' + +/** + * Extract input type from a JobDefinition or JobHandle + */ +type InferInput = + T extends JobDefinition + ? TInput extends Record + ? TInput + : Record + : T extends { trigger: (input: infer TInput) => unknown } + ? TInput extends Record + ? TInput + : Record + : Record + +/** + * Extract output type from a JobDefinition or JobHandle + */ +type InferOutput = + T extends JobDefinition + ? TOutput extends Record + ? TOutput + : Record + : T extends { + trigger: (input: unknown) => Promise<{ output?: infer TOutput }> + } + ? TOutput extends Record + ? TOutput + : Record + : Record + +/** + * Type-safe hooks for a specific job + */ +export interface JobClient { + /** + * Hook for triggering and monitoring the job + */ + useJob: () => UseJobClientResult + + /** + * Hook for subscribing to an existing run by ID + */ + useRun: (runId: string | null) => UseJobRunClientResult + + /** + * Hook for subscribing to logs from a run + */ + useLogs: ( + runId: string | null, + options?: { maxLogs?: number }, + ) => UseJobLogsClientResult +} + +/** + * Options for createDurablyClient + */ +export interface CreateDurablyClientOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string +} + +/** + * A type-safe client with hooks for each registered job + */ +export type DurablyClient> = { + [K in keyof TJobs]: JobClient, InferOutput> +} + +/** + * Create a type-safe Durably client with hooks for all registered jobs. + * + * @example + * ```tsx + * // Server: register jobs + * // app/lib/durably.server.ts + * export const jobs = durably.register({ + * importCsv: importCsvJob, + * syncUsers: syncUsersJob, + * }) + * + * // Client: create typed client + * // app/lib/durably.client.ts + * import type { jobs } from '~/lib/durably.server' + * import { createDurablyClient } from '@coji/durably-react/client' + * + * export const durably = createDurablyClient({ + * api: '/api/durably', + * }) + * + * // In your component - fully type-safe with autocomplete + * function CsvImporter() { + * const { trigger, output, isRunning } = durably.importCsv.useJob() + * + * return ( + * + * ) + * } + * ``` + */ +export function createDurablyClient>( + options: CreateDurablyClientOptions, +): DurablyClient { + const { api } = options + + // Create a proxy that generates job clients on demand + return new Proxy({} as DurablyClient, { + get(_target, jobKey: string) { + return { + useJob: () => { + return useJob({ api, jobName: jobKey }) + }, + + useRun: (runId: string | null) => { + return useJobRun({ api, runId }) + }, + + useLogs: (runId: string | null, logsOptions?: { maxLogs?: number }) => { + return useJobLogs({ api, runId, maxLogs: logsOptions?.maxLogs }) + }, + } + }, + }) +} diff --git a/packages/durably-react/src/client/create-job-hooks.ts b/packages/durably-react/src/client/create-job-hooks.ts new file mode 100644 index 00000000..b5a95be1 --- /dev/null +++ b/packages/durably-react/src/client/create-job-hooks.ts @@ -0,0 +1,109 @@ +import type { JobDefinition } from '@coji/durably' +import { useJob, type UseJobClientResult } from './use-job' +import { useJobLogs, type UseJobLogsClientResult } from './use-job-logs' +import { useJobRun, type UseJobRunClientResult } from './use-job-run' + +/** + * Extract input type from a JobDefinition + */ +type InferInput = + T extends JobDefinition + ? TInput extends Record + ? TInput + : Record + : Record + +/** + * Extract output type from a JobDefinition + */ +type InferOutput = + T extends JobDefinition + ? TOutput extends Record + ? TOutput + : Record + : Record + +/** + * Options for createJobHooks + */ +export interface CreateJobHooksOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string + /** + * Job name (must match the server-side job name) + */ + jobName: string +} + +/** + * Type-safe hooks for a specific job + */ +export interface JobHooks { + /** + * Hook for triggering and monitoring the job + */ + useJob: () => UseJobClientResult + + /** + * Hook for subscribing to an existing run by ID + */ + useRun: (runId: string | null) => UseJobRunClientResult + + /** + * Hook for subscribing to logs from a run + */ + useLogs: ( + runId: string | null, + options?: { maxLogs?: number }, + ) => UseJobLogsClientResult +} + +/** + * Create type-safe hooks for a specific job. + * + * @example + * ```tsx + * // Import job type from server (type-only import is safe) + * import type { importCsvJob } from '~/lib/durably.server' + * import { createJobHooks } from '@coji/durably-react/client' + * + * const importCsv = createJobHooks({ + * api: '/api/durably', + * jobName: 'import-csv', + * }) + * + * // In your component - fully type-safe + * function CsvImporter() { + * const { trigger, output, progress, isRunning } = importCsv.useJob() + * + * return ( + * + * ) + * } + * ``` + */ +export function createJobHooks< + TJob extends JobDefinition, +>( + options: CreateJobHooksOptions, +): JobHooks, InferOutput> { + const { api, jobName } = options + + return { + useJob: () => { + return useJob, InferOutput>({ api, jobName }) + }, + + useRun: (runId: string | null) => { + return useJobRun>({ api, runId }) + }, + + useLogs: (runId: string | null, logsOptions?: { maxLogs?: number }) => { + return useJobLogs({ api, runId, maxLogs: logsOptions?.maxLogs }) + }, + } +} diff --git a/packages/durably-react/src/client/index.ts b/packages/durably-react/src/client/index.ts index afa9e6cc..aaa49bd2 100644 --- a/packages/durably-react/src/client/index.ts +++ b/packages/durably-react/src/client/index.ts @@ -3,6 +3,16 @@ * Use these when connecting to a remote Durably server via HTTP/SSE */ +export { createDurablyClient } from './create-durably-client' +export type { + CreateDurablyClientOptions, + DurablyClient, + JobClient, +} from './create-durably-client' + +export { createJobHooks } from './create-job-hooks' +export type { CreateJobHooksOptions, JobHooks } from './create-job-hooks' + export { useJob } from './use-job' export type { UseJobClientOptions, UseJobClientResult } from './use-job' diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts index 53acad77..8e0f207f 100644 --- a/packages/durably-react/src/hooks/use-job.ts +++ b/packages/durably-react/src/hooks/use-job.ts @@ -98,8 +98,10 @@ export function useJob< useEffect(() => { if (!durably || !isDurablyReady) return - // Register the job - const jobHandle = durably.register(jobDefinition) + // Register the job (use fixed key for simpler type handling) + const { _job: jobHandle } = durably.register({ + _job: jobDefinition, + }) jobHandleRef.current = jobHandle // Subscribe to each event type separately diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx index a27049c3..2ccb469a 100644 --- a/packages/durably-react/tests/browser/use-job-logs.test.tsx +++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx @@ -106,7 +106,7 @@ describe('useJobLogs', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(loggingJob) + const { _job: handle } = result.current.durably!.register({ _job: loggingJob }) const run = await handle.trigger({ count: 3 }) result.current.setRunId(run.id) @@ -156,7 +156,7 @@ describe('useJobLogs', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(loggingJob) + const { _job: handle } = result.current.durably!.register({ _job: loggingJob }) const run = await handle.trigger({ count: 10 }) result.current.setRunId(run.id) @@ -188,7 +188,7 @@ describe('useJobLogs', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(loggingJob) + const { _job: handle } = result.current.durably!.register({ _job: loggingJob }) const run = await handle.trigger({ count: 3 }) result.current.setRunId(run.id) diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx index 9fc2c4c2..33a2d2e8 100644 --- a/packages/durably-react/tests/browser/use-job-run.test.tsx +++ b/packages/durably-react/tests/browser/use-job-run.test.tsx @@ -131,7 +131,7 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) // Trigger job and set runId - const handle = result.current.durably!.register(testJob) + const { _job: handle } = result.current.durably!.register({ _job: testJob }) const run = await handle.trigger({ input: 'test' }) // Update runId to start subscription @@ -180,7 +180,7 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(testJob) + const { _job: handle } = result.current.durably!.register({ _job: testJob }) const run = await handle.trigger({ input: 'hello' }) result.current.setRunId(run.id) @@ -214,7 +214,7 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(failingJob) + const { _job: handle } = result.current.durably!.register({ _job: failingJob }) const run = await handle.trigger({ input: 'test' }) result.current.setRunId(run.id) @@ -248,7 +248,7 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(progressJob) + const { _job: handle } = result.current.durably!.register({ _job: progressJob }) const run = await handle.trigger({ input: 'test' }) result.current.setRunId(run.id) @@ -285,7 +285,7 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const handle = result.current.durably!.register(testJob) + const { _job: handle } = result.current.durably!.register({ _job: testJob }) const run = await handle.trigger({ input: 'test' }) result.current.setRunId(run.id) diff --git a/packages/durably/docs/llms.md b/packages/durably/docs/llms.md index 0b483e6a..fa6684e0 100644 --- a/packages/durably/docs/llms.md +++ b/packages/durably/docs/llms.md @@ -61,8 +61,10 @@ const syncUsersJob = defineJob({ }, }) -// Register the job with durably instance -const syncUsers = durably.register(syncUsersJob) +// Register jobs with durably instance +const { syncUsers } = durably.register({ + syncUsers: syncUsersJob, +}) ``` ### 3. Starting the Worker @@ -316,15 +318,15 @@ const durably = createDurably({ }) // Same API as Node.js -const myJob = durably.register( - defineJob({ +const { myJob } = durably.register({ + myJob: defineJob({ name: 'my-job', input: z.object({}), run: async (step) => { /* ... */ }, }), -) +}) await durably.migrate() durably.start() diff --git a/packages/durably/src/define-job.ts b/packages/durably/src/define-job.ts index e6f4a6bb..2aea0103 100644 --- a/packages/durably/src/define-job.ts +++ b/packages/durably/src/define-job.ts @@ -20,6 +20,26 @@ export interface JobDefinition { readonly run: JobRunFunction } +/** + * Extract input type from a JobDefinition + * @example + * ```ts + * type Input = JobInput // { userId: string } + * ``` + */ +export type JobInput = + T extends JobDefinition ? TInput : never + +/** + * Extract output type from a JobDefinition + * @example + * ```ts + * type Output = JobOutput // { count: number } + * ``` + */ +export type JobOutput = + T extends JobDefinition ? TOutput : never + /** * Configuration for defining a job */ diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts index 0ac9de78..51ef3923 100644 --- a/packages/durably/src/durably.ts +++ b/packages/durably/src/durably.ts @@ -86,13 +86,30 @@ export interface Durably { onError(handler: ErrorHandler): void /** - * Register a job definition and return a job handle + * Register job definitions and return a registry of job handles * Same JobDefinition can be registered multiple times (idempotent) * Different JobDefinitions with the same name will throw an error + * @example + * ```ts + * const jobs = durably.register({ + * importCsv: importCsvJob, + * syncUsers: syncUsersJob, + * }) + * // Usage: jobs.importCsv.trigger({ rows: [...] }) + * ``` */ - register( - jobDef: JobDefinition, - ): JobHandle + // biome-ignore lint/suspicious/noExplicitAny: flexible type constraint for job definitions + register>>( + jobDefs: TJobs, + ): { + [K in keyof TJobs]: TJobs[K] extends JobDefinition< + infer TName, + infer TInput, + infer TOutput + > + ? JobHandle + : never + } /** * Start the worker polling loop @@ -181,10 +198,39 @@ export function createDurably(options: DurablyOptions): Durably { start: worker.start, stop: worker.stop, - register( - jobDef: JobDefinition, - ): JobHandle { - return createJobHandle(jobDef, storage, eventEmitter, jobRegistry) + // biome-ignore lint/suspicious/noExplicitAny: flexible type constraint for job definitions + register>>( + jobDefs: TJobs, + ): { + [K in keyof TJobs]: TJobs[K] extends JobDefinition< + infer TName, + infer TInput, + infer TOutput + > + ? JobHandle + : never + } { + const result = {} as { + [K in keyof TJobs]: TJobs[K] extends JobDefinition< + infer TName, + infer TInput, + infer TOutput + > + ? JobHandle + : never + } + + for (const key of Object.keys(jobDefs) as (keyof TJobs)[]) { + const jobDef = jobDefs[key] + result[key] = createJobHandle( + jobDef, + storage, + eventEmitter, + jobRegistry, + ) as (typeof result)[typeof key] + } + + return result }, getRun: storage.getRun, diff --git a/packages/durably/src/index.ts b/packages/durably/src/index.ts index eef11b3b..5b951e3f 100644 --- a/packages/durably/src/index.ts +++ b/packages/durably/src/index.ts @@ -8,7 +8,7 @@ export type { Durably, DurablyOptions, DurablyPlugin } from './durably' // Job Definition export { defineJob } from './define-job' -export type { JobDefinition } from './define-job' +export type { JobDefinition, JobInput, JobOutput } from './define-job' // Plugins export { withLogPersistence } from './plugins/log-persistence' diff --git a/packages/durably/tests/node/core-extensions.test.ts b/packages/durably/tests/node/core-extensions.test.ts index 16f1093e..92d099d6 100644 --- a/packages/durably/tests/node/core-extensions.test.ts +++ b/packages/durably/tests/node/core-extensions.test.ts @@ -29,7 +29,7 @@ describe('Core Extensions', () => { }) describe('getJob', () => { - const testJob = defineJob({ + const testJobDef = defineJob({ name: 'test-job-getjob', input: z.object({ value: z.number() }), output: z.object({ result: z.number() }), @@ -37,7 +37,7 @@ describe('Core Extensions', () => { }) it('returns registered job by name', () => { - durably.register(testJob) + durably.register({ testJob: testJobDef }) const job = durably.getJob('test-job-getjob') @@ -50,7 +50,7 @@ describe('Core Extensions', () => { }) it('can trigger job via getJob handle', async () => { - durably.register(testJob) + durably.register({ testJob: testJobDef }) const job = durably.getJob('test-job-getjob') const run = await job!.trigger({ value: 5 }) @@ -61,7 +61,7 @@ describe('Core Extensions', () => { }) describe('subscribe', () => { - const testJob = defineJob({ + const testJobDef = defineJob({ name: 'test-job-subscribe', input: z.object({ input: z.string() }), output: z.object({ result: z.string() }), @@ -72,7 +72,7 @@ describe('Core Extensions', () => { }) it('returns ReadableStream of events', async () => { - durably.register(testJob) + durably.register({ testJob: testJobDef }) durably.start() const job = durably.getJob('test-job-subscribe')! @@ -92,7 +92,7 @@ describe('Core Extensions', () => { }) it('emits run:start event', async () => { - durably.register(testJob) + durably.register({ testJob: testJobDef }) durably.start() const job = durably.getJob('test-job-subscribe')! @@ -112,7 +112,7 @@ describe('Core Extensions', () => { }) it('emits step events', async () => { - durably.register(testJob) + durably.register({ testJob: testJobDef }) durably.start() const job = durably.getJob('test-job-subscribe')! @@ -134,7 +134,7 @@ describe('Core Extensions', () => { }) describe('createDurablyHandler', () => { - const testJob = defineJob({ + const testJobDef = defineJob({ name: 'test-job-handler', input: z.object({ value: z.number() }), output: z.object({ result: z.number() }), @@ -142,7 +142,7 @@ describe('Core Extensions', () => { }) beforeEach(() => { - durably.register(testJob) + durably.register({ testJob: testJobDef }) }) it('trigger returns runId', async () => { diff --git a/packages/durably/tests/react/strict-mode.test.tsx b/packages/durably/tests/react/strict-mode.test.tsx index f3da5240..0dbfc6cd 100644 --- a/packages/durably/tests/react/strict-mode.test.tsx +++ b/packages/durably/tests/react/strict-mode.test.tsx @@ -204,8 +204,8 @@ describe('React StrictMode', () => { await instance.migrate() if (cleanedUp.current) return - const job = instance.register( - defineJob({ + const { job } = instance.register({ + job: defineJob({ name: 'strict-mode-test', input: z.object({ value: z.string() }), output: z.object({ processed: z.string() }), @@ -214,7 +214,7 @@ describe('React StrictMode', () => { return { processed: payload.value.toUpperCase() } }, }), - ) + }) const run = await job.trigger({ value: 'hello' }) if (cleanedUp.current) return @@ -289,13 +289,13 @@ describe('React StrictMode', () => { instance.migrate().then(() => { if (cleanedUp.current) return - const job = instance.register( - defineJob({ + const { job } = instance.register({ + job: defineJob({ name: 'event-test', input: z.object({}), run: async () => {}, }), - ) + }) job.trigger({}).then(() => { if (!cleanedUp.current) { instance.start() diff --git a/packages/durably/tests/shared/concurrency.shared.ts b/packages/durably/tests/shared/concurrency.shared.ts index e618c113..63753de2 100644 --- a/packages/durably/tests/shared/concurrency.shared.ts +++ b/packages/durably/tests/shared/concurrency.shared.ts @@ -34,7 +34,7 @@ export function createConcurrencyTests(createDialect: () => Dialect) { executionOrder.push(`end-${payload.id}`) }, }) - const job = durably.register(concurrencyTestDef) + const { job } = durably.register({ job: concurrencyTestDef }) // Trigger two runs with the same concurrency key await job.trigger({ id: '1' }, { concurrencyKey: 'user-123' }) @@ -68,7 +68,7 @@ export function createConcurrencyTests(createDialect: () => Dialect) { }) }, }) - const job = durably.register(differentKeysTestDef) + const { job } = durably.register({ job: differentKeysTestDef }) // Trigger two runs with different concurrency keys await job.trigger({ id: 'a' }, { concurrencyKey: 'user-A' }) @@ -103,7 +103,7 @@ export function createConcurrencyTests(createDialect: () => Dialect) { }) }, }) - const job = durably.register(noKeyTestDef) + const { job } = durably.register({ job: noKeyTestDef }) // Mix of runs with and without concurrency keys await job.trigger({ id: '1' }) // no key @@ -140,7 +140,7 @@ export function createConcurrencyTests(createDialect: () => Dialect) { concurrentRuns-- }, }) - const job = durably.register(nullKeyTestDef) + const { job } = durably.register({ job: nullKeyTestDef }) // Multiple runs with no concurrency key await job.trigger({ id: 1 }) diff --git a/packages/durably/tests/shared/job.shared.ts b/packages/durably/tests/shared/job.shared.ts index 53304d97..d187cb9f 100644 --- a/packages/durably/tests/shared/job.shared.ts +++ b/packages/durably/tests/shared/job.shared.ts @@ -25,7 +25,7 @@ export function createJobTests(createDialect: () => Dialect) { return { result: 42 } }, }) - const job = durably.register(testJobDef) + const { testJob: job } = durably.register({ testJob: testJobDef }) expect(job).toBeDefined() expect(job.name).toBe('test-job') @@ -42,8 +42,8 @@ export function createJobTests(createDialect: () => Dialect) { run: async () => ({}), }) - const handle1 = durably.register(jobDef) - const handle2 = durably.register(jobDef) + const { job: handle1 } = durably.register({ job: jobDef }) + const { job: handle2 } = durably.register({ job: jobDef }) expect(handle1).toBe(handle2) }) @@ -63,13 +63,44 @@ export function createJobTests(createDialect: () => Dialect) { run: async () => ({}), }) - durably.register(jobDef1) + durably.register({ job1: jobDef1 }) expect(() => { - durably.register(jobDef2) + durably.register({ job2: jobDef2 }) }).toThrow(/already registered|different/i) }) + it('registers multiple jobs in a single call', async () => { + const importCsvDef = defineJob({ + name: 'import-csv', + input: z.object({ rows: z.array(z.string()) }), + run: async () => {}, + }) + + const syncUsersDef = defineJob({ + name: 'sync-users', + input: z.object({ userId: z.string() }), + run: async () => {}, + }) + + const { importCsv, syncUsers } = durably.register({ + importCsv: importCsvDef, + syncUsers: syncUsersDef, + }) + + // Verify both handles are returned correctly + expect(importCsv.name).toBe('import-csv') + expect(syncUsers.name).toBe('sync-users') + + // Verify both can be triggered independently + const csvRun = await importCsv.trigger({ rows: ['a', 'b'] }) + const userRun = await syncUsers.trigger({ userId: 'user-1' }) + + expect(csvRun.id).toBeDefined() + expect(userRun.id).toBeDefined() + expect(csvRun.id).not.toBe(userRun.id) + }) + it('validates input with Zod schema on trigger', async () => { const validatedJobDef = defineJob({ name: 'validated-job', @@ -77,7 +108,7 @@ export function createJobTests(createDialect: () => Dialect) { output: z.object({}), run: async () => ({}), }) - const job = durably.register(validatedJobDef) + const { job } = durably.register({ job: validatedJobDef }) // Invalid input should throw await expect( @@ -96,7 +127,7 @@ export function createJobTests(createDialect: () => Dialect) { output: z.object({}), run: async () => ({}), }) - const job = durably.register(validInputJobDef) + const { job } = durably.register({ job: validInputJobDef }) // Valid input should work const run = await job.trigger({ count: 1 }) @@ -122,7 +153,7 @@ export function createJobTests(createDialect: () => Dialect) { return { success: true } }, }) - const job = durably.register(typedInputJobDef) + const { job } = durably.register({ job: typedInputJobDef }) const run = await job.trigger({ name: 'test', @@ -140,7 +171,7 @@ export function createJobTests(createDialect: () => Dialect) { // No return value }, }) - const job = durably.register(noOutputJobDef) + const { job } = durably.register({ job: noOutputJobDef }) const run = await job.trigger({ value: 'test' }) expect(run.status).toBe('pending') @@ -165,7 +196,7 @@ export function createJobTests(createDialect: () => Dialect) { input: z.object({ value: z.number() }), run: async () => {}, }) - const job = durably.register(batchJobDef) + const { job } = durably.register({ job: batchJobDef }) const runs = await job.batchTrigger([ { value: 1 }, @@ -189,7 +220,7 @@ export function createJobTests(createDialect: () => Dialect) { input: z.object({ value: z.number().min(1) }), run: async () => {}, }) - const job = durably.register(batchValidateJobDef) + const { job } = durably.register({ job: batchValidateJobDef }) // Second input is invalid (0 < min 1) await expect( @@ -207,7 +238,7 @@ export function createJobTests(createDialect: () => Dialect) { input: z.object({ id: z.string() }), run: async () => {}, }) - const job = durably.register(batchOptionsJobDef) + const { job } = durably.register({ job: batchOptionsJobDef }) const runs = await job.batchTrigger([ { input: { id: 'a' }, options: { idempotencyKey: 'key-a' } }, @@ -226,7 +257,7 @@ export function createJobTests(createDialect: () => Dialect) { input: z.object({}), run: async () => {}, }) - const job = durably.register(batchEmptyJobDef) + const { job } = durably.register({ job: batchEmptyJobDef }) const runs = await job.batchTrigger([]) expect(runs).toEqual([]) diff --git a/packages/durably/tests/shared/log.shared.ts b/packages/durably/tests/shared/log.shared.ts index 37d0bea2..962d317b 100644 --- a/packages/durably/tests/shared/log.shared.ts +++ b/packages/durably/tests/shared/log.shared.ts @@ -37,7 +37,7 @@ export function createLogTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }) - const job = durably.register(logInfoTestDef) + const { job } = durably.register({ job: logInfoTestDef }) await job.trigger({}) durably.start() @@ -64,7 +64,7 @@ export function createLogTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }) - const job = durably.register(logWarnTestDef) + const { job } = durably.register({ job: logWarnTestDef }) await job.trigger({}) durably.start() @@ -91,7 +91,7 @@ export function createLogTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }) - const job = durably.register(logErrorTestDef) + const { job } = durably.register({ job: logErrorTestDef }) await job.trigger({}) durably.start() @@ -118,7 +118,7 @@ export function createLogTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }) - const job = durably.register(logDataTestDef) + const { job } = durably.register({ job: logDataTestDef }) await job.trigger({}) durably.start() @@ -144,7 +144,7 @@ export function createLogTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }) - const job = durably.register(logRunIdTestDef) + const { job } = durably.register({ job: logRunIdTestDef }) const run = await job.trigger({}) durably.start() @@ -173,7 +173,7 @@ export function createLogTests(createDialect: () => Dialect) { step.log.info('After step') // stepName should be null }, }) - const job = durably.register(logStepNameTestDef) + const { job } = durably.register({ job: logStepNameTestDef }) await job.trigger({}) durably.start() diff --git a/packages/durably/tests/shared/plugin.shared.ts b/packages/durably/tests/shared/plugin.shared.ts index 2336554b..6e48f5a1 100644 --- a/packages/durably/tests/shared/plugin.shared.ts +++ b/packages/durably/tests/shared/plugin.shared.ts @@ -40,15 +40,15 @@ export function createPluginTests(createDialect: () => Dialect) { durably.use(plugin) - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'plugin-test', input: z.object({}), run: async (step) => { await step.run('step', () => {}) }, }), - ) + }) await job.trigger({}) durably.start() @@ -81,15 +81,15 @@ export function createPluginTests(createDialect: () => Dialect) { durably.use(plugin1) durably.use(plugin2) - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'multi-plugin-test', input: z.object({}), run: async (step) => { await step.run('step', () => {}) }, }), - ) + }) await job.trigger({}) durably.start() @@ -109,8 +109,8 @@ export function createPluginTests(createDialect: () => Dialect) { const { withLogPersistence } = await import('../../src') durably.use(withLogPersistence()) - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'log-persist-test', input: z.object({}), run: async (step) => { @@ -118,7 +118,7 @@ export function createPluginTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -140,8 +140,8 @@ export function createPluginTests(createDialect: () => Dialect) { }) it('logs table is empty without plugin', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'no-log-persist-test', input: z.object({}), run: async (step) => { @@ -149,7 +149,7 @@ export function createPluginTests(createDialect: () => Dialect) { await step.run('step', () => {}) }, }), - ) + }) const run = await job.trigger({}) durably.start() diff --git a/packages/durably/tests/shared/recovery.shared.ts b/packages/durably/tests/shared/recovery.shared.ts index 6700b1c8..971b372c 100644 --- a/packages/durably/tests/shared/recovery.shared.ts +++ b/packages/durably/tests/shared/recovery.shared.ts @@ -24,8 +24,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { describe('Heartbeat', () => { it('updates heartbeat_at periodically for running runs', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'heartbeat-test', input: z.object({}), run: async (step) => { @@ -35,7 +35,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) const initialHeartbeat = run.heartbeatAt @@ -73,8 +73,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { const timestamps: string[] = [] - const job = customDurably.register( - defineJob({ + const { job } = customDurably.register({ + job: defineJob({ name: 'custom-heartbeat-test', input: z.object({}), run: async (step) => { @@ -88,7 +88,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) customDurably.start() @@ -111,13 +111,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { describe('Stale Run Recovery', () => { it('recovers stale running runs to pending', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'stale-recovery-test', input: z.object({}), run: async () => {}, }), - ) + }) // Create a run and manually set it to running with old heartbeat const run = await job.trigger({}) @@ -145,8 +145,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { let step1Calls = 0 let step2Calls = 0 - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'resume-skip-test', input: z.object({}), run: async (step) => { @@ -160,7 +160,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) // Create run and simulate partial execution const run = await job.trigger({}) @@ -199,8 +199,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { describe('retry() API', () => { it('resets failed run to pending', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'retry-test', input: z.object({ shouldFail: z.boolean() }), run: async (_step, payload) => { @@ -209,7 +209,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { } }, }), - ) + }) const run = await job.trigger({ shouldFail: true }) durably.start() @@ -231,13 +231,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when retrying completed run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'retry-completed-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -256,13 +256,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when retrying pending run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'retry-pending-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) // Don't start worker - run stays pending @@ -273,8 +273,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when retrying running run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'retry-running-test', input: z.object({}), run: async (step) => { @@ -283,7 +283,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -305,13 +305,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { describe('cancel() API', () => { it('cancels pending run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-pending-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) // Don't start worker - run stays pending @@ -323,8 +323,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('cancels running run immediately', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-running-test', input: z.object({}), run: async (step) => { @@ -334,7 +334,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -356,13 +356,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when cancelling completed run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-completed-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -381,15 +381,15 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when cancelling failed run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-failed-test', input: z.object({}), run: async () => { throw new Error('fail') }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -408,13 +408,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when cancelling already cancelled run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-cancelled-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) await durably.cancel(run.id) @@ -435,8 +435,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { let step2Executed = false let step3Executed = false - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-mid-execution-test', input: z.object({}), run: async (step) => { @@ -456,7 +456,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -488,8 +488,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('does not overwrite cancelled status with completed', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'cancel-no-overwrite-test', input: z.object({}), run: async (step) => { @@ -499,7 +499,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -527,8 +527,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { describe('deleteRun() API', () => { it('deletes completed run with its steps and logs', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'delete-completed-test', input: z.object({}), run: async (step) => { @@ -536,7 +536,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { await step.run('step1', () => 'done') }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -566,15 +566,15 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('deletes failed run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'delete-failed-test', input: z.object({}), run: async () => { throw new Error('fail') }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -594,13 +594,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('deletes cancelled run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'delete-cancelled-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) await durably.cancel(run.id) @@ -612,13 +612,13 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when deleting pending run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'delete-pending-test', input: z.object({}), run: async () => {}, }), - ) + }) const run = await job.trigger({}) // Don't start worker - run stays pending @@ -629,8 +629,8 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) it('throws when deleting running run', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'delete-running-test', input: z.object({}), run: async (step) => { @@ -639,7 +639,7 @@ export function createRecoveryTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() diff --git a/packages/durably/tests/shared/run-api.shared.ts b/packages/durably/tests/shared/run-api.shared.ts index a9287855..30da1d9b 100644 --- a/packages/durably/tests/shared/run-api.shared.ts +++ b/packages/durably/tests/shared/run-api.shared.ts @@ -22,13 +22,13 @@ export function createRunApiTests(createDialect: () => Dialect) { describe('durably.getRun()', () => { it('returns a run by ID', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'get-run-test', input: z.object({ value: z.number() }), run: async () => {}, }), - ) + }) const run = await job.trigger({ value: 42 }) const fetched = await durably.getRun(run.id) @@ -46,14 +46,14 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('returns run with unknown output type', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'unknown-output-test', input: z.object({}), output: z.object({ result: z.string() }), run: async () => ({ result: 'hello' }), }), - ) + }) const run = await job.trigger({}) durably.start() @@ -74,20 +74,20 @@ export function createRunApiTests(createDialect: () => Dialect) { describe('durably.getRuns()', () => { it('returns all runs', async () => { - const job1 = durably.register( - defineJob({ + const { job1 } = durably.register({ + job1: defineJob({ name: 'job1', input: z.object({}), run: async () => {}, }), - ) - const job2 = durably.register( - defineJob({ + }) + const { job2 } = durably.register({ + job2: defineJob({ name: 'job2', input: z.object({}), run: async () => {}, }), - ) + }) await job1.trigger({}) await job2.trigger({}) @@ -98,13 +98,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('filters by status', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'status-filter-test', input: z.object({}), run: async () => {}, }), - ) + }) await job.trigger({}) await job.trigger({}) @@ -126,20 +126,20 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('filters by jobName', async () => { - const job1 = durably.register( - defineJob({ + const { job1 } = durably.register({ + job1: defineJob({ name: 'filter-job-a', input: z.object({}), run: async () => {}, }), - ) - const job2 = durably.register( - defineJob({ + }) + const { job2 } = durably.register({ + job2: defineJob({ name: 'filter-job-b', input: z.object({}), run: async () => {}, }), - ) + }) await job1.trigger({}) await job1.trigger({}) @@ -153,13 +153,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('returns runs sorted by created_at descending', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'sort-test', input: z.object({ order: z.number() }), run: async () => {}, }), - ) + }) await job.trigger({ order: 1 }) await new Promise((r) => setTimeout(r, 10)) @@ -176,13 +176,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('supports limit option', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'limit-test', input: z.object({ order: z.number() }), run: async () => {}, }), - ) + }) // Add slight delays to ensure distinct created_at timestamps for (let i = 1; i <= 5; i++) { @@ -203,13 +203,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('supports offset option', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'offset-test', input: z.object({ order: z.number() }), run: async () => {}, }), - ) + }) // Add slight delays to ensure distinct created_at timestamps for (let i = 1; i <= 5; i++) { @@ -230,13 +230,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('supports limit and offset together for pagination', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'pagination-test', input: z.object({ order: z.number() }), run: async () => {}, }), - ) + }) // Add slight delays to ensure distinct created_at timestamps for (let i = 1; i <= 10; i++) { @@ -277,13 +277,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('combines pagination with other filters', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'combined-filter-pagination-test', input: z.object({ order: z.number() }), run: async () => {}, }), - ) + }) // Add slight delays to ensure distinct created_at timestamps for (let i = 1; i <= 6; i++) { @@ -304,13 +304,13 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('returns empty array when offset exceeds total', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'offset-exceeds-test', input: z.object({}), run: async () => {}, }), - ) + }) await job.trigger({}) await job.trigger({}) @@ -325,8 +325,8 @@ export function createRunApiTests(createDialect: () => Dialect) { describe('triggerAndWait()', () => { it('triggers and waits for successful completion', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'trigger-and-wait-success', input: z.object({ value: z.number() }), output: z.object({ result: z.number() }), @@ -337,7 +337,7 @@ export function createRunApiTests(createDialect: () => Dialect) { return { result: payload.value * 2 } }, }), - ) + }) durably.start() @@ -352,8 +352,8 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('rejects when job fails', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'trigger-and-wait-fail', input: z.object({}), output: z.object({}), @@ -364,7 +364,7 @@ export function createRunApiTests(createDialect: () => Dialect) { return {} }, }), - ) + }) durably.start() @@ -374,8 +374,8 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('works with options', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'trigger-and-wait-options', input: z.object({}), output: z.object({ done: z.boolean() }), @@ -383,7 +383,7 @@ export function createRunApiTests(createDialect: () => Dialect) { return { done: true } }, }), - ) + }) durably.start() @@ -399,8 +399,8 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('times out if job does not complete within timeout', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'trigger-and-wait-timeout', input: z.object({}), output: z.object({}), @@ -412,7 +412,7 @@ export function createRunApiTests(createDialect: () => Dialect) { return {} }, }), - ) + }) // Don't start the worker - job will never complete // Or start with a delay that exceeds timeout @@ -425,8 +425,8 @@ export function createRunApiTests(createDialect: () => Dialect) { describe('step.progress()', () => { it('saves progress with current value', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'progress-test', input: z.object({}), run: async (step) => { @@ -436,7 +436,7 @@ export function createRunApiTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -454,8 +454,8 @@ export function createRunApiTests(createDialect: () => Dialect) { }) it('saves progress with all fields', async () => { - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'full-progress-test', input: z.object({}), run: async (step) => { @@ -465,7 +465,7 @@ export function createRunApiTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() @@ -489,8 +489,8 @@ export function createRunApiTests(createDialect: () => Dialect) { it('progress is available via getRun()', async () => { let progressSet = false - const job = durably.register( - defineJob({ + const { job } = durably.register({ + job: defineJob({ name: 'get-progress-test', input: z.object({}), run: async (step) => { @@ -501,7 +501,7 @@ export function createRunApiTests(createDialect: () => Dialect) { }) }, }), - ) + }) const run = await job.trigger({}) durably.start() diff --git a/packages/durably/tests/shared/step.shared.ts b/packages/durably/tests/shared/step.shared.ts index eb4b6fc4..616e0cb7 100644 --- a/packages/durably/tests/shared/step.shared.ts +++ b/packages/durably/tests/shared/step.shared.ts @@ -36,7 +36,7 @@ export function createStepTests(createDialect: () => Dialect) { return { result: value } }, }) - const job = durably.register(stepReturnTestDef) + const { job } = durably.register({ job: stepReturnTestDef }) const run = await job.trigger({}) durably.start() @@ -60,7 +60,7 @@ export function createStepTests(createDialect: () => Dialect) { await step.run('step2', () => 'result2') }, }) - const job = durably.register(stepRecordTestDef) + const { job } = durably.register({ job: stepRecordTestDef }) const run = await job.trigger({}) durably.start() @@ -90,7 +90,7 @@ export function createStepTests(createDialect: () => Dialect) { }) }, }) - const job = durably.register(stepFailTestDef) + const { job } = durably.register({ job: stepFailTestDef }) const run = await job.trigger({}) durably.start() @@ -133,7 +133,7 @@ export function createStepTests(createDialect: () => Dialect) { }) }, }) - const job = durably.register(stepResumeTestDef) + const { job } = durably.register({ job: stepResumeTestDef }) // First run - will fail at step2 const run1 = await job.trigger({ shouldFail: true }) @@ -194,7 +194,7 @@ export function createStepTests(createDialect: () => Dialect) { return { step1Result: result } }, }) - const job = durably.register(stepOutputResumeTestDef) + const { job } = durably.register({ job: stepOutputResumeTestDef }) // First attempt - step1 succeeds, step2 fails const run = await job.trigger({}) @@ -243,7 +243,7 @@ export function createStepTests(createDialect: () => Dialect) { await step.run('myStep', () => 'hello') }, }) - const job = durably.register(stepEventsTestDef) + const { job } = durably.register({ job: stepEventsTestDef }) await job.trigger({}) durably.start() @@ -271,7 +271,7 @@ export function createStepTests(createDialect: () => Dialect) { return { value } }, }) - const job = durably.register(asyncStepTestDef) + const { job } = durably.register({ job: asyncStepTestDef }) const run = await job.trigger({}) durably.start() @@ -297,7 +297,7 @@ export function createStepTests(createDialect: () => Dialect) { }) }, }) - const job = durably.register(stepTimingTestDef) + const { job } = durably.register({ job: stepTimingTestDef }) const run = await job.trigger({}) durably.start() @@ -341,7 +341,7 @@ export function createStepTests(createDialect: () => Dialect) { step.progress(3, 3, 'Complete') }, }) - const job = durably.register(progressTestDef) + const { job } = durably.register({ job: progressTestDef }) const run = await job.trigger({}) durably.start() diff --git a/packages/durably/tests/shared/worker.shared.ts b/packages/durably/tests/shared/worker.shared.ts index 58b58ad5..f3e0283b 100644 --- a/packages/durably/tests/shared/worker.shared.ts +++ b/packages/durably/tests/shared/worker.shared.ts @@ -28,7 +28,7 @@ export function createWorkerTests(createDialect: () => Dialect) { output: z.object({ done: z.boolean() }), run: async () => ({ done: true }), }) - const job = durably.register(pollingTestDef) + const { job } = durably.register({ job: pollingTestDef }) await job.trigger({}) durably.start() @@ -55,7 +55,7 @@ export function createWorkerTests(createDialect: () => Dialect) { }) }, }) - const job = durably.register(stopTestDef) + const { job } = durably.register({ job: stopTestDef }) await job.trigger({}) durably.start() @@ -92,7 +92,7 @@ export function createWorkerTests(createDialect: () => Dialect) { output: z.object({ value: z.number() }), run: async () => ({ value: 42 }), }) - const job = durably.register(stateTestDef) + const { job } = durably.register({ job: stateTestDef }) const run = await job.trigger({}) expect(run.status).toBe('pending') @@ -118,7 +118,7 @@ export function createWorkerTests(createDialect: () => Dialect) { throw new Error('Job failed intentionally') }, }) - const job = durably.register(failTestDef) + const { job } = durably.register({ job: failTestDef }) const run = await job.trigger({}) durably.start() @@ -145,7 +145,7 @@ export function createWorkerTests(createDialect: () => Dialect) { receivedPayload = payload }, }) - const job = durably.register(payloadTestDef) + const { job } = durably.register({ job: payloadTestDef }) await job.trigger({ value: 'hello' }) durably.start() @@ -165,7 +165,7 @@ export function createWorkerTests(createDialect: () => Dialect) { output: z.object({ result: z.number() }), run: async () => ({ result: 123 }), }) - const job = durably.register(outputTestDef) + const { job } = durably.register({ job: outputTestDef }) const run = await job.trigger({}) durably.start() @@ -191,7 +191,7 @@ export function createWorkerTests(createDialect: () => Dialect) { await new Promise((r) => setTimeout(r, 20)) }, }) - const job = durably.register(sequentialTestDef) + const { job } = durably.register({ job: sequentialTestDef }) await job.trigger({ n: 1 }) await job.trigger({ n: 2 }) diff --git a/website/api/define-job.md b/website/api/define-job.md index d679000f..0da56119 100644 --- a/website/api/define-job.md +++ b/website/api/define-job.md @@ -46,10 +46,18 @@ Returns a `JobDefinition` object that can be registered with `durably.register() ## Registering Jobs -Use `durably.register()` to register a job definition and get a job handle: +Use `durably.register()` to register job definitions and get job handles: ```ts -const job = durably.register(jobDef) +const { job } = durably.register({ + job: jobDef, +}) + +// Multiple jobs at once +const { syncUsers, importCsv } = durably.register({ + syncUsers: syncUsersJob, + importCsv: importCsvJob, +}) ``` The job handle provides the following methods: @@ -120,7 +128,9 @@ const syncUsersJob = defineJob({ }) // Register with durably instance -const syncUsers = durably.register(syncUsersJob) +const { syncUsers } = durably.register({ + syncUsers: syncUsersJob, +}) // Trigger the job await syncUsers.trigger({ orgId: 'org_123' }) @@ -147,7 +157,9 @@ const exampleJob = defineJob({ }, }) -const job = durably.register(exampleJob) +const { job } = durably.register({ + job: exampleJob, +}) // trigger() is typed await job.trigger({ id: 'abc' }) // OK @@ -161,8 +173,8 @@ Registering the same `JobDefinition` instance multiple times returns the same jo ```ts const jobDef = defineJob({ name: 'my-job', ... }) -const handle1 = durably.register(jobDef) -const handle2 = durably.register(jobDef) +const { job: handle1 } = durably.register({ job: jobDef }) +const { job: handle2 } = durably.register({ job: jobDef }) console.log(handle1 === handle2) // true ``` diff --git a/website/api/durably-react.md b/website/api/durably-react.md index 08a1e811..7eb6fd56 100644 --- a/website/api/durably-react.md +++ b/website/api/durably-react.md @@ -304,7 +304,7 @@ const syncJob = defineJob({ // Job logic }, }) -durably.register(syncJob) +durably.register({ syncJob }) await durably.migrate() durably.start() diff --git a/website/api/index.md b/website/api/index.md index 1c0add7c..61e39eb1 100644 --- a/website/api/index.md +++ b/website/api/index.md @@ -47,7 +47,7 @@ durably.start() // Start the worker await durably.stop() // Stop the worker gracefully // Job management -const job = durably.register(jobDef) // Register a job definition +const { job } = durably.register({ job: jobDef }) // Register jobs await durably.retry(runId) // Retry a failed run // Events @@ -73,7 +73,9 @@ const myJobDef = defineJob({ }) // Register with durably instance -const myJob = durably.register(myJobDef) +const { myJob } = durably.register({ + myJob: myJobDef, +}) // Trigger a new run await myJob.trigger(input, options?) diff --git a/website/api/step.md b/website/api/step.md index becee63d..a1164164 100644 --- a/website/api/step.md +++ b/website/api/step.md @@ -135,7 +135,9 @@ const processOrderJob = defineJob({ }) // Register and use -const processOrder = durably.register(processOrderJob) +const { processOrder } = durably.register({ + processOrder: processOrderJob, +}) await processOrder.trigger({ orderId: 'order_123' }) ``` diff --git a/website/guide/full-stack.md b/website/guide/full-stack.md index 2b8ed17f..e3c501e6 100644 --- a/website/guide/full-stack.md +++ b/website/guide/full-stack.md @@ -12,10 +12,10 @@ This guide uses [React Router v7](https://reactrouter.com/) as the full-stack fr ## Architecture -``` +```txt ┌─────────────────┐ HTTP/SSE ┌─────────────────┐ │ React Client │ ◄──────────────► │ React Router │ -│ (useJob hooks) │ │ Server (Durably)│ +│ (durably hooks)│ │ Server (Durably)│ └─────────────────┘ └─────────────────┘ ``` @@ -29,21 +29,21 @@ npm install @coji/durably @coji/durably-react kysely zod @libsql/client @libsql/ ```txt app/ -├── .server/ -│ └── durably.ts # Durably instance and jobs +├── lib/ +│ ├── durably.server.ts # Durably instance and jobs (server-only) +│ └── durably.client.ts # Type-safe client hooks (client-only) ├── routes/ │ ├── api.durably.trigger.ts # POST /api/durably/trigger -│ └── api.durably.subscribe.ts # GET /api/durably/subscribe -└── routes/ - └── _index.tsx # Client component with useJob +│ ├── api.durably.subscribe.ts # GET /api/durably/subscribe +│ └── _index.tsx # Upload form with action ``` -## Server Setup +## Setup -### 1. Create Durably Instance +### 1. Server (`durably.server.ts`) ```ts -// app/.server/durably.ts +// app/lib/durably.server.ts import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' import { LibsqlDialect } from '@libsql/kysely-libsql' import { createClient } from '@libsql/client' @@ -55,39 +55,65 @@ const dialect = new LibsqlDialect({ client }) export const durably = createDurably({ dialect }) export const handler = createDurablyHandler(durably) -// Define and register jobs -export const syncJob = defineJob({ - name: 'sync-data', - input: z.object({ userId: z.string() }), - output: z.object({ count: z.number() }), +// Define jobs +const importCsvJob = defineJob({ + name: 'importCsv', + input: z.object({ rows: z.array(z.record(z.string())) }), + output: z.object({ imported: z.number(), skipped: z.number() }), run: async (step, payload) => { - const users = await step.run('fetch-users', async () => { - return await api.fetchUsers(payload.userId) - }) - - await step.run('save-to-db', async () => { - await db.saveUsers(users) - }) - - return { count: users.length } + let imported = 0 + let skipped = 0 + + for (let i = 0; i < payload.rows.length; i++) { + await step.run(`import-row-${i}`, async () => { + try { + await db.insert('users', payload.rows[i]) + imported++ + } catch { + skipped++ + } + }) + step.setProgress({ current: i + 1, total: payload.rows.length }) + } + + return { imported, skipped } }, }) -durably.register(syncJob) +// Register jobs +export const jobs = durably.register({ + importCsv: importCsvJob, + // Add more jobs here: + // syncUsers: syncUsersJob, +}) // Initialize on server start await durably.migrate() durably.start() ``` -### 2. Create API Routes +### 2. Client (`durably.client.ts`) + +Create a type-safe client once, import the jobs type using `import type`: + +```ts +// app/lib/durably.client.ts +import { createDurablyClient } from '@coji/durably-react/client' +import type { jobs } from '~/lib/durably.server' + +export const durably = createDurablyClient({ + api: '/api/durably', +}) +``` + +### 3. API Routes **Trigger Route:** ```ts // app/routes/api.durably.trigger.ts import type { Route } from './+types/api.durably.trigger' -import { handler } from '~/.server/durably' +import { handler } from '~/lib/durably.server' export async function action({ request }: Route.ActionArgs) { return handler.trigger(request) @@ -99,94 +125,109 @@ export async function action({ request }: Route.ActionArgs) { ```ts // app/routes/api.durably.subscribe.ts import type { Route } from './+types/api.durably.subscribe' -import { handler } from '~/.server/durably' +import { handler } from '~/lib/durably.server' export async function loader({ request }: Route.LoaderArgs) { return handler.subscribe(request) } ``` -## Client Setup +## Usage -### useJob Hook +### Server-Side Trigger (Form with action) ```tsx // app/routes/_index.tsx -import { useJob } from '@coji/durably-react/client' - -export default function Index() { - const { - trigger, - status, - output, - error, - progress, - isRunning, - isCompleted, - isFailed, - } = useJob< - { userId: string }, - { count: number } - >({ - api: '/api/durably', - jobName: 'sync-data', +import { Form } from 'react-router' +import type { Route } from './+types/_index' +import { jobs } from '~/lib/durably.server' +import { durably } from '~/lib/durably.client' + +function parseCSV(text: string): Record[] { + const lines = text.trim().split('\n') + const headers = lines[0].split(',') + return lines.slice(1).map((line) => { + const values = line.split(',') + return Object.fromEntries(headers.map((h, i) => [h, values[i]])) }) +} + +export async function action({ request }: Route.ActionArgs) { + const formData = await request.formData() + const file = formData.get('file') as File + const text = await file.text() + const rows = parseCSV(text) + + const { runId } = await jobs.importCsv.trigger({ rows }) + return { runId } +} + +export default function CsvImporter({ actionData }: Route.ComponentProps) { + const { progress, output, error, isRunning, isCompleted, isFailed } = + durably.importCsv.useRun(actionData?.runId ?? null) return (
- +
+ + +
{progress && ( -

Progress: {progress.current}/{progress.total}

+
+ +

{progress.current} / {progress.total} rows

+
)} - {isCompleted &&

Synced {output?.count} items

} + {isCompleted && ( +

Done! Imported {output?.imported}, skipped {output?.skipped}

+ )} {isFailed &&

Error: {error}

}
) } ``` -### useJobRun Hook +### Client-Side Trigger -Subscribe to an existing run by ID: +For cases where you trigger from the client: ```tsx -import { useJobRun } from '@coji/durably-react/client' +import { durably } from '~/lib/durably.client' -function RunMonitor({ runId }: { runId: string }) { - const { status, output, error, progress } = useJobRun<{ count: number }>({ - api: '/api/durably', - runId, - }) +function SimpleImporter() { + const { trigger, progress, isRunning, isCompleted, output } = + durably.importCsv.useJob() + + const handleFileChange = async (e: React.ChangeEvent) => { + const file = e.target.files?.[0] + if (!file) return + + const text = await file.text() + const rows = parseCSV(text) + trigger({ rows }) // Fully type-safe with autocomplete! + } return (
-

Status: {status}

- {output &&

Result: {output.count} items

} + + {isRunning &&

Progress: {progress?.current}/{progress?.total}

} + {isCompleted &&

Imported {output?.imported} rows

}
) } ``` -### useJobLogs Hook - -Subscribe to logs from a run: +### Subscribe to Logs ```tsx -import { useJobLogs } from '@coji/durably-react/client' +import { durably } from '~/lib/durably.client' -function LogViewer({ runId }: { runId: string }) { - const { logs, clearLogs } = useJobLogs({ - api: '/api/durably', - runId, - maxLogs: 100, - }) +function ImportLogs({ runId }: { runId: string }) { + const { logs, clearLogs } = durably.importCsv.useLogs(runId, { maxLogs: 100 }) return (
@@ -203,12 +244,13 @@ function LogViewer({ runId }: { runId: string }) { } ``` -## Available Hooks +## API Reference -| Hook | Description | -|------|-------------| -| `useJob` | Trigger and monitor a job with real-time status, progress, and logs | -| `useJobRun` | Subscribe to an existing run by ID | -| `useJobLogs` | Subscribe to logs from a run with optional limit | +| Function | Description | +| ------------------------------------ | ------------------------------------ | +| `createDurablyClient()` | Create type-safe client for all jobs | +| `durably.jobName.useJob()` | Trigger and monitor a job | +| `durably.jobName.useRun(runId)` | Subscribe to an existing run | +| `durably.jobName.useLogs(runId)` | Subscribe to logs from a run | See the [API Reference](/api/durably-react#server-connected-mode) for detailed documentation. diff --git a/website/guide/getting-started.md b/website/guide/getting-started.md index 55cdb84f..f561c785 100644 --- a/website/guide/getting-started.md +++ b/website/guide/getting-started.md @@ -32,37 +32,40 @@ const client = createClient({ url: 'file:local.db' }) const dialect = new LibsqlDialect({ client }) const durably = createDurably({ dialect }) -// Define a job -const syncUsersJob = defineJob({ - name: 'sync-users', - input: z.object({ orgId: z.string() }), +// Define a CSV import job +const importCsvJob = defineJob({ + name: 'import-csv', + input: z.object({ filePath: z.string() }), output: z.object({ count: z.number() }), run: async (step, payload) => { - // Step 1: Fetch users - const users = await step.run('fetch', async () => { - const res = await fetch(`https://api.example.com/orgs/${payload.orgId}/users`) - return res.json() + // Step 1: Parse CSV + const rows = await step.run('parse', async () => { + const fs = await import('fs/promises') + const csv = await fs.readFile(payload.filePath, 'utf-8') + return csv.split('\n').slice(1).map((line) => line.split(',')) }) - // Step 2: Save to database - await step.run('save', async () => { + // Step 2: Import rows + await step.run('import', async () => { // Your database logic here - console.log(`Saving ${users.length} users`) + console.log(`Importing ${rows.length} rows`) }) - return { count: users.length } + return { count: rows.length } }, }) // Register the job -const syncUsers = durably.register(syncUsersJob) +const { importCsv } = durably.register({ + importCsv: importCsvJob, +}) // Initialize and start await durably.migrate() durably.start() // Trigger a job -await syncUsers.trigger({ orgId: 'org_123' }) +await importCsv.trigger({ filePath: './data/users.csv' }) ``` ### 3. Run @@ -71,7 +74,7 @@ await syncUsers.trigger({ orgId: 'org_123' }) npx tsx jobs.ts ``` -If the process crashes after step 1, restarting will skip the fetch and continue from step 2. +If the process crashes after step 1, restarting will skip the parse and continue from step 2. ## Next Steps diff --git a/website/guide/index.md b/website/guide/index.md index e325e62d..b81c29fd 100644 --- a/website/guide/index.md +++ b/website/guide/index.md @@ -6,15 +6,15 @@ Durably is a **resumable job execution** library for Node.js and browsers. Split ### Long-Running Jobs with Progress UI -Execute jobs on the server and show real-time progress in your React app via SSE. +Import a CSV with thousands of rows and show real-time progress in your React app via SSE. ```tsx const { trigger, progress, isRunning } = useJob({ api: '/api/durably', - jobName: 'sync-data', + jobName: 'import-csv', }) -// Progress: 50/100 +// Progress: 500/1000 rows ``` [Full-Stack Guide →](/guide/full-stack) @@ -24,14 +24,16 @@ const { trigger, progress, isRunning } = useJob({ Fetch data from APIs, transform, and save. If the process fails midway, it resumes from where it left off. ```ts -const syncJob = defineJob({ - name: 'sync-users', +const importJob = defineJob({ + name: 'import-csv', run: async (step, payload) => { - // Step 1: Fetch (persisted after completion) - const users = await step.run('fetch', () => api.getUsers()) + // Step 1: Parse CSV (persisted after completion) + const rows = await step.run('parse', () => parseCSV(payload.csv)) - // Step 2: Save (skipped if already done) - await step.run('save', () => db.saveUsers(users)) + // Step 2: Import (skipped if already done) + for (const [i, row] of rows.entries()) { + await step.run(`import-${i}`, () => db.insert(row)) + } }, }) ``` diff --git a/website/guide/jobs-and-steps.md b/website/guide/jobs-and-steps.md index 97b4c50b..57e93b95 100644 --- a/website/guide/jobs-and-steps.md +++ b/website/guide/jobs-and-steps.md @@ -22,7 +22,9 @@ const myJobDef = defineJob({ }) // Register to get a job handle -const myJob = durably.register(myJobDef) +const { myJob } = durably.register({ + myJob: myJobDef, +}) ``` ### Job Options From 664fca076fcda329d4b0e58bf4d293d6605a86b9 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 21:54:01 +0900 Subject: [PATCH 030/101] docs: simplify READMEs and update examples to new register API MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Simplify root README (87 → 30 lines) - Simplify packages/durably README (83 → 47 lines) - Simplify packages/durably-react README (242 → 56 lines) - Move detailed documentation to website - Update examples to use new register API pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- README.md | 57 +---- examples/browser/src/main.ts | 6 +- examples/node/basic.ts | 6 +- examples/react/src/jobs/processImage.ts | 6 +- packages/durably-react/README.md | 222 ++---------------- .../tests/browser/use-job-logs.test.tsx | 12 +- .../tests/browser/use-job-run.test.tsx | 8 +- packages/durably/README.md | 56 +---- 8 files changed, 57 insertions(+), 316 deletions(-) diff --git a/README.md b/README.md index 12e3ac28..55e4c901 100644 --- a/README.md +++ b/README.md @@ -20,62 +20,9 @@ Step-oriented resumable batch execution for Node.js and browsers using SQLite. - Event system for monitoring and extensibility - Type-safe input/output with Zod schemas -## Installation +## Quick Start -```bash -# Node.js with better-sqlite3 -npm install @coji/durably kysely zod better-sqlite3 - -# Node.js with libsql -npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql - -# Browser with SQLocal -npm install @coji/durably kysely zod sqlocal -``` - -## Usage - -```ts -import { createDurably } from '@coji/durably' -import SQLite from 'better-sqlite3' -import { SqliteDialect } from 'kysely' -import { z } from 'zod' - -const dialect = new SqliteDialect({ - database: new SQLite('local.db'), -}) - -const durably = createDurably({ dialect }) - -const syncUsers = durably.defineJob( - { - name: 'sync-users', - input: z.object({ orgId: z.string() }), - output: z.object({ syncedCount: z.number() }), - }, - async (step, payload) => { - const users = await step.run('fetch-users', async () => { - return api.fetchUsers(payload.orgId) - }) - - await step.run('save-to-db', async () => { - await db.upsertUsers(users) - }) - - return { syncedCount: users.length } - }, -) - -await durably.migrate() -durably.start() - -await syncUsers.trigger({ orgId: 'org_123' }) -``` - -## Documentation - -- [Specification](docs/spec.md) - Core API and concepts -- [Streaming Extension](docs/spec-streaming.md) - AI Agent workflow support (conceptual, not yet implemented) +See the [Getting Started Guide](https://coji.github.io/durably/guide/getting-started) for installation and usage instructions. ## License diff --git a/examples/browser/src/main.ts b/examples/browser/src/main.ts index 0b7f3501..36b83688 100644 --- a/examples/browser/src/main.ts +++ b/examples/browser/src/main.ts @@ -22,8 +22,8 @@ const durably = createDurably({ }) // Define job -const processImage = durably.register( - defineJob({ +const { processImage } = durably.register({ + processImage: defineJob({ name: 'process-image', input: z.object({ filename: z.string(), width: z.number() }), output: z.object({ url: z.string(), size: z.number() }), @@ -49,7 +49,7 @@ const processImage = durably.register( return { url, size: resizedSize } }, }), -) +}) const delay = (ms: number) => new Promise((r) => setTimeout(r, ms)) diff --git a/examples/node/basic.ts b/examples/node/basic.ts index e631a600..48353bbe 100644 --- a/examples/node/basic.ts +++ b/examples/node/basic.ts @@ -24,8 +24,8 @@ const durably = createDurably({ }) // Image processing job with sequential steps -const processImage = durably.register( - defineJob({ +const { processImage } = durably.register({ + processImage: defineJob({ name: 'process-image', input: z.object({ filename: z.string() }), output: z.object({ url: z.string() }), @@ -51,7 +51,7 @@ const processImage = durably.register( return { url: uploaded.url } }, }), -) +}) // Subscribe to events durably.on('run:start', (event) => { diff --git a/examples/react/src/jobs/processImage.ts b/examples/react/src/jobs/processImage.ts index 6333b217..f4015b22 100644 --- a/examples/react/src/jobs/processImage.ts +++ b/examples/react/src/jobs/processImage.ts @@ -10,8 +10,8 @@ import { durably } from '../lib/durably' const delay = (ms: number) => new Promise((r) => setTimeout(r, ms)) -export const processImage = durably.register( - defineJob({ +export const { processImage } = durably.register({ + processImage: defineJob({ name: 'process-image', input: z.object({ filename: z.string(), width: z.number() }), output: z.object({ url: z.string(), size: z.number() }), @@ -37,4 +37,4 @@ export const processImage = durably.register( return { url, size: resizedSize } }, }), -) +}) diff --git a/packages/durably-react/README.md b/packages/durably-react/README.md index f6a05b54..3169ad12 100644 --- a/packages/durably-react/README.md +++ b/packages/durably-react/README.md @@ -4,235 +4,51 @@ React bindings for [Durably](https://github.com/coji/durably) - step-oriented re **[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)** -## Features - -- React hooks for triggering and monitoring Durably jobs -- Real-time status updates, progress, and logs -- Type-safe with full TypeScript support -- Two operation modes: - - **Browser-complete mode**: Run Durably entirely in the browser with OPFS - - **Server-connected mode**: Connect to a remote Durably server via SSE - ## Installation ```bash -# Browser-complete mode (with SQLocal) +# Browser mode (with SQLocal) npm install @coji/durably-react @coji/durably kysely zod sqlocal # Server-connected mode (client only) npm install @coji/durably-react ``` -## Browser-Complete Mode - -Run Durably entirely in the browser using SQLite WASM with OPFS backend. - -### Setup - -```tsx -import { DurablyProvider } from '@coji/durably-react' -import { SQLocalKysely } from 'sqlocal/kysely' - -function App() { - return ( - new SQLocalKysely('app.sqlite3').dialect} - > - - - ) -} -``` - -### useJob Hook - -Trigger and monitor a job's execution: +## Quick Start ```tsx import { defineJob } from '@coji/durably' -import { useJob } from '@coji/durably-react' -import { z } from 'zod' +import { DurablyProvider, useJob } from '@coji/durably-react' +import { SQLocalKysely } from 'sqlocal/kysely' -const syncJob = defineJob({ - name: 'sync-data', - input: z.object({ userId: z.string() }), - output: z.object({ count: z.number() }), +const myJob = defineJob({ + name: 'my-job', + input: z.object({ id: z.string() }), run: async (step, payload) => { - const data = await step.run('fetch', () => api.fetch(payload.userId)) - await step.run('save', () => db.save(data)) - return { count: data.length } + await step.run('step-1', async () => { /* ... */ }) }, }) -function SyncButton() { - const { trigger, status, output, error, progress, isRunning, isCompleted } = - useJob(syncJob) - - return ( -
- - - {progress && ( -

- Progress: {progress.current}/{progress.total} -

- )} - - {isCompleted &&

Synced {output?.count} items

} - {error &&

Error: {error}

} -
- ) -} -``` - -### useJobRun Hook - -Subscribe to an existing run by ID: - -```tsx -import { useJobRun } from '@coji/durably-react' - -function RunStatus({ runId }: { runId: string }) { - const { status, output, error, progress } = useJobRun({ runId }) - - return ( -
-

Status: {status}

- {progress &&

Progress: {progress.message}

} -
- ) -} -``` - -### useJobLogs Hook - -Subscribe to logs from a run: - -```tsx -import { useJobLogs } from '@coji/durably-react' - -function LogViewer({ runId }: { runId: string }) { - const { logs, clearLogs } = useJobLogs({ runId, maxLogs: 100 }) - +function App() { return ( -
- - {logs.map((log) => ( -
- [{log.level}] {log.message} -
- ))} -
+ new SQLocalKysely('app.sqlite3').dialect}> + + ) } -``` - -## Server-Connected Mode - -Connect to a Durably server via HTTP/SSE. No `@coji/durably` dependency needed on the client. - -### Client Setup -```tsx -import { useJob, useJobRun, useJobLogs } from '@coji/durably-react/client' - -function SyncButton() { - const { trigger, status, output } = useJob< - { userId: string }, - { count: number } - >({ - api: '/api/durably', - jobName: 'sync-data', - }) - - return +function MyComponent() { + const { trigger, isRunning, isCompleted } = useJob(myJob) + return } ``` -### Server Setup - -On your server, use `createDurablyHandler` to expose the API: - -```ts -// server.ts -import { createDurably, createDurablyHandler, defineJob } from '@coji/durably' - -const durably = createDurably({ dialect }) -const handler = createDurablyHandler(durably) - -// Register jobs -durably.register({ syncJob }) - -// Route handlers -app.post('/api/durably/trigger', (req) => handler.trigger(req)) -app.get('/api/durably/subscribe', (req) => handler.subscribe(req)) -``` - -## API Reference - -### DurablyProvider - -| Prop | Type | Default | Description | -| ---------------- | ---------------- | -------- | ----------------------------- | -| `dialectFactory` | `() => Dialect` | required | Factory for Kysely dialect | -| `options` | `DurablyOptions` | - | Durably configuration options | -| `autoStart` | `boolean` | `true` | Auto-start the worker | -| `autoMigrate` | `boolean` | `true` | Auto-run migrations | - -### useJob (Browser Mode) - -```ts -const result = useJob(jobDefinition, options?) -``` - -**Returns:** - -- `isReady`: Whether Durably is initialized -- `trigger(input)`: Trigger job, returns `{ runId }` -- `triggerAndWait(input)`: Trigger and wait for completion -- `status`: `'pending' | 'running' | 'completed' | 'failed' | null` -- `output`: Job output (when completed) -- `error`: Error message (when failed) -- `progress`: `{ current, total?, message? }` -- `logs`: Array of log entries -- `isRunning`, `isPending`, `isCompleted`, `isFailed`: Boolean helpers -- `currentRunId`: Current run ID -- `reset()`: Reset all state - -### useJob (Client Mode) - -```ts -const result = useJob({ api, jobName }) -``` - -Same return type as browser mode. - -### useJobRun - -```ts -const result = useJobRun({ runId }) // Browser mode -const result = useJobRun({ api, runId }) // Client mode -``` - -**Returns:** Same as `useJob` except no `trigger` functions. - -### useJobLogs - -```ts -const result = useJobLogs({ runId, maxLogs? }) // Browser mode -const result = useJobLogs({ api, runId, maxLogs? }) // Client mode -``` +## Documentation -**Returns:** +For full documentation, visit [coji.github.io/durably](https://coji.github.io/durably/). -- `isReady`: Whether ready -- `logs`: Array of log entries -- `clearLogs()`: Clear collected logs +- [React Guide](https://coji.github.io/durably/guide/react) - Browser mode with hooks +- [Full-Stack Guide](https://coji.github.io/durably/guide/full-stack) - Server-connected mode ## License diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx index 2ccb469a..ec734648 100644 --- a/packages/durably-react/tests/browser/use-job-logs.test.tsx +++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx @@ -106,7 +106,9 @@ describe('useJobLogs', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const { _job: handle } = result.current.durably!.register({ _job: loggingJob }) + const { _job: handle } = result.current.durably!.register({ + _job: loggingJob, + }) const run = await handle.trigger({ count: 3 }) result.current.setRunId(run.id) @@ -156,7 +158,9 @@ describe('useJobLogs', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const { _job: handle } = result.current.durably!.register({ _job: loggingJob }) + const { _job: handle } = result.current.durably!.register({ + _job: loggingJob, + }) const run = await handle.trigger({ count: 10 }) result.current.setRunId(run.id) @@ -188,7 +192,9 @@ describe('useJobLogs', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const { _job: handle } = result.current.durably!.register({ _job: loggingJob }) + const { _job: handle } = result.current.durably!.register({ + _job: loggingJob, + }) const run = await handle.trigger({ count: 3 }) result.current.setRunId(run.id) diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx index 33a2d2e8..e1230ad9 100644 --- a/packages/durably-react/tests/browser/use-job-run.test.tsx +++ b/packages/durably-react/tests/browser/use-job-run.test.tsx @@ -214,7 +214,9 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const { _job: handle } = result.current.durably!.register({ _job: failingJob }) + const { _job: handle } = result.current.durably!.register({ + _job: failingJob, + }) const run = await handle.trigger({ input: 'test' }) result.current.setRunId(run.id) @@ -248,7 +250,9 @@ describe('useJobRun', () => { await waitFor(() => expect(result.current.isReady).toBe(true)) - const { _job: handle } = result.current.durably!.register({ _job: progressJob }) + const { _job: handle } = result.current.durably!.register({ + _job: progressJob, + }) const run = await handle.trigger({ input: 'test' }) result.current.setRunId(run.id) diff --git a/packages/durably/README.md b/packages/durably/README.md index ebfa0fe5..bd99ed36 100644 --- a/packages/durably/README.md +++ b/packages/durably/README.md @@ -4,65 +4,33 @@ Step-oriented resumable batch execution for Node.js and browsers using SQLite. **[Documentation](https://coji.github.io/durably/)** | **[GitHub](https://github.com/coji/durably)** | **[Live Demo](https://durably-demo.vercel.app)** -## Features - -- Resumable batch processing with step-level persistence -- Works in both Node.js and browsers -- Uses SQLite for state management (better-sqlite3/libsql for Node.js, SQLite WASM for browsers) -- Minimal dependencies - just Kysely and Zod as peer dependencies -- Event system for monitoring and extensibility -- Type-safe input/output with Zod schemas - ## Installation ```bash -# Node.js with better-sqlite3 npm install @coji/durably kysely zod better-sqlite3 - -# Node.js with libsql -npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql - -# Browser with SQLocal -npm install @coji/durably kysely zod sqlocal ``` -## Usage +See the [Getting Started Guide](https://coji.github.io/durably/guide/getting-started) for other SQLite backends (libsql, SQLocal for browsers). + +## Quick Start ```ts -import { createDurably } from '@coji/durably' -import SQLite from 'better-sqlite3' -import { SqliteDialect } from 'kysely' -import { z } from 'zod' +import { createDurably, defineJob } from '@coji/durably' -const dialect = new SqliteDialect({ - database: new SQLite('local.db'), +const job = defineJob({ + name: 'my-job', + input: z.object({ id: z.string() }), + run: async (step, payload) => { + await step.run('step-1', async () => { /* ... */ }) + }, }) const durably = createDurably({ dialect }) - -const syncUsers = durably.defineJob( - { - name: 'sync-users', - input: z.object({ orgId: z.string() }), - output: z.object({ syncedCount: z.number() }), - }, - async (step, payload) => { - const users = await step.run('fetch-users', async () => { - return api.fetchUsers(payload.orgId) - }) - - await step.run('save-to-db', async () => { - await db.upsertUsers(users) - }) - - return { syncedCount: users.length } - }, -) +const { myJob } = durably.register({ myJob: job }) await durably.migrate() durably.start() - -await syncUsers.trigger({ orgId: 'org_123' }) +await myJob.trigger({ id: '123' }) ``` ## Documentation From 0da68729a7993308b5d2ff78912e0050662c1f22 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 22:01:04 +0900 Subject: [PATCH 031/101] chore: bump version to 0.6.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - @coji/durably: 0.5.0 → 0.6.0 - @coji/durably-react: 0.5.0 → 0.6.0 - Update CHANGELOG with breaking changes for register() API - Update CLAUDE.md with new API pattern 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- CHANGELOG.md | 17 +++++++++++++++++ CLAUDE.md | 2 +- packages/durably-react/package.json | 2 +- packages/durably/package.json | 2 +- 4 files changed, 20 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 987c5741..749375d3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/), and this project adheres to [Semantic Versioning](https://semver.org/). +## [0.6.0] - 2025-12-29 + +### Breaking Changes + +- **`register()` API simplified**: `registerAll()` renamed to `register()`, old single-job signature removed + - New: `const { job } = durably.register({ job: jobDef })` + - Old (removed): `const job = durably.register(jobDef)` + +### Changed + +- Simplified README files - detailed documentation moved to website +- Updated all examples to use new `register()` API pattern + +### Fixed + +- Type inference for `register()` return value now works correctly + ## [0.5.0] - 2025-12-24 ### Added diff --git a/CLAUDE.md b/CLAUDE.md index 97ede353..8ff57a8e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,7 @@ When API changes are made, update `packages/durably/docs/llms.md` to keep it in ## Core Concepts -- **Job**: Defined via `durably.defineJob()`, receives a step context and payload +- **Job**: Defined via `defineJob()` and registered with `durably.register()`, receives a step context and payload - **Step**: Created via `step.run()`, each step's success state and return value is persisted - **Run**: A job execution instance, created via `trigger()`, always persisted as `pending` before execution - **Worker**: Polls for pending runs and executes them sequentially diff --git a/packages/durably-react/package.json b/packages/durably-react/package.json index 88fd7775..6338aa16 100644 --- a/packages/durably-react/package.json +++ b/packages/durably-react/package.json @@ -1,6 +1,6 @@ { "name": "@coji/durably-react", - "version": "0.5.0", + "version": "0.6.0", "description": "React bindings for Durably - step-oriented resumable batch execution", "type": "module", "main": "./dist/index.js", diff --git a/packages/durably/package.json b/packages/durably/package.json index 87407805..724cc60a 100644 --- a/packages/durably/package.json +++ b/packages/durably/package.json @@ -1,6 +1,6 @@ { "name": "@coji/durably", - "version": "0.5.0", + "version": "0.6.0", "description": "Step-oriented resumable batch execution for Node.js and browsers using SQLite", "type": "module", "main": "./dist/index.js", From 8f1fa849ff880ea64e6f83411b922a487afb95cd Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 22:28:12 +0900 Subject: [PATCH 032/101] refactor(examples/react): use @coji/durably-react instead of custom hooks MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Replace custom useDurably hook and lib/durably singleton with DurablyProvider - Use useJob hook for job triggering and status monitoring - Update processImage job to standalone definition with progress and logs - Fix DurablyProvider StrictMode compatibility by preserving instance across remounts 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/react/package.json | 1 + examples/react/src/App.tsx | 257 +++++++++++++++--------- examples/react/src/hooks/useDurably.ts | 106 ---------- examples/react/src/jobs/processImage.ts | 65 +++--- examples/react/src/lib/durably.ts | 25 --- packages/durably-react/src/context.tsx | 41 +++- pnpm-lock.yaml | 3 + 7 files changed, 237 insertions(+), 261 deletions(-) delete mode 100644 examples/react/src/hooks/useDurably.ts delete mode 100644 examples/react/src/lib/durably.ts diff --git a/examples/react/package.json b/examples/react/package.json index 14a0387d..0b1bb0b6 100644 --- a/examples/react/package.json +++ b/examples/react/package.json @@ -14,6 +14,7 @@ }, "dependencies": { "@coji/durably": "workspace:*", + "@coji/durably-react": "workspace:*", "kysely": "^0.28.9", "react": "^19.2.3", "react-dom": "^19.2.3", diff --git a/examples/react/src/App.tsx b/examples/react/src/App.tsx index ab1e5d1a..c2cb65b6 100644 --- a/examples/react/src/App.tsx +++ b/examples/react/src/App.tsx @@ -1,134 +1,209 @@ /** * React Example for Durably * - * Simple example showing basic durably usage with React. - * Demonstrates job resumption after page reload. - * - * Structure follows the pattern that will be provided by @coji/durably-react: - * - lib/durably.ts: Singleton durably instance - * - hooks/useDurably.ts: React lifecycle management hook - * - jobs/*.ts: Job definitions + * Demonstrates @coji/durably-react usage with: + * - DurablyProvider for context + * - useJob hook for triggering and monitoring jobs + * - useDurably hook for direct Durably access */ +import { + DurablyProvider, + useDurably, + useJob, + type LogEntry, +} from '@coji/durably-react' import { useState } from 'react' -import { Dashboard } from './Dashboard' -import { useDurably } from './hooks/useDurably' -import { processImage } from './jobs/processImage' -import { deleteDatabaseFile, durably } from './lib/durably' +import { SQLocalKysely } from 'sqlocal/kysely' +import { processImageJob } from './jobs/processImage' import { styles } from './styles' // Links const GITHUB_REPO = 'https://github.com/coji/durably' const SOURCE_CODE = `${GITHUB_REPO}/tree/main/examples/react` -// Main App -export function App() { +// SQLocal instance for database operations +const sqlocal = new SQLocalKysely('example.sqlite3') + +// Durably configuration (defined outside component to maintain stable reference) +const dialectFactory = () => sqlocal.dialect +const durablyOptions = { + pollingInterval: 100, + heartbeatInterval: 500, + staleThreshold: 3000, +} + +function Demo() { + const { durably } = useDurably() const { + trigger, status, - currentStep, - result, - markUserTriggered, - setRefreshDashboard, - refreshDashboard, - } = useDurably() - const [activeTab, setActiveTab] = useState<'demo' | 'dashboard'>('demo') - const isProcessing = status === 'running' || status === 'resuming' - - const statusText: Record = { - init: 'Initializing...', - ready: 'Ready', - running: 'Running', - resuming: '🔄 Resuming interrupted job...', - done: '✓ Completed', - error: '✗ Failed', - } + output, + error, + progress, + logs, + isRunning, + isCompleted, + isFailed, + isReady, + reset, + } = useJob(processImageJob) const handleRun = async () => { - markUserTriggered() - await processImage.trigger({ filename: 'photo.jpg', width: 800 }) - refreshDashboard() + await trigger({ filename: 'photo.jpg', width: 800 }) } const handleReset = async () => { - await durably.stop() - await deleteDatabaseFile() + if (durably) { + await durably.stop() + } + await sqlocal.deleteDatabaseFile() location.reload() } - return ( -
-
-

Durably React Example

- -
+ const statusText = isRunning + ? 'Running...' + : isCompleted + ? '✓ Completed' + : isFailed + ? '✗ Failed' + : isReady + ? 'Ready' + : 'Initializing...' -
+ return ( + <> +
+ +
- {activeTab === 'demo' && ( - <> -
- +
+
+ Status: {statusText} +
+ {status && ( +
+ Run status: {status} +
+ )} + {progress && ( +
+ Progress: {progress.current} + {progress.total ? `/${progress.total}` : ''}{' '} + {progress.message || ''} +
+ )} +
+ + {output && ( + 
+          {JSON.stringify(output, null, 2)}
+
+ )} + + {error && 
{error}
} + + {logs.length > 0 && ( +
+ Logs: +
    + {logs.map((log: LogEntry) => ( +
  • + [{log.level}] {log.message} +
    • + ))} +
+
+ )} + + ) +} + +export function App() { + const [showInfo, setShowInfo] = useState(false) + + return ( + +
+
+

Durably React Example

+
+ + GitHub + + | + + Source Code + + | -
+
-
-
- Status: {statusText[status]} -
- {currentStep && ( -
- Step: {currentStep} -
- )} + {showInfo && ( +
+

+ This example uses @coji/durably-react for seamless + React integration: +

+
    +
  • + DurablyProvider - Context provider with auto + migration and worker start +
    • +
  • + useJob - Hook for triggering jobs and real-time + status updates +
    • +
  • + useDurably - Direct access to Durably instance +
    • +
+ )} - {result && ( - 
{result}
- )} - - )} - - {activeTab === 'dashboard' && ( - - )} -
+ +
+ ) } diff --git a/examples/react/src/hooks/useDurably.ts b/examples/react/src/hooks/useDurably.ts deleted file mode 100644 index d1b47ede..00000000 --- a/examples/react/src/hooks/useDurably.ts +++ /dev/null @@ -1,106 +0,0 @@ -/** - * useDurably hook - * - * Manages durably lifecycle in React applications. - * In the future, this hook will be provided by @coji/durably-react. - */ - -import { useEffect, useRef, useState } from 'react' -import { durably } from '../lib/durably' - -export type DurablyStatus = - | 'init' - | 'ready' - | 'running' - | 'resuming' - | 'done' - | 'error' - -export function useDurably() { - const [status, setStatus] = useState('init') - const [currentStep, setCurrentStep] = useState(null) - const [result, setResult] = useState(null) - const userTriggered = useRef(false) - const refreshDashboardRef = useRef<(() => void) | null>(null) - - useEffect(() => { - let cancelled = false - - const unsubscribes = [ - durably.on('run:start', () => { - if (!cancelled) { - setStatus(userTriggered.current ? 'running' : 'resuming') - } - }), - durably.on('step:complete', (e) => { - if (!cancelled) { - setCurrentStep(e.stepName) - } - }), - durably.on('run:complete', (e) => { - if (!cancelled) { - setResult(JSON.stringify(e.output, null, 2)) - setCurrentStep(null) - setStatus('done') - userTriggered.current = false - refreshDashboardRef.current?.() - } - }), - durably.on('run:fail', (e) => { - if (!cancelled) { - setResult(e.error) - setCurrentStep(null) - setStatus('error') - userTriggered.current = false - refreshDashboardRef.current?.() - } - }), - ] - - durably - .migrate() - .then(() => { - if (!cancelled) { - durably.start() - setStatus('ready') - } - }) - .catch((err) => { - if (!cancelled) { - console.error('Durably migration failed:', err) - setStatus('error') - } - }) - - return () => { - cancelled = true - for (const fn of unsubscribes) fn() - durably.stop() - } - }, []) - - const markUserTriggered = () => { - userTriggered.current = true - setStatus('running') - setCurrentStep(null) - setResult(null) - } - - const setRefreshDashboard = (fn: () => void) => { - refreshDashboardRef.current = fn - } - - const refreshDashboard = () => { - refreshDashboardRef.current?.() - } - - return { - status, - currentStep, - result, - markUserTriggered, - setRefreshDashboard, - refreshDashboard, - durably, - } -} diff --git a/examples/react/src/jobs/processImage.ts b/examples/react/src/jobs/processImage.ts index f4015b22..abb3e93f 100644 --- a/examples/react/src/jobs/processImage.ts +++ b/examples/react/src/jobs/processImage.ts @@ -2,39 +2,48 @@ * Process Image Job * * Example job that simulates image processing with multiple steps. + * This is a standalone job definition - registration happens in DurablyProvider. */ import { defineJob } from '@coji/durably' import { z } from 'zod' -import { durably } from '../lib/durably' const delay = (ms: number) => new Promise((r) => setTimeout(r, ms)) -export const { processImage } = durably.register({ - processImage: defineJob({ - name: 'process-image', - input: z.object({ filename: z.string(), width: z.number() }), - output: z.object({ url: z.string(), size: z.number() }), - run: async (step, payload) => { - // Download original image - const fileSize = await step.run('download', async () => { - await delay(300) - return Math.floor(Math.random() * 1000000) + 500000 // 500KB-1.5MB - }) - - // Resize to target width - const resizedSize = await step.run('resize', async () => { - await delay(400) - return Math.floor(fileSize * (payload.width / 1920)) - }) - - // Upload to CDN - const url = await step.run('upload', async () => { - await delay(300) - return `https://cdn.example.com/${payload.width}/${payload.filename}` - }) - - return { url, size: resizedSize } - }, - }), +export const processImageJob = defineJob({ + name: 'process-image', + input: z.object({ filename: z.string(), width: z.number() }), + output: z.object({ url: z.string(), size: z.number() }), + run: async (step, payload) => { + step.log.info(`Starting image processing: ${payload.filename}`) + + // Download original image + const fileSize = await step.run('download', async () => { + step.progress(1, 3, 'Downloading...') + await delay(300) + return Math.floor(Math.random() * 1000000) + 500000 // 500KB-1.5MB + }) + + step.log.info(`Downloaded: ${fileSize} bytes`) + + // Resize to target width + const resizedSize = await step.run('resize', async () => { + step.progress(2, 3, 'Resizing...') + await delay(400) + return Math.floor(fileSize * (payload.width / 1920)) + }) + + step.log.info(`Resized to: ${resizedSize} bytes`) + + // Upload to CDN + const url = await step.run('upload', async () => { + step.progress(3, 3, 'Uploading...') + await delay(300) + return `https://cdn.example.com/${payload.width}/${payload.filename}` + }) + + step.log.info(`Uploaded to: ${url}`) + + return { url, size: resizedSize } + }, }) diff --git a/examples/react/src/lib/durably.ts b/examples/react/src/lib/durably.ts deleted file mode 100644 index 2fd41024..00000000 --- a/examples/react/src/lib/durably.ts +++ /dev/null @@ -1,25 +0,0 @@ -/** - * Durably singleton instance - * - * This module exports a singleton durably instance for use throughout the app. - * - * NOTE: This simple singleton pattern does NOT handle HMR (Hot Module Replacement). - * During development, if this file is modified, a full page reload is required. - * - * In the future, @coji/durably-react will provide DurablyProvider that handles - * HMR and StrictMode correctly using dialectFactory pattern. - * See: docs/spec-react.md - */ - -import { createDurably } from '@coji/durably' -import { SQLocalKysely } from 'sqlocal/kysely' - -const sqlocal = new SQLocalKysely('example.sqlite3') -export const { dialect, deleteDatabaseFile } = sqlocal - -export const durably = createDurably({ - dialect, - pollingInterval: 100, - heartbeatInterval: 500, - staleThreshold: 3000, -}) diff --git a/packages/durably-react/src/context.tsx b/packages/durably-react/src/context.tsx index 4b6d8df9..0501f035 100644 --- a/packages/durably-react/src/context.tsx +++ b/packages/durably-react/src/context.tsx @@ -65,14 +65,23 @@ export function DurablyProvider({ // Use ref to track initialization state for StrictMode safety const initializedRef = useRef(false) const instanceRef = useRef(null) + const initPromiseRef = useRef | null>(null) useEffect(() => { // Prevent double initialization in StrictMode if (initializedRef.current) { - // If already initialized, just use the existing instance - if (instanceRef.current) { - setDurably(instanceRef.current) - setIsReady(true) + // If already initialized, wait for init to complete and use existing instance + if (initPromiseRef.current) { + initPromiseRef.current.then(() => { + if (instanceRef.current) { + setDurably(instanceRef.current) + setIsReady(true) + // Restart worker if it was stopped during unmount + if (autoStart) { + instanceRef.current.start() + } + } + }) } return } @@ -86,19 +95,19 @@ export function DurablyProvider({ const instance = createDurably({ dialect, ...options }) instanceRef.current = instance - if (cleanedUp) return - if (autoMigrate) { await instance.migrate() - if (cleanedUp) return + } + + if (cleanedUp) { + // StrictMode unmounted us, but keep the instance for remount + return } if (autoStart) { instance.start() } - if (cleanedUp) return - setDurably(instance) setIsReady(true) onReady?.(instance) @@ -108,15 +117,25 @@ export function DurablyProvider({ } } - init() + initPromiseRef.current = init() return () => { cleanedUp = true + // Don't stop the worker here - StrictMode will remount and we want to keep running + } + }, [dialectFactory, options, autoStart, autoMigrate, onReady]) + + // Separate cleanup effect that only runs when truly unmounting + // This works because React guarantees cleanup order: child effects clean up before parent + useEffect(() => { + return () => { + // This cleanup runs when the component is truly removed + // We need to stop the worker here if (instanceRef.current) { instanceRef.current.stop() } } - }, [dialectFactory, options, autoStart, autoMigrate, onReady]) + }, []) return ( diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index a89b7545..81dde17d 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -97,6 +97,9 @@ importers: '@coji/durably': specifier: workspace:* version: link:../../packages/durably + '@coji/durably-react': + specifier: workspace:* + version: link:../../packages/durably-react kysely: specifier: ^0.28.9 version: 0.28.9 From 3edb36893a2ad330be06bfda89338bb01345b4e6 Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 22:29:20 +0900 Subject: [PATCH 033/101] style: format README code examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/README.md | 14 +++++++++++--- packages/durably/README.md | 4 +++- 2 files changed, 14 insertions(+), 4 deletions(-) diff --git a/packages/durably-react/README.md b/packages/durably-react/README.md index 3169ad12..12eecbb3 100644 --- a/packages/durably-react/README.md +++ b/packages/durably-react/README.md @@ -25,13 +25,17 @@ const myJob = defineJob({ name: 'my-job', input: z.object({ id: z.string() }), run: async (step, payload) => { - await step.run('step-1', async () => { /* ... */ }) + await step.run('step-1', async () => { + /* ... */ + }) }, }) function App() { return ( - new SQLocalKysely('app.sqlite3').dialect}> + new SQLocalKysely('app.sqlite3').dialect} + > ) @@ -39,7 +43,11 @@ function App() { function MyComponent() { const { trigger, isRunning, isCompleted } = useJob(myJob) - return + return ( + + ) } ``` diff --git a/packages/durably/README.md b/packages/durably/README.md index bd99ed36..ecd5b4cb 100644 --- a/packages/durably/README.md +++ b/packages/durably/README.md @@ -21,7 +21,9 @@ const job = defineJob({ name: 'my-job', input: z.object({ id: z.string() }), run: async (step, payload) => { - await step.run('step-1', async () => { /* ... */ }) + await step.run('step-1', async () => { + /* ... */ + }) }, }) From bae79faeb082bfb5955ca285428fcb37289385df Mon Sep 17 00:00:00 2001 From: coji Date: Mon, 29 Dec 2025 22:34:29 +0900 Subject: [PATCH 034/101] build: add turbo for monorepo task orchestration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add turborepo for dependency-aware task execution - dev/build/test now automatically build dependencies first - Add build caching for faster subsequent builds 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .gitignore | 1 + package.json | 25 ++++++++++---------- pnpm-lock.yaml | 64 ++++++++++++++++++++++++++++++++++++++++++++++++++ turbo.json | 31 ++++++++++++++++++++++++ 4 files changed, 109 insertions(+), 12 deletions(-) create mode 100644 turbo.json diff --git a/.gitignore b/.gitignore index 8c4a42e8..7954a40f 100644 --- a/.gitignore +++ b/.gitignore @@ -5,6 +5,7 @@ dist/ __screenshots__/ local.db .serena/ +.turbo/ # VitePress website/.vitepress/cache/ diff --git a/package.json b/package.json index 5d4df473..0d480619 100644 --- a/package.json +++ b/package.json @@ -5,26 +5,27 @@ "license": "MIT", "packageManager": "pnpm@10.26.0", "scripts": { - "build": "pnpm -r build", - "test": "pnpm -r test", - "test:node": "pnpm --filter @coji/durably test:node", - "test:browser": "pnpm --filter @coji/durably test:browser", - "test:react": "pnpm --filter @coji/durably test:react", - "dev:node": "pnpm --filter example-node dev", - "dev:browser": "pnpm --filter example-browser dev", - "dev:react": "pnpm --filter example-react dev", - "typecheck": "pnpm -r typecheck", - "lint": "pnpm -r lint", + "build": "turbo run build", + "test": "turbo run test", + "test:node": "turbo run test:node --filter=@coji/durably", + "test:browser": "turbo run test:browser --filter=@coji/durably", + "test:react": "turbo run test:react --filter=@coji/durably", + "dev:node": "turbo run dev --filter=example-node", + "dev:browser": "turbo run dev --filter=example-browser", + "dev:react": "turbo run dev --filter=example-react", + "typecheck": "turbo run typecheck", + "lint": "turbo run lint", "lint:fix": "pnpm -r lint:fix", - "format": "pnpm -r format", + "format": "turbo run format", "format:fix": "pnpm -r format:fix", - "validate": "pnpm format && pnpm lint && pnpm typecheck && pnpm test" + "validate": "turbo run format lint typecheck test" }, "devDependencies": { "@biomejs/biome": "^2.3.10", "@types/node": "^25.0.3", "cc-hooks-ts": "2.0.70", "tsx": "^4.21.0", + "turbo": "2.7.2", "typescript": "^5.9.3" }, "pnpm": { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 81dde17d..2c2c09ab 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -20,6 +20,9 @@ importers: tsx: specifier: ^4.21.0 version: 4.21.0 + turbo: + specifier: 2.7.2 + version: 2.7.2 typescript: specifier: ^5.9.3 version: 5.9.3 @@ -2178,6 +2181,40 @@ packages: engines: {node: '>=18.0.0'} hasBin: true + turbo-darwin-64@2.7.2: + resolution: {integrity: sha512-dxY3X6ezcT5vm3coK6VGixbrhplbQMwgNsCsvZamS/+/6JiebqW9DKt4NwpgYXhDY2HdH00I7FWs3wkVuan4rA==} + cpu: [x64] + os: [darwin] + + turbo-darwin-arm64@2.7.2: + resolution: {integrity: sha512-1bXmuwPLqNFt3mzrtYcVx1sdJ8UYb124Bf48nIgcpMCGZy3kDhgxNv1503kmuK/37OGOZbsWSQFU4I08feIuSg==} + cpu: [arm64] + os: [darwin] + + turbo-linux-64@2.7.2: + resolution: {integrity: sha512-kP+TiiMaiPugbRlv57VGLfcjFNsFbo8H64wMBCPV2270Or2TpDCBULMzZrvEsvWFjT3pBFvToYbdp8/Kw0jAQg==} + cpu: [x64] + os: [linux] + + turbo-linux-arm64@2.7.2: + resolution: {integrity: sha512-VDJwQ0+8zjAfbyY6boNaWfP6RIez4ypKHxwkuB6SrWbOSk+vxTyW5/hEjytTwK8w/TsbKVcMDyvpora8tEsRFw==} + cpu: [arm64] + os: [linux] + + turbo-windows-64@2.7.2: + resolution: {integrity: sha512-rPjqQXVnI6A6oxgzNEE8DNb6Vdj2Wwyhfv3oDc+YM3U9P7CAcBIlKv/868mKl4vsBtz4ouWpTQNXG8vljgJO+w==} + cpu: [x64] + os: [win32] + + turbo-windows-arm64@2.7.2: + resolution: {integrity: sha512-tcnHvBhO515OheIFWdxA+qUvZzNqqcHbLVFc1+n+TJ1rrp8prYicQtbtmsiKgMvr/54jb9jOabU62URAobnB7g==} + cpu: [arm64] + os: [win32] + + turbo@2.7.2: + resolution: {integrity: sha512-5JIA5aYBAJSAhrhbyag1ZuMSgUZnHtI+Sq3H8D3an4fL8PeF+L1yYvbEJg47akP1PFfATMf5ehkqFnxfkmuwZQ==} + hasBin: true + typescript@5.9.3: resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} engines: {node: '>=14.17'} @@ -4245,6 +4282,33 @@ snapshots: optionalDependencies: fsevents: 2.3.3 + turbo-darwin-64@2.7.2: + optional: true + + turbo-darwin-arm64@2.7.2: + optional: true + + turbo-linux-64@2.7.2: + optional: true + + turbo-linux-arm64@2.7.2: + optional: true + + turbo-windows-64@2.7.2: + optional: true + + turbo-windows-arm64@2.7.2: + optional: true + + turbo@2.7.2: + optionalDependencies: + turbo-darwin-64: 2.7.2 + turbo-darwin-arm64: 2.7.2 + turbo-linux-64: 2.7.2 + turbo-linux-arm64: 2.7.2 + turbo-windows-64: 2.7.2 + turbo-windows-arm64: 2.7.2 + typescript@5.9.3: {} ufo@1.6.1: {} diff --git a/turbo.json b/turbo.json new file mode 100644 index 00000000..27956396 --- /dev/null +++ b/turbo.json @@ -0,0 +1,31 @@ +{ + "$schema": "https://turbo.build/schema.json", + "tasks": { + "build": { + "dependsOn": ["^build"], + "outputs": ["dist/**", ".vitepress/dist/**"] + }, + "dev": { + "dependsOn": ["^build"], + "cache": false, + "persistent": true + }, + "test": { + "dependsOn": ["^build"] + }, + "test:node": { + "dependsOn": ["^build"] + }, + "test:browser": { + "dependsOn": ["^build"] + }, + "test:react": { + "dependsOn": ["^build"] + }, + "typecheck": { + "dependsOn": ["^build"] + }, + "lint": {}, + "format": {} + } +} From 491804774b312bd8de45a6afb69bb63fefe928be Mon Sep 17 00:00:00 2001 From: coji Date: Tue, 30 Dec 2025 16:12:19 +0900 Subject: [PATCH 035/101] feat(durably-react): add autoResume option and improve React example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add autoResume option to useJob hook (default: true) to automatically resume tracking pending/running jobs after page reload - Refactor Dashboard to use useDurably hook and subscribe to events for real-time updates - Improve React example layout with responsive grid (2-column desktop, 1-column mobile) - Simplify App.tsx by consolidating state management 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/react/index.html | 15 +- examples/react/src/App.tsx | 249 ++++++++++---------- examples/react/src/Dashboard.tsx | 34 ++- examples/react/src/styles.ts | 2 - packages/durably-react/src/hooks/use-job.ts | 38 ++- 5 files changed, 198 insertions(+), 140 deletions(-) diff --git a/examples/react/index.html b/examples/react/index.html index 6baf955f..304a49e7 100644 --- a/examples/react/index.html +++ b/examples/react/index.html @@ -10,9 +10,8 @@ font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif; - max-width: 640px; - margin: 0 auto; - padding: 40px 20px; + margin: 0; + padding: 0; background: #f8fafc; color: #1e293b; line-height: 1.5; @@ -188,6 +187,16 @@ content: 'Output will appear here...'; color: #64748b; } + .main-grid { + display: grid; + grid-template-columns: 1fr 1fr; + gap: 2rem; + } + @media (max-width: 800px) { + .main-grid { + grid-template-columns: 1fr; + } + } diff --git a/examples/react/src/App.tsx b/examples/react/src/App.tsx index c2cb65b6..01913c81 100644 --- a/examples/react/src/App.tsx +++ b/examples/react/src/App.tsx @@ -15,6 +15,7 @@ import { } from '@coji/durably-react' import { useState } from 'react' import { SQLocalKysely } from 'sqlocal/kysely' +import { Dashboard } from './Dashboard' import { processImageJob } from './jobs/processImage' import { styles } from './styles' @@ -25,7 +26,7 @@ const SOURCE_CODE = `${GITHUB_REPO}/tree/main/examples/react` // SQLocal instance for database operations const sqlocal = new SQLocalKysely('example.sqlite3') -// Durably configuration (defined outside component to maintain stable reference) +// Durably configuration const dialectFactory = () => sqlocal.dialect const durablyOptions = { pollingInterval: 100, @@ -33,21 +34,11 @@ const durablyOptions = { staleThreshold: 3000, } -function Demo() { +function AppContent() { + const [showInfo, setShowInfo] = useState(false) const { durably } = useDurably() - const { - trigger, - status, - output, - error, - progress, - logs, - isRunning, - isCompleted, - isFailed, - isReady, - reset, - } = useJob(processImageJob) + const { trigger, status, output, error, progress, logs, isRunning, isReady } = + useJob(processImageJob) const handleRun = async () => { await trigger({ filename: 'photo.jpg', width: 800 }) @@ -61,18 +52,79 @@ function Demo() { location.reload() } - const statusText = isRunning - ? 'Running...' - : isCompleted - ? '✓ Completed' - : isFailed - ? '✗ Failed' - : isReady - ? 'Ready' - : 'Initializing...' + const statusText = + status === 'running' + ? 'Running...' + : status === 'completed' + ? '✓ Completed' + : status === 'failed' + ? '✗ Failed' + : status === 'pending' + ? 'Pending...' + : isReady + ? 'Ready' + : 'Initializing...' return ( - <> +
+
+

Durably React Example

+
+ + GitHub + + | + + Source Code + + | + +
+
+ + {showInfo && ( +
+

+ This example uses @coji/durably-react for seamless + React integration: +

+
    +
  • + DurablyProvider - Context provider with auto + migration and worker start +
    • +
  • + useJob - Hook for triggering jobs and real-time + status updates +
    • +
  • + useDurably - Direct access to Durably instance +
    • +
+
+ )} +
-
-
+
- Status: {statusText} -
- {status && ( -
- Run status: {status} +

Job Status

+
+
+ Status: {statusText} +
+ {status && ( +
+ Run status: {status} +
+ )} + {progress && ( +
+ Progress: {progress.current} + {progress.total ? `/${progress.total}` : ''}{' '} + {progress.message || ''} +
+ )}
- )} - {progress && ( -
- Progress: {progress.current} - {progress.total ? `/${progress.total}` : ''}{' '} - {progress.message || ''} -
- )} -
- {output && ( - 
-          {JSON.stringify(output, null, 2)}
-
- )} + {output && ( + 
+              {JSON.stringify(output, null, 2)}
+
+ )} + + {error && 
{error}
} + + {logs.length > 0 && ( +
+ Logs: +
    + {logs.map((log: LogEntry) => ( +
  • + [{log.level}] {log.message} +
    • + ))} +
+
+ )} +
- {error && 
{error}
} - - {logs.length > 0 && ( -
- Logs: -
    - {logs.map((log: LogEntry) => ( -
  • - [{log.level}] {log.message} -
    • - ))} -
+
+
- )} - +
+
) } export function App() { - const [showInfo, setShowInfo] = useState(false) - return ( -
-
-

Durably React Example

-
- - GitHub - - | - - Source Code - - | - -
-
- - {showInfo && ( -
-

- This example uses @coji/durably-react for seamless - React integration: -

-
    -
  • - DurablyProvider - Context provider with auto - migration and worker start -
    • -
  • - useJob - Hook for triggering jobs and real-time - status updates -
    • -
  • - useDurably - Direct access to Durably instance -
    • -
-
- )} - - -
+ ) } diff --git a/examples/react/src/Dashboard.tsx b/examples/react/src/Dashboard.tsx index 00789161..6b875ff1 100644 --- a/examples/react/src/Dashboard.tsx +++ b/examples/react/src/Dashboard.tsx @@ -4,7 +4,8 @@ * Displays run history with status, details, and action buttons. */ -import type { Durably, Run } from '@coji/durably' +import type { Run } from '@coji/durably' +import { useDurably } from '@coji/durably-react' import { useCallback, useEffect, useState } from 'react' // Styles @@ -81,12 +82,8 @@ const styles = { }, } -interface DashboardProps { - durably: Durably - onMount: (refresh: () => void) => void -} - -export function Dashboard({ durably, onMount }: DashboardProps) { +export function Dashboard() { + const { durably } = useDurably() const [runs, setRuns] = useState([]) const [selectedRun, setSelectedRun] = useState(null) const [steps, setSteps] = useState< @@ -94,16 +91,32 @@ export function Dashboard({ durably, onMount }: DashboardProps) { >([]) const refresh = useCallback(async () => { + if (!durably) return const data = await durably.getRuns({ limit: 20 }) setRuns(data) }, [durably]) + // Initial fetch and subscribe to run events for real-time updates useEffect(() => { + if (!durably) return + refresh() - onMount(refresh) - }, [refresh, onMount]) + + const unsubscribes = [ + durably.on('run:start', refresh), + durably.on('run:complete', refresh), + durably.on('run:fail', refresh), + ] + + return () => { + for (const unsubscribe of unsubscribes) { + unsubscribe() + } + } + }, [durably, refresh]) const showDetails = async (runId: string) => { + if (!durably) return const run = await durably.getRun(runId) if (run) { setSelectedRun(run) @@ -115,16 +128,19 @@ export function Dashboard({ durably, onMount }: DashboardProps) { } const handleRetry = async (runId: string) => { + if (!durably) return await durably.retry(runId) refresh() } const handleCancel = async (runId: string) => { + if (!durably) return await durably.cancel(runId) refresh() } const handleDelete = async (runId: string) => { + if (!durably) return await durably.deleteRun(runId) setSelectedRun(null) refresh() diff --git a/examples/react/src/styles.ts b/examples/react/src/styles.ts index e9cb7061..3cb095d6 100644 --- a/examples/react/src/styles.ts +++ b/examples/react/src/styles.ts @@ -6,8 +6,6 @@ export const styles = { container: { padding: '2rem', fontFamily: 'system-ui', - maxWidth: '800px', - margin: '0 auto', }, header: { display: 'flex', diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts index 8e0f207f..07c3e386 100644 --- a/packages/durably-react/src/hooks/use-job.ts +++ b/packages/durably-react/src/hooks/use-job.ts @@ -8,6 +8,12 @@ export interface UseJobOptions { * Initial Run ID to subscribe to (for reconnection scenarios) */ initialRunId?: string + /** + * Automatically resume tracking any pending or running job on initialization. + * If a pending or running run exists for this job, the hook will subscribe to it. + * @default true + */ + autoResume?: boolean } export interface UseJobResult { @@ -170,12 +176,42 @@ export function useJob< }) } + // Auto-resume: find any pending or running runs for this job (default: true) + if (options?.autoResume !== false && !options?.initialRunId) { + ;(async () => { + // First check for running runs + const runningRuns = await jobHandle.getRuns({ status: 'running' }) + if (runningRuns.length > 0) { + const run = runningRuns[0] + setCurrentRunId(run.id) + currentRunIdRef.current = run.id + setStatus(run.status as RunStatus) + return + } + + // Then check for pending runs + const pendingRuns = await jobHandle.getRuns({ status: 'pending' }) + if (pendingRuns.length > 0) { + const run = pendingRuns[0] + setCurrentRunId(run.id) + currentRunIdRef.current = run.id + setStatus(run.status as RunStatus) + } + })() + } + return () => { for (const unsubscribe of unsubscribes) { unsubscribe() } } - }, [durably, isDurablyReady, jobDefinition, options?.initialRunId]) + }, [ + durably, + isDurablyReady, + jobDefinition, + options?.initialRunId, + options?.autoResume, + ]) // Update state when currentRunId changes (for initialRunId scenario) useEffect(() => { From 39ba8159ae47b13ef541d854da7ae716303c5b4f Mon Sep 17 00:00:00 2001 From: coji Date: Tue, 30 Dec 2025 16:23:37 +0900 Subject: [PATCH 036/101] feat(durably-react): improve job tracking and add pagination MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Allow triggering jobs while one is running (queue multiple jobs) - Auto-switch to tracking running job via run:start event - Fix currentRunIdRef sync issue in trigger function - Add pagination to Dashboard (10 items per page) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/react/src/App.tsx | 2 +- examples/react/src/Dashboard.tsx | 41 +++++++++++++++++++-- packages/durably-react/src/hooks/use-job.ts | 13 ++++++- 3 files changed, 51 insertions(+), 5 deletions(-) diff --git a/examples/react/src/App.tsx b/examples/react/src/App.tsx index 01913c81..5504d29f 100644 --- a/examples/react/src/App.tsx +++ b/examples/react/src/App.tsx @@ -129,7 +129,7 @@ function AppContent() { diff --git a/examples/react/src/Dashboard.tsx b/examples/react/src/Dashboard.tsx index 6b875ff1..a1beccf5 100644 --- a/examples/react/src/Dashboard.tsx +++ b/examples/react/src/Dashboard.tsx @@ -82,6 +82,8 @@ const styles = { }, } +const PAGE_SIZE = 10 + export function Dashboard() { const { durably } = useDurably() const [runs, setRuns] = useState([]) @@ -89,12 +91,15 @@ export function Dashboard() { const [steps, setSteps] = useState< { index: number; name: string; status: string }[] >([]) + const [page, setPage] = useState(0) + const [hasMore, setHasMore] = useState(false) const refresh = useCallback(async () => { if (!durably) return - const data = await durably.getRuns({ limit: 20 }) - setRuns(data) - }, [durably]) + const data = await durably.getRuns({ limit: PAGE_SIZE + 1, offset: page * PAGE_SIZE }) + setHasMore(data.length > PAGE_SIZE) + setRuns(data.slice(0, PAGE_SIZE)) + }, [durably, page]) // Initial fetch and subscribe to run events for real-time updates useEffect(() => { @@ -246,6 +251,36 @@ export function Dashboard() { + {(page > 0 || hasMore) && ( +
+ + Page {page + 1} + +
+ )} + {selectedRun && (

Run Details

diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts index 07c3e386..90170149 100644 --- a/packages/durably-react/src/hooks/use-job.ts +++ b/packages/durably-react/src/hooks/use-job.ts @@ -115,8 +115,17 @@ export function useJob< unsubscribes.push( durably.on('run:start', (event) => { - if (event.runId !== currentRunIdRef.current) return + // Check if this is a run for our job + if (event.jobName !== jobDefinition.name) return + // Switch to tracking the running job + setCurrentRunId(event.runId) + currentRunIdRef.current = event.runId setStatus('running') + // Reset output/error when switching to a new run + setOutput(null) + setError(null) + setLogs([]) + setProgress(null) }), ) @@ -248,6 +257,7 @@ export function useJob< const run = await jobHandle.trigger(input) setCurrentRunId(run.id) + currentRunIdRef.current = run.id setStatus('pending') return { runId: run.id } @@ -270,6 +280,7 @@ export function useJob< const run = await jobHandle.trigger(input) setCurrentRunId(run.id) + currentRunIdRef.current = run.id setStatus('pending') // Wait for completion From e7151c09bda26786d484b25398d4445f6d41af7d Mon Sep 17 00:00:00 2001 From: coji Date: Tue, 30 Dec 2025 16:35:46 +0900 Subject: [PATCH 037/101] feat(durably-react): add useRuns hook and followLatest option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add useRuns hook for paginated run listing with real-time updates - Add followLatest option to useJob (default: true) to control auto-tracking - Export type-safe client factories (createDurablyClient, createJobHooks) - Improve client.ts exports organization 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- packages/durably-react/src/client.ts | 15 ++ packages/durably-react/src/hooks/use-job.ts | 18 ++- packages/durably-react/src/hooks/use-runs.ts | 161 +++++++++++++++++++ packages/durably-react/src/index.ts | 2 + 4 files changed, 195 insertions(+), 1 deletion(-) create mode 100644 packages/durably-react/src/hooks/use-runs.ts diff --git a/packages/durably-react/src/client.ts b/packages/durably-react/src/client.ts index c3c821ca..10c7bb8f 100644 --- a/packages/durably-react/src/client.ts +++ b/packages/durably-react/src/client.ts @@ -1,6 +1,21 @@ // @coji/durably-react/client - Server-connected mode // This entry point is for connecting to a remote Durably server via HTTP/SSE +// Type-safe client factories (recommended) +export { createDurablyClient } from './client/create-durably-client' +export type { + CreateDurablyClientOptions, + DurablyClient, + JobClient, +} from './client/create-durably-client' + +export { createJobHooks } from './client/create-job-hooks' +export type { + CreateJobHooksOptions, + JobHooks, +} from './client/create-job-hooks' + +// Low-level hooks (for advanced use cases) export { useJob } from './client/use-job' export type { UseJobClientOptions, UseJobClientResult } from './client/use-job' diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts index 90170149..a3a25ed0 100644 --- a/packages/durably-react/src/hooks/use-job.ts +++ b/packages/durably-react/src/hooks/use-job.ts @@ -14,6 +14,13 @@ export interface UseJobOptions { * @default true */ autoResume?: boolean + /** + * Automatically switch to tracking the latest running job when a new run starts. + * When true, the hook will update to track any new run for this job as soon as it starts running. + * When false, the hook will only track the run that was triggered or explicitly set. + * @default true + */ + followLatest?: boolean } export interface UseJobResult { @@ -117,7 +124,15 @@ export function useJob< durably.on('run:start', (event) => { // Check if this is a run for our job if (event.jobName !== jobDefinition.name) return - // Switch to tracking the running job + + // If followLatest is disabled, only update if this is our current run + if (options?.followLatest === false) { + if (event.runId !== currentRunIdRef.current) return + setStatus('running') + return + } + + // Switch to tracking the running job (followLatest: true, default) setCurrentRunId(event.runId) currentRunIdRef.current = event.runId setStatus('running') @@ -220,6 +235,7 @@ export function useJob< jobDefinition, options?.initialRunId, options?.autoResume, + options?.followLatest, ]) // Update state when currentRunId changes (for initialRunId scenario) diff --git a/packages/durably-react/src/hooks/use-runs.ts b/packages/durably-react/src/hooks/use-runs.ts new file mode 100644 index 00000000..4e56626d --- /dev/null +++ b/packages/durably-react/src/hooks/use-runs.ts @@ -0,0 +1,161 @@ +import type { Run } from '@coji/durably' +import { useCallback, useEffect, useState } from 'react' +import { useDurably } from '../context' + +export interface UseRunsOptions { + /** + * Filter by job name + */ + jobName?: string + /** + * Filter by status + */ + status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' + /** + * Number of runs per page + * @default 10 + */ + pageSize?: number + /** + * Subscribe to real-time updates + * @default true + */ + realtime?: boolean +} + +export interface UseRunsResult { + /** + * Whether the hook is ready (Durably is initialized) + */ + isReady: boolean + /** + * List of runs for the current page + */ + runs: Run[] + /** + * Current page (0-indexed) + */ + page: number + /** + * Whether there are more pages + */ + hasMore: boolean + /** + * Whether data is being loaded + */ + isLoading: boolean + /** + * Go to the next page + */ + nextPage: () => void + /** + * Go to the previous page + */ + prevPage: () => void + /** + * Go to a specific page + */ + goToPage: (page: number) => void + /** + * Refresh the current page + */ + refresh: () => Promise +} + +/** + * Hook for listing runs with pagination and real-time updates. + * + * @example + * ```tsx + * function Dashboard() { + * const { runs, page, hasMore, nextPage, prevPage, isLoading } = useRuns({ + * pageSize: 20, + * }) + * + * return ( + *
+ * {runs.map(run => ( + *
{run.jobName}: {run.status}
+ * ))} + * + * + *
+ * ) + * } + * ``` + */ +export function useRuns(options?: UseRunsOptions): UseRunsResult { + const { durably, isReady: isDurablyReady } = useDurably() + const pageSize = options?.pageSize ?? 10 + const realtime = options?.realtime ?? true + + const [runs, setRuns] = useState([]) + const [page, setPage] = useState(0) + const [hasMore, setHasMore] = useState(false) + const [isLoading, setIsLoading] = useState(false) + + const refresh = useCallback(async () => { + if (!durably) return + + setIsLoading(true) + try { + const data = await durably.getRuns({ + jobName: options?.jobName, + status: options?.status, + limit: pageSize + 1, + offset: page * pageSize, + }) + setHasMore(data.length > pageSize) + setRuns(data.slice(0, pageSize)) + } finally { + setIsLoading(false) + } + }, [durably, options?.jobName, options?.status, pageSize, page]) + + // Initial fetch and subscribe to events + useEffect(() => { + if (!durably || !isDurablyReady) return + + refresh() + + if (!realtime) return + + const unsubscribes = [ + durably.on('run:start', refresh), + durably.on('run:complete', refresh), + durably.on('run:fail', refresh), + ] + + return () => { + for (const unsubscribe of unsubscribes) { + unsubscribe() + } + } + }, [durably, isDurablyReady, refresh, realtime]) + + const nextPage = useCallback(() => { + if (hasMore) { + setPage((p) => p + 1) + } + }, [hasMore]) + + const prevPage = useCallback(() => { + setPage((p) => Math.max(0, p - 1)) + }, []) + + const goToPage = useCallback((newPage: number) => { + setPage(Math.max(0, newPage)) + }, []) + + return { + isReady: isDurablyReady, + runs, + page, + hasMore, + isLoading, + nextPage, + prevPage, + goToPage, + refresh, + } +} diff --git a/packages/durably-react/src/index.ts b/packages/durably-react/src/index.ts index e39f30ea..43ea7d0f 100644 --- a/packages/durably-react/src/index.ts +++ b/packages/durably-react/src/index.ts @@ -9,4 +9,6 @@ export { useJobLogs } from './hooks/use-job-logs' export type { UseJobLogsOptions, UseJobLogsResult } from './hooks/use-job-logs' export { useJobRun } from './hooks/use-job-run' export type { UseJobRunOptions, UseJobRunResult } from './hooks/use-job-run' +export { useRuns } from './hooks/use-runs' +export type { UseRunsOptions, UseRunsResult } from './hooks/use-runs' export type { DurablyEvent, LogEntry, Progress, RunStatus } from './types' From e30ea16142b49b4e7bf90ab2d6d8967457fb6a72 Mon Sep 17 00:00:00 2001 From: coji Date: Tue, 30 Dec 2025 16:44:32 +0900 Subject: [PATCH 038/101] test(durably-react): add tests for useRuns hook and followLatest option MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add comprehensive tests for useRuns hook (pagination, filtering, real-time) - Add tests for followLatest option in useJob 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../tests/browser/use-job.test.tsx | 82 +++++ .../tests/browser/use-runs.test.tsx | 279 ++++++++++++++++++ 2 files changed, 361 insertions(+) create mode 100644 packages/durably-react/tests/browser/use-runs.test.tsx diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx index e88dde87..1f23ec70 100644 --- a/packages/durably-react/tests/browser/use-job.test.tsx +++ b/packages/durably-react/tests/browser/use-job.test.tsx @@ -296,4 +296,86 @@ describe('useJob', () => { // No errors should occur (memory leak test) await new Promise((r) => setTimeout(r, 100)) }) + + describe('followLatest option', () => { + it('switches to latest running job by default (followLatest: true)', async () => { + const slowJob = defineJob({ + name: 'slow-job', + input: z.object({ id: z.number() }), + output: z.object({ id: z.number() }), + run: async (context, payload) => { + await context.run('work', async () => { + await new Promise((r) => setTimeout(r, 200)) + }) + return { id: payload.id } + }, + }) + + const { result } = renderHook(() => useJob(slowJob), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // Trigger first job + const { runId: firstRunId } = await result.current.trigger({ id: 1 }) + + await waitFor(() => { + expect(result.current.currentRunId).toBe(firstRunId) + }) + + // Trigger second job while first is still running + const { runId: secondRunId } = await result.current.trigger({ id: 2 }) + + // Should switch to the second job when it starts running + await waitFor(() => { + expect(result.current.currentRunId).toBe(secondRunId) + }) + }) + + it('stays on current run when followLatest: false and external run starts', async () => { + // This test verifies that followLatest: false keeps tracking the current run + // even when run:start events fire (from the worker starting jobs) + const slowJob = defineJob({ + name: 'slow-job-no-follow', + input: z.object({ id: z.number() }), + output: z.object({ id: z.number() }), + run: async (context, payload) => { + await context.run('work', async () => { + await new Promise((r) => setTimeout(r, 300)) + }) + return { id: payload.id } + }, + }) + + const { result } = renderHook( + () => useJob(slowJob, { followLatest: false }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // Trigger first job + const { runId: firstRunId } = await result.current.trigger({ id: 1 }) + + // Wait for it to start running (status becomes 'running') + await waitFor(() => { + expect(result.current.status).toBe('running') + expect(result.current.currentRunId).toBe(firstRunId) + }) + + // Wait for the first run to complete - with followLatest: false, + // it should stay on firstRunId and eventually complete + await waitFor( + () => { + expect(result.current.status).toBe('completed') + expect(result.current.currentRunId).toBe(firstRunId) + }, + { timeout: 5000 }, + ) + + // Verify output is from the first job + expect(result.current.output).toEqual({ id: 1 }) + }) + }) }) diff --git a/packages/durably-react/tests/browser/use-runs.test.tsx b/packages/durably-react/tests/browser/use-runs.test.tsx new file mode 100644 index 00000000..f7f7b2e6 --- /dev/null +++ b/packages/durably-react/tests/browser/use-runs.test.tsx @@ -0,0 +1,279 @@ +/** + * useRuns Tests + * + * Test useRuns hook for browser-complete mode + */ + +import { defineJob, type Durably } from '@coji/durably' +import { renderHook, waitFor } from '@testing-library/react' +import type { ReactNode } from 'react' +import { afterEach, describe, expect, it } from 'vitest' +import { z } from 'zod' +import { DurablyProvider, useRuns } from '../../src' +import { createBrowserDialect } from '../helpers/browser-dialect' + +// Test job definition +const testJob = defineJob({ + name: 'test-job-runs', + input: z.object({ value: z.number() }), + run: async (context, payload) => { + await context.run('work', async () => { + await new Promise((r) => setTimeout(r, 50)) + return payload.value * 2 + }) + }, +}) + +describe('useRuns', () => { + const instances: Durably[] = [] + + afterEach(async () => { + for (const instance of instances) { + try { + await instance.stop() + } catch { + // Ignore errors from already stopped instances + } + } + instances.length = 0 + await new Promise((r) => setTimeout(r, 200)) + }) + + const createWrapper = + () => + ({ children }: { children: ReactNode }) => ( + createBrowserDialect()} + options={{ pollingInterval: 50 }} + onReady={(durably) => instances.push(durably)} + > + {children} + + ) + + it('returns empty runs initially', async () => { + const { result } = renderHook(() => useRuns(), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + expect(result.current.runs).toEqual([]) + expect(result.current.page).toBe(0) + expect(result.current.hasMore).toBe(false) + }) + + it('lists runs after job execution', async () => { + const { result } = renderHook(() => useRuns(), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + // Trigger a job using the durably instance directly + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + await testJobHandle.trigger({ value: 10 }) + + // Wait for runs to update + await waitFor(() => { + expect(result.current.runs.length).toBeGreaterThan(0) + }) + + expect(result.current.runs[0].jobName).toBe('test-job-runs') + }) + + it('filters by jobName', async () => { + const otherJob = defineJob({ + name: 'other-job', + input: z.object({ x: z.string() }), + run: async () => {}, + }) + + const { result } = renderHook( + () => useRuns({ jobName: 'test-job-runs' }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle, otherJobHandle } = durably.register({ + testJobHandle: testJob, + otherJobHandle: otherJob, + }) + + await testJobHandle.trigger({ value: 1 }) + await otherJobHandle.trigger({ x: 'test' }) + + await waitFor(() => { + expect(result.current.runs.length).toBe(1) + }) + + expect(result.current.runs[0].jobName).toBe('test-job-runs') + }) + + it('filters by status', async () => { + const { result } = renderHook( + () => useRuns({ status: 'completed' }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + + // Trigger and wait for completion + const run = await testJobHandle.trigger({ value: 5 }) + + // Wait for run to complete + await waitFor( + async () => { + const runData = await testJobHandle.getRun(run.id) + expect(runData?.status).toBe('completed') + }, + { timeout: 5000 }, + ) + + // Refresh to get completed runs + await result.current.refresh() + + await waitFor(() => { + expect(result.current.runs.length).toBe(1) + expect(result.current.runs[0].status).toBe('completed') + }) + }) + + it('supports pagination', async () => { + const { result } = renderHook( + () => useRuns({ pageSize: 2 }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + + // Create 3 runs + await testJobHandle.trigger({ value: 1 }) + await testJobHandle.trigger({ value: 2 }) + await testJobHandle.trigger({ value: 3 }) + + await waitFor(() => { + expect(result.current.runs.length).toBe(2) + expect(result.current.hasMore).toBe(true) + }) + + // Go to next page + result.current.nextPage() + + await waitFor(() => { + expect(result.current.page).toBe(1) + expect(result.current.runs.length).toBe(1) + expect(result.current.hasMore).toBe(false) + }) + + // Go back + result.current.prevPage() + + await waitFor(() => { + expect(result.current.page).toBe(0) + }) + }) + + it('goToPage navigates directly', async () => { + const { result } = renderHook( + () => useRuns({ pageSize: 1 }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + + // Create 3 runs + await testJobHandle.trigger({ value: 1 }) + await testJobHandle.trigger({ value: 2 }) + await testJobHandle.trigger({ value: 3 }) + + await waitFor(() => { + expect(result.current.runs.length).toBe(1) + }) + + result.current.goToPage(2) + + await waitFor(() => { + expect(result.current.page).toBe(2) + }) + }) + + it('refresh reloads data', async () => { + const { result } = renderHook(() => useRuns(), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + + // Initially empty + expect(result.current.runs).toEqual([]) + + await testJobHandle.trigger({ value: 42 }) + + // Manually refresh + await result.current.refresh() + + await waitFor(() => { + expect(result.current.runs.length).toBe(1) + }) + }) + + it('updates in real-time by default', async () => { + const { result } = renderHook(() => useRuns(), { + wrapper: createWrapper(), + }) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + + expect(result.current.runs.length).toBe(0) + + // Trigger job - should update automatically via events + await testJobHandle.trigger({ value: 99 }) + + await waitFor(() => { + expect(result.current.runs.length).toBe(1) + }) + }) + + it('disables real-time updates when realtime=false', async () => { + const { result } = renderHook( + () => useRuns({ realtime: false }), + { wrapper: createWrapper() }, + ) + + await waitFor(() => expect(result.current.isReady).toBe(true)) + + const durably = instances[0] + const { testJobHandle } = durably.register({ testJobHandle: testJob }) + + await testJobHandle.trigger({ value: 77 }) + + // Wait a bit - should NOT update automatically + await new Promise((r) => setTimeout(r, 100)) + expect(result.current.runs.length).toBe(0) + + // Manual refresh should work + await result.current.refresh() + + await waitFor(() => { + expect(result.current.runs.length).toBe(1) + }) + }) +}) From e1f69cbe2a2838ba5311a1bb379e0c475c5ec06e Mon Sep 17 00:00:00 2001 From: coji Date: Tue, 30 Dec 2025 17:10:00 +0900 Subject: [PATCH 039/101] test(durably-react): add tests for client factories and coverage config MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add tests for createDurablyClient factory (7 tests) - Add tests for createJobHooks factory (8 tests) - Add coverage configuration for vitest - Install @vitest/coverage-v8 for coverage reporting - Fix type constraints in createJobHooks to accept any JobDefinition Coverage improvement: - createDurablyClient: 0% → 100% - createJobHooks: 0% → 100% - Overall: 83.88% → 86.7% statements 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- package.json | 1 + .../src/client/create-job-hooks.ts | 3 +- .../client/create-durably-client.test.tsx | 203 +++++++++++++ .../tests/client/create-job-hooks.test.tsx | 273 ++++++++++++++++++ .../tests/client/use-job.test.tsx | 21 ++ packages/durably-react/vitest.config.ts | 6 + packages/durably/vitest.config.ts | 6 + pnpm-lock.yaml | 131 +++++++++ 8 files changed, 643 insertions(+), 1 deletion(-) create mode 100644 packages/durably-react/tests/client/create-durably-client.test.tsx create mode 100644 packages/durably-react/tests/client/create-job-hooks.test.tsx diff --git a/package.json b/package.json index 0d480619..94b40b15 100644 --- a/package.json +++ b/package.json @@ -23,6 +23,7 @@ "devDependencies": { "@biomejs/biome": "^2.3.10", "@types/node": "^25.0.3", + "@vitest/coverage-v8": "4.0.16", "cc-hooks-ts": "2.0.70", "tsx": "^4.21.0", "turbo": "2.7.2", diff --git a/packages/durably-react/src/client/create-job-hooks.ts b/packages/durably-react/src/client/create-job-hooks.ts index b5a95be1..772e2050 100644 --- a/packages/durably-react/src/client/create-job-hooks.ts +++ b/packages/durably-react/src/client/create-job-hooks.ts @@ -87,7 +87,8 @@ export interface JobHooks { * ``` */ export function createJobHooks< - TJob extends JobDefinition, + // biome-ignore lint/suspicious/noExplicitAny: TJob needs to accept any JobDefinition + TJob extends JobDefinition, >( options: CreateJobHooksOptions, ): JobHooks, InferOutput> { diff --git a/packages/durably-react/tests/client/create-durably-client.test.tsx b/packages/durably-react/tests/client/create-durably-client.test.tsx new file mode 100644 index 00000000..663a0ff6 --- /dev/null +++ b/packages/durably-react/tests/client/create-durably-client.test.tsx @@ -0,0 +1,203 @@ +/** + * createDurablyClient Tests + * + * Test the type-safe client factory + */ + +import { act, renderHook, waitFor } from '@testing-library/react' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { createDurablyClient } from '../../src/client/create-durably-client' +import { + createMockEventSource, + type MockEventSourceConstructor, +} from './mock-event-source' + +// Mock job types for type inference testing +type MockJobs = { + [key: string]: unknown + importCsv: { + trigger: (input: { filename: string }) => Promise<{ + output: { rowCount: number } + }> + } + syncUsers: { + trigger: (input: { orgId: string }) => Promise<{ + output: { syncedCount: number } + }> + } +} + +describe('createDurablyClient', () => { + let mockEventSource: MockEventSourceConstructor + let originalEventSource: typeof EventSource + let originalFetch: typeof fetch + + beforeEach(() => { + mockEventSource = createMockEventSource() + originalEventSource = globalThis.EventSource + originalFetch = globalThis.fetch + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + }) + + afterEach(() => { + globalThis.EventSource = originalEventSource + globalThis.fetch = originalFetch + vi.restoreAllMocks() + }) + + it('creates a client with job accessors', () => { + const client = createDurablyClient({ api: '/api/durably' }) + + // Verify the proxy creates job clients on access + expect(client.importCsv).toBeDefined() + expect(client.syncUsers).toBeDefined() + expect(client.importCsv.useJob).toBeTypeOf('function') + expect(client.importCsv.useRun).toBeTypeOf('function') + expect(client.importCsv.useLogs).toBeTypeOf('function') + }) + + it('useJob triggers correct job name', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'test-run-id' }), + }) + globalThis.fetch = fetchMock + + const client = createDurablyClient({ api: '/api/durably' }) + + const { result } = renderHook(() => client.importCsv.useJob()) + + expect(result.current.isReady).toBe(true) + + await result.current.trigger({ filename: 'data.csv' }) + + expect(fetchMock).toHaveBeenCalledWith( + '/api/durably/trigger', + expect.objectContaining({ + method: 'POST', + body: JSON.stringify({ + jobName: 'importCsv', + input: { filename: 'data.csv' }, + }), + }), + ) + }) + + it('useRun subscribes to run by ID', async () => { + const client = createDurablyClient({ api: '/api/durably' }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => + client.importCsv.useRun('test-run-123'), + ) + + // Wait for EventSource to be created + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(instanceCountBefore) + }) + + // Verify SSE subscription URL - get the latest instance + const instance = mockEventSource.instances[mockEventSource.instances.length - 1] + expect(instance.url).toContain('/api/durably/subscribe?runId=test-run-123') + + // Emit complete event + act(() => { + mockEventSource.emit({ + type: 'run:complete', + runId: 'test-run-123', + output: { rowCount: 42 }, + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('completed') + expect(result.current.output).toEqual({ rowCount: 42 }) + }) + }) + + it('useLogs subscribes to logs from run', async () => { + const client = createDurablyClient({ api: '/api/durably' }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => + client.importCsv.useLogs('log-run-123', { maxLogs: 50 }), + ) + + // Wait for EventSource to be created + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(instanceCountBefore) + }) + + // Emit log event + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'log-run-123', + level: 'info', + message: 'Processing row 1', + data: null, + }) + }) + + await waitFor(() => { + expect(result.current.logs.length).toBe(1) + expect(result.current.logs[0].message).toBe('Processing row 1') + }) + }) + + it('different jobs use different job names', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'run-1' }), + }) + globalThis.fetch = fetchMock + + const client = createDurablyClient({ api: '/api/durably' }) + + // Test importCsv + const { result: importResult } = renderHook(() => client.importCsv.useJob()) + await importResult.current.trigger({ filename: 'test.csv' }) + + expect(fetchMock).toHaveBeenLastCalledWith( + '/api/durably/trigger', + expect.objectContaining({ + body: expect.stringContaining('"jobName":"importCsv"'), + }), + ) + + // Test syncUsers + const { result: syncResult } = renderHook(() => client.syncUsers.useJob()) + await syncResult.current.trigger({ orgId: 'org-123' }) + + expect(fetchMock).toHaveBeenLastCalledWith( + '/api/durably/trigger', + expect.objectContaining({ + body: expect.stringContaining('"jobName":"syncUsers"'), + }), + ) + }) + + it('useRun with null runId does not subscribe', async () => { + const client = createDurablyClient({ api: '/api/durably' }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => client.importCsv.useRun(null)) + + // Wait a bit to ensure no NEW EventSource is created + await new Promise((r) => setTimeout(r, 50)) + expect(mockEventSource.instances.length).toBe(instanceCountBefore) + expect(result.current.status).toBeNull() + }) + + it('useLogs with null runId does not subscribe', async () => { + const client = createDurablyClient({ api: '/api/durably' }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => client.importCsv.useLogs(null)) + + // Wait a bit to ensure no NEW EventSource is created + await new Promise((r) => setTimeout(r, 50)) + expect(mockEventSource.instances.length).toBe(instanceCountBefore) + expect(result.current.logs).toEqual([]) + }) +}) diff --git a/packages/durably-react/tests/client/create-job-hooks.test.tsx b/packages/durably-react/tests/client/create-job-hooks.test.tsx new file mode 100644 index 00000000..ed199e30 --- /dev/null +++ b/packages/durably-react/tests/client/create-job-hooks.test.tsx @@ -0,0 +1,273 @@ +/** + * createJobHooks Tests + * + * Test the type-safe job hooks factory + */ + +import { defineJob } from '@coji/durably' +import { act, renderHook, waitFor } from '@testing-library/react' +import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest' +import { z } from 'zod' +import { createJobHooks } from '../../src/client/create-job-hooks' +import { + createMockEventSource, + type MockEventSourceConstructor, +} from './mock-event-source' + +// Define a mock job for type inference +const importCsvJob = defineJob({ + name: 'import-csv', + input: z.object({ filename: z.string(), delimiter: z.string().optional() }), + output: z.object({ rowCount: z.number(), errors: z.number() }), + run: async () => ({ rowCount: 100, errors: 0 }), +}) + +describe('createJobHooks', () => { + let mockEventSource: MockEventSourceConstructor + let originalEventSource: typeof EventSource + let originalFetch: typeof fetch + + beforeEach(() => { + mockEventSource = createMockEventSource() + originalEventSource = globalThis.EventSource + originalFetch = globalThis.fetch + globalThis.EventSource = mockEventSource as unknown as typeof EventSource + }) + + afterEach(() => { + globalThis.EventSource = originalEventSource + globalThis.fetch = originalFetch + vi.restoreAllMocks() + }) + + it('creates hooks object with useJob, useRun, useLogs', () => { + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + expect(hooks.useJob).toBeTypeOf('function') + expect(hooks.useRun).toBeTypeOf('function') + expect(hooks.useLogs).toBeTypeOf('function') + }) + + it('useJob triggers with correct job name', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'csv-run-id' }), + }) + globalThis.fetch = fetchMock + + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const { result } = renderHook(() => hooks.useJob()) + + expect(result.current.isReady).toBe(true) + + await result.current.trigger({ filename: 'data.csv' }) + + expect(fetchMock).toHaveBeenCalledWith( + '/api/durably/trigger', + expect.objectContaining({ + method: 'POST', + body: JSON.stringify({ + jobName: 'import-csv', + input: { filename: 'data.csv' }, + }), + }), + ) + }) + + it('useJob handles completion with typed output', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: true, + json: () => Promise.resolve({ runId: 'typed-run-id' }), + }) + globalThis.fetch = fetchMock + + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const { result } = renderHook(() => hooks.useJob()) + + await result.current.trigger({ filename: 'test.csv' }) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(0) + }) + + act(() => { + mockEventSource.emit({ + type: 'run:complete', + runId: 'typed-run-id', + output: { rowCount: 500, errors: 2 }, + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('completed') + expect(result.current.output).toEqual({ rowCount: 500, errors: 2 }) + // Type should be inferred correctly + expect(result.current.output?.rowCount).toBe(500) + expect(result.current.output?.errors).toBe(2) + }) + }) + + it('useRun subscribes to existing run', async () => { + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => hooks.useRun('existing-run-123')) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(instanceCountBefore) + }) + + const instance = mockEventSource.instances[mockEventSource.instances.length - 1] + expect(instance.url).toContain( + '/api/durably/subscribe?runId=existing-run-123', + ) + + act(() => { + mockEventSource.emit({ + type: 'run:start', + runId: 'existing-run-123', + }) + }) + + await waitFor(() => { + expect(result.current.status).toBe('running') + expect(result.current.isRunning).toBe(true) + }) + }) + + it('useLogs collects logs from run', async () => { + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => hooks.useLogs('logs-run-123')) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(instanceCountBefore) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'logs-run-123', + level: 'info', + message: 'Starting import', + data: null, + }) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'logs-run-123', + level: 'warn', + message: 'Skipping invalid row', + data: { row: 5 }, + }) + }) + + await waitFor(() => { + expect(result.current.logs.length).toBe(2) + expect(result.current.logs[0].level).toBe('info') + expect(result.current.logs[1].level).toBe('warn') + }) + }) + + it('useLogs respects maxLogs option', async () => { + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => + hooks.useLogs('max-logs-run', { maxLogs: 2 }), + ) + + await waitFor(() => { + expect(mockEventSource.instances.length).toBeGreaterThan(instanceCountBefore) + }) + + // Emit 3 logs + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'max-logs-run', + level: 'info', + message: 'Log 1', + data: null, + }) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'max-logs-run', + level: 'info', + message: 'Log 2', + data: null, + }) + }) + + act(() => { + mockEventSource.emit({ + type: 'log:write', + runId: 'max-logs-run', + level: 'info', + message: 'Log 3', + data: null, + }) + }) + + await waitFor(() => { + // Should only keep last 2 logs due to maxLogs: 2 + expect(result.current.logs.length).toBe(2) + expect(result.current.logs[0].message).toBe('Log 2') + expect(result.current.logs[1].message).toBe('Log 3') + }) + }) + + it('useRun with null runId does not subscribe', async () => { + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => hooks.useRun(null)) + + await new Promise((r) => setTimeout(r, 50)) + expect(mockEventSource.instances.length).toBe(instanceCountBefore) + expect(result.current.status).toBeNull() + }) + + it('useLogs with null runId does not subscribe', async () => { + const hooks = createJobHooks({ + api: '/api/durably', + jobName: 'import-csv', + }) + + const instanceCountBefore = mockEventSource.instances.length + const { result } = renderHook(() => hooks.useLogs(null)) + + await new Promise((r) => setTimeout(r, 50)) + expect(mockEventSource.instances.length).toBe(instanceCountBefore) + expect(result.current.logs).toEqual([]) + }) +}) diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx index ddd9ea0a..db205fbd 100644 --- a/packages/durably-react/tests/client/use-job.test.tsx +++ b/packages/durably-react/tests/client/use-job.test.tsx @@ -313,4 +313,25 @@ describe('useJob (client)', () => { 'Job not found', ) }) + + it('throws on fetch error with empty text', async () => { + const fetchMock = vi.fn().mockResolvedValue({ + ok: false, + status: 500, + text: () => Promise.resolve(''), + }) + globalThis.fetch = fetchMock + + const { result } = renderHook(() => + useJob({ api: '/api/durably', jobName: 'test-job' }), + ) + + await expect(result.current.trigger({ input: 'test' })).rejects.toThrow( + 'HTTP 500', + ) + }) + + // Note: triggerAndWait tests are difficult to test with the polling-based implementation + // because the hook needs to re-render to see the updated subscription.status. + // The triggerAndWait function is covered indirectly through the browser tests. }) diff --git a/packages/durably-react/vitest.config.ts b/packages/durably-react/vitest.config.ts index 5380273f..0e689476 100644 --- a/packages/durably-react/vitest.config.ts +++ b/packages/durably-react/vitest.config.ts @@ -26,6 +26,12 @@ export default defineConfig({ instances: [{ browser: 'chromium' }], headless: true, }, + coverage: { + provider: 'v8', + include: ['src/**/*.ts', 'src/**/*.tsx'], + exclude: ['src/**/*.d.ts', 'src/index.ts', 'src/client.ts'], + reporter: ['text', 'text-summary'], + }, }, optimizeDeps: { exclude: ['sqlocal'], diff --git a/packages/durably/vitest.config.ts b/packages/durably/vitest.config.ts index 280d4043..07994033 100644 --- a/packages/durably/vitest.config.ts +++ b/packages/durably/vitest.config.ts @@ -3,5 +3,11 @@ import { defineConfig } from 'vitest/config' export default defineConfig({ test: { include: ['tests/node/**/*.test.ts'], + coverage: { + provider: 'v8', + include: ['src/**/*.ts'], + exclude: ['src/**/*.d.ts', 'src/index.ts'], + reporter: ['text', 'text-summary'], + }, }, }) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 2c2c09ab..6ab1dc93 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -14,6 +14,9 @@ importers: '@types/node': specifier: ^25.0.3 version: 25.0.3 + '@vitest/coverage-v8': + specifier: 4.0.16 + version: 4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16) cc-hooks-ts: specifier: 2.0.70 version: 2.0.70(typescript@5.9.3)(zod@4.2.1) @@ -463,6 +466,10 @@ packages: resolution: {integrity: sha512-qQ5m48eI/MFLQ5PxQj4PFaprjyCTLI37ElWMmNs0K8Lk3dVeOdNpB3ks8jc7yM5CDmVC73eMVk/trk3fgmrUpA==} engines: {node: '>=6.9.0'} + '@bcoe/v8-coverage@1.0.2': + resolution: {integrity: sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==} + engines: {node: '>=18'} + '@biomejs/biome@2.3.10': resolution: {integrity: sha512-/uWSUd1MHX2fjqNLHNL6zLYWBbrJeG412/8H7ESuK8ewoRoMPUgHDebqKrPTx/5n6f17Xzqc9hdg3MEqA5hXnQ==} engines: {node: '>=14.21.3'} @@ -1342,6 +1349,15 @@ packages: peerDependencies: vitest: 4.0.16 + '@vitest/coverage-v8@4.0.16': + resolution: {integrity: sha512-2rNdjEIsPRzsdu6/9Eq0AYAzYdpP6Bx9cje9tL3FE5XzXRQF1fNU9pe/1yE8fCrS0HD+fBtt6gLPh6LI57tX7A==} + peerDependencies: + '@vitest/browser': 4.0.16 + vitest: 4.0.16 + peerDependenciesMeta: + '@vitest/browser': + optional: true + '@vitest/expect@4.0.16': resolution: {integrity: sha512-eshqULT2It7McaJkQGLkPjPjNph+uevROGuIMJdG3V+0BSR2w9u6J9Lwu+E8cK5TETlfou8GRijhafIMhXsimA==} @@ -1490,6 +1506,9 @@ packages: resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==} engines: {node: '>=12'} + ast-v8-to-istanbul@0.3.10: + resolution: {integrity: sha512-p4K7vMz2ZSk3wN8l5o3y2bJAoZXT3VuJI5OLTATY/01CYWumWvwkUw0SqDBnNq6IiTO3qDa1eSQDibAV8g7XOQ==} + baseline-browser-mapping@2.9.11: resolution: {integrity: sha512-Sg0xJUNDU1sJNGdfGWhVHX0kkZ+HWcvmVymJbj6NSgZZmW/8S9Y2HQ5euytnIgakgxN6papOAWiwDo1ctFDcoQ==} hasBin: true @@ -1692,6 +1711,10 @@ packages: get-tsconfig@4.13.0: resolution: {integrity: sha512-1VKTZJCwBrvbd+Wn3AOgQP/2Av+TfTCOlE4AcRJE72W1ksZXbAx8PPBR9RzgTeSPzlPMHrbANMH3LbltH73wxQ==} + has-flag@4.0.0: + resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==} + engines: {node: '>=8'} + hast-util-to-html@9.0.5: resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==} @@ -1705,6 +1728,9 @@ packages: resolution: {integrity: sha512-Y22oTqIU4uuPgEemfz7NDJz6OeKf12Lsu+QC+s3BVpda64lTiMYCyGwg5ki4vFxkMwQdeZDl2adZoqUgdFuTgQ==} engines: {node: '>=18'} + html-escaper@2.0.2: + resolution: {integrity: sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==} + html-void-elements@3.0.0: resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} @@ -1727,6 +1753,22 @@ packages: resolution: {integrity: sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==} engines: {node: '>=18'} + istanbul-lib-coverage@3.2.2: + resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==} + engines: {node: '>=8'} + + istanbul-lib-report@3.0.1: + resolution: {integrity: sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==} + engines: {node: '>=10'} + + istanbul-lib-source-maps@5.0.6: + resolution: {integrity: sha512-yg2d+Em4KizZC5niWhQaIomgf5WlL4vOOjZ5xGCmF8SnPE/mDWWXgvRExdcpCgh9lLRRa1/fSYp2ymmbJ1pI+A==} + engines: {node: '>=10'} + + istanbul-reports@3.2.0: + resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==} + engines: {node: '>=8'} + joycon@3.1.1: resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==} engines: {node: '>=10'} @@ -1737,6 +1779,9 @@ packages: js-tokens@4.0.0: resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==} + js-tokens@9.0.1: + resolution: {integrity: sha512-mxa9E9ITFOt0ban3j6L5MpjwegGz6lBQmM1IJkWeBZGcMxto50+eWdjC/52xDbS2vy0k7vIMK0Fe2wfL9OQSpQ==} + jsdom@27.3.0: resolution: {integrity: sha512-GtldT42B8+jefDUC4yUKAvsaOrH7PDHmZxZXNgF2xMmymjUbRYJvpAybZAKEmXDGTM0mCsz8duOa4vTm5AY2Kg==} engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0} @@ -1798,6 +1843,13 @@ packages: magic-string@0.30.21: resolution: {integrity: sha512-vd2F4YUyEXKGcLHoq+TEyCjxueSeHnFxyyjNp80yg0XV4vUhnDer/lvvlqM/arB5bXQN5K2/3oinyCRyx8T2CQ==} + magicast@0.5.1: + resolution: {integrity: sha512-xrHS24IxaLrvuo613F719wvOIv9xPHFWQHuvGUBmPnCA/3MQxKI3b+r7n1jAoDHmsbC5bRhTZYR77invLAxVnw==} + + make-dir@4.0.0: + resolution: {integrity: sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==} + engines: {node: '>=10'} + mark.js@8.11.1: resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} @@ -2031,6 +2083,11 @@ packages: resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==} hasBin: true + semver@7.7.3: + resolution: {integrity: sha512-SdsKMrI9TdgjdweUSR9MweHA4EJ8YxHn8DFaDisvhVlUOe4BF1tLD7GAj0lIqWVl+dPb/rExr0Btby5loQm20Q==} + engines: {node: '>=10'} + hasBin: true + shiki@2.5.0: resolution: {integrity: sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ==} @@ -2097,6 +2154,10 @@ packages: resolution: {integrity: sha512-H+ue8Zo4vJmV2nRjpx86P35lzwDT3nItnIsocgumgr0hHMQ+ZGq5vrERg9kJBo5AWGmxZDhzDo+WVIJqkB0cGA==} engines: {node: '>=16'} + supports-color@7.2.0: + resolution: {integrity: sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==} + engines: {node: '>=8'} + symbol-tree@3.2.4: resolution: {integrity: sha512-9QNk5KwDF+Bvz+PyObkmSYjI5ksVUYtjW7AU22r2NKcfLJcXp96hkDWU3+XndOsUb+AQ9QhfzfCT2O+CNWT5Tw==} @@ -2708,6 +2769,8 @@ snapshots: '@babel/helper-string-parser': 7.27.1 '@babel/helper-validator-identifier': 7.28.5 + '@bcoe/v8-coverage@1.0.2': {} + '@biomejs/biome@2.3.10': optionalDependencies: '@biomejs/cli-darwin-arm64': 2.3.10 @@ -3395,6 +3458,25 @@ snapshots: - utf-8-validate - vite + '@vitest/coverage-v8@4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16)': + dependencies: + '@bcoe/v8-coverage': 1.0.2 + '@vitest/utils': 4.0.16 + ast-v8-to-istanbul: 0.3.10 + istanbul-lib-coverage: 3.2.2 + istanbul-lib-report: 3.0.1 + istanbul-lib-source-maps: 5.0.6 + istanbul-reports: 3.2.0 + magicast: 0.5.1 + obug: 2.1.1 + std-env: 3.10.0 + tinyrainbow: 3.0.3 + vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + optionalDependencies: + '@vitest/browser': 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + transitivePeerDependencies: + - supports-color + '@vitest/expect@4.0.16': dependencies: '@standard-schema/spec': 1.1.0 @@ -3566,6 +3648,12 @@ snapshots: assertion-error@2.0.1: {} + ast-v8-to-istanbul@0.3.10: + dependencies: + '@jridgewell/trace-mapping': 0.3.31 + estree-walker: 3.0.3 + js-tokens: 9.0.1 + baseline-browser-mapping@2.9.11: {} bidi-js@1.0.3: @@ -3785,6 +3873,8 @@ snapshots: dependencies: resolve-pkg-maps: 1.0.0 + has-flag@4.0.0: {} + hast-util-to-html@9.0.5: dependencies: '@types/hast': 3.0.4 @@ -3809,6 +3899,8 @@ snapshots: dependencies: whatwg-encoding: 3.1.1 + html-escaper@2.0.2: {} + html-void-elements@3.0.0: {} http-proxy-agent@7.0.2: @@ -3833,12 +3925,35 @@ snapshots: is-what@5.5.0: {} + istanbul-lib-coverage@3.2.2: {} + + istanbul-lib-report@3.0.1: + dependencies: + istanbul-lib-coverage: 3.2.2 + make-dir: 4.0.0 + supports-color: 7.2.0 + + istanbul-lib-source-maps@5.0.6: + dependencies: + '@jridgewell/trace-mapping': 0.3.31 + debug: 4.4.3 + istanbul-lib-coverage: 3.2.2 + transitivePeerDependencies: + - supports-color + + istanbul-reports@3.2.0: + dependencies: + html-escaper: 2.0.2 + istanbul-lib-report: 3.0.1 + joycon@3.1.1: {} js-base64@3.7.8: {} js-tokens@4.0.0: {} + js-tokens@9.0.1: {} + jsdom@27.3.0: dependencies: '@acemir/cssom': 0.9.29 @@ -3920,6 +4035,16 @@ snapshots: dependencies: '@jridgewell/sourcemap-codec': 1.5.5 + magicast@0.5.1: + dependencies: + '@babel/parser': 7.28.5 + '@babel/types': 7.28.5 + source-map-js: 1.2.1 + + make-dir@4.0.0: + dependencies: + semver: 7.7.3 + mark.js@8.11.1: {} mdast-util-to-hast@13.2.1: @@ -4137,6 +4262,8 @@ snapshots: semver@6.3.1: {} + semver@7.7.3: {} + shiki@2.5.0: dependencies: '@shikijs/core': 2.5.0 @@ -4200,6 +4327,10 @@ snapshots: dependencies: copy-anything: 4.0.5 + supports-color@7.2.0: + dependencies: + has-flag: 4.0.0 + symbol-tree@3.2.4: {} tabbable@6.3.0: {} From 3a6c925f3dcd4f90e4298297b3da75927cb58894 Mon Sep 17 00:00:00 2001 From: coji Date: Tue, 30 Dec 2025 17:13:00 +0900 Subject: [PATCH 040/101] style: format button and getRuns parameters for improved readability --- examples/react/src/App.tsx | 6 +----- examples/react/src/Dashboard.tsx | 5 ++++- 2 files changed, 5 insertions(+), 6 deletions(-) diff --git a/examples/react/src/App.tsx b/examples/react/src/App.tsx index 5504d29f..665e07da 100644 --- a/examples/react/src/App.tsx +++ b/examples/react/src/App.tsx @@ -126,11 +126,7 @@ function AppContent() { )}
- + {actionData?.runId && ( +
+ Triggered:{' '} + {actionData.runId} +
+ )} + + + + {/* Run Progress */} + +
+ + {/* Right: Dashboard with Real-time SSE Updates */} + +
+
+
+ ) +} diff --git a/examples/react-router/app/routes/_index/dashboard.tsx b/examples/react-router/app/routes/_index/dashboard.tsx new file mode 100644 index 00000000..d056f411 --- /dev/null +++ b/examples/react-router/app/routes/_index/dashboard.tsx @@ -0,0 +1,87 @@ +/** + * Dashboard Component + * + * Displays run history with real-time updates via SSE and pagination. + * First page auto-subscribes to SSE for instant updates. + */ + +import { useRuns } from "@coji/durably-react/client"; + +export function Dashboard() { + const { runs, isLoading, error, page, hasMore, nextPage, prevPage } = useRuns( + { + api: "/api/durably", + jobName: "import-csv", + pageSize: 6, + } + ); + + return ( +
+
+

Dashboard

+ {isLoading && ( + Refreshing... + )} +
+ + {error &&
Error: {error}
} + + {runs.length === 0 ? ( +

No runs yet

+ ) : ( + <> +
    + {runs.map((r) => ( +
  • +
    + + {r.id.slice(0, 8)} + + - + + {new Date(r.createdAt).toLocaleString()} + +
    + + {r.status} + +
    • + ))} +
+ + {/* Pagination */} +
+ + Page {page + 1} + +
+ + )} +
+ ); +} diff --git a/examples/react-router/app/routes/_index/run-progress.tsx b/examples/react-router/app/routes/_index/run-progress.tsx new file mode 100644 index 00000000..9289ca16 --- /dev/null +++ b/examples/react-router/app/routes/_index/run-progress.tsx @@ -0,0 +1,72 @@ +/** + * RunProgress Component + * + * Displays real-time progress and result via SSE subscription. + */ + +import { useJobRun } from '@coji/durably-react/client' + +interface RunProgressProps { + runId: string | null +} + +export function RunProgress({ runId }: RunProgressProps) { + const run = useJobRun<{ imported: number; failed: number }>({ + api: '/api/durably', + runId, + }) + + // Don't render anything if no run + if (!runId) return null + + return ( + <> + {/* Pending State */} + {run.isPending && ( +
+
Waiting to start...
+
+ )} + + {/* Progress Display */} + {run.isRunning && run.progress && ( +
+
+ Progress + + {run.progress.current}/{run.progress.total} + +
+
+
+
+
{run.progress.message}
+
+ )} + + {/* Success Result */} + {run.isCompleted && run.output && ( +
+
Import Completed!
+
+ Imported: {run.output.imported} rows, Failed: {run.output.failed}{' '} + rows +
+
+ )} + + {/* Error Result */} + {run.isFailed && ( +
+
Import Failed
+
{run.error}
+
+ )} + + ) +} diff --git a/examples/react-router/app/routes/api.durably.$.ts b/examples/react-router/app/routes/api.durably.$.ts new file mode 100644 index 00000000..7596a112 --- /dev/null +++ b/examples/react-router/app/routes/api.durably.$.ts @@ -0,0 +1,22 @@ +/** + * Durably API Route (Splat) + * + * GET /api/durably/subscribe?runId=xxx - SSE stream for single run + * GET /api/durably/runs/subscribe?jobName=xxx - SSE stream for run updates + * GET /api/durably/runs - List runs + * GET /api/durably/run?runId=xxx - Get single run + * POST /api/durably/trigger - Trigger a job + * POST /api/durably/retry?runId=xxx - Retry a failed run + * POST /api/durably/cancel?runId=xxx - Cancel a run + */ + +import type { Route } from './+types/api.durably.$' +import { durablyHandler } from '~/lib/durably.server' + +export async function loader({ request }: Route.LoaderArgs) { + return durablyHandler.handle(request, '/api/durably') +} + +export async function action({ request }: Route.ActionArgs) { + return durablyHandler.handle(request, '/api/durably') +} diff --git a/examples/react-router/package.json b/examples/react-router/package.json new file mode 100644 index 00000000..87f98d7a --- /dev/null +++ b/examples/react-router/package.json @@ -0,0 +1,34 @@ +{ + "name": "example-react-router", + "private": true, + "type": "module", + "scripts": { + "build": "react-router build", + "dev": "react-router dev", + "start": "react-router-serve ./build/server/index.js", + "typecheck": "react-router typegen && tsc" + }, + "dependencies": { + "@coji/durably": "workspace:*", + "@coji/durably-react": "workspace:*", + "@libsql/kysely-libsql": "^0.4.1", + "@react-router/node": "7.11.0", + "@react-router/serve": "7.11.0", + "isbot": "^5.1.31", + "react": "^19.2.3", + "react-dom": "^19.2.3", + "react-router": "7.11.0", + "zod": "^4.2.1" + }, + "devDependencies": { + "@react-router/dev": "7.11.0", + "@tailwindcss/vite": "^4.1.13", + "@types/node": "^25.0.3", + "@types/react": "^19.2.7", + "@types/react-dom": "^19.2.3", + "tailwindcss": "^4.1.13", + "typescript": "^5.9.2", + "vite": "^7.1.7", + "vite-tsconfig-paths": "^6.0.3" + } +} \ No newline at end of file diff --git a/examples/react-router/public/favicon.ico b/examples/react-router/public/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..5dbdfcddcb14182535f6d32d1c900681321b1aa3 GIT binary patch literal 15086 zcmeI33v3ic7{|AFEmuJ-;v>ep_G*NPi6KM`qNryCe1PIJ8siIN1WZ(7qVa)RVtmC% z)Ch?tN+afMKm;5@rvorJk zcXnoOc4q51HBQnQH_jn!cAg&XI1?PlX>Kl^k8qq0;zkha`kY$Fxt#=KNJAE9CMdpW zqr4#g8`nTw191(+H4xW8Tmyru2I^3=J1G3emPxkPXA=3{vvuvse_WWSshqaqls^-m zgB7q8&Vk*aYRe?sn$n53dGH#%3y%^vxv{pL*-h0Z4bmb_(k6{FL7HWIz(V*HT#IcS z-wE{)+0x1U!RUPt3gB97%p}@oHxF4|6S*+Yw=_tLtxZ~`S=z6J?O^AfU>7qOX`JNBbV&8+bO0%@fhQitKIJ^O^ zpgIa__qD_y07t@DFlBJ)8SP_#^j{6jpaXt{U%=dx!qu=4u7^21lWEYHPPY5U3TcoQ zX_7W+lvZi>TapNk_X>k-KO%MC9iZp>1E`N34gHKd9tK&){jq2~7OsJ>!G0FzxQFw6G zm&Vb(2#-T|rM|n3>uAsG_hnbvUKFf3#ay@u4uTzia~NY%XgCHfx4^To4BDU@)HlV? z@EN=g^ymETa1sQK{kRwyE4Ax8?wT&GvaG@ASO}{&a17&^v`y z!oPdiSiia^oov(Z)QhG2&|FgE{M9_4hJROGbnj>#$~ZF$-G^|zPj*QApltKe?;u;uKHJ~-V!=VLkg7Kgct)l7u39f@%VG8e3f$N-B zAu3a4%ZGf)r+jPAYCSLt73m_J3}p>}6Tx0j(wg4vvKhP!DzgiWANiE;Ppvp}P2W@m z-VbYn+NXFF?6ngef5CfY6ZwKnWvNV4z6s^~yMXw2i5mv}jC$6$46g?G|CPAu{W5qF zDobS=zb2ILX9D827g*NtGe5w;>frjanY{f)hrBP_2ehBt1?`~ypvg_Ot4x1V+43P@Ve8>qd)9NX_jWdLo`Zfy zoeam9)@Dpym{4m@+LNxXBPjPKA7{3a&H+~xQvr>C_A;7=JrfK~$M2pCh>|xLz>W6SCs4qC|#V`)# z)0C|?$o>jzh<|-cpf

K7osU{Xp5PG4-K+L2G=)c3f&}H&M3wo7TlO_UJjQ-Oq&_ zjAc9=nNIYz{c3zxOiS5UfcE1}8#iI4@uy;$Q7>}u`j+OU0N<*Ezx$k{x_27+{s2Eg z`^=rhtIzCm!_UcJ?Db~Lh-=_))PT3{Q0{Mwdq;0>ZL%l3+;B&4!&xm#%HYAK|;b456Iv&&f$VQHf` z>$*K9w8T+paVwc7fLfMlhQ4)*zL_SG{~v4QR;IuX-(oRtYAhWOlh`NLoX0k$RUYMi z2Y!bqpdN}wz8q`-%>&Le@q|jFw92ErW-hma-le?S z-@OZt2EEUm4wLsuEMkt4zlyy29_3S50JAcQHTtgTC{P~%-mvCTzrjXOc|{}N`Cz`W zSj7CrXfa7lcsU0J(0uSX6G`54t^7}+OLM0n(|g4waOQ}bd3%!XLh?NX9|8G_|06Ie zD5F1)w5I~!et7lA{G^;uf7aqT`KE&2qx9|~O;s6t!gb`+zVLJyT2T)l*8l(j literal 0 HcmV?d00001 diff --git a/examples/react-router/react-router.config.ts b/examples/react-router/react-router.config.ts new file mode 100644 index 00000000..6ff16f91 --- /dev/null +++ b/examples/react-router/react-router.config.ts @@ -0,0 +1,7 @@ +import type { Config } from "@react-router/dev/config"; + +export default { + // Config options... + // Server-side render by default, to enable SPA mode set this to `false` + ssr: true, +} satisfies Config; diff --git a/examples/react-router/tsconfig.json b/examples/react-router/tsconfig.json new file mode 100644 index 00000000..dc391a45 --- /dev/null +++ b/examples/react-router/tsconfig.json @@ -0,0 +1,27 @@ +{ + "include": [ + "**/*", + "**/.server/**/*", + "**/.client/**/*", + ".react-router/types/**/*" + ], + "compilerOptions": { + "lib": ["DOM", "DOM.Iterable", "ES2022"], + "types": ["node", "vite/client"], + "target": "ES2022", + "module": "ES2022", + "moduleResolution": "bundler", + "jsx": "react-jsx", + "rootDirs": [".", "./.react-router/types"], + "baseUrl": ".", + "paths": { + "~/*": ["./app/*"] + }, + "esModuleInterop": true, + "verbatimModuleSyntax": true, + "noEmit": true, + "resolveJsonModule": true, + "skipLibCheck": true, + "strict": true + } +} diff --git a/examples/react-router/vite.config.ts b/examples/react-router/vite.config.ts new file mode 100644 index 00000000..4a88d587 --- /dev/null +++ b/examples/react-router/vite.config.ts @@ -0,0 +1,8 @@ +import { reactRouter } from "@react-router/dev/vite"; +import tailwindcss from "@tailwindcss/vite"; +import { defineConfig } from "vite"; +import tsconfigPaths from "vite-tsconfig-paths"; + +export default defineConfig({ + plugins: [tailwindcss(), reactRouter(), tsconfigPaths()], +}); diff --git a/packages/durably-react/src/client.ts b/packages/durably-react/src/client.ts index efa0a646..107f67fb 100644 --- a/packages/durably-react/src/client.ts +++ b/packages/durably-react/src/client.ts @@ -28,5 +28,18 @@ export type { UseJobLogsClientResult, } from './client/use-job-logs' +export { useRuns } from './client/use-runs' +export type { + ClientRun, + UseRunsClientOptions, + UseRunsClientResult, +} from './client/use-runs' + +export { useRunActions } from './client/use-run-actions' +export type { + UseRunActionsClientOptions, + UseRunActionsClientResult, +} from './client/use-run-actions' + // Re-export shared types export type { LogEntry, Progress, RunStatus } from './types' diff --git a/packages/durably-react/src/client/index.ts b/packages/durably-react/src/client/index.ts index aaa49bd2..41e9b339 100644 --- a/packages/durably-react/src/client/index.ts +++ b/packages/durably-react/src/client/index.ts @@ -28,5 +28,18 @@ export type { UseJobLogsClientResult, } from './use-job-logs' +export { useRuns } from './use-runs' +export type { + ClientRun, + UseRunsClientOptions, + UseRunsClientResult, +} from './use-runs' + +export { useRunActions } from './use-run-actions' +export type { + UseRunActionsClientOptions, + UseRunActionsClientResult, +} from './use-run-actions' + // Re-export types for convenience export type { LogEntry, Progress, RunStatus } from '../types' diff --git a/packages/durably-react/src/client/use-job-run.ts b/packages/durably-react/src/client/use-job-run.ts index fdad33bb..78b9042c 100644 --- a/packages/durably-react/src/client/use-job-run.ts +++ b/packages/durably-react/src/client/use-job-run.ts @@ -1,3 +1,4 @@ +import { useEffect, useRef } from 'react' import type { LogEntry, Progress, RunStatus } from '../types' import { useSSESubscription } from './use-sse-subscription' @@ -10,6 +11,18 @@ export interface UseJobRunClientOptions { * The run ID to subscribe to */ runId: string | null + /** + * Callback when run starts (transitions to pending/running) + */ + onStart?: () => void + /** + * Callback when run completes successfully + */ + onComplete?: () => void + /** + * Callback when run fails + */ + onFail?: () => void } export interface UseJobRunClientResult { @@ -62,20 +75,59 @@ export interface UseJobRunClientResult { export function useJobRun( options: UseJobRunClientOptions, ): UseJobRunClientResult { - const { api, runId } = options + const { api, runId, onStart, onComplete, onFail } = options const subscription = useSSESubscription(api, runId) + // If we have a runId but no status yet, treat as pending + const effectiveStatus = subscription.status ?? (runId ? 'pending' : null) + + const isCompleted = effectiveStatus === 'completed' + const isFailed = effectiveStatus === 'failed' + const isPending = effectiveStatus === 'pending' + const isRunning = effectiveStatus === 'running' + + // Track previous status to detect transitions + const prevStatusRef = useRef(null) + + useEffect(() => { + const prevStatus = prevStatusRef.current + prevStatusRef.current = subscription.status + + // Only fire callbacks on status transitions + if (prevStatus !== subscription.status) { + // Fire onStart when transitioning from null to pending/running + if (prevStatus === null && (isPending || isRunning) && onStart) { + onStart() + } + if (isCompleted && onComplete) { + onComplete() + } + if (isFailed && onFail) { + onFail() + } + } + }, [ + subscription.status, + isPending, + isRunning, + isCompleted, + isFailed, + onStart, + onComplete, + onFail, + ]) + return { isReady: true, - status: subscription.status, + status: effectiveStatus, output: subscription.output, error: subscription.error, logs: subscription.logs, progress: subscription.progress, - isRunning: subscription.status === 'running', - isPending: subscription.status === 'pending', - isCompleted: subscription.status === 'completed', - isFailed: subscription.status === 'failed', + isRunning, + isPending, + isCompleted, + isFailed, } } diff --git a/packages/durably-react/src/client/use-run-actions.ts b/packages/durably-react/src/client/use-run-actions.ts new file mode 100644 index 00000000..e80b83bc --- /dev/null +++ b/packages/durably-react/src/client/use-run-actions.ts @@ -0,0 +1,123 @@ +import { useCallback, useState } from 'react' + +export interface UseRunActionsClientOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string +} + +export interface UseRunActionsClientResult { + /** + * Retry a failed run + */ + retry: (runId: string) => Promise + /** + * Cancel a pending or running run + */ + cancel: (runId: string) => Promise + /** + * Whether an action is in progress + */ + isLoading: boolean + /** + * Error message from last action + */ + error: string | null +} + +/** + * Hook for run actions (retry, cancel) via server API. + * + * @example + * ```tsx + * function RunActions({ runId, status }: { runId: string; status: string }) { + * const { retry, cancel, isLoading, error } = useRunActions({ + * api: '/api/durably', + * }) + * + * return ( + *

+ * {status === 'failed' && ( + * + * )} + * {(status === 'pending' || status === 'running') && ( + * + * )} + * {error && {error}} + *
+ * ) + * } + * ``` + */ +export function useRunActions( + options: UseRunActionsClientOptions, +): UseRunActionsClientResult { + const { api } = options + + const [isLoading, setIsLoading] = useState(false) + const [error, setError] = useState(null) + + const retry = useCallback( + async (runId: string) => { + setIsLoading(true) + setError(null) + + try { + const url = `${api}/retry?runId=${encodeURIComponent(runId)}` + const response = await fetch(url, { method: 'POST' }) + + if (!response.ok) { + const data = await response.json() + throw new Error( + data.error || `Failed to retry: ${response.statusText}`, + ) + } + } catch (err) { + const message = err instanceof Error ? err.message : 'Unknown error' + setError(message) + throw err + } finally { + setIsLoading(false) + } + }, + [api], + ) + + const cancel = useCallback( + async (runId: string) => { + setIsLoading(true) + setError(null) + + try { + const url = `${api}/cancel?runId=${encodeURIComponent(runId)}` + const response = await fetch(url, { method: 'POST' }) + + if (!response.ok) { + const data = await response.json() + throw new Error( + data.error || `Failed to cancel: ${response.statusText}`, + ) + } + } catch (err) { + const message = err instanceof Error ? err.message : 'Unknown error' + setError(message) + throw err + } finally { + setIsLoading(false) + } + }, + [api], + ) + + return { + retry, + cancel, + isLoading, + error, + } +} diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts new file mode 100644 index 00000000..7621fab2 --- /dev/null +++ b/packages/durably-react/src/client/use-runs.ts @@ -0,0 +1,242 @@ +import { useCallback, useEffect, useRef, useState } from 'react' +import type { RunStatus } from '../types' + +/** + * Run type for client mode (matches server response) + */ +export interface ClientRun { + id: string + jobName: string + status: RunStatus + input: unknown + output: unknown | null + error: string | null + createdAt: string + startedAt: string | null + completedAt: string | null +} + +/** + * SSE notification event from /runs/subscribe + */ +interface RunUpdateEvent { + type: 'run:start' | 'run:complete' | 'run:fail' + runId: string + jobName: string +} + +export interface UseRunsClientOptions { + /** + * API endpoint URL (e.g., '/api/durably') + */ + api: string + /** + * Filter by job name + */ + jobName?: string + /** + * Filter by status + */ + status?: RunStatus + /** + * Number of runs per page + * @default 10 + */ + pageSize?: number +} + +export interface UseRunsClientResult { + /** + * List of runs for the current page + */ + runs: ClientRun[] + /** + * Current page (0-indexed) + */ + page: number + /** + * Whether there are more pages + */ + hasMore: boolean + /** + * Whether data is being loaded + */ + isLoading: boolean + /** + * Error message if fetch failed + */ + error: string | null + /** + * Go to the next page + */ + nextPage: () => void + /** + * Go to the previous page + */ + prevPage: () => void + /** + * Go to a specific page + */ + goToPage: (page: number) => void + /** + * Refresh the current page + */ + refresh: () => Promise +} + +/** + * Hook for listing runs via server API with pagination. + * First page (page 0) automatically subscribes to SSE for real-time updates. + * Other pages are static and require manual refresh. + * + * @example + * ```tsx + * function RunHistory() { + * const { runs, page, hasMore, nextPage, prevPage, refresh } = useRuns({ + * api: '/api/durably', + * jobName: 'import-csv', + * pageSize: 10, + * }) + * + * return ( + *
+ * {runs.map(run => ( + *
{run.jobName}: {run.status}
+ * ))} + * + * + * + *
+ * ) + * } + * ``` + */ +export function useRuns(options: UseRunsClientOptions): UseRunsClientResult { + const { api, jobName, status, pageSize = 10 } = options + + const [runs, setRuns] = useState([]) + const [page, setPage] = useState(0) + const [hasMore, setHasMore] = useState(false) + const [isLoading, setIsLoading] = useState(false) + const [error, setError] = useState(null) + + const isMountedRef = useRef(true) + const eventSourceRef = useRef(null) + + const refresh = useCallback(async () => { + setIsLoading(true) + setError(null) + + try { + const params = new URLSearchParams() + if (jobName) params.set('jobName', jobName) + if (status) params.set('status', status) + params.set('limit', String(pageSize + 1)) + params.set('offset', String(page * pageSize)) + + const url = `${api}/runs?${params.toString()}` + const response = await fetch(url) + + if (!response.ok) { + throw new Error(`Failed to fetch runs: ${response.statusText}`) + } + + const data = (await response.json()) as ClientRun[] + + if (isMountedRef.current) { + setHasMore(data.length > pageSize) + setRuns(data.slice(0, pageSize)) + } + } catch (err) { + if (isMountedRef.current) { + setError(err instanceof Error ? err.message : 'Unknown error') + } + } finally { + if (isMountedRef.current) { + setIsLoading(false) + } + } + }, [api, jobName, status, pageSize, page]) + + // Initial fetch + useEffect(() => { + isMountedRef.current = true + refresh() + + return () => { + isMountedRef.current = false + } + }, [refresh]) + + // SSE subscription for first page only + useEffect(() => { + // Only subscribe to SSE on first page + if (page !== 0) { + // Clean up any existing connection when navigating away from first page + if (eventSourceRef.current) { + eventSourceRef.current.close() + eventSourceRef.current = null + } + return + } + + // Build SSE URL + const params = new URLSearchParams() + if (jobName) params.set('jobName', jobName) + const sseUrl = `${api}/runs/subscribe${params.toString() ? `?${params.toString()}` : ''}` + + const eventSource = new EventSource(sseUrl) + eventSourceRef.current = eventSource + + eventSource.onmessage = (event) => { + try { + const data = JSON.parse(event.data) as RunUpdateEvent + // On any run update, refresh the list + if ( + data.type === 'run:start' || + data.type === 'run:complete' || + data.type === 'run:fail' + ) { + refresh() + } + } catch { + // Ignore parse errors + } + } + + eventSource.onerror = () => { + // EventSource will automatically reconnect + } + + return () => { + eventSource.close() + eventSourceRef.current = null + } + }, [api, jobName, page, refresh]) + + const nextPage = useCallback(() => { + if (hasMore) { + setPage((p) => p + 1) + } + }, [hasMore]) + + const prevPage = useCallback(() => { + setPage((p) => Math.max(0, p - 1)) + }, []) + + const goToPage = useCallback((newPage: number) => { + setPage(Math.max(0, newPage)) + }, []) + + return { + runs, + page, + hasMore, + isLoading, + error, + nextPage, + prevPage, + goToPage, + refresh, + } +} diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx index 4cf3c507..3b68f83b 100644 --- a/packages/durably-react/tests/client/use-job-run.test.tsx +++ b/packages/durably-react/tests/client/use-job-run.test.tsx @@ -189,12 +189,15 @@ describe('useJobRun (client)', () => { expect(mockEventSource.instances.length).toBeGreaterThan(0) }) + // With runId set, status starts as 'pending' until SSE events arrive + expect(result.current.status).toBe('pending') + act(() => { mockEventSource.emit({ type: 'run:start', runId: 'other-run' }) }) - // Status should remain null since event is for a different run + // Status should remain 'pending' since event is for a different run await new Promise((r) => setTimeout(r, 50)) - expect(result.current.status).toBeNull() + expect(result.current.status).toBe('pending') }) }) diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts index dc350485..a962cf5b 100644 --- a/packages/durably/src/server.ts +++ b/packages/durably/src/server.ts @@ -18,10 +18,48 @@ export interface TriggerResponse { runId: string } +/** + * Request query params for listing runs + */ +export interface RunsRequest { + jobName?: string + status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' + limit?: number + offset?: number +} + /** * Handler interface for HTTP endpoints */ export interface DurablyHandler { + /** + * Handle all Durably HTTP requests with automatic routing + * + * Routes: + * - GET {basePath}/subscribe?runId=xxx - SSE stream + * - GET {basePath}/runs - List runs + * - GET {basePath}/run?runId=xxx - Get single run + * - POST {basePath}/trigger - Trigger a job + * - POST {basePath}/retry?runId=xxx - Retry a failed run + * - POST {basePath}/cancel?runId=xxx - Cancel a run + * + * @param request - The incoming HTTP request + * @param basePath - The base path to strip from the URL (e.g., '/api/durably') + * @returns Response or null if route not matched + * + * @example + * ```ts + * // React Router / Remix + * export async function loader({ request }) { + * return durablyHandler.handle(request, '/api/durably') + * } + * export async function action({ request }) { + * return durablyHandler.handle(request, '/api/durably') + * } + * ``` + */ + handle(request: Request, basePath: string): Promise + /** * Handle job trigger request * Expects POST with JSON body: { jobName, input, idempotencyKey?, concurrencyKey? } @@ -35,14 +73,101 @@ export interface DurablyHandler { * Returns SSE stream of events */ subscribe(request: Request): Response + + /** + * Handle runs list request + * Expects GET with optional query params: jobName, status, limit, offset + * Returns JSON array of runs + */ + runs(request: Request): Promise + + /** + * Handle single run request + * Expects GET with query param: runId + * Returns JSON run object or 404 + */ + run(request: Request): Promise + + /** + * Handle retry request + * Expects POST with query param: runId + * Returns JSON: { success: true } + */ + retry(request: Request): Promise + + /** + * Handle cancel request + * Expects POST with query param: runId + * Returns JSON: { success: true } + */ + cancel(request: Request): Promise + + /** + * Handle runs subscription request + * Expects GET with optional query param: jobName + * Returns SSE stream of run update notifications + */ + subscribeRuns(request: Request): Response +} + +/** + * Options for createDurablyHandler + */ +export interface CreateDurablyHandlerOptions { + /** + * Called before handling each request. + * Use this to initialize Durably (migrate, start worker, etc.) + * + * @example + * ```ts + * const durablyHandler = createDurablyHandler(durably, { + * onRequest: async () => { + * await durably.migrate() + * durably.start() + * } + * }) + * ``` + */ + onRequest?: () => Promise | void } /** * Create HTTP handlers for Durably * Uses Web Standard Request/Response for framework-agnostic usage */ -export function createDurablyHandler(durably: Durably): DurablyHandler { - return { +export function createDurablyHandler( + durably: Durably, + options?: CreateDurablyHandlerOptions, +): DurablyHandler { + const handler: DurablyHandler = { + async handle(request: Request, basePath: string): Promise { + // Run onRequest hook if provided + if (options?.onRequest) { + await options.onRequest() + } + + const url = new URL(request.url) + const path = url.pathname.replace(basePath, '') + const method = request.method + + // GET routes + if (method === 'GET') { + if (path === '/subscribe') return handler.subscribe(request) + if (path === '/runs') return handler.runs(request) + if (path === '/run') return handler.run(request) + if (path === '/runs/subscribe') return handler.subscribeRuns(request) + } + + // POST routes + if (method === 'POST') { + if (path === '/trigger') return handler.trigger(request) + if (path === '/retry') return handler.retry(request) + if (path === '/cancel') return handler.cancel(request) + } + + return new Response('Not Found', { status: 404 }) + }, + async trigger(request: Request): Promise { try { const body = (await request.json()) as TriggerRequest @@ -128,5 +253,194 @@ export function createDurablyHandler(durably: Durably): DurablyHandler { }, }) }, + + async runs(request: Request): Promise { + try { + const url = new URL(request.url) + const jobName = url.searchParams.get('jobName') ?? undefined + const status = url.searchParams.get('status') as RunsRequest['status'] + const limit = url.searchParams.get('limit') + const offset = url.searchParams.get('offset') + + const runs = await durably.getRuns({ + jobName, + status, + limit: limit ? Number.parseInt(limit, 10) : undefined, + offset: offset ? Number.parseInt(offset, 10) : undefined, + }) + + return new Response(JSON.stringify(runs), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) + } catch (error) { + const message = error instanceof Error ? error.message : 'Unknown error' + return new Response(JSON.stringify({ error: message }), { + status: 500, + headers: { 'Content-Type': 'application/json' }, + }) + } + }, + + async run(request: Request): Promise { + try { + const url = new URL(request.url) + const runId = url.searchParams.get('runId') + + if (!runId) { + return new Response( + JSON.stringify({ error: 'runId query parameter is required' }), + { status: 400, headers: { 'Content-Type': 'application/json' } }, + ) + } + + const run = await durably.getRun(runId) + + if (!run) { + return new Response(JSON.stringify({ error: 'Run not found' }), { + status: 404, + headers: { 'Content-Type': 'application/json' }, + }) + } + + return new Response(JSON.stringify(run), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) + } catch (error) { + const message = error instanceof Error ? error.message : 'Unknown error' + return new Response(JSON.stringify({ error: message }), { + status: 500, + headers: { 'Content-Type': 'application/json' }, + }) + } + }, + + async retry(request: Request): Promise { + try { + const url = new URL(request.url) + const runId = url.searchParams.get('runId') + + if (!runId) { + return new Response( + JSON.stringify({ error: 'runId query parameter is required' }), + { status: 400, headers: { 'Content-Type': 'application/json' } }, + ) + } + + await durably.retry(runId) + + return new Response(JSON.stringify({ success: true }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) + } catch (error) { + const message = error instanceof Error ? error.message : 'Unknown error' + return new Response(JSON.stringify({ error: message }), { + status: 500, + headers: { 'Content-Type': 'application/json' }, + }) + } + }, + + async cancel(request: Request): Promise { + try { + const url = new URL(request.url) + const runId = url.searchParams.get('runId') + + if (!runId) { + return new Response( + JSON.stringify({ error: 'runId query parameter is required' }), + { status: 400, headers: { 'Content-Type': 'application/json' } }, + ) + } + + await durably.cancel(runId) + + return new Response(JSON.stringify({ success: true }), { + status: 200, + headers: { 'Content-Type': 'application/json' }, + }) + } catch (error) { + const message = error instanceof Error ? error.message : 'Unknown error' + return new Response(JSON.stringify({ error: message }), { + status: 500, + headers: { 'Content-Type': 'application/json' }, + }) + } + }, + + subscribeRuns(request: Request): Response { + const url = new URL(request.url) + const jobNameFilter = url.searchParams.get('jobName') + + const encoder = new TextEncoder() + let closed = false + + const sseStream = new ReadableStream({ + start(controller) { + // Subscribe to run lifecycle events + const unsubscribeStart = durably.on('run:start', (event) => { + if (closed) return + if (jobNameFilter && event.jobName !== jobNameFilter) return + + const data = `data: ${JSON.stringify({ + type: 'run:start', + runId: event.runId, + jobName: event.jobName, + })}\n\n` + controller.enqueue(encoder.encode(data)) + }) + + const unsubscribeComplete = durably.on('run:complete', (event) => { + if (closed) return + if (jobNameFilter && event.jobName !== jobNameFilter) return + + const data = `data: ${JSON.stringify({ + type: 'run:complete', + runId: event.runId, + jobName: event.jobName, + })}\n\n` + controller.enqueue(encoder.encode(data)) + }) + + const unsubscribeFail = durably.on('run:fail', (event) => { + if (closed) return + if (jobNameFilter && event.jobName !== jobNameFilter) return + + const data = `data: ${JSON.stringify({ + type: 'run:fail', + runId: event.runId, + jobName: event.jobName, + })}\n\n` + controller.enqueue(encoder.encode(data)) + }) + + // Store cleanup function for cancel + ;(controller as unknown as { cleanup: () => void }).cleanup = () => { + closed = true + unsubscribeStart() + unsubscribeComplete() + unsubscribeFail() + } + }, + cancel(controller) { + const cleanup = (controller as unknown as { cleanup: () => void }) + .cleanup + if (cleanup) cleanup() + }, + }) + + return new Response(sseStream, { + status: 200, + headers: { + 'Content-Type': 'text/event-stream', + 'Cache-Control': 'no-cache', + Connection: 'keep-alive', + }, + }) + }, } + + return handler } diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 6ab1dc93..cfa9eca5 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -16,7 +16,7 @@ importers: version: 25.0.3 '@vitest/coverage-v8': specifier: 4.0.16 - version: 4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16) + version: 4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16) cc-hooks-ts: specifier: 2.0.70 version: 2.0.70(typescript@5.9.3)(zod@4.2.1) @@ -40,7 +40,7 @@ importers: version: 0.28.9 sqlocal: specifier: ^0.16.0 - version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) + version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) zod: specifier: ^4.2.1 version: 4.2.1 @@ -59,7 +59,7 @@ importers: version: 5.9.3 vite: specifier: ^7.3.0 - version: 7.3.0(@types/node@25.0.3)(tsx@4.21.0) + version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) examples/node: dependencies: @@ -117,7 +117,7 @@ importers: version: 19.2.3(react@19.2.3) sqlocal: specifier: ^0.16.0 - version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) + version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) zod: specifier: ^4.2.1 version: 4.2.1 @@ -133,7 +133,7 @@ importers: version: 19.2.3(@types/react@19.2.7) '@vitejs/plugin-react': specifier: ^5.1.2 - version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) prettier: specifier: ^3.7.4 version: 3.7.4 @@ -145,7 +145,68 @@ importers: version: 5.9.3 vite: specifier: ^7.3.0 - version: 7.3.0(@types/node@25.0.3)(tsx@4.21.0) + version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + + examples/react-router: + dependencies: + '@coji/durably': + specifier: workspace:* + version: link:../../packages/durably + '@coji/durably-react': + specifier: workspace:* + version: link:../../packages/durably-react + '@libsql/kysely-libsql': + specifier: ^0.4.1 + version: 0.4.1(kysely@0.28.9) + '@react-router/node': + specifier: 7.11.0 + version: 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + '@react-router/serve': + specifier: 7.11.0 + version: 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + isbot: + specifier: ^5.1.31 + version: 5.1.32 + react: + specifier: ^19.2.3 + version: 19.2.3 + react-dom: + specifier: ^19.2.3 + version: 19.2.3(react@19.2.3) + react-router: + specifier: 7.11.0 + version: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + zod: + specifier: ^4.2.1 + version: 4.2.1 + devDependencies: + '@react-router/dev': + specifier: 7.11.0 + version: 7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) + '@tailwindcss/vite': + specifier: ^4.1.13 + version: 4.1.18(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) + '@types/node': + specifier: ^25.0.3 + version: 25.0.3 + '@types/react': + specifier: ^19.2.7 + version: 19.2.7 + '@types/react-dom': + specifier: ^19.2.3 + version: 19.2.3(@types/react@19.2.7) + tailwindcss: + specifier: ^4.1.13 + version: 4.1.18 + typescript: + specifier: ^5.9.2 + version: 5.9.3 + vite: + specifier: ^7.1.7 + version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + vite-tsconfig-paths: + specifier: ^6.0.3 + version: 6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) packages/durably: dependencies: @@ -173,13 +234,13 @@ importers: version: 19.2.3(@types/react@19.2.7) '@vitejs/plugin-react': specifier: ^5.1.2 - version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) '@vitest/browser': specifier: ^4.0.16 - version: 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + version: 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) '@vitest/browser-playwright': specifier: 4.0.16 - version: 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + version: 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) jsdom: specifier: ^27.3.0 version: 27.3.0 @@ -203,16 +264,16 @@ importers: version: 19.2.3(react@19.2.3) sqlocal: specifier: ^0.16.0 - version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) + version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) tsup: specifier: ^8.5.1 - version: 8.5.1(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3) + version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3) typescript: specifier: ^5.9.3 version: 5.9.3 vitest: specifier: ^4.0.16 - version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.3.0)(lightningcss@1.30.2)(tsx@4.21.0) zod: specifier: ^4.2.1 version: 4.2.1 @@ -236,13 +297,13 @@ importers: version: 19.2.3(@types/react@19.2.7) '@vitejs/plugin-react': specifier: ^5.1.2 - version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + version: 5.1.2(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) '@vitest/browser': specifier: ^4.0.16 - version: 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + version: 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) '@vitest/browser-playwright': specifier: 4.0.16 - version: 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + version: 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) kysely: specifier: ^0.28.9 version: 0.28.9 @@ -263,16 +324,16 @@ importers: version: 19.2.3(react@19.2.3) sqlocal: specifier: ^0.16.0 - version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) + version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)) tsup: specifier: ^8.5.1 - version: 8.5.1(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3) + version: 8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3) typescript: specifier: ^5.9.3 version: 5.9.3 vitest: specifier: ^4.0.16 - version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.3.0)(lightningcss@1.30.2)(tsx@4.21.0) zod: specifier: ^4.2.1 version: 4.2.1 @@ -281,7 +342,7 @@ importers: devDependencies: vitepress: specifier: ^1.6.4 - version: 1.6.4(@algolia/client-search@5.46.1)(@types/node@25.0.3)(postcss@8.5.6)(search-insights@2.17.3)(typescript@5.9.3) + version: 1.6.4(@algolia/client-search@5.46.1)(@types/node@25.0.3)(lightningcss@1.30.2)(postcss@8.5.6)(search-insights@2.17.3)(typescript@5.9.3) packages: @@ -395,14 +456,28 @@ packages: resolution: {integrity: sha512-3EwLFhZ38J4VyIP6WNtt2kUdW9dokXA9Cr4IVIFHuCpZ3H8/YFOl5JjZHisrn1fATPBmKKqXzDFvh9fUwHz6CQ==} engines: {node: '>=6.9.0'} + '@babel/helper-annotate-as-pure@7.27.3': + resolution: {integrity: sha512-fXSwMQqitTGeHLBC08Eq5yXz2m37E4pJX1qAU1+2cNedz/ifv/bVXft90VeSav5nFO61EcNgwr0aJxbyPaWBPg==} + engines: {node: '>=6.9.0'} + '@babel/helper-compilation-targets@7.27.2': resolution: {integrity: sha512-2+1thGUUWWjLTYTHZWK1n8Yga0ijBz1XAhUXcKy81rd5g6yh7hGqMp45v7cadSbEHc9G3OTv45SyneRN3ps4DQ==} engines: {node: '>=6.9.0'} + '@babel/helper-create-class-features-plugin@7.28.5': + resolution: {integrity: sha512-q3WC4JfdODypvxArsJQROfupPBq9+lMwjKq7C33GhbFYJsufD0yd/ziwD+hJucLeWsnFPWZjsU2DNFqBPE7jwQ==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0 + '@babel/helper-globals@7.28.0': resolution: {integrity: sha512-+W6cISkXFa1jXsDEdYA8HeevQT/FULhxzR99pxphltZcVaugps53THCeiWA8SguxxpSp3gKPiuYfSWopkLQ4hw==} engines: {node: '>=6.9.0'} + '@babel/helper-member-expression-to-functions@7.28.5': + resolution: {integrity: sha512-cwM7SBRZcPCLgl8a7cY0soT1SptSzAlMH39vwiRpOQkJlh53r5hdHwLSCZpQdVLT39sZt+CRpNwYG4Y2v77atg==} + engines: {node: '>=6.9.0'} + '@babel/helper-module-imports@7.27.1': resolution: {integrity: sha512-0gSFWUPNXNopqtIPQvlD5WgXYI5GY2kP2cCvoT8kczjbfcfuIljTbcWrulD1CIPIX2gt1wghbDy08yE1p+/r3w==} engines: {node: '>=6.9.0'} @@ -413,10 +488,24 @@ packages: peerDependencies: '@babel/core': ^7.0.0 + '@babel/helper-optimise-call-expression@7.27.1': + resolution: {integrity: sha512-URMGH08NzYFhubNSGJrpUEphGKQwMQYBySzat5cAByY1/YgIRkULnIy3tAMeszlL/so2HbeilYloUmSpd7GdVw==} + engines: {node: '>=6.9.0'} + '@babel/helper-plugin-utils@7.27.1': resolution: {integrity: sha512-1gn1Up5YXka3YYAHGKpbideQ5Yjf1tDa9qYcgysz+cNCXukyLl6DjPXhD3VRwSb8c0J9tA4b2+rHEZtc6R0tlw==} engines: {node: '>=6.9.0'} + '@babel/helper-replace-supers@7.27.1': + resolution: {integrity: sha512-7EHz6qDZc8RYS5ElPoShMheWvEgERonFCs7IAonWLLUTXW59DP14bCZt89/GKyreYn8g3S83m21FelHKbeDCKA==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0 + + '@babel/helper-skip-transparent-expression-wrappers@7.27.1': + resolution: {integrity: sha512-Tub4ZKEXqbPjXgWLl2+3JpQAYBJ8+ikpQ2Ocj/q/r0LwE3UhENh7EUabyHjz2kCEsrRY83ew2DQdHluuiDQFzg==} + engines: {node: '>=6.9.0'} + '@babel/helper-string-parser@7.27.1': resolution: {integrity: sha512-qMlSxKbpRlAridDExk92nSobyDdpPijUq2DW6oDnUqd0iOGxmQjyqhMIihI9+zv4LPyZdRje2cavWPbCbWm3eA==} engines: {node: '>=6.9.0'} @@ -438,6 +527,24 @@ packages: engines: {node: '>=6.0.0'} hasBin: true + '@babel/plugin-syntax-jsx@7.27.1': + resolution: {integrity: sha512-y8YTNIeKoyhGd9O0Jiyzyyqk8gdjnumGTQPsz0xOZOQ2RmkVJeZ1vmmfIvFEKqucBG6axJGBZDE/7iI5suUI/w==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0-0 + + '@babel/plugin-syntax-typescript@7.27.1': + resolution: {integrity: sha512-xfYCBMxveHrRMnAWl1ZlPXOZjzkN82THFvLhQhFXFt81Z5HnN+EtUkZhv/zcKpmT3fzmWZB0ywiBrbC3vogbwQ==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0-0 + + '@babel/plugin-transform-modules-commonjs@7.27.1': + resolution: {integrity: sha512-OJguuwlTYlN0gBZFRPqwOGNWssZjfIUdS7HMYtN8c1KmwpwHFBwTeFZrg9XZa+DFTitWOW5iTAG7tyCUPsCCyw==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0-0 + '@babel/plugin-transform-react-jsx-self@7.27.1': resolution: {integrity: sha512-6UzkCs+ejGdZ5mFFC/OCUrv028ab2fp1znZmCZjAOBKiBK2jXD1O+BPSfX8X2qjJ75fZBMSnQn3Rq2mrBJK2mw==} engines: {node: '>=6.9.0'} @@ -450,6 +557,18 @@ packages: peerDependencies: '@babel/core': ^7.0.0-0 + '@babel/plugin-transform-typescript@7.28.5': + resolution: {integrity: sha512-x2Qa+v/CuEoX7Dr31iAfr0IhInrVOWZU/2vJMJ00FOR/2nM0BcBEclpaf9sWCDc+v5e9dMrhSH8/atq/kX7+bA==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0-0 + + '@babel/preset-typescript@7.28.5': + resolution: {integrity: sha512-+bQy5WOI2V6LJZpPVxY+yp66XdZ2yifu0Mc1aP5CQKgjn4QM5IN2i5fAZ4xKop47pr8rpVhiAeu+nDQa12C8+g==} + engines: {node: '>=6.9.0'} + peerDependencies: + '@babel/core': ^7.0.0-0 + '@babel/runtime@7.28.4': resolution: {integrity: sha512-Q/N6JNWvIvPnLDvjlE1OUBLPQHH6l3CltCEsHIujp45zQUSSh8K+gHnaEX45yAT1nyngnINhvWtzN+Nb9D8RAQ==} engines: {node: '>=6.9.0'} @@ -1091,12 +1210,70 @@ packages: cpu: [x64] os: [win32] + '@mjackson/node-fetch-server@0.2.0': + resolution: {integrity: sha512-EMlH1e30yzmTpGLQjlFmaDAjyOeZhng1/XCd7DExR8PNAnG/G1tyruZxEoUe11ClnwGhGrtsdnyyUx1frSzjng==} + '@neon-rs/load@0.0.4': resolution: {integrity: sha512-kTPhdZyTQxB+2wpiRcFWrDcejc4JI6tkPuS7UZCG4l6Zvc5kU/gGQ/ozvHTh1XR5tS+UlfAfGuPajjzQjCiHCw==} '@polka/url@1.0.0-next.29': resolution: {integrity: sha512-wwQAWhWSuHaag8c4q/KN/vCoeOJYshAIvMQwD4GpSb3OiZklFfvAgmj0VCBBImRpuF/aFgIRzllXlVX93Jevww==} + '@react-router/dev@7.11.0': + resolution: {integrity: sha512-g1ou5Zw3r4mCU0L+EXH4vRtAiyt8qz1JOvL1k+PW4rZ4+71h5nBy/fLgD7cg5BnzQZmjRO1PzCgpF5BIrlKYxQ==} + engines: {node: '>=20.0.0'} + hasBin: true + peerDependencies: + '@react-router/serve': ^7.11.0 + '@vitejs/plugin-rsc': ~0.5.7 + react-router: ^7.11.0 + react-server-dom-webpack: ^19.2.3 + typescript: ^5.1.0 + vite: ^5.1.0 || ^6.0.0 || ^7.0.0 + wrangler: ^3.28.2 || ^4.0.0 + peerDependenciesMeta: + '@react-router/serve': + optional: true + '@vitejs/plugin-rsc': + optional: true + react-server-dom-webpack: + optional: true + typescript: + optional: true + wrangler: + optional: true + + '@react-router/express@7.11.0': + resolution: {integrity: sha512-o5DeO9tqUrZcUWAgmPGgK4I/S6iFpqnj/e20xMGA04trk+90b9KAx9eqmRMgHERubVKANTM9gTDPduobQjeH1A==} + engines: {node: '>=20.0.0'} + peerDependencies: + express: ^4.17.1 || ^5 + react-router: 7.11.0 + typescript: ^5.1.0 + peerDependenciesMeta: + typescript: + optional: true + + '@react-router/node@7.11.0': + resolution: {integrity: sha512-11ha8EW+F7wTMmPz2pdi11LJxz2irtuksiCpunpZjtpPmYU37S+GGihG8vFeTa2xFPNunEaHNlfzKyzeYm570Q==} + engines: {node: '>=20.0.0'} + peerDependencies: + react-router: 7.11.0 + typescript: ^5.1.0 + peerDependenciesMeta: + typescript: + optional: true + + '@react-router/serve@7.11.0': + resolution: {integrity: sha512-U5Ht9PmUYF4Ti1ssaWlddLY4ZCbXBtHDGFU/u1h3VsHqleSdHsFuGAFrr/ZEuqTuEWp1CLqn2npEDAmlV9IUKQ==} + engines: {node: '>=20.0.0'} + hasBin: true + peerDependencies: + react-router: 7.11.0 + + '@remix-run/node-fetch-server@0.9.0': + resolution: {integrity: sha512-SoLMv7dbH+njWzXnOY6fI08dFMI5+/dQ+vY3n8RnnbdG7MdJEgiP28Xj/xWlnRnED/aB6SFw56Zop+LbmaaKqA==} + '@rolldown/pluginutils@1.0.0-beta.53': resolution: {integrity: sha512-vENRlFU4YbrwVqNDZ7fLvy+JR1CRkyr01jhSiDpE1u6py3OMzQfztQU2jxykW3ALNxO4kSlqIDeYyD0Y9RcQeQ==} @@ -1241,6 +1418,96 @@ packages: '@standard-schema/spec@1.1.0': resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==} + '@tailwindcss/node@4.1.18': + resolution: {integrity: sha512-DoR7U1P7iYhw16qJ49fgXUlry1t4CpXeErJHnQ44JgTSKMaZUdf17cfn5mHchfJ4KRBZRFA/Coo+MUF5+gOaCQ==} + + '@tailwindcss/oxide-android-arm64@4.1.18': + resolution: {integrity: sha512-dJHz7+Ugr9U/diKJA0W6N/6/cjI+ZTAoxPf9Iz9BFRF2GzEX8IvXxFIi/dZBloVJX/MZGvRuFA9rqwdiIEZQ0Q==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [android] + + '@tailwindcss/oxide-darwin-arm64@4.1.18': + resolution: {integrity: sha512-Gc2q4Qhs660bhjyBSKgq6BYvwDz4G+BuyJ5H1xfhmDR3D8HnHCmT/BSkvSL0vQLy/nkMLY20PQ2OoYMO15Jd0A==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [darwin] + + '@tailwindcss/oxide-darwin-x64@4.1.18': + resolution: {integrity: sha512-FL5oxr2xQsFrc3X9o1fjHKBYBMD1QZNyc1Xzw/h5Qu4XnEBi3dZn96HcHm41c/euGV+GRiXFfh2hUCyKi/e+yw==} + engines: {node: '>= 10'} + cpu: [x64] + os: [darwin] + + '@tailwindcss/oxide-freebsd-x64@4.1.18': + resolution: {integrity: sha512-Fj+RHgu5bDodmV1dM9yAxlfJwkkWvLiRjbhuO2LEtwtlYlBgiAT4x/j5wQr1tC3SANAgD+0YcmWVrj8R9trVMA==} + engines: {node: '>= 10'} + cpu: [x64] + os: [freebsd] + + '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18': + resolution: {integrity: sha512-Fp+Wzk/Ws4dZn+LV2Nqx3IilnhH51YZoRaYHQsVq3RQvEl+71VGKFpkfHrLM/Li+kt5c0DJe/bHXK1eHgDmdiA==} + engines: {node: '>= 10'} + cpu: [arm] + os: [linux] + + '@tailwindcss/oxide-linux-arm64-gnu@4.1.18': + resolution: {integrity: sha512-S0n3jboLysNbh55Vrt7pk9wgpyTTPD0fdQeh7wQfMqLPM/Hrxi+dVsLsPrycQjGKEQk85Kgbx+6+QnYNiHalnw==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [linux] + + '@tailwindcss/oxide-linux-arm64-musl@4.1.18': + resolution: {integrity: sha512-1px92582HkPQlaaCkdRcio71p8bc8i/ap5807tPRDK/uw953cauQBT8c5tVGkOwrHMfc2Yh6UuxaH4vtTjGvHg==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [linux] + + '@tailwindcss/oxide-linux-x64-gnu@4.1.18': + resolution: {integrity: sha512-v3gyT0ivkfBLoZGF9LyHmts0Isc8jHZyVcbzio6Wpzifg/+5ZJpDiRiUhDLkcr7f/r38SWNe7ucxmGW3j3Kb/g==} + engines: {node: '>= 10'} + cpu: [x64] + os: [linux] + + '@tailwindcss/oxide-linux-x64-musl@4.1.18': + resolution: {integrity: sha512-bhJ2y2OQNlcRwwgOAGMY0xTFStt4/wyU6pvI6LSuZpRgKQwxTec0/3Scu91O8ir7qCR3AuepQKLU/kX99FouqQ==} + engines: {node: '>= 10'} + cpu: [x64] + os: [linux] + + '@tailwindcss/oxide-wasm32-wasi@4.1.18': + resolution: {integrity: sha512-LffYTvPjODiP6PT16oNeUQJzNVyJl1cjIebq/rWWBF+3eDst5JGEFSc5cWxyRCJ0Mxl+KyIkqRxk1XPEs9x8TA==} + engines: {node: '>=14.0.0'} + cpu: [wasm32] + bundledDependencies: + - '@napi-rs/wasm-runtime' + - '@emnapi/core' + - '@emnapi/runtime' + - '@tybys/wasm-util' + - '@emnapi/wasi-threads' + - tslib + + '@tailwindcss/oxide-win32-arm64-msvc@4.1.18': + resolution: {integrity: sha512-HjSA7mr9HmC8fu6bdsZvZ+dhjyGCLdotjVOgLA2vEqxEBZaQo9YTX4kwgEvPCpRh8o4uWc4J/wEoFzhEmjvPbA==} + engines: {node: '>= 10'} + cpu: [arm64] + os: [win32] + + '@tailwindcss/oxide-win32-x64-msvc@4.1.18': + resolution: {integrity: sha512-bJWbyYpUlqamC8dpR7pfjA0I7vdF6t5VpUGMWRkXVE3AXgIZjYUYAK7II1GNaxR8J1SSrSrppRar8G++JekE3Q==} + engines: {node: '>= 10'} + cpu: [x64] + os: [win32] + + '@tailwindcss/oxide@4.1.18': + resolution: {integrity: sha512-EgCR5tTS5bUSKQgzeMClT6iCY3ToqE1y+ZB0AKldj809QXk1Y+3jB0upOYZrn9aGIzPtUsP7sX4QQ4XtjBB95A==} + engines: {node: '>= 10'} + + '@tailwindcss/vite@4.1.18': + resolution: {integrity: sha512-jVA+/UpKL1vRLg6Hkao5jldawNmRo7mQYrZtNHMIVpLfLhDml5nMRUo/8MwoX2vNXvnaXNNMedrMfMugAVX1nA==} + peerDependencies: + vite: ^5.2.0 || ^6 || ^7 + '@testing-library/dom@10.4.1': resolution: {integrity: sha512-o4PXJQidqJl82ckFaXUeoAW+XysPLauYI43Abki5hABd853iMhitooc6znOnczgbTYmEP6U6/y1ZyKAIsvMKGg==} engines: {node: '>=18'} @@ -1475,6 +1742,10 @@ packages: '@vueuse/shared@12.8.2': resolution: {integrity: sha512-dznP38YzxZoNloI0qpEfpkms8knDtaoQ6Y/sfS0L7Yki4zh40LFHEhur0odJC6xTHG5dxWVPiUWBXn+wCG2s5w==} + accepts@1.3.8: + resolution: {integrity: sha512-PYAthTa2m2VKxuvSD3DPC/Gy+U+sOA1LAuT8mkmRuvw+NACSaeXEQ+NHcVF7rONl6qcaxV3Uuemwawk+7+SJLw==} + engines: {node: '>= 0.6'} + acorn@8.15.0: resolution: {integrity: sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==} engines: {node: '>=0.4.0'} @@ -1499,9 +1770,15 @@ packages: any-promise@1.3.0: resolution: {integrity: sha512-7UvmKalWRt1wgjL1RrGxoSJW/0QZFIegpeGvZG9kjp8vrRu55XTHbwnqq2GpXm9uLbcuhxm3IqX9OB4MZR1b2A==} + arg@5.0.2: + resolution: {integrity: sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==} + aria-query@5.3.0: resolution: {integrity: sha512-b0P0sZPKtyu8HkeRAfCq0IfURZK+SuwMjY1UXGBU27wpAiTwQAIlq56IbIO+ytk/JjS1fMR14ee5WBBfKi5J6A==} + array-flatten@1.1.1: + resolution: {integrity: sha512-PCVAQswWemu6UdxsDFFX/+gVeYqKAod3D3UVm91jHwynguOwAvYPhx8nNlM++NqRcK6CxxpUafjmhIdKiHibqg==} + assertion-error@2.0.1: resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==} engines: {node: '>=12'} @@ -1509,33 +1786,59 @@ packages: ast-v8-to-istanbul@0.3.10: resolution: {integrity: sha512-p4K7vMz2ZSk3wN8l5o3y2bJAoZXT3VuJI5OLTATY/01CYWumWvwkUw0SqDBnNq6IiTO3qDa1eSQDibAV8g7XOQ==} + babel-dead-code-elimination@1.0.11: + resolution: {integrity: sha512-mwq3W3e/pKSI6TG8lXMiDWvEi1VXYlSBlJlB3l+I0bAb5u1RNUl88udos85eOPNK3m5EXK9uO7d2g08pesTySQ==} + baseline-browser-mapping@2.9.11: resolution: {integrity: sha512-Sg0xJUNDU1sJNGdfGWhVHX0kkZ+HWcvmVymJbj6NSgZZmW/8S9Y2HQ5euytnIgakgxN6papOAWiwDo1ctFDcoQ==} hasBin: true + basic-auth@2.0.1: + resolution: {integrity: sha512-NF+epuEdnUYVlGuhaxbbq+dvJttwLnGY+YixlXlME5KpQ5W3CnXA5cVTneY3SPbPDRkcjMbifrwmFYcClgOZeg==} + engines: {node: '>= 0.8'} + bidi-js@1.0.3: resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==} birpc@2.9.0: resolution: {integrity: sha512-KrayHS5pBi69Xi9JmvoqrIgYGDkD6mcSe/i6YKi3w5kekCLzrX4+nawcXqrj2tIp50Kw/mT/s3p+GVK0A0sKxw==} + body-parser@1.20.4: + resolution: {integrity: sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA==} + engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16} + browserslist@4.28.1: resolution: {integrity: sha512-ZC5Bd0LgJXgwGqUknZY/vkUQ04r8NXnJZ3yYi4vDmSiZmC/pdSN0NbNRPxZpbtO4uAfDUAFffO8IZoM3Gj8IkA==} engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7} hasBin: true + buffer-from@1.1.2: + resolution: {integrity: sha512-E+XQCRwSbaaiChtv6k6Dwgc+bx+Bs6vuKJHHl5kox/BaKbhiXzqQOwK4cO22yElGp2OCmjwVhT3HmxgyPGnJfQ==} + bundle-require@5.1.0: resolution: {integrity: sha512-3WrrOuZiyaaZPWiEt4G3+IffISVC9HYlWueJEBWED4ZH4aIAC2PnkdnuRrR94M+w6yGWn4AglWtJtBI8YqvgoA==} engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} peerDependencies: esbuild: '>=0.18' + bytes@3.1.2: + resolution: {integrity: sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==} + engines: {node: '>= 0.8'} + cac@6.7.14: resolution: {integrity: sha512-b6Ilus+c3RrdDk+JhLKUAQfzzgLEPy6wcXqS7f/xe1EETvsDP6GORG7SFuOs6cID5YkqchW/LXZbX5bc8j7ZcQ==} engines: {node: '>=8'} - caniuse-lite@1.0.30001761: - resolution: {integrity: sha512-JF9ptu1vP2coz98+5051jZ4PwQgd2ni8A+gYSN7EA7dPKIMf0pDlSUxhdmVOaV3/fYK5uWBkgSXJaRLr4+3A6g==} + call-bind-apply-helpers@1.0.2: + resolution: {integrity: sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==} + engines: {node: '>= 0.4'} + + call-bound@1.0.4: + resolution: {integrity: sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==} + engines: {node: '>= 0.4'} + + caniuse-lite@1.0.30001762: + resolution: {integrity: sha512-PxZwGNvH7Ak8WX5iXzoK1KPZttBXNPuaOvI2ZYU7NrlM+d9Ov+TUvlLOBNGzVXAntMSMMlJPd+jY6ovrVjSmUw==} cc-hooks-ts@2.0.70: resolution: {integrity: sha512-VIUAEXw/huaTev21xlKjCpWso51vHRIuodGc6T0ihVyA7BXwmQHlfxBnhfsvYtTbo9xVsijSPIgwS7/flJOjAQ==} @@ -1568,16 +1871,46 @@ packages: resolution: {integrity: sha512-NOKm8xhkzAjzFx8B2v5OAHT+u5pRQc2UCa2Vq9jYL/31o2wi9mxBA7LIFs3sV5VSC49z6pEhfbMULvShKj26WA==} engines: {node: '>= 6'} + compressible@2.0.18: + resolution: {integrity: sha512-AF3r7P5dWxL8MxyITRMlORQNaOA2IkAFaTr4k7BUumjPtRpGDTZpl0Pb1XCO6JeDCBdp126Cgs9sMxqSjgYyRg==} + engines: {node: '>= 0.6'} + + compression@1.8.1: + resolution: {integrity: sha512-9mAqGPHLakhCLeNyxPkK4xVo746zQ/czLH1Ky+vkitMnWfWZps8r0qXuwhwizagCRttsL4lfG4pIOvaWLpAP0w==} + engines: {node: '>= 0.8.0'} + confbox@0.1.8: resolution: {integrity: sha512-RMtmw0iFkeR4YV+fUOSucriAQNb9g8zFR52MWCtl+cCZOFRNL6zeB395vPzFhEjjn4fMxXudmELnl/KF/WrK6w==} + confbox@0.2.2: + resolution: {integrity: sha512-1NB+BKqhtNipMsov4xI/NnhCKp9XG9NamYp5PVm9klAT0fsrNPjaFICsCFhNhwZJKNh7zB/3q8qXz0E9oaMNtQ==} + consola@3.4.2: resolution: {integrity: sha512-5IKcdX0nnYavi6G7TtOhwkYzyjfJlatbjMjuLSfE2kYT5pMDOilZ4OvMhi637CcDICTmz3wARPoyhqyX1Y+XvA==} engines: {node: ^14.18.0 || >=16.10.0} + content-disposition@0.5.4: + resolution: {integrity: sha512-FveZTNuGw04cxlAiWbzi6zTAL/lhehaWbTtgluJh4/E95DqMwTmha3KZN1aAWA8cFIhHzMZUvLevkw5Rqk+tSQ==} + engines: {node: '>= 0.6'} + + content-type@1.0.5: + resolution: {integrity: sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==} + engines: {node: '>= 0.6'} + convert-source-map@2.0.0: resolution: {integrity: sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==} + cookie-signature@1.0.7: + resolution: {integrity: sha512-NXdYc3dLr47pBkpUCHtKSwIOQXLVn8dZEuywboCOJY/osA0wFSLlSawr3KN8qXJEyX66FcONTH8EIlVuK0yyFA==} + + cookie@0.7.2: + resolution: {integrity: sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==} + engines: {node: '>= 0.6'} + + cookie@1.1.1: + resolution: {integrity: sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==} + engines: {node: '>=18'} + copy-anything@4.0.5: resolution: {integrity: sha512-7Vv6asjS4gMOuILabD3l739tsaxFQmC+a7pLZm02zyvs8p977bL3zEgq3yDk5rn9B0PbYgIv++jmHcuUab4RhA==} engines: {node: '>=18'} @@ -1601,6 +1934,14 @@ packages: resolution: {integrity: sha512-BnBS08aLUM+DKamupXs3w2tJJoqU+AkaE/+6vQxi/G/DPmIZFJJp9Dkb1kM03AZx8ADehDUZgsNxju3mPXZYIA==} engines: {node: '>=20'} + debug@2.6.9: + resolution: {integrity: sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==} + peerDependencies: + supports-color: '*' + peerDependenciesMeta: + supports-color: + optional: true + debug@4.4.3: resolution: {integrity: sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==} engines: {node: '>=6.0'} @@ -1613,26 +1954,61 @@ packages: decimal.js@10.6.0: resolution: {integrity: sha512-YpgQiITW3JXGntzdUmyUR1V812Hn8T1YVXhCu+wO3OpS4eU9l4YdD3qjyiKdV6mvV29zapkMeD390UVEf2lkUg==} + dedent@1.7.1: + resolution: {integrity: sha512-9JmrhGZpOlEgOLdQgSm0zxFaYoQon408V1v49aqTWuXENVlnCuY9JBZcXZiCsZQWDjTm5Qf/nIvAy77mXDAjEg==} + peerDependencies: + babel-plugin-macros: ^3.1.0 + peerDependenciesMeta: + babel-plugin-macros: + optional: true + + depd@2.0.0: + resolution: {integrity: sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==} + engines: {node: '>= 0.8'} + dequal@2.0.3: resolution: {integrity: sha512-0je+qPKHEMohvfRTCEo3CrPG6cAzAYgmzKyxRiYSSDkS6eGJdyVJm7WaYA5ECaAD9wLB2T4EEeymA5aFVcYXCA==} engines: {node: '>=6'} + destroy@1.2.0: + resolution: {integrity: sha512-2sJGJTaXIIaR1w4iJSNoN0hnMY7Gpc/n8D4qSCJw8QqFWXf7cuAgnEHxBpweaVcPevC2l3KpjYCx3NypQQgaJg==} + engines: {node: '>= 0.8', npm: 1.2.8000 || >= 1.4.16} + detect-libc@2.0.2: resolution: {integrity: sha512-UX6sGumvvqSaXgdKGUsgZWqcUyIXZ/vZTrlRT/iobiKhGL0zL4d3osHj3uqllWJK+i+sixDS/3COVEOFbupFyw==} engines: {node: '>=8'} + detect-libc@2.1.2: + resolution: {integrity: sha512-Btj2BOOO83o3WyH59e8MgXsxEQVcarkUOpEYrubB0urwnN10yQ364rsiByU11nZlqWYZm05i/of7io4mzihBtQ==} + engines: {node: '>=8'} + devlop@1.1.0: resolution: {integrity: sha512-RWmIqhcFf1lRYBvNmr7qTNuyCt/7/ns2jbpp1+PalgE/rDQcBT0fioSMUpJ93irlUhC5hrg4cYqe6U+0ImW0rA==} dom-accessibility-api@0.5.16: resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==} + dunder-proto@1.0.1: + resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==} + engines: {node: '>= 0.4'} + + ee-first@1.1.1: + resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==} + electron-to-chromium@1.5.267: resolution: {integrity: sha512-0Drusm6MVRXSOJpGbaSVgcQsuB4hEkMpHXaVstcPmhu5LIedxs1xNK/nIxmQIU/RPC0+1/o0AVZfBTkTNJOdUw==} emoji-regex-xs@1.0.0: resolution: {integrity: sha512-LRlerrMYoIDrT6jgpeZ2YYl/L8EulRTt5hQcYjy5AInh7HWXKimpqx68aknBFpGL2+/IcogTcaydJEgaTmOpDg==} + encodeurl@2.0.0: + resolution: {integrity: sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==} + engines: {node: '>= 0.8'} + + enhanced-resolve@5.18.4: + resolution: {integrity: sha512-LgQMM4WXU3QI+SYgEc2liRgznaD5ojbmY3sb8LxyguVkIg5FxdpTkvk72te2R38/TGKxH634oLxXRGY6d7AP+Q==} + engines: {node: '>=10.13.0'} + entities@6.0.1: resolution: {integrity: sha512-aN97NXWF6AWBTahfVOIrB/NShkzi5H7F9r1s9mD3cDj4Ko5f2qhhVoYMibXF7GlLveb/D2ioWay8lxI97Ven3g==} engines: {node: '>=0.12'} @@ -1641,9 +2017,21 @@ packages: resolution: {integrity: sha512-FDWG5cmEYf2Z00IkYRhbFrwIwvdFKH07uV8dvNy0omp/Qb1xcyCWp2UDtcwJF4QZZvk0sLudP6/hAu42TaqVhQ==} engines: {node: '>=0.12'} + es-define-property@1.0.1: + resolution: {integrity: sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==} + engines: {node: '>= 0.4'} + + es-errors@1.3.0: + resolution: {integrity: sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==} + engines: {node: '>= 0.4'} + es-module-lexer@1.7.0: resolution: {integrity: sha512-jEQoCwk8hyb2AZziIOLhDqpm5+2ww5uIE6lkO/6jcOCusfk6LhMHpXXfBLXTZ7Ydyt0j4VoUQv6uGNYbdW+kBA==} + es-object-atoms@1.1.1: + resolution: {integrity: sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==} + engines: {node: '>= 0.4'} + esbuild@0.21.5: resolution: {integrity: sha512-mg3OPMV4hXywwpoDxu3Qda5xCKQi+vCTZq8S9J/EpkhB2HzKXq4SNFZE3+NK93JYxc8VMSep+lOUSC/RVKaBqw==} engines: {node: '>=12'} @@ -1658,16 +2046,34 @@ packages: resolution: {integrity: sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==} engines: {node: '>=6'} + escape-html@1.0.3: + resolution: {integrity: sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==} + estree-walker@2.0.2: resolution: {integrity: sha512-Rfkk/Mp/DL7JVje3u18FxFujQlTNR2q6QfMSMB7AvCBx91NGj/ba3kCfza0f6dVDbw7YlRf/nDrn7pQrCCyQ/w==} estree-walker@3.0.3: resolution: {integrity: sha512-7RUKfXgSMMkzt6ZuXmqapOurLGPPfgj6l9uRZ7lRGolvk0y2yocc35LdcxKC5PQZdn2DMqioAQ2NoWcrTKmm6g==} + etag@1.8.1: + resolution: {integrity: sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==} + engines: {node: '>= 0.6'} + + exit-hook@2.2.1: + resolution: {integrity: sha512-eNTPlAD67BmP31LDINZ3U7HSF8l57TxOY2PmBJ1shpCvpnxBF93mWCE8YHBnXs8qiUZJc9WDcWIeC3a2HIAMfw==} + engines: {node: '>=6'} + expect-type@1.3.0: resolution: {integrity: sha512-knvyeauYhqjOYvQ66MznSMs83wmHrCycNEN6Ao+2AeYEfxUIkuiVxdEa1qlGEPK+We3n0THiDciYSsCcgW/DoA==} engines: {node: '>=12.0.0'} + express@4.22.1: + resolution: {integrity: sha512-F2X8g9P1X7uCPZMA3MVf9wcTqlyNp7IhH5qPCI0izhaOIYXaW9L535tGA3qmjRzpH+bZczqq7hVKxTR4NWnu+g==} + engines: {node: '>= 0.10.0'} + + exsolve@1.0.8: + resolution: {integrity: sha512-LmDxfWXwcTArk8fUEnOfSZpHOJ6zOMUJKOtFLFqJLoKJetuQG874Uc7/Kki7zFLzYybmZhp1M7+98pfMqeX8yA==} + fdir@6.5.0: resolution: {integrity: sha512-tIbYtZbucOs0BRGqPJkshJUYdL+SDH7dVM8gjy+ERp3WAUjLEFJE+02kanyHtwjWOnwrKYBiwAmM0p4kLJAnXg==} engines: {node: '>=12.0.0'} @@ -1681,6 +2087,10 @@ packages: resolution: {integrity: sha512-7yAQpD2UMJzLi1Dqv7qFYnPbaPx7ZfFK6PiIxQ4PfkGPyNyl2Ugx+a/umUonmKqjhM4DnfbMvdX6otXq83soQQ==} engines: {node: ^12.20 || >= 14.13} + finalhandler@1.3.2: + resolution: {integrity: sha512-aA4RyPcd3badbdABGDuTXCMTtOneUCAYH/gxoYRTZlIJdF0YPWuGqiAsIrhNnnqdXGswYk6dGujem4w80UJFhg==} + engines: {node: '>= 0.8'} + fix-dts-default-cjs-exports@1.0.1: resolution: {integrity: sha512-pVIECanWFC61Hzl2+oOCtoJ3F17kglZC/6N94eRWycFgBH35hHx0Li604ZIzhseh97mf2p0cv7vVrOZGoqhlEg==} @@ -1691,6 +2101,14 @@ packages: resolution: {integrity: sha512-buewHzMvYL29jdeQTVILecSaZKnt/RJWjoZCF5OW60Z67/GmSLBkOFM7qh1PI3zFNtJbaZL5eQu1vLfazOwj4g==} engines: {node: '>=12.20.0'} + forwarded@0.2.0: + resolution: {integrity: sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==} + engines: {node: '>= 0.6'} + + fresh@0.5.2: + resolution: {integrity: sha512-zJ2mQYM18rEFOudeV4GShTGIQ7RbzA7ozbU9I/XBpm7kqgMywgmylMwXHxZJmkVoYkna9d2pVXVXPdYTP9ej8Q==} + engines: {node: '>= 0.6'} + fsevents@2.3.2: resolution: {integrity: sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==} engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} @@ -1701,6 +2119,9 @@ packages: engines: {node: ^8.16.0 || ^10.6.0 || >=11.0.0} os: [darwin] + function-bind@1.1.2: + resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==} + gc-hook@0.3.1: resolution: {integrity: sha512-E5M+O/h2o7eZzGhzRZGex6hbB3k4NWqO0eA+OzLRLXxhdbYPajZnynPwAtphnh+cRHPwsj5Z80dqZlfI4eK55A==} @@ -1708,13 +2129,43 @@ packages: resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==} engines: {node: '>=6.9.0'} + get-intrinsic@1.3.0: + resolution: {integrity: sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==} + engines: {node: '>= 0.4'} + + get-port@5.1.1: + resolution: {integrity: sha512-g/Q1aTSDOxFpchXC4i8ZWvxA1lnPqx/JHqcpIw0/LX9T8x/GBbi6YnlN5nhaKIFkT8oFsscUKgDJYxfwfS6QsQ==} + engines: {node: '>=8'} + + get-proto@1.0.1: + resolution: {integrity: sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==} + engines: {node: '>= 0.4'} + get-tsconfig@4.13.0: resolution: {integrity: sha512-1VKTZJCwBrvbd+Wn3AOgQP/2Av+TfTCOlE4AcRJE72W1ksZXbAx8PPBR9RzgTeSPzlPMHrbANMH3LbltH73wxQ==} + globrex@0.1.2: + resolution: {integrity: sha512-uHJgbwAMwNFf5mLst7IWLNg14x1CkeqglJb/K3doi4dw6q2IvAAmM/Y81kevy83wP+Sst+nutFTYOGg3d1lsxg==} + + gopd@1.2.0: + resolution: {integrity: sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==} + engines: {node: '>= 0.4'} + + graceful-fs@4.2.11: + resolution: {integrity: sha512-RbJ5/jmFcNNCcDV5o9eTnBLJ/HszWV0P73bc+Ff4nS/rJj+YaS6IGyiOL0VoBYX+l1Wrl3k63h/KrH+nhJ0XvQ==} + has-flag@4.0.0: resolution: {integrity: sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==} engines: {node: '>=8'} + has-symbols@1.1.0: + resolution: {integrity: sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==} + engines: {node: '>= 0.4'} + + hasown@2.0.2: + resolution: {integrity: sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==} + engines: {node: '>= 0.4'} + hast-util-to-html@9.0.5: resolution: {integrity: sha512-OguPdidb+fbHQSU4Q4ZiLKnzWo8Wwsf5bZfbvu7//a9oTYoqD/fWpe96NuHkoS9h0ccGOTe0C4NGXdtS0iObOw==} @@ -1734,6 +2185,10 @@ packages: html-void-elements@3.0.0: resolution: {integrity: sha512-bEqo66MRXsUGxWHV5IP0PUiAWwoEjba4VCzg0LjFJBpchPaTfyfCKTG6bc5F8ucKec3q5y6qOdGyYTSBEvhCrg==} + http-errors@2.0.1: + resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==} + engines: {node: '>= 0.8'} + http-proxy-agent@7.0.2: resolution: {integrity: sha512-T1gkAiYYDWYx3V5Bmyu7HcfcvL7mUrTWiM6yOfa3PIphViJ/gFPbvidQ+veqSOHci/PxBcDabeUNCzpOODJZig==} engines: {node: '>= 14'} @@ -1742,10 +2197,21 @@ packages: resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==} engines: {node: '>= 14'} + iconv-lite@0.4.24: + resolution: {integrity: sha512-v3MXnZAcvnywkTUEZomIActle7RXXeedOR31wwl7VlyoXO4Qi9arvSenNQWne1TcRwhCL1HwLI21bEqdpj8/rA==} + engines: {node: '>=0.10.0'} + iconv-lite@0.6.3: resolution: {integrity: sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==} engines: {node: '>=0.10.0'} + inherits@2.0.4: + resolution: {integrity: sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==} + + ipaddr.js@1.9.1: + resolution: {integrity: sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==} + engines: {node: '>= 0.10'} + is-potential-custom-element-name@1.0.1: resolution: {integrity: sha512-bCYeRA2rVibKZd+s2625gGnGF/t7DSqDs4dP7CrLA1m7jKWz6pps0LpYLJN8Q64HtmPKJ1hrN3nzPNKFEKOUiQ==} @@ -1753,6 +2219,10 @@ packages: resolution: {integrity: sha512-oG7cgbmg5kLYae2N5IVd3jm2s+vldjxJzK1pcu9LfpGuQ93MQSzo0okvRna+7y5ifrD+20FE8FvjusyGaz14fw==} engines: {node: '>=18'} + isbot@5.1.32: + resolution: {integrity: sha512-VNfjM73zz2IBZmdShMfAUg10prm6t7HFUQmNAEOAVS4YH92ZrZcvkMcGX6cIgBJAzWDzPent/EeAtYEHNPNPBQ==} + engines: {node: '>=18'} + istanbul-lib-coverage@3.2.2: resolution: {integrity: sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==} engines: {node: '>=8'} @@ -1769,6 +2239,10 @@ packages: resolution: {integrity: sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==} engines: {node: '>=8'} + jiti@2.6.1: + resolution: {integrity: sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==} + hasBin: true + joycon@3.1.1: resolution: {integrity: sha512-34wB/Y7MW7bzjKRjUKTa46I2Z7eV62Rkhva+KkopW7Qvv/OSWBqvkSY7vusOPrNuZcUG3tApvdVgNB8POj3SPw==} engines: {node: '>=10'} @@ -1791,8 +2265,8 @@ packages: canvas: optional: true - jsesc@3.1.0: - resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==} + jsesc@3.0.2: + resolution: {integrity: sha512-xKqzzWXDttJuOcawBt4KnKHHIf5oQ/Cxax+0PWFG+DFDgHNAdi+TXECADI+RYiFUMmx8792xsMbbgXj4CwnP4g==} engines: {node: '>=6'} hasBin: true @@ -1818,6 +2292,76 @@ packages: cpu: [x64, arm64, wasm32, arm] os: [darwin, linux, win32] + lightningcss-android-arm64@1.30.2: + resolution: {integrity: sha512-BH9sEdOCahSgmkVhBLeU7Hc9DWeZ1Eb6wNS6Da8igvUwAe0sqROHddIlvU06q3WyXVEOYDZ6ykBZQnjTbmo4+A==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [android] + + lightningcss-darwin-arm64@1.30.2: + resolution: {integrity: sha512-ylTcDJBN3Hp21TdhRT5zBOIi73P6/W0qwvlFEk22fkdXchtNTOU4Qc37SkzV+EKYxLouZ6M4LG9NfZ1qkhhBWA==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [darwin] + + lightningcss-darwin-x64@1.30.2: + resolution: {integrity: sha512-oBZgKchomuDYxr7ilwLcyms6BCyLn0z8J0+ZZmfpjwg9fRVZIR5/GMXd7r9RH94iDhld3UmSjBM6nXWM2TfZTQ==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [darwin] + + lightningcss-freebsd-x64@1.30.2: + resolution: {integrity: sha512-c2bH6xTrf4BDpK8MoGG4Bd6zAMZDAXS569UxCAGcA7IKbHNMlhGQ89eRmvpIUGfKWNVdbhSbkQaWhEoMGmGslA==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [freebsd] + + lightningcss-linux-arm-gnueabihf@1.30.2: + resolution: {integrity: sha512-eVdpxh4wYcm0PofJIZVuYuLiqBIakQ9uFZmipf6LF/HRj5Bgm0eb3qL/mr1smyXIS1twwOxNWndd8z0E374hiA==} + engines: {node: '>= 12.0.0'} + cpu: [arm] + os: [linux] + + lightningcss-linux-arm64-gnu@1.30.2: + resolution: {integrity: sha512-UK65WJAbwIJbiBFXpxrbTNArtfuznvxAJw4Q2ZGlU8kPeDIWEX1dg3rn2veBVUylA2Ezg89ktszWbaQnxD/e3A==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [linux] + + lightningcss-linux-arm64-musl@1.30.2: + resolution: {integrity: sha512-5Vh9dGeblpTxWHpOx8iauV02popZDsCYMPIgiuw97OJ5uaDsL86cnqSFs5LZkG3ghHoX5isLgWzMs+eD1YzrnA==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [linux] + + lightningcss-linux-x64-gnu@1.30.2: + resolution: {integrity: sha512-Cfd46gdmj1vQ+lR6VRTTadNHu6ALuw2pKR9lYq4FnhvgBc4zWY1EtZcAc6EffShbb1MFrIPfLDXD6Xprbnni4w==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [linux] + + lightningcss-linux-x64-musl@1.30.2: + resolution: {integrity: sha512-XJaLUUFXb6/QG2lGIW6aIk6jKdtjtcffUT0NKvIqhSBY3hh9Ch+1LCeH80dR9q9LBjG3ewbDjnumefsLsP6aiA==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [linux] + + lightningcss-win32-arm64-msvc@1.30.2: + resolution: {integrity: sha512-FZn+vaj7zLv//D/192WFFVA0RgHawIcHqLX9xuWiQt7P0PtdFEVaxgF9rjM/IRYHQXNnk61/H/gb2Ei+kUQ4xQ==} + engines: {node: '>= 12.0.0'} + cpu: [arm64] + os: [win32] + + lightningcss-win32-x64-msvc@1.30.2: + resolution: {integrity: sha512-5g1yc73p+iAkid5phb4oVFMB45417DkRevRbt/El/gKXJk4jid+vPFF/AXbxn05Aky8PapwzZrdJShv5C0avjw==} + engines: {node: '>= 12.0.0'} + cpu: [x64] + os: [win32] + + lightningcss@1.30.2: + resolution: {integrity: sha512-utfs7Pr5uJyyvDETitgsaqSyjCb2qNRAtuqUeWIAKztsOYdcACf2KtARYXg2pSvhkt+9NfoaNY7fxjl6nuMjIQ==} + engines: {node: '>= 12.0.0'} + lilconfig@3.1.3: resolution: {integrity: sha512-/vlFKAoH5Cgt3Ie+JLhRbwOsCQePABiU3tJ1egGvyQ+33R/vcwM2Zl2QR/LzjsBeItPt3oSVXapn+m4nQDvpzw==} engines: {node: '>=14'} @@ -1829,6 +2373,9 @@ packages: resolution: {integrity: sha512-IXO6OCs9yg8tMKzfPZ1YmheJbZCiEsnBdcB03l0OcfK9prKnJb96siuHCr5Fl37/yo9DnKU+TLpxzTUspw9shg==} engines: {node: ^12.20.0 || ^14.13.1 || >=16.0.0} + lodash@4.17.21: + resolution: {integrity: sha512-v2kDEe57lecTulaDIuNTPy3Ry4gLGJ6Z1O3vE1krgXZNrsQ+LFTGHVxVjcXPs17LhbZVGedAJv8XZ1tvj5FvSg==} + lru-cache@11.2.4: resolution: {integrity: sha512-B5Y16Jr9LB9dHVkh6ZevG+vAbOsNOYCX+sXvFWFu7B3Iz5mijW3zdbMyhsh8ANd2mSWBYdJgnqi+mL7/LrOPYg==} engines: {node: 20 || >=22} @@ -1853,12 +2400,27 @@ packages: mark.js@8.11.1: resolution: {integrity: sha512-1I+1qpDt4idfgLQG+BNWmrqku+7/2bi5nLf4YwF8y8zXvmfiTBY3PV3ZibfrjBueCByROpuBjLLFCajqkgYoLQ==} + math-intrinsics@1.1.0: + resolution: {integrity: sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==} + engines: {node: '>= 0.4'} + mdast-util-to-hast@13.2.1: resolution: {integrity: sha512-cctsq2wp5vTsLIcaymblUriiTcZd0CwWtCbLvrOzYCDZoWyMNV8sZ7krj09FSnsiJi3WVsHLM4k6Dq/yaPyCXA==} mdn-data@2.12.2: resolution: {integrity: sha512-IEn+pegP1aManZuckezWCO+XZQDplx1366JoVhTpMpBB1sPey/SbveZQUosKiKiGYjg1wH4pMlNgXbCiYgihQA==} + media-typer@0.3.0: + resolution: {integrity: sha512-dq+qelQ9akHpcOl/gUVRTxVIOkAJ1wR3QAvb4RsVjS8oVoFjDGTc679wJYmUmknUF5HwMLOgb5O+a3KxfWapPQ==} + engines: {node: '>= 0.6'} + + merge-descriptors@1.0.3: + resolution: {integrity: sha512-gaNvAS7TZ897/rVaZ0nMtAyxNyi/pdbjbAwUpFQpN70GqnVfOiXpeUUMKRBmzXaSQ8DdTX4/0ms62r2K+hE6mQ==} + + methods@1.1.2: + resolution: {integrity: sha512-iclAHeNqNm68zFtnZ0e+1L2yUIdvzNoauKU4WBA3VvH/vPFieF7qfRlwUZU+DA9P9bPXIS90ulxoUoCH23sV2w==} + engines: {node: '>= 0.6'} + micromark-util-character@2.1.1: resolution: {integrity: sha512-wv8tdUTJ3thSFFFJKtpYKOYiGP2+v96Hvk4Tu8KpCAsTMs6yi+nVmGh1syvSCsaxz45J6Jbw+9DD6g97+NV67Q==} @@ -1874,6 +2436,23 @@ packages: micromark-util-types@2.0.2: resolution: {integrity: sha512-Yw0ECSpJoViF1qTU4DC6NwtC4aWGt1EkzaQB8KPPyCRR8z9TWeV0HbEFGTO+ZY1wB22zmxnJqhPyTpOVCpeHTA==} + mime-db@1.52.0: + resolution: {integrity: sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==} + engines: {node: '>= 0.6'} + + mime-db@1.54.0: + resolution: {integrity: sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==} + engines: {node: '>= 0.6'} + + mime-types@2.1.35: + resolution: {integrity: sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==} + engines: {node: '>= 0.6'} + + mime@1.6.0: + resolution: {integrity: sha512-x0Vn8spI+wuJ1O6S7gnbaQg8Pxh4NNHb7KSINmEWKiPE4RKOplvijn+NkmYmmRgP68mc70j2EbeTFRsrswaQeg==} + engines: {node: '>=4'} + hasBin: true + minisearch@7.2.0: resolution: {integrity: sha512-dqT2XBYUOZOiC5t2HRnwADjhNS2cecp9u+TJRiJ1Qp/f5qjkeT5APcGPjHw+bz89Ms8Jp+cG4AlE+QZ/QnDglg==} @@ -1883,10 +2462,17 @@ packages: mlly@1.8.0: resolution: {integrity: sha512-l8D9ODSRWLe2KHJSifWGwBqpTZXIXTeo8mlKjY+E2HAakaTeNpqAyBZ8GSqLzHgw4XmHmC8whvpjJNMbFZN7/g==} + morgan@1.10.1: + resolution: {integrity: sha512-223dMRJtI/l25dJKWpgij2cMtywuG/WiUKXdvwfbhGKBhy1puASqXwFzmWZ7+K73vUPoR7SS2Qz2cI/g9MKw0A==} + engines: {node: '>= 0.8.0'} + mrmime@2.0.1: resolution: {integrity: sha512-Y3wQdFg2Va6etvQ5I82yUhGdsKrcYox6p7FfL1LbK2J4V01F9TGlepTIhnK24t7koZibmg82KGglhA1XK5IsLQ==} engines: {node: '>=10'} + ms@2.0.0: + resolution: {integrity: sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==} + ms@2.1.3: resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==} @@ -1898,6 +2484,14 @@ packages: engines: {node: ^10 || ^12 || ^13.7 || ^14 || >=15.0.1} hasBin: true + negotiator@0.6.3: + resolution: {integrity: sha512-+EUsqGPLsM+j/zdChZjsnX51g4XrHFOIXwfnCVPGlQk/k5giakcKsuxCObBRu6DSm9opw/O6slWbJdghQM4bBg==} + engines: {node: '>= 0.6'} + + negotiator@0.6.4: + resolution: {integrity: sha512-myRT3DiWPHqho5PrJaIRyaMv2kgYf0mUVgBNOYMuCH5Ki1yEiQaf/ZJuQ62nvpc44wL5WDbTX7yGJi1Neevw8w==} + engines: {node: '>= 0.6'} + node-domexception@1.0.0: resolution: {integrity: sha512-/jKZoMpw0F8GRwl4/eLROPA3cfcXtLApP0QzLmUT/HuPCZWyB7IY9ZrMeKw2O/nFIqPQB3PVM9aYm0F312AXDQ==} engines: {node: '>=10.5.0'} @@ -1914,15 +2508,45 @@ packages: resolution: {integrity: sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==} engines: {node: '>=0.10.0'} + object-inspect@1.13.4: + resolution: {integrity: sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==} + engines: {node: '>= 0.4'} + obug@2.1.1: resolution: {integrity: sha512-uTqF9MuPraAQ+IsnPf366RG4cP9RtUi7MLO1N3KEc+wb0a6yKpeL0lmk2IB1jY5KHPAlTc6T/JRdC/YqxHNwkQ==} + on-finished@2.3.0: + resolution: {integrity: sha512-ikqdkGAAyf/X/gPhXGvfgAytDZtDbr+bkNUJ0N9h5MI/dmdgCs3l6hoHrcUv41sRKew3jIwrp4qQDXiK99Utww==} + engines: {node: '>= 0.8'} + + on-finished@2.4.1: + resolution: {integrity: sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==} + engines: {node: '>= 0.8'} + + on-headers@1.1.0: + resolution: {integrity: sha512-737ZY3yNnXy37FHkQxPzt4UZ2UWPWiCZWLvFZ4fu5cueciegX0zGPnrlY6bwRg4FdQOe9YU8MkmJwGhoMybl8A==} + engines: {node: '>= 0.8'} + oniguruma-to-es@3.1.1: resolution: {integrity: sha512-bUH8SDvPkH3ho3dvwJwfonjlQ4R80vjyvrU8YpxuROddv55vAEJrTuCuCVUhhsHbtlD9tGGbaNApGQckXhS8iQ==} + p-map@7.0.4: + resolution: {integrity: sha512-tkAQEw8ysMzmkhgw8k+1U/iPhWNhykKnSk4Rd5zLoPJCuJaGRPo6YposrZgaxHKzDHdDWWZvE/Sk7hsL2X/CpQ==} + engines: {node: '>=18'} + parse5@8.0.0: resolution: {integrity: sha512-9m4m5GSgXjL4AjumKzq1Fgfp3Z8rsvjRNbnkVwfu2ImRqE5D0LnY2QfDen18FSY9C573YU5XxSapdHZTZ2WolA==} + parseurl@1.3.3: + resolution: {integrity: sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==} + engines: {node: '>= 0.8'} + + path-to-regexp@0.1.12: + resolution: {integrity: sha512-RA1GjUVMnvYFxuqovrEqZoxxW5NUZqbwKtYz/Tt7nXerk0LbLblQmrsgdeOxV5SFHf0UDggjS/bSeOZwt1pmEQ==} + + pathe@1.1.2: + resolution: {integrity: sha512-whLdWMYL2TwI08hn8/ZqAbrVemu0LNaNNJZX73O6qaIdCTfXutsLhMkjdENX0qhsQ9uIimo4/aQOmXkoon2nDQ==} + pathe@2.0.3: resolution: {integrity: sha512-WUjGcAqP1gQacoQe+OBJsFA7Ld4DyXuUIjZ5cc75cLHvJ7dtNsTugphxIADwspS+AraAUePCKrSVtPLFj/F88w==} @@ -1947,6 +2571,9 @@ packages: pkg-types@1.3.1: resolution: {integrity: sha512-/Jm5M4RvtBFVkKWRu2BLUTNP8/M2a+UwuAX+ae4770q1qVGtfjG+WTCupoZixokjmHiry8uI+dlY8KXYV5HVVQ==} + pkg-types@2.3.0: + resolution: {integrity: sha512-SIqCzDRg0s9npO5XQ3tNZioRY1uK06lA41ynBC1YmFTmnY6FjUjVt6s4LoADmwoig1qqD0oK8h1p/8mlMx8Oig==} + playwright-core@1.57.0: resolution: {integrity: sha512-agTcKlMw/mjBWOnD6kFZttAAGHgi/Nw0CZ2o6JqWSbMlI219lAFLZZCyqByTsvVAJq5XA5H8cA6PrvBRpBWEuQ==} engines: {node: '>=18'} @@ -2011,6 +2638,10 @@ packages: property-information@7.1.0: resolution: {integrity: sha512-TwEZ+X+yCJmYfL7TPUOcvBZ4QfoT5YenQiJuX//0th53DE6w0xxLEtfK3iyryQFddXuvkIk51EEgrJQ0WJkOmQ==} + proxy-addr@2.0.7: + resolution: {integrity: sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==} + engines: {node: '>= 0.10'} + proxy-target@3.0.2: resolution: {integrity: sha512-FFE1XNwXX/FNC3/P8HiKaJSy/Qk68RitG/QEcLy/bVnTAPlgTAWPZKh0pARLAnpfXQPKyalBhk009NRTgsk8vQ==} @@ -2018,6 +2649,18 @@ packages: resolution: {integrity: sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg==} engines: {node: '>=6'} + qs@6.14.1: + resolution: {integrity: sha512-4EK3+xJl8Ts67nLYNwqw/dsFVnCf+qR7RgXSK9jEEm9unao3njwMDdmsdvoKBKHzxd7tCYz5e5M+SnMjdtXGQQ==} + engines: {node: '>=0.6'} + + range-parser@1.2.1: + resolution: {integrity: sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==} + engines: {node: '>= 0.6'} + + raw-body@2.5.3: + resolution: {integrity: sha512-s4VSOf6yN0rvbRZGxs8Om5CWj6seneMwK3oDb4lWDH0UPhWcxwOWw5+qk24bxq87szX1ydrwylIOp2uG1ojUpA==} + engines: {node: '>= 0.8'} + react-dom@19.2.3: resolution: {integrity: sha512-yELu4WmLPw5Mr/lmeEpox5rw3RETacE++JgHqQzd2dg+YbJuat3jH4ingc+WPZhxaoFzdv9y33G+F7Nl5O0GBg==} peerDependencies: @@ -2026,10 +2669,24 @@ packages: react-is@17.0.2: resolution: {integrity: sha512-w2GsyukL62IJnlaff/nRegPQR94C/XXamvMWmSHRJ4y7Ts/4ocGRmTHvOs8PSE6pB3dWOrD/nueuU5sduBsQ4w==} + react-refresh@0.14.2: + resolution: {integrity: sha512-jCvmsr+1IUSMUyzOkRcvnVbX3ZYC6g9TDrDbFuFmRDq7PD4yaGbLKNQL6k2jnArV8hjYxh7hVhAZB6s9HDGpZA==} + engines: {node: '>=0.10.0'} + react-refresh@0.18.0: resolution: {integrity: sha512-QgT5//D3jfjJb6Gsjxv0Slpj23ip+HtOpnNgnb2S5zU3CB26G/IDPGoy4RJB42wzFE46DRsstbW6tKHoKbhAxw==} engines: {node: '>=0.10.0'} + react-router@7.11.0: + resolution: {integrity: sha512-uI4JkMmjbWCZc01WVP2cH7ZfSzH91JAZUDd7/nIprDgWxBV1TkkmLToFh7EbMTcMak8URFRa2YoBL/W8GWnCTQ==} + engines: {node: '>=20.0.0'} + peerDependencies: + react: '>=18' + react-dom: '>=18' + peerDependenciesMeta: + react-dom: + optional: true + react@19.2.3: resolution: {integrity: sha512-Ku/hhYbVjOQnXDZFv2+RibmLFGwFdeeKHFcOTlrt7xplBnya5OGn/hIRDsqDiSUcfORsDC7MPxwork8jBwsIWA==} engines: {node: '>=0.10.0'} @@ -2066,6 +2723,12 @@ packages: engines: {node: '>=18.0.0', npm: '>=8.0.0'} hasBin: true + safe-buffer@5.1.2: + resolution: {integrity: sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==} + + safe-buffer@5.2.1: + resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==} + safer-buffer@2.1.2: resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==} @@ -2088,9 +2751,39 @@ packages: engines: {node: '>=10'} hasBin: true + send@0.19.2: + resolution: {integrity: sha512-VMbMxbDeehAxpOtWJXlcUS5E8iXh6QmN+BkRX1GARS3wRaXEEgzCcB10gTQazO42tpNIya8xIyNx8fll1OFPrg==} + engines: {node: '>= 0.8.0'} + + serve-static@1.16.3: + resolution: {integrity: sha512-x0RTqQel6g5SY7Lg6ZreMmsOzncHFU7nhnRWkKgWuMTu5NN0DR5oruckMqRvacAN9d5w6ARnRBXl9xhDCgfMeA==} + engines: {node: '>= 0.8.0'} + + set-cookie-parser@2.7.2: + resolution: {integrity: sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==} + + setprototypeof@1.2.0: + resolution: {integrity: sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==} + shiki@2.5.0: resolution: {integrity: sha512-mI//trrsaiCIPsja5CNfsyNOqgAZUb6VpJA+340toL42UpzQlXpwRV9nch69X6gaUxrr9kaOOa6e3y3uAkGFxQ==} + side-channel-list@1.0.0: + resolution: {integrity: sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==} + engines: {node: '>= 0.4'} + + side-channel-map@1.0.1: + resolution: {integrity: sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==} + engines: {node: '>= 0.4'} + + side-channel-weakmap@1.0.2: + resolution: {integrity: sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==} + engines: {node: '>= 0.4'} + + side-channel@1.1.0: + resolution: {integrity: sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==} + engines: {node: '>= 0.4'} + siginfo@2.0.0: resolution: {integrity: sha512-ybx0WO1/8bSBLEWXZvEd7gMW3Sn3JFlW3TvX1nREbDLRNQNaeNN8WK0meBwPdAaOI7TtRRRJn/Es1zhrrCHu7g==} @@ -2102,6 +2795,13 @@ packages: resolution: {integrity: sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==} engines: {node: '>=0.10.0'} + source-map-support@0.5.21: + resolution: {integrity: sha512-uBHU3L3czsIyYXKX88fdrGovxdSCoTGDRZ6SYXtSRxLZUzHg5P/66Ht6uoUlHu9EZod+inXhKo3qQgwXUT/y1w==} + + source-map@0.6.1: + resolution: {integrity: sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==} + engines: {node: '>=0.10.0'} + source-map@0.7.6: resolution: {integrity: sha512-i5uvt8C3ikiWeNZSVZNWcfZPItFQOsYTUAOkcUPGd8DqDy1uOUikjt5dG+uRlwyvR108Fb9DOd4GvXfT0N2/uQ==} engines: {node: '>= 12'} @@ -2139,6 +2839,10 @@ packages: stackback@0.0.2: resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==} + statuses@2.0.2: + resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==} + engines: {node: '>= 0.8'} + std-env@3.10.0: resolution: {integrity: sha512-5GS12FdOZNliM5mAOxFRg7Ir0pWz8MdpYm6AY6VPkGpbA7ZzmbzNcBJQ0GPvvyWgcY7QAhCgf9Uy89I03faLkg==} @@ -2164,6 +2868,13 @@ packages: tabbable@6.3.0: resolution: {integrity: sha512-EIHvdY5bPLuWForiR/AN2Bxngzpuwn1is4asboytXtpTgsArc+WmSJKVLlhdh71u7jFcryDqB2A8lQvj78MkyQ==} + tailwindcss@4.1.18: + resolution: {integrity: sha512-4+Z+0yiYyEtUVCScyfHCxOYP06L5Ne+JiHhY2IjR2KWMIWhJOYZKLSGZaP5HkZ8+bY0cxfzwDE5uOmzFXyIwxw==} + + tapable@2.3.0: + resolution: {integrity: sha512-g9ljZiwki/LfxmQADO3dEY1CbpmXT5Hm2fJ+QaGKwSXUylMybePR7/67YW7jOrrvjEgL1Fmz5kzyAjWVWLlucg==} + engines: {node: '>=6'} + thenify-all@1.6.0: resolution: {integrity: sha512-RNxQH/qI8/t3thXJDwcstUO4zeqo64+Uy/+sNVRBx4Xn2OX+OZ9oP+iJnNFqplFra2ZUVeKCSa2oVWi3T4uVmA==} engines: {node: '>=0.8'} @@ -2196,6 +2907,10 @@ packages: resolution: {integrity: sha512-8PWx8tvC4jDB39BQw1m4x8y5MH1BcQ5xHeL2n7UVFulMPH/3Q0uiamahFJ3lXA0zO2SUyRXuVVbWSDmstlt9YA==} hasBin: true + toidentifier@1.0.1: + resolution: {integrity: sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==} + engines: {node: '>=0.6'} + totalist@3.0.1: resolution: {integrity: sha512-sf4i37nQ2LBx4m3wB74y+ubopq6W/dIzXg0FDGjsYnZHVa1Da8FH853wlL2gtUhg+xJXjfk3kUZS3BRoQeoQBQ==} engines: {node: '>=6'} @@ -2218,6 +2933,16 @@ packages: ts-interface-checker@0.1.13: resolution: {integrity: sha512-Y/arvbn+rrz3JCKl9C4kVNfTfSm2/mEp5FSz5EsZSANGPSlQrpRI5M4PKF+mJnE52jOO90PnPSc3Ur3bTQw0gA==} + tsconfck@3.1.6: + resolution: {integrity: sha512-ks6Vjr/jEw0P1gmOVwutM3B7fWxoWBL2KRDb1JfqGVawBmO5UsvmWOQFGHBPl5yxYz4eERr19E6L7NMv+Fej4w==} + engines: {node: ^18 || >=20} + hasBin: true + peerDependencies: + typescript: ^5.0.0 + peerDependenciesMeta: + typescript: + optional: true + tsup@8.5.1: resolution: {integrity: sha512-xtgkqwdhpKWr3tKPmCkvYmS9xnQK3m3XgxZHwSUjvfTjp7YfXe5tT3GgWi0F2N+ZSMsOeWeZFh7ZZFg5iPhing==} engines: {node: '>=18'} @@ -2276,6 +3001,10 @@ packages: resolution: {integrity: sha512-5JIA5aYBAJSAhrhbyag1ZuMSgUZnHtI+Sq3H8D3an4fL8PeF+L1yYvbEJg47akP1PFfATMf5ehkqFnxfkmuwZQ==} hasBin: true + type-is@1.6.18: + resolution: {integrity: sha512-TkRKr9sUTxEH8MdfuCSP7VizJyzRNMjj2J2do2Jr3Kym598JVdEksuzPQCnlFPW4ky9Q+iA+ma9BGm06XQBy8g==} + engines: {node: '>= 0.6'} + typescript@5.9.3: resolution: {integrity: sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==} engines: {node: '>=14.17'} @@ -2306,12 +3035,20 @@ packages: unist-util-visit@5.0.0: resolution: {integrity: sha512-MR04uvD+07cwl/yhVuVWAtw+3GOR/knlL55Nd/wAdblk27GCVt3lqpTivy/tkJcZoNPzTwS1Y+KMojlLDhoTzg==} + unpipe@1.0.0: + resolution: {integrity: sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==} + engines: {node: '>= 0.8'} + update-browserslist-db@1.2.3: resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==} hasBin: true peerDependencies: browserslist: '>= 4.21.0' + utils-merge@1.0.1: + resolution: {integrity: sha512-pMZTvIkT1d+TFGvDOqodOclx0QWkkgi6Tdoa8gC8ffGAAqz9pzPTZWAybbsHHoED/ztMtkv/VoYTYyShUn81hA==} + engines: {node: '>= 0.4.0'} + valibot@1.2.0: resolution: {integrity: sha512-mm1rxUsmOxzrwnX5arGS+U4T25RdvpPjPN4yR0u9pUBov9+zGVtO84tif1eY4r6zWxVxu3KzIyknJy3rxfRZZg==} peerDependencies: @@ -2320,12 +3057,29 @@ packages: typescript: optional: true + vary@1.1.2: + resolution: {integrity: sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==} + engines: {node: '>= 0.8'} + vfile-message@4.0.3: resolution: {integrity: sha512-QTHzsGd1EhbZs4AsQ20JX1rC3cOlt/IWJruk893DfLRr57lcnOeMaWG4K0JrRta4mIJZKth2Au3mM3u03/JWKw==} vfile@6.0.3: resolution: {integrity: sha512-KzIbH/9tXat2u30jf+smMwFCsno4wHVdNmzFyL+T/L3UGqqk6JKfVqOFOZEpZSHADH1k40ab6NUIXZq422ov3Q==} + vite-node@3.2.4: + resolution: {integrity: sha512-EbKSKh+bh1E1IFxeO0pg1n4dvoOTt0UDiXMd/qn++r98+jPO1xtJilvXldeuQ8giIB5IkpjCgMleHMNEsGH6pg==} + engines: {node: ^18.0.0 || ^20.0.0 || >=22.0.0} + hasBin: true + + vite-tsconfig-paths@6.0.3: + resolution: {integrity: sha512-7bL7FPX/DSviaZGYUKowWF1AiDVWjMjxNbE8lyaVGDezkedWqfGhlnQ4BZXre0ZN5P4kAgIJfAlgFDVyjrCIyg==} + peerDependencies: + vite: '*' + peerDependenciesMeta: + vite: + optional: true + vite@5.4.21: resolution: {integrity: sha512-o5a9xKjbtuhY6Bi5S3+HvbRERmouabWbyUcpXXUA1u+GNUKoROi9byOJ8M0nHbHYHkYICiMlqxkg1KkYmm25Sw==} engines: {node: ^18.0.0 || >=20.0.0} @@ -2689,7 +3443,11 @@ snapshots: '@babel/types': 7.28.5 '@jridgewell/gen-mapping': 0.3.13 '@jridgewell/trace-mapping': 0.3.31 - jsesc: 3.1.0 + jsesc: 3.0.2 + + '@babel/helper-annotate-as-pure@7.27.3': + dependencies: + '@babel/types': 7.28.5 '@babel/helper-compilation-targets@7.27.2': dependencies: @@ -2699,8 +3457,28 @@ snapshots: lru-cache: 5.1.1 semver: 6.3.1 + '@babel/helper-create-class-features-plugin@7.28.5(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-annotate-as-pure': 7.27.3 + '@babel/helper-member-expression-to-functions': 7.28.5 + '@babel/helper-optimise-call-expression': 7.27.1 + '@babel/helper-replace-supers': 7.27.1(@babel/core@7.28.5) + '@babel/helper-skip-transparent-expression-wrappers': 7.27.1 + '@babel/traverse': 7.28.5 + semver: 6.3.1 + transitivePeerDependencies: + - supports-color + '@babel/helper-globals@7.28.0': {} + '@babel/helper-member-expression-to-functions@7.28.5': + dependencies: + '@babel/traverse': 7.28.5 + '@babel/types': 7.28.5 + transitivePeerDependencies: + - supports-color + '@babel/helper-module-imports@7.27.1': dependencies: '@babel/traverse': 7.28.5 @@ -2717,8 +3495,28 @@ snapshots: transitivePeerDependencies: - supports-color + '@babel/helper-optimise-call-expression@7.27.1': + dependencies: + '@babel/types': 7.28.5 + '@babel/helper-plugin-utils@7.27.1': {} + '@babel/helper-replace-supers@7.27.1(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-member-expression-to-functions': 7.28.5 + '@babel/helper-optimise-call-expression': 7.27.1 + '@babel/traverse': 7.28.5 + transitivePeerDependencies: + - supports-color + + '@babel/helper-skip-transparent-expression-wrappers@7.27.1': + dependencies: + '@babel/traverse': 7.28.5 + '@babel/types': 7.28.5 + transitivePeerDependencies: + - supports-color + '@babel/helper-string-parser@7.27.1': {} '@babel/helper-validator-identifier@7.28.5': {} @@ -2734,6 +3532,24 @@ snapshots: dependencies: '@babel/types': 7.28.5 + '@babel/plugin-syntax-jsx@7.27.1(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-plugin-utils': 7.27.1 + + '@babel/plugin-syntax-typescript@7.27.1(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-plugin-utils': 7.27.1 + + '@babel/plugin-transform-modules-commonjs@7.27.1(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-module-transforms': 7.28.3(@babel/core@7.28.5) + '@babel/helper-plugin-utils': 7.27.1 + transitivePeerDependencies: + - supports-color + '@babel/plugin-transform-react-jsx-self@7.27.1(@babel/core@7.28.5)': dependencies: '@babel/core': 7.28.5 @@ -2744,6 +3560,28 @@ snapshots: '@babel/core': 7.28.5 '@babel/helper-plugin-utils': 7.27.1 + '@babel/plugin-transform-typescript@7.28.5(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-annotate-as-pure': 7.27.3 + '@babel/helper-create-class-features-plugin': 7.28.5(@babel/core@7.28.5) + '@babel/helper-plugin-utils': 7.27.1 + '@babel/helper-skip-transparent-expression-wrappers': 7.27.1 + '@babel/plugin-syntax-typescript': 7.27.1(@babel/core@7.28.5) + transitivePeerDependencies: + - supports-color + + '@babel/preset-typescript@7.28.5(@babel/core@7.28.5)': + dependencies: + '@babel/core': 7.28.5 + '@babel/helper-plugin-utils': 7.27.1 + '@babel/helper-validator-option': 7.27.1 + '@babel/plugin-syntax-jsx': 7.27.1(@babel/core@7.28.5) + '@babel/plugin-transform-modules-commonjs': 7.27.1(@babel/core@7.28.5) + '@babel/plugin-transform-typescript': 7.28.5(@babel/core@7.28.5) + transitivePeerDependencies: + - supports-color + '@babel/runtime@7.28.4': {} '@babel/template@7.27.2': @@ -3201,10 +4039,94 @@ snapshots: '@libsql/win32-x64-msvc@0.5.22': optional: true + '@mjackson/node-fetch-server@0.2.0': {} + '@neon-rs/load@0.0.4': {} '@polka/url@1.0.0-next.29': {} + '@react-router/dev@7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))': + dependencies: + '@babel/core': 7.28.5 + '@babel/generator': 7.28.5 + '@babel/parser': 7.28.5 + '@babel/plugin-syntax-jsx': 7.27.1(@babel/core@7.28.5) + '@babel/preset-typescript': 7.28.5(@babel/core@7.28.5) + '@babel/traverse': 7.28.5 + '@babel/types': 7.28.5 + '@react-router/node': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + '@remix-run/node-fetch-server': 0.9.0 + arg: 5.0.2 + babel-dead-code-elimination: 1.0.11 + chokidar: 4.0.3 + dedent: 1.7.1 + es-module-lexer: 1.7.0 + exit-hook: 2.2.1 + isbot: 5.1.32 + jsesc: 3.0.2 + lodash: 4.17.21 + p-map: 7.0.4 + pathe: 1.1.2 + picocolors: 1.1.1 + pkg-types: 2.3.0 + prettier: 3.7.4 + react-refresh: 0.14.2 + react-router: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + semver: 7.7.3 + tinyglobby: 0.2.15 + valibot: 1.2.0(typescript@5.9.3) + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + vite-node: 3.2.4(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + optionalDependencies: + '@react-router/serve': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + typescript: 5.9.3 + transitivePeerDependencies: + - '@types/node' + - babel-plugin-macros + - jiti + - less + - lightningcss + - sass + - sass-embedded + - stylus + - sugarss + - supports-color + - terser + - tsx + - yaml + + '@react-router/express@7.11.0(express@4.22.1)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)': + dependencies: + '@react-router/node': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + express: 4.22.1 + react-router: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + optionalDependencies: + typescript: 5.9.3 + + '@react-router/node@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)': + dependencies: + '@mjackson/node-fetch-server': 0.2.0 + react-router: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + optionalDependencies: + typescript: 5.9.3 + + '@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)': + dependencies: + '@mjackson/node-fetch-server': 0.2.0 + '@react-router/express': 7.11.0(express@4.22.1)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + '@react-router/node': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3) + compression: 1.8.1 + express: 4.22.1 + get-port: 5.1.1 + morgan: 1.10.1 + react-router: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3) + source-map-support: 0.5.21 + transitivePeerDependencies: + - supports-color + - typescript + + '@remix-run/node-fetch-server@0.9.0': {} + '@rolldown/pluginutils@1.0.0-beta.53': {} '@rollup/rollup-android-arm-eabi@4.54.0': @@ -3317,6 +4239,74 @@ snapshots: '@standard-schema/spec@1.1.0': {} + '@tailwindcss/node@4.1.18': + dependencies: + '@jridgewell/remapping': 2.3.5 + enhanced-resolve: 5.18.4 + jiti: 2.6.1 + lightningcss: 1.30.2 + magic-string: 0.30.21 + source-map-js: 1.2.1 + tailwindcss: 4.1.18 + + '@tailwindcss/oxide-android-arm64@4.1.18': + optional: true + + '@tailwindcss/oxide-darwin-arm64@4.1.18': + optional: true + + '@tailwindcss/oxide-darwin-x64@4.1.18': + optional: true + + '@tailwindcss/oxide-freebsd-x64@4.1.18': + optional: true + + '@tailwindcss/oxide-linux-arm-gnueabihf@4.1.18': + optional: true + + '@tailwindcss/oxide-linux-arm64-gnu@4.1.18': + optional: true + + '@tailwindcss/oxide-linux-arm64-musl@4.1.18': + optional: true + + '@tailwindcss/oxide-linux-x64-gnu@4.1.18': + optional: true + + '@tailwindcss/oxide-linux-x64-musl@4.1.18': + optional: true + + '@tailwindcss/oxide-wasm32-wasi@4.1.18': + optional: true + + '@tailwindcss/oxide-win32-arm64-msvc@4.1.18': + optional: true + + '@tailwindcss/oxide-win32-x64-msvc@4.1.18': + optional: true + + '@tailwindcss/oxide@4.1.18': + optionalDependencies: + '@tailwindcss/oxide-android-arm64': 4.1.18 + '@tailwindcss/oxide-darwin-arm64': 4.1.18 + '@tailwindcss/oxide-darwin-x64': 4.1.18 + '@tailwindcss/oxide-freebsd-x64': 4.1.18 + '@tailwindcss/oxide-linux-arm-gnueabihf': 4.1.18 + '@tailwindcss/oxide-linux-arm64-gnu': 4.1.18 + '@tailwindcss/oxide-linux-arm64-musl': 4.1.18 + '@tailwindcss/oxide-linux-x64-gnu': 4.1.18 + '@tailwindcss/oxide-linux-x64-musl': 4.1.18 + '@tailwindcss/oxide-wasm32-wasi': 4.1.18 + '@tailwindcss/oxide-win32-arm64-msvc': 4.1.18 + '@tailwindcss/oxide-win32-x64-msvc': 4.1.18 + + '@tailwindcss/vite@4.1.18(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))': + dependencies: + '@tailwindcss/node': 4.1.18 + '@tailwindcss/oxide': 4.1.18 + tailwindcss: 4.1.18 + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + '@testing-library/dom@10.4.1': dependencies: '@babel/code-frame': 7.27.1 @@ -3411,7 +4401,7 @@ snapshots: '@ungap/with-resolvers@0.1.0': {} - '@vitejs/plugin-react@5.1.2(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))': + '@vitejs/plugin-react@5.1.2(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))': dependencies: '@babel/core': 7.28.5 '@babel/plugin-transform-react-jsx-self': 7.27.1(@babel/core@7.28.5) @@ -3419,38 +4409,38 @@ snapshots: '@rolldown/pluginutils': 1.0.0-beta.53 '@types/babel__core': 7.20.5 react-refresh: 0.18.0 - vite: 7.3.0(@types/node@25.0.3)(tsx@4.21.0) + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) transitivePeerDependencies: - supports-color - '@vitejs/plugin-vue@5.2.4(vite@5.4.21(@types/node@25.0.3))(vue@3.5.26(typescript@5.9.3))': + '@vitejs/plugin-vue@5.2.4(vite@5.4.21(@types/node@25.0.3)(lightningcss@1.30.2))(vue@3.5.26(typescript@5.9.3))': dependencies: - vite: 5.4.21(@types/node@25.0.3) + vite: 5.4.21(@types/node@25.0.3)(lightningcss@1.30.2) vue: 3.5.26(typescript@5.9.3) - '@vitest/browser-playwright@4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16)': + '@vitest/browser-playwright@4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16)': dependencies: - '@vitest/browser': 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) - '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + '@vitest/browser': 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) + '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) playwright: 1.57.0 tinyrainbow: 3.0.3 - vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.3.0)(lightningcss@1.30.2)(tsx@4.21.0) transitivePeerDependencies: - bufferutil - msw - utf-8-validate - vite - '@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16)': + '@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16)': dependencies: - '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) '@vitest/utils': 4.0.16 magic-string: 0.30.21 pixelmatch: 7.1.0 pngjs: 7.0.0 sirv: 3.0.2 tinyrainbow: 3.0.3 - vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.3.0)(lightningcss@1.30.2)(tsx@4.21.0) ws: 8.18.3 transitivePeerDependencies: - bufferutil @@ -3458,7 +4448,7 @@ snapshots: - utf-8-validate - vite - '@vitest/coverage-v8@4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16)': + '@vitest/coverage-v8@4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16)': dependencies: '@bcoe/v8-coverage': 1.0.2 '@vitest/utils': 4.0.16 @@ -3471,9 +4461,9 @@ snapshots: obug: 2.1.1 std-env: 3.10.0 tinyrainbow: 3.0.3 - vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0) + vitest: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.3.0)(lightningcss@1.30.2)(tsx@4.21.0) optionalDependencies: - '@vitest/browser': 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + '@vitest/browser': 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) transitivePeerDependencies: - supports-color @@ -3486,13 +4476,13 @@ snapshots: chai: 6.2.1 tinyrainbow: 3.0.3 - '@vitest/mocker@4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))': + '@vitest/mocker@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))': dependencies: '@vitest/spy': 4.0.16 estree-walker: 3.0.3 magic-string: 0.30.21 optionalDependencies: - vite: 7.3.0(@types/node@25.0.3)(tsx@4.21.0) + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) '@vitest/pretty-format@4.0.16': dependencies: @@ -3615,6 +4605,11 @@ snapshots: transitivePeerDependencies: - typescript + accepts@1.3.8: + dependencies: + mime-types: 2.1.35 + negotiator: 0.6.3 + acorn@8.15.0: {} agent-base@7.1.4: {} @@ -3642,10 +4637,14 @@ snapshots: any-promise@1.3.0: {} + arg@5.0.2: {} + aria-query@5.3.0: dependencies: dequal: 2.0.3 + array-flatten@1.1.1: {} + assertion-error@2.0.1: {} ast-v8-to-istanbul@0.3.10: @@ -3654,30 +4653,74 @@ snapshots: estree-walker: 3.0.3 js-tokens: 9.0.1 + babel-dead-code-elimination@1.0.11: + dependencies: + '@babel/core': 7.28.5 + '@babel/parser': 7.28.5 + '@babel/traverse': 7.28.5 + '@babel/types': 7.28.5 + transitivePeerDependencies: + - supports-color + baseline-browser-mapping@2.9.11: {} + basic-auth@2.0.1: + dependencies: + safe-buffer: 5.1.2 + bidi-js@1.0.3: dependencies: require-from-string: 2.0.2 birpc@2.9.0: {} + body-parser@1.20.4: + dependencies: + bytes: 3.1.2 + content-type: 1.0.5 + debug: 2.6.9 + depd: 2.0.0 + destroy: 1.2.0 + http-errors: 2.0.1 + iconv-lite: 0.4.24 + on-finished: 2.4.1 + qs: 6.14.1 + raw-body: 2.5.3 + type-is: 1.6.18 + unpipe: 1.0.0 + transitivePeerDependencies: + - supports-color + browserslist@4.28.1: dependencies: baseline-browser-mapping: 2.9.11 - caniuse-lite: 1.0.30001761 + caniuse-lite: 1.0.30001762 electron-to-chromium: 1.5.267 node-releases: 2.0.27 update-browserslist-db: 1.2.3(browserslist@4.28.1) + buffer-from@1.1.2: {} + bundle-require@5.1.0(esbuild@0.27.2): dependencies: esbuild: 0.27.2 load-tsconfig: 0.2.5 + bytes@3.1.2: {} + cac@6.7.14: {} - caniuse-lite@1.0.30001761: {} + call-bind-apply-helpers@1.0.2: + dependencies: + es-errors: 1.3.0 + function-bind: 1.1.2 + + call-bound@1.0.4: + dependencies: + call-bind-apply-helpers: 1.0.2 + get-intrinsic: 1.3.0 + + caniuse-lite@1.0.30001762: {} cc-hooks-ts@2.0.70(typescript@5.9.3)(zod@4.2.1): dependencies: @@ -3715,12 +4758,42 @@ snapshots: commander@4.1.1: {} + compressible@2.0.18: + dependencies: + mime-db: 1.54.0 + + compression@1.8.1: + dependencies: + bytes: 3.1.2 + compressible: 2.0.18 + debug: 2.6.9 + negotiator: 0.6.4 + on-headers: 1.1.0 + safe-buffer: 5.2.1 + vary: 1.1.2 + transitivePeerDependencies: + - supports-color + confbox@0.1.8: {} + confbox@0.2.2: {} + consola@3.4.2: {} + content-disposition@0.5.4: + dependencies: + safe-buffer: 5.2.1 + + content-type@1.0.5: {} + convert-source-map@2.0.0: {} + cookie-signature@1.0.7: {} + + cookie@0.7.2: {} + + cookie@1.1.1: {} + copy-anything@4.0.5: dependencies: is-what: 5.5.0 @@ -3745,32 +4818,67 @@ snapshots: whatwg-mimetype: 4.0.0 whatwg-url: 15.1.0 + debug@2.6.9: + dependencies: + ms: 2.0.0 + debug@4.4.3: dependencies: ms: 2.1.3 decimal.js@10.6.0: {} + dedent@1.7.1: {} + + depd@2.0.0: {} + dequal@2.0.3: {} + destroy@1.2.0: {} + detect-libc@2.0.2: {} + detect-libc@2.1.2: {} + devlop@1.1.0: dependencies: dequal: 2.0.3 dom-accessibility-api@0.5.16: {} + dunder-proto@1.0.1: + dependencies: + call-bind-apply-helpers: 1.0.2 + es-errors: 1.3.0 + gopd: 1.2.0 + + ee-first@1.1.1: {} + electron-to-chromium@1.5.267: {} emoji-regex-xs@1.0.0: {} + encodeurl@2.0.0: {} + + enhanced-resolve@5.18.4: + dependencies: + graceful-fs: 4.2.11 + tapable: 2.3.0 + entities@6.0.1: {} entities@7.0.0: {} + es-define-property@1.0.1: {} + + es-errors@1.3.0: {} + es-module-lexer@1.7.0: {} + es-object-atoms@1.1.1: + dependencies: + es-errors: 1.3.0 + esbuild@0.21.5: optionalDependencies: '@esbuild/aix-ppc64': 0.21.5 @@ -3828,14 +4936,58 @@ snapshots: escalade@3.2.0: {} + escape-html@1.0.3: {} + estree-walker@2.0.2: {} estree-walker@3.0.3: dependencies: '@types/estree': 1.0.8 + etag@1.8.1: {} + + exit-hook@2.2.1: {} + expect-type@1.3.0: {} + express@4.22.1: + dependencies: + accepts: 1.3.8 + array-flatten: 1.1.1 + body-parser: 1.20.4 + content-disposition: 0.5.4 + content-type: 1.0.5 + cookie: 0.7.2 + cookie-signature: 1.0.7 + debug: 2.6.9 + depd: 2.0.0 + encodeurl: 2.0.0 + escape-html: 1.0.3 + etag: 1.8.1 + finalhandler: 1.3.2 + fresh: 0.5.2 + http-errors: 2.0.1 + merge-descriptors: 1.0.3 + methods: 1.1.2 + on-finished: 2.4.1 + parseurl: 1.3.3 + path-to-regexp: 0.1.12 + proxy-addr: 2.0.7 + qs: 6.14.1 + range-parser: 1.2.1 + safe-buffer: 5.2.1 + send: 0.19.2 + serve-static: 1.16.3 + setprototypeof: 1.2.0 + statuses: 2.0.2 + type-is: 1.6.18 + utils-merge: 1.0.1 + vary: 1.1.2 + transitivePeerDependencies: + - supports-color + + exsolve@1.0.8: {} + fdir@6.5.0(picomatch@4.0.3): optionalDependencies: picomatch: 4.0.3 @@ -3845,6 +4997,18 @@ snapshots: node-domexception: 1.0.0 web-streams-polyfill: 3.3.3 + finalhandler@1.3.2: + dependencies: + debug: 2.6.9 + encodeurl: 2.0.0 + escape-html: 1.0.3 + on-finished: 2.4.1 + parseurl: 1.3.3 + statuses: 2.0.2 + unpipe: 1.0.0 + transitivePeerDependencies: + - supports-color + fix-dts-default-cjs-exports@1.0.1: dependencies: magic-string: 0.30.21 @@ -3859,22 +5023,60 @@ snapshots: dependencies: fetch-blob: 3.2.0 + forwarded@0.2.0: {} + + fresh@0.5.2: {} + fsevents@2.3.2: optional: true fsevents@2.3.3: optional: true + function-bind@1.1.2: {} + gc-hook@0.3.1: {} gensync@1.0.0-beta.2: {} + get-intrinsic@1.3.0: + dependencies: + call-bind-apply-helpers: 1.0.2 + es-define-property: 1.0.1 + es-errors: 1.3.0 + es-object-atoms: 1.1.1 + function-bind: 1.1.2 + get-proto: 1.0.1 + gopd: 1.2.0 + has-symbols: 1.1.0 + hasown: 2.0.2 + math-intrinsics: 1.1.0 + + get-port@5.1.1: {} + + get-proto@1.0.1: + dependencies: + dunder-proto: 1.0.1 + es-object-atoms: 1.1.1 + get-tsconfig@4.13.0: dependencies: resolve-pkg-maps: 1.0.0 + globrex@0.1.2: {} + + gopd@1.2.0: {} + + graceful-fs@4.2.11: {} + has-flag@4.0.0: {} + has-symbols@1.1.0: {} + + hasown@2.0.2: + dependencies: + function-bind: 1.1.2 + hast-util-to-html@9.0.5: dependencies: '@types/hast': 3.0.4 @@ -3903,6 +5105,14 @@ snapshots: html-void-elements@3.0.0: {} + http-errors@2.0.1: + dependencies: + depd: 2.0.0 + inherits: 2.0.4 + setprototypeof: 1.2.0 + statuses: 2.0.2 + toidentifier: 1.0.1 + http-proxy-agent@7.0.2: dependencies: agent-base: 7.1.4 @@ -3917,14 +5127,24 @@ snapshots: transitivePeerDependencies: - supports-color + iconv-lite@0.4.24: + dependencies: + safer-buffer: 2.1.2 + iconv-lite@0.6.3: dependencies: safer-buffer: 2.1.2 + inherits@2.0.4: {} + + ipaddr.js@1.9.1: {} + is-potential-custom-element-name@1.0.1: {} is-what@5.5.0: {} + isbot@5.1.32: {} + istanbul-lib-coverage@3.2.2: {} istanbul-lib-report@3.0.1: @@ -3946,6 +5166,8 @@ snapshots: html-escaper: 2.0.2 istanbul-lib-report: 3.0.1 + jiti@2.6.1: {} + joycon@3.1.1: {} js-base64@3.7.8: {} @@ -3981,7 +5203,7 @@ snapshots: - supports-color - utf-8-validate - jsesc@3.1.0: {} + jsesc@3.0.2: {} json5@2.2.3: {} @@ -4017,12 +5239,63 @@ snapshots: '@libsql/linux-x64-musl': 0.5.22 '@libsql/win32-x64-msvc': 0.5.22 + lightningcss-android-arm64@1.30.2: + optional: true + + lightningcss-darwin-arm64@1.30.2: + optional: true + + lightningcss-darwin-x64@1.30.2: + optional: true + + lightningcss-freebsd-x64@1.30.2: + optional: true + + lightningcss-linux-arm-gnueabihf@1.30.2: + optional: true + + lightningcss-linux-arm64-gnu@1.30.2: + optional: true + + lightningcss-linux-arm64-musl@1.30.2: + optional: true + + lightningcss-linux-x64-gnu@1.30.2: + optional: true + + lightningcss-linux-x64-musl@1.30.2: + optional: true + + lightningcss-win32-arm64-msvc@1.30.2: + optional: true + + lightningcss-win32-x64-msvc@1.30.2: + optional: true + + lightningcss@1.30.2: + dependencies: + detect-libc: 2.1.2 + optionalDependencies: + lightningcss-android-arm64: 1.30.2 + lightningcss-darwin-arm64: 1.30.2 + lightningcss-darwin-x64: 1.30.2 + lightningcss-freebsd-x64: 1.30.2 + lightningcss-linux-arm-gnueabihf: 1.30.2 + lightningcss-linux-arm64-gnu: 1.30.2 + lightningcss-linux-arm64-musl: 1.30.2 + lightningcss-linux-x64-gnu: 1.30.2 + lightningcss-linux-x64-musl: 1.30.2 + lightningcss-win32-arm64-msvc: 1.30.2 + lightningcss-win32-x64-msvc: 1.30.2 + lilconfig@3.1.3: {} lines-and-columns@1.2.4: {} load-tsconfig@0.2.5: {} + lodash@4.17.21: {} + lru-cache@11.2.4: {} lru-cache@5.1.1: @@ -4047,6 +5320,8 @@ snapshots: mark.js@8.11.1: {} + math-intrinsics@1.1.0: {} + mdast-util-to-hast@13.2.1: dependencies: '@types/hast': 3.0.4 @@ -4061,6 +5336,12 @@ snapshots: mdn-data@2.12.2: {} + media-typer@0.3.0: {} + + merge-descriptors@1.0.3: {} + + methods@1.1.2: {} + micromark-util-character@2.1.1: dependencies: micromark-util-symbol: 2.0.1 @@ -4078,6 +5359,16 @@ snapshots: micromark-util-types@2.0.2: {} + mime-db@1.52.0: {} + + mime-db@1.54.0: {} + + mime-types@2.1.35: + dependencies: + mime-db: 1.52.0 + + mime@1.6.0: {} + minisearch@7.2.0: {} mitt@3.0.1: {} @@ -4089,8 +5380,20 @@ snapshots: pkg-types: 1.3.1 ufo: 1.6.1 + morgan@1.10.1: + dependencies: + basic-auth: 2.0.1 + debug: 2.6.9 + depd: 2.0.0 + on-finished: 2.3.0 + on-headers: 1.1.0 + transitivePeerDependencies: + - supports-color + mrmime@2.0.1: {} + ms@2.0.0: {} + ms@2.1.3: {} mz@2.7.0: @@ -4101,6 +5404,10 @@ snapshots: nanoid@3.3.11: {} + negotiator@0.6.3: {} + + negotiator@0.6.4: {} + node-domexception@1.0.0: {} node-fetch@3.3.2: @@ -4113,18 +5420,38 @@ snapshots: object-assign@4.1.1: {} + object-inspect@1.13.4: {} + obug@2.1.1: {} + on-finished@2.3.0: + dependencies: + ee-first: 1.1.1 + + on-finished@2.4.1: + dependencies: + ee-first: 1.1.1 + + on-headers@1.1.0: {} + oniguruma-to-es@3.1.1: dependencies: emoji-regex-xs: 1.0.0 regex: 6.1.0 regex-recursion: 6.0.2 + p-map@7.0.4: {} + parse5@8.0.0: dependencies: entities: 6.0.1 + parseurl@1.3.3: {} + + path-to-regexp@0.1.12: {} + + pathe@1.1.2: {} + pathe@2.0.3: {} perfect-debounce@1.0.0: {} @@ -4145,6 +5472,12 @@ snapshots: mlly: 1.8.0 pathe: 2.0.3 + pkg-types@2.3.0: + dependencies: + confbox: 0.2.2 + exsolve: 1.0.8 + pathe: 2.0.3 + playwright-core@1.57.0: {} playwright@1.57.0: @@ -4155,10 +5488,11 @@ snapshots: pngjs@7.0.0: {} - postcss-load-config@6.0.1(postcss@8.5.6)(tsx@4.21.0): + postcss-load-config@6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0): dependencies: lilconfig: 3.1.3 optionalDependencies: + jiti: 2.6.1 postcss: 8.5.6 tsx: 4.21.0 @@ -4187,10 +5521,28 @@ snapshots: property-information@7.1.0: {} + proxy-addr@2.0.7: + dependencies: + forwarded: 0.2.0 + ipaddr.js: 1.9.1 + proxy-target@3.0.2: {} punycode@2.3.1: {} + qs@6.14.1: + dependencies: + side-channel: 1.1.0 + + range-parser@1.2.1: {} + + raw-body@2.5.3: + dependencies: + bytes: 3.1.2 + http-errors: 2.0.1 + iconv-lite: 0.4.24 + unpipe: 1.0.0 + react-dom@19.2.3(react@19.2.3): dependencies: react: 19.2.3 @@ -4198,8 +5550,18 @@ snapshots: react-is@17.0.2: {} + react-refresh@0.14.2: {} + react-refresh@0.18.0: {} + react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3): + dependencies: + cookie: 1.1.1 + react: 19.2.3 + set-cookie-parser: 2.7.2 + optionalDependencies: + react-dom: 19.2.3(react@19.2.3) + react@19.2.3: {} readdirp@4.1.2: {} @@ -4250,6 +5612,10 @@ snapshots: '@rollup/rollup-win32-x64-msvc': 4.54.0 fsevents: 2.3.3 + safe-buffer@5.1.2: {} + + safe-buffer@5.2.1: {} + safer-buffer@2.1.2: {} saxes@6.0.0: @@ -4264,6 +5630,37 @@ snapshots: semver@7.7.3: {} + send@0.19.2: + dependencies: + debug: 2.6.9 + depd: 2.0.0 + destroy: 1.2.0 + encodeurl: 2.0.0 + escape-html: 1.0.3 + etag: 1.8.1 + fresh: 0.5.2 + http-errors: 2.0.1 + mime: 1.6.0 + ms: 2.1.3 + on-finished: 2.4.1 + range-parser: 1.2.1 + statuses: 2.0.2 + transitivePeerDependencies: + - supports-color + + serve-static@1.16.3: + dependencies: + encodeurl: 2.0.0 + escape-html: 1.0.3 + parseurl: 1.3.3 + send: 0.19.2 + transitivePeerDependencies: + - supports-color + + set-cookie-parser@2.7.2: {} + + setprototypeof@1.2.0: {} + shiki@2.5.0: dependencies: '@shikijs/core': 2.5.0 @@ -4275,6 +5672,34 @@ snapshots: '@shikijs/vscode-textmate': 10.0.2 '@types/hast': 3.0.4 + side-channel-list@1.0.0: + dependencies: + es-errors: 1.3.0 + object-inspect: 1.13.4 + + side-channel-map@1.0.1: + dependencies: + call-bound: 1.0.4 + es-errors: 1.3.0 + get-intrinsic: 1.3.0 + object-inspect: 1.13.4 + + side-channel-weakmap@1.0.2: + dependencies: + call-bound: 1.0.4 + es-errors: 1.3.0 + get-intrinsic: 1.3.0 + object-inspect: 1.13.4 + side-channel-map: 1.0.1 + + side-channel@1.1.0: + dependencies: + es-errors: 1.3.0 + object-inspect: 1.13.4 + side-channel-list: 1.0.0 + side-channel-map: 1.0.1 + side-channel-weakmap: 1.0.2 + siginfo@2.0.0: {} sirv@3.0.2: @@ -4285,20 +5710,27 @@ snapshots: source-map-js@1.2.1: {} + source-map-support@0.5.21: + dependencies: + buffer-from: 1.1.2 + source-map: 0.6.1 + + source-map@0.6.1: {} + source-map@0.7.6: {} space-separated-tokens@2.0.2: {} speakingurl@14.0.1: {} - sqlocal@0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)): + sqlocal@0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)): dependencies: '@sqlite.org/sqlite-wasm': 3.50.4-build1 coincident: 1.2.3 optionalDependencies: kysely: 0.28.9 react: 19.2.3 - vite: 7.3.0(@types/node@25.0.3)(tsx@4.21.0) + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) vue: 3.5.26(typescript@5.9.3) transitivePeerDependencies: - bufferutil @@ -4306,6 +5738,8 @@ snapshots: stackback@0.0.2: {} + statuses@2.0.2: {} + std-env@3.10.0: {} stringify-entities@4.0.4: @@ -4335,6 +5769,10 @@ snapshots: tabbable@6.3.0: {} + tailwindcss@4.1.18: {} + + tapable@2.3.0: {} + thenify-all@1.6.0: dependencies: thenify: 3.3.1 @@ -4362,6 +5800,8 @@ snapshots: dependencies: tldts-core: 7.0.19 + toidentifier@1.0.1: {} + totalist@3.0.1: {} tough-cookie@6.0.0: @@ -4378,7 +5818,11 @@ snapshots: ts-interface-checker@0.1.13: {} - tsup@8.5.1(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3): + tsconfck@3.1.6(typescript@5.9.3): + optionalDependencies: + typescript: 5.9.3 + + tsup@8.5.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0)(typescript@5.9.3): dependencies: bundle-require: 5.1.0(esbuild@0.27.2) cac: 6.7.14 @@ -4389,7 +5833,7 @@ snapshots: fix-dts-default-cjs-exports: 1.0.1 joycon: 3.1.1 picocolors: 1.1.1 - postcss-load-config: 6.0.1(postcss@8.5.6)(tsx@4.21.0) + postcss-load-config: 6.0.1(jiti@2.6.1)(postcss@8.5.6)(tsx@4.21.0) resolve-from: 5.0.0 rollup: 4.54.0 source-map: 0.7.6 @@ -4440,6 +5884,11 @@ snapshots: turbo-windows-64: 2.7.2 turbo-windows-arm64: 2.7.2 + type-is@1.6.18: + dependencies: + media-typer: 0.3.0 + mime-types: 2.1.35 + typescript@5.9.3: {} ufo@1.6.1: {} @@ -4473,16 +5922,22 @@ snapshots: unist-util-is: 6.0.1 unist-util-visit-parents: 6.0.2 + unpipe@1.0.0: {} + update-browserslist-db@1.2.3(browserslist@4.28.1): dependencies: browserslist: 4.28.1 escalade: 3.2.0 picocolors: 1.1.1 + utils-merge@1.0.1: {} + valibot@1.2.0(typescript@5.9.3): optionalDependencies: typescript: 5.9.3 + vary@1.1.2: {} + vfile-message@4.0.3: dependencies: '@types/unist': 3.0.3 @@ -4493,7 +5948,39 @@ snapshots: '@types/unist': 3.0.3 vfile-message: 4.0.3 - vite@5.4.21(@types/node@25.0.3): + vite-node@3.2.4(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0): + dependencies: + cac: 6.7.14 + debug: 4.4.3 + es-module-lexer: 1.7.0 + pathe: 2.0.3 + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + transitivePeerDependencies: + - '@types/node' + - jiti + - less + - lightningcss + - sass + - sass-embedded + - stylus + - sugarss + - supports-color + - terser + - tsx + - yaml + + vite-tsconfig-paths@6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)): + dependencies: + debug: 4.4.3 + globrex: 0.1.2 + tsconfck: 3.1.6(typescript@5.9.3) + optionalDependencies: + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) + transitivePeerDependencies: + - supports-color + - typescript + + vite@5.4.21(@types/node@25.0.3)(lightningcss@1.30.2): dependencies: esbuild: 0.21.5 postcss: 8.5.6 @@ -4501,8 +5988,9 @@ snapshots: optionalDependencies: '@types/node': 25.0.3 fsevents: 2.3.3 + lightningcss: 1.30.2 - vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0): + vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0): dependencies: esbuild: 0.27.2 fdir: 6.5.0(picomatch@4.0.3) @@ -4513,9 +6001,11 @@ snapshots: optionalDependencies: '@types/node': 25.0.3 fsevents: 2.3.3 + jiti: 2.6.1 + lightningcss: 1.30.2 tsx: 4.21.0 - vitepress@1.6.4(@algolia/client-search@5.46.1)(@types/node@25.0.3)(postcss@8.5.6)(search-insights@2.17.3)(typescript@5.9.3): + vitepress@1.6.4(@algolia/client-search@5.46.1)(@types/node@25.0.3)(lightningcss@1.30.2)(postcss@8.5.6)(search-insights@2.17.3)(typescript@5.9.3): dependencies: '@docsearch/css': 3.8.2 '@docsearch/js': 3.8.2(@algolia/client-search@5.46.1)(search-insights@2.17.3) @@ -4524,7 +6014,7 @@ snapshots: '@shikijs/transformers': 2.5.0 '@shikijs/types': 2.5.0 '@types/markdown-it': 14.1.2 - '@vitejs/plugin-vue': 5.2.4(vite@5.4.21(@types/node@25.0.3))(vue@3.5.26(typescript@5.9.3)) + '@vitejs/plugin-vue': 5.2.4(vite@5.4.21(@types/node@25.0.3)(lightningcss@1.30.2))(vue@3.5.26(typescript@5.9.3)) '@vue/devtools-api': 7.7.9 '@vue/shared': 3.5.26 '@vueuse/core': 12.8.2(typescript@5.9.3) @@ -4533,7 +6023,7 @@ snapshots: mark.js: 8.11.1 minisearch: 7.2.0 shiki: 2.5.0 - vite: 5.4.21(@types/node@25.0.3) + vite: 5.4.21(@types/node@25.0.3)(lightningcss@1.30.2) vue: 3.5.26(typescript@5.9.3) optionalDependencies: postcss: 8.5.6 @@ -4564,10 +6054,10 @@ snapshots: - typescript - universal-cookie - vitest@4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jsdom@27.3.0)(tsx@4.21.0): + vitest@4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.3.0)(lightningcss@1.30.2)(tsx@4.21.0): dependencies: '@vitest/expect': 4.0.16 - '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0)) + '@vitest/mocker': 4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) '@vitest/pretty-format': 4.0.16 '@vitest/runner': 4.0.16 '@vitest/snapshot': 4.0.16 @@ -4584,11 +6074,11 @@ snapshots: tinyexec: 1.0.2 tinyglobby: 0.2.15 tinyrainbow: 3.0.3 - vite: 7.3.0(@types/node@25.0.3)(tsx@4.21.0) + vite: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0) why-is-node-running: 2.3.0 optionalDependencies: '@types/node': 25.0.3 - '@vitest/browser-playwright': 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(tsx@4.21.0))(vitest@4.0.16) + '@vitest/browser-playwright': 4.0.16(playwright@1.57.0)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16) jsdom: 27.3.0 transitivePeerDependencies: - jiti From 94656ad3ac0417167e2d3ebaf7961d06a73ef986 Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 31 Dec 2025 00:15:43 +0900 Subject: [PATCH 046/101] refactor(example-react-router): improve type safety and documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Export output type from job definition for reuse in components - Add JSDoc explaining HMR singleton helper purpose 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/react-router/app/jobs/import-csv.ts | 44 +++++++++++-------- examples/react-router/app/jobs/index.ts | 7 ++- .../react-router/app/lib/durably.server.ts | 10 ++++- .../app/routes/_index/run-progress.tsx | 3 +- 4 files changed, 41 insertions(+), 23 deletions(-) diff --git a/examples/react-router/app/jobs/import-csv.ts b/examples/react-router/app/jobs/import-csv.ts index b99eb1d8..5abbfba9 100644 --- a/examples/react-router/app/jobs/import-csv.ts +++ b/examples/react-router/app/jobs/import-csv.ts @@ -4,53 +4,59 @@ * Processes CSV rows with progress reporting. */ -import { defineJob } from '@coji/durably' -import { z } from 'zod' +import { defineJob } from "@coji/durably"; +import { z } from "zod"; const csvRowSchema = z.object({ id: z.number(), name: z.string(), email: z.string(), amount: z.number(), -}) +}); + +/** Output schema for type inference */ +const outputSchema = z.object({ imported: z.number(), failed: z.number() }); + +/** Output type for use in components */ +export type ImportCsvOutput = z.infer; export const importCsvJob = defineJob({ - name: 'import-csv', + name: "import-csv", input: z.object({ filename: z.string(), rows: z.array(csvRowSchema), }), - output: z.object({ imported: z.number(), failed: z.number() }), + output: outputSchema, run: async (step, payload) => { step.log.info( - `Starting import of ${payload.filename} (${payload.rows.length} rows)`, - ) + `Starting import of ${payload.filename} (${payload.rows.length} rows)` + ); - let imported = 0 + let imported = 0; for (let i = 0; i < payload.rows.length; i++) { - const row = payload.rows[i] + const row = payload.rows[i]; const result = await step.run(`row-${i}`, async () => { // Simulate processing with validation - await new Promise((r) => setTimeout(r, 100)) + await new Promise((r) => setTimeout(r, 100)); // Simulate occasional failures (negative amounts) if (row.amount < 0) { - throw new Error(`Invalid amount for ${row.name}: ${row.amount}`) + throw new Error(`Invalid amount for ${row.name}: ${row.amount}`); } - return { processed: true, id: row.id } - }) + return { processed: true, id: row.id }; + }); if (result.processed) { - imported++ - step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`) + imported++; + step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`); } - step.progress(i + 1, payload.rows.length, `Processing ${row.name}`) + step.progress(i + 1, payload.rows.length, `Processing ${row.name}`); } - step.log.info(`Import completed: ${imported} rows`) - return { imported, failed: 0 } + step.log.info(`Import completed: ${imported} rows`); + return { imported, failed: 0 }; }, -}) +}); diff --git a/examples/react-router/app/jobs/index.ts b/examples/react-router/app/jobs/index.ts index 7141877c..173b27b8 100644 --- a/examples/react-router/app/jobs/index.ts +++ b/examples/react-router/app/jobs/index.ts @@ -4,8 +4,11 @@ * Barrel export for all job definitions. */ -import { importCsvJob } from './import-csv' +import { importCsvJob } from "./import-csv"; + +// Re-export types for use in components +export type { ImportCsvOutput } from "./import-csv"; export const jobs = { importCsv: importCsvJob, -} +}; diff --git a/examples/react-router/app/lib/durably.server.ts b/examples/react-router/app/lib/durably.server.ts index d7d43fe6..92d02149 100644 --- a/examples/react-router/app/lib/durably.server.ts +++ b/examples/react-router/app/lib/durably.server.ts @@ -12,7 +12,15 @@ import { import { LibsqlDialect } from '@libsql/kysely-libsql' import { jobs } from '~/jobs' -// HMR-safe singleton helper +/** + * HMR-safe singleton helper for React Router dev server. + * + * During development, React Router's HMR reloads this module on every change, + * which would create new Durably/database instances each time. This helper + * stores instances on globalThis to persist them across HMR reloads. + * + * In production, this just works as a normal singleton pattern. + */ function singleton(name: string, factory: () => T): T { const g = globalThis as unknown as Record if (g[name] === undefined) { diff --git a/examples/react-router/app/routes/_index/run-progress.tsx b/examples/react-router/app/routes/_index/run-progress.tsx index 9289ca16..4a1cfa3e 100644 --- a/examples/react-router/app/routes/_index/run-progress.tsx +++ b/examples/react-router/app/routes/_index/run-progress.tsx @@ -5,13 +5,14 @@ */ import { useJobRun } from '@coji/durably-react/client' +import type { ImportCsvOutput } from '~/jobs' interface RunProgressProps { runId: string | null } export function RunProgress({ runId }: RunProgressProps) { - const run = useJobRun<{ imported: number; failed: number }>({ + const run = useJobRun({ api: '/api/durably', runId, }) From a47af9bacd4c1ef174c360f815634504b0cf81c7 Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 31 Dec 2025 00:22:43 +0900 Subject: [PATCH 047/101] chore(example-react-router): add prettier and biome configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add prettier and biome devDependencies - Add format and lint npm scripts - Configure biome with Tailwind CSS parser support 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/react-router/app/app.css | 7 ++-- examples/react-router/app/jobs/import-csv.ts | 40 +++++++++--------- examples/react-router/app/jobs/index.ts | 6 +-- .../react-router/app/lib/durably.server.ts | 5 +-- examples/react-router/app/root.tsx | 42 +++++++++---------- examples/react-router/app/routes/_index.tsx | 10 +++-- .../app/routes/_index/dashboard.tsx | 26 ++++++------ .../app/routes/_index/run-progress.tsx | 8 +++- .../react-router/app/routes/api.durably.$.ts | 2 +- examples/react-router/biome.json | 10 +++++ examples/react-router/package.json | 11 ++++- examples/react-router/prettier.config.js | 7 ++++ examples/react-router/react-router.config.ts | 4 +- examples/react-router/vite.config.ts | 10 ++--- pnpm-lock.yaml | 9 ++++ 15 files changed, 117 insertions(+), 80 deletions(-) create mode 100644 examples/react-router/biome.json create mode 100644 examples/react-router/prettier.config.js diff --git a/examples/react-router/app/app.css b/examples/react-router/app/app.css index 23f3dd9d..f3902dce 100644 --- a/examples/react-router/app/app.css +++ b/examples/react-router/app/app.css @@ -1,8 +1,9 @@ -@import "tailwindcss"; +@import 'tailwindcss'; @theme { - --font-sans: "Inter", ui-sans-serif, system-ui, sans-serif, - "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"; + --font-sans: + 'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', + 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji'; } html, diff --git a/examples/react-router/app/jobs/import-csv.ts b/examples/react-router/app/jobs/import-csv.ts index 5abbfba9..855e3232 100644 --- a/examples/react-router/app/jobs/import-csv.ts +++ b/examples/react-router/app/jobs/import-csv.ts @@ -4,24 +4,24 @@ * Processes CSV rows with progress reporting. */ -import { defineJob } from "@coji/durably"; -import { z } from "zod"; +import { defineJob } from '@coji/durably' +import { z } from 'zod' const csvRowSchema = z.object({ id: z.number(), name: z.string(), email: z.string(), amount: z.number(), -}); +}) /** Output schema for type inference */ -const outputSchema = z.object({ imported: z.number(), failed: z.number() }); +const outputSchema = z.object({ imported: z.number(), failed: z.number() }) /** Output type for use in components */ -export type ImportCsvOutput = z.infer; +export type ImportCsvOutput = z.infer export const importCsvJob = defineJob({ - name: "import-csv", + name: 'import-csv', input: z.object({ filename: z.string(), rows: z.array(csvRowSchema), @@ -29,34 +29,34 @@ export const importCsvJob = defineJob({ output: outputSchema, run: async (step, payload) => { step.log.info( - `Starting import of ${payload.filename} (${payload.rows.length} rows)` - ); + `Starting import of ${payload.filename} (${payload.rows.length} rows)`, + ) - let imported = 0; + let imported = 0 for (let i = 0; i < payload.rows.length; i++) { - const row = payload.rows[i]; + const row = payload.rows[i] const result = await step.run(`row-${i}`, async () => { // Simulate processing with validation - await new Promise((r) => setTimeout(r, 100)); + await new Promise((r) => setTimeout(r, 100)) // Simulate occasional failures (negative amounts) if (row.amount < 0) { - throw new Error(`Invalid amount for ${row.name}: ${row.amount}`); + throw new Error(`Invalid amount for ${row.name}: ${row.amount}`) } - return { processed: true, id: row.id }; - }); + return { processed: true, id: row.id } + }) if (result.processed) { - imported++; - step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`); + imported++ + step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`) } - step.progress(i + 1, payload.rows.length, `Processing ${row.name}`); + step.progress(i + 1, payload.rows.length, `Processing ${row.name}`) } - step.log.info(`Import completed: ${imported} rows`); - return { imported, failed: 0 }; + step.log.info(`Import completed: ${imported} rows`) + return { imported, failed: 0 } }, -}); +}) diff --git a/examples/react-router/app/jobs/index.ts b/examples/react-router/app/jobs/index.ts index 173b27b8..8e309e9f 100644 --- a/examples/react-router/app/jobs/index.ts +++ b/examples/react-router/app/jobs/index.ts @@ -4,11 +4,11 @@ * Barrel export for all job definitions. */ -import { importCsvJob } from "./import-csv"; +import { importCsvJob } from './import-csv' // Re-export types for use in components -export type { ImportCsvOutput } from "./import-csv"; +export type { ImportCsvOutput } from './import-csv' export const jobs = { importCsv: importCsvJob, -}; +} diff --git a/examples/react-router/app/lib/durably.server.ts b/examples/react-router/app/lib/durably.server.ts index 92d02149..a8d314a3 100644 --- a/examples/react-router/app/lib/durably.server.ts +++ b/examples/react-router/app/lib/durably.server.ts @@ -5,10 +5,7 @@ * Server-only - do not import in client code. */ -import { - createDurably, - createDurablyHandler, -} from '@coji/durably' +import { createDurably, createDurablyHandler } from '@coji/durably' import { LibsqlDialect } from '@libsql/kysely-libsql' import { jobs } from '~/jobs' diff --git a/examples/react-router/app/root.tsx b/examples/react-router/app/root.tsx index 9fc66361..f9f8bdfc 100644 --- a/examples/react-router/app/root.tsx +++ b/examples/react-router/app/root.tsx @@ -5,23 +5,23 @@ import { Outlet, Scripts, ScrollRestoration, -} from "react-router"; +} from 'react-router' -import type { Route } from "./+types/root"; -import "./app.css"; +import type { Route } from './+types/root' +import './app.css' export const links: Route.LinksFunction = () => [ - { rel: "preconnect", href: "https://fonts.googleapis.com" }, + { rel: 'preconnect', href: 'https://fonts.googleapis.com' }, { - rel: "preconnect", - href: "https://fonts.gstatic.com", - crossOrigin: "anonymous", + rel: 'preconnect', + href: 'https://fonts.gstatic.com', + crossOrigin: 'anonymous', }, { - rel: "stylesheet", - href: "https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap", + rel: 'stylesheet', + href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap', }, -]; +] export function Layout({ children }: { children: React.ReactNode }) { return ( @@ -38,27 +38,27 @@ export function Layout({ children }: { children: React.ReactNode }) { - ); + ) } export default function App() { - return ; + return } export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) { - let message = "Oops!"; - let details = "An unexpected error occurred."; - let stack: string | undefined; + let message = 'Oops!' + let details = 'An unexpected error occurred.' + let stack: string | undefined if (isRouteErrorResponse(error)) { - message = error.status === 404 ? "404" : "Error"; + message = error.status === 404 ? '404' : 'Error' details = error.status === 404 - ? "The requested page could not be found." - : error.statusText || details; + ? 'The requested page could not be found.' + : error.statusText || details } else if (import.meta.env.DEV && error && error instanceof Error) { - details = error.message; - stack = error.stack; + details = error.message + stack = error.stack } return ( @@ -71,5 +71,5 @@ export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) { )} - ); + ) } diff --git a/examples/react-router/app/routes/_index.tsx b/examples/react-router/app/routes/_index.tsx index d9a5aa05..2d4a9a93 100644 --- a/examples/react-router/app/routes/_index.tsx +++ b/examples/react-router/app/routes/_index.tsx @@ -7,11 +7,11 @@ * - Dashboard: useRuns with SSE for real-time updates and pagination */ -import type { Route } from './+types/_index' import { Form, useActionData, useNavigation } from 'react-router' -import { RunProgress } from './_index/run-progress' -import { Dashboard } from './_index/dashboard' import { registeredJobs } from '~/lib/durably.server' +import type { Route } from './+types/_index' +import { Dashboard } from './_index/dashboard' +import { RunProgress } from './_index/run-progress' export function meta() { return [ @@ -37,7 +37,9 @@ function generateDummyRows(count: number) { return Array.from({ length: count }, (_, i) => ({ id: i + 1, name: names[i % names.length], - email: `${names[i % names.length].toLowerCase()}${i}@${domains[i % domains.length]}`, + email: `${names[i % names.length].toLowerCase()}${i}@${ + domains[i % domains.length] + }`, amount: Math.floor(Math.random() * 1000) + 10, })) } diff --git a/examples/react-router/app/routes/_index/dashboard.tsx b/examples/react-router/app/routes/_index/dashboard.tsx index d056f411..8b35ab9a 100644 --- a/examples/react-router/app/routes/_index/dashboard.tsx +++ b/examples/react-router/app/routes/_index/dashboard.tsx @@ -5,16 +5,16 @@ * First page auto-subscribes to SSE for instant updates. */ -import { useRuns } from "@coji/durably-react/client"; +import { useRuns } from '@coji/durably-react/client' export function Dashboard() { const { runs, isLoading, error, page, hasMore, nextPage, prevPage } = useRuns( { - api: "/api/durably", - jobName: "import-csv", + api: '/api/durably', + jobName: 'import-csv', pageSize: 6, - } - ); + }, + ) return (
@@ -45,13 +45,13 @@ export function Dashboard() {
{r.status} @@ -83,5 +83,5 @@ export function Dashboard() { )} - ); + ) } diff --git a/examples/react-router/app/routes/_index/run-progress.tsx b/examples/react-router/app/routes/_index/run-progress.tsx index 4a1cfa3e..696662c7 100644 --- a/examples/react-router/app/routes/_index/run-progress.tsx +++ b/examples/react-router/app/routes/_index/run-progress.tsx @@ -42,11 +42,15 @@ export function RunProgress({ runId }: RunProgressProps) {
-
{run.progress.message}
+
+ {run.progress.message} +
)} diff --git a/examples/react-router/app/routes/api.durably.$.ts b/examples/react-router/app/routes/api.durably.$.ts index 7596a112..daa1494b 100644 --- a/examples/react-router/app/routes/api.durably.$.ts +++ b/examples/react-router/app/routes/api.durably.$.ts @@ -10,8 +10,8 @@ * POST /api/durably/cancel?runId=xxx - Cancel a run */ -import type { Route } from './+types/api.durably.$' import { durablyHandler } from '~/lib/durably.server' +import type { Route } from './+types/api.durably.$' export async function loader({ request }: Route.LoaderArgs) { return durablyHandler.handle(request, '/api/durably') diff --git a/examples/react-router/biome.json b/examples/react-router/biome.json new file mode 100644 index 00000000..cb0ac4d9 --- /dev/null +++ b/examples/react-router/biome.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", + "extends": ["../../biome.json"], + "css": { + "parser": { + "cssModules": true, + "tailwindDirectives": true + } + } +} diff --git a/examples/react-router/package.json b/examples/react-router/package.json index 87f98d7a..8962bffe 100644 --- a/examples/react-router/package.json +++ b/examples/react-router/package.json @@ -6,7 +6,11 @@ "build": "react-router build", "dev": "react-router dev", "start": "react-router-serve ./build/server/index.js", - "typecheck": "react-router typegen && tsc" + "typecheck": "react-router typegen && tsc", + "lint": "biome lint .", + "lint:fix": "biome lint --write .", + "format": "prettier --experimental-cli --check .", + "format:fix": "prettier --experimental-cli --write ." }, "dependencies": { "@coji/durably": "workspace:*", @@ -21,14 +25,17 @@ "zod": "^4.2.1" }, "devDependencies": { + "@biomejs/biome": "^2.3.10", "@react-router/dev": "7.11.0", "@tailwindcss/vite": "^4.1.13", "@types/node": "^25.0.3", "@types/react": "^19.2.7", "@types/react-dom": "^19.2.3", + "prettier": "^3.7.4", + "prettier-plugin-organize-imports": "^4.3.0", "tailwindcss": "^4.1.13", "typescript": "^5.9.2", "vite": "^7.1.7", "vite-tsconfig-paths": "^6.0.3" } -} \ No newline at end of file +} diff --git a/examples/react-router/prettier.config.js b/examples/react-router/prettier.config.js new file mode 100644 index 00000000..48dce797 --- /dev/null +++ b/examples/react-router/prettier.config.js @@ -0,0 +1,7 @@ +export default { + semi: false, + singleQuote: true, + trailingComma: 'all', + printWidth: 80, + plugins: ['prettier-plugin-organize-imports'], +} diff --git a/examples/react-router/react-router.config.ts b/examples/react-router/react-router.config.ts index 6ff16f91..d5306db8 100644 --- a/examples/react-router/react-router.config.ts +++ b/examples/react-router/react-router.config.ts @@ -1,7 +1,7 @@ -import type { Config } from "@react-router/dev/config"; +import type { Config } from '@react-router/dev/config' export default { // Config options... // Server-side render by default, to enable SPA mode set this to `false` ssr: true, -} satisfies Config; +} satisfies Config diff --git a/examples/react-router/vite.config.ts b/examples/react-router/vite.config.ts index 4a88d587..de677b2b 100644 --- a/examples/react-router/vite.config.ts +++ b/examples/react-router/vite.config.ts @@ -1,8 +1,8 @@ -import { reactRouter } from "@react-router/dev/vite"; -import tailwindcss from "@tailwindcss/vite"; -import { defineConfig } from "vite"; -import tsconfigPaths from "vite-tsconfig-paths"; +import { reactRouter } from '@react-router/dev/vite' +import tailwindcss from '@tailwindcss/vite' +import { defineConfig } from 'vite' +import tsconfigPaths from 'vite-tsconfig-paths' export default defineConfig({ plugins: [tailwindcss(), reactRouter(), tsconfigPaths()], -}); +}) diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index cfa9eca5..02a07205 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -180,6 +180,9 @@ importers: specifier: ^4.2.1 version: 4.2.1 devDependencies: + '@biomejs/biome': + specifier: ^2.3.10 + version: 2.3.10 '@react-router/dev': specifier: 7.11.0 version: 7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)) @@ -195,6 +198,12 @@ importers: '@types/react-dom': specifier: ^19.2.3 version: 19.2.3(@types/react@19.2.7) + prettier: + specifier: ^3.7.4 + version: 3.7.4 + prettier-plugin-organize-imports: + specifier: ^4.3.0 + version: 4.3.0(prettier@3.7.4)(typescript@5.9.3) tailwindcss: specifier: ^4.1.13 version: 4.1.18 From a51799a210f5dfa609015f6176d745871f2074b7 Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 31 Dec 2025 00:27:29 +0900 Subject: [PATCH 048/101] chore(examples): add biome and prettier configuration to all examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Add biome.json and prettier.config.js to browser, node, react examples - Add .gitignore to browser, node, react examples - Simplify biome.json to extend root config 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/browser/.gitignore | 11 +++++++++++ examples/browser/biome.json | 4 ++++ examples/browser/prettier.config.js | 7 +++++++ examples/node/.gitignore | 5 +++++ examples/node/biome.json | 4 ++++ examples/node/prettier.config.js | 7 +++++++ examples/react/.gitignore | 8 ++++++++ examples/react/biome.json | 4 ++++ examples/react/prettier.config.js | 7 +++++++ 9 files changed, 57 insertions(+) create mode 100644 examples/browser/.gitignore create mode 100644 examples/browser/biome.json create mode 100644 examples/browser/prettier.config.js create mode 100644 examples/node/.gitignore create mode 100644 examples/node/biome.json create mode 100644 examples/node/prettier.config.js create mode 100644 examples/react/.gitignore create mode 100644 examples/react/biome.json create mode 100644 examples/react/prettier.config.js diff --git a/examples/browser/.gitignore b/examples/browser/.gitignore new file mode 100644 index 00000000..99b401df --- /dev/null +++ b/examples/browser/.gitignore @@ -0,0 +1,11 @@ +# Dependencies +node_modules/ + +# Build output +dist/ + +# SQLite database files +*.db + +# Vendor files (third-party, not linted) +public/ diff --git a/examples/browser/biome.json b/examples/browser/biome.json new file mode 100644 index 00000000..6455521c --- /dev/null +++ b/examples/browser/biome.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", + "extends": ["../../biome.json"] +} diff --git a/examples/browser/prettier.config.js b/examples/browser/prettier.config.js new file mode 100644 index 00000000..48dce797 --- /dev/null +++ b/examples/browser/prettier.config.js @@ -0,0 +1,7 @@ +export default { + semi: false, + singleQuote: true, + trailingComma: 'all', + printWidth: 80, + plugins: ['prettier-plugin-organize-imports'], +} diff --git a/examples/node/.gitignore b/examples/node/.gitignore new file mode 100644 index 00000000..4ce1e340 --- /dev/null +++ b/examples/node/.gitignore @@ -0,0 +1,5 @@ +# Dependencies +node_modules/ + +# SQLite database files +*.db diff --git a/examples/node/biome.json b/examples/node/biome.json new file mode 100644 index 00000000..6455521c --- /dev/null +++ b/examples/node/biome.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", + "extends": ["../../biome.json"] +} diff --git a/examples/node/prettier.config.js b/examples/node/prettier.config.js new file mode 100644 index 00000000..48dce797 --- /dev/null +++ b/examples/node/prettier.config.js @@ -0,0 +1,7 @@ +export default { + semi: false, + singleQuote: true, + trailingComma: 'all', + printWidth: 80, + plugins: ['prettier-plugin-organize-imports'], +} diff --git a/examples/react/.gitignore b/examples/react/.gitignore new file mode 100644 index 00000000..f8dce739 --- /dev/null +++ b/examples/react/.gitignore @@ -0,0 +1,8 @@ +# Dependencies +node_modules/ + +# Build output +dist/ + +# SQLite database files +*.db diff --git a/examples/react/biome.json b/examples/react/biome.json new file mode 100644 index 00000000..6455521c --- /dev/null +++ b/examples/react/biome.json @@ -0,0 +1,4 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", + "extends": ["../../biome.json"] +} diff --git a/examples/react/prettier.config.js b/examples/react/prettier.config.js new file mode 100644 index 00000000..48dce797 --- /dev/null +++ b/examples/react/prettier.config.js @@ -0,0 +1,7 @@ +export default { + semi: false, + singleQuote: true, + trailingComma: 'all', + printWidth: 80, + plugins: ['prettier-plugin-organize-imports'], +} From 549d40f7f796f403a0edf3215c2c4d572a3d3140 Mon Sep 17 00:00:00 2001 From: coji Date: Wed, 31 Dec 2025 00:28:37 +0900 Subject: [PATCH 049/101] chore: remove browser example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The browser example is no longer needed as react and react-router examples provide better coverage. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- examples/browser/.gitignore | 11 -- examples/browser/biome.json | 4 - examples/browser/index.html | 229 ---------------------------- examples/browser/package.json | 28 ---- examples/browser/prettier.config.js | 7 - examples/browser/src/dashboard.ts | 136 ----------------- examples/browser/src/main.ts | 178 --------------------- examples/browser/tsconfig.json | 13 -- examples/browser/vercel.json | 12 -- examples/browser/vite.config.ts | 22 --- pnpm-lock.yaml | 31 ---- 11 files changed, 671 deletions(-) delete mode 100644 examples/browser/.gitignore delete mode 100644 examples/browser/biome.json delete mode 100644 examples/browser/index.html delete mode 100644 examples/browser/package.json delete mode 100644 examples/browser/prettier.config.js delete mode 100644 examples/browser/src/dashboard.ts delete mode 100644 examples/browser/src/main.ts delete mode 100644 examples/browser/tsconfig.json delete mode 100644 examples/browser/vercel.json delete mode 100644 examples/browser/vite.config.ts diff --git a/examples/browser/.gitignore b/examples/browser/.gitignore deleted file mode 100644 index 99b401df..00000000 --- a/examples/browser/.gitignore +++ /dev/null @@ -1,11 +0,0 @@ -# Dependencies -node_modules/ - -# Build output -dist/ - -# SQLite database files -*.db - -# Vendor files (third-party, not linted) -public/ diff --git a/examples/browser/biome.json b/examples/browser/biome.json deleted file mode 100644 index 6455521c..00000000 --- a/examples/browser/biome.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json", - "extends": ["../../biome.json"] -} diff --git a/examples/browser/index.html b/examples/browser/index.html deleted file mode 100644 index 8bfe330f..00000000 --- a/examples/browser/index.html +++ /dev/null @@ -1,229 +0,0 @@ - - - - Durably Browser Example - - - -

Durably Browser Example

- -
- - -
- - -
-
- - - -
- -
- Status: Initializing... -
-
- 

-    

-
-    
-    

-      

-        
Runs

-        
-      

-      
-        
-          
-            
-            
-            
-            
-            
-          
-        
-        
-          
-            
-          
-        
-      
IDJobStatusCreatedActions
Loading...

-      
-    

-
-    
-  
-
diff --git a/examples/browser/package.json b/examples/browser/package.json
deleted file mode 100644
index 758111fe..00000000
--- a/examples/browser/package.json
+++ /dev/null
@@ -1,28 +0,0 @@
-{
-  "name": "example-browser",
-  "private": true,
-  "type": "module",
-  "scripts": {
-    "dev": "vite",
-    "build": "vite build",
-    "preview": "vite preview",
-    "typecheck": "tsc --noEmit",
-    "lint": "biome lint .",
-    "lint:fix": "biome lint --write .",
-    "format": "prettier --experimental-cli --check .",
-    "format:fix": "prettier --experimental-cli --write ."
-  },
-  "dependencies": {
-    "@coji/durably": "workspace:*",
-    "kysely": "^0.28.9",
-    "sqlocal": "^0.16.0",
-    "zod": "^4.2.1"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
-    "prettier": "^3.7.4",
-    "prettier-plugin-organize-imports": "^4.3.0",
-    "typescript": "^5.9.3",
-    "vite": "^7.3.0"
-  }
-}
diff --git a/examples/browser/prettier.config.js b/examples/browser/prettier.config.js
deleted file mode 100644
index 48dce797..00000000
--- a/examples/browser/prettier.config.js
+++ /dev/null
@@ -1,7 +0,0 @@
-export default {
-  semi: false,
-  singleQuote: true,
-  trailingComma: 'all',
-  printWidth: 80,
-  plugins: ['prettier-plugin-organize-imports'],
-}
diff --git a/examples/browser/src/dashboard.ts b/examples/browser/src/dashboard.ts
deleted file mode 100644
index 92f5b46e..00000000
--- a/examples/browser/src/dashboard.ts
+++ /dev/null
@@ -1,136 +0,0 @@
-/**
- * Dashboard Module for Durably Browser Example
- *
- * Displays run history with status, details, and action buttons.
- */
-
-import type { Durably } from '@coji/durably'
-
-let durably: Durably
-
-/**
- * Escape HTML special characters to prevent XSS
- */
-function escapeHtml(unsafe: string): string {
-  return unsafe
-    .replace(/&/g, '&')
-    .replace(//g, '>')
-    .replace(/"/g, '"')
-    .replace(/'/g, ''')
-}
-
-const runsTbody = document.getElementById(
-  'runs-tbody',
-) as HTMLTableSectionElement
-const refreshBtn = document.getElementById('refresh-btn') as HTMLButtonElement
-const runDetailsEl = document.getElementById('run-details') as HTMLDivElement
-const detailsContent = document.getElementById(
-  'details-content',
-) as HTMLDivElement
-
-export function initDashboard(durablyInstance: Durably) {
-  durably = durablyInstance
-  refreshBtn.addEventListener('click', refreshDashboard)
-}
-
-export async function refreshDashboard() {
-  const runs = await durably.getRuns({ limit: 20 })
-
-  if (runs.length === 0) {
-    runsTbody.innerHTML = `No runs yet`
-    runDetailsEl.style.display = 'none'
-    return
-  }
-
-  runsTbody.innerHTML = runs
-    .map(
-      (run) => `
-    
-      ${run.id.slice(0, 8)}...
-      ${run.jobName}
-      ${run.status}
-      ${formatDate(run.createdAt)}
-      
-        
-        ${run.status === 'failed' ? `` : ''}
-        ${run.status === 'running' || run.status === 'pending' ? `` : ''}
-        ${run.status !== 'running' && run.status !== 'pending' ? `` : ''}
-      
-    
-  `,
-    )
-    .join('')
-
-  // Add event listeners
-  runsTbody.querySelectorAll('.view-btn').forEach((btn) => {
-    btn.addEventListener('click', () => {
-      const id = (btn as HTMLElement).dataset.id
-      if (id) showRunDetails(id)
-    })
-  })
-  runsTbody.querySelectorAll('.retry-btn').forEach((btn) => {
-    btn.addEventListener('click', async () => {
-      const id = (btn as HTMLElement).dataset.id
-      if (id) {
-        await durably.retry(id)
-        refreshDashboard()
-      }
-    })
-  })
-  runsTbody.querySelectorAll('.cancel-btn').forEach((btn) => {
-    btn.addEventListener('click', async () => {
-      const id = (btn as HTMLElement).dataset.id
-      if (id) {
-        await durably.cancel(id)
-        refreshDashboard()
-      }
-    })
-  })
-  runsTbody.querySelectorAll('.delete-btn').forEach((btn) => {
-    btn.addEventListener('click', async () => {
-      const id = (btn as HTMLElement).dataset.id
-      if (id) {
-        await durably.deleteRun(id)
-        refreshDashboard()
-      }
-    })
-  })
-}
-
-async function showRunDetails(runId: string) {
-  const run = await durably.getRun(runId)
-  if (!run) {
-    runDetailsEl.style.display = 'none'
-    return
-  }
-
-  const steps = await durably.storage.getSteps(runId)
-
-  detailsContent.innerHTML = `
-    
ID: ${escapeHtml(run.id)}

-    
Job: ${escapeHtml(run.jobName)}

-    
Status: ${run.status}

-    
Created: ${formatDate(run.createdAt)}

-    ${run.progress ? `
Progress: ${run.progress.current}${run.progress.total ? `/${run.progress.total}` : ''} ${escapeHtml(run.progress.message || '')}
` : ''}
-    ${run.error ? `
Error: ${escapeHtml(run.error)}
` : ''}
-    ${run.output ? `
Output:
${escapeHtml(JSON.stringify(run.output, null, 2))}
` : ''}
-    
Payload:

-    
${escapeHtml(JSON.stringify(run.payload, null, 2))}

-    ${
-      steps.length > 0
-        ? `
-      
Steps:

-      
    
-        ${steps.map((s) => `
  • ${escapeHtml(s.name)}${s.status}
    • `).join('')}
-      

-    `
-        : ''
-    }
-  `
-  runDetailsEl.style.display = 'block'
-}
-
-function formatDate(iso: string): string {
-  return new Date(iso).toLocaleString()
-}
diff --git a/examples/browser/src/main.ts b/examples/browser/src/main.ts
deleted file mode 100644
index 36b83688..00000000
--- a/examples/browser/src/main.ts
+++ /dev/null
@@ -1,178 +0,0 @@
-/**
- * Browser Example for Durably
- *
- * Simple example showing basic durably usage in the browser.
- * Demonstrates job resumption after page reload.
- */
-
-import { createDurably, defineJob } from '@coji/durably'
-import { SQLocalKysely } from 'sqlocal/kysely'
-import { z } from 'zod'
-import { initDashboard, refreshDashboard } from './dashboard'
-
-// Initialize Durably
-const sqlocal = new SQLocalKysely('example.sqlite3')
-const { dialect, deleteDatabaseFile } = sqlocal
-
-const durably = createDurably({
-  dialect,
-  pollingInterval: 100,
-  heartbeatInterval: 500,
-  staleThreshold: 3000,
-})
-
-// Define job
-const { processImage } = durably.register({
-  processImage: defineJob({
-    name: 'process-image',
-    input: z.object({ filename: z.string(), width: z.number() }),
-    output: z.object({ url: z.string(), size: z.number() }),
-    run: async (step, payload) => {
-      // Download original image
-      const fileSize = await step.run('download', async () => {
-        await delay(300)
-        return Math.floor(Math.random() * 1000000) + 500000 // 500KB-1.5MB
-      })
-
-      // Resize to target width
-      const resizedSize = await step.run('resize', async () => {
-        await delay(400)
-        return Math.floor(fileSize * (payload.width / 1920))
-      })
-
-      // Upload to CDN
-      const url = await step.run('upload', async () => {
-        await delay(300)
-        return `https://cdn.example.com/${payload.width}/${payload.filename}`
-      })
-
-      return { url, size: resizedSize }
-    },
-  }),
-})
-
-const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
-
-// ============================================
-// Demo Tab
-// ============================================
-
-const statusEl = document.getElementById('status') as HTMLElement
-const stepEl = document.getElementById('step') as HTMLElement
-const resultEl = document.getElementById('result') as HTMLPreElement
-const runBtn = document.getElementById('run-btn') as HTMLButtonElement
-const reloadBtn = document.getElementById('reload-btn') as HTMLButtonElement
-const resetBtn = document.getElementById('reset-btn') as HTMLButtonElement
-
-let userTriggered = false
-
-const statusText: Record = {
-  init: 'Initializing...',
-  ready: 'Ready',
-  running: 'Running',
-  resuming: '🔄 Resuming interrupted job...',
-  done: '✓ Completed',
-  error: '✗ Failed',
-}
-
-function setStatus(status: string) {
-  statusEl.textContent = statusText[status] || status
-}
-
-function setStep(step: string | null) {
-  stepEl.textContent = step ? `Step: ${step}` : ''
-}
-
-function setResult(result: string | null, isError = false) {
-  resultEl.textContent = result || ''
-  resultEl.className = isError ? 'result error' : 'result'
-}
-
-function setProcessing(processing: boolean) {
-  runBtn.disabled = processing
-  resetBtn.disabled = processing
-}
-
-// Subscribe to events
-durably.on('run:start', () => {
-  setStatus(userTriggered ? 'running' : 'resuming')
-  setProcessing(true)
-})
-
-durably.on('step:complete', (e) => {
-  setStep(e.stepName)
-})
-
-durably.on('run:complete', (e) => {
-  setResult(JSON.stringify(e.output, null, 2))
-  setStep(null)
-  setStatus('done')
-  setProcessing(false)
-  userTriggered = false
-  refreshDashboard()
-})
-
-durably.on('run:fail', (e) => {
-  setResult(e.error, true)
-  setStep(null)
-  setStatus('error')
-  setProcessing(false)
-  userTriggered = false
-  refreshDashboard()
-})
-
-// Button handlers
-runBtn.addEventListener('click', async () => {
-  userTriggered = true
-  setStatus('running')
-  setStep(null)
-  setResult(null)
-  await processImage.trigger({ filename: 'photo.jpg', width: 800 })
-  refreshDashboard()
-})
-
-reloadBtn.addEventListener('click', () => {
-  location.reload()
-})
-
-resetBtn.addEventListener('click', async () => {
-  await durably.stop()
-  await deleteDatabaseFile()
-  location.reload()
-})
-
-// ============================================
-// Tab Navigation
-// ============================================
-
-const tabs = Array.from(document.querySelectorAll('.tab'))
-const tabContents = Array.from(document.querySelectorAll('.tab-content'))
-
-for (const tab of tabs) {
-  tab.addEventListener('click', () => {
-    const tabName = (tab as HTMLElement).dataset.tab
-    for (const t of tabs) t.classList.remove('active')
-    for (const c of tabContents) c.classList.remove('active')
-    tab.classList.add('active')
-    document.getElementById(`${tabName}-tab`)?.classList.add('active')
-
-    if (tabName === 'dashboard') {
-      refreshDashboard()
-    }
-  })
-}
-
-// ============================================
-// Initialize
-// ============================================
-
-initDashboard(durably)
-
-durably.migrate().then(() => {
-  durably.start()
-  setStatus('ready')
-  runBtn.disabled = false
-  reloadBtn.disabled = false
-  resetBtn.disabled = false
-  refreshDashboard()
-})
diff --git a/examples/browser/tsconfig.json b/examples/browser/tsconfig.json
deleted file mode 100644
index 7fce9f12..00000000
--- a/examples/browser/tsconfig.json
+++ /dev/null
@@ -1,13 +0,0 @@
-{
-  "compilerOptions": {
-    "target": "ES2022",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "strict": true,
-    "skipLibCheck": true,
-    "esModuleInterop": true,
-    "noEmit": true,
-    "lib": ["ES2022", "DOM"]
-  },
-  "include": ["src/**/*.ts"]
-}
diff --git a/examples/browser/vercel.json b/examples/browser/vercel.json
deleted file mode 100644
index ae3c460f..00000000
--- a/examples/browser/vercel.json
+++ /dev/null
@@ -1,12 +0,0 @@
-{
-  "$schema": "https://openapi.vercel.sh/vercel.json",
-  "headers": [
-    {
-      "source": "/(.*)",
-      "headers": [
-        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" },
-        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" }
-      ]
-    }
-  ]
-}
diff --git a/examples/browser/vite.config.ts b/examples/browser/vite.config.ts
deleted file mode 100644
index 202a8d1f..00000000
--- a/examples/browser/vite.config.ts
+++ /dev/null
@@ -1,22 +0,0 @@
-import { defineConfig } from 'vite'
-
-export default defineConfig({
-  plugins: [
-    {
-      name: 'configure-response-headers',
-      configureServer: (server) => {
-        server.middlewares.use((_req, res, next) => {
-          res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
-          res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-          next()
-        })
-      },
-    },
-  ],
-  optimizeDeps: {
-    exclude: ['sqlocal'],
-  },
-  worker: {
-    format: 'es',
-  },
-})
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 02a07205..bedb0a47 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -30,37 +30,6 @@ importers:
         specifier: ^5.9.3
         version: 5.9.3
 
-  examples/browser:
-    dependencies:
-      '@coji/durably':
-        specifier: workspace:*
-        version: link:../../packages/durably
-      kysely:
-        specifier: ^0.28.9
-        version: 0.28.9
-      sqlocal:
-        specifier: ^0.16.0
-        version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3))
-      zod:
-        specifier: ^4.2.1
-        version: 4.2.1
-    devDependencies:
-      '@biomejs/biome':
-        specifier: ^2.3.10
-        version: 2.3.10
-      prettier:
-        specifier: ^3.7.4
-        version: 3.7.4
-      prettier-plugin-organize-imports:
-        specifier: ^4.3.0
-        version: 4.3.0(prettier@3.7.4)(typescript@5.9.3)
-      typescript:
-        specifier: ^5.9.3
-        version: 5.9.3
-      vite:
-        specifier: ^7.3.0
-        version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-
   examples/node:
     dependencies:
       '@coji/durably':

From 3b125e31384e06e2473c4a63f28e05d6cef53664 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 00:37:25 +0900
Subject: [PATCH 050/101] feat(example-react-router): add cancel button to
 dashboard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Use useRunActions hook to cancel pending/running jobs from the dashboard.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/react-router/app/routes/_index.tsx   |  4 +-
 .../app/routes/_index/dashboard.tsx           | 56 +++++++++++++------
 2 files changed, 40 insertions(+), 20 deletions(-)

diff --git a/examples/react-router/app/routes/_index.tsx b/examples/react-router/app/routes/_index.tsx
index 2d4a9a93..ffb77ea4 100644
--- a/examples/react-router/app/routes/_index.tsx
+++ b/examples/react-router/app/routes/_index.tsx
@@ -106,9 +106,9 @@ export default function Home() {
                     id="rowCount"
                     name="rowCount"
                     type="number"
-                    defaultValue={10}
+                    defaultValue={100}
                     min={1}
-                    max={100}
+                    max={1000}
                     className="border border-gray-300 rounded-md px-3 py-2 w-full focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
                   />
                 

diff --git a/examples/react-router/app/routes/_index/dashboard.tsx b/examples/react-router/app/routes/_index/dashboard.tsx
index 8b35ab9a..b3cfbd77 100644
--- a/examples/react-router/app/routes/_index/dashboard.tsx
+++ b/examples/react-router/app/routes/_index/dashboard.tsx
@@ -5,16 +5,24 @@
  * First page auto-subscribes to SSE for instant updates.
  */
 
-import { useRuns } from '@coji/durably-react/client'
+import { useRunActions, useRuns } from '@coji/durably-react/client'
 
 export function Dashboard() {
-  const { runs, isLoading, error, page, hasMore, nextPage, prevPage } = useRuns(
-    {
+  const { runs, isLoading, error, page, hasMore, nextPage, prevPage, refresh } =
+    useRuns({
       api: '/api/durably',
       jobName: 'import-csv',
       pageSize: 6,
-    },
-  )
+    })
+
+  const { cancel, isLoading: isCancelling } = useRunActions({
+    api: '/api/durably',
+  })
+
+  const handleCancel = async (runId: string) => {
+    await cancel(runId)
+    refresh()
+  }
 
   return (
     

@@ -43,19 +51,31 @@ export function Dashboard() {
                     {new Date(r.createdAt).toLocaleString()}
                   
                 

-                
-                  {r.status}
-                
+                

+                  {(r.status === 'pending' || r.status === 'running') && (
+                    
+                  )}
+                  
+                    {r.status}
+                  
+                

               
             ))}
           

From b33c22062f812a1182ec738a75e151fafb9fda2f Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 10:46:30 +0900
Subject: [PATCH 051/101] feat(durably-react): add real-time progress updates
 via SSE
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add run:progress event subscription to SSE handler in server
- Update useRuns hook to handle progress events and update runs in place
- Add progress property to ClientRun interface
- Display progress bar in dashboard example

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/react-router/app/routes/_index.tsx   |  2 +-
 .../app/routes/_index/dashboard.tsx           | 34 ++++++++++++++-----
 packages/durably-react/src/client/use-runs.ts | 21 ++++++++----
 packages/durably/src/server.ts                | 14 ++++++++
 4 files changed, 55 insertions(+), 16 deletions(-)

diff --git a/examples/react-router/app/routes/_index.tsx b/examples/react-router/app/routes/_index.tsx
index ffb77ea4..e6e5d17d 100644
--- a/examples/react-router/app/routes/_index.tsx
+++ b/examples/react-router/app/routes/_index.tsx
@@ -44,7 +44,7 @@ function generateDummyRows(count: number) {
   }))
 }
 
-// Action: Trigger job from Form submit
+// Action: Trigger job
 export async function action({ request }: Route.ActionArgs) {
   const formData = await request.formData()
   const filename = formData.get('filename') as string
diff --git a/examples/react-router/app/routes/_index/dashboard.tsx b/examples/react-router/app/routes/_index/dashboard.tsx
index b3cfbd77..b8bcf460 100644
--- a/examples/react-router/app/routes/_index/dashboard.tsx
+++ b/examples/react-router/app/routes/_index/dashboard.tsx
@@ -42,14 +42,32 @@ export function Dashboard() {
           
    
             {runs.map((r) => (
               
  • 
-                
    
-                  
-                    {r.id.slice(0, 8)}
-                  
-                  -
-                  
-                    {new Date(r.createdAt).toLocaleString()}
-                  
+                
    
+                  
    
+                    
+                      {r.id.slice(0, 8)}
+                    
+                    -
+                    
+                      {new Date(r.createdAt).toLocaleString()}
+                    
+                  
    
+                  {r.progress && (
+                    
    
+                      
    
+                        
    
+                      
    
+                      
+                        {r.progress.current}
+                        {r.progress.total && `/${r.progress.total}`}
+                      
+                    
    
+                  )}
                 
    
                 
    
                   {(r.status === 'pending' || r.status === 'running') && (
diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts
index 7621fab2..e04124cd 100644
--- a/packages/durably-react/src/client/use-runs.ts
+++ b/packages/durably-react/src/client/use-runs.ts
@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useRef, useState } from 'react'
-import type { RunStatus } from '../types'
+import type { Progress, RunStatus } from '../types'
 
 /**
  * Run type for client mode (matches server response)
@@ -11,6 +11,7 @@ export interface ClientRun {
   input: unknown
   output: unknown | null
   error: string | null
+  progress: Progress | null
   createdAt: string
   startedAt: string | null
   completedAt: string | null
@@ -19,11 +20,9 @@ export interface ClientRun {
 /**
  * SSE notification event from /runs/subscribe
  */
-interface RunUpdateEvent {
-  type: 'run:start' | 'run:complete' | 'run:fail'
-  runId: string
-  jobName: string
-}
+type RunUpdateEvent =
+  | { type: 'run:start' | 'run:complete' | 'run:fail'; runId: string; jobName: string }
+  | { type: 'run:progress'; runId: string; jobName: string; progress: Progress }
 
 export interface UseRunsClientOptions {
   /**
@@ -191,7 +190,7 @@ export function useRuns(options: UseRunsClientOptions): UseRunsClientResult {
     eventSource.onmessage = (event) => {
       try {
         const data = JSON.parse(event.data) as RunUpdateEvent
-        // On any run update, refresh the list
+        // On run lifecycle events, refresh the list
         if (
           data.type === 'run:start' ||
           data.type === 'run:complete' ||
@@ -199,6 +198,14 @@ export function useRuns(options: UseRunsClientOptions): UseRunsClientResult {
         ) {
           refresh()
         }
+        // On progress update, update the run in place
+        if (data.type === 'run:progress') {
+          setRuns((prev) =>
+            prev.map((run) =>
+              run.id === data.runId ? { ...run, progress: data.progress } : run,
+            ),
+          )
+        }
       } catch {
         // Ignore parse errors
       }
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index a962cf5b..26dfd22f 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -416,12 +416,26 @@ export function createDurablyHandler(
             controller.enqueue(encoder.encode(data))
           })
 
+          const unsubscribeProgress = durably.on('run:progress', (event) => {
+            if (closed) return
+            if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'run:progress',
+              runId: event.runId,
+              jobName: event.jobName,
+              progress: event.progress,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
           // Store cleanup function for cancel
           ;(controller as unknown as { cleanup: () => void }).cleanup = () => {
             closed = true
             unsubscribeStart()
             unsubscribeComplete()
             unsubscribeFail()
+            unsubscribeProgress()
           }
         },
         cancel(controller) {

From 5d15314986e8f9adfcad1768a84b2e6a0d611734 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 10:51:19 +0900
Subject: [PATCH 052/101] test(durably-react): add client mode useRuns hook
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Test coverage for:
- Fetching runs on mount
- Filtering by jobName and status
- Pagination (nextPage, prevPage, goToPage)
- SSE subscription on first page only
- Real-time updates: run:start, run:complete, run:fail trigger refresh
- Progress updates: run:progress updates run in place without fetch
- Error handling and refresh functionality

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../tests/client/use-runs.test.tsx            | 434 ++++++++++++++++++
 1 file changed, 434 insertions(+)
 create mode 100644 packages/durably-react/tests/client/use-runs.test.tsx

diff --git a/packages/durably-react/tests/client/use-runs.test.tsx b/packages/durably-react/tests/client/use-runs.test.tsx
new file mode 100644
index 00000000..7b90ff43
--- /dev/null
+++ b/packages/durably-react/tests/client/use-runs.test.tsx
@@ -0,0 +1,434 @@
+/**
+ * Client mode useRuns tests
+ *
+ * Test runs listing via fetch and SSE subscription
+ */
+
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useRuns, type ClientRun } from '../../src/client/use-runs'
+import {
+  createMockEventSource,
+  type MockEventSourceConstructor,
+} from './mock-event-source'
+
+const createMockRun = (overrides: Partial = {}): ClientRun => ({
+  id: 'run-1',
+  jobName: 'test-job',
+  status: 'pending',
+  input: { value: 1 },
+  output: null,
+  error: null,
+  progress: null,
+  createdAt: '2024-01-01T00:00:00.000Z',
+  startedAt: null,
+  completedAt: null,
+  ...overrides,
+})
+
+describe('useRuns (client)', () => {
+  let mockEventSource: MockEventSourceConstructor
+  let originalEventSource: typeof EventSource
+  let originalFetch: typeof fetch
+
+  beforeEach(() => {
+    mockEventSource = createMockEventSource()
+    originalEventSource = globalThis.EventSource
+    originalFetch = globalThis.fetch
+    globalThis.EventSource = mockEventSource as unknown as typeof EventSource
+  })
+
+  afterEach(() => {
+    globalThis.EventSource = originalEventSource
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  it('fetches runs on mount', async () => {
+    const mockRuns = [createMockRun({ id: 'run-1' }), createMockRun({ id: 'run-2' })]
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockRuns),
+    })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() =>
+      useRuns({ api: '/api/durably' }),
+    )
+
+    expect(result.current.isLoading).toBe(true)
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.stringContaining('/api/durably/runs?'),
+    )
+    expect(result.current.runs).toHaveLength(2)
+    expect(result.current.runs[0].id).toBe('run-1')
+  })
+
+  it('filters by jobName', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() =>
+      useRuns({ api: '/api/durably', jobName: 'my-job' }),
+    )
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalled()
+    })
+
+    const url = fetchMock.mock.calls[0][0] as string
+    expect(url).toContain('jobName=my-job')
+  })
+
+  it('filters by status', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() =>
+      useRuns({ api: '/api/durably', status: 'completed' }),
+    )
+
+    await waitFor(() => {
+      expect(fetchMock).toHaveBeenCalled()
+    })
+
+    const url = fetchMock.mock.calls[0][0] as string
+    expect(url).toContain('status=completed')
+  })
+
+  it('handles pagination', async () => {
+    const page1Runs = [
+      createMockRun({ id: 'run-1' }),
+      createMockRun({ id: 'run-2' }),
+      createMockRun({ id: 'run-3' }), // Extra item indicates hasMore
+    ]
+    const page2Runs = [createMockRun({ id: 'run-4' })]
+
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(page1Runs),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve(page2Runs),
+      })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() =>
+      useRuns({ api: '/api/durably', pageSize: 2 }),
+    )
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    expect(result.current.runs).toHaveLength(2)
+    expect(result.current.hasMore).toBe(true)
+    expect(result.current.page).toBe(0)
+
+    // Go to next page
+    act(() => {
+      result.current.nextPage()
+    })
+
+    await waitFor(() => {
+      expect(result.current.page).toBe(1)
+    })
+
+    await waitFor(() => {
+      expect(result.current.runs[0].id).toBe('run-4')
+    })
+  })
+
+  it('subscribes to SSE on first page', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    expect(mockEventSource.instances[0].url).toContain('/api/durably/runs/subscribe')
+  })
+
+  it('includes jobName filter in SSE URL', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() =>
+      useRuns({ api: '/api/durably', jobName: 'my-job' }),
+    )
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    expect(mockEventSource.instances[0].url).toContain('jobName=my-job')
+  })
+
+  it('refreshes on run:start event', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    const initialCallCount = fetchMock.mock.calls.length
+
+    act(() => {
+      mockEventSource.emit({ type: 'run:start', runId: 'new-run', jobName: 'test-job' })
+    })
+
+    await waitFor(() => {
+      expect(fetchMock.mock.calls.length).toBeGreaterThan(initialCallCount)
+    })
+  })
+
+  it('refreshes on run:complete event', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    const initialCallCount = fetchMock.mock.calls.length
+
+    act(() => {
+      mockEventSource.emit({ type: 'run:complete', runId: 'run-1', jobName: 'test-job' })
+    })
+
+    await waitFor(() => {
+      expect(fetchMock.mock.calls.length).toBeGreaterThan(initialCallCount)
+    })
+  })
+
+  it('refreshes on run:fail event', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    const initialCallCount = fetchMock.mock.calls.length
+
+    act(() => {
+      mockEventSource.emit({ type: 'run:fail', runId: 'run-1', jobName: 'test-job' })
+    })
+
+    await waitFor(() => {
+      expect(fetchMock.mock.calls.length).toBeGreaterThan(initialCallCount)
+    })
+  })
+
+  it('updates progress in place on run:progress event', async () => {
+    const mockRuns = [
+      createMockRun({ id: 'run-1', status: 'running' }),
+      createMockRun({ id: 'run-2', status: 'running' }),
+    ]
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(mockRuns),
+    })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(result.current.runs).toHaveLength(2)
+    })
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    const callCountBeforeProgress = fetchMock.mock.calls.length
+
+    act(() => {
+      mockEventSource.emit({
+        type: 'run:progress',
+        runId: 'run-1',
+        jobName: 'test-job',
+        progress: { current: 5, total: 10, message: 'Processing...' },
+      })
+    })
+
+    await waitFor(() => {
+      expect(result.current.runs[0].progress).toEqual({
+        current: 5,
+        total: 10,
+        message: 'Processing...',
+      })
+    })
+
+    // Verify no fetch was triggered for progress update
+    expect(fetchMock.mock.calls.length).toBe(callCountBeforeProgress)
+
+    // Other runs should not be affected
+    expect(result.current.runs[1].progress).toBeNull()
+  })
+
+  it('does not subscribe to SSE on non-first pages', async () => {
+    const page1Runs = [
+      createMockRun({ id: 'run-1' }),
+      createMockRun({ id: 'run-2' }),
+      createMockRun({ id: 'run-3' }), // Extra for hasMore
+    ]
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve(page1Runs),
+    })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() =>
+      useRuns({ api: '/api/durably', pageSize: 2 }),
+    )
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    const instancesOnPage0 = mockEventSource.instances.length
+
+    act(() => {
+      result.current.nextPage()
+    })
+
+    await waitFor(() => {
+      expect(result.current.page).toBe(1)
+    })
+
+    // EventSource should be closed, no new instances created
+    // (actually the old one is closed but counts remain)
+    expect(mockEventSource.instances[instancesOnPage0 - 1].readyState).toBe(2) // CLOSED
+  })
+
+  it('handles fetch errors', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: false,
+      statusText: 'Internal Server Error',
+    })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(result.current.error).toBe('Failed to fetch runs: Internal Server Error')
+    })
+
+    expect(result.current.isLoading).toBe(false)
+    expect(result.current.runs).toEqual([])
+  })
+
+  it('refresh reloads data', async () => {
+    const fetchMock = vi
+      .fn()
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () => Promise.resolve([createMockRun({ id: 'run-1' })]),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        json: () =>
+          Promise.resolve([
+            createMockRun({ id: 'run-1' }),
+            createMockRun({ id: 'run-2' }),
+          ]),
+      })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(result.current.runs).toHaveLength(1)
+    })
+
+    await act(async () => {
+      await result.current.refresh()
+    })
+
+    expect(result.current.runs).toHaveLength(2)
+  })
+
+  it('goToPage navigates directly', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    act(() => {
+      result.current.goToPage(5)
+    })
+
+    await waitFor(() => {
+      expect(result.current.page).toBe(5)
+    })
+  })
+
+  it('prevPage does not go below 0', async () => {
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      json: () => Promise.resolve([]),
+    })
+    globalThis.fetch = fetchMock
+
+    const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
+
+    await waitFor(() => {
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    expect(result.current.page).toBe(0)
+
+    act(() => {
+      result.current.prevPage()
+    })
+
+    expect(result.current.page).toBe(0)
+  })
+})

From 2eeadab3017e4ed9bd87fe7f61da130e19cf6d43 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 14:58:18 +0900
Subject: [PATCH 053/101] style: fix formatting in use-runs files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/client/use-runs.ts |  6 ++-
 .../tests/client/use-runs.test.tsx            | 47 ++++++++++++-------
 2 files changed, 34 insertions(+), 19 deletions(-)

diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts
index e04124cd..a3ab7a55 100644
--- a/packages/durably-react/src/client/use-runs.ts
+++ b/packages/durably-react/src/client/use-runs.ts
@@ -21,7 +21,11 @@ export interface ClientRun {
  * SSE notification event from /runs/subscribe
  */
 type RunUpdateEvent =
-  | { type: 'run:start' | 'run:complete' | 'run:fail'; runId: string; jobName: string }
+  | {
+      type: 'run:start' | 'run:complete' | 'run:fail'
+      runId: string
+      jobName: string
+    }
   | { type: 'run:progress'; runId: string; jobName: string; progress: Progress }
 
 export interface UseRunsClientOptions {
diff --git a/packages/durably-react/tests/client/use-runs.test.tsx b/packages/durably-react/tests/client/use-runs.test.tsx
index 7b90ff43..005479db 100644
--- a/packages/durably-react/tests/client/use-runs.test.tsx
+++ b/packages/durably-react/tests/client/use-runs.test.tsx
@@ -45,16 +45,17 @@ describe('useRuns (client)', () => {
   })
 
   it('fetches runs on mount', async () => {
-    const mockRuns = [createMockRun({ id: 'run-1' }), createMockRun({ id: 'run-2' })]
+    const mockRuns = [
+      createMockRun({ id: 'run-1' }),
+      createMockRun({ id: 'run-2' }),
+    ]
     const fetchMock = vi.fn().mockResolvedValue({
       ok: true,
       json: () => Promise.resolve(mockRuns),
     })
     globalThis.fetch = fetchMock
 
-    const { result } = renderHook(() =>
-      useRuns({ api: '/api/durably' }),
-    )
+    const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
 
     expect(result.current.isLoading).toBe(true)
 
@@ -76,9 +77,7 @@ describe('useRuns (client)', () => {
     })
     globalThis.fetch = fetchMock
 
-    renderHook(() =>
-      useRuns({ api: '/api/durably', jobName: 'my-job' }),
-    )
+    renderHook(() => useRuns({ api: '/api/durably', jobName: 'my-job' }))
 
     await waitFor(() => {
       expect(fetchMock).toHaveBeenCalled()
@@ -95,9 +94,7 @@ describe('useRuns (client)', () => {
     })
     globalThis.fetch = fetchMock
 
-    renderHook(() =>
-      useRuns({ api: '/api/durably', status: 'completed' }),
-    )
+    renderHook(() => useRuns({ api: '/api/durably', status: 'completed' }))
 
     await waitFor(() => {
       expect(fetchMock).toHaveBeenCalled()
@@ -166,7 +163,9 @@ describe('useRuns (client)', () => {
       expect(mockEventSource.instances.length).toBeGreaterThan(0)
     })
 
-    expect(mockEventSource.instances[0].url).toContain('/api/durably/runs/subscribe')
+    expect(mockEventSource.instances[0].url).toContain(
+      '/api/durably/runs/subscribe',
+    )
   })
 
   it('includes jobName filter in SSE URL', async () => {
@@ -176,9 +175,7 @@ describe('useRuns (client)', () => {
     })
     globalThis.fetch = fetchMock
 
-    renderHook(() =>
-      useRuns({ api: '/api/durably', jobName: 'my-job' }),
-    )
+    renderHook(() => useRuns({ api: '/api/durably', jobName: 'my-job' }))
 
     await waitFor(() => {
       expect(mockEventSource.instances.length).toBeGreaterThan(0)
@@ -203,7 +200,11 @@ describe('useRuns (client)', () => {
     const initialCallCount = fetchMock.mock.calls.length
 
     act(() => {
-      mockEventSource.emit({ type: 'run:start', runId: 'new-run', jobName: 'test-job' })
+      mockEventSource.emit({
+        type: 'run:start',
+        runId: 'new-run',
+        jobName: 'test-job',
+      })
     })
 
     await waitFor(() => {
@@ -227,7 +228,11 @@ describe('useRuns (client)', () => {
     const initialCallCount = fetchMock.mock.calls.length
 
     act(() => {
-      mockEventSource.emit({ type: 'run:complete', runId: 'run-1', jobName: 'test-job' })
+      mockEventSource.emit({
+        type: 'run:complete',
+        runId: 'run-1',
+        jobName: 'test-job',
+      })
     })
 
     await waitFor(() => {
@@ -251,7 +256,11 @@ describe('useRuns (client)', () => {
     const initialCallCount = fetchMock.mock.calls.length
 
     act(() => {
-      mockEventSource.emit({ type: 'run:fail', runId: 'run-1', jobName: 'test-job' })
+      mockEventSource.emit({
+        type: 'run:fail',
+        runId: 'run-1',
+        jobName: 'test-job',
+      })
     })
 
     await waitFor(() => {
@@ -351,7 +360,9 @@ describe('useRuns (client)', () => {
     const { result } = renderHook(() => useRuns({ api: '/api/durably' }))
 
     await waitFor(() => {
-      expect(result.current.error).toBe('Failed to fetch runs: Internal Server Error')
+      expect(result.current.error).toBe(
+        'Failed to fetch runs: Internal Server Error',
+      )
     })
 
     expect(result.current.isLoading).toBe(false)

From 5f809f367b7fea50c08c165d904c5d1f484e1828 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 15:11:29 +0900
Subject: [PATCH 054/101] fix(durably-react): add 'cancelled' to RunStatus type
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The core package already supports 'cancelled' status but the React
bindings were missing it in the type definition.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/types.ts        | 7 ++++++-
 packages/durably-react/tests/types.test.ts | 4 ++--
 2 files changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/durably-react/src/types.ts b/packages/durably-react/src/types.ts
index 90fa90ee..50974709 100644
--- a/packages/durably-react/src/types.ts
+++ b/packages/durably-react/src/types.ts
@@ -1,6 +1,11 @@
 // Shared type definitions for @coji/durably-react
 
-export type RunStatus = 'pending' | 'running' | 'completed' | 'failed'
+export type RunStatus =
+  | 'pending'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
 
 export interface Progress {
   current: number
diff --git a/packages/durably-react/tests/types.test.ts b/packages/durably-react/tests/types.test.ts
index f0826bd8..dd00d4d8 100644
--- a/packages/durably-react/tests/types.test.ts
+++ b/packages/durably-react/tests/types.test.ts
@@ -35,7 +35,7 @@ describe('Type inference', () => {
 
       expectTypeOf().toEqualTypeOf()
       expectTypeOf().toEqualTypeOf<
-        'pending' | 'running' | 'completed' | 'failed' | null
+        'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | null
       >()
       expectTypeOf().toEqualTypeOf<{
         success: boolean
@@ -88,7 +88,7 @@ describe('Type inference', () => {
         data: number[]
       } | null>()
       expectTypeOf().toEqualTypeOf<
-        'pending' | 'running' | 'completed' | 'failed' | null
+        'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | null
       >()
       expectTypeOf().toEqualTypeOf()
     })

From e14cc4224f5fd8cd8bfe4c1e7f6e24495136c5e0 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 15:16:46 +0900
Subject: [PATCH 055/101] test(durably-react): add useRunActions client mode
 tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Test coverage for retry and cancel actions:
- Correct endpoint URLs with encoded runId
- Loading state during requests
- Error handling and state updates
- Error message fallback to statusText
- Error clearing on new requests

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../tests/client/use-run-actions.test.tsx     | 359 ++++++++++++++++++
 1 file changed, 359 insertions(+)
 create mode 100644 packages/durably-react/tests/client/use-run-actions.test.tsx

diff --git a/packages/durably-react/tests/client/use-run-actions.test.tsx b/packages/durably-react/tests/client/use-run-actions.test.tsx
new file mode 100644
index 00000000..18827835
--- /dev/null
+++ b/packages/durably-react/tests/client/use-run-actions.test.tsx
@@ -0,0 +1,359 @@
+/**
+ * Client mode useRunActions tests
+ *
+ * Test retry and cancel actions via fetch
+ */
+
+import { act, renderHook } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { useRunActions } from '../../src/client/use-run-actions'
+
+describe('useRunActions (client)', () => {
+  let originalFetch: typeof fetch
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch
+  })
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch
+    vi.restoreAllMocks()
+  })
+
+  describe('retry', () => {
+    it('calls retry endpoint with runId', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ success: true }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      await act(async () => {
+        await result.current.retry('run-123')
+      })
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        '/api/durably/retry?runId=run-123',
+        { method: 'POST' },
+      )
+    })
+
+    it('encodes runId in URL', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ success: true }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      await act(async () => {
+        await result.current.retry('run/with/special&chars')
+      })
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        '/api/durably/retry?runId=run%2Fwith%2Fspecial%26chars',
+        { method: 'POST' },
+      )
+    })
+
+    it('sets isLoading during request', async () => {
+      let resolvePromise: () => void
+      const fetchPromise = new Promise((resolve) => {
+        resolvePromise = resolve
+      })
+      const fetchMock = vi.fn().mockImplementation(() =>
+        fetchPromise.then(() => ({
+          ok: true,
+          json: () => Promise.resolve({ success: true }),
+        })),
+      )
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      expect(result.current.isLoading).toBe(false)
+
+      let retryPromise: Promise
+      act(() => {
+        retryPromise = result.current.retry('run-123')
+      })
+
+      expect(result.current.isLoading).toBe(true)
+
+      await act(async () => {
+        resolvePromise!()
+        await retryPromise
+      })
+
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    it('sets error on failure and throws', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Not Found',
+        json: () => Promise.resolve({ error: 'Run not found' }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let thrownError: Error | undefined
+      await act(async () => {
+        try {
+          await result.current.retry('run-123')
+        } catch (err) {
+          thrownError = err as Error
+        }
+      })
+
+      expect(thrownError?.message).toBe('Run not found')
+      expect(result.current.error).toBe('Run not found')
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    it('uses statusText when no error in response', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Internal Server Error',
+        json: () => Promise.resolve({}),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let thrownError: Error | undefined
+      await act(async () => {
+        try {
+          await result.current.retry('run-123')
+        } catch (err) {
+          thrownError = err as Error
+        }
+      })
+
+      expect(thrownError?.message).toBe(
+        'Failed to retry: Internal Server Error',
+      )
+      expect(result.current.error).toBe(
+        'Failed to retry: Internal Server Error',
+      )
+    })
+
+    it('clears error on new request', async () => {
+      const fetchMock = vi
+        .fn()
+        .mockResolvedValueOnce({
+          ok: false,
+          statusText: 'Error',
+          json: () => Promise.resolve({ error: 'First error' }),
+        })
+        .mockResolvedValueOnce({
+          ok: true,
+          json: () => Promise.resolve({ success: true }),
+        })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      // First call fails
+      await act(async () => {
+        try {
+          await result.current.retry('run-123')
+        } catch {
+          // Expected
+        }
+      })
+
+      expect(result.current.error).toBe('First error')
+
+      // Second call succeeds
+      await act(async () => {
+        await result.current.retry('run-123')
+      })
+
+      expect(result.current.error).toBeNull()
+    })
+  })
+
+  describe('cancel', () => {
+    it('calls cancel endpoint with runId', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ success: true }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      await act(async () => {
+        await result.current.cancel('run-456')
+      })
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        '/api/durably/cancel?runId=run-456',
+        { method: 'POST' },
+      )
+    })
+
+    it('encodes runId in URL', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ success: true }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      await act(async () => {
+        await result.current.cancel('run/with/special&chars')
+      })
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        '/api/durably/cancel?runId=run%2Fwith%2Fspecial%26chars',
+        { method: 'POST' },
+      )
+    })
+
+    it('sets isLoading during request', async () => {
+      let resolvePromise: () => void
+      const fetchPromise = new Promise((resolve) => {
+        resolvePromise = resolve
+      })
+      const fetchMock = vi.fn().mockImplementation(() =>
+        fetchPromise.then(() => ({
+          ok: true,
+          json: () => Promise.resolve({ success: true }),
+        })),
+      )
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      expect(result.current.isLoading).toBe(false)
+
+      let cancelPromise: Promise
+      act(() => {
+        cancelPromise = result.current.cancel('run-456')
+      })
+
+      expect(result.current.isLoading).toBe(true)
+
+      await act(async () => {
+        resolvePromise!()
+        await cancelPromise
+      })
+
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    it('sets error on failure and throws', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Bad Request',
+        json: () => Promise.resolve({ error: 'Run already completed' }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let thrownError: Error | undefined
+      await act(async () => {
+        try {
+          await result.current.cancel('run-456')
+        } catch (err) {
+          thrownError = err as Error
+        }
+      })
+
+      expect(thrownError?.message).toBe('Run already completed')
+      expect(result.current.error).toBe('Run already completed')
+      expect(result.current.isLoading).toBe(false)
+    })
+
+    it('uses statusText when no error in response', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Internal Server Error',
+        json: () => Promise.resolve({}),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let thrownError: Error | undefined
+      await act(async () => {
+        try {
+          await result.current.cancel('run-456')
+        } catch (err) {
+          thrownError = err as Error
+        }
+      })
+
+      expect(thrownError?.message).toBe(
+        'Failed to cancel: Internal Server Error',
+      )
+      expect(result.current.error).toBe(
+        'Failed to cancel: Internal Server Error',
+      )
+    })
+  })
+
+  describe('shared state', () => {
+    it('shares isLoading between retry and cancel', async () => {
+      let resolvePromise: () => void
+      const fetchPromise = new Promise((resolve) => {
+        resolvePromise = resolve
+      })
+      const fetchMock = vi.fn().mockImplementation(() =>
+        fetchPromise.then(() => ({
+          ok: true,
+          json: () => Promise.resolve({ success: true }),
+        })),
+      )
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let retryPromise: Promise
+      act(() => {
+        retryPromise = result.current.retry('run-123')
+      })
+
+      expect(result.current.isLoading).toBe(true)
+
+      await act(async () => {
+        resolvePromise!()
+        await retryPromise
+      })
+
+      expect(result.current.isLoading).toBe(false)
+    })
+  })
+})

From 18351858031030783923710d13c72185882c769e Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 15:31:08 +0900
Subject: [PATCH 056/101] docs: sync spec.md with implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add run:progress event to event type definitions and firing table
- Document durably.getJob(name) method for dynamic job retrieval
- Document durably.subscribe(runId) for real-time run subscription
- Add step.runId property documentation to StepContext
- Move subscribe() from v2 planned to v1 implemented
- Fix RunFilter type in job.ts to include cancelled status and limit/offset

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 docs/spec.md                | 57 ++++++++++++++++++++++++++++++++++++-
 packages/durably/src/job.ts |  6 +++-
 2 files changed, 61 insertions(+), 2 deletions(-)

diff --git a/docs/spec.md b/docs/spec.md
index bd385041..96c1a1d6 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -156,6 +156,15 @@ interface RunFilter {
 
 `step.run` に渡す名前は、同一 Run 内で一意でなければならない。同じ名前のステップが複数回実行された場合はエラーとなる。成功したステップは再実行時に自動的にスキップされ、保存済みの戻り値が返される。この挙動は固定であり、ユーザーが選択する必要はない。
 
+`step.runId` プロパティで現在の Run の ID にアクセスできる。これは外部サービスへの通知や、ログに Run ID を含める場合に有用である。
+
+```ts
+const users = await step.run("fetch-users", async () => {
+  console.log(`Processing run: ${step.runId}`)
+  return api.fetchUsers(payload.orgId)
+})
+```
+
 `step.run` の戻り値はステップ関数の戻り値から型推論される。
 
 ```ts
@@ -355,6 +364,38 @@ const failedRuns = await durably.getRuns({
 
 `limit` は取得する最大件数、`offset` はスキップする件数を指定する。両方を組み合わせることで、ページ単位の取得が可能になる。
 
+### ジョブの取得
+
+登録済みのジョブを名前で取得するには `getJob` メソッドを使う。
+
+```ts
+const job = durably.getJob('sync-users')
+if (job) {
+  await job.trigger({ orgId: 'org_123' })
+}
+```
+
+`getJob` は登録済みのジョブがあれば `JobHandle` を返し、なければ `undefined` を返す。これは動的にジョブを取得したい場合（例: API ハンドラでジョブ名をパラメータとして受け取る場合）に有用である。
+
+### Run のリアルタイム購読
+
+Run の実行をリアルタイムで購読するには `subscribe` メソッドを使う。
+
+```ts
+const stream = durably.subscribe(runId)
+
+const reader = stream.getReader()
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+  console.log(value)  // DurablyEvent
+}
+```
+
+`subscribe` は指定した Run の実行中に発火されるイベントを `ReadableStream` として返す。ストリームは `run:complete` または `run:fail` イベントが発火されると自動的にクローズされる。
+
+これにより、UI でのリアルタイム進捗表示や、SSE（Server-Sent Events）を介したクライアントへのイベント配信が可能になる。
+
 ### ワーカー
 
 ワーカーは `start` 関数によって起動される。起動すると、一定間隔で `pending` 状態の Run を取得し、逐次実行する。
@@ -412,6 +453,10 @@ durably.on('run:fail', (event) => {
   // { runId, jobName, error, failedStepName, timestamp }
 })
 
+durably.on('run:progress', (event) => {
+  // { runId, jobName, progress: { current, total?, message? }, timestamp }
+})
+
 durably.on('step:start', (event) => {
   // { runId, jobName, stepName, stepIndex, timestamp }
 })
@@ -473,6 +518,13 @@ interface RunFailEvent extends BaseEvent {
   failedStepName: string
 }
 
+interface RunProgressEvent extends BaseEvent {
+  type: 'run:progress'
+  runId: string
+  jobName: string
+  progress: { current: number; total?: number; message?: string }
+}
+
 // Step イベント
 interface StepStartEvent extends BaseEvent {
   type: 'step:start'
@@ -524,6 +576,7 @@ type DurablyEvent =
   | RunStartEvent
   | RunCompleteEvent
   | RunFailEvent
+  | RunProgressEvent
   | StepStartEvent
   | StepCompleteEvent
   | StepFailEvent
@@ -788,6 +841,7 @@ Run の取得クエリは以下の条件を満たすものを一件取得する
 | run:start | Run が running に遷移した直後 |
 | run:complete | Run が completed に遷移した直後 |
 | run:fail | Run が failed に遷移した直後 |
+| run:progress | step.progress が呼ばれた直後 |
 | step:start | ステップの実行を開始する直前 |
 | step:complete | ステップが成功し DB に記録した直後 |
 | step:fail | ステップが失敗し DB に記録した直後 |
@@ -1038,10 +1092,11 @@ v2 では AI Agent ワークフロー対応として以下の機能が計画さ
 | 機能 | 概要 |
 |------|------|
 | `step.stream()` | ストリーミング出力をサポートするステップ |
-| `subscribe()` | Run の実行をリアルタイムで購読（ReadableStream） |
 | `events` テーブル | 粗いイベント（step:*, run:*）の永続化 |
 | `checkpoint()` | 長時間実行中の中間状態保存 |
 
+注: `subscribe()` は v1 で実装済み。詳細は「Run のリアルタイム購読」セクションを参照。
+
 ### v1 での準備事項
 
 v1 実装時に以下を守ることで、v2 への移行がスムーズになる。
diff --git a/packages/durably/src/job.ts b/packages/durably/src/job.ts
index fb617f85..e238fad3 100644
--- a/packages/durably/src/job.ts
+++ b/packages/durably/src/job.ts
@@ -54,8 +54,12 @@ export interface TriggerOptions {
  * Run filter options
  */
 export interface RunFilter {
-  status?: 'pending' | 'running' | 'completed' | 'failed'
+  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
   jobName?: string
+  /** Maximum number of runs to return */
+  limit?: number
+  /** Number of runs to skip (for pagination) */
+  offset?: number
 }
 
 /**

From fe47fb73e1c7137f001767032b1398495dab8659 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 17:06:31 +0900
Subject: [PATCH 057/101] feat(durably-react): add initialRunId to client mode
 useJob
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add initialRunId option for reconnection scenarios in client mode.
When provided, the hook immediately subscribes to the existing run via SSE.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 docs/spec-react-update-plan.md                | 279 ++++++++++++++++++
 packages/durably-react/src/client/use-job.ts  |  11 +-
 .../tests/client/use-job.test.tsx             | 117 ++++++++
 3 files changed, 405 insertions(+), 2 deletions(-)
 create mode 100644 docs/spec-react-update-plan.md

diff --git a/docs/spec-react-update-plan.md b/docs/spec-react-update-plan.md
new file mode 100644
index 00000000..44cd9608
--- /dev/null
+++ b/docs/spec-react-update-plan.md
@@ -0,0 +1,279 @@
+# spec-react.md 修正プラン
+
+## 概要
+
+`docs/spec-react.md` と実装の差異を解消するための修正プランです。
+
+---
+
+## 1. RunStatus 型に cancelled を追加
+
+**現状 (L386):**
+```ts
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed'
+```
+
+**修正後:**
+```ts
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+```
+
+---
+
+## 2. useJob (browser mode) に autoResume / followLatest オプションを追加
+
+**現状 (L249-253):**
+```
+| 引数 | 型 | 説明 |
+|------|-----|------|
+| `jobDefinition` | `JobDefinition` | ジョブ定義 |
+| `options.initialRunId` | `string` | 初期購読 Run ID |
+```
+
+**修正後:**
+```
+| 引数 | 型 | 説明 |
+|------|-----|------|
+| `jobDefinition` | `JobDefinition` | ジョブ定義 |
+| `options.initialRunId` | `string` | 初期購読 Run ID |
+| `options.autoResume` | `boolean` | pending/running の Run を自動再開（デフォルト: true） |
+| `options.followLatest` | `boolean` | 新しい Run 開始時に自動切替（デフォルト: true） |
+```
+
+---
+
+## 3. client mode useJob の initialRunId ✅ 実装済み
+
+**現状 (L357-364):**
+```
+| オプション     | 型       | 必須 | 説明                        |
+|----------------|----------|------|-----------------------------|
+| `api`          | `string` | Yes  | API エンドポイント          |
+| `jobName`      | `string` | Yes  | ジョブ名                    |
+| `initialRunId` | `string` | -    | 初期購読 Run ID（再接続用） |
+```
+
+→ **仕様通り実装済み。変更不要。**
+
+---
+
+## 4. useRuns hook を追加
+
+「API 仕様」セクションに以下を追加:
+
+### ブラウザ完結モード
+
+```tsx
+const {
+  runs,
+  isLoading,
+  error,
+  page,
+  hasMore,
+  nextPage,
+  prevPage,
+  goToPage,
+  refresh,
+} = useRuns(options?)
+```
+
+| オプション | 型 | 説明 |
+|------------|-----|------|
+| `jobName` | `string` | ジョブ名でフィルタ |
+| `status` | `RunStatus` | ステータスでフィルタ |
+| `limit` | `number` | 1ページの件数（デフォルト: 20） |
+| `realtime` | `boolean` | リアルタイム更新（デフォルト: true） |
+
+### サーバー連携モード
+
+```tsx
+import { useRuns } from '@coji/durably-react/client'
+
+const {
+  runs,
+  isLoading,
+  error,
+  page,
+  hasMore,
+  nextPage,
+  prevPage,
+  goToPage,
+  refresh,
+} = useRuns({
+  api: '/api/durably',
+  jobName?: 'my-job',
+  status?: 'completed',
+  limit?: 20,
+  realtime?: true,
+})
+```
+
+---
+
+## 5. useRunActions hook を追加（client mode のみ）
+
+「サーバー連携モード」セクションに以下を追加:
+
+```tsx
+import { useRunActions } from '@coji/durably-react/client'
+
+const { retry, cancel, isLoading, error } = useRunActions({
+  api: '/api/durably',
+})
+
+// 使用例
+await retry(runId)   // 失敗した Run を再実行
+await cancel(runId)  // 実行中の Run をキャンセル
+```
+
+| 戻り値 | 型 | 説明 |
+|--------|-----|------|
+| `retry` | `(runId: string) => Promise` | Run を再実行 |
+| `cancel` | `(runId: string) => Promise` | Run をキャンセル |
+| `isLoading` | `boolean` | アクション実行中 |
+| `error` | `string \| null` | エラーメッセージ |
+
+---
+
+## 6. createDurablyClient / createJobHooks を追加
+
+「サーバー連携モード」セクションに以下を追加:
+
+### 型安全クライアントファクトリ（推奨）
+
+```tsx
+import { createDurablyClient, createJobHooks } from '@coji/durably-react/client'
+import type { processTask, syncUsers } from './jobs'
+
+// 方法1: createDurablyClient
+const client = createDurablyClient<{
+  'process-task': typeof processTask
+  'sync-users': typeof syncUsers
+}>({ api: '/api/durably' })
+
+const { trigger, status } = client.useJob('process-task')
+await trigger({ taskId: '123' })  // 型安全
+
+// 方法2: createJobHooks
+const { useProcessTask, useSyncUsers } = createJobHooks<{
+  'process-task': typeof processTask
+  'sync-users': typeof syncUsers
+}>({ api: '/api/durably' })
+
+const { trigger, status } = useProcessTask()
+```
+
+---
+
+## 7. DurablyHandler の追加メソッドを文書化
+
+**現状 (L292-293):**
+```ts
+handler.trigger(request: Request): Promise  // POST
+handler.subscribe(request: Request): Response         // GET (SSE)
+```
+
+**修正後:**
+```ts
+// 自動ルーティング（推奨）
+handler.handle(request: Request, basePath: string): Promise
+
+// 個別ハンドラー
+handler.trigger(request: Request): Promise      // POST /trigger
+handler.subscribe(request: Request): Response             // GET /subscribe?runId=xxx
+handler.runs(request: Request): Promise         // GET /runs
+handler.run(request: Request): Promise          // GET /run?runId=xxx
+handler.retry(request: Request): Promise        // POST /retry?runId=xxx
+handler.cancel(request: Request): Promise       // POST /cancel?runId=xxx
+handler.subscribeRuns(request: Request): Response         // GET /runs/subscribe
+```
+
+---
+
+## 8. API ルーティングを実装に合わせて更新
+
+**現状 (L298-301):**
+```
+| エンドポイント | メソッド | リクエスト | レスポンス |
+|---------------|---------|-----------|-----------|
+| `/api/durably` | POST | `{ jobName, input }` | `{ runId }` |
+| `/api/durably?runId=xxx` | GET | - | SSE stream |
+```
+
+**修正後:**
+```
+| エンドポイント | メソッド | リクエスト | レスポンス |
+|---------------|---------|-----------|-----------|
+| `{basePath}/trigger` | POST | `{ jobName, input, idempotencyKey?, concurrencyKey? }` | `{ runId }` |
+| `{basePath}/subscribe?runId=xxx` | GET | - | SSE stream (single run) |
+| `{basePath}/runs` | GET | `?jobName=&status=&limit=&offset=` | `Run[]` |
+| `{basePath}/run?runId=xxx` | GET | - | `Run` or 404 |
+| `{basePath}/retry?runId=xxx` | POST | - | `{ success: true }` |
+| `{basePath}/cancel?runId=xxx` | POST | - | `{ success: true }` |
+| `{basePath}/runs/subscribe` | GET | `?jobName=` | SSE stream (run updates) |
+```
+
+---
+
+## 9. 将来拡張セクションの更新
+
+キャンセル API は実装済みのため、将来拡張から削除し、実装済みとして記載する。
+
+**現状 (L629-642):**
+```
+### キャンセル API
+
+Run のキャンセル機能を追加予定。
+...
+```
+
+**修正後:**
+「将来拡張」セクションからキャンセル API を削除し、上記の useRunActions として文書化済みであることを確認。
+
+---
+
+## 10. サーバー側使用例の更新
+
+**現状 (L109-125):**
+```ts
+const handler = createDurablyHandler(durably)
+
+// POST /api/durably - ジョブ起動
+export async function action({ request }: ActionFunctionArgs) {
+  return handler.trigger(request)
+}
+
+// GET /api/durably?runId=xxx - SSE 購読
+export async function loader({ request }: LoaderFunctionArgs) {
+  return handler.subscribe(request)
+}
+```
+
+**修正後:**
+```ts
+const handler = createDurablyHandler(durably)
+
+// 全ルートを自動処理（推奨）
+export async function loader({ request }: LoaderFunctionArgs) {
+  return handler.handle(request, '/api/durably')
+}
+
+export async function action({ request }: ActionFunctionArgs) {
+  return handler.handle(request, '/api/durably')
+}
+```
+
+---
+
+## 修正優先度
+
+| 優先度 | 項目 | 理由 |
+|--------|------|------|
+| 高 | API ルーティング更新 | 実装と大きく乖離 |
+| 高 | DurablyHandler メソッド追加 | 実装と大きく乖離 |
+| 高 | useRuns hook 追加 | 実装済みだが未文書化 |
+| 高 | useRunActions hook 追加 | 実装済みだが未文書化 |
+| 中 | RunStatus に cancelled 追加 | 型の不一致 |
+| 中 | useJob オプション更新 | 機能の不一致 |
+| 中 | createDurablyClient 追加 | 推奨 API だが未文書化 |
+| 低 | 将来拡張セクション更新 | 実装済み機能の整理 |
diff --git a/packages/durably-react/src/client/use-job.ts b/packages/durably-react/src/client/use-job.ts
index 56e13d96..228e9f3d 100644
--- a/packages/durably-react/src/client/use-job.ts
+++ b/packages/durably-react/src/client/use-job.ts
@@ -11,6 +11,11 @@ export interface UseJobClientOptions {
    * Job name to trigger
    */
   jobName: string
+  /**
+   * Initial Run ID to subscribe to (for reconnection scenarios)
+   * When provided, the hook will immediately start subscribing to this run
+   */
+  initialRunId?: string
 }
 
 export interface UseJobClientResult {
@@ -80,9 +85,11 @@ export function useJob<
   TInput extends Record = Record,
   TOutput extends Record = Record,
 >(options: UseJobClientOptions): UseJobClientResult {
-  const { api, jobName } = options
+  const { api, jobName, initialRunId } = options
 
-  const [currentRunId, setCurrentRunId] = useState(null)
+  const [currentRunId, setCurrentRunId] = useState(
+    initialRunId ?? null,
+  )
   const [isPending, setIsPending] = useState(false)
 
   const subscription = useSSESubscription(api, currentRunId)
diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx
index db205fbd..8813ea8a 100644
--- a/packages/durably-react/tests/client/use-job.test.tsx
+++ b/packages/durably-react/tests/client/use-job.test.tsx
@@ -334,4 +334,121 @@ describe('useJob (client)', () => {
   // Note: triggerAndWait tests are difficult to test with the polling-based implementation
   // because the hook needs to re-render to see the updated subscription.status.
   // The triggerAndWait function is covered indirectly through the browser tests.
+
+  describe('initialRunId', () => {
+    it('sets currentRunId from initialRunId', () => {
+      const fetchMock = vi.fn()
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useJob({
+          api: '/api/durably',
+          jobName: 'test-job',
+          initialRunId: 'existing-run-id',
+        }),
+      )
+
+      expect(result.current.currentRunId).toBe('existing-run-id')
+    })
+
+    it('subscribes to initialRunId via EventSource immediately', async () => {
+      const fetchMock = vi.fn()
+      globalThis.fetch = fetchMock
+
+      renderHook(() =>
+        useJob({
+          api: '/api/durably',
+          jobName: 'test-job',
+          initialRunId: 'existing-run-id',
+        }),
+      )
+
+      // EventSource should be created for the initial run
+      await waitFor(() => {
+        expect(mockEventSource.instances.length).toBeGreaterThan(0)
+      })
+
+      expect(mockEventSource.instances[0].url).toContain('existing-run-id')
+    })
+
+    it('receives events for initialRunId', async () => {
+      const fetchMock = vi.fn()
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useJob<{ input: string }, { result: string }>({
+          api: '/api/durably',
+          jobName: 'test-job',
+          initialRunId: 'existing-run-id',
+        }),
+      )
+
+      await waitFor(() => {
+        expect(mockEventSource.instances.length).toBeGreaterThan(0)
+      })
+
+      // Simulate receiving events for the existing run
+      act(() => {
+        mockEventSource.emit({
+          type: 'run:progress',
+          runId: 'existing-run-id',
+          progress: { current: 5, total: 10, message: 'In progress' },
+        })
+      })
+
+      await waitFor(() => {
+        expect(result.current.progress).toEqual({
+          current: 5,
+          total: 10,
+          message: 'In progress',
+        })
+      })
+
+      act(() => {
+        mockEventSource.emit({
+          type: 'run:complete',
+          runId: 'existing-run-id',
+          output: { result: 'reconnected' },
+        })
+      })
+
+      await waitFor(() => {
+        expect(result.current.status).toBe('completed')
+        expect(result.current.output).toEqual({ result: 'reconnected' })
+        expect(result.current.isCompleted).toBe(true)
+      })
+    })
+
+    it('can trigger new run after initialRunId', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: true,
+        json: () => Promise.resolve({ runId: 'new-run-id' }),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useJob({
+          api: '/api/durably',
+          jobName: 'test-job',
+          initialRunId: 'existing-run-id',
+        }),
+      )
+
+      expect(result.current.currentRunId).toBe('existing-run-id')
+
+      // Trigger a new run
+      await result.current.trigger({ input: 'new' })
+
+      await waitFor(() => {
+        expect(result.current.currentRunId).toBe('new-run-id')
+      })
+
+      expect(fetchMock).toHaveBeenCalledWith(
+        '/api/durably/trigger',
+        expect.objectContaining({
+          method: 'POST',
+        }),
+      )
+    })
+  })
 })

From e28929642e0ec1feb318c39e11657693503a0d4a Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 17:11:01 +0900
Subject: [PATCH 058/101] docs(spec-react): sync with implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add 'cancelled' to RunStatus type
- Add autoResume/followLatest options to browser mode useJob
- Document useRuns hook for both modes
- Document useRunActions hook for client mode
- Document createDurablyClient/createJobHooks factories
- Update DurablyHandler with all methods including handle()
- Update API routing to match implementation
- Update server usage example to use handler.handle()
- Remove cancelled API from future extensions (already implemented)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 docs/spec-react.md | 155 +++++++++++++++++++++++++++++++++++++--------
 1 file changed, 128 insertions(+), 27 deletions(-)

diff --git a/docs/spec-react.md b/docs/spec-react.md
index 5a4e7b26..262a6b82 100644
--- a/docs/spec-react.md
+++ b/docs/spec-react.md
@@ -113,14 +113,13 @@ import { durably } from '~/lib/durably.server'
 
 const handler = createDurablyHandler(durably)
 
-// POST /api/durably - ジョブ起動
-export async function action({ request }: ActionFunctionArgs) {
-  return handler.trigger(request)
+// 全ルートを自動処理（推奨）
+export async function loader({ request }: LoaderFunctionArgs) {
+  return handler.handle(request, '/api/durably')
 }
 
-// GET /api/durably?runId=xxx - SSE 購読
-export async function loader({ request }: LoaderFunctionArgs) {
-  return handler.subscribe(request)
+export async function action({ request }: ActionFunctionArgs) {
+  return handler.handle(request, '/api/durably')
 }
 ```
 
@@ -250,6 +249,8 @@ const {
 |------|-----|------|
 | `jobDefinition` | `JobDefinition` | ジョブ定義 |
 | `options.initialRunId` | `string` | 初期購読 Run ID |
+| `options.autoResume` | `boolean` | pending/running の Run を自動再開（デフォルト: true） |
+| `options.followLatest` | `boolean` | 新しい Run 開始時に自動切替（デフォルト: true） |
 
 **戻り値の詳細**:
 
@@ -277,6 +278,29 @@ Run ID のみで購読（trigger なし）。`runId` が `null` の場合は購
 const { logs, clear } = useJobLogs({ runId, maxLogs? })
 ```
 
+#### useRuns
+
+```tsx
+const {
+  runs,
+  isLoading,
+  error,
+  page,
+  hasMore,
+  nextPage,
+  prevPage,
+  goToPage,
+  refresh,
+} = useRuns(options?)
+```
+
+| オプション | 型 | 説明 |
+|------------|------|------|
+| `jobName` | `string` | ジョブ名でフィルタ |
+| `status` | `RunStatus` | ステータスでフィルタ |
+| `limit` | `number` | 1ページの件数（デフォルト: 20） |
+| `realtime` | `boolean` | リアルタイム更新（デフォルト: true） |
+
 ---
 
 ### サーバー連携モード
@@ -288,17 +312,30 @@ import { createDurablyHandler } from '@coji/durably/server'
 
 const handler = createDurablyHandler(durably)
 
-// Request handlers
-handler.trigger(request: Request): Promise  // POST
-handler.subscribe(request: Request): Response         // GET (SSE)
+// 自動ルーティング（推奨）
+handler.handle(request: Request, basePath: string): Promise
+
+// 個別ハンドラー
+handler.trigger(request: Request): Promise      // POST /trigger
+handler.subscribe(request: Request): Response             // GET /subscribe?runId=xxx
+handler.runs(request: Request): Promise         // GET /runs
+handler.run(request: Request): Promise          // GET /run?runId=xxx
+handler.retry(request: Request): Promise        // POST /retry?runId=xxx
+handler.cancel(request: Request): Promise       // POST /cancel?runId=xxx
+handler.subscribeRuns(request: Request): Response         // GET /runs/subscribe
 ```
 
 **API 規約**:
 
 | エンドポイント | メソッド | リクエスト | レスポンス |
 |---------------|---------|-----------|-----------|
-| `/api/durably` | POST | `{ jobName, input }` | `{ runId }` |
-| `/api/durably?runId=xxx` | GET | - | SSE stream |
+| `{basePath}/trigger` | POST | `{ jobName, input, idempotencyKey?, concurrencyKey? }` | `{ runId }` |
+| `{basePath}/subscribe?runId=xxx` | GET | - | SSE stream (single run) |
+| `{basePath}/runs` | GET | `?jobName=&status=&limit=&offset=` | `Run[]` |
+| `{basePath}/run?runId=xxx` | GET | - | `Run` or 404 |
+| `{basePath}/retry?runId=xxx` | POST | - | `{ success: true }` |
+| `{basePath}/cancel?runId=xxx` | POST | - | `{ success: true }` |
+| `{basePath}/runs/subscribe` | GET | `?jobName=` | SSE stream (run updates) |
 
 > **Note**: 認証・認可、CORS、CSRF の扱いは本仕様のスコープ外。アプリケーション側で適切に実装すること。
 
@@ -377,13 +414,92 @@ const { logs, clear } = useJobLogs({
 | `runId`    | `string` | Yes  | Run ID                                |
 | `maxLogs`  | `number` | -    | 保持する最大ログ数（デフォルト: 100） |
 
+**useRuns オプション**:
+
+```tsx
+import { useRuns } from '@coji/durably-react/client'
+
+const {
+  runs,
+  isLoading,
+  error,
+  page,
+  hasMore,
+  nextPage,
+  prevPage,
+  goToPage,
+  refresh,
+} = useRuns({
+  api: '/api/durably',
+  jobName?: 'my-job',
+  status?: 'completed',
+  limit?: 20,
+  realtime?: true,
+})
+```
+
+| オプション | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `api` | `string` | Yes | API エンドポイント |
+| `jobName` | `string` | - | ジョブ名でフィルタ |
+| `status` | `RunStatus` | - | ステータスでフィルタ |
+| `limit` | `number` | - | 1ページの件数（デフォルト: 20） |
+| `realtime` | `boolean` | - | リアルタイム更新（デフォルト: true） |
+
+**useRunActions オプション**:
+
+```tsx
+import { useRunActions } from '@coji/durably-react/client'
+
+const { retry, cancel, isLoading, error } = useRunActions({
+  api: '/api/durably',
+})
+
+// 使用例
+await retry(runId)   // 失敗した Run を再実行
+await cancel(runId)  // 実行中の Run をキャンセル
+```
+
+| 戻り値 | 型 | 説明 |
+|--------|------|------|
+| `retry` | `(runId: string) => Promise` | Run を再実行 |
+| `cancel` | `(runId: string) => Promise` | Run をキャンセル |
+| `isLoading` | `boolean` | アクション実行中 |
+| `error` | `string \| null` | エラーメッセージ |
+
+---
+
+### 型安全クライアントファクトリ（推奨）
+
+```tsx
+import { createDurablyClient, createJobHooks } from '@coji/durably-react/client'
+import type { processTask, syncUsers } from './jobs'
+
+// 方法1: createDurablyClient
+const client = createDurablyClient<{
+  'process-task': typeof processTask
+  'sync-users': typeof syncUsers
+}>({ api: '/api/durably' })
+
+const { trigger, status } = client.useJob('process-task')
+await trigger({ taskId: '123' })  // 型安全
+
+// 方法2: createJobHooks
+const { useProcessTask, useSyncUsers } = createJobHooks<{
+  'process-task': typeof processTask
+  'sync-users': typeof syncUsers
+}>({ api: '/api/durably' })
+
+const { trigger, status } = useProcessTask()
+```
+
 ---
 
 ## 型定義
 
 ```ts
 // 共通
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed'
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
 
 interface DurablyOptions {
   pollingInterval?: number   // デフォルト: 1000ms
@@ -626,21 +742,6 @@ function TaskPage() {
 
 ## 将来拡張
 
-### キャンセル API
-
-Run のキャンセル機能を追加予定。
-
-```tsx
-// useJob に cancel を追加
-const { trigger, cancel, status } = useJob(job)
-await cancel()  // 現在の Run をキャンセル
-
-// サーバー API
-DELETE /api/durably?runId=xxx  → { success: true }
-```
-
-> **Note**: キャンセルは cooperative。ステップ実行中は即座に止められず、次のステップに進む前にチェックされる。
-
 ### Streaming 対応
 
 `step.stream()` でトークン単位のストリーミングを追加予定。

From e9489abd0041a366ed8911e83e202e70b2d49b94 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 17:17:49 +0900
Subject: [PATCH 059/101] refactor(durably): rename subscribeRuns to
 runsSubscribe for API naming consistency
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Method names now follow the pattern of matching their path structure:
- handler.runs → /runs
- handler.subscribe → /subscribe
- handler.runsSubscribe → /runs/subscribe (was subscribeRuns)

Also documented onRequest option in createDurablyHandler.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 docs/spec-react-update-plan.md |  2 +-
 docs/spec-react.md             | 14 ++++++++++----
 packages/durably/src/server.ts |  6 +++---
 3 files changed, 14 insertions(+), 8 deletions(-)

diff --git a/docs/spec-react-update-plan.md b/docs/spec-react-update-plan.md
index 44cd9608..480e18ea 100644
--- a/docs/spec-react-update-plan.md
+++ b/docs/spec-react-update-plan.md
@@ -185,7 +185,7 @@ handler.runs(request: Request): Promise         // GET /runs
 handler.run(request: Request): Promise          // GET /run?runId=xxx
 handler.retry(request: Request): Promise        // POST /retry?runId=xxx
 handler.cancel(request: Request): Promise       // POST /cancel?runId=xxx
-handler.subscribeRuns(request: Request): Response         // GET /runs/subscribe
+handler.runsSubscribe(request: Request): Response         // GET /runs/subscribe
 ```
 
 ---
diff --git a/docs/spec-react.md b/docs/spec-react.md
index 262a6b82..233e4462 100644
--- a/docs/spec-react.md
+++ b/docs/spec-react.md
@@ -126,7 +126,7 @@ export async function action({ request }: ActionFunctionArgs) {
 または手動で実装:
 
 ```ts
-// POST /api/durably
+// POST /api/durably/trigger
 export async function action({ request }: ActionFunctionArgs) {
   const { jobName, input } = await request.json()
   const job = durably.getJob(jobName)
@@ -134,7 +134,7 @@ export async function action({ request }: ActionFunctionArgs) {
   return Response.json({ runId: run.id })
 }
 
-// GET /api/durably?runId=xxx
+// GET /api/durably/subscribe?runId=xxx
 export async function loader({ request }: LoaderFunctionArgs) {
   const url = new URL(request.url)
   const runId = url.searchParams.get('runId')
@@ -310,7 +310,13 @@ const {
 ```ts
 import { createDurablyHandler } from '@coji/durably/server'
 
-const handler = createDurablyHandler(durably)
+const handler = createDurablyHandler(durably, {
+  // リクエスト処理前に呼ばれる（オプション）
+  onRequest: async () => {
+    await durably.migrate()
+    durably.start()
+  }
+})
 
 // 自動ルーティング（推奨）
 handler.handle(request: Request, basePath: string): Promise
@@ -322,7 +328,7 @@ handler.runs(request: Request): Promise         // GET /runs
 handler.run(request: Request): Promise          // GET /run?runId=xxx
 handler.retry(request: Request): Promise        // POST /retry?runId=xxx
 handler.cancel(request: Request): Promise       // POST /cancel?runId=xxx
-handler.subscribeRuns(request: Request): Response         // GET /runs/subscribe
+handler.runsSubscribe(request: Request): Response         // GET /runs/subscribe
 ```
 
 **API 規約**:
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index 26dfd22f..07cbebca 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -107,7 +107,7 @@ export interface DurablyHandler {
    * Expects GET with optional query param: jobName
    * Returns SSE stream of run update notifications
    */
-  subscribeRuns(request: Request): Response
+  runsSubscribe(request: Request): Response
 }
 
 /**
@@ -155,7 +155,7 @@ export function createDurablyHandler(
         if (path === '/subscribe') return handler.subscribe(request)
         if (path === '/runs') return handler.runs(request)
         if (path === '/run') return handler.run(request)
-        if (path === '/runs/subscribe') return handler.subscribeRuns(request)
+        if (path === '/runs/subscribe') return handler.runsSubscribe(request)
       }
 
       // POST routes
@@ -370,7 +370,7 @@ export function createDurablyHandler(
       }
     },
 
-    subscribeRuns(request: Request): Response {
+    runsSubscribe(request: Request): Response {
       const url = new URL(request.url)
       const jobNameFilter = url.searchParams.get('jobName')
 

From cf8e0123eb8821fa390d9534c0b1ebb45e8f0219 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 17:22:36 +0900
Subject: [PATCH 060/101] docs(spec): sync Storage interface with
 implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Updated Storage interface to match actual implementation:
- createRun/createStep/createLog now return created entity
- Added batchCreateRuns and deleteRun methods
- Log operations are now required (not optional)
- Use Input types (CreateRunInput, etc.) instead of entity types

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 docs/spec.md | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/docs/spec.md b/docs/spec.md
index 96c1a1d6..66f25229 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -1041,20 +1041,22 @@ class JobContextImpl implements JobContext {
 ```ts
 interface Storage {
   // Run 操作
-  createRun(run: Run): Promise
-  updateRun(runId: string, data: Partial): Promise
+  createRun(input: CreateRunInput): Promise
+  batchCreateRuns(inputs: CreateRunInput[]): Promise
+  updateRun(runId: string, data: UpdateRunInput): Promise
+  deleteRun(runId: string): Promise
   getRun(runId: string): Promise
   getRuns(filter?: RunFilter): Promise
   getNextPendingRun(excludeConcurrencyKeys: string[]): Promise
 
   // Step 操作
-  createStep(step: Step): Promise
+  createStep(input: CreateStepInput): Promise
   getSteps(runId: string): Promise
   getCompletedStep(runId: string, name: string): Promise
 
-  // Log 操作（withLogPersistence プラグイン用）
-  createLog?(log: Log): Promise
-  getLogs?(runId: string): Promise
+  // Log 操作
+  createLog(input: CreateLogInput): Promise
+  getLogs(runId: string): Promise
 
   // v2 で追加予定:
   // createEvent?(event: DurablyEvent): Promise

From 664bcc1e8e77e1f4c6a71cb30fba194b4a50b516 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 17:23:03 +0900
Subject: [PATCH 061/101] chore(docs): remove outdated spec-react update plan

---
 docs/spec-react-update-plan.md | 279 ---------------------------------
 1 file changed, 279 deletions(-)
 delete mode 100644 docs/spec-react-update-plan.md

diff --git a/docs/spec-react-update-plan.md b/docs/spec-react-update-plan.md
deleted file mode 100644
index 480e18ea..00000000
--- a/docs/spec-react-update-plan.md
+++ /dev/null
@@ -1,279 +0,0 @@
-# spec-react.md 修正プラン
-
-## 概要
-
-`docs/spec-react.md` と実装の差異を解消するための修正プランです。
-
----
-
-## 1. RunStatus 型に cancelled を追加
-
-**現状 (L386):**
-```ts
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed'
-```
-
-**修正後:**
-```ts
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
-```
-
----
-
-## 2. useJob (browser mode) に autoResume / followLatest オプションを追加
-
-**現状 (L249-253):**
-```
-| 引数 | 型 | 説明 |
-|------|-----|------|
-| `jobDefinition` | `JobDefinition` | ジョブ定義 |
-| `options.initialRunId` | `string` | 初期購読 Run ID |
-```
-
-**修正後:**
-```
-| 引数 | 型 | 説明 |
-|------|-----|------|
-| `jobDefinition` | `JobDefinition` | ジョブ定義 |
-| `options.initialRunId` | `string` | 初期購読 Run ID |
-| `options.autoResume` | `boolean` | pending/running の Run を自動再開（デフォルト: true） |
-| `options.followLatest` | `boolean` | 新しい Run 開始時に自動切替（デフォルト: true） |
-```
-
----
-
-## 3. client mode useJob の initialRunId ✅ 実装済み
-
-**現状 (L357-364):**
-```
-| オプション     | 型       | 必須 | 説明                        |
-|----------------|----------|------|-----------------------------|
-| `api`          | `string` | Yes  | API エンドポイント          |
-| `jobName`      | `string` | Yes  | ジョブ名                    |
-| `initialRunId` | `string` | -    | 初期購読 Run ID（再接続用） |
-```
-
-→ **仕様通り実装済み。変更不要。**
-
----
-
-## 4. useRuns hook を追加
-
-「API 仕様」セクションに以下を追加:
-
-### ブラウザ完結モード
-
-```tsx
-const {
-  runs,
-  isLoading,
-  error,
-  page,
-  hasMore,
-  nextPage,
-  prevPage,
-  goToPage,
-  refresh,
-} = useRuns(options?)
-```
-
-| オプション | 型 | 説明 |
-|------------|-----|------|
-| `jobName` | `string` | ジョブ名でフィルタ |
-| `status` | `RunStatus` | ステータスでフィルタ |
-| `limit` | `number` | 1ページの件数（デフォルト: 20） |
-| `realtime` | `boolean` | リアルタイム更新（デフォルト: true） |
-
-### サーバー連携モード
-
-```tsx
-import { useRuns } from '@coji/durably-react/client'
-
-const {
-  runs,
-  isLoading,
-  error,
-  page,
-  hasMore,
-  nextPage,
-  prevPage,
-  goToPage,
-  refresh,
-} = useRuns({
-  api: '/api/durably',
-  jobName?: 'my-job',
-  status?: 'completed',
-  limit?: 20,
-  realtime?: true,
-})
-```
-
----
-
-## 5. useRunActions hook を追加（client mode のみ）
-
-「サーバー連携モード」セクションに以下を追加:
-
-```tsx
-import { useRunActions } from '@coji/durably-react/client'
-
-const { retry, cancel, isLoading, error } = useRunActions({
-  api: '/api/durably',
-})
-
-// 使用例
-await retry(runId)   // 失敗した Run を再実行
-await cancel(runId)  // 実行中の Run をキャンセル
-```
-
-| 戻り値 | 型 | 説明 |
-|--------|-----|------|
-| `retry` | `(runId: string) => Promise` | Run を再実行 |
-| `cancel` | `(runId: string) => Promise` | Run をキャンセル |
-| `isLoading` | `boolean` | アクション実行中 |
-| `error` | `string \| null` | エラーメッセージ |
-
----
-
-## 6. createDurablyClient / createJobHooks を追加
-
-「サーバー連携モード」セクションに以下を追加:
-
-### 型安全クライアントファクトリ（推奨）
-
-```tsx
-import { createDurablyClient, createJobHooks } from '@coji/durably-react/client'
-import type { processTask, syncUsers } from './jobs'
-
-// 方法1: createDurablyClient
-const client = createDurablyClient<{
-  'process-task': typeof processTask
-  'sync-users': typeof syncUsers
-}>({ api: '/api/durably' })
-
-const { trigger, status } = client.useJob('process-task')
-await trigger({ taskId: '123' })  // 型安全
-
-// 方法2: createJobHooks
-const { useProcessTask, useSyncUsers } = createJobHooks<{
-  'process-task': typeof processTask
-  'sync-users': typeof syncUsers
-}>({ api: '/api/durably' })
-
-const { trigger, status } = useProcessTask()
-```
-
----
-
-## 7. DurablyHandler の追加メソッドを文書化
-
-**現状 (L292-293):**
-```ts
-handler.trigger(request: Request): Promise  // POST
-handler.subscribe(request: Request): Response         // GET (SSE)
-```
-
-**修正後:**
-```ts
-// 自動ルーティング（推奨）
-handler.handle(request: Request, basePath: string): Promise
-
-// 個別ハンドラー
-handler.trigger(request: Request): Promise      // POST /trigger
-handler.subscribe(request: Request): Response             // GET /subscribe?runId=xxx
-handler.runs(request: Request): Promise         // GET /runs
-handler.run(request: Request): Promise          // GET /run?runId=xxx
-handler.retry(request: Request): Promise        // POST /retry?runId=xxx
-handler.cancel(request: Request): Promise       // POST /cancel?runId=xxx
-handler.runsSubscribe(request: Request): Response         // GET /runs/subscribe
-```
-
----
-
-## 8. API ルーティングを実装に合わせて更新
-
-**現状 (L298-301):**
-```
-| エンドポイント | メソッド | リクエスト | レスポンス |
-|---------------|---------|-----------|-----------|
-| `/api/durably` | POST | `{ jobName, input }` | `{ runId }` |
-| `/api/durably?runId=xxx` | GET | - | SSE stream |
-```
-
-**修正後:**
-```
-| エンドポイント | メソッド | リクエスト | レスポンス |
-|---------------|---------|-----------|-----------|
-| `{basePath}/trigger` | POST | `{ jobName, input, idempotencyKey?, concurrencyKey? }` | `{ runId }` |
-| `{basePath}/subscribe?runId=xxx` | GET | - | SSE stream (single run) |
-| `{basePath}/runs` | GET | `?jobName=&status=&limit=&offset=` | `Run[]` |
-| `{basePath}/run?runId=xxx` | GET | - | `Run` or 404 |
-| `{basePath}/retry?runId=xxx` | POST | - | `{ success: true }` |
-| `{basePath}/cancel?runId=xxx` | POST | - | `{ success: true }` |
-| `{basePath}/runs/subscribe` | GET | `?jobName=` | SSE stream (run updates) |
-```
-
----
-
-## 9. 将来拡張セクションの更新
-
-キャンセル API は実装済みのため、将来拡張から削除し、実装済みとして記載する。
-
-**現状 (L629-642):**
-```
-### キャンセル API
-
-Run のキャンセル機能を追加予定。
-...
-```
-
-**修正後:**
-「将来拡張」セクションからキャンセル API を削除し、上記の useRunActions として文書化済みであることを確認。
-
----
-
-## 10. サーバー側使用例の更新
-
-**現状 (L109-125):**
-```ts
-const handler = createDurablyHandler(durably)
-
-// POST /api/durably - ジョブ起動
-export async function action({ request }: ActionFunctionArgs) {
-  return handler.trigger(request)
-}
-
-// GET /api/durably?runId=xxx - SSE 購読
-export async function loader({ request }: LoaderFunctionArgs) {
-  return handler.subscribe(request)
-}
-```
-
-**修正後:**
-```ts
-const handler = createDurablyHandler(durably)
-
-// 全ルートを自動処理（推奨）
-export async function loader({ request }: LoaderFunctionArgs) {
-  return handler.handle(request, '/api/durably')
-}
-
-export async function action({ request }: ActionFunctionArgs) {
-  return handler.handle(request, '/api/durably')
-}
-```
-
----
-
-## 修正優先度
-
-| 優先度 | 項目 | 理由 |
-|--------|------|------|
-| 高 | API ルーティング更新 | 実装と大きく乖離 |
-| 高 | DurablyHandler メソッド追加 | 実装と大きく乖離 |
-| 高 | useRuns hook 追加 | 実装済みだが未文書化 |
-| 高 | useRunActions hook 追加 | 実装済みだが未文書化 |
-| 中 | RunStatus に cancelled 追加 | 型の不一致 |
-| 中 | useJob オプション更新 | 機能の不一致 |
-| 中 | createDurablyClient 追加 | 推奨 API だが未文書化 |
-| 低 | 将来拡張セクション更新 | 実装済み機能の整理 |

From 5181699fab5101f35c1c768c9cee8b010ded0717 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 17:25:32 +0900
Subject: [PATCH 062/101] docs(spec-streaming): revise for v2 planning, reflect
 v1 subscribe() implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Updated to reflect that subscribe() is already implemented in v1
- Reorganized into "v1 implemented" and "v2 planned" sections
- Clarified current limitations and future extension phases
- Simplified structure and removed redundant content
- Fixed table formatting

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 docs/spec-streaming.md | 393 +++++++++++++++--------------------------
 1 file changed, 139 insertions(+), 254 deletions(-)

diff --git a/docs/spec-streaming.md b/docs/spec-streaming.md
index 4ef1be31..68756185 100644
--- a/docs/spec-streaming.md
+++ b/docs/spec-streaming.md
@@ -1,8 +1,8 @@
-# 将来仕様検討: AI Agent ワークフロー対応
+# 将来仕様: AI Agent ワークフロー拡張 (v2)
 
-> **⚠️ 注意: これは構想段階のドキュメントです。まだ実装されていません。**
+> **⚠️ 注意: これは将来拡張の構想ドキュメントです。**
 >
-> v1 の基本機能が安定した後、Phase A から段階的に検討・実装予定です。
+> v1 で `subscribe()` は実装済み。本ドキュメントでは v2 以降の拡張機能を検討します。
 
 ## 背景
 
@@ -16,22 +16,45 @@ LLM を使った AI Agent のワークフローを durably で実装したい。
 
 ---
 
-## 課題
+## v1 で実装済みの機能
 
-### 現仕様の制約
+### `subscribe()` - リアルタイム購読
 
-1. **ストリーミング非対応**: 現在の設計はリクエスト/レスポンス型。ステップ完了時にのみ状態が永続化される。
+v1 で実装済み。Run の実行中に発火されるイベントを `ReadableStream` として取得できる。
 
-2. **リアルタイム通知の欠如**: イベントシステムは同一プロセス内のみ。ブラウザタブ間やサーバー→クライアントへのプッシュ機構がない。
+```ts
+const stream = durably.subscribe(runId)
+
+const reader = stream.getReader()
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+
+  switch (value.type) {
+    case 'run:start':
+      console.log('Run started')
+      break
+    case 'step:complete':
+      console.log(`Step ${value.stepName} completed`)
+      break
+    case 'run:complete':
+      console.log('Run completed:', value.output)
+      break
+    case 'run:fail':
+      console.error('Run failed:', value.error)
+      break
+  }
+}
+```
 
-3. **LLM 特有の要件**:
-   - トークン単位のストリーミング出力
-   - 中間結果の表示（思考過程、ツール呼び出し）
-   - 長時間実行中の heartbeat
+**現在の制約**:
+- イベントはメモリ上のみ（永続化されない）
+- 再接続時に過去のイベントは取得できない
+- `step.stream()` によるトークン単位のストリーミングは未対応
 
 ---
 
-## 拡張案
+## v2 拡張案
 
 ### 1. ストリーミングステップ (`step.stream()`)
 
@@ -82,103 +105,9 @@ export const aiAgent = defineJob({
 - ステップ完了時に戻り値が永続化される
 - 再実行時は完了済みステップをスキップ（通常と同じ）
 
-### 2. リアルタイム購読 (`subscribe()`)
-
-実行中の Run にリアルタイムで接続する API。Web Streams API の `ReadableStream` を使用する。
-
-```ts
-// subscribe() は ReadableStream を返す
-const stream = await durably.subscribe(runId)
-
-// ReadableStream として消費
-for await (const event of stream) {
-  switch (event.type) {
-    case 'stream':
-      appendToUI(event.data.text)
-      break
-    case 'step:complete':
-      updateProgress(event.stepName)
-      break
-    case 'run:complete':
-      showResult(event.output)
-      break
-  }
-}
-```
-
-**メリット**:
-- ブラウザネイティブ API（追加ライブラリ不要）
-- バックプレッシャー対応（消費側が遅いと生成を待つ）
-- `for await...of` で直感的に消費
-- `pipeThrough()` でトランスフォーム可能
-- Node.js でも同じ API（`ReadableStream` は標準化済み）
-
-**実装イメージ**:
-
-```ts
-// subscribe の実装
-async function subscribe(runId: string, options?: SubscribeOptions): Promise> {
-  // 初期イベントを先に取得（再接続時は resumeFrom 以降）
-  const initialEvents = await getEvents(runId, options?.resumeFrom)
-
-  return new ReadableStream({
-    start(controller) {
-      // 取得済みの初期イベントをプッシュ
-      for (const event of initialEvents) {
-        controller.enqueue(event)
-      }
-    },
-
-    async pull(controller) {
-      // 新しいイベントをポーリングまたはリッスン
-      const event = await waitForNextEvent(runId)
-      if (event.type === 'run:complete' || event.type === 'run:fail') {
-        controller.enqueue(event)
-        controller.close()
-      } else {
-        controller.enqueue(event)
-      }
-    },
-
-    cancel() {
-      // クリーンアップ
-    }
-  })
-}
-```
-
-**再接続の実装**:
-
-```ts
-// クライアント側で最後のイベントを記録
-let lastSequence = 0
-
-async function consumeWithReconnect(runId: string) {
-  while (true) {
-    try {
-      const stream = await durably.subscribe(runId, {
-        resumeFrom: lastSequence
-      })
-
-      for await (const event of stream) {
-        lastSequence = event.sequence
-        handleEvent(event)
-
-        if (event.type === 'run:complete' || event.type === 'run:fail') {
-          return // 正常終了
-        }
-      }
-    } catch (error) {
-      // 接続エラー時はリトライ
-      await sleep(1000)
-    }
-  }
-}
-```
-
-### 3. イベントログの永続化
+### 2. イベントログの永続化
 
-ストリーミングイベントを再接続時に再生するため、イベントログを永続化。
+粗いイベント（step:*, run:*）を永続化し、再接続時に再生可能にする。
 
 ```sql
 -- events テーブル（新規追加）
@@ -186,10 +115,10 @@ CREATE TABLE events (
   id TEXT PRIMARY KEY,        -- ULID
   run_id TEXT NOT NULL,
   step_name TEXT,
-  type TEXT NOT NULL,         -- 'stream', 'step:start', 'step:complete', etc.
+  type TEXT NOT NULL,         -- 'step:start', 'step:complete', 'run:complete', etc.
   data TEXT,                  -- JSON
   sequence INTEGER NOT NULL,  -- 順序保証用
-  created_at TEXT NOT NULL,   -- イベント型では timestamp として公開
+  created_at TEXT NOT NULL,
 
   FOREIGN KEY (run_id) REFERENCES runs(id)
 );
@@ -197,11 +126,29 @@ CREATE TABLE events (
 CREATE INDEX idx_events_run_sequence ON events(run_id, sequence);
 ```
 
-**注**: DBカラム名 `created_at` は、イベント型では `timestamp` フィールドとして公開される（v1 と同じパターン）。
+**永続化するイベント**:
+- `run:start`, `run:complete`, `run:fail`
+- `step:start`, `step:complete`, `step:fail`
+- `run:progress`
+- `log:write`
+
+**永続化しないイベント**:
+- `stream`（トークン単位の emit）- メモリのみで直接配信
+
+### 3. 再接続サポート (`resumeFrom`)
+
+```ts
+interface SubscribeOptions {
+  resumeFrom?: number  // 最後に受信した sequence
+}
+
+// 再接続時に使用
+const stream = durably.subscribe(runId, { resumeFrom: lastSequence })
+```
 
 **再接続フロー**:
 1. クライアントが `resumeFrom: lastSequence` で接続
-2. サーバーは `sequence > lastSequence` のイベントを送信
+2. サーバーは `sequence > lastSequence` のイベントを DB から取得して送信
 3. 以降はリアルタイムでイベントを配信
 
 ### 4. チェックポイント（長時間実行対応）
@@ -230,179 +177,124 @@ const response = await step.stream('generate-response', async (emit, checkpoint)
 - チェックポイントがあれば、そこから再開
 - LLM に「続きを生成」のプロンプトを送る（アプリケーション側の責務）
 
-### 5. ブラウザ環境での実装
-
-ブラウザでは Web Worker + BroadcastChannel でタブ間通信。
-
-```ts
-// メインタブ（実行側）
-const durably = createDurably({ dialect })
-durably.on('stream', (event) => {
-  // BroadcastChannel で他のタブに通知
-  channel.postMessage(event)
-})
-
-// 別タブ（表示側）
-const channel = new BroadcastChannel('durably-events')
-channel.onmessage = (event) => {
-  updateUI(event.data)
-}
-```
-
-**制約**:
-- 同一オリジン内のみ
-- タブが全て閉じると通知も停止
-- 永続化されたイベントログから復元は可能
-
 ---
 
 ## API 設計案
 
-### JobHandle の拡張
+### StepContext の拡張
 
 ```ts
-interface JobHandle {
-  // 型情報（v1と同じ）
-  readonly name: TName
-  readonly $types: {
-    input: TInput
-    output: TOutput
+interface StepContext {
+  // v1 (実装済み)
+  readonly runId: string
+  run(name: string, fn: () => Promise): Promise
+  progress(current: number, total?: number, message?: string): void
+  log: {
+    info(message: string, data?: unknown): void
+    warn(message: string, data?: unknown): void
+    error(message: string, data?: unknown): void
   }
 
-  // 既存
-  trigger(input: TInput, options?: TriggerOptions): Promise>
-  getRun(id: string): Promise | null>
-  getRuns(filter?: RunFilter): Promise[]>
-
-  // 新規: ReadableStream を返す（初期イベント取得のため非同期）
-  subscribe(runId: string, options?: SubscribeOptions): Promise>
+  // v2 (新規)
+  stream(
+    name: string,
+    fn: (emit: EmitFn, checkpoint?: CheckpointFn) => Promise
+  ): Promise
 }
 
-interface SubscribeOptions {
-  resumeFrom?: number  // 最後に受信した sequence
-}
+type EmitFn = (data: unknown) => void
+type CheckpointFn = (state: unknown) => Promise
+```
 
-// subscribe() は ReadableStream を返す
-type DurablyEventStream = ReadableStream
+### DurablyEvent の拡張
 
+```ts
+// v1 イベント (実装済み)
 type DurablyEvent =
-  // v1 イベント
   | RunStartEvent
   | RunCompleteEvent
   | RunFailEvent
+  | RunProgressEvent
   | StepStartEvent
   | StepCompleteEvent
   | StepFailEvent
   | LogWriteEvent
-  // v2 追加イベント
-  | StreamEvent
+  | WorkerErrorEvent
 
-interface StreamEvent {
+// v2 追加イベント
+interface StreamEvent extends BaseEvent {
   type: 'stream'
   runId: string
   stepName: string
-  sequence: number
   data: unknown  // emit() に渡されたデータ
-  timestamp: string
 }
 ```
 
-### StepContext の拡張
+### subscribe() の拡張
 
 ```ts
-interface StepContext {
-  // 既存
-  run(name: string, fn: () => Promise): Promise
-  log: Logger
-  progress(current: number, total: number, message?: string): void
+// v1 (実装済み)
+subscribe(runId: string): ReadableStream
 
-  // 新規
-  stream(
-    name: string,
-    fn: (emit: EmitFn, checkpoint: CheckpointFn) => Promise
-  ): Promise
-}
+// v2 (拡張)
+subscribe(runId: string, options?: SubscribeOptions): ReadableStream
 
-type EmitFn = (data: unknown) => void
-type CheckpointFn = (state: unknown) => Promise
+interface SubscribeOptions {
+  resumeFrom?: number  // 最後に受信した sequence
+}
 ```
 
 ---
 
 ## 実装フェーズ案
 
-### Phase A: イベントログ基盤（v0.2）
+### Phase A: step.stream() 基本実装
 
-- `events` テーブルの追加
-- `step.stream()` の基本実装（emit のみ、checkpoint なし）
-- `subscribe()` の実装（ReadableStream を返す、ポーリングベース）
+- `step.stream()` の実装（emit のみ、checkpoint なし）
+- `StreamEvent` の追加
+- `subscribe()` で `stream` イベントを配信
 
-### Phase B: 再接続とタブ間通知（v0.3）
+### Phase B: イベント永続化と再接続
 
-- `resumeFrom` による再接続（イベントログから再生）
-- BroadcastChannel によるタブ間通知（ブラウザ、ポーリング不要に）
-- ヘルパー関数 `subscribeWithReconnect()` の提供
+- `events` テーブルの追加
+- 粗いイベント（step:*, run:*）の永続化
+- `resumeFrom` による再接続サポート
+- Storage インターフェースの拡張:
+  ```ts
+  createEvent(event: DurablyEvent): Promise
+  getEvents(runId: string, afterSequence?: number): Promise
+  ```
 
-### Phase C: チェックポイント（v0.4）
+### Phase C: チェックポイント
 
 - `checkpoint()` の実装
-- 部分的な再開のサポート
+- チェックポイントからの再開サポート
 - TTL によるイベントログのクリーンアップ
 
 ---
 
-## 検討事項
+## 設計上の考慮事項
 
 ### DB負荷とストリーミング戦略
 
 LLM のトークン単位ストリーミングは 1秒に数十〜数百回の emit が発生しうる。
 毎回 DB に書き込むのは現実的ではない。
 
-#### 採用する方針: イベントログは粗いイベントのみ永続化
+**採用方針**: イベントログは粗いイベントのみ永続化
 
-```ts
-// DB に永続化するイベント（再接続時に再生可能）
-step:start
-step:complete
-step:fail
-run:complete
-run:fail
-progress 更新（setProgress）
-
-// DB に書かないイベント（メモリのみ、直接配信）
-stream（トークン単位の emit）
-```
+| イベント       | 永続化 | 備考                 |
+|----------------|--------|----------------------|
+| `run:*`        | ✅     | 再接続時に再生       |
+| `step:*`       | ✅     | 再接続時に再生       |
+| `run:progress` | ✅     | 進捗状態の復元       |
+| `log:write`    | ✅     | ログの永続化         |
+| `stream`       | ❌     | メモリのみ、直接配信 |
 
 **トレードオフ**:
 - 再接続時にトークン単位の再生は不可
 - 進行中ステップがあれば、そのステップは最初からやり直し
 - ステップを細かく分ければ損失は最小限
 
-**実装イメージ**:
-
-```ts
-step.stream('generate-response', async (emit) => {
-  for await (const chunk of llmStream) {
-    // emit はメモリのみ → 接続中のクライアントに即座に配信
-    emit({ type: 'token', text: chunk.text })
-  }
-  // ステップ完了時に最終結果が DB に保存される
-  return fullResponse
-})
-```
-
-**再接続時の挙動**:
-
-1. クライアントが再接続
-2. DB から `step:complete` までのイベントを再生
-3. 進行中のステップがあれば、ステップ完了を待つ
-4. 完了していないステップの途中経過（トークン）は失われる
-
-これは許容できる制約。理由:
-- LLM の応答は再生成可能（決定論的ではないが、意味的には同等）
-- ステップを細かく分ければ損失は小さい
-- DB負荷を劇的に削減できる
-
 ### ストレージ容量
 
 永続化するイベントは粗いものに限定されるため、容量問題は軽減される。
@@ -494,39 +386,33 @@ export const codingAssistant = defineJob({
   },
 })
 
-// main.ts
-import { createDurably } from '@coji/durably'
-import { codingAssistant } from './jobs'
+// client.ts - subscribe() で購読
+const stream = durably.subscribe(run.id)
 
-const durably = createDurably({ dialect })
-const { codingAssistant: codingAssistantJob } = durably.register({
-  codingAssistant,
-})
+const reader = stream.getReader()
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
 
-const run = await codingAssistantJob.trigger({
-  task: 'Add user authentication',
-  codebase: '/path/to/repo',
-})
-
-const stream = await codingAssistantJob.subscribe(run.id)
-
-for await (const event of stream) {
-  switch (event.type) {
+  switch (value.type) {
     case 'stream':
-      switch (event.data.type) {
+      switch (value.data.type) {
         case 'thinking':
-          appendToThinkingPanel(event.data.text)
+          appendToThinkingPanel(value.data.text)
           break
         case 'diff-chunk':
-          appendToDiffViewer(event.data.file, event.data.text)
+          appendToDiffViewer(value.data.file, value.data.text)
           break
         case 'status':
-          updateStatus(event.data.message)
+          updateStatus(value.data.message)
           break
       }
       break
+    case 'run:progress':
+      updateProgressBar(value.progress)
+      break
     case 'run:complete':
-      showFinalResult(event.output)
+      showFinalResult(value.output)
       break
   }
 }
@@ -536,13 +422,12 @@ for await (const event of stream) {
 
 ## まとめ
 
-| 機能 | 優先度 | 複雑度 | 備考 |
-|------|--------|--------|------|
-| `step.stream()` | 高 | 中 | AI Agent の基本要件 |
-| `subscribe()` (ReadableStream) | 高 | 低 | Web Streams API、追加依存なし |
-| 粗いイベントのみ永続化 | 高 | 低 | step:*, run:* のみ DB 保存。トークン単位はメモリのみ |
-| `resumeFrom` 再接続 | 高 | 低 | 完了済みステップから再生 |
-| `checkpoint()` | 中 | 高 | 長時間実行に必要 |
-| BroadcastChannel | 低 | 低 | ブラウザ専用の最適化 |
+| 機能                 | 状態           | 複雑度 | 備考                         |
+|----------------------|----------------|--------|------------------------------|
+| `subscribe()`        | ✅ v1 実装済み | -      | ReadableStream を返す        |
+| `step.stream()`      | 🔜 v2 Phase A  | 中     | AI Agent の基本要件          |
+| イベント永続化       | 🔜 v2 Phase B  | 中     | 粗いイベントのみ DB 保存     |
+| `resumeFrom` 再接続  | 🔜 v2 Phase B  | 低     | 永続化されたイベントから再生 |
+| `checkpoint()`       | 🔜 v2 Phase C  | 高     | 長時間実行に必要             |
 
-v0.1 (現在の計画) の完成後、Phase A から段階的に実装していく。
+v1 の `subscribe()` をベースに、段階的に拡張していく。

From 013c2b8fbc563cb72de9e62e05457640e1141d16 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 18:03:49 +0900
Subject: [PATCH 063/101] refactor(examples): reorganize by use case and add
 SPA example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename examples with usecase-framework naming convention:
  - node -> server-node
  - react -> browser-vite-react
  - react-router -> fullstack-react-router
- Add browser-react-router-spa: React Router v7 SPA mode example
  - SQLite WASM + OPFS for browser-only persistence
  - DurablyProvider for lifecycle management
  - Multiple job examples (image processing, data sync)
  - Run history dashboard with retry/cancel/delete

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-react-router-spa/.gitignore  |   7 +
 examples/browser-react-router-spa/README.md   |  71 ++++
 .../app/app.css                               |   0
 .../app/entry.client.tsx                      |  12 +
 .../browser-react-router-spa/app/lib/jobs.ts  | 104 ++++++
 .../browser-react-router-spa/app/root.tsx     |  92 +++++
 .../browser-react-router-spa/app/routes.ts    |   3 +
 .../app/routes/_index.tsx                     | 334 ++++++++++++++++++
 .../app/routes/_index/dashboard.tsx           | 293 +++++++++++++++
 examples/browser-react-router-spa/biome.json  |  13 +
 .../browser-react-router-spa/package.json     |  41 +++
 .../prettier.config.js                        |   7 +
 .../public/favicon.ico                        | Bin
 .../react-router.config.ts                    |   6 +
 .../tsconfig.json                             |   0
 .../browser-react-router-spa/vite.config.ts   |  29 ++
 .../{react => browser-vite-react}/.gitignore  |   0
 .../{node => browser-vite-react}/biome.json   |   0
 .../{react => browser-vite-react}/index.html  |   0
 .../package.json                              |   2 +-
 .../prettier.config.js                        |   0
 .../{react => browser-vite-react}/src/App.tsx |   0
 .../src/Dashboard.tsx                         |   0
 .../src/jobs/processImage.ts                  |   0
 .../src/main.tsx                              |   0
 .../src/styles.ts                             |   0
 .../tsconfig.json                             |   0
 .../{react => browser-vite-react}/vercel.json |   0
 .../vite.config.ts                            |   0
 .../.dockerignore                             |   0
 .../.gitignore                                |   0
 .../Dockerfile                                |   0
 .../README.md                                 |   0
 examples/fullstack-react-router/app/app.css   |  12 +
 .../app/jobs/import-csv.ts                    |   0
 .../app/jobs/index.ts                         |   0
 .../app/lib/durably.server.ts                 |   0
 .../app/root.tsx                              |   0
 .../app/routes.ts                             |   0
 .../app/routes/_index.tsx                     |   0
 .../app/routes/_index/dashboard.tsx           |   0
 .../app/routes/_index/run-progress.tsx        |   0
 .../app/routes/api.durably.$.ts               |   0
 .../biome.json                                |   0
 .../package.json                              |   2 +-
 .../prettier.config.js                        |   0
 .../fullstack-react-router/public/favicon.ico | Bin 0 -> 15086 bytes
 .../react-router.config.ts                    |   0
 examples/fullstack-react-router/tsconfig.json |  27 ++
 .../vite.config.ts                            |   0
 examples/{node => server-node}/.gitignore     |   0
 examples/{node => server-node}/basic.ts       |   0
 examples/{react => server-node}/biome.json    |   0
 examples/{node => server-node}/package.json   |   2 +-
 .../{react => server-node}/prettier.config.js |   0
 examples/{node => server-node}/tsconfig.json  |   0
 pnpm-lock.yaml                                | 246 +++++++++++--
 57 files changed, 1279 insertions(+), 24 deletions(-)
 create mode 100644 examples/browser-react-router-spa/.gitignore
 create mode 100644 examples/browser-react-router-spa/README.md
 rename examples/{react-router => browser-react-router-spa}/app/app.css (100%)
 create mode 100644 examples/browser-react-router-spa/app/entry.client.tsx
 create mode 100644 examples/browser-react-router-spa/app/lib/jobs.ts
 create mode 100644 examples/browser-react-router-spa/app/root.tsx
 create mode 100644 examples/browser-react-router-spa/app/routes.ts
 create mode 100644 examples/browser-react-router-spa/app/routes/_index.tsx
 create mode 100644 examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
 create mode 100644 examples/browser-react-router-spa/biome.json
 create mode 100644 examples/browser-react-router-spa/package.json
 create mode 100644 examples/browser-react-router-spa/prettier.config.js
 rename examples/{react-router => browser-react-router-spa}/public/favicon.ico (100%)
 create mode 100644 examples/browser-react-router-spa/react-router.config.ts
 rename examples/{react-router => browser-react-router-spa}/tsconfig.json (100%)
 create mode 100644 examples/browser-react-router-spa/vite.config.ts
 rename examples/{react => browser-vite-react}/.gitignore (100%)
 rename examples/{node => browser-vite-react}/biome.json (100%)
 rename examples/{react => browser-vite-react}/index.html (100%)
 rename examples/{react => browser-vite-react}/package.json (95%)
 rename examples/{node => browser-vite-react}/prettier.config.js (100%)
 rename examples/{react => browser-vite-react}/src/App.tsx (100%)
 rename examples/{react => browser-vite-react}/src/Dashboard.tsx (100%)
 rename examples/{react => browser-vite-react}/src/jobs/processImage.ts (100%)
 rename examples/{react => browser-vite-react}/src/main.tsx (100%)
 rename examples/{react => browser-vite-react}/src/styles.ts (100%)
 rename examples/{react => browser-vite-react}/tsconfig.json (100%)
 rename examples/{react => browser-vite-react}/vercel.json (100%)
 rename examples/{react => browser-vite-react}/vite.config.ts (100%)
 rename examples/{react-router => fullstack-react-router}/.dockerignore (100%)
 rename examples/{react-router => fullstack-react-router}/.gitignore (100%)
 rename examples/{react-router => fullstack-react-router}/Dockerfile (100%)
 rename examples/{react-router => fullstack-react-router}/README.md (100%)
 create mode 100644 examples/fullstack-react-router/app/app.css
 rename examples/{react-router => fullstack-react-router}/app/jobs/import-csv.ts (100%)
 rename examples/{react-router => fullstack-react-router}/app/jobs/index.ts (100%)
 rename examples/{react-router => fullstack-react-router}/app/lib/durably.server.ts (100%)
 rename examples/{react-router => fullstack-react-router}/app/root.tsx (100%)
 rename examples/{react-router => fullstack-react-router}/app/routes.ts (100%)
 rename examples/{react-router => fullstack-react-router}/app/routes/_index.tsx (100%)
 rename examples/{react-router => fullstack-react-router}/app/routes/_index/dashboard.tsx (100%)
 rename examples/{react-router => fullstack-react-router}/app/routes/_index/run-progress.tsx (100%)
 rename examples/{react-router => fullstack-react-router}/app/routes/api.durably.$.ts (100%)
 rename examples/{react-router => fullstack-react-router}/biome.json (100%)
 rename examples/{react-router => fullstack-react-router}/package.json (96%)
 rename examples/{react-router => fullstack-react-router}/prettier.config.js (100%)
 create mode 100644 examples/fullstack-react-router/public/favicon.ico
 rename examples/{react-router => fullstack-react-router}/react-router.config.ts (100%)
 create mode 100644 examples/fullstack-react-router/tsconfig.json
 rename examples/{react-router => fullstack-react-router}/vite.config.ts (100%)
 rename examples/{node => server-node}/.gitignore (100%)
 rename examples/{node => server-node}/basic.ts (100%)
 rename examples/{react => server-node}/biome.json (100%)
 rename examples/{node => server-node}/package.json (95%)
 rename examples/{react => server-node}/prettier.config.js (100%)
 rename examples/{node => server-node}/tsconfig.json (100%)

diff --git a/examples/browser-react-router-spa/.gitignore b/examples/browser-react-router-spa/.gitignore
new file mode 100644
index 00000000..4e2bf0b3
--- /dev/null
+++ b/examples/browser-react-router-spa/.gitignore
@@ -0,0 +1,7 @@
+node_modules
+
+/.cache
+/build
+.env
+.react-router
+*.sqlite3
diff --git a/examples/browser-react-router-spa/README.md b/examples/browser-react-router-spa/README.md
new file mode 100644
index 00000000..b63d552a
--- /dev/null
+++ b/examples/browser-react-router-spa/README.md
@@ -0,0 +1,71 @@
+# Browser-Only SPA Example (React Router v7)
+
+This example demonstrates Durably running entirely in the browser using React Router v7 in SPA mode.
+
+## Features
+
+- **React Router v7 SPA mode** - No server-side rendering, pure client-side app
+- **SQLite WASM with OPFS** - Persistent storage in the browser
+- **DurablyProvider** - React context for lifecycle management
+- **Multiple jobs** - Image processing and data sync examples
+- **Run history dashboard** - View, retry, cancel, and delete runs
+- **Tailwind CSS** - Modern styling
+
+## Getting Started
+
+```bash
+# Install dependencies
+pnpm install
+
+# Start development server (generates types automatically)
+pnpm dev
+```
+
+Open http://localhost:5173
+
+> **Note:** Run `pnpm dev` at least once before `pnpm typecheck` to generate React Router type definitions.
+
+## Requirements
+
+### COOP/COEP Headers
+
+SQLite WASM requires cross-origin isolation. This is configured in `vite.config.ts`:
+
+```http
+Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Opener-Policy: same-origin
+```
+
+### Secure Context
+
+Browser-only mode requires HTTPS or localhost for OPFS access.
+
+## Project Structure
+
+```
+app/
+├── root.tsx           # DurablyProvider setup with SQLocalKysely
+├── lib/
+│   └── jobs.ts        # Job definitions (processImageJob, dataSyncJob)
+└── routes/
+    └── _index.tsx     # Main page with job panels
+    └── _index/
+        └── dashboard.tsx  # Run history component
+```
+
+## Key Differences from Fullstack Mode
+
+| Aspect | Browser-Only (SPA) | Fullstack (SSR) |
+|--------|-------------------|-----------------|
+| Database | SQLite WASM + OPFS | libsql/better-sqlite3 |
+| Provider | `DurablyProvider` | No provider needed |
+| Hooks | `useJob(jobDefinition)` | `durably.jobName.useJob()` |
+| Data | Stays in browser | Server-side storage |
+| Offline | Works offline | Requires server |
+
+## Try It
+
+1. Run a job and observe the progress
+2. Reload the page during execution - it resumes automatically
+3. Check the dashboard for run history
+4. Try retry/cancel/delete actions
diff --git a/examples/react-router/app/app.css b/examples/browser-react-router-spa/app/app.css
similarity index 100%
rename from examples/react-router/app/app.css
rename to examples/browser-react-router-spa/app/app.css
diff --git a/examples/browser-react-router-spa/app/entry.client.tsx b/examples/browser-react-router-spa/app/entry.client.tsx
new file mode 100644
index 00000000..7e8a9375
--- /dev/null
+++ b/examples/browser-react-router-spa/app/entry.client.tsx
@@ -0,0 +1,12 @@
+import { startTransition, StrictMode } from 'react'
+import { hydrateRoot } from 'react-dom/client'
+import { HydratedRouter } from 'react-router/dom'
+
+startTransition(() => {
+  hydrateRoot(
+    document,
+    
+      
+    ,
+  )
+})
diff --git a/examples/browser-react-router-spa/app/lib/jobs.ts b/examples/browser-react-router-spa/app/lib/jobs.ts
new file mode 100644
index 00000000..c58219d3
--- /dev/null
+++ b/examples/browser-react-router-spa/app/lib/jobs.ts
@@ -0,0 +1,104 @@
+/**
+ * Job definitions for browser-only mode
+ *
+ * These jobs run entirely in the browser using SQLite WASM with OPFS.
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+/**
+ * Process Image Job
+ *
+ * Simulates image processing with multiple steps.
+ */
+export const processImageJob = defineJob({
+  name: 'process-image',
+  input: z.object({ filename: z.string(), width: z.number() }),
+  output: z.object({ url: z.string(), size: z.number() }),
+  run: async (step, payload) => {
+    step.log.info(`Starting image processing: ${payload.filename}`)
+
+    // Download original image
+    const fileSize = await step.run('download', async () => {
+      step.progress(1, 3, 'Downloading...')
+      await delay(500)
+      return Math.floor(Math.random() * 1000000) + 500000 // 500KB-1.5MB
+    })
+
+    step.log.info(`Downloaded: ${fileSize} bytes`)
+
+    // Resize to target width
+    const resizedSize = await step.run('resize', async () => {
+      step.progress(2, 3, 'Resizing...')
+      await delay(600)
+      return Math.floor(fileSize * (payload.width / 1920))
+    })
+
+    step.log.info(`Resized to: ${resizedSize} bytes`)
+
+    // Upload to CDN
+    const url = await step.run('upload', async () => {
+      step.progress(3, 3, 'Uploading...')
+      await delay(400)
+      return `https://cdn.example.com/${payload.width}/${payload.filename}`
+    })
+
+    step.log.info(`Uploaded to: ${url}`)
+
+    return { url, size: resizedSize }
+  },
+})
+
+/**
+ * Data Sync Job
+ *
+ * Simulates syncing data with a remote server.
+ */
+export const dataSyncJob = defineJob({
+  name: 'data-sync',
+  input: z.object({ userId: z.string() }),
+  output: z.object({ synced: z.number(), failed: z.number() }),
+  run: async (step, payload) => {
+    step.log.info(`Starting sync for user: ${payload.userId}`)
+
+    const items = await step.run('fetch-local', async () => {
+      step.progress(1, 4, 'Fetching local data...')
+      await delay(300)
+      return Array.from({ length: 10 }, (_, i) => ({
+        id: `item-${i}`,
+        data: `Data for ${payload.userId}`,
+      }))
+    })
+
+    let synced = 0
+    let failed = 0
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]
+      const success = await step.run(`sync-item-${item.id}`, async () => {
+        step.progress(2 + Math.floor(i / 5), 4, `Syncing item ${i + 1}...`)
+        await delay(100)
+        return Math.random() > 0.1 // 90% success rate
+      })
+
+      if (success) {
+        synced++
+      } else {
+        failed++
+        step.log.warn(`Failed to sync item: ${item.id}`)
+      }
+    }
+
+    await step.run('finalize', async () => {
+      step.progress(4, 4, 'Finalizing...')
+      await delay(200)
+    })
+
+    step.log.info(`Sync complete: ${synced} synced, ${failed} failed`)
+
+    return { synced, failed }
+  },
+})
diff --git a/examples/browser-react-router-spa/app/root.tsx b/examples/browser-react-router-spa/app/root.tsx
new file mode 100644
index 00000000..4dab506e
--- /dev/null
+++ b/examples/browser-react-router-spa/app/root.tsx
@@ -0,0 +1,92 @@
+import { DurablyProvider } from '@coji/durably-react'
+import {
+  isRouteErrorResponse,
+  Links,
+  Meta,
+  Outlet,
+  Scripts,
+  ScrollRestoration,
+} from 'react-router'
+import { SQLocalKysely } from 'sqlocal/kysely'
+import type { Route } from './+types/root'
+import './app.css'
+
+// SQLocal instance for SQLite WASM with OPFS
+const sqlocal = new SQLocalKysely('example.sqlite3')
+
+export function links() {
+  return [
+    { rel: 'preconnect', href: 'https://fonts.googleapis.com' },
+    {
+      rel: 'preconnect',
+      href: 'https://fonts.gstatic.com',
+      crossOrigin: 'anonymous',
+    },
+    {
+      rel: 'stylesheet',
+      href: 'https://fonts.googleapis.com/css2?family=Inter:ital,opsz,wght@0,14..32,100..900;1,14..32,100..900&display=swap',
+    },
+  ]
+}
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  return (
+    
+      
+        
+        
+        
+        
+      
+      
+        {children}
+        
+        
+      
+    
+  )
+}
+
+export default function App() {
+  return (
+     sqlocal.dialect}
+      options={{
+        pollingInterval: 100,
+        heartbeatInterval: 500,
+        staleThreshold: 3000,
+      }}
+    >
+      
+    
+  )
+}
+
+export function ErrorBoundary({ error }: Route.ErrorBoundaryProps) {
+  let message = 'Oops!'
+  let details = 'An unexpected error occurred.'
+  let stack: string | undefined
+
+  if (isRouteErrorResponse(error)) {
+    message = error.status === 404 ? '404' : 'Error'
+    details =
+      error.status === 404
+        ? 'The requested page could not be found.'
+        : error.statusText || details
+  } else if (import.meta.env.DEV && error && error instanceof Error) {
+    details = error.message
+    stack = error.stack
+  }
+
+  return (
+    
    
+      
    {message}
    
+      
    {details}
    
+      {stack && (
+        
    +          {stack}
+        
    
+      )}
+    
    
+  )
+}
diff --git a/examples/browser-react-router-spa/app/routes.ts b/examples/browser-react-router-spa/app/routes.ts
new file mode 100644
index 00000000..6c129bf6
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes.ts
@@ -0,0 +1,3 @@
+import { type RouteConfig, index } from '@react-router/dev/routes'
+
+export default [index('routes/_index.tsx')] satisfies RouteConfig
diff --git a/examples/browser-react-router-spa/app/routes/_index.tsx b/examples/browser-react-router-spa/app/routes/_index.tsx
new file mode 100644
index 00000000..c1307365
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index.tsx
@@ -0,0 +1,334 @@
+/**
+ * Browser-Only SPA Example
+ *
+ * This example demonstrates:
+ * - React Router v7 in SPA mode (ssr: false)
+ * - SQLite WASM with OPFS for browser-only persistence
+ * - DurablyProvider for context and lifecycle management
+ * - useJob hook for triggering and monitoring jobs
+ */
+
+import { useDurably, useJob, type LogEntry } from '@coji/durably-react'
+import { useState } from 'react'
+import { Link } from 'react-router'
+import { SQLocalKysely } from 'sqlocal/kysely'
+import { dataSyncJob, processImageJob } from '~/lib/jobs'
+import { Dashboard } from './_index/dashboard'
+
+const sqlocal = new SQLocalKysely('example.sqlite3')
+
+export default function Index() {
+  const [activeTab, setActiveTab] = useState<'image' | 'sync'>('image')
+  const { durably } = useDurably()
+
+  const handleReset = async () => {
+    if (durably) {
+      await durably.stop()
+    }
+    await sqlocal.deleteDatabaseFile()
+    location.reload()
+  }
+
+  return (
+    
    
+      
    
+        
    
+          
    
+            Durably - Browser-Only SPA
+          
    
+          
    
+            React Router v7 SPA mode with SQLite WASM + OPFS
+          
    
+          
    
+            
+              GitHub
+            
+            |
+            
+              Source Code
+            
+          
    
+        
    
+
+        
    
+          
    
+            
+            
+            
    
+            
+            
+          
    
+
+          {activeTab === 'image' ?  : }
+        
    
+
+        
+
+        
    
+          
    
+            All data is stored locally in your browser using SQLite WASM with
+            OPFS.
+          
    
+          
    
+            Try reloading the page during job execution - it will resume
+            automatically!
+          
    
+        
    
+      
    
+    
    
+  )
+}
+
+function ImageProcessingPanel() {
+  const {
+    trigger,
+    output,
+    error,
+    progress,
+    logs,
+    isReady,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJob(processImageJob)
+
+  const handleRun = async () => {
+    await trigger({ filename: 'photo.jpg', width: 800 })
+  }
+
+  return (
+    
+  )
+}
+
+function DataSyncPanel() {
+  const {
+    trigger,
+    output,
+    error,
+    progress,
+    logs,
+    isReady,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJob(dataSyncJob)
+
+  const handleRun = async () => {
+    await trigger({ userId: 'user_123' })
+  }
+
+  return (
+    
+  )
+}
+
+interface JobPanelProps {
+  title: string
+  description: string
+  onRun: () => void
+  isReady: boolean
+  isPending: boolean
+  isRunning: boolean
+  isCompleted: boolean
+  isFailed: boolean
+  progress: { current: number; total?: number; message?: string } | null
+  output: unknown
+  error: string | null
+  logs: LogEntry[]
+}
+
+function JobPanel({
+  title,
+  description,
+  onRun,
+  isReady,
+  isPending,
+  isRunning,
+  isCompleted,
+  isFailed,
+  progress,
+  output,
+  error,
+  logs,
+}: JobPanelProps) {
+  const statusText = isRunning
+    ? 'Running...'
+    : isCompleted
+      ? '✓ Completed'
+      : isFailed
+        ? '✗ Failed'
+        : isPending
+          ? 'Pending...'
+          : isReady
+            ? 'Ready'
+            : 'Initializing...'
+
+  const statusColor = isCompleted
+    ? 'text-green-600'
+    : isFailed
+      ? 'text-red-600'
+      : isRunning
+        ? 'text-blue-600'
+        : 'text-gray-600'
+
+  return (
+    
    
+      
    
+        
    
+          
    {title}
    
+          
    {description}
    
+        
    
+        
+      
    
+
+      
    
+        
    
+          
    
+            Status: 
+            {statusText}
+          
    
+
+          {progress && (
+            
    
+              
    
+                {progress.message}
+                
+                  {progress.current}
+                  {progress.total ? `/${progress.total}` : ''}
+                
+              
    
+              
    
+                
    
+              
    
+            
    
+          )}
+
+          {output && (
+            
    
+              
    
+                Output
+              
    
+              
    +                {JSON.stringify(output, null, 2)}
+              
    
+            
    
+          )}
+
+          {error && (
+            
    
+              
    Error
    
+              
    {error}
    
+            
    
+          )}
+        
    
+
+        
    
+          {logs.length > 0 && (
+            
    
+              
    Logs
    
+              
    
+                
      
+                  {logs.map((log) => (
+                    
    • 
+                      
+                        [{log.level}]
+                      {' '}
+                      {log.message}
+                    
      • 
+                  ))}
+                
    
+              
    
+            
    
+          )}
+        
    
+      
    
+    
    
+  )
+}
diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
new file mode 100644
index 00000000..c21d6266
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -0,0 +1,293 @@
+/**
+ * Dashboard Component
+ *
+ * Displays run history with real-time updates and pagination.
+ * Uses browser-only mode hooks for direct durably access.
+ */
+
+import type { Run } from '@coji/durably'
+import { useDurably, useRuns } from '@coji/durably-react'
+import { useState } from 'react'
+
+export function Dashboard() {
+  const { durably } = useDurably()
+  const { runs, page, hasMore, refresh, nextPage, prevPage } = useRuns({
+    pageSize: 6,
+  })
+
+  const [selectedRun, setSelectedRun] = useState(null)
+  const [steps, setSteps] = useState<
+    { index: number; name: string; status: string }[]
+  >([])
+
+  const showDetails = async (runId: string) => {
+    if (!durably) return
+    const run = await durably.getRun(runId)
+    if (run) {
+      setSelectedRun(run)
+      const stepsData = await durably.storage.getSteps(runId)
+      setSteps(
+        stepsData.map((s, i) => ({ index: i, name: s.name, status: s.status })),
+      )
+    }
+  }
+
+  const handleRetry = async (runId: string) => {
+    if (!durably) return
+    await durably.retry(runId)
+    refresh()
+  }
+
+  const handleCancel = async (runId: string) => {
+    if (!durably) return
+    await durably.cancel(runId)
+    refresh()
+  }
+
+  const handleDelete = async (runId: string) => {
+    if (!durably) return
+    await durably.deleteRun(runId)
+    setSelectedRun(null)
+    refresh()
+  }
+
+  const formatDate = (iso: string) => new Date(iso).toLocaleString()
+
+  const statusClasses: Record = {
+    pending: 'bg-yellow-100 text-yellow-800',
+    running: 'bg-blue-100 text-blue-800',
+    completed: 'bg-green-100 text-green-800',
+    failed: 'bg-red-100 text-red-800',
+    cancelled: 'bg-gray-100 text-gray-800',
+  }
+
+  return (
+    
    
+      
    
+        
    Run History
    
+        
+      
    
+
+      {runs.length === 0 ? (
+        
    No runs yet
    
+      ) : (
+        <>
+          
    
+            
+              
+                
+                  
+                  
+                  
+                  
+                  
+                
+              
+              
+                {runs.map((run) => (
+                  
+                    
+                    
+                    
+                    
+                    
+                  
+                ))}
+              
+            
    
+                    ID
+                  
+                    Job
+                  
+                    Status
+                  
+                    Created
+                  
+                    Actions
+                  
    
+                      {run.id.slice(0, 8)}...
+                    {run.jobName}
+                      
+                        {run.status}
+                      
+                    
+                      {formatDate(run.createdAt)}
+                    
+                      
    
+                        
+                        {run.status === 'failed' && (
+                          
+                        )}
+                        {(run.status === 'running' ||
+                          run.status === 'pending') && (
+                          
+                        )}
+                        {run.status !== 'running' &&
+                          run.status !== 'pending' && (
+                            
+                          )}
+                      
    
+                    
    
+          
    
+
+          {/* Pagination */}
+          
    
+            
+            Page {page + 1}
+            
+          
    
+        
+      )}
+
+      {/* Run Details Modal */}
+      {selectedRun && (
+        
    
+          
    
+            
    
+              
    
+                
    Run Details
    
+                
+              
    
+
+              
    
+                
    
+                  ID:{' '}
+                  
+                    {selectedRun.id}
+                  
+                
    
+                
    
+                  Job:{' '}
+                  {selectedRun.jobName}
+                
    
+                
    
+                  Status:{' '}
+                  
+                    {selectedRun.status}
+                  
+                
    
+                
    
+                  Created:{' '}
+                  {formatDate(selectedRun.createdAt)}
+                
    
+
+                {selectedRun.progress && (
+                  
    
+                    Progress:{' '}
+                    {selectedRun.progress.current}
+                    {selectedRun.progress.total
+                      ? `/${selectedRun.progress.total}`
+                      : ''}{' '}
+                    {selectedRun.progress.message || ''}
+                  
    
+                )}
+
+                {selectedRun.error && (
+                  
    
+                    Error:{' '}
+                    {selectedRun.error}
+                  
    
+                )}
+
+                {selectedRun.output !== null && (
+                  
    
+                    Output:
+                    
    +                      {JSON.stringify(selectedRun.output, null, 2)}
+                    
    
+                  
    
+                )}
+
+                
    
+                  Payload:
+                  
    +                    {JSON.stringify(selectedRun.payload, null, 2)}
+                  
    
+                
    
+
+                {steps.length > 0 && (
+                  
    
+                    Steps:
+                    
      
+                      {steps.map((s) => (
+                        
    • 
+                          {s.name}
+                          
+                            {s.status}
+                          
+                        
      • 
+                      ))}
+                    
    
+                  
    
+                )}
+              
    
+            
    
+          
    
+        
    
+      )}
+    
    
+  )
+}
diff --git a/examples/browser-react-router-spa/biome.json b/examples/browser-react-router-spa/biome.json
new file mode 100644
index 00000000..285e2ef8
--- /dev/null
+++ b/examples/browser-react-router-spa/biome.json
@@ -0,0 +1,13 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.0.5/schema.json",
+  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
+  "formatter": { "enabled": false },
+  "linter": {
+    "enabled": true,
+    "rules": { "recommended": true }
+  },
+  "organizeImports": { "enabled": false },
+  "javascript": {
+    "globals": []
+  }
+}
diff --git a/examples/browser-react-router-spa/package.json b/examples/browser-react-router-spa/package.json
new file mode 100644
index 00000000..624217d5
--- /dev/null
+++ b/examples/browser-react-router-spa/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "example-browser-react-router-spa",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "react-router build",
+    "dev": "react-router dev",
+    "preview": "vite preview",
+    "typecheck": "echo 'Run pnpm dev first to generate types' && tsc",
+    "lint": "biome lint .",
+    "lint:fix": "biome lint --write .",
+    "format": "prettier --experimental-cli --check .",
+    "format:fix": "prettier --experimental-cli --write ."
+  },
+  "dependencies": {
+    "@coji/durably": "workspace:*",
+    "@coji/durably-react": "workspace:*",
+    "@react-router/node": "7.11.0",
+    "kysely": "^0.28.9",
+    "react": "^19.2.3",
+    "react-dom": "^19.2.3",
+    "react-router": "7.11.0",
+    "sqlocal": "^0.16.0",
+    "zod": "^4.3.2",
+    "isbot": "^5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.10",
+    "@react-router/dev": "7.11.0",
+    "@types/node": "^22",
+    "@tailwindcss/vite": "^4.1.18",
+    "@types/react": "^19.2.7",
+    "@types/react-dom": "^19.2.3",
+    "prettier": "^3.7.4",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.0",
+    "vite-tsconfig-paths": "^6.0.3"
+  }
+}
diff --git a/examples/browser-react-router-spa/prettier.config.js b/examples/browser-react-router-spa/prettier.config.js
new file mode 100644
index 00000000..f28e092a
--- /dev/null
+++ b/examples/browser-react-router-spa/prettier.config.js
@@ -0,0 +1,7 @@
+/** @type {import('prettier').Config} */
+export default {
+  semi: false,
+  singleQuote: true,
+  trailingComma: 'all',
+  plugins: ['prettier-plugin-organize-imports'],
+}
diff --git a/examples/react-router/public/favicon.ico b/examples/browser-react-router-spa/public/favicon.ico
similarity index 100%
rename from examples/react-router/public/favicon.ico
rename to examples/browser-react-router-spa/public/favicon.ico
diff --git a/examples/browser-react-router-spa/react-router.config.ts b/examples/browser-react-router-spa/react-router.config.ts
new file mode 100644
index 00000000..d28d0110
--- /dev/null
+++ b/examples/browser-react-router-spa/react-router.config.ts
@@ -0,0 +1,6 @@
+import type { Config } from '@react-router/dev/config'
+
+export default {
+  // SPA mode - no server-side rendering
+  ssr: false,
+} satisfies Config
diff --git a/examples/react-router/tsconfig.json b/examples/browser-react-router-spa/tsconfig.json
similarity index 100%
rename from examples/react-router/tsconfig.json
rename to examples/browser-react-router-spa/tsconfig.json
diff --git a/examples/browser-react-router-spa/vite.config.ts b/examples/browser-react-router-spa/vite.config.ts
new file mode 100644
index 00000000..1df00322
--- /dev/null
+++ b/examples/browser-react-router-spa/vite.config.ts
@@ -0,0 +1,29 @@
+import tailwindcss from '@tailwindcss/vite'
+import { reactRouter } from '@react-router/dev/vite'
+import { defineConfig } from 'vite'
+import tsconfigPaths from 'vite-tsconfig-paths'
+
+export default defineConfig({
+  plugins: [
+    tailwindcss(),
+    reactRouter(),
+    tsconfigPaths(),
+    // COOP/COEP headers for SQLite WASM (required for browser-only mode)
+    {
+      name: 'configure-response-headers',
+      configureServer: (server) => {
+        server.middlewares.use((_req, res, next) => {
+          res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+          res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+          next()
+        })
+      },
+    },
+  ],
+  optimizeDeps: {
+    exclude: ['sqlocal'],
+  },
+  worker: {
+    format: 'es',
+  },
+})
diff --git a/examples/react/.gitignore b/examples/browser-vite-react/.gitignore
similarity index 100%
rename from examples/react/.gitignore
rename to examples/browser-vite-react/.gitignore
diff --git a/examples/node/biome.json b/examples/browser-vite-react/biome.json
similarity index 100%
rename from examples/node/biome.json
rename to examples/browser-vite-react/biome.json
diff --git a/examples/react/index.html b/examples/browser-vite-react/index.html
similarity index 100%
rename from examples/react/index.html
rename to examples/browser-vite-react/index.html
diff --git a/examples/react/package.json b/examples/browser-vite-react/package.json
similarity index 95%
rename from examples/react/package.json
rename to examples/browser-vite-react/package.json
index 0b1bb0b6..3b577881 100644
--- a/examples/react/package.json
+++ b/examples/browser-vite-react/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "example-react",
+  "name": "example-browser-vite-react",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/examples/node/prettier.config.js b/examples/browser-vite-react/prettier.config.js
similarity index 100%
rename from examples/node/prettier.config.js
rename to examples/browser-vite-react/prettier.config.js
diff --git a/examples/react/src/App.tsx b/examples/browser-vite-react/src/App.tsx
similarity index 100%
rename from examples/react/src/App.tsx
rename to examples/browser-vite-react/src/App.tsx
diff --git a/examples/react/src/Dashboard.tsx b/examples/browser-vite-react/src/Dashboard.tsx
similarity index 100%
rename from examples/react/src/Dashboard.tsx
rename to examples/browser-vite-react/src/Dashboard.tsx
diff --git a/examples/react/src/jobs/processImage.ts b/examples/browser-vite-react/src/jobs/processImage.ts
similarity index 100%
rename from examples/react/src/jobs/processImage.ts
rename to examples/browser-vite-react/src/jobs/processImage.ts
diff --git a/examples/react/src/main.tsx b/examples/browser-vite-react/src/main.tsx
similarity index 100%
rename from examples/react/src/main.tsx
rename to examples/browser-vite-react/src/main.tsx
diff --git a/examples/react/src/styles.ts b/examples/browser-vite-react/src/styles.ts
similarity index 100%
rename from examples/react/src/styles.ts
rename to examples/browser-vite-react/src/styles.ts
diff --git a/examples/react/tsconfig.json b/examples/browser-vite-react/tsconfig.json
similarity index 100%
rename from examples/react/tsconfig.json
rename to examples/browser-vite-react/tsconfig.json
diff --git a/examples/react/vercel.json b/examples/browser-vite-react/vercel.json
similarity index 100%
rename from examples/react/vercel.json
rename to examples/browser-vite-react/vercel.json
diff --git a/examples/react/vite.config.ts b/examples/browser-vite-react/vite.config.ts
similarity index 100%
rename from examples/react/vite.config.ts
rename to examples/browser-vite-react/vite.config.ts
diff --git a/examples/react-router/.dockerignore b/examples/fullstack-react-router/.dockerignore
similarity index 100%
rename from examples/react-router/.dockerignore
rename to examples/fullstack-react-router/.dockerignore
diff --git a/examples/react-router/.gitignore b/examples/fullstack-react-router/.gitignore
similarity index 100%
rename from examples/react-router/.gitignore
rename to examples/fullstack-react-router/.gitignore
diff --git a/examples/react-router/Dockerfile b/examples/fullstack-react-router/Dockerfile
similarity index 100%
rename from examples/react-router/Dockerfile
rename to examples/fullstack-react-router/Dockerfile
diff --git a/examples/react-router/README.md b/examples/fullstack-react-router/README.md
similarity index 100%
rename from examples/react-router/README.md
rename to examples/fullstack-react-router/README.md
diff --git a/examples/fullstack-react-router/app/app.css b/examples/fullstack-react-router/app/app.css
new file mode 100644
index 00000000..f3902dce
--- /dev/null
+++ b/examples/fullstack-react-router/app/app.css
@@ -0,0 +1,12 @@
+@import 'tailwindcss';
+
+@theme {
+  --font-sans:
+    'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+    'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+}
+
+html,
+body {
+  @apply bg-gray-50;
+}
diff --git a/examples/react-router/app/jobs/import-csv.ts b/examples/fullstack-react-router/app/jobs/import-csv.ts
similarity index 100%
rename from examples/react-router/app/jobs/import-csv.ts
rename to examples/fullstack-react-router/app/jobs/import-csv.ts
diff --git a/examples/react-router/app/jobs/index.ts b/examples/fullstack-react-router/app/jobs/index.ts
similarity index 100%
rename from examples/react-router/app/jobs/index.ts
rename to examples/fullstack-react-router/app/jobs/index.ts
diff --git a/examples/react-router/app/lib/durably.server.ts b/examples/fullstack-react-router/app/lib/durably.server.ts
similarity index 100%
rename from examples/react-router/app/lib/durably.server.ts
rename to examples/fullstack-react-router/app/lib/durably.server.ts
diff --git a/examples/react-router/app/root.tsx b/examples/fullstack-react-router/app/root.tsx
similarity index 100%
rename from examples/react-router/app/root.tsx
rename to examples/fullstack-react-router/app/root.tsx
diff --git a/examples/react-router/app/routes.ts b/examples/fullstack-react-router/app/routes.ts
similarity index 100%
rename from examples/react-router/app/routes.ts
rename to examples/fullstack-react-router/app/routes.ts
diff --git a/examples/react-router/app/routes/_index.tsx b/examples/fullstack-react-router/app/routes/_index.tsx
similarity index 100%
rename from examples/react-router/app/routes/_index.tsx
rename to examples/fullstack-react-router/app/routes/_index.tsx
diff --git a/examples/react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
similarity index 100%
rename from examples/react-router/app/routes/_index/dashboard.tsx
rename to examples/fullstack-react-router/app/routes/_index/dashboard.tsx
diff --git a/examples/react-router/app/routes/_index/run-progress.tsx b/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
similarity index 100%
rename from examples/react-router/app/routes/_index/run-progress.tsx
rename to examples/fullstack-react-router/app/routes/_index/run-progress.tsx
diff --git a/examples/react-router/app/routes/api.durably.$.ts b/examples/fullstack-react-router/app/routes/api.durably.$.ts
similarity index 100%
rename from examples/react-router/app/routes/api.durably.$.ts
rename to examples/fullstack-react-router/app/routes/api.durably.$.ts
diff --git a/examples/react-router/biome.json b/examples/fullstack-react-router/biome.json
similarity index 100%
rename from examples/react-router/biome.json
rename to examples/fullstack-react-router/biome.json
diff --git a/examples/react-router/package.json b/examples/fullstack-react-router/package.json
similarity index 96%
rename from examples/react-router/package.json
rename to examples/fullstack-react-router/package.json
index 8962bffe..5be7b81e 100644
--- a/examples/react-router/package.json
+++ b/examples/fullstack-react-router/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "example-react-router",
+  "name": "example-fullstack-react-router",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/examples/react-router/prettier.config.js b/examples/fullstack-react-router/prettier.config.js
similarity index 100%
rename from examples/react-router/prettier.config.js
rename to examples/fullstack-react-router/prettier.config.js
diff --git a/examples/fullstack-react-router/public/favicon.ico b/examples/fullstack-react-router/public/favicon.ico
new file mode 100644
index 0000000000000000000000000000000000000000..5dbdfcddcb14182535f6d32d1c900681321b1aa3
GIT binary patch
literal 15086
zcmeI33v3ic7{|AFEmuJ-;v>ep_G*NPi6KM`qNryCe1PIJ8siIN1WZ(7qVa)RVtmC%
z)Ch?tN+afMKm;5@rvorJk
zcXnoOc4q51HBQnQH_jn!cAg&XI1?PlX>Kl^k8qq0;zkha`kY$Fxt#=KNJAE9CMdpW
zqr4#g8`nTw191(+H4xW8Tmyru2I^3=J1G3emPxkPXA=3{vvuvse_WWSshqaqls^-m
zgB7q8&Vk*aYRe?sn$n53dGH#%3y%^vxv{pL*-h0Z4bmb_(k6{FL7HWIz(V*HT#IcS
z-wE{)+0x1U!RUPt3gB97%p}@oHxF4|6S*+Yw=_tLtxZ~`S=z6J?O^AfU>7qOX`JNBbV&8+bO0%@fhQitKIJ^O^
zpgIa__qD_y07t@DFlBJ)8SP_#^j{6jpaXt{U%=dx!qu=4u7^21lWEYHPPY5U3TcoQ
zX_7W+lvZi>TapNk_X>k-KO%MC9iZp>1E`N34gHKd9tK&){jq2~7OsJ>!G0FzxQFw6G
zm&Vb(2#-T|rM|n3>uAsG_hnbvUKFf3#ay@u4uTzia~NY%XgCHfx4^To4BDU@)HlV?
z@EN=g^ymETa1sQK{kRwyE4Ax8?wT&GvaG@ASO}{&a17&^v`y
z!oPdiSiia^oov(Z)QhG2&|FgE{M9_4hJROGbnj>#$~ZF$-G^|zPj*QApltKe?;u;uKHJ~-V!=VLkg7Kgct)l7u39f@%VG8e3f$N-B
zAu3a4%ZGf)r+jPAYCSLt73m_J3}p>}6Tx0j(wg4vvKhP!DzgiWANiE;Ppvp}P2W@m
z-VbYn+NXFF?6ngef5CfY6ZwKnWvNV4z6s^~yMXw2i5mv}jC$6$46g?G|CPAu{W5qF
zDobS=zb2ILX9D827g*NtGe5w;>frjanY{f)hrBP_2ehBt1?`~ypvg_Ot4x1V+43P@Ve8>qd)9NX_jWdLo`Zfy
zoeam9)@Dpym{4m@+LNxXBPjPKA7{3a&H+~xQvr>C_A;7=JrfK~$M2pCh>|xLz>W6SCs4qC|#V`)#
z)0C|?$o>jzh<|-cpf
    K7osU{Xp5PG4-K+L2G=)c3f&}H&M3wo7TlO_UJjQ-Oq&_
zjAc9=nNIYz{c3zxOiS5UfcE1}8#iI4@uy;$Q7>}u`j+OU0N<*Ezx$k{x_27+{s2Eg
z`^=rhtIzCm!_UcJ?Db~Lh-=_))PT3{Q0{Mwdq;0>ZL%l3+;B&4!&xm#%HYAK|;b456Iv&&f$VQHf`
z>$*K9w8T+paVwc7fLfMlhQ4)*zL_SG{~v4QR;IuX-(oRtYAhWOlh`NLoX0k$RUYMi
z2Y!bqpdN}wz8q`-%>&Le@q|jFw92ErW-hma-le?S
z-@OZt2EEUm4wLsuEMkt4zlyy29_3S50JAcQHTtgTC{P~%-mvCTzrjXOc|{}N`Cz`W
zSj7CrXfa7lcsU0J(0uSX6G`54t^7}+OLM0n(|g4waOQ}bd3%!XLh?NX9|8G_|06Ie
zD5F1)w5I~!et7lA{G^;uf7aqT`KE&2qx9|~O;s6t!gb`+zVLJyT2T)l*8l(j

literal 0
HcmV?d00001

diff --git a/examples/react-router/react-router.config.ts b/examples/fullstack-react-router/react-router.config.ts
similarity index 100%
rename from examples/react-router/react-router.config.ts
rename to examples/fullstack-react-router/react-router.config.ts
diff --git a/examples/fullstack-react-router/tsconfig.json b/examples/fullstack-react-router/tsconfig.json
new file mode 100644
index 00000000..dc391a45
--- /dev/null
+++ b/examples/fullstack-react-router/tsconfig.json
@@ -0,0 +1,27 @@
+{
+  "include": [
+    "**/*",
+    "**/.server/**/*",
+    "**/.client/**/*",
+    ".react-router/types/**/*"
+  ],
+  "compilerOptions": {
+    "lib": ["DOM", "DOM.Iterable", "ES2022"],
+    "types": ["node", "vite/client"],
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "rootDirs": [".", "./.react-router/types"],
+    "baseUrl": ".",
+    "paths": {
+      "~/*": ["./app/*"]
+    },
+    "esModuleInterop": true,
+    "verbatimModuleSyntax": true,
+    "noEmit": true,
+    "resolveJsonModule": true,
+    "skipLibCheck": true,
+    "strict": true
+  }
+}
diff --git a/examples/react-router/vite.config.ts b/examples/fullstack-react-router/vite.config.ts
similarity index 100%
rename from examples/react-router/vite.config.ts
rename to examples/fullstack-react-router/vite.config.ts
diff --git a/examples/node/.gitignore b/examples/server-node/.gitignore
similarity index 100%
rename from examples/node/.gitignore
rename to examples/server-node/.gitignore
diff --git a/examples/node/basic.ts b/examples/server-node/basic.ts
similarity index 100%
rename from examples/node/basic.ts
rename to examples/server-node/basic.ts
diff --git a/examples/react/biome.json b/examples/server-node/biome.json
similarity index 100%
rename from examples/react/biome.json
rename to examples/server-node/biome.json
diff --git a/examples/node/package.json b/examples/server-node/package.json
similarity index 95%
rename from examples/node/package.json
rename to examples/server-node/package.json
index 8aec017d..f0a7c220 100644
--- a/examples/node/package.json
+++ b/examples/server-node/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "example-node",
+  "name": "example-server-node",
   "private": true,
   "type": "module",
   "scripts": {
diff --git a/examples/react/prettier.config.js b/examples/server-node/prettier.config.js
similarity index 100%
rename from examples/react/prettier.config.js
rename to examples/server-node/prettier.config.js
diff --git a/examples/node/tsconfig.json b/examples/server-node/tsconfig.json
similarity index 100%
rename from examples/node/tsconfig.json
rename to examples/server-node/tsconfig.json
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index bedb0a47..14c8cdd2 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -19,7 +19,7 @@ importers:
         version: 4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16)
       cc-hooks-ts:
         specifier: 2.0.70
-        version: 2.0.70(typescript@5.9.3)(zod@4.2.1)
+        version: 2.0.70(typescript@5.9.3)(zod@4.3.2)
       tsx:
         specifier: ^4.21.0
         version: 4.21.0
@@ -30,44 +30,77 @@ importers:
         specifier: ^5.9.3
         version: 5.9.3
 
-  examples/node:
+  examples/browser-react-router-spa:
     dependencies:
       '@coji/durably':
         specifier: workspace:*
         version: link:../../packages/durably
-      '@libsql/client':
-        specifier: ^0.15.15
-        version: 0.15.15
-      '@libsql/kysely-libsql':
-        specifier: ^0.4.1
-        version: 0.4.1(kysely@0.28.9)
+      '@coji/durably-react':
+        specifier: workspace:*
+        version: link:../../packages/durably-react
+      '@react-router/node':
+        specifier: 7.11.0
+        version: 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)
+      isbot:
+        specifier: ^5
+        version: 5.1.32
       kysely:
         specifier: ^0.28.9
         version: 0.28.9
+      react:
+        specifier: ^19.2.3
+        version: 19.2.3
+      react-dom:
+        specifier: ^19.2.3
+        version: 19.2.3(react@19.2.3)
+      react-router:
+        specifier: 7.11.0
+        version: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      sqlocal:
+        specifier: ^0.16.0
+        version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3))
       zod:
-        specifier: ^4.2.1
-        version: 4.2.1
+        specifier: ^4.3.2
+        version: 4.3.2
     devDependencies:
       '@biomejs/biome':
         specifier: ^2.3.10
         version: 2.3.10
+      '@react-router/dev':
+        specifier: 7.11.0
+        version: 7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
+      '@tailwindcss/vite':
+        specifier: ^4.1.18
+        version: 4.1.18(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
       '@types/node':
-        specifier: ^25.0.3
-        version: 25.0.3
+        specifier: ^22
+        version: 22.19.3
+      '@types/react':
+        specifier: ^19.2.7
+        version: 19.2.7
+      '@types/react-dom':
+        specifier: ^19.2.3
+        version: 19.2.3(@types/react@19.2.7)
       prettier:
         specifier: ^3.7.4
         version: 3.7.4
       prettier-plugin-organize-imports:
         specifier: ^4.3.0
         version: 4.3.0(prettier@3.7.4)(typescript@5.9.3)
-      tsx:
-        specifier: ^4.21.0
-        version: 4.21.0
+      tailwindcss:
+        specifier: ^4.1.18
+        version: 4.1.18
       typescript:
         specifier: ^5.9.3
         version: 5.9.3
+      vite:
+        specifier: ^7.3.0
+        version: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+      vite-tsconfig-paths:
+        specifier: ^6.0.3
+        version: 6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
 
-  examples/react:
+  examples/browser-vite-react:
     dependencies:
       '@coji/durably':
         specifier: workspace:*
@@ -116,7 +149,7 @@ importers:
         specifier: ^7.3.0
         version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
 
-  examples/react-router:
+  examples/fullstack-react-router:
     dependencies:
       '@coji/durably':
         specifier: workspace:*
@@ -186,6 +219,43 @@ importers:
         specifier: ^6.0.3
         version: 6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
 
+  examples/server-node:
+    dependencies:
+      '@coji/durably':
+        specifier: workspace:*
+        version: link:../../packages/durably
+      '@libsql/client':
+        specifier: ^0.15.15
+        version: 0.15.15
+      '@libsql/kysely-libsql':
+        specifier: ^0.4.1
+        version: 0.4.1(kysely@0.28.9)
+      kysely:
+        specifier: ^0.28.9
+        version: 0.28.9
+      zod:
+        specifier: ^4.2.1
+        version: 4.2.1
+    devDependencies:
+      '@biomejs/biome':
+        specifier: ^2.3.10
+        version: 2.3.10
+      '@types/node':
+        specifier: ^25.0.3
+        version: 25.0.3
+      prettier:
+        specifier: ^3.7.4
+        version: 3.7.4
+      prettier-plugin-organize-imports:
+        specifier: ^4.3.0
+        version: 4.3.0(prettier@3.7.4)(typescript@5.9.3)
+      tsx:
+        specifier: ^4.21.0
+        version: 4.21.0
+      typescript:
+        specifier: ^5.9.3
+        version: 5.9.3
+
   packages/durably:
     dependencies:
       ulidx:
@@ -1544,6 +1614,9 @@ packages:
   '@types/mdurl@2.0.0':
     resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==}
 
+  '@types/node@22.19.3':
+    resolution: {integrity: sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==}
+
   '@types/node@25.0.3':
     resolution: {integrity: sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==}
 
@@ -2995,6 +3068,9 @@ packages:
     resolution: {integrity: sha512-xY7c8LPyzvhvew0Fn+Ek3wBC9STZAuDI/Y5andCKi9AX6/jvfaX45PhsDX8oxgPL0YFp0Jhr8qWMbS/p9375Xg==}
     engines: {node: '>=16'}
 
+  undici-types@6.21.0:
+    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
+
   undici-types@7.16.0:
     resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
 
@@ -3237,6 +3313,9 @@ packages:
   zod@4.2.1:
     resolution: {integrity: sha512-0wZ1IRqGGhMP76gLqz8EyfBXKk0J2qo2+H3fi4mcUP/KtTocoX08nmIAHl1Z2kJIZbZee8KOpBCSNPRgauucjw==}
 
+  zod@4.3.2:
+    resolution: {integrity: sha512-b8L8yn4rIVfiXyHAmnr52/ZEpDumlT0bmxiq3Ws1ybrinhflGpt12Hvv54kYnEsGPRs6o/Ka3/ppA2OWY21IVg==}
+
   zwitch@2.0.4:
     resolution: {integrity: sha512-bXE4cR/kVZhKZX/RjPEflHaKVhUVl85noU3v6b8apfQEc1x4A+zBxjZ4lN8LqGd6WZ3dl98pY4o717VFmoPp+A==}
 
@@ -3356,9 +3435,9 @@ snapshots:
     dependencies:
       '@algolia/client-common': 5.46.1
 
-  '@anthropic-ai/claude-agent-sdk@0.1.70(zod@4.2.1)':
+  '@anthropic-ai/claude-agent-sdk@0.1.70(zod@4.3.2)':
     dependencies:
-      zod: 4.2.1
+      zod: 4.3.2
     optionalDependencies:
       '@img/sharp-darwin-arm64': 0.33.5
       '@img/sharp-darwin-x64': 0.33.5
@@ -4023,6 +4102,56 @@ snapshots:
 
   '@polka/url@1.0.0-next.29': {}
 
+  '@react-router/dev@7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
+    dependencies:
+      '@babel/core': 7.28.5
+      '@babel/generator': 7.28.5
+      '@babel/parser': 7.28.5
+      '@babel/plugin-syntax-jsx': 7.27.1(@babel/core@7.28.5)
+      '@babel/preset-typescript': 7.28.5(@babel/core@7.28.5)
+      '@babel/traverse': 7.28.5
+      '@babel/types': 7.28.5
+      '@react-router/node': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)
+      '@remix-run/node-fetch-server': 0.9.0
+      arg: 5.0.2
+      babel-dead-code-elimination: 1.0.11
+      chokidar: 4.0.3
+      dedent: 1.7.1
+      es-module-lexer: 1.7.0
+      exit-hook: 2.2.1
+      isbot: 5.1.32
+      jsesc: 3.0.2
+      lodash: 4.17.21
+      p-map: 7.0.4
+      pathe: 1.1.2
+      picocolors: 1.1.1
+      pkg-types: 2.3.0
+      prettier: 3.7.4
+      react-refresh: 0.14.2
+      react-router: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
+      semver: 7.7.3
+      tinyglobby: 0.2.15
+      valibot: 1.2.0(typescript@5.9.3)
+      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+      vite-node: 3.2.4(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+    optionalDependencies:
+      '@react-router/serve': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)
+      typescript: 5.9.3
+    transitivePeerDependencies:
+      - '@types/node'
+      - babel-plugin-macros
+      - jiti
+      - less
+      - lightningcss
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+      - tsx
+      - yaml
+
   '@react-router/dev@7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
     dependencies:
       '@babel/core': 7.28.5
@@ -4278,6 +4407,13 @@ snapshots:
       '@tailwindcss/oxide-win32-arm64-msvc': 4.1.18
       '@tailwindcss/oxide-win32-x64-msvc': 4.1.18
 
+  '@tailwindcss/vite@4.1.18(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
+    dependencies:
+      '@tailwindcss/node': 4.1.18
+      '@tailwindcss/oxide': 4.1.18
+      tailwindcss: 4.1.18
+      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+
   '@tailwindcss/vite@4.1.18(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
     dependencies:
       '@tailwindcss/node': 4.1.18
@@ -4355,6 +4491,10 @@ snapshots:
 
   '@types/mdurl@2.0.0': {}
 
+  '@types/node@22.19.3':
+    dependencies:
+      undici-types: 6.21.0
+
   '@types/node@25.0.3':
     dependencies:
       undici-types: 7.16.0
@@ -4700,9 +4840,9 @@ snapshots:
 
   caniuse-lite@1.0.30001762: {}
 
-  cc-hooks-ts@2.0.70(typescript@5.9.3)(zod@4.2.1):
+  cc-hooks-ts@2.0.70(typescript@5.9.3)(zod@4.3.2):
     dependencies:
-      '@anthropic-ai/claude-agent-sdk': 0.1.70(zod@4.2.1)
+      '@anthropic-ai/claude-agent-sdk': 0.1.70(zod@4.3.2)
       valibot: 1.2.0(typescript@5.9.3)
     transitivePeerDependencies:
       - typescript
@@ -5701,6 +5841,19 @@ snapshots:
 
   speakingurl@14.0.1: {}
 
+  sqlocal@0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)):
+    dependencies:
+      '@sqlite.org/sqlite-wasm': 3.50.4-build1
+      coincident: 1.2.3
+    optionalDependencies:
+      kysely: 0.28.9
+      react: 19.2.3
+      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+      vue: 3.5.26(typescript@5.9.3)
+    transitivePeerDependencies:
+      - bufferutil
+      - utf-8-validate
+
   sqlocal@0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)):
     dependencies:
       '@sqlite.org/sqlite-wasm': 3.50.4-build1
@@ -5875,6 +6028,8 @@ snapshots:
     dependencies:
       layerr: 3.0.0
 
+  undici-types@6.21.0: {}
+
   undici-types@7.16.0: {}
 
   unist-util-is@6.0.1:
@@ -5926,6 +6081,27 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
+  vite-node@3.2.4(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
+    dependencies:
+      cac: 6.7.14
+      debug: 4.4.3
+      es-module-lexer: 1.7.0
+      pathe: 2.0.3
+      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+    transitivePeerDependencies:
+      - '@types/node'
+      - jiti
+      - less
+      - lightningcss
+      - sass
+      - sass-embedded
+      - stylus
+      - sugarss
+      - supports-color
+      - terser
+      - tsx
+      - yaml
+
   vite-node@3.2.4(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
     dependencies:
       cac: 6.7.14
@@ -5947,6 +6123,17 @@ snapshots:
       - tsx
       - yaml
 
+  vite-tsconfig-paths@6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)):
+    dependencies:
+      debug: 4.4.3
+      globrex: 0.1.2
+      tsconfck: 3.1.6(typescript@5.9.3)
+    optionalDependencies:
+      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+    transitivePeerDependencies:
+      - supports-color
+      - typescript
+
   vite-tsconfig-paths@6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)):
     dependencies:
       debug: 4.4.3
@@ -5968,6 +6155,21 @@ snapshots:
       fsevents: 2.3.3
       lightningcss: 1.30.2
 
+  vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
+    dependencies:
+      esbuild: 0.27.2
+      fdir: 6.5.0(picomatch@4.0.3)
+      picomatch: 4.0.3
+      postcss: 8.5.6
+      rollup: 4.54.0
+      tinyglobby: 0.2.15
+    optionalDependencies:
+      '@types/node': 22.19.3
+      fsevents: 2.3.3
+      jiti: 2.6.1
+      lightningcss: 1.30.2
+      tsx: 4.21.0
+
   vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
     dependencies:
       esbuild: 0.27.2
@@ -6115,4 +6317,6 @@ snapshots:
 
   zod@4.2.1: {}
 
+  zod@4.3.2: {}
+
   zwitch@2.0.4: {}

From a1cae7e518d5b37d25c8558e7873ce57a70639e6 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 18:09:17 +0900
Subject: [PATCH 064/101] fix(example): add comment for sqlocal instance in SPA
 example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-react-router-spa/app/routes/_index.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/examples/browser-react-router-spa/app/routes/_index.tsx b/examples/browser-react-router-spa/app/routes/_index.tsx
index c1307365..7c8889fd 100644
--- a/examples/browser-react-router-spa/app/routes/_index.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index.tsx
@@ -15,6 +15,7 @@ import { SQLocalKysely } from 'sqlocal/kysely'
 import { dataSyncJob, processImageJob } from '~/lib/jobs'
 import { Dashboard } from './_index/dashboard'
 
+// Same database as root.tsx - for reset functionality
 const sqlocal = new SQLocalKysely('example.sqlite3')
 
 export default function Index() {

From f3d81bc3a552dc1fe2b98a53a2c10e887de0bc86 Mon Sep 17 00:00:00 2001
From: coji 
Date: Wed, 31 Dec 2025 18:10:38 +0900
Subject: [PATCH 065/101] fix(example): fix unknown type check for output in
 SPA example
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-react-router-spa/app/routes/_index.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/browser-react-router-spa/app/routes/_index.tsx b/examples/browser-react-router-spa/app/routes/_index.tsx
index 7c8889fd..7e7eb4c4 100644
--- a/examples/browser-react-router-spa/app/routes/_index.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index.tsx
@@ -283,7 +283,7 @@ function JobPanel({
             
    
           )}
 
-          {output && (
+          {output !== null && output !== undefined && (
             
    
               
    
                 Output

From 34eeb144bcf4fd841fd7a97d016c1acd1cf00134 Mon Sep 17 00:00:00 2001
From: coji 
Date: Thu, 1 Jan 2026 00:33:27 +0900
Subject: [PATCH 066/101] refactor(durably-react): simplify DurablyProvider to
 accept durably prop only
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Remove dialectFactory mode from DurablyProvider. The provider now only accepts
a pre-created Durably instance via the durably prop. This simplifies the API
and moves StrictMode handling to the application layer via singleton pattern.

- Remove dialectFactory, options, and autoMigrate props from DurablyProvider
- Update browser-vite-react example to use getDurably() singleton pattern
- Update browser-react-router-spa example with clientLoader/clientAction
- Add createTestDurably() helper for tests
- Update all browser tests to use new pattern

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-react-router-spa/README.md   |  14 +-
 .../app/lib/durably.ts                        |  84 ++++
 .../browser-react-router-spa/app/root.tsx     |  31 +-
 .../app/routes/_index.tsx                     | 397 +++++-------------
 .../app/routes/_index/data-sync-form.tsx      |  47 +++
 .../app/routes/_index/data-sync-progress.tsx  |  40 ++
 .../routes/_index/image-processing-form.tsx   |  64 +++
 .../_index/image-processing-progress.tsx      |  40 ++
 .../app/routes/_index/run-progress.tsx        | 113 +++++
 examples/browser-react-router-spa/biome.json  |  17 +-
 .../browser-react-router-spa/package.json     |   8 +-
 .../browser-react-router-spa/vite.config.ts   |   2 +-
 examples/browser-vite-react/src/App.tsx       |  49 ++-
 examples/browser-vite-react/src/durably.ts    |  49 +++
 packages/durably-react/src/context.tsx        | 107 +----
 packages/durably-react/src/index.ts           |   2 +-
 .../tests/browser/provider.test.tsx           | 154 +++----
 .../tests/browser/use-job-logs.test.tsx       |  85 ++--
 .../tests/browser/use-job-run.test.tsx        | 105 ++---
 .../tests/browser/use-job.test.tsx            |  88 ++--
 .../tests/browser/use-runs.test.tsx           |  69 +--
 .../tests/helpers/create-test-durably.ts      |  29 ++
 pnpm-lock.yaml                                | 145 +------
 23 files changed, 902 insertions(+), 837 deletions(-)
 create mode 100644 examples/browser-react-router-spa/app/lib/durably.ts
 create mode 100644 examples/browser-react-router-spa/app/routes/_index/data-sync-form.tsx
 create mode 100644 examples/browser-react-router-spa/app/routes/_index/data-sync-progress.tsx
 create mode 100644 examples/browser-react-router-spa/app/routes/_index/image-processing-form.tsx
 create mode 100644 examples/browser-react-router-spa/app/routes/_index/image-processing-progress.tsx
 create mode 100644 examples/browser-react-router-spa/app/routes/_index/run-progress.tsx
 create mode 100644 examples/browser-vite-react/src/durably.ts
 create mode 100644 packages/durably-react/tests/helpers/create-test-durably.ts

diff --git a/examples/browser-react-router-spa/README.md b/examples/browser-react-router-spa/README.md
index b63d552a..df518cb3 100644
--- a/examples/browser-react-router-spa/README.md
+++ b/examples/browser-react-router-spa/README.md
@@ -55,13 +55,13 @@ app/
 
 ## Key Differences from Fullstack Mode
 
-| Aspect | Browser-Only (SPA) | Fullstack (SSR) |
-|--------|-------------------|-----------------|
-| Database | SQLite WASM + OPFS | libsql/better-sqlite3 |
-| Provider | `DurablyProvider` | No provider needed |
-| Hooks | `useJob(jobDefinition)` | `durably.jobName.useJob()` |
-| Data | Stays in browser | Server-side storage |
-| Offline | Works offline | Requires server |
+| Aspect   | Browser-Only (SPA)      | Fullstack (SSR)            |
+| -------- | ----------------------- | -------------------------- |
+| Database | SQLite WASM + OPFS      | libsql/better-sqlite3      |
+| Provider | `DurablyProvider`       | No provider needed         |
+| Hooks    | `useJob(jobDefinition)` | `durably.jobName.useJob()` |
+| Data     | Stays in browser        | Server-side storage        |
+| Offline  | Works offline           | Requires server            |
 
 ## Try It
 
diff --git a/examples/browser-react-router-spa/app/lib/durably.ts b/examples/browser-react-router-spa/app/lib/durably.ts
new file mode 100644
index 00000000..b806b292
--- /dev/null
+++ b/examples/browser-react-router-spa/app/lib/durably.ts
@@ -0,0 +1,84 @@
+/**
+ * Durably instance for browser-only mode
+ *
+ * This creates a singleton Durably instance that can be used
+ * both by DurablyProvider and by clientAction for triggering jobs.
+ *
+ * IMPORTANT: Job definitions are exported from here to ensure the same
+ * object references are used throughout the app. This prevents
+ * "already registered with a different definition" errors.
+ */
+
+import { createDurably, type Durably } from '@coji/durably'
+import { SQLocalKysely } from 'sqlocal/kysely'
+import { dataSyncJob, processImageJob } from './jobs'
+
+// Re-export job definitions to ensure consistent object references
+export { dataSyncJob, processImageJob }
+
+// SQLocal instance for SQLite WASM with OPFS
+export const sqlocal = new SQLocalKysely('example.sqlite3')
+
+// Singleton Durably instance (lazily initialized)
+let durablyInstance: Durably | null = null
+let durablyPromise: Promise | null = null
+
+/**
+ * Get the shared Durably instance.
+ * Creates and migrates on first call, returns cached instance thereafter.
+ */
+export async function getDurably(): Promise {
+  if (durablyInstance) {
+    return durablyInstance
+  }
+
+  if (!durablyPromise) {
+    durablyPromise = (async () => {
+      const instance = createDurably({
+        dialect: sqlocal.dialect,
+        pollingInterval: 100,
+        heartbeatInterval: 500,
+        staleThreshold: 3000,
+      })
+      await instance.migrate()
+
+      // Pre-register jobs immediately after migration
+      // This ensures they're registered before any component tries to use them
+      instance.register({
+        processImage: processImageJob,
+        dataSync: dataSyncJob,
+      })
+
+      durablyInstance = instance
+      return instance
+    })()
+  }
+
+  return durablyPromise
+}
+
+/**
+ * Trigger a job by name.
+ * This uses the shared durably instance and its registered jobs.
+ */
+export async function triggerJob(
+  jobName: 'processImage',
+  payload: T,
+): Promise<{ id: string }>
+export async function triggerJob(
+  jobName: 'dataSync',
+  payload: T,
+): Promise<{ id: string }>
+export async function triggerJob(
+  jobName: 'processImage' | 'dataSync',
+  payload: Record,
+): Promise<{ id: string }> {
+  const durably = await getDurably()
+  const jobHandle = durably.getJob(
+    jobName === 'processImage' ? 'process-image' : 'data-sync',
+  )
+  if (!jobHandle) {
+    throw new Error(`Job ${jobName} not found`)
+  }
+  return jobHandle.trigger(payload)
+}
diff --git a/examples/browser-react-router-spa/app/root.tsx b/examples/browser-react-router-spa/app/root.tsx
index 4dab506e..18998443 100644
--- a/examples/browser-react-router-spa/app/root.tsx
+++ b/examples/browser-react-router-spa/app/root.tsx
@@ -7,12 +7,9 @@ import {
   Scripts,
   ScrollRestoration,
 } from 'react-router'
-import { SQLocalKysely } from 'sqlocal/kysely'
 import type { Route } from './+types/root'
 import './app.css'
-
-// SQLocal instance for SQLite WASM with OPFS
-const sqlocal = new SQLocalKysely('example.sqlite3')
+import { getDurably } from './lib/durably'
 
 export function links() {
   return [
@@ -29,6 +26,21 @@ export function links() {
   ]
 }
 
+// clientLoader: Get shared durably instance
+export async function clientLoader() {
+  const durably = await getDurably()
+  return { durably }
+}
+
+// HydrateFallback: Show while clientLoader is running
+export function HydrateFallback() {
+  return (
+    
    
+      
    Loading...
    
+    
    
+  )
+}
+
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
     
@@ -47,16 +59,9 @@ export function Layout({ children }: { children: React.ReactNode }) {
   )
 }
 
-export default function App() {
+export default function App({ loaderData }: Route.ComponentProps) {
   return (
-     sqlocal.dialect}
-      options={{
-        pollingInterval: 100,
-        heartbeatInterval: 500,
-        staleThreshold: 3000,
-      }}
-    >
+    
       
     
   )
diff --git a/examples/browser-react-router-spa/app/routes/_index.tsx b/examples/browser-react-router-spa/app/routes/_index.tsx
index 7e7eb4c4..076075cc 100644
--- a/examples/browser-react-router-spa/app/routes/_index.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index.tsx
@@ -5,104 +5,137 @@
  * - React Router v7 in SPA mode (ssr: false)
  * - SQLite WASM with OPFS for browser-only persistence
  * - DurablyProvider for context and lifecycle management
- * - useJob hook for triggering and monitoring jobs
+ * - clientAction for Form-based job triggering (direct trigger in action)
+ * - useJob hook with initialRunId for monitoring jobs
  */
 
-import { useDurably, useJob, type LogEntry } from '@coji/durably-react'
 import { useState } from 'react'
-import { Link } from 'react-router'
-import { SQLocalKysely } from 'sqlocal/kysely'
-import { dataSyncJob, processImageJob } from '~/lib/jobs'
+import { getDurably, sqlocal, triggerJob } from '~/lib/durably'
 import { Dashboard } from './_index/dashboard'
+import { DataSyncForm } from './_index/data-sync-form'
+import { DataSyncProgress } from './_index/data-sync-progress'
+import { ImageProcessingForm } from './_index/image-processing-form'
+import { ImageProcessingProgress } from './_index/image-processing-progress'
+
+export function meta() {
+  return [
+    { title: 'Durably - Browser-Only SPA' },
+    { name: 'description', content: 'Browser-only job processing with OPFS' },
+  ]
+}
+
+// clientAction: Trigger jobs directly in SPA mode
+export async function clientAction({ request }: { request: Request }) {
+  const formData = await request.formData()
+  const intent = formData.get('intent') as string
+
+  if (intent === 'image') {
+    const filename = formData.get('filename') as string
+    const width = Number(formData.get('width'))
+    const run = await triggerJob('processImage', { filename, width })
+    return { intent: 'image', runId: run.id }
+  }
 
-// Same database as root.tsx - for reset functionality
-const sqlocal = new SQLocalKysely('example.sqlite3')
+  if (intent === 'sync') {
+    const userId = formData.get('userId') as string
+    const run = await triggerJob('dataSync', { userId })
+    return { intent: 'sync', runId: run.id }
+  }
+
+  return null
+}
 
 export default function Index() {
-  const [activeTab, setActiveTab] = useState<'image' | 'sync'>('image')
-  const { durably } = useDurably()
+  const [activeJob, setActiveJob] = useState<'image' | 'sync'>('image')
 
   const handleReset = async () => {
-    if (durably) {
-      await durably.stop()
-    }
+    const durably = await getDurably()
+    await durably.stop()
     await sqlocal.deleteDatabaseFile()
     location.reload()
   }
 
   return (
-    
    
-      
    
+    
    
+      
    
         
    
-          
    
+          
    
             Durably - Browser-Only SPA
           
    
-          
    
-            React Router v7 SPA mode with SQLite WASM + OPFS
+          
    
+            React Router v7 SPA mode with clientAction + Form
           
    
-          
    
-            
-              GitHub
-            
-            |
-            
-              Source Code
-            
-          
    
         
    
 
-        
    
-          
    
-            
-            
-            
    
-            
-            
+        
    
+          {/* Left: Job Trigger + Progress */}
+          
    
+            {/* Job Selection */}
+            
    
+              
    
+                
    Run Job
    
+                
    
+                  
+                  
+                
    
+              
    
+
+              
    
+                
+                
+              
    
+
+              {activeJob === 'image' ? (
+                
+              ) : (
+                
+              )}
+            
    
+
+            {/* Progress Display */}
+            {activeJob === 'image' ? (
+              
+            ) : (
+              
+            )}
           
    
 
-          {activeTab === 'image' ?  : }
+          {/* Right: Dashboard */}
+          
         
    
 
-        
-
         
    
           
    
             All data is stored locally in your browser using SQLite WASM with
@@ -117,219 +150,3 @@ export default function Index() {
     
    
   )
 }
-
-function ImageProcessingPanel() {
-  const {
-    trigger,
-    output,
-    error,
-    progress,
-    logs,
-    isReady,
-    isPending,
-    isRunning,
-    isCompleted,
-    isFailed,
-  } = useJob(processImageJob)
-
-  const handleRun = async () => {
-    await trigger({ filename: 'photo.jpg', width: 800 })
-  }
-
-  return (
-    
-  )
-}
-
-function DataSyncPanel() {
-  const {
-    trigger,
-    output,
-    error,
-    progress,
-    logs,
-    isReady,
-    isPending,
-    isRunning,
-    isCompleted,
-    isFailed,
-  } = useJob(dataSyncJob)
-
-  const handleRun = async () => {
-    await trigger({ userId: 'user_123' })
-  }
-
-  return (
-    
-  )
-}
-
-interface JobPanelProps {
-  title: string
-  description: string
-  onRun: () => void
-  isReady: boolean
-  isPending: boolean
-  isRunning: boolean
-  isCompleted: boolean
-  isFailed: boolean
-  progress: { current: number; total?: number; message?: string } | null
-  output: unknown
-  error: string | null
-  logs: LogEntry[]
-}
-
-function JobPanel({
-  title,
-  description,
-  onRun,
-  isReady,
-  isPending,
-  isRunning,
-  isCompleted,
-  isFailed,
-  progress,
-  output,
-  error,
-  logs,
-}: JobPanelProps) {
-  const statusText = isRunning
-    ? 'Running...'
-    : isCompleted
-      ? '✓ Completed'
-      : isFailed
-        ? '✗ Failed'
-        : isPending
-          ? 'Pending...'
-          : isReady
-            ? 'Ready'
-            : 'Initializing...'
-
-  const statusColor = isCompleted
-    ? 'text-green-600'
-    : isFailed
-      ? 'text-red-600'
-      : isRunning
-        ? 'text-blue-600'
-        : 'text-gray-600'
-
-  return (
-    
    
-      
    
-        
    
-          
    {title}
    
-          
    {description}
    
-        
    
-        
-      
    
-
-      
    
-        
    
-          
    
-            Status: 
-            {statusText}
-          
    
-
-          {progress && (
-            
    
-              
    
-                {progress.message}
-                
-                  {progress.current}
-                  {progress.total ? `/${progress.total}` : ''}
-                
-              
    
-              
    
-                
    
-              
    
-            
    
-          )}
-
-          {output !== null && output !== undefined && (
-            
    
-              
    
-                Output
-              
    
-              
    -                {JSON.stringify(output, null, 2)}
-              
    
-            
    
-          )}
-
-          {error && (
-            
    
-              
    Error
    
-              
    {error}
    
-            
    
-          )}
-        
    
-
-        
    
-          {logs.length > 0 && (
-            
    
-              
    Logs
    
-              
    
-                
      
-                  {logs.map((log) => (
-                    
    • 
-                      
-                        [{log.level}]
-                      {' '}
-                      {log.message}
-                    
      • 
-                  ))}
-                
    
-              
    
-            
    
-          )}
-        
    
-      
    
-    
    
-  )
-}
diff --git a/examples/browser-react-router-spa/app/routes/_index/data-sync-form.tsx b/examples/browser-react-router-spa/app/routes/_index/data-sync-form.tsx
new file mode 100644
index 00000000..fec71898
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index/data-sync-form.tsx
@@ -0,0 +1,47 @@
+/**
+ * Data Sync Form Component
+ *
+ * Form for triggering data sync jobs via clientAction.
+ */
+
+import { Form, useActionData, useNavigation } from 'react-router'
+import type { clientAction } from '../_index'
+
+export function DataSyncForm() {
+  const actionData = useActionData()
+  const navigation = useNavigation()
+  const isSubmitting = navigation.state === 'submitting'
+  const runId = actionData?.intent === 'sync' ? actionData.runId : null
+
+  return (
+    
    
+      
+      
    
+        
+        
+      
    
+      
+      {runId && (
+        
    
+          Triggered: {runId.slice(0, 8)}
+        
    
+      )}
+    
    
+  )
+}
diff --git a/examples/browser-react-router-spa/app/routes/_index/data-sync-progress.tsx b/examples/browser-react-router-spa/app/routes/_index/data-sync-progress.tsx
new file mode 100644
index 00000000..6a31eeb5
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index/data-sync-progress.tsx
@@ -0,0 +1,40 @@
+/**
+ * Data Sync Progress Component
+ *
+ * Displays progress for the data sync job using initialRunId.
+ */
+
+import { useJob } from '@coji/durably-react'
+import { useActionData } from 'react-router'
+import { dataSyncJob } from '~/lib/durably'
+import type { clientAction } from '../_index'
+import { RunProgress } from './run-progress'
+
+export function DataSyncProgress() {
+  const actionData = useActionData()
+  const runId = actionData?.intent === 'sync' ? actionData.runId : undefined
+
+  const {
+    progress,
+    output,
+    error,
+    logs,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJob(dataSyncJob, { initialRunId: runId })
+
+  return (
+    
+  )
+}
diff --git a/examples/browser-react-router-spa/app/routes/_index/image-processing-form.tsx b/examples/browser-react-router-spa/app/routes/_index/image-processing-form.tsx
new file mode 100644
index 00000000..2e877417
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index/image-processing-form.tsx
@@ -0,0 +1,64 @@
+/**
+ * Image Processing Form Component
+ *
+ * Form for triggering image processing jobs via clientAction.
+ */
+
+import { Form, useActionData, useNavigation } from 'react-router'
+import type { clientAction } from '../_index'
+
+export function ImageProcessingForm() {
+  const actionData = useActionData()
+  const navigation = useNavigation()
+  const isSubmitting = navigation.state === 'submitting'
+  const runId = actionData?.intent === 'image' ? actionData.runId : null
+
+  return (
+    
    
+      
+      
    
+        
+        
+      
    
+      
    
+        
+        
+      
    
+      
+      {runId && (
+        
    
+          Triggered: {runId.slice(0, 8)}
+        
    
+      )}
+    
    
+  )
+}
diff --git a/examples/browser-react-router-spa/app/routes/_index/image-processing-progress.tsx b/examples/browser-react-router-spa/app/routes/_index/image-processing-progress.tsx
new file mode 100644
index 00000000..2dc686f2
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index/image-processing-progress.tsx
@@ -0,0 +1,40 @@
+/**
+ * Image Processing Progress Component
+ *
+ * Displays progress for the image processing job using initialRunId.
+ */
+
+import { useJob } from '@coji/durably-react'
+import { useActionData } from 'react-router'
+import { processImageJob } from '~/lib/durably'
+import type { clientAction } from '../_index'
+import { RunProgress } from './run-progress'
+
+export function ImageProcessingProgress() {
+  const actionData = useActionData()
+  const runId = actionData?.intent === 'image' ? actionData.runId : undefined
+
+  const {
+    progress,
+    output,
+    error,
+    logs,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJob(processImageJob, { initialRunId: runId })
+
+  return (
+    
+  )
+}
diff --git a/examples/browser-react-router-spa/app/routes/_index/run-progress.tsx b/examples/browser-react-router-spa/app/routes/_index/run-progress.tsx
new file mode 100644
index 00000000..55f5f094
--- /dev/null
+++ b/examples/browser-react-router-spa/app/routes/_index/run-progress.tsx
@@ -0,0 +1,113 @@
+/**
+ * RunProgress Component
+ *
+ * Displays real-time progress and result for browser-only jobs.
+ */
+
+import type { LogEntry } from '@coji/durably-react'
+
+interface RunProgressProps {
+  progress: { current: number; total?: number; message?: string } | null
+  output: unknown
+  error: string | null
+  logs: LogEntry[]
+  isPending: boolean
+  isRunning: boolean
+  isCompleted: boolean
+  isFailed: boolean
+}
+
+export function RunProgress({
+  progress,
+  output,
+  error,
+  logs,
+  isPending,
+  isRunning,
+  isCompleted,
+  isFailed,
+}: RunProgressProps) {
+  // Don't render anything if no activity
+  if (!isPending && !isRunning && !isCompleted && !isFailed) {
+    return null
+  }
+
+  return (
+    <>
+      {/* Pending State */}
+      {isPending && (
+        
    
+          
    Waiting to start...
    
+        
    
+      )}
+
+      {/* Progress Display */}
+      {isRunning && progress && (
+        
    
+          
    
+            Progress
+            
+              {progress.current}/{progress.total || '?'}
+            
+          
    
+          
    
+            
    
+          
    
+          {progress.message && (
+            
    {progress.message}
    
+          )}
+        
    
+      )}
+
+      {/* Success Result */}
+      {isCompleted && output !== null && output !== undefined && (
+        
    
+          
    Completed!
    
+          
    +            {JSON.stringify(output, null, 2)}
+          
    
+        
    
+      )}
+
+      {/* Error Result */}
+      {isFailed && (
+        
    
+          
    Failed
    
+          
    {error}
    
+        
    
+      )}
+
+      {/* Logs */}
+      {logs.length > 0 && (
+        
    
+          
    Logs
    
+          
    
+            
      
+              {logs.map((log) => (
+                
    • 
+                  
+                    [{log.level}]
+                  {' '}
+                  {log.message}
+                
      • 
+              ))}
+            
    
+          
    
+        
    
+      )}
+    
+  )
+}
diff --git a/examples/browser-react-router-spa/biome.json b/examples/browser-react-router-spa/biome.json
index 285e2ef8..cb0ac4d9 100644
--- a/examples/browser-react-router-spa/biome.json
+++ b/examples/browser-react-router-spa/biome.json
@@ -1,13 +1,10 @@
 {
-  "$schema": "https://biomejs.dev/schemas/2.0.5/schema.json",
-  "vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
-  "formatter": { "enabled": false },
-  "linter": {
-    "enabled": true,
-    "rules": { "recommended": true }
-  },
-  "organizeImports": { "enabled": false },
-  "javascript": {
-    "globals": []
+  "$schema": "https://biomejs.dev/schemas/2.3.10/schema.json",
+  "extends": ["../../biome.json"],
+  "css": {
+    "parser": {
+      "cssModules": true,
+      "tailwindDirectives": true
+    }
   }
 }
diff --git a/examples/browser-react-router-spa/package.json b/examples/browser-react-router-spa/package.json
index 624217d5..78335a37 100644
--- a/examples/browser-react-router-spa/package.json
+++ b/examples/browser-react-router-spa/package.json
@@ -6,7 +6,7 @@
     "build": "react-router build",
     "dev": "react-router dev",
     "preview": "vite preview",
-    "typecheck": "echo 'Run pnpm dev first to generate types' && tsc",
+    "typecheck": "react-router typegen && tsc",
     "lint": "biome lint .",
     "lint:fix": "biome lint --write .",
     "format": "prettier --experimental-cli --check .",
@@ -16,19 +16,19 @@
     "@coji/durably": "workspace:*",
     "@coji/durably-react": "workspace:*",
     "@react-router/node": "7.11.0",
+    "isbot": "^5.1.32",
     "kysely": "^0.28.9",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-router": "7.11.0",
     "sqlocal": "^0.16.0",
-    "zod": "^4.3.2",
-    "isbot": "^5"
+    "zod": "^4.3.2"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
     "@react-router/dev": "7.11.0",
-    "@types/node": "^22",
     "@tailwindcss/vite": "^4.1.18",
+    "@types/node": "^25.0.3",
     "@types/react": "^19.2.7",
     "@types/react-dom": "^19.2.3",
     "prettier": "^3.7.4",
diff --git a/examples/browser-react-router-spa/vite.config.ts b/examples/browser-react-router-spa/vite.config.ts
index 1df00322..204a0ec1 100644
--- a/examples/browser-react-router-spa/vite.config.ts
+++ b/examples/browser-react-router-spa/vite.config.ts
@@ -1,5 +1,5 @@
-import tailwindcss from '@tailwindcss/vite'
 import { reactRouter } from '@react-router/dev/vite'
+import tailwindcss from '@tailwindcss/vite'
 import { defineConfig } from 'vite'
 import tsconfigPaths from 'vite-tsconfig-paths'
 
diff --git a/examples/browser-vite-react/src/App.tsx b/examples/browser-vite-react/src/App.tsx
index c4eb6948..e32b2bc5 100644
--- a/examples/browser-vite-react/src/App.tsx
+++ b/examples/browser-vite-react/src/App.tsx
@@ -7,33 +7,22 @@
  * - useDurably hook for direct Durably access
  */
 
+import type { Durably } from '@coji/durably'
 import {
   DurablyProvider,
   useDurably,
   useJob,
   type LogEntry,
 } from '@coji/durably-react'
-import { useState } from 'react'
-import { SQLocalKysely } from 'sqlocal/kysely'
+import { useEffect, useState } from 'react'
 import { Dashboard } from './Dashboard'
-import { processImageJob } from './jobs/processImage'
+import { getDurably, processImageJob, sqlocal } from './durably'
 import { styles } from './styles'
 
 // Links
 const GITHUB_REPO = 'https://github.com/coji/durably'
 const SOURCE_CODE = `${GITHUB_REPO}/tree/main/examples/react`
 
-// SQLocal instance for database operations
-const sqlocal = new SQLocalKysely('example.sqlite3')
-
-// Durably configuration
-const dialectFactory = () => sqlocal.dialect
-const durablyOptions = {
-  pollingInterval: 100,
-  heartbeatInterval: 500,
-  staleThreshold: 3000,
-}
-
 function AppContent() {
   const [showInfo, setShowInfo] = useState(false)
   const { durably } = useDurably()
@@ -120,8 +109,8 @@ function AppContent() {
           
    
           
      
             
    • 
-              DurablyProvider - Context provider with auto
-              migration and worker start
+              DurablyProvider - Context provider for Durably
+              instance
             
      • 
             
    • 
               useJob - Hook for triggering jobs and real-time
@@ -199,9 +188,35 @@ function AppContent() {
   )
 }
 
+function Loading() {
+  return (
+    
      
+      Loading...
+    
      
+  )
+}
+
 export function App() {
+  const [durably, setDurably] = useState(null)
+
+  useEffect(() => {
+    getDurably().then(setDurably)
+  }, [])
+
+  if (!durably) {
+    return 
+  }
+
   return (
-    
+    
       
     
   )
diff --git a/examples/browser-vite-react/src/durably.ts b/examples/browser-vite-react/src/durably.ts
new file mode 100644
index 00000000..2b120817
--- /dev/null
+++ b/examples/browser-vite-react/src/durably.ts
@@ -0,0 +1,49 @@
+/**
+ * Durably instance for browser-only mode
+ *
+ * This creates a singleton Durably instance that is shared across the app.
+ */
+
+import { createDurably, type Durably } from '@coji/durably'
+import { SQLocalKysely } from 'sqlocal/kysely'
+import { processImageJob } from './jobs/processImage'
+
+// Re-export job definition to ensure consistent object reference
+export { processImageJob }
+
+// SQLocal instance for SQLite WASM with OPFS
+export const sqlocal = new SQLocalKysely('example.sqlite3')
+
+// Singleton Durably instance (lazily initialized)
+let durablyInstance: Durably | null = null
+let durablyPromise: Promise | null = null
+
+/**
+ * Get the shared Durably instance.
+ * Creates and migrates on first call, returns cached instance thereafter.
+ */
+export async function getDurably(): Promise {
+  if (durablyInstance) {
+    return durablyInstance
+  }
+
+  if (!durablyPromise) {
+    durablyPromise = (async () => {
+      const instance = createDurably({
+        dialect: sqlocal.dialect,
+        pollingInterval: 100,
+        heartbeatInterval: 500,
+        staleThreshold: 3000,
+      })
+      await instance.migrate()
+
+      // Pre-register jobs immediately after migration
+      instance.register({ processImage: processImageJob })
+
+      durablyInstance = instance
+      return instance
+    })()
+  }
+
+  return durablyPromise
+}
diff --git a/packages/durably-react/src/context.tsx b/packages/durably-react/src/context.tsx
index 0501f035..b03bb36b 100644
--- a/packages/durably-react/src/context.tsx
+++ b/packages/durably-react/src/context.tsx
@@ -1,5 +1,4 @@
-import { createDurably, type Durably, type DurablyOptions } from '@coji/durably'
-import type { Dialect } from 'kysely'
+import type { Durably } from '@coji/durably'
 import {
   createContext,
   useContext,
@@ -17,44 +16,27 @@ interface DurablyContextValue {
 
 const DurablyContext = createContext(null)
 
-/**
- * Options for DurablyProvider (dialect is provided separately via dialectFactory)
- */
-export type DurablyProviderOptions = Omit
-
 export interface DurablyProviderProps {
   /**
-   * Factory function to create a Kysely dialect.
-   * Called only once during initialization.
-   */
-  dialectFactory: () => Dialect
-  /**
-   * Durably options (pollingInterval, heartbeatInterval, etc.)
+   * Pre-created Durably instance.
+   * The instance should already be migrated and have jobs registered if needed.
    */
-  options?: DurablyProviderOptions
+  durably: Durably
   /**
-   * Whether to automatically call start() after initialization.
+   * Whether to automatically call start() after mounting.
    * @default true
    */
   autoStart?: boolean
-  /**
-   * Whether to automatically call migrate() during initialization.
-   * @default true
-   */
-  autoMigrate?: boolean
   /**
    * Callback when Durably instance is ready.
-   * Useful for testing to track instances.
    */
   onReady?: (durably: Durably) => void
   children: ReactNode
 }
 
 export function DurablyProvider({
-  dialectFactory,
-  options,
+  durably: externalDurably,
   autoStart = true,
-  autoMigrate = true,
   onReady,
   children,
 }: DurablyProviderProps) {
@@ -62,80 +44,23 @@ export function DurablyProvider({
   const [isReady, setIsReady] = useState(false)
   const [error, setError] = useState(null)
 
-  // Use ref to track initialization state for StrictMode safety
-  const initializedRef = useRef(false)
   const instanceRef = useRef(null)
-  const initPromiseRef = useRef | null>(null)
 
   useEffect(() => {
-    // Prevent double initialization in StrictMode
-    if (initializedRef.current) {
-      // If already initialized, wait for init to complete and use existing instance
-      if (initPromiseRef.current) {
-        initPromiseRef.current.then(() => {
-          if (instanceRef.current) {
-            setDurably(instanceRef.current)
-            setIsReady(true)
-            // Restart worker if it was stopped during unmount
-            if (autoStart) {
-              instanceRef.current.start()
-            }
-          }
-        })
-      }
-      return
-    }
-
-    initializedRef.current = true
-    let cleanedUp = false
-
-    async function init() {
-      try {
-        const dialect = dialectFactory()
-        const instance = createDurably({ dialect, ...options })
-        instanceRef.current = instance
+    try {
+      instanceRef.current = externalDurably
 
-        if (autoMigrate) {
-          await instance.migrate()
-        }
-
-        if (cleanedUp) {
-          // StrictMode unmounted us, but keep the instance for remount
-          return
-        }
-
-        if (autoStart) {
-          instance.start()
-        }
-
-        setDurably(instance)
-        setIsReady(true)
-        onReady?.(instance)
-      } catch (err) {
-        if (cleanedUp) return
-        setError(err instanceof Error ? err : new Error(String(err)))
+      if (autoStart) {
+        externalDurably.start()
       }
-    }
-
-    initPromiseRef.current = init()
 
-    return () => {
-      cleanedUp = true
-      // Don't stop the worker here - StrictMode will remount and we want to keep running
-    }
-  }, [dialectFactory, options, autoStart, autoMigrate, onReady])
-
-  // Separate cleanup effect that only runs when truly unmounting
-  // This works because React guarantees cleanup order: child effects clean up before parent
-  useEffect(() => {
-    return () => {
-      // This cleanup runs when the component is truly removed
-      // We need to stop the worker here
-      if (instanceRef.current) {
-        instanceRef.current.stop()
-      }
+      setDurably(externalDurably)
+      setIsReady(true)
+      onReady?.(externalDurably)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)))
     }
-  }, [])
+  }, [externalDurably, autoStart, onReady])
 
   return (
     
diff --git a/packages/durably-react/src/index.ts b/packages/durably-react/src/index.ts
index 43ea7d0f..3e75bb57 100644
--- a/packages/durably-react/src/index.ts
+++ b/packages/durably-react/src/index.ts
@@ -2,7 +2,7 @@
 // This entry point is for running Durably entirely in the browser with OPFS
 
 export { DurablyProvider, useDurably } from './context'
-export type { DurablyProviderOptions, DurablyProviderProps } from './context'
+export type { DurablyProviderProps } from './context'
 export { useJob } from './hooks/use-job'
 export type { UseJobOptions, UseJobResult } from './hooks/use-job'
 export { useJobLogs } from './hooks/use-job-logs'
diff --git a/packages/durably-react/tests/browser/provider.test.tsx b/packages/durably-react/tests/browser/provider.test.tsx
index feac4878..2f1d4639 100644
--- a/packages/durably-react/tests/browser/provider.test.tsx
+++ b/packages/durably-react/tests/browser/provider.test.tsx
@@ -6,10 +6,10 @@
 
 import type { Durably } from '@coji/durably'
 import { render, renderHook, waitFor } from '@testing-library/react'
-import { type ReactNode, StrictMode } from 'react'
+import { StrictMode } from 'react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { DurablyProvider, useDurably } from '../../src'
-import { createBrowserDialect } from '../helpers/browser-dialect'
+import { createTestDurably } from '../helpers/create-test-durably'
 
 describe('DurablyProvider', () => {
   // Track all instances created during tests for cleanup
@@ -27,127 +27,100 @@ describe('DurablyProvider', () => {
     await new Promise((r) => setTimeout(r, 200))
   })
 
-  // Helper to create wrapper with cleanup tracking
-  const createWrapper =
-    (options?: {
-      autoStart?: boolean
-      autoMigrate?: boolean
-      durablyOptions?: { pollingInterval?: number }
-    }) =>
-    ({ children }: { children: ReactNode }) => {
-      return (
-         createBrowserDialect()}
-          autoStart={options?.autoStart}
-          autoMigrate={options?.autoMigrate}
-          options={options?.durablyOptions}
-          onReady={(durably) => instances.push(durably)}
-        >
-          {children}
-        
-      )
-    }
-
   it('initializes Durably and provides isReady=true', async () => {
+    const durably = await createTestDurably()
+    instances.push(durably)
+
     const { result } = renderHook(() => useDurably(), {
-      wrapper: createWrapper(),
+      wrapper: ({ children }) => (
+        {children}
+      ),
     })
 
     await waitFor(() => {
       expect(result.current.isReady).toBe(true)
     })
-    expect(result.current.durably).not.toBeNull()
+    expect(result.current.durably).toBe(durably)
     expect(result.current.error).toBeNull()
   })
 
-  it('does not double-initialize in StrictMode', async () => {
-    const dialectFactory = vi.fn(() => createBrowserDialect())
+  it('works correctly in StrictMode', async () => {
+    const durably = await createTestDurably()
+    instances.push(durably)
 
     function TestComponent() {
-      const { isReady, durably } = useDurably()
-      if (durably) instances.push(durably)
-      return 
      {isReady ? 'ready' : 'loading'}
      
+      const { isReady, durably: d } = useDurably()
+      return (
+        
      
+          {isReady ? 'ready' : 'loading'}-{d ? 'has-durably' : 'no-durably'}
+        
      
+      )
     }
 
     const { getByTestId } = render(
       
-        
+        
           
         
       ,
     )
 
     await waitFor(() => {
-      expect(getByTestId('status').textContent).toBe('ready')
+      expect(getByTestId('status').textContent).toBe('ready-has-durably')
     })
-
-    // dialectFactory should only be called once even with StrictMode double mount
-    expect(dialectFactory).toHaveBeenCalledTimes(1)
   })
 
   it('respects autoStart=false', async () => {
+    const durably = await createTestDurably()
+    instances.push(durably)
+
+    // Spy on start to verify it's not called
+    const startSpy = vi.spyOn(durably, 'start')
+
     const { result } = renderHook(() => useDurably(), {
-      wrapper: createWrapper({ autoStart: false }),
+      wrapper: ({ children }) => (
+        
+          {children}
+        
+      ),
     })
 
     await waitFor(() => {
       expect(result.current.isReady).toBe(true)
     })
 
-    // Instance should exist but worker should not be running
-    expect(result.current.durably).not.toBeNull()
-    // Note: We can't easily verify start() wasn't called without mocking,
-    // but the instance should still be usable
+    expect(startSpy).not.toHaveBeenCalled()
   })
 
-  it('respects autoMigrate=false', async () => {
-    const { result } = renderHook(() => useDurably(), {
-      wrapper: createWrapper({ autoMigrate: false, autoStart: false }),
-    })
+  it('calls start() by default (autoStart=true)', async () => {
+    const durably = await createTestDurably()
+    instances.push(durably)
 
-    await waitFor(
-      () => {
-        expect(result.current.isReady).toBe(true)
-      },
-      { timeout: 1000 },
-    )
-
-    // Instance should exist but may not be migrated
-    expect(result.current.durably).not.toBeNull()
-  })
+    // Spy on start to verify it's called
+    const startSpy = vi.spyOn(durably, 'start')
 
-  it('passes options to createDurably', async () => {
     const { result } = renderHook(() => useDurably(), {
-      wrapper: createWrapper({ durablyOptions: { pollingInterval: 500 } }),
+      wrapper: ({ children }) => (
+        {children}
+      ),
     })
 
     await waitFor(() => {
       expect(result.current.isReady).toBe(true)
     })
 
-    // The durably instance should be created with custom options
-    expect(result.current.durably).not.toBeNull()
+    expect(startSpy).toHaveBeenCalled()
   })
 
-  it('calls stop() on unmount', async () => {
-    const stopSpy = vi.fn()
-    let durablyRef: Durably | null = null
+  it('calls onReady callback when ready', async () => {
+    const durably = await createTestDurably()
+    instances.push(durably)
 
-    const { result, unmount } = renderHook(() => useDurably(), {
+    const onReady = vi.fn()
+
+    const { result } = renderHook(() => useDurably(), {
       wrapper: ({ children }) => (
-         createBrowserDialect()}
-          onReady={(durably) => {
-            durablyRef = durably
-            instances.push(durably)
-            // Wrap stop to track calls
-            const originalStop = durably.stop.bind(durably)
-            durably.stop = async () => {
-              stopSpy()
-              return originalStop()
-            }
-          }}
-        >
+        
           {children}
         
       ),
@@ -157,33 +130,30 @@ describe('DurablyProvider', () => {
       expect(result.current.isReady).toBe(true)
     })
 
-    expect(durablyRef).not.toBeNull()
-
-    unmount()
-
-    // stop() should be called on unmount
-    expect(stopSpy).toHaveBeenCalled()
+    expect(onReady).toHaveBeenCalledWith(durably)
   })
 
-  it('provides error when initialization fails', async () => {
-    const failingDialectFactory = () => {
-      throw new Error('Dialect creation failed')
-    }
+  it('provides the same durably instance from useDurably', async () => {
+    const durably = await createTestDurably()
+    instances.push(durably)
 
     const { result } = renderHook(() => useDurably(), {
       wrapper: ({ children }) => (
-        
-          {children}
-        
+        {children}
       ),
     })
 
     await waitFor(() => {
-      expect(result.current.error).not.toBeNull()
+      expect(result.current.isReady).toBe(true)
     })
 
-    expect(result.current.isReady).toBe(false)
-    expect(result.current.durably).toBeNull()
-    expect(result.current.error?.message).toBe('Dialect creation failed')
+    // Should be the exact same instance
+    expect(result.current.durably).toBe(durably)
+  })
+
+  it('throws when useDurably is used outside provider', () => {
+    expect(() => {
+      renderHook(() => useDurably())
+    }).toThrow('useDurably must be used within a DurablyProvider')
   })
 })
diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx
index ec734648..0f443596 100644
--- a/packages/durably-react/tests/browser/use-job-logs.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx
@@ -11,7 +11,7 @@ import { useState } from 'react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 import { DurablyProvider, useDurably, useJobLogs } from '../../src'
-import { createBrowserDialect } from '../helpers/browser-dialect'
+import { createTestDurably } from '../helpers/create-test-durably'
 
 // Test job that generates logs with delay to ensure we can subscribe
 const loggingJob = defineJob({
@@ -29,49 +29,8 @@ const loggingJob = defineJob({
 })
 
 describe('useJobLogs', () => {
-  // Track all instances created during tests for cleanup
   const instances: Durably[] = []
 
-  // Create a shared dialect for tests that need to share the same Durably instance
-  let sharedDialect: ReturnType | null = null
-
-  const getSharedDialect = () => {
-    if (!sharedDialect) {
-      sharedDialect = createBrowserDialect()
-    }
-    return sharedDialect
-  }
-
-  // Helper to create wrapper with shared dialect
-  const createSharedWrapper =
-    () =>
-    ({ children }: { children: ReactNode }) => (
-       {
-          if (!instances.includes(durably)) {
-            instances.push(durably)
-          }
-        }}
-      >
-        {children}
-      
-    )
-
-  // Helper to create wrapper with new dialect
-  const createWrapper =
-    () =>
-    ({ children }: { children: ReactNode }) => (
-       createBrowserDialect()}
-        options={{ pollingInterval: 50 }}
-        onReady={(durably) => instances.push(durably)}
-      >
-        {children}
-      
-    )
-
   afterEach(async () => {
     for (const instance of instances) {
       try {
@@ -81,32 +40,39 @@ describe('useJobLogs', () => {
       }
     }
     instances.length = 0
-    sharedDialect = null
     await new Promise((r) => setTimeout(r, 200))
   })
 
+  const createWrapper = (durably: Durably) => {
+    return ({ children }: { children: ReactNode }) => (
+      {children}
+    )
+  }
+
   it('collects logs for run', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobLogs({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({
+    const { _job: handle } = durably.register({
       _job: loggingJob,
     })
     const run = await handle.trigger({ count: 3 })
@@ -127,8 +93,11 @@ describe('useJobLogs', () => {
   })
 
   it('handles null runId', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJobLogs({ runId: null }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -138,27 +107,29 @@ describe('useJobLogs', () => {
   })
 
   it('respects maxLogs limit', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobLogs({ runId, maxLogs: 5 })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({
+    const { _job: handle } = durably.register({
       _job: loggingJob,
     })
     const run = await handle.trigger({ count: 10 })
@@ -172,27 +143,29 @@ describe('useJobLogs', () => {
   })
 
   it('clears logs on clearLogs call', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobLogs({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({
+    const { _job: handle } = durably.register({
       _job: loggingJob,
     })
     const run = await handle.trigger({ count: 3 })
diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx
index e1230ad9..e5640c5f 100644
--- a/packages/durably-react/tests/browser/use-job-run.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-run.test.tsx
@@ -11,7 +11,7 @@ import { useState } from 'react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 import { DurablyProvider, useDurably, useJobRun } from '../../src'
-import { createBrowserDialect } from '../helpers/browser-dialect'
+import { createTestDurably } from '../helpers/create-test-durably'
 
 // Test job definitions - use slow jobs to ensure we can subscribe before completion
 const testJob = defineJob({
@@ -52,49 +52,8 @@ const progressJob = defineJob({
 })
 
 describe('useJobRun', () => {
-  // Track all instances created during tests for cleanup
   const instances: Durably[] = []
 
-  // Create a shared dialect for tests that need to share the same Durably instance
-  let sharedDialect: ReturnType | null = null
-
-  const getSharedDialect = () => {
-    if (!sharedDialect) {
-      sharedDialect = createBrowserDialect()
-    }
-    return sharedDialect
-  }
-
-  // Helper to create wrapper with shared dialect
-  const createSharedWrapper =
-    () =>
-    ({ children }: { children: ReactNode }) => (
-       {
-          if (!instances.includes(durably)) {
-            instances.push(durably)
-          }
-        }}
-      >
-        {children}
-      
-    )
-
-  // Helper to create wrapper with new dialect
-  const createWrapper =
-    () =>
-    ({ children }: { children: ReactNode }) => (
-       createBrowserDialect()}
-        options={{ pollingInterval: 50 }}
-        onReady={(durably) => instances.push(durably)}
-      >
-        {children}
-      
-    )
-
   afterEach(async () => {
     for (const instance of instances) {
       try {
@@ -104,34 +63,41 @@ describe('useJobRun', () => {
       }
     }
     instances.length = 0
-    sharedDialect = null
     await new Promise((r) => setTimeout(r, 200))
   })
 
+  const createWrapper = (durably: Durably) => {
+    return ({ children }: { children: ReactNode }) => (
+      {children}
+    )
+  }
+
   it('subscribes to run by id', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     // Use a combined hook that triggers then subscribes
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
     // Trigger job and set runId
-    const { _job: handle } = result.current.durably!.register({ _job: testJob })
+    const { _job: handle } = durably.register({ _job: testJob })
     const run = await handle.trigger({ input: 'test' })
 
     // Update runId to start subscription
@@ -147,8 +113,11 @@ describe('useJobRun', () => {
   })
 
   it('handles null runId', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJobRun({ runId: null }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -160,27 +129,29 @@ describe('useJobRun', () => {
   })
 
   it('provides output when run completes', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun<{ result: string }>({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({ _job: testJob })
+    const { _job: handle } = durably.register({ _job: testJob })
     const run = await handle.trigger({ input: 'hello' })
     result.current.setRunId(run.id)
 
@@ -194,27 +165,29 @@ describe('useJobRun', () => {
   })
 
   it('provides error when run fails', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({
+    const { _job: handle } = durably.register({
       _job: failingJob,
     })
     const run = await handle.trigger({ input: 'test' })
@@ -230,27 +203,29 @@ describe('useJobRun', () => {
   })
 
   it('tracks progress updates', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({
+    const { _job: handle } = durably.register({
       _job: progressJob,
     })
     const run = await handle.trigger({ input: 'test' })
@@ -269,27 +244,29 @@ describe('useJobRun', () => {
   })
 
   it('provides boolean helpers', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     function useTriggerAndSubscribe() {
-      const { durably, isReady: durablyReady } = useDurably()
+      const { isReady: durablyReady } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
         isReady: durablyReady && subscription.isReady,
-        durably,
         runId,
         setRunId,
       }
     }
 
     const { result } = renderHook(() => useTriggerAndSubscribe(), {
-      wrapper: createSharedWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const { _job: handle } = result.current.durably!.register({ _job: testJob })
+    const { _job: handle } = durably.register({ _job: testJob })
     const run = await handle.trigger({ input: 'test' })
     result.current.setRunId(run.id)
 
diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx
index 1f23ec70..7ff97884 100644
--- a/packages/durably-react/tests/browser/use-job.test.tsx
+++ b/packages/durably-react/tests/browser/use-job.test.tsx
@@ -10,7 +10,7 @@ import type { ReactNode } from 'react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 import { DurablyProvider, useJob } from '../../src'
-import { createBrowserDialect } from '../helpers/browser-dialect'
+import { createTestDurably } from '../helpers/create-test-durably'
 
 // Test job definitions
 const testJob = defineJob({
@@ -70,22 +70,19 @@ describe('useJob', () => {
     await new Promise((r) => setTimeout(r, 200))
   })
 
-  // Helper to create wrapper
-  const createWrapper =
-    () =>
-    ({ children }: { children: ReactNode }) => (
-       createBrowserDialect()}
-        options={{ pollingInterval: 50 }}
-        onReady={(durably) => instances.push(durably)}
-      >
-        {children}
-      
+  // Helper to create wrapper with a fresh durably instance
+  const createWrapper = (durably: Durably) => {
+    return ({ children }: { children: ReactNode }) => (
+      {children}
     )
+  }
 
   it('returns trigger function that executes job', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -97,8 +94,11 @@ describe('useJob', () => {
   })
 
   it('updates status from pending to running to completed', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -120,8 +120,11 @@ describe('useJob', () => {
   })
 
   it('provides output when completed', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -134,8 +137,11 @@ describe('useJob', () => {
   })
 
   it('provides error when failed', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(failingJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -149,8 +155,11 @@ describe('useJob', () => {
   })
 
   it('updates progress during execution', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(progressJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -169,8 +178,11 @@ describe('useJob', () => {
   })
 
   it('collects logs during execution', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(loggingJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -188,8 +200,11 @@ describe('useJob', () => {
   })
 
   it('provides boolean helpers', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -221,8 +236,11 @@ describe('useJob', () => {
   })
 
   it('triggerAndWait resolves with output', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -236,8 +254,11 @@ describe('useJob', () => {
   })
 
   it('triggerAndWait rejects on failure', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(failingJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -248,8 +269,11 @@ describe('useJob', () => {
   })
 
   it('reset clears all state', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -268,11 +292,14 @@ describe('useJob', () => {
   })
 
   it('sets initialRunId as currentRunId', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const fakeRunId = 'test-run-123'
 
     const { result } = renderHook(
       () => useJob(testJob, { initialRunId: fakeRunId }),
-      { wrapper: createWrapper() },
+      { wrapper: createWrapper(durably) },
     )
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -282,8 +309,11 @@ describe('useJob', () => {
   })
 
   it('unsubscribes on unmount', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result, unmount } = renderHook(() => useJob(testJob), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -299,6 +329,9 @@ describe('useJob', () => {
 
   describe('followLatest option', () => {
     it('switches to latest running job by default (followLatest: true)', async () => {
+      const durably = await createTestDurably({ pollingInterval: 50 })
+      instances.push(durably)
+
       const slowJob = defineJob({
         name: 'slow-job',
         input: z.object({ id: z.number() }),
@@ -312,7 +345,7 @@ describe('useJob', () => {
       })
 
       const { result } = renderHook(() => useJob(slowJob), {
-        wrapper: createWrapper(),
+        wrapper: createWrapper(durably),
       })
 
       await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -334,6 +367,9 @@ describe('useJob', () => {
     })
 
     it('stays on current run when followLatest: false and external run starts', async () => {
+      const durably = await createTestDurably({ pollingInterval: 50 })
+      instances.push(durably)
+
       // This test verifies that followLatest: false keeps tracking the current run
       // even when run:start events fire (from the worker starting jobs)
       const slowJob = defineJob({
@@ -350,7 +386,7 @@ describe('useJob', () => {
 
       const { result } = renderHook(
         () => useJob(slowJob, { followLatest: false }),
-        { wrapper: createWrapper() },
+        { wrapper: createWrapper(durably) },
       )
 
       await waitFor(() => expect(result.current.isReady).toBe(true))
diff --git a/packages/durably-react/tests/browser/use-runs.test.tsx b/packages/durably-react/tests/browser/use-runs.test.tsx
index ab47e09c..a0a20022 100644
--- a/packages/durably-react/tests/browser/use-runs.test.tsx
+++ b/packages/durably-react/tests/browser/use-runs.test.tsx
@@ -10,7 +10,7 @@ import type { ReactNode } from 'react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { z } from 'zod'
 import { DurablyProvider, useRuns } from '../../src'
-import { createBrowserDialect } from '../helpers/browser-dialect'
+import { createTestDurably } from '../helpers/create-test-durably'
 
 // Test job definition
 const testJob = defineJob({
@@ -39,21 +39,18 @@ describe('useRuns', () => {
     await new Promise((r) => setTimeout(r, 200))
   })
 
-  const createWrapper =
-    () =>
-    ({ children }: { children: ReactNode }) => (
-       createBrowserDialect()}
-        options={{ pollingInterval: 50 }}
-        onReady={(durably) => instances.push(durably)}
-      >
-        {children}
-      
+  const createWrapper = (durably: Durably) => {
+    return ({ children }: { children: ReactNode }) => (
+      {children}
     )
+  }
 
   it('returns empty runs initially', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns(), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
@@ -63,14 +60,16 @@ describe('useRuns', () => {
   })
 
   it('lists runs after job execution', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns(), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
     // Trigger a job using the durably instance directly
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
     await testJobHandle.trigger({ value: 10 })
 
@@ -83,6 +82,9 @@ describe('useRuns', () => {
   })
 
   it('filters by jobName', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const otherJob = defineJob({
       name: 'other-job',
       input: z.object({ x: z.string() }),
@@ -90,12 +92,11 @@ describe('useRuns', () => {
     })
 
     const { result } = renderHook(() => useRuns({ jobName: 'test-job-runs' }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle, otherJobHandle } = durably.register({
       testJobHandle: testJob,
       otherJobHandle: otherJob,
@@ -112,13 +113,15 @@ describe('useRuns', () => {
   })
 
   it('filters by status', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns({ status: 'completed' }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
 
     // Trigger and wait for completion
@@ -143,13 +146,15 @@ describe('useRuns', () => {
   })
 
   it('supports pagination', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns({ pageSize: 2 }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
 
     // Create 3 runs
@@ -180,13 +185,15 @@ describe('useRuns', () => {
   })
 
   it('goToPage navigates directly', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns({ pageSize: 1 }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
 
     // Create 3 runs
@@ -206,13 +213,15 @@ describe('useRuns', () => {
   })
 
   it('refresh reloads data', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns(), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
 
     // Initially empty
@@ -229,13 +238,15 @@ describe('useRuns', () => {
   })
 
   it('updates in real-time by default', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns(), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
 
     expect(result.current.runs.length).toBe(0)
@@ -249,13 +260,15 @@ describe('useRuns', () => {
   })
 
   it('disables real-time updates when realtime=false', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
     const { result } = renderHook(() => useRuns({ realtime: false }), {
-      wrapper: createWrapper(),
+      wrapper: createWrapper(durably),
     })
 
     await waitFor(() => expect(result.current.isReady).toBe(true))
 
-    const durably = instances[0]
     const { testJobHandle } = durably.register({ testJobHandle: testJob })
 
     await testJobHandle.trigger({ value: 77 })
diff --git a/packages/durably-react/tests/helpers/create-test-durably.ts b/packages/durably-react/tests/helpers/create-test-durably.ts
new file mode 100644
index 00000000..8e912c85
--- /dev/null
+++ b/packages/durably-react/tests/helpers/create-test-durably.ts
@@ -0,0 +1,29 @@
+import { createDurably, type Durably } from '@coji/durably'
+import { createBrowserDialect } from './browser-dialect'
+
+export interface TestDurablyOptions {
+  pollingInterval?: number
+  autoMigrate?: boolean
+}
+
+/**
+ * Create a Durably instance for testing.
+ * The instance is migrated unless autoMigrate is false.
+ */
+export async function createTestDurably(
+  options?: TestDurablyOptions,
+): Promise {
+  const dialect = createBrowserDialect()
+  const durably = createDurably({
+    dialect,
+    pollingInterval: options?.pollingInterval ?? 100,
+    heartbeatInterval: 500,
+    staleThreshold: 3000,
+  })
+
+  if (options?.autoMigrate !== false) {
+    await durably.migrate()
+  }
+
+  return durably
+}
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 14c8cdd2..ad96b19a 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -42,7 +42,7 @@ importers:
         specifier: 7.11.0
         version: 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)
       isbot:
-        specifier: ^5
+        specifier: ^5.1.32
         version: 5.1.32
       kysely:
         specifier: ^0.28.9
@@ -58,7 +58,7 @@ importers:
         version: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       sqlocal:
         specifier: ^0.16.0
-        version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3))
+        version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3))
       zod:
         specifier: ^4.3.2
         version: 4.3.2
@@ -68,13 +68,13 @@ importers:
         version: 2.3.10
       '@react-router/dev':
         specifier: 7.11.0
-        version: 7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
+        version: 7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
       '@tailwindcss/vite':
         specifier: ^4.1.18
-        version: 4.1.18(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
+        version: 4.1.18(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
       '@types/node':
-        specifier: ^22
-        version: 22.19.3
+        specifier: ^25.0.3
+        version: 25.0.3
       '@types/react':
         specifier: ^19.2.7
         version: 19.2.7
@@ -95,10 +95,10 @@ importers:
         version: 5.9.3
       vite:
         specifier: ^7.3.0
-        version: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
+        version: 7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
       vite-tsconfig-paths:
         specifier: ^6.0.3
-        version: 6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
+        version: 6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
 
   examples/browser-vite-react:
     dependencies:
@@ -1614,9 +1614,6 @@ packages:
   '@types/mdurl@2.0.0':
     resolution: {integrity: sha512-RGdgjQUZba5p6QEFAVx2OGb8rQDL/cPRG7GiedRzMcJ1tYnUANBncjbSB1NRGwbvjcPeikRABz2nshyPk1bhWg==}
 
-  '@types/node@22.19.3':
-    resolution: {integrity: sha512-1N9SBnWYOJTrNZCdh/yJE+t910Y128BoyY+zBLWhL3r0TYzlTmFdXrPwHL9DyFZmlEXNQQolTZh3KHV31QDhyA==}
-
   '@types/node@25.0.3':
     resolution: {integrity: sha512-W609buLVRVmeW693xKfzHeIV6nJGGz98uCPfeXI1ELMLXVeKYZ9m15fAMSaUPBHYLGFsVRcMmSCksQOrZV9BYA==}
 
@@ -3068,9 +3065,6 @@ packages:
     resolution: {integrity: sha512-xY7c8LPyzvhvew0Fn+Ek3wBC9STZAuDI/Y5andCKi9AX6/jvfaX45PhsDX8oxgPL0YFp0Jhr8qWMbS/p9375Xg==}
     engines: {node: '>=16'}
 
-  undici-types@6.21.0:
-    resolution: {integrity: sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==}
-
   undici-types@7.16.0:
     resolution: {integrity: sha512-Zz+aZWSj8LE6zoxD+xrjh4VfkIG8Ya6LvYkZqtUQGJPZjYl53ypCaUwWqo7eI0x66KBGeRo+mlBEkMSeSZ38Nw==}
 
@@ -4102,56 +4096,6 @@ snapshots:
 
   '@polka/url@1.0.0-next.29': {}
 
-  '@react-router/dev@7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
-    dependencies:
-      '@babel/core': 7.28.5
-      '@babel/generator': 7.28.5
-      '@babel/parser': 7.28.5
-      '@babel/plugin-syntax-jsx': 7.27.1(@babel/core@7.28.5)
-      '@babel/preset-typescript': 7.28.5(@babel/core@7.28.5)
-      '@babel/traverse': 7.28.5
-      '@babel/types': 7.28.5
-      '@react-router/node': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)
-      '@remix-run/node-fetch-server': 0.9.0
-      arg: 5.0.2
-      babel-dead-code-elimination: 1.0.11
-      chokidar: 4.0.3
-      dedent: 1.7.1
-      es-module-lexer: 1.7.0
-      exit-hook: 2.2.1
-      isbot: 5.1.32
-      jsesc: 3.0.2
-      lodash: 4.17.21
-      p-map: 7.0.4
-      pathe: 1.1.2
-      picocolors: 1.1.1
-      pkg-types: 2.3.0
-      prettier: 3.7.4
-      react-refresh: 0.14.2
-      react-router: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
-      semver: 7.7.3
-      tinyglobby: 0.2.15
-      valibot: 1.2.0(typescript@5.9.3)
-      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-      vite-node: 3.2.4(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-    optionalDependencies:
-      '@react-router/serve': 7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3)
-      typescript: 5.9.3
-    transitivePeerDependencies:
-      - '@types/node'
-      - babel-plugin-macros
-      - jiti
-      - less
-      - lightningcss
-      - sass
-      - sass-embedded
-      - stylus
-      - sugarss
-      - supports-color
-      - terser
-      - tsx
-      - yaml
-
   '@react-router/dev@7.11.0(@react-router/serve@7.11.0(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(typescript@5.9.3))(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(react-router@7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3))(tsx@4.21.0)(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
     dependencies:
       '@babel/core': 7.28.5
@@ -4407,13 +4351,6 @@ snapshots:
       '@tailwindcss/oxide-win32-arm64-msvc': 4.1.18
       '@tailwindcss/oxide-win32-x64-msvc': 4.1.18
 
-  '@tailwindcss/vite@4.1.18(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
-    dependencies:
-      '@tailwindcss/node': 4.1.18
-      '@tailwindcss/oxide': 4.1.18
-      tailwindcss: 4.1.18
-      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-
   '@tailwindcss/vite@4.1.18(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))':
     dependencies:
       '@tailwindcss/node': 4.1.18
@@ -4491,10 +4428,6 @@ snapshots:
 
   '@types/mdurl@2.0.0': {}
 
-  '@types/node@22.19.3':
-    dependencies:
-      undici-types: 6.21.0
-
   '@types/node@25.0.3':
     dependencies:
       undici-types: 7.16.0
@@ -5841,19 +5774,6 @@ snapshots:
 
   speakingurl@14.0.1: {}
 
-  sqlocal@0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)):
-    dependencies:
-      '@sqlite.org/sqlite-wasm': 3.50.4-build1
-      coincident: 1.2.3
-    optionalDependencies:
-      kysely: 0.28.9
-      react: 19.2.3
-      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-      vue: 3.5.26(typescript@5.9.3)
-    transitivePeerDependencies:
-      - bufferutil
-      - utf-8-validate
-
   sqlocal@0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3)):
     dependencies:
       '@sqlite.org/sqlite-wasm': 3.50.4-build1
@@ -6028,8 +5948,6 @@ snapshots:
     dependencies:
       layerr: 3.0.0
 
-  undici-types@6.21.0: {}
-
   undici-types@7.16.0: {}
 
   unist-util-is@6.0.1:
@@ -6081,27 +5999,6 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite-node@3.2.4(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
-    dependencies:
-      cac: 6.7.14
-      debug: 4.4.3
-      es-module-lexer: 1.7.0
-      pathe: 2.0.3
-      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-    transitivePeerDependencies:
-      - '@types/node'
-      - jiti
-      - less
-      - lightningcss
-      - sass
-      - sass-embedded
-      - stylus
-      - sugarss
-      - supports-color
-      - terser
-      - tsx
-      - yaml
-
   vite-node@3.2.4(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
     dependencies:
       cac: 6.7.14
@@ -6123,17 +6020,6 @@ snapshots:
       - tsx
       - yaml
 
-  vite-tsconfig-paths@6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)):
-    dependencies:
-      debug: 4.4.3
-      globrex: 0.1.2
-      tsconfck: 3.1.6(typescript@5.9.3)
-    optionalDependencies:
-      vite: 7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)
-    transitivePeerDependencies:
-      - supports-color
-      - typescript
-
   vite-tsconfig-paths@6.0.3(typescript@5.9.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0)):
     dependencies:
       debug: 4.4.3
@@ -6155,21 +6041,6 @@ snapshots:
       fsevents: 2.3.3
       lightningcss: 1.30.2
 
-  vite@7.3.0(@types/node@22.19.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
-    dependencies:
-      esbuild: 0.27.2
-      fdir: 6.5.0(picomatch@4.0.3)
-      picomatch: 4.0.3
-      postcss: 8.5.6
-      rollup: 4.54.0
-      tinyglobby: 0.2.15
-    optionalDependencies:
-      '@types/node': 22.19.3
-      fsevents: 2.3.3
-      jiti: 2.6.1
-      lightningcss: 1.30.2
-      tsx: 4.21.0
-
   vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0):
     dependencies:
       esbuild: 0.27.2

From 8ffe82fb517915d5da44ca55944108935a72a389 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 11:35:55 +0900
Subject: [PATCH 067/101] feat(durably): add durably.jobs for type-safe job
 access
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add `jobs` property to Durably interface, populated by register()
- Update examples to use durably.jobs.xxx.trigger() pattern
- Simplify durably.ts initialization with top-level await
- Document ESM-only requirement in README and CLAUDE.md
- Update spec-react.md for new API patterns

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 CLAUDE.md                                     |   1 +
 docs/spec-react.md                            | 327 ++++++++++++------
 .../app/lib/durably.ts                        |  86 +----
 .../browser-react-router-spa/app/root.tsx     |  21 +-
 .../app/routes/_index.tsx                     |  52 +--
 examples/browser-vite-react/src/App.tsx       |  17 +-
 examples/browser-vite-react/src/durably.ts    |  44 +--
 packages/durably-react/README.md              |   2 +
 packages/durably-react/src/context.tsx        |  77 ++++-
 packages/durably/README.md                    |   2 +
 packages/durably/src/durably.ts               |  24 +-
 11 files changed, 373 insertions(+), 280 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index 8ff57a8e..41ba138a 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -27,6 +27,7 @@ When API changes are made, update `packages/durably/docs/llms.md` to keep it in
 
 ## Key Design Decisions
 
+- **ESM-only**: This library is ESM-only. CommonJS is not supported. Always use top-level `await` for async initialization (e.g., `await durably.migrate()`). Do not wrap in async IIFE or Promise chains.
 - Single-threaded execution, no parallel run processing in minimal config
 - No automatic retry - failures are immediate and explicit (`retry()` API for manual retry)
 - Dialect injection pattern - Kysely dialect passed to `createDurably()` to abstract SQLite implementations
diff --git a/docs/spec-react.md b/docs/spec-react.md
index 233e4462..a80a21e8 100644
--- a/docs/spec-react.md
+++ b/docs/spec-react.md
@@ -18,7 +18,7 @@
 ```text
 @coji/durably-react
 ├── index.ts          # ブラウザ完結モード用（DurablyProvider + hooks）
-└── client.ts         # サーバー連携モード用（軽量、@coji/durably 不要）
+└── client/index.ts   # サーバー連携モード用（軽量、@coji/durably 不要）
 
 @coji/durably
 └── server.ts         # サーバー側ヘルパー（Web 標準 API）
@@ -32,16 +32,74 @@
 
 ### セットアップ
 
+Durably インスタンスは Promise として export し、DurablyProvider に直接渡す:
+
+```ts
+// lib/durably.ts
+import { createDurably, type Durably } from '@coji/durably'
+import { SQLocalKysely } from 'sqlocal/kysely'
+import { processImageJob } from './jobs'
+
+export { processImageJob }
+
+export const sqlocal = new SQLocalKysely('app.sqlite3')
+
+async function initDurably(): Promise {
+  const instance = createDurably({
+    dialect: sqlocal.dialect,
+    pollingInterval: 100,
+    heartbeatInterval: 500,
+    staleThreshold: 3000,
+  })
+  await instance.migrate()
+  instance.register({ processImage: processImageJob })
+  return instance
+}
+
+/** Shared Durably instance promise */
+export const durably = initDurably()
+```
+
+```tsx
+// App.tsx
+import { DurablyProvider } from '@coji/durably-react'
+import { durably } from './lib/durably'
+
+function Loading() {
+  return 
      Loading...
      
+}
+
+export function App() {
+  return (
+    }>
+      
+    
+  )
+}
+```
+
+`DurablyProvider` は `Durably` または `Promise` を受け付ける。Promise の場合は内部で React 19 の `use()` を使って解決する。`fallback` を指定すると自動的に Suspense でラップされる。
+
+React Router 7 の場合は `clientLoader` を使用することもできる:
+
 ```tsx
 // root.tsx
 import { DurablyProvider } from '@coji/durably-react'
-import { SQLocalKysely } from 'sqlocal/kysely'
+import { Outlet } from 'react-router'
+import { getDurably } from './lib/durably'
 
-export default function App() {
+export async function clientLoader() {
+  const durably = await getDurably()
+  return { durably }
+}
+
+export function HydrateFallback() {
+  return 
      Loading...
      
+}
+
+export default function App({ loaderData }) {
   return (
-     new SQLocalKysely('app.sqlite3').dialect}
-    >
+    
       
     
   )
@@ -107,7 +165,7 @@ function TaskRunner() {
 ### サーバー側（Web 標準 API）
 
 ```ts
-// app/routes/api.durably.ts (Remix example)
+// app/routes/api.durably.ts (React Router / Remix example)
 import { createDurablyHandler } from '@coji/durably/server'
 import { durably } from '~/lib/durably.server'
 
@@ -163,7 +221,7 @@ import { useJob } from '@coji/durably-react/client'
 
 function TaskRunner() {
   const { trigger, status, output, progress, isRunning } = useJob({
-    api: '/api/durably',
+    baseUrl: '/api/durably',
     jobName: 'process-task',
   })
 
@@ -195,11 +253,16 @@ function TaskRunner() {
 #### DurablyProvider
 
 ```tsx
+// Promise を渡す場合（推奨）
+}>
+  {children}
+
+
+// 解決済みインスタンスを渡す場合
  dialect}
-  options={{ pollingInterval: 1000 }}
+  durably={durably}
   autoStart={true}
-  autoMigrate={true}
+  onReady={(durably) => console.log('Ready!')}
 >
   {children}
 
@@ -207,10 +270,10 @@ function TaskRunner() {
 
 | Prop | 型 | 必須 | 説明 |
 |------|-----|------|------|
-| `dialectFactory` | `() => Dialect` | Yes | Dialect ファクトリ（一度だけ実行） |
-| `options` | `DurablyOptions` | - | Durably 設定 |
+| `durably` | `Durably \| Promise` | Yes | Durably インスタンスまたは Promise |
 | `autoStart` | `boolean` | - | 自動 start()（デフォルト: true） |
-| `autoMigrate` | `boolean` | - | 自動 migrate()（デフォルト: true） |
+| `onReady` | `(durably: Durably) => void` | - | 準備完了コールバック |
+| `fallback` | `ReactNode` | - | Promise 解決中のフォールバック UI |
 
 #### useDurably
 
@@ -254,11 +317,22 @@ const {
 
 **戻り値の詳細**:
 
-| プロパティ              | 型                                            | 説明                                                                 |
-|-------------------------|-----------------------------------------------|----------------------------------------------------------------------|
-| `isReady`               | `boolean`                                     | 準備完了（ブラウザ: 初期化完了、サーバー連携: 常に `true`）          |
-| `trigger(input)`        | `Promise<{ runId: string }>`                  | ジョブを実行、Run ID を返す                                          |
-| `triggerAndWait(input)` | `Promise<{ runId: string; output: TOutput }>` | 実行して完了を待つ                                                   |
+| プロパティ | 型 | 説明 |
+|-----------|-----|------|
+| `isReady` | `boolean` | 準備完了 |
+| `trigger(input)` | `Promise<{ runId: string }>` | ジョブを実行、Run ID を返す |
+| `triggerAndWait(input)` | `Promise<{ runId: string; output: TOutput }>` | 実行して完了を待つ |
+| `status` | `RunStatus \| null` | 現在のステータス |
+| `output` | `TOutput \| null` | 完了時の出力 |
+| `error` | `string \| null` | 失敗時のエラー |
+| `logs` | `LogEntry[]` | ログ一覧 |
+| `progress` | `Progress \| null` | 進捗情報 |
+| `isRunning` | `boolean` | 実行中 |
+| `isPending` | `boolean` | 待機中 |
+| `isCompleted` | `boolean` | 完了 |
+| `isFailed` | `boolean` | 失敗 |
+| `currentRunId` | `string \| null` | 現在の Run ID |
+| `reset` | `() => void` | 状態リセット |
 
 #### useJobRun
 
@@ -268,8 +342,8 @@ const { status, output, error, logs, progress } = useJobRun({ runId })
 
 Run ID のみで購読（trigger なし）。`runId` が `null` の場合は購読せず待機する。
 
-| 引数    | 型               | 説明            |
-|---------|------------------|-----------------|
+| 引数 | 型 | 説明 |
+|------|-----|------|
 | `runId` | `string \| null` | 購読する Run ID |
 
 #### useJobLogs
@@ -278,6 +352,11 @@ Run ID のみで購読（trigger なし）。`runId` が `null` の場合は購
 const { logs, clear } = useJobLogs({ runId, maxLogs? })
 ```
 
+| 引数 | 型 | 説明 |
+|------|-----|------|
+| `runId` | `string \| null` | Run ID |
+| `maxLogs` | `number` | 最大ログ数（デフォルト: 100） |
+
 #### useRuns
 
 ```tsx
@@ -291,6 +370,8 @@ const {
   prevPage,
   goToPage,
   refresh,
+  retry,
+  cancel,
 } = useRuns(options?)
 ```
 
@@ -301,6 +382,20 @@ const {
 | `limit` | `number` | 1ページの件数（デフォルト: 20） |
 | `realtime` | `boolean` | リアルタイム更新（デフォルト: true） |
 
+| 戻り値 | 型 | 説明 |
+|--------|-----|------|
+| `runs` | `Run[]` | Run 一覧 |
+| `isLoading` | `boolean` | 読み込み中 |
+| `error` | `string \| null` | エラー |
+| `page` | `number` | 現在ページ |
+| `hasMore` | `boolean` | 次ページあり |
+| `nextPage` | `() => void` | 次ページへ |
+| `prevPage` | `() => void` | 前ページへ |
+| `goToPage` | `(page: number) => void` | 指定ページへ |
+| `refresh` | `() => Promise` | 再読み込み |
+| `retry` | `(runId: string) => Promise` | Run を再実行 |
+| `cancel` | `(runId: string) => Promise` | Run をキャンセル |
+
 ---
 
 ### サーバー連携モード
@@ -311,7 +406,6 @@ const {
 import { createDurablyHandler } from '@coji/durably/server'
 
 const handler = createDurablyHandler(durably, {
-  // リクエスト処理前に呼ばれる（オプション）
   onRequest: async () => {
     await durably.migrate()
     durably.start()
@@ -361,7 +455,7 @@ data: {"type":"run:fail","runId":"xxx","jobName":"process-task","error":"Somethi
 #### クライアント側 (`@coji/durably-react/client`)
 
 ```tsx
-import { useJob, useJobRun, useJobLogs } from '@coji/durably-react/client'
+import { useJob, useJobRun, useJobLogs, useRuns, useRunActions } from '@coji/durably-react/client'
 
 // ジョブ実行 + 購読
 const {
@@ -380,73 +474,62 @@ const {
   currentRunId,
   reset,
 } = useJob({
-  api: '/api/durably',
+  baseUrl: '/api/durably',
   jobName: 'process-task',
 })
 
 // 既存 Run の購読のみ
 const { status, output, error, logs, progress } = useJobRun({
-  api: '/api/durably',
+  baseUrl: '/api/durably',
   runId: 'xxx',
 })
 
 // ログ購読
 const { logs, clear } = useJobLogs({
-  api: '/api/durably',
+  baseUrl: '/api/durably',
   runId: 'xxx',
 })
+
+// Run 一覧
+const { runs, isLoading, refresh, retry, cancel } = useRuns({
+  baseUrl: '/api/durably',
+  jobName: 'process-task',
+})
+
+// Run アクション
+const { retry, cancel, isLoading, error } = useRunActions({
+  baseUrl: '/api/durably',
+})
 ```
 
 **useJob オプション**:
 
-| オプション     | 型       | 必須 | 説明                        |
-|----------------|----------|------|-----------------------------|
-| `api`          | `string` | Yes  | API エンドポイント          |
-| `jobName`      | `string` | Yes  | ジョブ名                    |
-| `initialRunId` | `string` | -    | 初期購読 Run ID（再接続用） |
+| オプション | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `baseUrl` | `string` | Yes | API エンドポイント |
+| `jobName` | `string` | Yes | ジョブ名 |
+| `initialRunId` | `string` | - | 初期購読 Run ID（再接続用） |
 
 **useJobRun オプション**:
 
-| オプション | 型       | 必須 | 説明               |
-|------------|----------|------|--------------------|
-| `api`      | `string` | Yes  | API エンドポイント |
-| `runId`    | `string \| null` | Yes  | Run ID（`null` の場合は購読しない） |
+| オプション | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `baseUrl` | `string` | Yes | API エンドポイント |
+| `runId` | `string \| null` | Yes | Run ID（`null` の場合は購読しない） |
 
 **useJobLogs オプション**:
 
-| オプション | 型       | 必須 | 説明                                  |
-|------------|----------|------|---------------------------------------|
-| `api`      | `string` | Yes  | API エンドポイント                    |
-| `runId`    | `string` | Yes  | Run ID                                |
-| `maxLogs`  | `number` | -    | 保持する最大ログ数（デフォルト: 100） |
+| オプション | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `baseUrl` | `string` | Yes | API エンドポイント |
+| `runId` | `string` | Yes | Run ID |
+| `maxLogs` | `number` | - | 保持する最大ログ数（デフォルト: 100） |
 
 **useRuns オプション**:
 
-```tsx
-import { useRuns } from '@coji/durably-react/client'
-
-const {
-  runs,
-  isLoading,
-  error,
-  page,
-  hasMore,
-  nextPage,
-  prevPage,
-  goToPage,
-  refresh,
-} = useRuns({
-  api: '/api/durably',
-  jobName?: 'my-job',
-  status?: 'completed',
-  limit?: 20,
-  realtime?: true,
-})
-```
-
 | オプション | 型 | 必須 | 説明 |
 |------------|------|------|------|
-| `api` | `string` | Yes | API エンドポイント |
+| `baseUrl` | `string` | Yes | API エンドポイント |
 | `jobName` | `string` | - | ジョブ名でフィルタ |
 | `status` | `RunStatus` | - | ステータスでフィルタ |
 | `limit` | `number` | - | 1ページの件数（デフォルト: 20） |
@@ -454,17 +537,9 @@ const {
 
 **useRunActions オプション**:
 
-```tsx
-import { useRunActions } from '@coji/durably-react/client'
-
-const { retry, cancel, isLoading, error } = useRunActions({
-  api: '/api/durably',
-})
-
-// 使用例
-await retry(runId)   // 失敗した Run を再実行
-await cancel(runId)  // 実行中の Run をキャンセル
-```
+| オプション | 型 | 必須 | 説明 |
+|------------|------|------|------|
+| `baseUrl` | `string` | Yes | API エンドポイント |
 
 | 戻り値 | 型 | 説明 |
 |--------|------|------|
@@ -475,7 +550,7 @@ await cancel(runId)  // 実行中の Run をキャンセル
 
 ---
 
-### 型安全クライアントファクトリ（推奨）
+### 型安全クライアントファクトリ
 
 ```tsx
 import { createDurablyClient, createJobHooks } from '@coji/durably-react/client'
@@ -485,7 +560,7 @@ import type { processTask, syncUsers } from './jobs'
 const client = createDurablyClient<{
   'process-task': typeof processTask
   'sync-users': typeof syncUsers
-}>({ api: '/api/durably' })
+}>({ baseUrl: '/api/durably' })
 
 const { trigger, status } = client.useJob('process-task')
 await trigger({ taskId: '123' })  // 型安全
@@ -494,7 +569,7 @@ await trigger({ taskId: '123' })  // 型安全
 const { useProcessTask, useSyncUsers } = createJobHooks<{
   'process-task': typeof processTask
   'sync-users': typeof syncUsers
-}>({ api: '/api/durably' })
+}>({ baseUrl: '/api/durably' })
 
 const { trigger, status } = useProcessTask()
 ```
@@ -507,12 +582,6 @@ const { trigger, status } = useProcessTask()
 // 共通
 type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
 
-interface DurablyOptions {
-  pollingInterval?: number   // デフォルト: 1000ms
-  heartbeatInterval?: number // デフォルト: 5000ms
-  staleThreshold?: number    // デフォルト: 30000ms
-}
-
 interface Progress {
   current: number
   total?: number
@@ -646,7 +715,7 @@ import { useJob } from '@coji/durably-react/client'
 
 function AIChat() {
   const { trigger, status, progress, output, logs } = useJob({
-    api: '/api/durably',
+    baseUrl: '/api/durably',
     jobName: 'ai-agent',
   })
 
@@ -681,7 +750,7 @@ function TaskPage() {
   const runId = searchParams.get('runId')
 
   const { trigger, status, output } = useJob({
-    api: '/api/durably',
+    baseUrl: '/api/durably',
     jobName: 'process-task',
     initialRunId: runId ?? undefined,  // 既存 Run を再購読
   })
@@ -702,15 +771,76 @@ function TaskPage() {
 }
 ```
 
+### Run 一覧ダッシュボード
+
+```tsx
+import { useRuns } from '@coji/durably-react'
+
+function Dashboard() {
+  const {
+    runs,
+    isLoading,
+    page,
+    hasMore,
+    nextPage,
+    prevPage,
+    refresh,
+    retry,
+    cancel,
+  } = useRuns({ limit: 10 })
+
+  return (
+    
      
+      
+
+      
+        
+          
+            
+            
+            
+            
+          
+        
+        
+          {runs.map((run) => (
+            
+              
+              
+              
+              
+            
+          ))}
+        
+      
      IDJobStatusActions
      {run.id}{run.jobName}{run.status}
+                {run.status === 'failed' && (
+                  
+                )}
+                {run.status === 'pending' && (
+                  
+                )}
+              
      
+
+      
      
+        
+        Page {page + 1}
+        
+      
      
+    
      
+  )
+}
+```
+
 ---
 
 ## 内部実装指針
 
 ### ブラウザ完結モード
 
-- `DurablyProvider` で `createDurably()` → `migrate()` → `start()`
+- `DurablyProvider` で渡された `durably` インスタンスを Context に保持
+- `autoStart=true` の場合、マウント時に `durably.start()` を呼び出し
 - `useJob` は `durably.on()` でイベント購読
-- アンマウント時に `stop()` とリスナー解除
+- アンマウント時にリスナー解除
 
 ### サーバー連携モード
 
@@ -725,27 +855,6 @@ function TaskPage() {
 
 ---
 
-## Durably コア側の要件
-
-### 既存（実装済み）
-
-- `durably.on()` が unsubscribe 関数を返す
-- `durably.register({ name: jobDef })` で JobHandle のオブジェクトを取得
-
-### 新規（サーバー連携用）
-
-1. **`durably.subscribe(runId): ReadableStream`**
-   - Run のイベントを ReadableStream で返す
-   - SSE に変換可能
-
-2. **`durably.getJob(jobName): JobHandle`**
-   - 登録済みジョブを名前で取得
-
-3. **`createDurablyHandler(durably)`** (`@coji/durably/server`)
-   - Web 標準の Request/Response を扱うヘルパー
-
----
-
 ## 将来拡張
 
 ### Streaming 対応
@@ -755,7 +864,7 @@ function TaskPage() {
 ```tsx
 // 将来
 const { trigger, chunks, fullText, isStreaming } = useJobStream({
-  api: '/api/durably',
+  baseUrl: '/api/durably',
   jobName: 'ai-chat',
 })
 ```
diff --git a/examples/browser-react-router-spa/app/lib/durably.ts b/examples/browser-react-router-spa/app/lib/durably.ts
index b806b292..111c7e10 100644
--- a/examples/browser-react-router-spa/app/lib/durably.ts
+++ b/examples/browser-react-router-spa/app/lib/durably.ts
@@ -1,84 +1,30 @@
 /**
  * Durably instance for browser-only mode
  *
- * This creates a singleton Durably instance that can be used
- * both by DurablyProvider and by clientAction for triggering jobs.
- *
- * IMPORTANT: Job definitions are exported from here to ensure the same
- * object references are used throughout the app. This prevents
- * "already registered with a different definition" errors.
+ * This creates a singleton Durably instance that is shared across the app.
  */
 
-import { createDurably, type Durably } from '@coji/durably'
+import { createDurably } from '@coji/durably'
 import { SQLocalKysely } from 'sqlocal/kysely'
 import { dataSyncJob, processImageJob } from './jobs'
 
-// Re-export job definitions to ensure consistent object references
-export { dataSyncJob, processImageJob }
-
 // SQLocal instance for SQLite WASM with OPFS
 export const sqlocal = new SQLocalKysely('example.sqlite3')
 
-// Singleton Durably instance (lazily initialized)
-let durablyInstance: Durably | null = null
-let durablyPromise: Promise | null = null
-
-/**
- * Get the shared Durably instance.
- * Creates and migrates on first call, returns cached instance thereafter.
- */
-export async function getDurably(): Promise {
-  if (durablyInstance) {
-    return durablyInstance
-  }
+// Create and configure durably instance
+const durably = createDurably({
+  dialect: sqlocal.dialect,
+  pollingInterval: 100,
+  heartbeatInterval: 500,
+  staleThreshold: 3000,
+})
 
-  if (!durablyPromise) {
-    durablyPromise = (async () => {
-      const instance = createDurably({
-        dialect: sqlocal.dialect,
-        pollingInterval: 100,
-        heartbeatInterval: 500,
-        staleThreshold: 3000,
-      })
-      await instance.migrate()
+await durably.migrate()
 
-      // Pre-register jobs immediately after migration
-      // This ensures they're registered before any component tries to use them
-      instance.register({
-        processImage: processImageJob,
-        dataSync: dataSyncJob,
-      })
+// Register jobs - populates durably.jobs
+durably.register({
+  processImage: processImageJob,
+  dataSync: dataSyncJob,
+})
 
-      durablyInstance = instance
-      return instance
-    })()
-  }
-
-  return durablyPromise
-}
-
-/**
- * Trigger a job by name.
- * This uses the shared durably instance and its registered jobs.
- */
-export async function triggerJob(
-  jobName: 'processImage',
-  payload: T,
-): Promise<{ id: string }>
-export async function triggerJob(
-  jobName: 'dataSync',
-  payload: T,
-): Promise<{ id: string }>
-export async function triggerJob(
-  jobName: 'processImage' | 'dataSync',
-  payload: Record,
-): Promise<{ id: string }> {
-  const durably = await getDurably()
-  const jobHandle = durably.getJob(
-    jobName === 'processImage' ? 'process-image' : 'data-sync',
-  )
-  if (!jobHandle) {
-    throw new Error(`Job ${jobName} not found`)
-  }
-  return jobHandle.trigger(payload)
-}
+export { durably }
diff --git a/examples/browser-react-router-spa/app/root.tsx b/examples/browser-react-router-spa/app/root.tsx
index 18998443..6cabe198 100644
--- a/examples/browser-react-router-spa/app/root.tsx
+++ b/examples/browser-react-router-spa/app/root.tsx
@@ -9,7 +9,7 @@ import {
 } from 'react-router'
 import type { Route } from './+types/root'
 import './app.css'
-import { getDurably } from './lib/durably'
+import { durably } from './lib/durably'
 
 export function links() {
   return [
@@ -26,21 +26,6 @@ export function links() {
   ]
 }
 
-// clientLoader: Get shared durably instance
-export async function clientLoader() {
-  const durably = await getDurably()
-  return { durably }
-}
-
-// HydrateFallback: Show while clientLoader is running
-export function HydrateFallback() {
-  return (
-    
      
-      
      Loading...
      
-    
      
-  )
-}
-
 export function Layout({ children }: { children: React.ReactNode }) {
   return (
     
@@ -59,9 +44,9 @@ export function Layout({ children }: { children: React.ReactNode }) {
   )
 }
 
-export default function App({ loaderData }: Route.ComponentProps) {
+export default function App() {
   return (
-    
+    
       
     
   )
diff --git a/examples/browser-react-router-spa/app/routes/_index.tsx b/examples/browser-react-router-spa/app/routes/_index.tsx
index 076075cc..d1182dc7 100644
--- a/examples/browser-react-router-spa/app/routes/_index.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index.tsx
@@ -10,7 +10,8 @@
  */
 
 import { useState } from 'react'
-import { getDurably, sqlocal, triggerJob } from '~/lib/durably'
+import { Form } from 'react-router'
+import { durably, sqlocal } from '~/lib/durably'
 import { Dashboard } from './_index/dashboard'
 import { DataSyncForm } from './_index/data-sync-form'
 import { DataSyncProgress } from './_index/data-sync-progress'
@@ -32,29 +33,29 @@ export async function clientAction({ request }: { request: Request }) {
   if (intent === 'image') {
     const filename = formData.get('filename') as string
     const width = Number(formData.get('width'))
-    const run = await triggerJob('processImage', { filename, width })
+    const run = await durably.jobs.processImage.trigger({ filename, width })
     return { intent: 'image', runId: run.id }
   }
 
   if (intent === 'sync') {
     const userId = formData.get('userId') as string
-    const run = await triggerJob('dataSync', { userId })
+    const run = await durably.jobs.dataSync.trigger({ userId })
     return { intent: 'sync', runId: run.id }
   }
 
+  if (intent === 'reset') {
+    await durably.stop()
+    await sqlocal.deleteDatabaseFile()
+    location.reload()
+    return null
+  }
+
   return null
 }
 
 export default function Index() {
   const [activeJob, setActiveJob] = useState<'image' | 'sync'>('image')
 
-  const handleReset = async () => {
-    const durably = await getDurably()
-    await durably.stop()
-    await sqlocal.deleteDatabaseFile()
-    location.reload()
-  }
-
   return (
     
      
       
      
@@ -82,24 +83,27 @@ export default function Index() {
                   >
                     Reload
                   
-                  
+                  
      
+                    
+                  
      
                 
      
               
      
 
-              
      
+              
      
                 
-        
      
-      
-
-      {showInfo && (
-        
      
-          
      
-            This example uses @coji/durably-react for seamless
-            React integration:
+    
      
+      
      
+        
      
+          
      
+            Durably - Browser-Only Vite React
+          
      
+          
      
+            Pure React with Vite and Tailwind CSS
           
      
-          
        
-            
      • 
-              DurablyProvider - Context provider for Durably
-              instance
-            
        • 
-            
      • 
-              useJob - Hook for triggering jobs and real-time
-              status updates
-            
        • 
-            
      • 
-              useDurably - Direct access to Durably instance
-            
        • 
-          
      
-        
      
-      )}
-
-      
      
-        
-        
-        
-      
      
+        
+
+        
      
+          {/* Left: Job Trigger + Progress */}
+          
      
+            {/* Job Selection */}
+            
      
+              
      
+                
      Run Job
      
+                
      
+                  
+                  
+                
      
+              
      
 
-      
      
-        
      
-          
      Job Status
      
-          
      
-            
      
-              Status: {statusText}
-            
      
-            {progress && (
-              
      
-                Progress: {progress.current}
-                {progress.total ? `/${progress.total}` : ''}{' '}
-                {progress.message || ''}
+              
      
+                
+                
               
      
+
+              {activeJob === 'image' ? (
+                
+              ) : (
+                
+              )}
+            
      
+
+            {/* Progress Display */}
+            {activeJob === 'image' ? (
+              
+            ) : (
+              
             )}
           
      
 
-          {output && (
-            
      -              {JSON.stringify(output, null, 2)}
-            
      
-          )}
-
-          {error && 
      {error}
      }
-
-          {logs.length > 0 && (
-            
      
-              Logs:
-              
        
-                {logs.map((log: LogEntry) => (
-                  
      • 
-                    [{log.level}] {log.message}
-                  
        • 
-                ))}
-              
      
-            
      
-          )}
-        
      
-
-        
      
+          {/* Right: Dashboard */}
           
         
      
+
+        
      
+          
      
+            All data is stored locally in your browser using SQLite WASM with
+            OPFS.
+          
      
+          
      
+            Try reloading the page during job execution - it will resume
+            automatically!
+          
      
+        
      
       
      
     
      
   )
@@ -189,15 +163,7 @@ function AppContent() {
 
 function Loading() {
   return (
-    
      
+    
      
       Loading...
     
      
   )
diff --git a/examples/browser-vite-react/src/Dashboard.tsx b/examples/browser-vite-react/src/Dashboard.tsx
deleted file mode 100644
index f6adc429..00000000
--- a/examples/browser-vite-react/src/Dashboard.tsx
+++ /dev/null
@@ -1,333 +0,0 @@
-/**
- * Dashboard Component for Durably React Example
- *
- * Displays run history with status, details, and action buttons.
- * Uses useRuns hook for pagination and real-time updates.
- */
-
-import type { Run } from '@coji/durably'
-import { useDurably, useRuns } from '@coji/durably-react'
-import { useState } from 'react'
-
-// Styles
-const styles = {
-  table: {
-    width: '100%',
-    borderCollapse: 'collapse' as const,
-    fontSize: '0.875rem',
-  },
-  th: {
-    padding: '0.5rem',
-    textAlign: 'left' as const,
-    borderBottom: '1px solid #e0e0e0',
-    background: '#f5f5f5',
-  },
-  td: {
-    padding: '0.5rem',
-    textAlign: 'left' as const,
-    borderBottom: '1px solid #e0e0e0',
-  },
-  badge: (status: string) => ({
-    display: 'inline-block',
-    padding: '0.125rem 0.5rem',
-    borderRadius: '9999px',
-    fontSize: '0.75rem',
-    fontWeight: 500,
-    background:
-      status === 'pending'
-        ? '#fff3cd'
-        : status === 'running'
-          ? '#cce5ff'
-          : status === 'completed'
-            ? '#d4edda'
-            : status === 'failed'
-              ? '#f8d7da'
-              : '#e2e3e5',
-    color:
-      status === 'pending'
-        ? '#856404'
-        : status === 'running'
-          ? '#004085'
-          : status === 'completed'
-            ? '#155724'
-            : status === 'failed'
-              ? '#721c24'
-              : '#383d41',
-  }),
-  runId: { fontFamily: 'monospace', fontSize: '0.75rem', color: '#666' },
-  actionBtn: {
-    padding: '0.25rem 0.5rem',
-    fontSize: '0.75rem',
-    marginLeft: '0.25rem',
-    cursor: 'pointer',
-  },
-  details: {
-    marginTop: '1.5rem',
-    padding: '1rem',
-    background: '#f9f9f9',
-    borderRadius: '4px',
-  },
-  result: {
-    background: '#f5f5f5',
-    padding: '1rem',
-    borderRadius: '4px',
-    fontFamily: 'monospace',
-    whiteSpace: 'pre-wrap' as const,
-  },
-  stepsList: { listStyle: 'none', padding: 0, margin: 0 },
-  stepsItem: {
-    padding: '0.5rem',
-    borderBottom: '1px solid #e0e0e0',
-    display: 'flex',
-    justifyContent: 'space-between',
-  },
-}
-
-export function Dashboard() {
-  const { durably } = useDurably()
-  const { runs, page, hasMore, refresh, nextPage, prevPage } = useRuns({
-    pageSize: 10,
-  })
-
-  const [selectedRun, setSelectedRun] = useState(null)
-  const [steps, setSteps] = useState<
-    { index: number; name: string; status: string }[]
-  >([])
-
-  const showDetails = async (runId: string) => {
-    if (!durably) return
-    const run = await durably.getRun(runId)
-    if (run) {
-      setSelectedRun(run)
-      const stepsData = await durably.storage.getSteps(runId)
-      setSteps(
-        stepsData.map((s, i) => ({ index: i, name: s.name, status: s.status })),
-      )
-    }
-  }
-
-  const handleRetry = async (runId: string) => {
-    if (!durably) return
-    await durably.retry(runId)
-    refresh()
-  }
-
-  const handleCancel = async (runId: string) => {
-    if (!durably) return
-    await durably.cancel(runId)
-    refresh()
-  }
-
-  const handleDelete = async (runId: string) => {
-    if (!durably) return
-    await durably.deleteRun(runId)
-    setSelectedRun(null)
-    refresh()
-  }
-
-  const formatDate = (iso: string) => new Date(iso).toLocaleString()
-
-  return (
-    
      
-      
      
-        
      Runs
      
-        
-      
      
-
-      
-        
-          
-            
-            
-            
-            
-            
-          
-        
-        
-          {runs.length === 0 ? (
-            
-              
-            
-          ) : (
-            runs.map((run) => (
-              
-                
-                
-                
-                
-                
-              
-            ))
-          )}
-        
-      
      IDJobStatusCreatedActions
      
-                No runs yet
-              
      
-                  {run.id.slice(0, 8)}...
-                {run.jobName}
-                  {run.status}
-                {formatDate(run.createdAt)}
-                  
-                  {run.status === 'failed' && (
-                    
-                  )}
-                  {(run.status === 'running' || run.status === 'pending') && (
-                    
-                  )}
-                  {run.status !== 'running' && run.status !== 'pending' && (
-                    
-                  )}
-                
      
-
-      {(page > 0 || hasMore) && (
-        
      
-          
-          Page {page + 1}
-          
-        
      
-      )}
-
-      {selectedRun && (
-        
      
-          
      Run Details
      
-          
      
-            ID:{' '}
-            {selectedRun.id}
-          
      
-          
      
-            Job: {selectedRun.jobName}
-          
      
-          
      
-            Status:{' '}
-            
-              {selectedRun.status}
-            
-          
      
-          
      
-            Created: {formatDate(selectedRun.createdAt)}
-          
      
-          {selectedRun.progress && (
-            
      
-              Progress: {selectedRun.progress.current}
-              {selectedRun.progress.total
-                ? `/${selectedRun.progress.total}`
-                : ''}{' '}
-              {selectedRun.progress.message || ''}
-            
      
-          )}
-          {selectedRun.error && (
-            
      
-              Error:{' '}
-              {selectedRun.error}
-            
      
-          )}
-          {selectedRun.output !== null && (
-            <>
-              
      
-                Output:
-              
      
-              
      -                {JSON.stringify(selectedRun.output, null, 2)}
-              
      
-            
-          )}
-          
      
-            Payload:
-          
      
-          
      -            {JSON.stringify(selectedRun.payload, null, 2)}
-          
      
-          {steps.length > 0 && (
-            <>
-              
      
-                Steps:
-              
      
-              
        
-                {steps.map((s) => (
-                  
      • 
-                    {s.name}
-                    
-                      {s.status}
-                    
-                  
        • 
-                ))}
-              
      
-            
-          )}
-        
      
-      )}
-    
      
-  )
-}
diff --git a/examples/browser-vite-react/src/app.css b/examples/browser-vite-react/src/app.css
new file mode 100644
index 00000000..f3902dce
--- /dev/null
+++ b/examples/browser-vite-react/src/app.css
@@ -0,0 +1,12 @@
+@import 'tailwindcss';
+
+@theme {
+  --font-sans:
+    'Inter', ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji',
+    'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji';
+}
+
+html,
+body {
+  @apply bg-gray-50;
+}
diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
new file mode 100644
index 00000000..c21d6266
--- /dev/null
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -0,0 +1,293 @@
+/**
+ * Dashboard Component
+ *
+ * Displays run history with real-time updates and pagination.
+ * Uses browser-only mode hooks for direct durably access.
+ */
+
+import type { Run } from '@coji/durably'
+import { useDurably, useRuns } from '@coji/durably-react'
+import { useState } from 'react'
+
+export function Dashboard() {
+  const { durably } = useDurably()
+  const { runs, page, hasMore, refresh, nextPage, prevPage } = useRuns({
+    pageSize: 6,
+  })
+
+  const [selectedRun, setSelectedRun] = useState(null)
+  const [steps, setSteps] = useState<
+    { index: number; name: string; status: string }[]
+  >([])
+
+  const showDetails = async (runId: string) => {
+    if (!durably) return
+    const run = await durably.getRun(runId)
+    if (run) {
+      setSelectedRun(run)
+      const stepsData = await durably.storage.getSteps(runId)
+      setSteps(
+        stepsData.map((s, i) => ({ index: i, name: s.name, status: s.status })),
+      )
+    }
+  }
+
+  const handleRetry = async (runId: string) => {
+    if (!durably) return
+    await durably.retry(runId)
+    refresh()
+  }
+
+  const handleCancel = async (runId: string) => {
+    if (!durably) return
+    await durably.cancel(runId)
+    refresh()
+  }
+
+  const handleDelete = async (runId: string) => {
+    if (!durably) return
+    await durably.deleteRun(runId)
+    setSelectedRun(null)
+    refresh()
+  }
+
+  const formatDate = (iso: string) => new Date(iso).toLocaleString()
+
+  const statusClasses: Record = {
+    pending: 'bg-yellow-100 text-yellow-800',
+    running: 'bg-blue-100 text-blue-800',
+    completed: 'bg-green-100 text-green-800',
+    failed: 'bg-red-100 text-red-800',
+    cancelled: 'bg-gray-100 text-gray-800',
+  }
+
+  return (
+    
      
+      
      
+        
      Run History
      
+        
+      
      
+
+      {runs.length === 0 ? (
+        
      No runs yet
      
+      ) : (
+        <>
+          
      
+            
+              
+                
+                  
+                  
+                  
+                  
+                  
+                
+              
+              
+                {runs.map((run) => (
+                  
+                    
+                    
+                    
+                    
+                    
+                  
+                ))}
+              
+            
      
+                    ID
+                  
+                    Job
+                  
+                    Status
+                  
+                    Created
+                  
+                    Actions
+                  
      
+                      {run.id.slice(0, 8)}...
+                    {run.jobName}
+                      
+                        {run.status}
+                      
+                    
+                      {formatDate(run.createdAt)}
+                    
+                      
      
+                        
+                        {run.status === 'failed' && (
+                          
+                        )}
+                        {(run.status === 'running' ||
+                          run.status === 'pending') && (
+                          
+                        )}
+                        {run.status !== 'running' &&
+                          run.status !== 'pending' && (
+                            
+                          )}
+                      
      
+                    
      
+          
      
+
+          {/* Pagination */}
+          
      
+            
+            Page {page + 1}
+            
+          
      
+        
+      )}
+
+      {/* Run Details Modal */}
+      {selectedRun && (
+        
      
+          
      
+            
      
+              
      
+                
      Run Details
      
+                
+              
      
+
+              
      
+                
      
+                  ID:{' '}
+                  
+                    {selectedRun.id}
+                  
+                
      
+                
      
+                  Job:{' '}
+                  {selectedRun.jobName}
+                
      
+                
      
+                  Status:{' '}
+                  
+                    {selectedRun.status}
+                  
+                
      
+                
      
+                  Created:{' '}
+                  {formatDate(selectedRun.createdAt)}
+                
      
+
+                {selectedRun.progress && (
+                  
      
+                    Progress:{' '}
+                    {selectedRun.progress.current}
+                    {selectedRun.progress.total
+                      ? `/${selectedRun.progress.total}`
+                      : ''}{' '}
+                    {selectedRun.progress.message || ''}
+                  
      
+                )}
+
+                {selectedRun.error && (
+                  
      
+                    Error:{' '}
+                    {selectedRun.error}
+                  
      
+                )}
+
+                {selectedRun.output !== null && (
+                  
      
+                    Output:
+                    
      +                      {JSON.stringify(selectedRun.output, null, 2)}
+                    
      
+                  
      
+                )}
+
+                
      
+                  Payload:
+                  
      +                    {JSON.stringify(selectedRun.payload, null, 2)}
+                  
      
+                
      
+
+                {steps.length > 0 && (
+                  
      
+                    Steps:
+                    
        
+                      {steps.map((s) => (
+                        
      • 
+                          {s.name}
+                          
+                            {s.status}
+                          
+                        
        • 
+                      ))}
+                    
      
+                  
      
+                )}
+              
      
+            
      
+          
      
+        
      
+      )}
+    
      
+  )
+}
diff --git a/examples/browser-vite-react/src/components/data-sync-form.tsx b/examples/browser-vite-react/src/components/data-sync-form.tsx
new file mode 100644
index 00000000..68f051a9
--- /dev/null
+++ b/examples/browser-vite-react/src/components/data-sync-form.tsx
@@ -0,0 +1,57 @@
+/**
+ * Data Sync Form Component
+ *
+ * Form for triggering data sync jobs.
+ */
+
+import { useState } from 'react'
+
+interface DataSyncFormProps {
+  onSubmit: (data: { userId: string }) => void
+  isSubmitting: boolean
+  runId: string | null
+}
+
+export function DataSyncForm({
+  onSubmit,
+  isSubmitting,
+  runId,
+}: DataSyncFormProps) {
+  const [userId, setUserId] = useState('user_123')
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    onSubmit({ userId })
+  }
+
+  return (
+    
      
+      
      
+        
+         setUserId(e.target.value)}
+          className="border border-gray-300 rounded-md px-3 py-2 w-full focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+        />
+      
      
+      
+      {runId && (
+        
      
+          Triggered: {runId.slice(0, 8)}
+        
      
+      )}
+    
      
+  )
+}
diff --git a/examples/browser-vite-react/src/components/data-sync-progress.tsx b/examples/browser-vite-react/src/components/data-sync-progress.tsx
new file mode 100644
index 00000000..0820710d
--- /dev/null
+++ b/examples/browser-vite-react/src/components/data-sync-progress.tsx
@@ -0,0 +1,39 @@
+/**
+ * Data Sync Progress Component
+ *
+ * Displays progress for the data sync job.
+ */
+
+import { useJob } from '@coji/durably-react'
+import { dataSyncJob } from '../jobs'
+import { RunProgress } from './run-progress'
+
+interface DataSyncProgressProps {
+  runId?: string
+}
+
+export function DataSyncProgress({ runId }: DataSyncProgressProps) {
+  const {
+    progress,
+    output,
+    error,
+    logs,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJob(dataSyncJob, { initialRunId: runId })
+
+  return (
+    
+  )
+}
diff --git a/examples/browser-vite-react/src/components/image-processing-form.tsx b/examples/browser-vite-react/src/components/image-processing-form.tsx
new file mode 100644
index 00000000..574340c3
--- /dev/null
+++ b/examples/browser-vite-react/src/components/image-processing-form.tsx
@@ -0,0 +1,75 @@
+/**
+ * Image Processing Form Component
+ *
+ * Form for triggering image processing jobs.
+ */
+
+import { useState } from 'react'
+
+interface ImageProcessingFormProps {
+  onSubmit: (data: { filename: string; width: number }) => void
+  isSubmitting: boolean
+  runId: string | null
+}
+
+export function ImageProcessingForm({
+  onSubmit,
+  isSubmitting,
+  runId,
+}: ImageProcessingFormProps) {
+  const [filename, setFilename] = useState('photo.jpg')
+  const [width, setWidth] = useState(800)
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault()
+    onSubmit({ filename, width })
+  }
+
+  return (
+    
      
+      
      
+        
+         setFilename(e.target.value)}
+          className="border border-gray-300 rounded-md px-3 py-2 w-full focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+        />
+      
      
+      
      
+        
+         setWidth(Number(e.target.value))}
+          min={100}
+          max={4000}
+          className="border border-gray-300 rounded-md px-3 py-2 w-full focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
+        />
+      
      
+      
+      {runId && (
+        
      
+          Triggered: {runId.slice(0, 8)}
+        
      
+      )}
+    
      
+  )
+}
diff --git a/examples/browser-vite-react/src/components/image-processing-progress.tsx b/examples/browser-vite-react/src/components/image-processing-progress.tsx
new file mode 100644
index 00000000..02ac09a8
--- /dev/null
+++ b/examples/browser-vite-react/src/components/image-processing-progress.tsx
@@ -0,0 +1,41 @@
+/**
+ * Image Processing Progress Component
+ *
+ * Displays progress for the image processing job.
+ */
+
+import { useJob } from '@coji/durably-react'
+import { processImageJob } from '../jobs'
+import { RunProgress } from './run-progress'
+
+interface ImageProcessingProgressProps {
+  runId?: string
+}
+
+export function ImageProcessingProgress({
+  runId,
+}: ImageProcessingProgressProps) {
+  const {
+    progress,
+    output,
+    error,
+    logs,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJob(processImageJob, { initialRunId: runId })
+
+  return (
+    
+  )
+}
diff --git a/examples/browser-vite-react/src/components/index.ts b/examples/browser-vite-react/src/components/index.ts
new file mode 100644
index 00000000..584908b5
--- /dev/null
+++ b/examples/browser-vite-react/src/components/index.ts
@@ -0,0 +1,10 @@
+/**
+ * Component Exports
+ */
+
+export { Dashboard } from './dashboard'
+export { DataSyncForm } from './data-sync-form'
+export { DataSyncProgress } from './data-sync-progress'
+export { ImageProcessingForm } from './image-processing-form'
+export { ImageProcessingProgress } from './image-processing-progress'
+export { RunProgress } from './run-progress'
diff --git a/examples/browser-vite-react/src/components/run-progress.tsx b/examples/browser-vite-react/src/components/run-progress.tsx
new file mode 100644
index 00000000..55f5f094
--- /dev/null
+++ b/examples/browser-vite-react/src/components/run-progress.tsx
@@ -0,0 +1,113 @@
+/**
+ * RunProgress Component
+ *
+ * Displays real-time progress and result for browser-only jobs.
+ */
+
+import type { LogEntry } from '@coji/durably-react'
+
+interface RunProgressProps {
+  progress: { current: number; total?: number; message?: string } | null
+  output: unknown
+  error: string | null
+  logs: LogEntry[]
+  isPending: boolean
+  isRunning: boolean
+  isCompleted: boolean
+  isFailed: boolean
+}
+
+export function RunProgress({
+  progress,
+  output,
+  error,
+  logs,
+  isPending,
+  isRunning,
+  isCompleted,
+  isFailed,
+}: RunProgressProps) {
+  // Don't render anything if no activity
+  if (!isPending && !isRunning && !isCompleted && !isFailed) {
+    return null
+  }
+
+  return (
+    <>
+      {/* Pending State */}
+      {isPending && (
+        
      
+          
      Waiting to start...
      
+        
      
+      )}
+
+      {/* Progress Display */}
+      {isRunning && progress && (
+        
      
+          
      
+            Progress
+            
+              {progress.current}/{progress.total || '?'}
+            
+          
      
+          
      
+            
      
+          
      
+          {progress.message && (
+            
      {progress.message}
      
+          )}
+        
      
+      )}
+
+      {/* Success Result */}
+      {isCompleted && output !== null && output !== undefined && (
+        
      
+          
      Completed!
      
+          
      +            {JSON.stringify(output, null, 2)}
+          
      
+        
      
+      )}
+
+      {/* Error Result */}
+      {isFailed && (
+        
      
+          
      Failed
      
+          
      {error}
      
+        
      
+      )}
+
+      {/* Logs */}
+      {logs.length > 0 && (
+        
      
+          
      Logs
      
+          
      
+            
        
+              {logs.map((log) => (
+                
      • 
+                  
+                    [{log.level}]
+                  {' '}
+                  {log.message}
+                
        • 
+              ))}
+            
      
+          
      
+        
      
+      )}
+    
+  )
+}
diff --git a/examples/browser-vite-react/src/durably.ts b/examples/browser-vite-react/src/durably.ts
deleted file mode 100644
index bd802b9e..00000000
--- a/examples/browser-vite-react/src/durably.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-/**
- * Durably instance for browser-only mode
- *
- * This creates a singleton Durably instance that is shared across the app.
- */
-
-import { createDurably } from '@coji/durably'
-import { SQLocalKysely } from 'sqlocal/kysely'
-import { processImageJob } from './jobs/processImage'
-
-// Re-export job definition to ensure consistent object reference
-export { processImageJob }
-
-// SQLocal instance for SQLite WASM with OPFS
-export const sqlocal = new SQLocalKysely('example.sqlite3')
-
-async function initDurably() {
-  // Create and configure durably instance with chained register()
-  const instance = createDurably({
-    dialect: sqlocal.dialect,
-    pollingInterval: 100,
-    heartbeatInterval: 500,
-    staleThreshold: 3000,
-  }).register({ processImage: processImageJob })
-
-  await instance.migrate()
-  return instance
-}
-
-/**
- * Shared Durably instance promise.
- * Can be passed directly to DurablyProvider.
- */
-export const durably = initDurably()
diff --git a/examples/browser-vite-react/src/jobs/data-sync.ts b/examples/browser-vite-react/src/jobs/data-sync.ts
new file mode 100644
index 00000000..1a3e9ebc
--- /dev/null
+++ b/examples/browser-vite-react/src/jobs/data-sync.ts
@@ -0,0 +1,56 @@
+/**
+ * Data Sync Job
+ *
+ * Simulates syncing data with a remote server.
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const dataSyncJob = defineJob({
+  name: 'data-sync',
+  input: z.object({ userId: z.string() }),
+  output: z.object({ synced: z.number(), failed: z.number() }),
+  run: async (step, payload) => {
+    step.log.info(`Starting sync for user: ${payload.userId}`)
+
+    const items = await step.run('fetch-local', async () => {
+      step.progress(1, 4, 'Fetching local data...')
+      await delay(300)
+      return Array.from({ length: 10 }, (_, i) => ({
+        id: `item-${i}`,
+        data: `Data for ${payload.userId}`,
+      }))
+    })
+
+    let synced = 0
+    let failed = 0
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]
+      const success = await step.run(`sync-item-${item.id}`, async () => {
+        step.progress(2 + Math.floor(i / 5), 4, `Syncing item ${i + 1}...`)
+        await delay(100)
+        return Math.random() > 0.1 // 90% success rate
+      })
+
+      if (success) {
+        synced++
+      } else {
+        failed++
+        step.log.warn(`Failed to sync item: ${item.id}`)
+      }
+    }
+
+    await step.run('finalize', async () => {
+      step.progress(4, 4, 'Finalizing...')
+      await delay(200)
+    })
+
+    step.log.info(`Sync complete: ${synced} synced, ${failed} failed`)
+
+    return { synced, failed }
+  },
+})
diff --git a/examples/browser-vite-react/src/jobs/index.ts b/examples/browser-vite-react/src/jobs/index.ts
new file mode 100644
index 00000000..404d49a4
--- /dev/null
+++ b/examples/browser-vite-react/src/jobs/index.ts
@@ -0,0 +1,9 @@
+/**
+ * Job Definitions
+ *
+ * Barrel export for all job definitions.
+ * When adding a new job, import and add it here.
+ */
+
+export { dataSyncJob } from './data-sync'
+export { processImageJob } from './process-image'
diff --git a/examples/browser-vite-react/src/jobs/processImage.ts b/examples/browser-vite-react/src/jobs/process-image.ts
similarity index 89%
rename from examples/browser-vite-react/src/jobs/processImage.ts
rename to examples/browser-vite-react/src/jobs/process-image.ts
index abb3e93f..621a81be 100644
--- a/examples/browser-vite-react/src/jobs/processImage.ts
+++ b/examples/browser-vite-react/src/jobs/process-image.ts
@@ -1,8 +1,7 @@
 /**
  * Process Image Job
  *
- * Example job that simulates image processing with multiple steps.
- * This is a standalone job definition - registration happens in DurablyProvider.
+ * Simulates image processing with multiple steps.
  */
 
 import { defineJob } from '@coji/durably'
diff --git a/examples/browser-vite-react/src/lib/database.ts b/examples/browser-vite-react/src/lib/database.ts
new file mode 100644
index 00000000..5443dec3
--- /dev/null
+++ b/examples/browser-vite-react/src/lib/database.ts
@@ -0,0 +1,9 @@
+/**
+ * Database Configuration
+ *
+ * SQLocal instance for SQLite WASM with OPFS backend.
+ */
+
+import { SQLocalKysely } from 'sqlocal/kysely'
+
+export const sqlocal = new SQLocalKysely('example.sqlite3')
diff --git a/examples/browser-vite-react/src/lib/durably.ts b/examples/browser-vite-react/src/lib/durably.ts
new file mode 100644
index 00000000..4d221967
--- /dev/null
+++ b/examples/browser-vite-react/src/lib/durably.ts
@@ -0,0 +1,25 @@
+/**
+ * Durably instance for browser-only mode
+ *
+ * This creates a singleton Durably instance that is shared across the app.
+ */
+
+import { createDurably } from '@coji/durably'
+import { dataSyncJob, processImageJob } from '../jobs'
+import { sqlocal } from './database'
+
+// Create and configure durably instance with chained register()
+// register() returns a new Durably instance with type-safe jobs
+const durably = createDurably({
+  dialect: sqlocal.dialect,
+  pollingInterval: 100,
+  heartbeatInterval: 500,
+  staleThreshold: 3000,
+}).register({
+  processImage: processImageJob,
+  dataSync: dataSyncJob,
+})
+
+await durably.migrate()
+
+export { durably }
diff --git a/examples/browser-vite-react/src/main.tsx b/examples/browser-vite-react/src/main.tsx
index 983f944e..38b875fd 100644
--- a/examples/browser-vite-react/src/main.tsx
+++ b/examples/browser-vite-react/src/main.tsx
@@ -1,6 +1,7 @@
 import { StrictMode } from 'react'
 import { createRoot } from 'react-dom/client'
 import { App } from './App'
+import './app.css'
 
 createRoot(document.getElementById('root') as HTMLElement).render(
   
diff --git a/examples/browser-vite-react/src/styles.ts b/examples/browser-vite-react/src/styles.ts
deleted file mode 100644
index 3cb095d6..00000000
--- a/examples/browser-vite-react/src/styles.ts
+++ /dev/null
@@ -1,54 +0,0 @@
-/**
- * Shared styles for Durably React Example
- */
-
-export const styles = {
-  container: {
-    padding: '2rem',
-    fontFamily: 'system-ui',
-  },
-  header: {
-    display: 'flex',
-    justifyContent: 'space-between',
-    alignItems: 'center',
-    marginBottom: '1.5rem',
-  },
-  title: {
-    margin: 0,
-    fontSize: '1.5rem',
-  },
-  links: {
-    display: 'flex',
-    alignItems: 'center',
-    gap: '0.5rem',
-    fontSize: '0.875rem',
-  },
-  linkSeparator: {
-    color: '#999',
-  },
-  tabs: {
-    display: 'flex',
-    gap: 0,
-    marginBottom: '1.5rem',
-    borderBottom: '2px solid #e0e0e0',
-  },
-  tab: (active: boolean) => ({
-    padding: '0.75rem 1.5rem',
-    background: 'none',
-    border: 'none',
-    fontSize: '1rem',
-    cursor: 'pointer',
-    borderBottom: active ? '2px solid #007bff' : '2px solid transparent',
-    marginBottom: '-2px',
-    color: active ? '#007bff' : '#666',
-    fontWeight: active ? 500 : 400,
-  }),
-  buttons: { display: 'flex', gap: '1rem', marginBottom: '2rem' },
-  result: (isError: boolean) => ({
-    background: isError ? '#fee' : '#f5f5f5',
-    padding: '1rem',
-    borderRadius: '4px',
-    fontFamily: 'monospace',
-    whiteSpace: 'pre-wrap' as const,
-  }),
-}
diff --git a/examples/browser-vite-react/vite.config.ts b/examples/browser-vite-react/vite.config.ts
index d87cb90c..10e36a6f 100644
--- a/examples/browser-vite-react/vite.config.ts
+++ b/examples/browser-vite-react/vite.config.ts
@@ -1,8 +1,10 @@
+import tailwindcss from '@tailwindcss/vite'
 import react from '@vitejs/plugin-react'
 import { defineConfig } from 'vite'
 
 export default defineConfig({
   plugins: [
+    tailwindcss(),
     react(),
     {
       name: 'configure-response-headers',
diff --git a/examples/fullstack-react-router/app/jobs/index.ts b/examples/fullstack-react-router/app/jobs/index.ts
index 8e309e9f..dbc665ba 100644
--- a/examples/fullstack-react-router/app/jobs/index.ts
+++ b/examples/fullstack-react-router/app/jobs/index.ts
@@ -2,13 +2,7 @@
  * Job Definitions
  *
  * Barrel export for all job definitions.
+ * When adding a new job, import and add it here.
  */
 
-import { importCsvJob } from './import-csv'
-
-// Re-export types for use in components
-export type { ImportCsvOutput } from './import-csv'
-
-export const jobs = {
-  importCsv: importCsvJob,
-}
+export { importCsvJob, type ImportCsvOutput } from './import-csv'
diff --git a/examples/fullstack-react-router/app/lib/database.server.ts b/examples/fullstack-react-router/app/lib/database.server.ts
new file mode 100644
index 00000000..09ffa9db
--- /dev/null
+++ b/examples/fullstack-react-router/app/lib/database.server.ts
@@ -0,0 +1,12 @@
+/**
+ * Database Configuration
+ *
+ * libSQL dialect for server-side SQLite.
+ * Server-only - do not import in client code.
+ */
+
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+
+export const dialect = new LibsqlDialect({
+  url: process.env.DATABASE_URL ?? 'file:./local.db',
+})
diff --git a/examples/fullstack-react-router/app/lib/durably.server.ts b/examples/fullstack-react-router/app/lib/durably.server.ts
index 2cc77e2a..c28e5d33 100644
--- a/examples/fullstack-react-router/app/lib/durably.server.ts
+++ b/examples/fullstack-react-router/app/lib/durably.server.ts
@@ -3,46 +3,26 @@
  *
  * Sets up Durably instance, registers jobs, and provides HTTP handler.
  * Server-only - do not import in client code.
+ *
+ * Note: In development with HMR, this module may reload on changes.
+ * For production apps, consider using a singleton pattern to prevent
+ * multiple instances.
  */
 
 import { createDurably, createDurablyHandler } from '@coji/durably'
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-import { jobs } from '~/jobs'
-
-/**
- * HMR-safe singleton helper for React Router dev server.
- *
- * During development, React Router's HMR reloads this module on every change,
- * which would create new Durably/database instances each time. This helper
- * stores instances on globalThis to persist them across HMR reloads.
- *
- * In production, this just works as a normal singleton pattern.
- */
-function singleton(name: string, factory: () => T): T {
-  const g = globalThis as unknown as Record
-  if (g[name] === undefined) {
-    g[name] = factory()
-  }
-  return g[name]
-}
+import { importCsvJob } from '~/jobs'
+import { dialect } from './database.server'
 
-// Durably instance with registered jobs
-export const durably = singleton('__durably', () =>
-  createDurably({
-    dialect: new LibsqlDialect({
-      url: process.env.DATABASE_URL ?? 'file:./local.db',
-    }),
-  }).register(jobs),
-)
+// Create Durably instance with registered jobs
+export const durably = createDurably({
+  dialect,
+}).register({
+  importCsv: importCsvJob,
+})
 
-// HTTP handler
-export const durablyHandler = singleton('__durablyHandler', () =>
-  createDurablyHandler(durably),
-)
+// HTTP handler for SSE streaming
+export const durablyHandler = createDurablyHandler(durably)
 
-// Initialize on first load
-singleton('__durablyInitialized', async () => {
-  await durably.migrate()
-  durably.start()
-  return true
-})
+// Initialize database and start worker
+await durably.migrate()
+durably.start()
diff --git a/examples/fullstack-react-router/package.json b/examples/fullstack-react-router/package.json
index 5be7b81e..d3742b96 100644
--- a/examples/fullstack-react-router/package.json
+++ b/examples/fullstack-react-router/package.json
@@ -22,7 +22,7 @@
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-router": "7.11.0",
-    "zod": "^4.2.1"
+    "zod": "^4.3.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
diff --git a/examples/server-node/basic.ts b/examples/server-node/basic.ts
index 2ca5756c..2368a78b 100644
--- a/examples/server-node/basic.ts
+++ b/examples/server-node/basic.ts
@@ -5,51 +5,7 @@
  * Same job definition as browser/react examples for comparison.
  */
 
-import { createDurably, defineJob } from '@coji/durably'
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-import { z } from 'zod'
-
-// Turso の場合は環境変数から URL と authToken を取得
-// ローカル開発では file:local.db を使用
-const dialect = new LibsqlDialect({
-  url: process.env.TURSO_DATABASE_URL ?? 'file:local.db',
-  authToken: process.env.TURSO_AUTH_TOKEN,
-})
-
-// Create durably instance with chained register()
-const durably = createDurably({
-  dialect,
-  pollingInterval: 100,
-  heartbeatInterval: 500,
-  staleThreshold: 3000,
-}).register({
-  processImage: defineJob({
-    name: 'process-image',
-    input: z.object({ filename: z.string() }),
-    output: z.object({ url: z.string() }),
-    run: async (step, payload) => {
-      // Step 1: Download
-      const data = await step.run('download', async () => {
-        await new Promise((r) => setTimeout(r, 500))
-        return { size: 1024000 }
-      })
-
-      // Step 2: Resize
-      await step.run('resize', async () => {
-        await new Promise((r) => setTimeout(r, 500))
-        return { width: 800, height: 600, size: data.size / 2 }
-      })
-
-      // Step 3: Upload
-      const uploaded = await step.run('upload', async () => {
-        await new Promise((r) => setTimeout(r, 500))
-        return { url: `https://cdn.example.com/${payload.filename}` }
-      })
-
-      return { url: uploaded.url }
-    },
-  }),
-})
+import { durably } from './lib/durably'
 
 // Subscribe to events
 durably.on('run:start', (event) => {
diff --git a/examples/server-node/jobs/index.ts b/examples/server-node/jobs/index.ts
new file mode 100644
index 00000000..23b287c3
--- /dev/null
+++ b/examples/server-node/jobs/index.ts
@@ -0,0 +1,8 @@
+/**
+ * Job Definitions
+ *
+ * Barrel export for all job definitions.
+ * When adding a new job, import and add it here.
+ */
+
+export { processImageJob } from './process-image'
diff --git a/examples/server-node/jobs/process-image.ts b/examples/server-node/jobs/process-image.ts
new file mode 100644
index 00000000..aa5810a2
--- /dev/null
+++ b/examples/server-node/jobs/process-image.ts
@@ -0,0 +1,37 @@
+/**
+ * Process Image Job
+ *
+ * Simulates image processing with multiple steps.
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const processImageJob = defineJob({
+  name: 'process-image',
+  input: z.object({ filename: z.string() }),
+  output: z.object({ url: z.string() }),
+  run: async (step, payload) => {
+    // Step 1: Download
+    const data = await step.run('download', async () => {
+      await delay(500)
+      return { size: 1024000 }
+    })
+
+    // Step 2: Resize
+    await step.run('resize', async () => {
+      await delay(500)
+      return { width: 800, height: 600, size: data.size / 2 }
+    })
+
+    // Step 3: Upload
+    const uploaded = await step.run('upload', async () => {
+      await delay(500)
+      return { url: `https://cdn.example.com/${payload.filename}` }
+    })
+
+    return { url: uploaded.url }
+  },
+})
diff --git a/examples/server-node/lib/database.ts b/examples/server-node/lib/database.ts
new file mode 100644
index 00000000..17ade5cd
--- /dev/null
+++ b/examples/server-node/lib/database.ts
@@ -0,0 +1,13 @@
+/**
+ * Database Configuration
+ *
+ * libSQL/Turso dialect for server-side SQLite.
+ * Uses environment variables for Turso connection, falls back to local file.
+ */
+
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+
+export const dialect = new LibsqlDialect({
+  url: process.env.TURSO_DATABASE_URL ?? 'file:local.db',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+})
diff --git a/examples/server-node/lib/durably.ts b/examples/server-node/lib/durably.ts
new file mode 100644
index 00000000..e3368501
--- /dev/null
+++ b/examples/server-node/lib/durably.ts
@@ -0,0 +1,20 @@
+/**
+ * Durably Server Configuration
+ *
+ * Sets up Durably instance and registers jobs.
+ */
+
+import { createDurably } from '@coji/durably'
+import { processImageJob } from '../jobs'
+import { dialect } from './database'
+
+// Create and configure durably instance with chained register()
+// register() returns a new Durably instance with type-safe jobs
+export const durably = createDurably({
+  dialect,
+  pollingInterval: 100,
+  heartbeatInterval: 500,
+  staleThreshold: 3000,
+}).register({
+  processImage: processImageJob,
+})
diff --git a/examples/server-node/package.json b/examples/server-node/package.json
index f0a7c220..2f53477b 100644
--- a/examples/server-node/package.json
+++ b/examples/server-node/package.json
@@ -15,7 +15,7 @@
     "@libsql/client": "^0.15.15",
     "@libsql/kysely-libsql": "^0.4.1",
     "kysely": "^0.28.9",
-    "zod": "^4.2.1"
+    "zod": "^4.3.4"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.3.10",
diff --git a/package.json b/package.json
index 94b40b15..03b2937e 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,7 @@
     "@biomejs/biome": "^2.3.10",
     "@types/node": "^25.0.3",
     "@vitest/coverage-v8": "4.0.16",
-    "cc-hooks-ts": "2.0.70",
+    "cc-hooks-ts": "2.0.76",
     "tsx": "^4.21.0",
     "turbo": "2.7.2",
     "typescript": "^5.9.3"
diff --git a/packages/durably-react/package.json b/packages/durably-react/package.json
index 6338aa16..03d83bcf 100644
--- a/packages/durably-react/package.json
+++ b/packages/durably-react/package.json
@@ -77,6 +77,6 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
-    "zod": "^4.2.1"
+    "zod": "^4.3.4"
   }
 }
diff --git a/packages/durably/package.json b/packages/durably/package.json
index fd933114..5725000a 100644
--- a/packages/durably/package.json
+++ b/packages/durably/package.json
@@ -80,6 +80,6 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16",
-    "zod": "^4.2.1"
+    "zod": "^4.3.4"
   }
 }
diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts
index a9632df8..adf3289a 100644
--- a/packages/durably/src/durably.ts
+++ b/packages/durably/src/durably.ts
@@ -58,9 +58,8 @@ export interface DurablyPlugin {
 /**
  * Helper type to transform JobDefinition record to JobHandle record
  */
-// biome-ignore lint/suspicious/noExplicitAny: flexible type constraint for job definitions
 type TransformToHandles<
-  TJobs extends Record>,
+  TJobs extends Record>,
 > = {
   [K in keyof TJobs]: TJobs[K] extends JobDefinition<
     infer TName,
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index e77b18b7..e86daddf 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -4,9 +4,6 @@ settings:
   autoInstallPeers: true
   excludeLinksFromLockfile: false
 
-overrides:
-  zod: ^4.2.1
-
 importers:
 
   .:
@@ -21,8 +18,8 @@ importers:
         specifier: 4.0.16
         version: 4.0.16(@vitest/browser@4.0.16(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vitest@4.0.16))(vitest@4.0.16)
       cc-hooks-ts:
-        specifier: 2.0.70
-        version: 2.0.70(typescript@5.9.3)(zod@4.3.4)
+        specifier: 2.0.76
+        version: 2.0.76(typescript@5.9.3)(zod@4.3.4)
       tsx:
         specifier: ^4.21.0
         version: 4.21.0
@@ -63,7 +60,7 @@ importers:
         specifier: ^0.16.0
         version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3))
       zod:
-        specifier: ^4.2.1
+        specifier: ^4.3.4
         version: 4.3.4
     devDependencies:
       '@biomejs/biome':
@@ -124,12 +121,15 @@ importers:
         specifier: ^0.16.0
         version: 0.16.0(kysely@0.28.9)(react@19.2.3)(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))(vue@3.5.26(typescript@5.9.3))
       zod:
-        specifier: ^4.2.1
+        specifier: ^4.3.4
         version: 4.3.4
     devDependencies:
       '@biomejs/biome':
         specifier: ^2.3.10
         version: 2.3.10
+      '@tailwindcss/vite':
+        specifier: ^4.1.18
+        version: 4.1.18(vite@7.3.0(@types/node@25.0.3)(jiti@2.6.1)(lightningcss@1.30.2)(tsx@4.21.0))
       '@types/react':
         specifier: ^19.2.7
         version: 19.2.7
@@ -145,6 +145,9 @@ importers:
       prettier-plugin-organize-imports:
         specifier: ^4.3.0
         version: 4.3.0(prettier@3.7.4)(typescript@5.9.3)
+      tailwindcss:
+        specifier: ^4.1.18
+        version: 4.1.18
       typescript:
         specifier: ^5.9.3
         version: 5.9.3
@@ -182,7 +185,7 @@ importers:
         specifier: 7.11.0
         version: 7.11.0(react-dom@19.2.3(react@19.2.3))(react@19.2.3)
       zod:
-        specifier: ^4.2.1
+        specifier: ^4.3.4
         version: 4.3.4
     devDependencies:
       '@biomejs/biome':
@@ -237,7 +240,7 @@ importers:
         specifier: ^0.28.9
         version: 0.28.9
       zod:
-        specifier: ^4.2.1
+        specifier: ^4.3.4
         version: 4.3.4
     devDependencies:
       '@biomejs/biome':
@@ -326,7 +329,7 @@ importers:
         specifier: ^4.0.16
         version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.4.0)(lightningcss@1.30.2)(tsx@4.21.0)
       zod:
-        specifier: ^4.2.1
+        specifier: ^4.3.4
         version: 4.3.4
 
   packages/durably-react:
@@ -386,7 +389,7 @@ importers:
         specifier: ^4.0.16
         version: 4.0.16(@types/node@25.0.3)(@vitest/browser-playwright@4.0.16)(jiti@2.6.1)(jsdom@27.4.0)(lightningcss@1.30.2)(tsx@4.21.0)
       zod:
-        specifier: ^4.2.1
+        specifier: ^4.3.4
         version: 4.3.4
 
   website:
@@ -476,11 +479,11 @@ packages:
     resolution: {integrity: sha512-ciPihkletp7ttweJ8Zt+GukSVLp2ANJHU+9ttiSxsJZThXc4Y2yJ8HGVWesW5jN1zrsZsezN71KrMx/iZsOYpg==}
     engines: {node: '>= 14.0.0'}
 
-  '@anthropic-ai/claude-agent-sdk@0.1.70':
-    resolution: {integrity: sha512-4jpFPDX8asys6skO1r3Pzh0Fe9nbND2ASYTWuyFB5iN9bWEL6WScTFyGokjql3M2TkEp9ZGuB2YYpTCdaqT9Sw==}
+  '@anthropic-ai/claude-agent-sdk@0.1.76':
+    resolution: {integrity: sha512-s7RvpXoFaLXLG7A1cJBAPD8ilwOhhc/12fb5mJXRuD561o4FmPtQ+WRfuy9akMmrFRfLsKv8Ornw3ClGAPL2fw==}
     engines: {node: '>=18.0.0'}
     peerDependencies:
-      zod: ^4.2.1
+      zod: ^3.24.1 || ^4.0.0
 
   '@asamuzakjp/css-color@4.1.1':
     resolution: {integrity: sha512-B0Hv6G3gWGMn0xKJ0txEi/jM5iFpT3MfDxmhZFb4W047GvytCf1DHQ1D69W3zHI4yWe2aTZAA0JnbMZ7Xc8DuQ==}
@@ -1900,8 +1903,8 @@ packages:
   caniuse-lite@1.0.30001762:
     resolution: {integrity: sha512-PxZwGNvH7Ak8WX5iXzoK1KPZttBXNPuaOvI2ZYU7NrlM+d9Ov+TUvlLOBNGzVXAntMSMMlJPd+jY6ovrVjSmUw==}
 
-  cc-hooks-ts@2.0.70:
-    resolution: {integrity: sha512-VIUAEXw/huaTev21xlKjCpWso51vHRIuodGc6T0ihVyA7BXwmQHlfxBnhfsvYtTbo9xVsijSPIgwS7/flJOjAQ==}
+  cc-hooks-ts@2.0.76:
+    resolution: {integrity: sha512-5b4UyCiqCxUM4UfvWYASTP5DqdNsHuAq4Zyks5uNqgGs4DQo2BAhFTQG8g5vj4SqLXYaFjszBDtsGhi3lkAkCw==}
     engines: {node: ^20.12.0 || ^22.0.0 || >=24.0.0}
 
   ccount@2.0.1:
@@ -3430,7 +3433,7 @@ snapshots:
     dependencies:
       '@algolia/client-common': 5.46.2
 
-  '@anthropic-ai/claude-agent-sdk@0.1.70(zod@4.3.4)':
+  '@anthropic-ai/claude-agent-sdk@0.1.76(zod@4.3.4)':
     dependencies:
       zod: 4.3.4
     optionalDependencies:
@@ -4776,9 +4779,9 @@ snapshots:
 
   caniuse-lite@1.0.30001762: {}
 
-  cc-hooks-ts@2.0.70(typescript@5.9.3)(zod@4.3.4):
+  cc-hooks-ts@2.0.76(typescript@5.9.3)(zod@4.3.4):
     dependencies:
-      '@anthropic-ai/claude-agent-sdk': 0.1.70(zod@4.3.4)
+      '@anthropic-ai/claude-agent-sdk': 0.1.76(zod@4.3.4)
       valibot: 1.2.0(typescript@5.9.3)
     transitivePeerDependencies:
       - typescript
diff --git a/turbo.json b/turbo.json
index 27956396..adcdeaaf 100644
--- a/turbo.json
+++ b/turbo.json
@@ -3,7 +3,7 @@
   "tasks": {
     "build": {
       "dependsOn": ["^build"],
-      "outputs": ["dist/**", ".vitepress/dist/**"]
+      "outputs": ["dist/**", "build/**", ".vitepress/dist/**"]
     },
     "dev": {
       "dependsOn": ["^build"],

From 252f1b2581b7f231de058dd3889861cf86b30496 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 14:38:02 +0900
Subject: [PATCH 071/101] test(durably): add server.ts HTTP handler tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add comprehensive tests for createDurablyHandler covering:
- handle() routing for all endpoints
- trigger() with validation and error cases
- runs() and run() with filtering and pagination
- retry() and cancel() operations
- subscribe() and runsSubscribe() SSE streams

Coverage improvement:
- server.ts: 17.5% → 80.3% (statements)
- Overall: 75.2% → 89.6% (statements)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably/tests/node/server.test.ts    |   4 +
 .../durably/tests/shared/server.shared.ts     | 759 ++++++++++++++++++
 2 files changed, 763 insertions(+)
 create mode 100644 packages/durably/tests/node/server.test.ts
 create mode 100644 packages/durably/tests/shared/server.shared.ts

diff --git a/packages/durably/tests/node/server.test.ts b/packages/durably/tests/node/server.test.ts
new file mode 100644
index 00000000..081527e6
--- /dev/null
+++ b/packages/durably/tests/node/server.test.ts
@@ -0,0 +1,4 @@
+import { createNodeDialect } from '../helpers/node-dialect'
+import { createServerTests } from '../shared/server.shared'
+
+createServerTests(createNodeDialect)
diff --git a/packages/durably/tests/shared/server.shared.ts b/packages/durably/tests/shared/server.shared.ts
new file mode 100644
index 00000000..e0e2756e
--- /dev/null
+++ b/packages/durably/tests/shared/server.shared.ts
@@ -0,0 +1,759 @@
+import type { Dialect } from 'kysely'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { z } from 'zod'
+import {
+  createDurably,
+  createDurablyHandler,
+  defineJob,
+  type Durably,
+  type DurablyHandler,
+} from '../../src'
+
+export function createServerTests(createDialect: () => Dialect) {
+  describe('createDurablyHandler', () => {
+    let durably: Durably
+    let handler: DurablyHandler
+
+    beforeEach(async () => {
+      durably = createDurably({
+        dialect: createDialect(),
+        pollingInterval: 50,
+      })
+      await durably.migrate()
+      handler = createDurablyHandler(durably)
+    })
+
+    afterEach(async () => {
+      await durably.stop()
+      await durably.db.destroy()
+    })
+
+    describe('handle() routing', () => {
+      it('routes GET /subscribe to subscribe handler', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'subscribe-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/subscribe?runId=${run.id}`,
+          { method: 'GET' },
+        )
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+        expect(response.headers.get('Content-Type')).toBe('text/event-stream')
+      })
+
+      it('routes GET /runs to runs handler', async () => {
+        const request = new Request('http://localhost/api/durably/runs', {
+          method: 'GET',
+        })
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+        expect(response.headers.get('Content-Type')).toBe('application/json')
+      })
+
+      it('routes GET /run to run handler', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'run-route-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/run?runId=${run.id}`,
+          { method: 'GET' },
+        )
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+      })
+
+      it('routes POST /trigger to trigger handler', async () => {
+        durably.register({
+          job: defineJob({
+            name: 'trigger-route-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+
+        const request = new Request('http://localhost/api/durably/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ jobName: 'trigger-route-test', input: {} }),
+        })
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+      })
+
+      it('routes POST /retry to retry handler', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'retry-route-test',
+            input: z.object({}),
+            run: async () => {
+              throw new Error('fail')
+            },
+          }),
+        })
+
+        const run = await d.jobs.job.trigger({})
+        d.start()
+
+        await vi.waitFor(
+          async () => {
+            const updated = await d.getRun(run.id)
+            expect(updated?.status).toBe('failed')
+          },
+          { timeout: 1000 },
+        )
+
+        const request = new Request(
+          `http://localhost/api/durably/retry?runId=${run.id}`,
+          { method: 'POST' },
+        )
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+      })
+
+      it('routes POST /cancel to cancel handler', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'cancel-route-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/cancel?runId=${run.id}`,
+          { method: 'POST' },
+        )
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+      })
+
+      it('returns 404 for unknown routes', async () => {
+        const request = new Request('http://localhost/api/durably/unknown', {
+          method: 'GET',
+        })
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(404)
+      })
+
+      it('calls onRequest hook before handling', async () => {
+        const onRequest = vi.fn()
+        const handlerWithHook = createDurablyHandler(durably, { onRequest })
+
+        const request = new Request('http://localhost/api/durably/runs', {
+          method: 'GET',
+        })
+        await handlerWithHook.handle(request, '/api/durably')
+
+        expect(onRequest).toHaveBeenCalled()
+      })
+    })
+
+    describe('trigger()', () => {
+      it('triggers a job and returns runId', async () => {
+        durably.register({
+          job: defineJob({
+            name: 'trigger-test',
+            input: z.object({ value: z.number() }),
+            run: async () => {},
+          }),
+        })
+
+        const request = new Request('http://localhost/api/durably/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            jobName: 'trigger-test',
+            input: { value: 42 },
+          }),
+        })
+
+        const response = await handler.trigger(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(200)
+        expect(body.runId).toBeDefined()
+      })
+
+      it('returns 400 when jobName is missing', async () => {
+        const request = new Request('http://localhost/api/durably/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ input: {} }),
+        })
+
+        const response = await handler.trigger(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(400)
+        expect(body.error).toBe('jobName is required')
+      })
+
+      it('returns 404 when job is not found', async () => {
+        const request = new Request('http://localhost/api/durably/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ jobName: 'non-existent', input: {} }),
+        })
+
+        const response = await handler.trigger(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(404)
+        expect(body.error).toBe('Job not found: non-existent')
+      })
+
+      it('supports idempotencyKey and concurrencyKey', async () => {
+        durably.register({
+          job: defineJob({
+            name: 'trigger-options-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+
+        const request = new Request('http://localhost/api/durably/trigger', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            jobName: 'trigger-options-test',
+            input: {},
+            idempotencyKey: 'idem-key',
+            concurrencyKey: 'conc-key',
+          }),
+        })
+
+        const response = await handler.trigger(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(200)
+
+        const run = await durably.getRun(body.runId)
+        expect(run?.idempotencyKey).toBe('idem-key')
+        expect(run?.concurrencyKey).toBe('conc-key')
+      })
+    })
+
+    describe('runs()', () => {
+      it('returns all runs', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'runs-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        await d.jobs.job.trigger({})
+        await d.jobs.job.trigger({})
+
+        const request = new Request('http://localhost/api/durably/runs', {
+          method: 'GET',
+        })
+
+        const response = await handler.runs(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(200)
+        expect(body).toHaveLength(2)
+      })
+
+      it('filters by jobName', async () => {
+        const d1 = durably.register({
+          job1: defineJob({
+            name: 'filter-job-1',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const d2 = d1.register({
+          job2: defineJob({
+            name: 'filter-job-2',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        await d2.jobs.job1.trigger({})
+        await d2.jobs.job2.trigger({})
+
+        const request = new Request(
+          'http://localhost/api/durably/runs?jobName=filter-job-1',
+          { method: 'GET' },
+        )
+
+        const response = await handler.runs(request)
+        const body = await response.json()
+
+        expect(body).toHaveLength(1)
+        expect(body[0].jobName).toBe('filter-job-1')
+      })
+
+      it('filters by status', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'status-filter-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        await d.jobs.job.trigger({})
+        await d.jobs.job.trigger({})
+        d.start()
+
+        await vi.waitFor(
+          async () => {
+            const runs = await d.getRuns({ status: 'completed' })
+            expect(runs.length).toBeGreaterThanOrEqual(1)
+          },
+          { timeout: 1000 },
+        )
+
+        const request = new Request(
+          'http://localhost/api/durably/runs?status=completed',
+          { method: 'GET' },
+        )
+
+        const response = await handler.runs(request)
+        const body = await response.json()
+
+        for (const run of body) {
+          expect(run.status).toBe('completed')
+        }
+      })
+
+      it('supports limit and offset', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'pagination-test',
+            input: z.object({ order: z.number() }),
+            run: async () => {},
+          }),
+        })
+        for (let i = 1; i <= 5; i++) {
+          await d.jobs.job.trigger({ order: i })
+          if (i < 5) await new Promise((r) => setTimeout(r, 5))
+        }
+
+        const request = new Request(
+          'http://localhost/api/durably/runs?limit=2&offset=1',
+          { method: 'GET' },
+        )
+
+        const response = await handler.runs(request)
+        const body = await response.json()
+
+        expect(body).toHaveLength(2)
+      })
+    })
+
+    describe('run()', () => {
+      it('returns a single run', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'single-run-test',
+            input: z.object({ value: z.number() }),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({ value: 42 })
+
+        const request = new Request(
+          `http://localhost/api/durably/run?runId=${run.id}`,
+          { method: 'GET' },
+        )
+
+        const response = await handler.run(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(200)
+        expect(body.id).toBe(run.id)
+        expect(body.payload).toEqual({ value: 42 })
+      })
+
+      it('returns 400 when runId is missing', async () => {
+        const request = new Request('http://localhost/api/durably/run', {
+          method: 'GET',
+        })
+
+        const response = await handler.run(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(400)
+        expect(body.error).toBe('runId query parameter is required')
+      })
+
+      it('returns 404 when run is not found', async () => {
+        const request = new Request(
+          'http://localhost/api/durably/run?runId=non-existent',
+          { method: 'GET' },
+        )
+
+        const response = await handler.run(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(404)
+        expect(body.error).toBe('Run not found')
+      })
+    })
+
+    describe('retry()', () => {
+      it('retries a failed run', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'retry-test',
+            input: z.object({}),
+            run: async () => {
+              throw new Error('fail')
+            },
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+        d.start()
+
+        await vi.waitFor(
+          async () => {
+            const updated = await d.getRun(run.id)
+            expect(updated?.status).toBe('failed')
+          },
+          { timeout: 1000 },
+        )
+
+        const request = new Request(
+          `http://localhost/api/durably/retry?runId=${run.id}`,
+          { method: 'POST' },
+        )
+
+        const response = await handler.retry(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(200)
+        expect(body.success).toBe(true)
+
+        const updated = await d.getRun(run.id)
+        expect(updated?.status).toBe('pending')
+      })
+
+      it('returns 400 when runId is missing', async () => {
+        const request = new Request('http://localhost/api/durably/retry', {
+          method: 'POST',
+        })
+
+        const response = await handler.retry(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(400)
+        expect(body.error).toBe('runId query parameter is required')
+      })
+
+      it('returns 500 when retrying non-failed run', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'retry-pending-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/retry?runId=${run.id}`,
+          { method: 'POST' },
+        )
+
+        const response = await handler.retry(request)
+        expect(response.status).toBe(500)
+      })
+    })
+
+    describe('cancel()', () => {
+      it('cancels a pending run', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'cancel-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/cancel?runId=${run.id}`,
+          { method: 'POST' },
+        )
+
+        const response = await handler.cancel(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(200)
+        expect(body.success).toBe(true)
+
+        const updated = await d.getRun(run.id)
+        expect(updated?.status).toBe('cancelled')
+      })
+
+      it('returns 400 when runId is missing', async () => {
+        const request = new Request('http://localhost/api/durably/cancel', {
+          method: 'POST',
+        })
+
+        const response = await handler.cancel(request)
+        const body = await response.json()
+
+        expect(response.status).toBe(400)
+        expect(body.error).toBe('runId query parameter is required')
+      })
+
+      it('returns 500 when cancelling completed run', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'cancel-completed-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+        d.start()
+
+        await vi.waitFor(
+          async () => {
+            const updated = await d.getRun(run.id)
+            expect(updated?.status).toBe('completed')
+          },
+          { timeout: 1000 },
+        )
+
+        const request = new Request(
+          `http://localhost/api/durably/cancel?runId=${run.id}`,
+          { method: 'POST' },
+        )
+
+        const response = await handler.cancel(request)
+        expect(response.status).toBe(500)
+      })
+    })
+
+    describe('subscribe()', () => {
+      it('returns SSE stream', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'sse-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/subscribe?runId=${run.id}`,
+          { method: 'GET' },
+        )
+
+        const response = handler.subscribe(request)
+
+        expect(response.status).toBe(200)
+        expect(response.headers.get('Content-Type')).toBe('text/event-stream')
+        expect(response.headers.get('Cache-Control')).toBe('no-cache')
+      })
+
+      it('streams events for a run', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'sse-stream-test',
+            input: z.object({}),
+            run: async (step) => {
+              await step.run('step1', async () => 'result')
+            },
+          }),
+        })
+        const run = await d.jobs.job.trigger({})
+
+        const request = new Request(
+          `http://localhost/api/durably/subscribe?runId=${run.id}`,
+          { method: 'GET' },
+        )
+
+        const response = handler.subscribe(request)
+        const reader = response.body!.getReader()
+        const decoder = new TextDecoder()
+
+        // Start worker to process the job
+        d.start()
+
+        const events: string[] = []
+        const readEvents = async () => {
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            events.push(decoder.decode(value))
+          }
+        }
+
+        await Promise.race([
+          readEvents(),
+          new Promise((r) => setTimeout(r, 1000)),
+        ])
+
+        // Should have received some events
+        expect(events.length).toBeGreaterThan(0)
+        const allEvents = events.join('')
+        expect(allEvents).toContain('data:')
+      })
+
+      it('returns 400 when runId is missing', () => {
+        const request = new Request('http://localhost/api/durably/subscribe', {
+          method: 'GET',
+        })
+
+        const response = handler.subscribe(request)
+        expect(response.status).toBe(400)
+      })
+    })
+
+    describe('runsSubscribe()', () => {
+      it('returns SSE stream for run updates', () => {
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe',
+          { method: 'GET' },
+        )
+
+        const response = handler.runsSubscribe(request)
+
+        expect(response.status).toBe(200)
+        expect(response.headers.get('Content-Type')).toBe('text/event-stream')
+      })
+
+      it('routes to runsSubscribe via handle()', async () => {
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe',
+          { method: 'GET' },
+        )
+
+        const response = await handler.handle(request, '/api/durably')
+
+        expect(response.status).toBe(200)
+        expect(response.headers.get('Content-Type')).toBe('text/event-stream')
+      })
+
+      it('streams run lifecycle events', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'runs-subscribe-test',
+            input: z.object({}),
+            run: async (step) => {
+              step.progress(50)
+              await step.run('work', async () => {})
+            },
+          }),
+        })
+
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe',
+          { method: 'GET' },
+        )
+
+        const response = handler.runsSubscribe(request)
+        const reader = response.body!.getReader()
+        const decoder = new TextDecoder()
+
+        // Trigger a job to generate events
+        await d.jobs.job.trigger({})
+        d.start()
+
+        const events: string[] = []
+        const readEvents = async () => {
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            events.push(decoder.decode(value))
+            // Stop after receiving some events
+            if (events.length >= 2) break
+          }
+        }
+
+        await Promise.race([
+          readEvents(),
+          new Promise((r) => setTimeout(r, 1000)),
+        ])
+
+        // Should have received run:start and run:complete events
+        expect(events.length).toBeGreaterThan(0)
+        const allEvents = events.join('')
+        expect(allEvents).toContain('data:')
+        expect(allEvents).toContain('run:')
+      })
+
+      it('filters by jobName', async () => {
+        const d1 = durably.register({
+          job1: defineJob({
+            name: 'filter-subscribe-1',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+        const d2 = d1.register({
+          job2: defineJob({
+            name: 'filter-subscribe-2',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+
+        // Subscribe only to job1
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe?jobName=filter-subscribe-1',
+          { method: 'GET' },
+        )
+
+        const response = handler.runsSubscribe(request)
+        const reader = response.body!.getReader()
+        const decoder = new TextDecoder()
+
+        // Trigger both jobs
+        await d2.jobs.job1.trigger({})
+        await d2.jobs.job2.trigger({})
+        d2.start()
+
+        const events: string[] = []
+        const readEvents = async () => {
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            events.push(decoder.decode(value))
+            if (events.length >= 2) break
+          }
+        }
+
+        await Promise.race([
+          readEvents(),
+          new Promise((r) => setTimeout(r, 1000)),
+        ])
+
+        // All events should be for filter-subscribe-1 only
+        const allEvents = events.join('')
+        if (allEvents.includes('jobName')) {
+          expect(allEvents).toContain('filter-subscribe-1')
+          expect(allEvents).not.toContain('filter-subscribe-2')
+        }
+      })
+    })
+  })
+}

From c9a4e43fdfc994b32db6f5896bdd05f770839f9c Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 15:56:58 +0900
Subject: [PATCH 072/101] feat(durably): add run:trigger and run:cancel events
 for real-time dashboard updates
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add run:trigger event emitted when job.trigger() is called (before worker picks up)
- Add run:trigger emission in batchTrigger() for all created runs
- Add run:cancel event emitted when durably.cancel() is called
- Subscribe to run:trigger and run:cancel in runsSubscribe SSE endpoint
- Handle run:trigger and run:cancel in client/use-runs.ts SSE handler
- Subscribe to run:trigger and run:cancel in hooks/use-runs.ts
- Add tests for run:trigger and run:cancel SSE streaming

This fixes the issue where jobs triggered don't immediately appear in the dashboard.
Previously, jobs only showed when run:start fired (when worker executed), not when
trigger() was called.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/client/use-runs.ts | 11 ++-
 packages/durably-react/src/hooks/use-runs.ts  |  2 +
 packages/durably/src/durably.ts               |  7 ++
 packages/durably/src/events.ts                | 23 +++++
 packages/durably/src/job.ts                   | 43 ++++++---
 packages/durably/src/server.ts                | 26 ++++++
 .../durably/tests/shared/server.shared.ts     | 89 ++++++++++++++++++-
 7 files changed, 183 insertions(+), 18 deletions(-)

diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts
index a3ab7a55..766daa83 100644
--- a/packages/durably-react/src/client/use-runs.ts
+++ b/packages/durably-react/src/client/use-runs.ts
@@ -22,7 +22,12 @@ export interface ClientRun {
  */
 type RunUpdateEvent =
   | {
-      type: 'run:start' | 'run:complete' | 'run:fail'
+      type:
+        | 'run:trigger'
+        | 'run:start'
+        | 'run:complete'
+        | 'run:fail'
+        | 'run:cancel'
       runId: string
       jobName: string
     }
@@ -196,9 +201,11 @@ export function useRuns(options: UseRunsClientOptions): UseRunsClientResult {
         const data = JSON.parse(event.data) as RunUpdateEvent
         // On run lifecycle events, refresh the list
         if (
+          data.type === 'run:trigger' ||
           data.type === 'run:start' ||
           data.type === 'run:complete' ||
-          data.type === 'run:fail'
+          data.type === 'run:fail' ||
+          data.type === 'run:cancel'
         ) {
           refresh()
         }
diff --git a/packages/durably-react/src/hooks/use-runs.ts b/packages/durably-react/src/hooks/use-runs.ts
index 4e56626d..186fe562 100644
--- a/packages/durably-react/src/hooks/use-runs.ts
+++ b/packages/durably-react/src/hooks/use-runs.ts
@@ -121,9 +121,11 @@ export function useRuns(options?: UseRunsOptions): UseRunsResult {
     if (!realtime) return
 
     const unsubscribes = [
+      durably.on('run:trigger', refresh),
       durably.on('run:start', refresh),
       durably.on('run:complete', refresh),
       durably.on('run:fail', refresh),
+      durably.on('run:cancel', refresh),
     ]
 
     return () => {
diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts
index adf3289a..ed5b1904 100644
--- a/packages/durably/src/durably.ts
+++ b/packages/durably/src/durably.ts
@@ -390,6 +390,13 @@ function createDurablyInstance<
       await storage.updateRun(runId, {
         status: 'cancelled',
       })
+
+      // Emit run:cancel event
+      eventEmitter.emit({
+        type: 'run:cancel',
+        runId,
+        jobName: run.jobName,
+      })
     },
 
     async deleteRun(runId: string): Promise {
diff --git a/packages/durably/src/events.ts b/packages/durably/src/events.ts
index eb78b1a9..5b0f8372 100644
--- a/packages/durably/src/events.ts
+++ b/packages/durably/src/events.ts
@@ -7,6 +7,16 @@ export interface BaseEvent {
   sequence: number
 }
 
+/**
+ * Run trigger event (emitted when a job is triggered, before worker picks it up)
+ */
+export interface RunTriggerEvent extends BaseEvent {
+  type: 'run:trigger'
+  runId: string
+  jobName: string
+  payload: unknown
+}
+
 /**
  * Run start event
  */
@@ -39,6 +49,15 @@ export interface RunFailEvent extends BaseEvent {
   failedStepName: string
 }
 
+/**
+ * Run cancel event
+ */
+export interface RunCancelEvent extends BaseEvent {
+  type: 'run:cancel'
+  runId: string
+  jobName: string
+}
+
 /**
  * Run progress event
  */
@@ -111,9 +130,11 @@ export interface WorkerErrorEvent extends BaseEvent {
  * All event types as discriminated union
  */
 export type DurablyEvent =
+  | RunTriggerEvent
   | RunStartEvent
   | RunCompleteEvent
   | RunFailEvent
+  | RunCancelEvent
   | RunProgressEvent
   | StepStartEvent
   | StepCompleteEvent
@@ -146,9 +167,11 @@ export type EventInput = Omit<
  * All possible event inputs as a union (properly distributed)
  */
 export type AnyEventInput =
+  | EventInput<'run:trigger'>
   | EventInput<'run:start'>
   | EventInput<'run:complete'>
   | EventInput<'run:fail'>
+  | EventInput<'run:cancel'>
   | EventInput<'run:progress'>
   | EventInput<'step:start'>
   | EventInput<'step:complete'>
diff --git a/packages/durably/src/job.ts b/packages/durably/src/job.ts
index e238fad3..f453b6f6 100644
--- a/packages/durably/src/job.ts
+++ b/packages/durably/src/job.ts
@@ -182,7 +182,7 @@ export function createJobRegistry(): JobRegistry {
 export function createJobHandle(
   jobDef: JobDefinition,
   storage: Storage,
-  _eventEmitter: EventEmitter,
+  eventEmitter: EventEmitter,
   registry: JobRegistry,
 ): JobHandle {
   // Check if same JobDefinition is already registered (idempotent)
@@ -222,6 +222,14 @@ export function createJobHandle(
         concurrencyKey: options?.concurrencyKey,
       })
 
+      // Emit run:trigger event
+      eventEmitter.emit({
+        type: 'run:trigger',
+        runId: run.id,
+        jobName: jobDef.name,
+        payload: parseResult.data,
+      })
+
       return run as TypedRun
     },
 
@@ -247,20 +255,17 @@ export function createJobHandle(
           }
         }
 
-        const unsubscribeComplete = _eventEmitter.on(
-          'run:complete',
-          (event) => {
-            if (event.runId === run.id && !resolved) {
-              cleanup()
-              resolve({
-                id: run.id,
-                output: event.output as TOutput,
-              })
-            }
-          },
-        )
+        const unsubscribeComplete = eventEmitter.on('run:complete', (event) => {
+          if (event.runId === run.id && !resolved) {
+            cleanup()
+            resolve({
+              id: run.id,
+              output: event.output as TOutput,
+            })
+          }
+        })
 
-        const unsubscribeFail = _eventEmitter.on('run:fail', (event) => {
+        const unsubscribeFail = eventEmitter.on('run:fail', (event) => {
           if (event.runId === run.id && !resolved) {
             cleanup()
             reject(new Error(event.error))
@@ -337,6 +342,16 @@ export function createJobHandle(
         })),
       )
 
+      // Emit run:trigger events for all created runs
+      for (let i = 0; i < runs.length; i++) {
+        eventEmitter.emit({
+          type: 'run:trigger',
+          runId: runs[i].id,
+          jobName: jobDef.name,
+          payload: validated[i].payload,
+        })
+      }
+
       return runs as TypedRun[]
     },
 
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index 07cbebca..e5bbc9cb 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -380,6 +380,18 @@ export function createDurablyHandler(
       const sseStream = new ReadableStream({
         start(controller) {
           // Subscribe to run lifecycle events
+          const unsubscribeTrigger = durably.on('run:trigger', (event) => {
+            if (closed) return
+            if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'run:trigger',
+              runId: event.runId,
+              jobName: event.jobName,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
           const unsubscribeStart = durably.on('run:start', (event) => {
             if (closed) return
             if (jobNameFilter && event.jobName !== jobNameFilter) return
@@ -416,6 +428,18 @@ export function createDurablyHandler(
             controller.enqueue(encoder.encode(data))
           })
 
+          const unsubscribeCancel = durably.on('run:cancel', (event) => {
+            if (closed) return
+            if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'run:cancel',
+              runId: event.runId,
+              jobName: event.jobName,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
           const unsubscribeProgress = durably.on('run:progress', (event) => {
             if (closed) return
             if (jobNameFilter && event.jobName !== jobNameFilter) return
@@ -432,9 +456,11 @@ export function createDurablyHandler(
           // Store cleanup function for cancel
           ;(controller as unknown as { cleanup: () => void }).cleanup = () => {
             closed = true
+            unsubscribeTrigger()
             unsubscribeStart()
             unsubscribeComplete()
             unsubscribeFail()
+            unsubscribeCancel()
             unsubscribeProgress()
           }
         },
diff --git a/packages/durably/tests/shared/server.shared.ts b/packages/durably/tests/shared/server.shared.ts
index e0e2756e..7622f6c8 100644
--- a/packages/durably/tests/shared/server.shared.ts
+++ b/packages/durably/tests/shared/server.shared.ts
@@ -653,6 +653,91 @@ export function createServerTests(createDialect: () => Dialect) {
         expect(response.headers.get('Content-Type')).toBe('text/event-stream')
       })
 
+      it('streams run:trigger immediately when job is triggered', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'runs-subscribe-trigger-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe',
+          { method: 'GET' },
+        )
+
+        const response = handler.runsSubscribe(request)
+        const reader = response.body!.getReader()
+        const decoder = new TextDecoder()
+
+        const events: string[] = []
+        const readPromise = (async () => {
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            events.push(decoder.decode(value))
+            // Stop after receiving the trigger event
+            if (events.some((e) => e.includes('run:trigger'))) break
+          }
+        })()
+
+        // Trigger the job (don't start worker yet)
+        await d.jobs.job.trigger({})
+
+        await Promise.race([
+          readPromise,
+          new Promise((r) => setTimeout(r, 500)),
+        ])
+
+        // Should have received run:trigger event immediately
+        const allEvents = events.join('')
+        expect(allEvents).toContain('run:trigger')
+      })
+
+      it('streams run:cancel when job is cancelled', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'runs-subscribe-cancel-test',
+            input: z.object({}),
+            run: async () => {},
+          }),
+        })
+
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe',
+          { method: 'GET' },
+        )
+
+        const response = handler.runsSubscribe(request)
+        const reader = response.body!.getReader()
+        const decoder = new TextDecoder()
+
+        const events: string[] = []
+        const readPromise = (async () => {
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            events.push(decoder.decode(value))
+            // Stop after receiving the cancel event
+            if (events.some((e) => e.includes('run:cancel'))) break
+          }
+        })()
+
+        // Trigger and then cancel the job
+        const run = await d.jobs.job.trigger({})
+        await d.cancel(run.id)
+
+        await Promise.race([
+          readPromise,
+          new Promise((r) => setTimeout(r, 500)),
+        ])
+
+        // Should have received run:cancel event
+        const allEvents = events.join('')
+        expect(allEvents).toContain('run:cancel')
+      })
+
       it('streams run lifecycle events', async () => {
         const d = durably.register({
           job: defineJob({
@@ -685,7 +770,7 @@ export function createServerTests(createDialect: () => Dialect) {
             if (done) break
             events.push(decoder.decode(value))
             // Stop after receiving some events
-            if (events.length >= 2) break
+            if (events.length >= 3) break
           }
         }
 
@@ -694,7 +779,7 @@ export function createServerTests(createDialect: () => Dialect) {
           new Promise((r) => setTimeout(r, 1000)),
         ])
 
-        // Should have received run:start and run:complete events
+        // Should have received run:trigger, run:start and run:complete events
         expect(events.length).toBeGreaterThan(0)
         const allEvents = events.join('')
         expect(allEvents).toContain('data:')

From f92782f28f719257da127a6cb2835a2986763c00 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 16:03:42 +0900
Subject: [PATCH 073/101] feat(durably): add run:retry event and fix
 subscribe() to handle run:cancel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add run:retry event emitted when retry() is called
- Subscribe to run:cancel in subscribe() method for single run subscriptions
- Subscribe to run:retry in runsSubscribe SSE endpoint
- Handle run:retry in client/use-runs.ts and hooks/use-runs.ts
- Add test for run:retry SSE streaming

This ensures dashboard updates when a failed run is retried.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/client/use-runs.ts |  4 +-
 packages/durably-react/src/hooks/use-runs.ts  |  1 +
 packages/durably/src/durably.ts               | 17 +++++++
 packages/durably/src/events.ts                | 11 ++++
 packages/durably/src/server.ts                | 13 +++++
 .../durably/tests/shared/server.shared.ts     | 51 +++++++++++++++++++
 6 files changed, 96 insertions(+), 1 deletion(-)

diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts
index 766daa83..3503204b 100644
--- a/packages/durably-react/src/client/use-runs.ts
+++ b/packages/durably-react/src/client/use-runs.ts
@@ -28,6 +28,7 @@ type RunUpdateEvent =
         | 'run:complete'
         | 'run:fail'
         | 'run:cancel'
+        | 'run:retry'
       runId: string
       jobName: string
     }
@@ -205,7 +206,8 @@ export function useRuns(options: UseRunsClientOptions): UseRunsClientResult {
           data.type === 'run:start' ||
           data.type === 'run:complete' ||
           data.type === 'run:fail' ||
-          data.type === 'run:cancel'
+          data.type === 'run:cancel' ||
+          data.type === 'run:retry'
         ) {
           refresh()
         }
diff --git a/packages/durably-react/src/hooks/use-runs.ts b/packages/durably-react/src/hooks/use-runs.ts
index 186fe562..669b6f75 100644
--- a/packages/durably-react/src/hooks/use-runs.ts
+++ b/packages/durably-react/src/hooks/use-runs.ts
@@ -126,6 +126,7 @@ export function useRuns(options?: UseRunsOptions): UseRunsResult {
       durably.on('run:complete', refresh),
       durably.on('run:fail', refresh),
       durably.on('run:cancel', refresh),
+      durably.on('run:retry', refresh),
     ]
 
     return () => {
diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts
index ed5b1904..1c44e893 100644
--- a/packages/durably/src/durably.ts
+++ b/packages/durably/src/durably.ts
@@ -300,6 +300,15 @@ function createDurablyInstance<
             }
           })
 
+          const unsubscribeCancel = eventEmitter.on('run:cancel', (event) => {
+            if (!closed && event.runId === runId) {
+              controller.enqueue(event)
+              closed = true
+              cleanup()
+              controller.close()
+            }
+          })
+
           const unsubscribeProgress = eventEmitter.on(
             'run:progress',
             (event) => {
@@ -343,6 +352,7 @@ function createDurablyInstance<
             unsubscribeStart()
             unsubscribeComplete()
             unsubscribeFail()
+            unsubscribeCancel()
             unsubscribeProgress()
             unsubscribeStepStart()
             unsubscribeStepComplete()
@@ -371,6 +381,13 @@ function createDurablyInstance<
         status: 'pending',
         error: null,
       })
+
+      // Emit run:retry event
+      eventEmitter.emit({
+        type: 'run:retry',
+        runId,
+        jobName: run.jobName,
+      })
     },
 
     async cancel(runId: string): Promise {
diff --git a/packages/durably/src/events.ts b/packages/durably/src/events.ts
index 5b0f8372..fb53eea0 100644
--- a/packages/durably/src/events.ts
+++ b/packages/durably/src/events.ts
@@ -58,6 +58,15 @@ export interface RunCancelEvent extends BaseEvent {
   jobName: string
 }
 
+/**
+ * Run retry event (emitted when a failed run is retried)
+ */
+export interface RunRetryEvent extends BaseEvent {
+  type: 'run:retry'
+  runId: string
+  jobName: string
+}
+
 /**
  * Run progress event
  */
@@ -135,6 +144,7 @@ export type DurablyEvent =
   | RunCompleteEvent
   | RunFailEvent
   | RunCancelEvent
+  | RunRetryEvent
   | RunProgressEvent
   | StepStartEvent
   | StepCompleteEvent
@@ -172,6 +182,7 @@ export type AnyEventInput =
   | EventInput<'run:complete'>
   | EventInput<'run:fail'>
   | EventInput<'run:cancel'>
+  | EventInput<'run:retry'>
   | EventInput<'run:progress'>
   | EventInput<'step:start'>
   | EventInput<'step:complete'>
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index e5bbc9cb..8a184ef3 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -440,6 +440,18 @@ export function createDurablyHandler(
             controller.enqueue(encoder.encode(data))
           })
 
+          const unsubscribeRetry = durably.on('run:retry', (event) => {
+            if (closed) return
+            if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'run:retry',
+              runId: event.runId,
+              jobName: event.jobName,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
           const unsubscribeProgress = durably.on('run:progress', (event) => {
             if (closed) return
             if (jobNameFilter && event.jobName !== jobNameFilter) return
@@ -461,6 +473,7 @@ export function createDurablyHandler(
             unsubscribeComplete()
             unsubscribeFail()
             unsubscribeCancel()
+            unsubscribeRetry()
             unsubscribeProgress()
           }
         },
diff --git a/packages/durably/tests/shared/server.shared.ts b/packages/durably/tests/shared/server.shared.ts
index 7622f6c8..73735891 100644
--- a/packages/durably/tests/shared/server.shared.ts
+++ b/packages/durably/tests/shared/server.shared.ts
@@ -738,6 +738,57 @@ export function createServerTests(createDialect: () => Dialect) {
         expect(allEvents).toContain('run:cancel')
       })
 
+      it('streams run:retry when job is retried', async () => {
+        const d = durably.register({
+          job: defineJob({
+            name: 'runs-subscribe-retry-test',
+            input: z.object({}),
+            run: async () => {
+              throw new Error('test error')
+            },
+          }),
+        })
+
+        // First, trigger and let it fail
+        const run = await d.jobs.job.trigger({})
+        d.start()
+
+        // Wait for the job to fail
+        await new Promise((r) => setTimeout(r, 200))
+
+        const request = new Request(
+          'http://localhost/api/durably/runs/subscribe',
+          { method: 'GET' },
+        )
+
+        const response = handler.runsSubscribe(request)
+        const reader = response.body!.getReader()
+        const decoder = new TextDecoder()
+
+        const events: string[] = []
+        const readPromise = (async () => {
+          while (true) {
+            const { done, value } = await reader.read()
+            if (done) break
+            events.push(decoder.decode(value))
+            // Stop after receiving the retry event
+            if (events.some((e) => e.includes('run:retry'))) break
+          }
+        })()
+
+        // Retry the failed job
+        await d.retry(run.id)
+
+        await Promise.race([
+          readPromise,
+          new Promise((r) => setTimeout(r, 500)),
+        ])
+
+        // Should have received run:retry event
+        const allEvents = events.join('')
+        expect(allEvents).toContain('run:retry')
+      })
+
       it('streams run lifecycle events', async () => {
         const d = durably.register({
           job: defineJob({

From 6c8c2fb8f825cb6c98740bddc6ed12ca12e89246 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 16:04:49 +0900
Subject: [PATCH 074/101] feat(example): add retry button to fullstack
 dashboard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Failed and cancelled runs now show a Retry button to re-queue them.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/routes/_index/dashboard.tsx           | 25 ++++++++++++++++---
 1 file changed, 22 insertions(+), 3 deletions(-)

diff --git a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
index b8bcf460..088f16a9 100644
--- a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
@@ -15,7 +15,11 @@ export function Dashboard() {
       pageSize: 6,
     })
 
-  const { cancel, isLoading: isCancelling } = useRunActions({
+  const {
+    cancel,
+    retry,
+    isLoading: isActioning,
+  } = useRunActions({
     api: '/api/durably',
   })
 
@@ -24,6 +28,11 @@ export function Dashboard() {
     refresh()
   }
 
+  const handleRetry = async (runId: string) => {
+    await retry(runId)
+    refresh()
+  }
+
   return (
     
      
       
      
@@ -74,10 +83,20 @@ export function Dashboard() {
                     
+                  )}
+                  {(r.status === 'failed' || r.status === 'cancelled') && (
+                    
                   )}
                   
Date: Fri, 2 Jan 2026 16:18:47 +0900
Subject: [PATCH 075/101] feat(durably-react): add run:cancel and run:retry
 event subscriptions to single-run hooks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add run:cancel and run:retry handling to useRunSubscription (browser)
- Add run:cancel and run:retry handling to useSSESubscription (client)
- Add isCancelled helper to useJobRun (both browser and client)
- Add DurablyEvent types for run:cancel and run:retry
- Add tests for cancel and retry status updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../durably-react/src/client/use-job-run.ts   |  6 ++
 .../src/client/use-sse-subscription.ts        |  7 ++
 .../durably-react/src/hooks/use-job-run.ts    |  5 +
 .../src/hooks/use-run-subscription.ts         | 15 +++
 packages/durably-react/src/types.ts           |  2 +
 .../tests/browser/use-job-run.test.tsx        | 98 +++++++++++++++++++
 .../tests/client/use-job-run.test.tsx         | 60 ++++++++++++
 7 files changed, 193 insertions(+)

diff --git a/packages/durably-react/src/client/use-job-run.ts b/packages/durably-react/src/client/use-job-run.ts
index 78b9042c..ac0ea6c6 100644
--- a/packages/durably-react/src/client/use-job-run.ts
+++ b/packages/durably-react/src/client/use-job-run.ts
@@ -66,6 +66,10 @@ export interface UseJobRunClientResult {
    * Whether the run failed
    */
   isFailed: boolean
+  /**
+   * Whether the run was cancelled
+   */
+  isCancelled: boolean
 }
 
 /**
@@ -86,6 +90,7 @@ export function useJobRun(
   const isFailed = effectiveStatus === 'failed'
   const isPending = effectiveStatus === 'pending'
   const isRunning = effectiveStatus === 'running'
+  const isCancelled = effectiveStatus === 'cancelled'
 
   // Track previous status to detect transitions
   const prevStatusRef = useRef(null)
@@ -129,5 +134,6 @@ export function useJobRun(
     isPending,
     isCompleted,
     isFailed,
+    isCancelled,
   }
 }
diff --git a/packages/durably-react/src/client/use-sse-subscription.ts b/packages/durably-react/src/client/use-sse-subscription.ts
index 5047a350..53efe68a 100644
--- a/packages/durably-react/src/client/use-sse-subscription.ts
+++ b/packages/durably-react/src/client/use-sse-subscription.ts
@@ -75,6 +75,13 @@ export function useSSESubscription(
             setStatus('failed')
             setError(data.error)
             break
+          case 'run:cancel':
+            setStatus('cancelled')
+            break
+          case 'run:retry':
+            setStatus('pending')
+            setError(null)
+            break
           case 'run:progress':
             setProgress(data.progress)
             break
diff --git a/packages/durably-react/src/hooks/use-job-run.ts b/packages/durably-react/src/hooks/use-job-run.ts
index 34f92803..c941691c 100644
--- a/packages/durably-react/src/hooks/use-job-run.ts
+++ b/packages/durably-react/src/hooks/use-job-run.ts
@@ -51,6 +51,10 @@ export interface UseJobRunResult {
    * Whether the run failed
    */
   isFailed: boolean
+  /**
+   * Whether the run was cancelled
+   */
+  isCancelled: boolean
 }
 
 /**
@@ -90,5 +94,6 @@ export function useJobRun(
     isPending: subscription.status === 'pending',
     isCompleted: subscription.status === 'completed',
     isFailed: subscription.status === 'failed',
+    isCancelled: subscription.status === 'cancelled',
   }
 }
diff --git a/packages/durably-react/src/hooks/use-run-subscription.ts b/packages/durably-react/src/hooks/use-run-subscription.ts
index d41bfb61..d5ed8add 100644
--- a/packages/durably-react/src/hooks/use-run-subscription.ts
+++ b/packages/durably-react/src/hooks/use-run-subscription.ts
@@ -80,6 +80,21 @@ export function useRunSubscription(
       }),
     )
 
+    unsubscribes.push(
+      durably.on('run:cancel', (event) => {
+        if (event.runId !== runIdRef.current) return
+        setStatus('cancelled')
+      }),
+    )
+
+    unsubscribes.push(
+      durably.on('run:retry', (event) => {
+        if (event.runId !== runIdRef.current) return
+        setStatus('pending')
+        setError(null)
+      }),
+    )
+
     unsubscribes.push(
       durably.on('run:progress', (event) => {
         if (event.runId !== runIdRef.current) return
diff --git a/packages/durably-react/src/types.ts b/packages/durably-react/src/types.ts
index 50974709..d1f7ce16 100644
--- a/packages/durably-react/src/types.ts
+++ b/packages/durably-react/src/types.ts
@@ -34,6 +34,8 @@ export type DurablyEvent =
       duration: number
     }
   | { type: 'run:fail'; runId: string; jobName: string; error: string }
+  | { type: 'run:cancel'; runId: string; jobName: string }
+  | { type: 'run:retry'; runId: string; jobName: string }
   | {
       type: 'run:progress'
       runId: string
diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx
index 40b398d5..f97798ce 100644
--- a/packages/durably-react/tests/browser/use-job-run.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-run.test.tsx
@@ -202,6 +202,104 @@ describe('useJobRun', () => {
     )
   })
 
+  it('updates status when run is cancelled', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
+    // Use autoStart=false wrapper so worker doesn't pick up the job
+    const noAutoStartWrapper = ({ children }: { children: ReactNode }) => (
+      
+        {children}
+      
+    )
+
+    function useTriggerAndSubscribe() {
+      const { isReady: durablyReady } = useDurably()
+      const [runId, setRunId] = useState(null)
+      const subscription = useJobRun({ runId })
+
+      return {
+        ...subscription,
+        isReady: durablyReady && subscription.isReady,
+        runId,
+        setRunId,
+      }
+    }
+
+    const { result } = renderHook(() => useTriggerAndSubscribe(), {
+      wrapper: noAutoStartWrapper,
+    })
+
+    await waitFor(() => expect(result.current.isReady).toBe(true))
+
+    const d = durably.register({ _job: testJob })
+    const run = await d.jobs._job.trigger({ input: 'test' })
+    result.current.setRunId(run.id)
+
+    // Cancel the pending run (worker is not running)
+    await durably.cancel(run.id)
+
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('cancelled')
+        expect(result.current.isCancelled).toBe(true)
+      },
+      { timeout: 3000 },
+    )
+  })
+
+  it('resets status when run is retried', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
+    function useTriggerAndSubscribe() {
+      const { isReady: durablyReady } = useDurably()
+      const [runId, setRunId] = useState(null)
+      const subscription = useJobRun({ runId })
+
+      return {
+        ...subscription,
+        isReady: durablyReady && subscription.isReady,
+        runId,
+        setRunId,
+      }
+    }
+
+    const { result } = renderHook(() => useTriggerAndSubscribe(), {
+      wrapper: createWrapper(durably),
+    })
+
+    await waitFor(() => expect(result.current.isReady).toBe(true))
+
+    const d = durably.register({ _job: failingJob })
+    const run = await d.jobs._job.trigger({ input: 'test' })
+    result.current.setRunId(run.id)
+
+    // Wait for the run to fail
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('failed')
+        expect(result.current.error).toBe('Job failed')
+      },
+      { timeout: 3000 },
+    )
+
+    // Stop worker so retry doesn't immediately re-run
+    await durably.stop()
+
+    // Retry the run
+    await durably.retry(run.id)
+
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('pending')
+        expect(result.current.error).toBeNull()
+        expect(result.current.isPending).toBe(true)
+      },
+      { timeout: 3000 },
+    )
+  })
+
   it('tracks progress updates', async () => {
     const durably = await createTestDurably({ pollingInterval: 50 })
     instances.push(durably)
diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx
index 3b68f83b..c2cc1fcb 100644
--- a/packages/durably-react/tests/client/use-job-run.test.tsx
+++ b/packages/durably-react/tests/client/use-job-run.test.tsx
@@ -110,6 +110,66 @@ describe('useJobRun (client)', () => {
     })
   })
 
+  it('updates status when run is cancelled', async () => {
+    const { result } = renderHook(() =>
+      useJobRun({ api: '/api/durably', runId: 'cancel-run' }),
+    )
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    act(() => {
+      mockEventSource.emit({
+        type: 'run:cancel',
+        runId: 'cancel-run',
+      })
+    })
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('cancelled')
+      expect(result.current.isCancelled).toBe(true)
+    })
+  })
+
+  it('resets status when run is retried', async () => {
+    const { result } = renderHook(() =>
+      useJobRun({ api: '/api/durably', runId: 'retry-run' }),
+    )
+
+    await waitFor(() => {
+      expect(mockEventSource.instances.length).toBeGreaterThan(0)
+    })
+
+    // First fail the run
+    act(() => {
+      mockEventSource.emit({
+        type: 'run:fail',
+        runId: 'retry-run',
+        error: 'Something went wrong',
+      })
+    })
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('failed')
+      expect(result.current.error).toBe('Something went wrong')
+    })
+
+    // Then retry it
+    act(() => {
+      mockEventSource.emit({
+        type: 'run:retry',
+        runId: 'retry-run',
+      })
+    })
+
+    await waitFor(() => {
+      expect(result.current.status).toBe('pending')
+      expect(result.current.error).toBeNull()
+      expect(result.current.isPending).toBe(true)
+    })
+  })
+
   it('tracks progress updates', async () => {
     const { result } = renderHook(() =>
       useJobRun({ api: '/api/durably', runId: 'progress-run' }),

From 024d60fb2b4d099f38c4c423b27cbf1453008c7c Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 16:30:45 +0900
Subject: [PATCH 076/101] feat(durably-react): add isCancelled to useJob hook
 and update examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add isCancelled boolean helper to useJob hook for consistent cancelled
state handling. Update all browser example components to display
cancelled state UI and allow retry from cancelled runs in dashboards.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/routes/_index/dashboard.tsx                |  3 ++-
 .../app/routes/_index/data-sync-progress.tsx       |  2 ++
 .../routes/_index/image-processing-progress.tsx    |  2 ++
 .../app/routes/_index/run-progress.tsx             | 14 +++++++++++++-
 .../src/components/dashboard.tsx                   |  3 ++-
 .../src/components/data-sync-progress.tsx          |  2 ++
 .../src/components/image-processing-progress.tsx   |  2 ++
 .../src/components/run-progress.tsx                | 14 +++++++++++++-
 packages/durably-react/src/hooks/use-job.ts        |  5 +++++
 9 files changed, 43 insertions(+), 4 deletions(-)

diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
index c21d6266..df05a3e3 100644
--- a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -125,7 +125,8 @@ export function Dashboard() {
                         >
                           View
                         
-                        {run.status === 'failed' && (
+                        {(run.status === 'failed' ||
+                          run.status === 'cancelled') && (
                           
      
       )}
 
+      {/* Cancelled Result */}
+      {isCancelled && (
+        
      
+          
      Cancelled
      
+          
      
+            The job was cancelled before completion.
+          
      
+        
      
+      )}
+
       {/* Logs */}
       {logs.length > 0 && (
         
      
diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
index c21d6266..df05a3e3 100644
--- a/examples/browser-vite-react/src/components/dashboard.tsx
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -125,7 +125,8 @@ export function Dashboard() {
                         >
                           View
                         
-                        {run.status === 'failed' && (
+                        {(run.status === 'failed' ||
+                          run.status === 'cancelled') && (
                           
      
       )}
 
+      {/* Cancelled Result */}
+      {isCancelled && (
+        
      
+          
      Cancelled
      
+          
      
+            The job was cancelled before completion.
+          
      
+        
      
+      )}
+
       {/* Logs */}
       {logs.length > 0 && (
         
      
diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts
index c48c5467..e4249270 100644
--- a/packages/durably-react/src/hooks/use-job.ts
+++ b/packages/durably-react/src/hooks/use-job.ts
@@ -72,6 +72,10 @@ export interface UseJobResult {
    * Whether the run failed
    */
   isFailed: boolean
+  /**
+   * Whether the run was cancelled
+   */
+  isCancelled: boolean
   /**
    * Current run ID
    */
@@ -346,6 +350,7 @@ export function useJob<
     isPending: status === 'pending',
     isCompleted: status === 'completed',
     isFailed: status === 'failed',
+    isCancelled: status === 'cancelled',
     currentRunId,
     reset,
   }

From 102eb58bb59fc60fc7af5d09cd7ed59fa29f4d95 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 16:47:51 +0900
Subject: [PATCH 077/101] fix(durably): keep SSE stream open on fail/cancel to
 allow retry tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Previously, the subscribe() stream would close on run:fail and run:cancel
events, preventing subsequent retry events from being received. Now only
run:complete closes the stream since completed runs cannot be retried.

Also fixes runId change handling in useSSESubscription by resetting state.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../src/client/use-sse-subscription.ts        |  16 ++-
 .../tests/browser/use-job-run.test.tsx        | 135 ++++++++++++++++++
 packages/durably/src/durably.ts               |  15 +-
 3 files changed, 159 insertions(+), 7 deletions(-)

diff --git a/packages/durably-react/src/client/use-sse-subscription.ts b/packages/durably-react/src/client/use-sse-subscription.ts
index 53efe68a..48d6b74a 100644
--- a/packages/durably-react/src/client/use-sse-subscription.ts
+++ b/packages/durably-react/src/client/use-sse-subscription.ts
@@ -46,10 +46,24 @@ export function useSSESubscription(
 
   const eventSourceRef = useRef(null)
   const runIdRef = useRef(runId)
-  runIdRef.current = runId
+  const prevRunIdRef = useRef(null)
 
   const maxLogs = options?.maxLogs ?? 0
 
+  // Reset state when runId changes
+  if (prevRunIdRef.current !== runId) {
+    prevRunIdRef.current = runId
+    // Only reset if this isn't the initial render (runIdRef already set)
+    if (runIdRef.current !== runId) {
+      setStatus(null)
+      setOutput(null)
+      setError(null)
+      setLogs([])
+      setProgress(null)
+    }
+  }
+  runIdRef.current = runId
+
   // Subscribe to SSE events
   useEffect(() => {
     if (!api || !runId) return
diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx
index f97798ce..bbb9cc0f 100644
--- a/packages/durably-react/tests/browser/use-job-run.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-run.test.tsx
@@ -300,6 +300,141 @@ describe('useJobRun', () => {
     )
   })
 
+  it('tracks retry from failed through completion', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
+    // Job that fails first time, succeeds on retry (use attempt counter via steps)
+    let attemptCount = 0
+    const retryableJob = defineJob({
+      name: 'retryable-job',
+      input: z.object({ input: z.string() }),
+      output: z.object({ result: z.string() }),
+      run: async (context, payload) => {
+        attemptCount++
+        await context.run('process', async () => {
+          await new Promise((r) => setTimeout(r, 30))
+        })
+        if (attemptCount === 1) {
+          throw new Error('First attempt failed')
+        }
+        return { result: `success: ${payload.input}` }
+      },
+    })
+
+    function useTriggerAndSubscribe() {
+      const { isReady: durablyReady } = useDurably()
+      const [runId, setRunId] = useState(null)
+      const subscription = useJobRun<{ result: string }>({ runId })
+
+      return {
+        ...subscription,
+        isReady: durablyReady && subscription.isReady,
+        runId,
+        setRunId,
+      }
+    }
+
+    const { result } = renderHook(() => useTriggerAndSubscribe(), {
+      wrapper: createWrapper(durably),
+    })
+
+    await waitFor(() => expect(result.current.isReady).toBe(true))
+
+    const d = durably.register({ _job: retryableJob })
+    const run = await d.jobs._job.trigger({ input: 'test' })
+    result.current.setRunId(run.id)
+
+    // Wait for the run to fail
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('failed')
+      },
+      { timeout: 3000 },
+    )
+
+    // Retry the run (worker is still running, will pick it up)
+    await durably.retry(run.id)
+
+    // Should track through to completion
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('completed')
+        expect(result.current.output).toEqual({ result: 'success: test' })
+      },
+      { timeout: 3000 },
+    )
+  })
+
+  it('tracks retry from cancelled through completion', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
+    // Use autoStart=false wrapper so we can control when the worker runs
+    const noAutoStartWrapper = ({ children }: { children: ReactNode }) => (
+      
+        {children}
+      
+    )
+
+    function useTriggerAndSubscribe() {
+      const { isReady: durablyReady } = useDurably()
+      const [runId, setRunId] = useState(null)
+      const subscription = useJobRun<{ result: string }>({ runId })
+
+      return {
+        ...subscription,
+        isReady: durablyReady && subscription.isReady,
+        runId,
+        setRunId,
+      }
+    }
+
+    const { result } = renderHook(() => useTriggerAndSubscribe(), {
+      wrapper: noAutoStartWrapper,
+    })
+
+    await waitFor(() => expect(result.current.isReady).toBe(true))
+
+    const d = durably.register({ _job: testJob })
+    const run = await d.jobs._job.trigger({ input: 'test' })
+    result.current.setRunId(run.id)
+
+    // Cancel the pending run
+    await durably.cancel(run.id)
+
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('cancelled')
+        expect(result.current.isCancelled).toBe(true)
+      },
+      { timeout: 3000 },
+    )
+
+    // Retry the run
+    await durably.retry(run.id)
+
+    // Should see pending
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('pending')
+      },
+      { timeout: 3000 },
+    )
+
+    // Start the worker to process the retry
+    durably.start()
+
+    // Should track through to completion
+    await waitFor(
+      () => {
+        expect(result.current.status).toBe('completed')
+        expect(result.current.output).toEqual({ result: 'processed: test' })
+      },
+      { timeout: 3000 },
+    )
+  })
+
   it('tracks progress updates', async () => {
     const durably = await createTestDurably({ pollingInterval: 50 })
     instances.push(durably)
diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts
index 1c44e893..7fdf7c14 100644
--- a/packages/durably/src/durably.ts
+++ b/packages/durably/src/durably.ts
@@ -294,18 +294,20 @@ function createDurablyInstance<
           const unsubscribeFail = eventEmitter.on('run:fail', (event) => {
             if (!closed && event.runId === runId) {
               controller.enqueue(event)
-              closed = true
-              cleanup()
-              controller.close()
+              // Don't close stream on fail - retry is possible
             }
           })
 
           const unsubscribeCancel = eventEmitter.on('run:cancel', (event) => {
             if (!closed && event.runId === runId) {
               controller.enqueue(event)
-              closed = true
-              cleanup()
-              controller.close()
+              // Don't close stream on cancel - retry is possible
+            }
+          })
+
+          const unsubscribeRetry = eventEmitter.on('run:retry', (event) => {
+            if (!closed && event.runId === runId) {
+              controller.enqueue(event)
             }
           })
 
@@ -353,6 +355,7 @@ function createDurablyInstance<
             unsubscribeComplete()
             unsubscribeFail()
             unsubscribeCancel()
+            unsubscribeRetry()
             unsubscribeProgress()
             unsubscribeStepStart()
             unsubscribeStepComplete()

From 53982e478af199b983437953f933ac7a2cdce938 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 17:11:50 +0900
Subject: [PATCH 078/101] feat(durably): add delete endpoint and enhance
 useRunActions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add DELETE /run endpoint to server handler for deleting runs
- Add deleteRun() and getRun() to useRunActions client hook
- Export RunRecord type from durably-react/client
- Add View/Delete buttons and details modal to fullstack dashboard
- Add cancelled state UI and logs display to fullstack RunProgress

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/routes/_index/dashboard.tsx           | 139 ++++++++++++++++--
 .../app/routes/_index/run-progress.tsx        |  33 +++++
 packages/durably-react/src/client.ts          |   1 +
 packages/durably-react/src/client/index.ts    |   1 +
 .../src/client/use-run-actions.ts             |  86 ++++++++++-
 packages/durably/src/server.ts                |  39 +++++
 6 files changed, 287 insertions(+), 12 deletions(-)

diff --git a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
index 088f16a9..783e1c7a 100644
--- a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
@@ -5,7 +5,9 @@
  * First page auto-subscribes to SSE for instant updates.
  */
 
+import type { RunRecord } from '@coji/durably-react/client'
 import { useRunActions, useRuns } from '@coji/durably-react/client'
+import { useState } from 'react'
 
 export function Dashboard() {
   const { runs, isLoading, error, page, hasMore, nextPage, prevPage, refresh } =
@@ -18,11 +20,15 @@ export function Dashboard() {
   const {
     cancel,
     retry,
+    deleteRun,
+    getRun,
     isLoading: isActioning,
   } = useRunActions({
     api: '/api/durably',
   })
 
+  const [selectedRun, setSelectedRun] = useState(null)
+
   const handleCancel = async (runId: string) => {
     await cancel(runId)
     refresh()
@@ -33,6 +39,29 @@ export function Dashboard() {
     refresh()
   }
 
+  const handleDelete = async (runId: string) => {
+    await deleteRun(runId)
+    setSelectedRun(null)
+    refresh()
+  }
+
+  const showDetails = async (runId: string) => {
+    const run = await getRun(runId)
+    if (run) {
+      setSelectedRun(run)
+    }
+  }
+
+  const formatDate = (iso: string) => new Date(iso).toLocaleString()
+
+  const statusClasses: Record = {
+    pending: 'bg-yellow-100 text-yellow-800',
+    running: 'bg-blue-100 text-blue-800',
+    completed: 'bg-green-100 text-green-800',
+    failed: 'bg-red-100 text-red-800',
+    cancelled: 'bg-gray-100 text-gray-800',
+  }
+
   return (
     
      
       
      
@@ -79,12 +108,19 @@ export function Dashboard() {
                   )}
                 
      
                 
      
+                  
                   {(r.status === 'pending' || r.status === 'running') && (
                     
@@ -94,21 +130,23 @@ export function Dashboard() {
                       type="button"
                       onClick={() => handleRetry(r.id)}
                       disabled={isActioning}
-                      className="text-xs text-blue-600 hover:text-blue-800 disabled:text-gray-400 disabled:cursor-not-allowed"
+                      className="text-xs text-green-600 hover:text-green-800 disabled:text-gray-400 disabled:cursor-not-allowed"
                     >
                       Retry
                     
                   )}
+                  {r.status !== 'running' && r.status !== 'pending' && (
+                    
+                  )}
                   
                     {r.status}
                   
@@ -139,6 +177,85 @@ export function Dashboard() {
           
      
         
       )}
+
+      {/* Run Details Modal */}
+      {selectedRun && (
+        
      
+          
      
+            
      
+              
      
+                
      Run Details
      
+                
+              
      
+
+              
      
+                
      
+                  ID:{' '}
+                  
+                    {selectedRun.id}
+                  
+                
      
+                
      
+                  Job:{' '}
+                  {selectedRun.jobName}
+                
      
+                
      
+                  Status:{' '}
+                  
+                    {selectedRun.status}
+                  
+                
      
+                
      
+                  Created:{' '}
+                  {formatDate(selectedRun.createdAt)}
+                
      
+
+                {selectedRun.progress && (
+                  
      
+                    Progress:{' '}
+                    {selectedRun.progress.current}
+                    {selectedRun.progress.total
+                      ? `/${selectedRun.progress.total}`
+                      : ''}{' '}
+                    {selectedRun.progress.message || ''}
+                  
      
+                )}
+
+                {selectedRun.error && (
+                  
      
+                    Error:{' '}
+                    {selectedRun.error}
+                  
      
+                )}
+
+                {selectedRun.output !== null && (
+                  
      
+                    Output:
+                    
      +                      {JSON.stringify(selectedRun.output, null, 2)}
+                    
      
+                  
      
+                )}
+
+                
      
+                  Payload:
+                  
      +                    {JSON.stringify(selectedRun.payload, null, 2)}
+                  
      
+                
      
+              
      
+            
      
+          
      
+        
      
+      )}
     
      
   )
 }
diff --git a/examples/fullstack-react-router/app/routes/_index/run-progress.tsx b/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
index 696662c7..2b04b348 100644
--- a/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
@@ -54,6 +54,16 @@ export function RunProgress({ runId }: RunProgressProps) {
         
      
       )}
 
+      {/* Cancelled State */}
+      {run.isCancelled && (
+        
      
+          
      Import Cancelled
      
+          
      
+            The import was cancelled before completion.
+          
      
+        
      
+      )}
+
       {/* Success Result */}
       {run.isCompleted && run.output && (
         
      
@@ -72,6 +82,29 @@ export function RunProgress({ runId }: RunProgressProps) {
           
      {run.error}
      
         
      
       )}
+
+      {/* Logs Display */}
+      {run.logs.length > 0 && (
+        
      
+          
      Logs
      
+          
      
+            {run.logs.map((log) => (
+              
      
+                [{log.level}] {log.message}
+              
      
+            ))}
+          
      
+        
      
+      )}
     
   )
 }
diff --git a/packages/durably-react/src/client.ts b/packages/durably-react/src/client.ts
index 107f67fb..fc2ca05b 100644
--- a/packages/durably-react/src/client.ts
+++ b/packages/durably-react/src/client.ts
@@ -37,6 +37,7 @@ export type {
 
 export { useRunActions } from './client/use-run-actions'
 export type {
+  RunRecord,
   UseRunActionsClientOptions,
   UseRunActionsClientResult,
 } from './client/use-run-actions'
diff --git a/packages/durably-react/src/client/index.ts b/packages/durably-react/src/client/index.ts
index 41e9b339..f1bcb4f7 100644
--- a/packages/durably-react/src/client/index.ts
+++ b/packages/durably-react/src/client/index.ts
@@ -37,6 +37,7 @@ export type {
 
 export { useRunActions } from './use-run-actions'
 export type {
+  RunRecord,
   UseRunActionsClientOptions,
   UseRunActionsClientResult,
 } from './use-run-actions'
diff --git a/packages/durably-react/src/client/use-run-actions.ts b/packages/durably-react/src/client/use-run-actions.ts
index e80b83bc..c03b78eb 100644
--- a/packages/durably-react/src/client/use-run-actions.ts
+++ b/packages/durably-react/src/client/use-run-actions.ts
@@ -1,5 +1,21 @@
 import { useCallback, useState } from 'react'
 
+/**
+ * Run record returned from the server API
+ */
+export interface RunRecord {
+  id: string
+  jobName: string
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  payload: unknown
+  output: unknown | null
+  error: string | null
+  progress: { current: number; total?: number; message?: string } | null
+  createdAt: string
+  startedAt: string | null
+  completedAt: string | null
+}
+
 export interface UseRunActionsClientOptions {
   /**
    * API endpoint URL (e.g., '/api/durably')
@@ -9,13 +25,21 @@ export interface UseRunActionsClientOptions {
 
 export interface UseRunActionsClientResult {
   /**
-   * Retry a failed run
+   * Retry a failed or cancelled run
    */
   retry: (runId: string) => Promise
   /**
    * Cancel a pending or running run
    */
   cancel: (runId: string) => Promise
+  /**
+   * Delete a run (only completed, failed, or cancelled runs)
+   */
+  deleteRun: (runId: string) => Promise
+  /**
+   * Get a single run by ID
+   */
+  getRun: (runId: string) => Promise
   /**
    * Whether an action is in progress
    */
@@ -114,9 +138,69 @@ export function useRunActions(
     [api],
   )
 
+  const deleteRun = useCallback(
+    async (runId: string) => {
+      setIsLoading(true)
+      setError(null)
+
+      try {
+        const url = `${api}/run?runId=${encodeURIComponent(runId)}`
+        const response = await fetch(url, { method: 'DELETE' })
+
+        if (!response.ok) {
+          const data = await response.json()
+          throw new Error(
+            data.error || `Failed to delete: ${response.statusText}`,
+          )
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error'
+        setError(message)
+        throw err
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [api],
+  )
+
+  const getRun = useCallback(
+    async (runId: string): Promise => {
+      setIsLoading(true)
+      setError(null)
+
+      try {
+        const url = `${api}/run?runId=${encodeURIComponent(runId)}`
+        const response = await fetch(url)
+
+        if (response.status === 404) {
+          return null
+        }
+
+        if (!response.ok) {
+          const data = await response.json()
+          throw new Error(
+            data.error || `Failed to get run: ${response.statusText}`,
+          )
+        }
+
+        return (await response.json()) as RunRecord
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error'
+        setError(message)
+        throw err
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [api],
+  )
+
   return {
     retry,
     cancel,
+    deleteRun,
+    getRun,
     isLoading,
     error,
   }
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index 8a184ef3..fdb32601 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -102,6 +102,13 @@ export interface DurablyHandler {
    */
   cancel(request: Request): Promise
 
+  /**
+   * Handle delete request
+   * Expects DELETE with query param: runId
+   * Returns JSON: { success: true }
+   */
+  delete(request: Request): Promise
+
   /**
    * Handle runs subscription request
    * Expects GET with optional query param: jobName
@@ -165,6 +172,11 @@ export function createDurablyHandler(
         if (path === '/cancel') return handler.cancel(request)
       }
 
+      // DELETE routes
+      if (method === 'DELETE') {
+        if (path === '/run') return handler.delete(request)
+      }
+
       return new Response('Not Found', { status: 404 })
     },
 
@@ -370,6 +382,33 @@ export function createDurablyHandler(
       }
     },
 
+    async delete(request: Request): Promise {
+      try {
+        const url = new URL(request.url)
+        const runId = url.searchParams.get('runId')
+
+        if (!runId) {
+          return new Response(
+            JSON.stringify({ error: 'runId query parameter is required' }),
+            { status: 400, headers: { 'Content-Type': 'application/json' } },
+          )
+        }
+
+        await durably.deleteRun(runId)
+
+        return new Response(JSON.stringify({ success: true }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error'
+        return new Response(JSON.stringify({ error: message }), {
+          status: 500,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+    },
+
     runsSubscribe(request: Request): Response {
       const url = new URL(request.url)
       const jobNameFilter = url.searchParams.get('jobName')

From 9992fb1935e56f55c15778a0953ac6684d46220f Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 19:04:07 +0900
Subject: [PATCH 079/101] feat(durably): add steps endpoint and unify example
 dashboards
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add GET /steps endpoint to server handler
- Add getSteps() and StepRecord type to useRunActions client hook
- Add steps display to fullstack dashboard modal
- Add progress bar column to browser example dashboards

All three example dashboards now have consistent features:
- View, Retry, Cancel, Delete buttons
- Details modal with steps display
- Progress bar in list view
- Pagination

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/routes/_index/dashboard.tsx           | 23 ++++++++++
 .../src/components/dashboard.tsx              | 23 ++++++++++
 .../app/routes/_index/dashboard.tsx           | 31 +++++++++++++-
 packages/durably-react/src/client.ts          |  1 +
 packages/durably-react/src/client/index.ts    |  1 +
 .../src/client/use-run-actions.ts             | 42 +++++++++++++++++++
 packages/durably/src/server.ts                | 35 ++++++++++++++++
 7 files changed, 155 insertions(+), 1 deletion(-)

diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
index df05a3e3..b1305c1d 100644
--- a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -91,6 +91,9 @@ export function Dashboard() {
                   
                     Status
                   
+                  
+                    Progress
+                  
                   
                     Created
                   
@@ -113,6 +116,26 @@ export function Dashboard() {
                         {run.status}
                       
                     
+                    
+                      {run.progress ? (
+                        
      
+                          
      
+                            
      
+                          
      
+                          
+                            {run.progress.current}
+                            {run.progress.total && `/${run.progress.total}`}
+                          
+                        
      
+                      ) : (
+                        -
+                      )}
+                    
                     
                       {formatDate(run.createdAt)}
                     
diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
index df05a3e3..b1305c1d 100644
--- a/examples/browser-vite-react/src/components/dashboard.tsx
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -91,6 +91,9 @@ export function Dashboard() {
                   
                     Status
                   
+                  
+                    Progress
+                  
                   
                     Created
                   
@@ -113,6 +116,26 @@ export function Dashboard() {
                         {run.status}
                       
                     
+                    
+                      {run.progress ? (
+                        
      
+                          
      
+                            
      
+                          
      
+                          
+                            {run.progress.current}
+                            {run.progress.total && `/${run.progress.total}`}
+                          
+                        
      
+                      ) : (
+                        -
+                      )}
+                    
                     
                       {formatDate(run.createdAt)}
                     
diff --git a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
index 783e1c7a..c8b0e6f0 100644
--- a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
@@ -5,7 +5,7 @@
  * First page auto-subscribes to SSE for instant updates.
  */
 
-import type { RunRecord } from '@coji/durably-react/client'
+import type { RunRecord, StepRecord } from '@coji/durably-react/client'
 import { useRunActions, useRuns } from '@coji/durably-react/client'
 import { useState } from 'react'
 
@@ -22,12 +22,14 @@ export function Dashboard() {
     retry,
     deleteRun,
     getRun,
+    getSteps,
     isLoading: isActioning,
   } = useRunActions({
     api: '/api/durably',
   })
 
   const [selectedRun, setSelectedRun] = useState(null)
+  const [steps, setSteps] = useState([])
 
   const handleCancel = async (runId: string) => {
     await cancel(runId)
@@ -49,6 +51,8 @@ export function Dashboard() {
     const run = await getRun(runId)
     if (run) {
       setSelectedRun(run)
+      const stepsData = await getSteps(runId)
+      setSteps(stepsData)
     }
   }
 
@@ -251,6 +255,31 @@ export function Dashboard() {
                     {JSON.stringify(selectedRun.payload, null, 2)}
                   
                 
      
+
+                {steps.length > 0 && (
+                  
      
+                    Steps:
+                    
        
+                      {steps.map((s) => (
+                        
      • 
+                          {s.name}
+                          
+                            {s.status}
+                          
+                        
        • 
+                      ))}
+                    
      
+                  
      
+                )}
               
      
             
      
           
      
diff --git a/packages/durably-react/src/client.ts b/packages/durably-react/src/client.ts
index fc2ca05b..01fbe68c 100644
--- a/packages/durably-react/src/client.ts
+++ b/packages/durably-react/src/client.ts
@@ -38,6 +38,7 @@ export type {
 export { useRunActions } from './client/use-run-actions'
 export type {
   RunRecord,
+  StepRecord,
   UseRunActionsClientOptions,
   UseRunActionsClientResult,
 } from './client/use-run-actions'
diff --git a/packages/durably-react/src/client/index.ts b/packages/durably-react/src/client/index.ts
index f1bcb4f7..ae88c2e6 100644
--- a/packages/durably-react/src/client/index.ts
+++ b/packages/durably-react/src/client/index.ts
@@ -38,6 +38,7 @@ export type {
 export { useRunActions } from './use-run-actions'
 export type {
   RunRecord,
+  StepRecord,
   UseRunActionsClientOptions,
   UseRunActionsClientResult,
 } from './use-run-actions'
diff --git a/packages/durably-react/src/client/use-run-actions.ts b/packages/durably-react/src/client/use-run-actions.ts
index c03b78eb..42b79b10 100644
--- a/packages/durably-react/src/client/use-run-actions.ts
+++ b/packages/durably-react/src/client/use-run-actions.ts
@@ -16,6 +16,15 @@ export interface RunRecord {
   completedAt: string | null
 }
 
+/**
+ * Step record returned from the server API
+ */
+export interface StepRecord {
+  name: string
+  status: 'completed' | 'failed'
+  output: unknown
+}
+
 export interface UseRunActionsClientOptions {
   /**
    * API endpoint URL (e.g., '/api/durably')
@@ -40,6 +49,10 @@ export interface UseRunActionsClientResult {
    * Get a single run by ID
    */
   getRun: (runId: string) => Promise
+  /**
+   * Get steps for a run
+   */
+  getSteps: (runId: string) => Promise
   /**
    * Whether an action is in progress
    */
@@ -196,11 +209,40 @@ export function useRunActions(
     [api],
   )
 
+  const getSteps = useCallback(
+    async (runId: string): Promise => {
+      setIsLoading(true)
+      setError(null)
+
+      try {
+        const url = `${api}/steps?runId=${encodeURIComponent(runId)}`
+        const response = await fetch(url)
+
+        if (!response.ok) {
+          const data = await response.json()
+          throw new Error(
+            data.error || `Failed to get steps: ${response.statusText}`,
+          )
+        }
+
+        return (await response.json()) as StepRecord[]
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Unknown error'
+        setError(message)
+        throw err
+      } finally {
+        setIsLoading(false)
+      }
+    },
+    [api],
+  )
+
   return {
     retry,
     cancel,
     deleteRun,
     getRun,
+    getSteps,
     isLoading,
     error,
   }
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index fdb32601..e9ed0ee1 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -109,6 +109,13 @@ export interface DurablyHandler {
    */
   delete(request: Request): Promise
 
+  /**
+   * Handle steps request
+   * Expects GET with query param: runId
+   * Returns JSON array of steps
+   */
+  steps(request: Request): Promise
+
   /**
    * Handle runs subscription request
    * Expects GET with optional query param: jobName
@@ -162,6 +169,7 @@ export function createDurablyHandler(
         if (path === '/subscribe') return handler.subscribe(request)
         if (path === '/runs') return handler.runs(request)
         if (path === '/run') return handler.run(request)
+        if (path === '/steps') return handler.steps(request)
         if (path === '/runs/subscribe') return handler.runsSubscribe(request)
       }
 
@@ -409,6 +417,33 @@ export function createDurablyHandler(
       }
     },
 
+    async steps(request: Request): Promise {
+      try {
+        const url = new URL(request.url)
+        const runId = url.searchParams.get('runId')
+
+        if (!runId) {
+          return new Response(
+            JSON.stringify({ error: 'runId query parameter is required' }),
+            { status: 400, headers: { 'Content-Type': 'application/json' } },
+          )
+        }
+
+        const steps = await durably.storage.getSteps(runId)
+
+        return new Response(JSON.stringify(steps), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : 'Unknown error'
+        return new Response(JSON.stringify({ error: message }), {
+          status: 500,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      }
+    },
+
     runsSubscribe(request: Request): Response {
       const url = new URL(request.url)
       const jobNameFilter = url.searchParams.get('jobName')

From 272e0c964c670ee12599d81fdb1b7d667ded7bea Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 20:50:37 +0900
Subject: [PATCH 080/101] docs: update documentation to match v0.6.0 API
 implementation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update CHANGELOG with new features (run:trigger/cancel/retry events, type-safe jobs, useRunActions enhancements)
- Update spec-react.md with unified useRuns API, useRunActions extensions, type-safe client factories
- Update spec.md with new events (run:trigger, run:cancel, run:retry)
- Update durably-react README with DurablyProvider durably prop pattern and Server-Connected Mode
- Update durably-react llms.md with comprehensive API documentation
- Update durably README with zod import and consistent variable naming
- Update durably llms.md with new events and APIs
- Update website docs (browser-only, full-stack, events, durably-react API)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 CHANGELOG.md                        |  33 ++-
 docs/spec-react.md                  | 355 +++++++++++++++++++++++-----
 docs/spec.md                        |  62 ++++-
 packages/durably-react/README.md    |  49 +++-
 packages/durably-react/docs/llms.md | 272 +++++++++++++++++++--
 packages/durably/README.md          |   7 +-
 packages/durably/docs/llms.md       |  51 ++--
 website/api/create-durably.md       |  99 ++++++--
 website/api/durably-react.md        | 156 ++++++++++--
 website/api/events.md               |  52 ++++
 website/guide/browser-only.md       |  22 +-
 website/guide/full-stack.md         |   5 +-
 12 files changed, 1008 insertions(+), 155 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 7e09ab61..522c1390 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,7 +5,7 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
-## [0.6.0] - 2025-12-30
+## [0.6.0] - 2026-01-02
 
 ### Breaking Changes
 
@@ -15,6 +15,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Added
 
+#### @coji/durably
+
+- **New events for run lifecycle**:
+  - `run:trigger`: Emitted when a job is triggered (before worker picks it up)
+  - `run:cancel`: Emitted when a run is cancelled via `cancel()` API
+  - `run:retry`: Emitted when a failed/cancelled run is retried via `retry()` API
+- **Type-safe `durably.jobs` property**: Access registered jobs with full type inference
+  ```ts
+  const durably = createDurably({ dialect })
+    .register({ processImage, syncUsers })
+  await durably.jobs.processImage.trigger({ imageId: '123' }) // Type-safe
+  ```
+- **Retry from cancelled state**: `retry()` now works on both `failed` and `cancelled` runs
+
+#### @coji/durably/server
+
+- **New endpoints**:
+  - `GET /steps?runId=xxx`: Get steps for a run
+  - `DELETE /run?runId=xxx`: Delete a run
+- **SSE event streaming**: `/runs/subscribe` now streams `run:trigger`, `run:cancel`, `run:retry` events
+
 #### @coji/durably-react
 
 - `useRuns`: List and paginate job runs with filtering and real-time updates
@@ -27,15 +48,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 - `createDurablyClient`: Type-safe client factory for server-connected mode
 - `createJobHooks`: Per-job hook factory for server-connected mode
 
+#### @coji/durably-react/client
+
+- **`useRunActions` enhancements**:
+  - `deleteRun(runId)`: Delete a completed/failed/cancelled run
+  - `getRun(runId)`: Get a single run by ID
+  - `getSteps(runId)`: Get steps for a run
+- **New type exports**: `RunRecord`, `StepRecord` for type-safe run and step data
+
 ### Changed
 
 - Simplified README files - detailed documentation moved to website
 - Updated all examples to use new `register()` API pattern
 - Added Turbo for monorepo task orchestration
+- Unified dashboard UI across all examples (View, Retry, Cancel, Delete, Progress, Steps)
 
 ### Fixed
 
 - Type inference for `register()` return value now works correctly
+- SSE stream lifecycle properly cleaned up on client disconnect
 
 ## [0.5.0] - 2025-12-24
 
diff --git a/docs/spec-react.md b/docs/spec-react.md
index a80a21e8..65c682fa 100644
--- a/docs/spec-react.md
+++ b/docs/spec-react.md
@@ -361,17 +361,15 @@ const { logs, clear } = useJobLogs({ runId, maxLogs? })
 
 ```tsx
 const {
+  isReady,
   runs,
   isLoading,
-  error,
   page,
   hasMore,
   nextPage,
   prevPage,
   goToPage,
   refresh,
-  retry,
-  cancel,
 } = useRuns(options?)
 ```
 
@@ -379,22 +377,22 @@ const {
 |------------|------|------|
 | `jobName` | `string` | ジョブ名でフィルタ |
 | `status` | `RunStatus` | ステータスでフィルタ |
-| `limit` | `number` | 1ページの件数（デフォルト: 20） |
+| `pageSize` | `number` | 1ページの件数（デフォルト: 10） |
 | `realtime` | `boolean` | リアルタイム更新（デフォルト: true） |
 
 | 戻り値 | 型 | 説明 |
 |--------|-----|------|
+| `isReady` | `boolean` | 準備完了 |
 | `runs` | `Run[]` | Run 一覧 |
 | `isLoading` | `boolean` | 読み込み中 |
-| `error` | `string \| null` | エラー |
 | `page` | `number` | 現在ページ |
 | `hasMore` | `boolean` | 次ページあり |
 | `nextPage` | `() => void` | 次ページへ |
 | `prevPage` | `() => void` | 前ページへ |
 | `goToPage` | `(page: number) => void` | 指定ページへ |
 | `refresh` | `() => Promise` | 再読み込み |
-| `retry` | `(runId: string) => Promise` | Run を再実行 |
-| `cancel` | `(runId: string) => Promise` | Run をキャンセル |
+
+> **Note**: Run アクション（retry, cancel, delete）は `useDurably` から取得した Durably インスタンスを使用するか、サーバー連携モードでは `useRunActions` を使用する。
 
 ---
 
@@ -420,8 +418,10 @@ handler.trigger(request: Request): Promise      // POST /trigger
 handler.subscribe(request: Request): Response             // GET /subscribe?runId=xxx
 handler.runs(request: Request): Promise         // GET /runs
 handler.run(request: Request): Promise          // GET /run?runId=xxx
+handler.steps(request: Request): Promise        // GET /steps?runId=xxx
 handler.retry(request: Request): Promise        // POST /retry?runId=xxx
 handler.cancel(request: Request): Promise       // POST /cancel?runId=xxx
+handler.delete(request: Request): Promise       // DELETE /run?runId=xxx
 handler.runsSubscribe(request: Request): Response         // GET /runs/subscribe
 ```
 
@@ -433,14 +433,17 @@ handler.runsSubscribe(request: Request): Response         // GET /runs/subscribe
 | `{basePath}/subscribe?runId=xxx` | GET | - | SSE stream (single run) |
 | `{basePath}/runs` | GET | `?jobName=&status=&limit=&offset=` | `Run[]` |
 | `{basePath}/run?runId=xxx` | GET | - | `Run` or 404 |
+| `{basePath}/steps?runId=xxx` | GET | - | `Step[]` |
 | `{basePath}/retry?runId=xxx` | POST | - | `{ success: true }` |
 | `{basePath}/cancel?runId=xxx` | POST | - | `{ success: true }` |
+| `{basePath}/run?runId=xxx` | DELETE | - | `{ success: true }` |
 | `{basePath}/runs/subscribe` | GET | `?jobName=` | SSE stream (run updates) |
 
 > **Note**: 認証・認可、CORS、CSRF の扱いは本仕様のスコープ外。アプリケーション側で適切に実装すること。
 
 **SSE イベント形式**:
 
+Single run subscription (`/subscribe?runId=xxx`):
 ```text
 data: {"type":"run:start","runId":"xxx","jobName":"process-task","payload":{...}}
 
@@ -450,6 +453,28 @@ data: {"type":"run:complete","runId":"xxx","jobName":"process-task","output":{"s
 
 data: {"type":"run:fail","runId":"xxx","jobName":"process-task","error":"Something went wrong"}
 
+data: {"type":"run:cancel","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:retry","runId":"xxx","jobName":"process-task"}
+
+```
+
+Runs subscription (`/runs/subscribe`):
+```text
+data: {"type":"run:trigger","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:start","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:complete","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:fail","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:cancel","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:retry","runId":"xxx","jobName":"process-task"}
+
+data: {"type":"run:progress","runId":"xxx","jobName":"process-task","progress":{"current":1,"total":2}}
+
 ```
 
 #### クライアント側 (`@coji/durably-react/client`)
@@ -474,31 +499,31 @@ const {
   currentRunId,
   reset,
 } = useJob({
-  baseUrl: '/api/durably',
+  api: '/api/durably',
   jobName: 'process-task',
 })
 
 // 既存 Run の購読のみ
 const { status, output, error, logs, progress } = useJobRun({
-  baseUrl: '/api/durably',
+  api: '/api/durably',
   runId: 'xxx',
 })
 
 // ログ購読
 const { logs, clear } = useJobLogs({
-  baseUrl: '/api/durably',
+  api: '/api/durably',
   runId: 'xxx',
 })
 
 // Run 一覧
-const { runs, isLoading, refresh, retry, cancel } = useRuns({
-  baseUrl: '/api/durably',
+const { runs, isLoading, hasMore, nextPage, prevPage, refresh } = useRuns({
+  api: '/api/durably',
   jobName: 'process-task',
 })
 
 // Run アクション
-const { retry, cancel, isLoading, error } = useRunActions({
-  baseUrl: '/api/durably',
+const { retry, cancel, deleteRun, getRun, getSteps, isLoading, error } = useRunActions({
+  api: '/api/durably',
 })
 ```
 
@@ -506,7 +531,7 @@ const { retry, cancel, isLoading, error } = useRunActions({
 
 | オプション | 型 | 必須 | 説明 |
 |------------|------|------|------|
-| `baseUrl` | `string` | Yes | API エンドポイント |
+| `api` | `string` | Yes | API エンドポイント |
 | `jobName` | `string` | Yes | ジョブ名 |
 | `initialRunId` | `string` | - | 初期購読 Run ID（再接続用） |
 
@@ -514,39 +539,68 @@ const { retry, cancel, isLoading, error } = useRunActions({
 
 | オプション | 型 | 必須 | 説明 |
 |------------|------|------|------|
-| `baseUrl` | `string` | Yes | API エンドポイント |
+| `api` | `string` | Yes | API エンドポイント |
 | `runId` | `string \| null` | Yes | Run ID（`null` の場合は購読しない） |
 
 **useJobLogs オプション**:
 
 | オプション | 型 | 必須 | 説明 |
 |------------|------|------|------|
-| `baseUrl` | `string` | Yes | API エンドポイント |
-| `runId` | `string` | Yes | Run ID |
+| `api` | `string` | Yes | API エンドポイント |
+| `runId` | `string \| null` | Yes | Run ID（`null` の場合は購読しない） |
 | `maxLogs` | `number` | - | 保持する最大ログ数（デフォルト: 100） |
 
 **useRuns オプション**:
 
 | オプション | 型 | 必須 | 説明 |
 |------------|------|------|------|
-| `baseUrl` | `string` | Yes | API エンドポイント |
+| `api` | `string` | Yes | API エンドポイント |
 | `jobName` | `string` | - | ジョブ名でフィルタ |
 | `status` | `RunStatus` | - | ステータスでフィルタ |
-| `limit` | `number` | - | 1ページの件数（デフォルト: 20） |
-| `realtime` | `boolean` | - | リアルタイム更新（デフォルト: true） |
+| `pageSize` | `number` | - | 1ページの件数（デフォルト: 10） |
 
 **useRunActions オプション**:
 
-| オプション | 型 | 必須 | 説明 |
-|------------|------|------|------|
-| `baseUrl` | `string` | Yes | API エンドポイント |
+| オプション | 型       | 必須 | 説明               |
+|------------|----------|------|--------------------|
+| `api`      | `string` | Yes  | API エンドポイント |
 
-| 戻り値 | 型 | 説明 |
-|--------|------|------|
-| `retry` | `(runId: string) => Promise` | Run を再実行 |
-| `cancel` | `(runId: string) => Promise` | Run をキャンセル |
-| `isLoading` | `boolean` | アクション実行中 |
-| `error` | `string \| null` | エラーメッセージ |
+| 戻り値      | 型                                                 | 説明            |
+|-------------|---------------------------------------------------|-----------------|
+| `retry`     | `(runId: string) => Promise`                | Run を再実行    |
+| `cancel`    | `(runId: string) => Promise`                | Run をキャンセル |
+| `deleteRun` | `(runId: string) => Promise`                | Run を削除      |
+| `getRun`    | `(runId: string) => Promise`   | Run を取得      |
+| `getSteps`  | `(runId: string) => Promise`        | Steps を取得    |
+| `isLoading` | `boolean`                                         | アクション実行中 |
+| `error`     | `string \| null`                                  | エラーメッセージ |
+
+**RunRecord 型**:
+
+```ts
+interface RunRecord {
+  id: string
+  jobName: string
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  payload: unknown
+  output: unknown | null
+  error: string | null
+  progress: { current: number; total?: number; message?: string } | null
+  createdAt: string
+  startedAt: string | null
+  completedAt: string | null
+}
+```
+
+**StepRecord 型**:
+
+```ts
+interface StepRecord {
+  name: string
+  status: 'completed' | 'failed'
+  output: unknown
+}
+```
 
 ---
 
@@ -554,24 +608,30 @@ const { retry, cancel, isLoading, error } = useRunActions({
 
 ```tsx
 import { createDurablyClient, createJobHooks } from '@coji/durably-react/client'
-import type { processTask, syncUsers } from './jobs'
+import type { jobs } from './durably.server'  // サーバー側の jobs をインポート
 
-// 方法1: createDurablyClient
-const client = createDurablyClient<{
-  'process-task': typeof processTask
-  'sync-users': typeof syncUsers
-}>({ baseUrl: '/api/durably' })
+// 方法1: createDurablyClient（推奨）
+// サーバー側で register() した jobs の型を使用
+const durably = createDurablyClient({
+  api: '/api/durably',
+})
 
-const { trigger, status } = client.useJob('process-task')
+// 型安全なアクセス
+const { trigger, status } = durably.processTask.useJob()
 await trigger({ taskId: '123' })  // 型安全
 
-// 方法2: createJobHooks
-const { useProcessTask, useSyncUsers } = createJobHooks<{
-  'process-task': typeof processTask
-  'sync-users': typeof syncUsers
-}>({ baseUrl: '/api/durably' })
+const { status, output } = durably.processTask.useRun(runId)
+const { logs, clearLogs } = durably.processTask.useLogs(runId)
+
+// 方法2: createJobHooks（単一ジョブ用）
+import type { processTaskJob } from './jobs'
 
-const { trigger, status } = useProcessTask()
+const processTaskHooks = createJobHooks({
+  api: '/api/durably',
+  jobName: 'process-task',
+})
+
+const { trigger, status } = processTaskHooks.useJob()
 ```
 
 ---
@@ -600,13 +660,18 @@ interface LogEntry {
 
 // イベント（SSE で送信される）
 type DurablyEvent =
+  | { type: 'run:trigger'; runId: string; jobName: string; payload: unknown }
   | { type: 'run:start'; runId: string; jobName: string; payload: unknown }
   | { type: 'run:complete'; runId: string; jobName: string; output: unknown; duration: number }
-  | { type: 'run:fail'; runId: string; jobName: string; error: string }
+  | { type: 'run:fail'; runId: string; jobName: string; error: string; failedStepName: string }
+  | { type: 'run:cancel'; runId: string; jobName: string }
+  | { type: 'run:retry'; runId: string; jobName: string }
   | { type: 'run:progress'; runId: string; jobName: string; progress: Progress }
   | { type: 'step:start'; runId: string; jobName: string; stepName: string; stepIndex: number }
-  | { type: 'step:complete'; runId: string; jobName: string; stepName: string; stepIndex: number; output: unknown }
-  | { type: 'log:write'; runId: string; jobName: string; level: 'info' | 'warn' | 'error'; message: string; data: unknown }
+  | { type: 'step:complete'; runId: string; jobName: string; stepName: string; stepIndex: number; output: unknown; duration: number }
+  | { type: 'step:fail'; runId: string; jobName: string; stepName: string; stepIndex: number; error: string }
+  | { type: 'log:write'; runId: string; stepName: string | null; level: 'info' | 'warn' | 'error'; message: string; data: unknown }
+  | { type: 'worker:error'; error: string; context: string; runId?: string }
 ```
 
 ---
@@ -715,7 +780,7 @@ import { useJob } from '@coji/durably-react/client'
 
 function AIChat() {
   const { trigger, status, progress, output, logs } = useJob({
-    baseUrl: '/api/durably',
+    api: '/api/durably',
     jobName: 'ai-agent',
   })
 
@@ -750,7 +815,7 @@ function TaskPage() {
   const runId = searchParams.get('runId')
 
   const { trigger, status, output } = useJob({
-    baseUrl: '/api/durably',
+    api: '/api/durably',
     jobName: 'process-task',
     initialRunId: runId ?? undefined,  // 既存 Run を再購読
   })
@@ -771,12 +836,13 @@ function TaskPage() {
 }
 ```
 
-### Run 一覧ダッシュボード
+### Run 一覧ダッシュボード（ブラウザ完結モード）
 
 ```tsx
-import { useRuns } from '@coji/durably-react'
+import { useRuns, useDurably } from '@coji/durably-react'
 
 function Dashboard() {
+  const { durably } = useDurably()
   const {
     runs,
     isLoading,
@@ -785,9 +851,83 @@ function Dashboard() {
     nextPage,
     prevPage,
     refresh,
-    retry,
-    cancel,
-  } = useRuns({ limit: 10 })
+  } = useRuns({ pageSize: 10 })
+
+  const handleRetry = async (runId: string) => {
+    await durably?.retry(runId)
+    refresh()
+  }
+
+  const handleCancel = async (runId: string) => {
+    await durably?.cancel(runId)
+    refresh()
+  }
+
+  return (
+    
      
+      
+
+      
+        
+          
+            
+            
+            
+            
+          
+        
+        
+          {runs.map((run) => (
+            
+              
+              
+              
+              
+            
+          ))}
+        
+      
      IDJobStatusActions
      {run.id}{run.jobName}{run.status}
+                {(run.status === 'failed' || run.status === 'cancelled') && (
+                  
+                )}
+                {(run.status === 'pending' || run.status === 'running') && (
+                  
+                )}
+              
      
+
+      
      
+        
+        Page {page + 1}
+        
+      
      
+    
      
+  )
+}
+```
+
+### Run 一覧ダッシュボード（サーバー連携モード）
+
+```tsx
+import { useRuns, useRunActions } from '@coji/durably-react/client'
+
+function Dashboard() {
+  const { runs, isLoading, page, hasMore, nextPage, prevPage, refresh } = useRuns({
+    api: '/api/durably',
+    pageSize: 10,
+  })
+  const { retry, cancel, isLoading: isActioning } = useRunActions({
+    api: '/api/durably',
+  })
+
+  const handleRetry = async (runId: string) => {
+    await retry(runId)
+    refresh()
+  }
+
+  const handleCancel = async (runId: string) => {
+    await cancel(runId)
+    refresh()
+  }
 
   return (
     
      
@@ -809,11 +949,15 @@ function Dashboard() {
               {run.jobName}
               {run.status}
               
-                {run.status === 'failed' && (
-                  
+                {(run.status === 'failed' || run.status === 'cancelled') && (
+                  
                 )}
-                {run.status === 'pending' && (
-                  
+                {(run.status === 'pending' || run.status === 'running') && (
+                  
                 )}
               
             
@@ -881,3 +1025,100 @@ const { trigger, status } = useJob({
   subscribe: (runId) => new EventSource(`/custom/subscribe/${runId}`),
 })
 ```
+
+---
+
+## v1 からの変更点
+
+### @coji/durably コアパッケージ
+
+#### 型安全な `durably.jobs` API
+
+`register()` がオブジェクト形式を受け取り、型安全な `jobs` プロパティを返すようになった:
+
+```ts
+// 旧: 個別に register
+const processImageHandle = durably.register(processImageJob)
+const syncUsersHandle = durably.register(syncUsersJob)
+
+// 新: オブジェクト形式で一括登録、型安全な jobs プロパティ
+const durably = createDurably({ dialect })
+  .register({
+    processImage: processImageJob,
+    syncUsers: syncUsersJob,
+  })
+
+// 型安全なアクセス
+await durably.jobs.processImage.trigger({ imageId: '123' })
+await durably.jobs.syncUsers.trigger({ source: 'api' })
+```
+
+#### 新しいイベント
+
+以下のイベントが追加された:
+
+| イベント        | 説明                                |
+|-----------------|-------------------------------------|
+| `run:trigger`   | ジョブがトリガーされた時（Worker 実行前） |
+| `run:cancel`    | Run がキャンセルされた時             |
+| `run:retry`     | Run がリトライされた時               |
+
+#### `subscribe()` メソッド
+
+`durably.subscribe(runId)` で特定 Run のイベントを `ReadableStream` で購読可能:
+
+```ts
+const stream = durably.subscribe(runId)
+const reader = stream.getReader()
+
+while (true) {
+  const { done, value } = await reader.read()
+  if (done) break
+  console.log(value) // DurablyEvent
+}
+```
+
+#### `getJob()` メソッド
+
+名前で登録済みジョブを取得:
+
+```ts
+const job = durably.getJob('process-image')
+if (job) {
+  await job.trigger({ imageId: '123' })
+}
+```
+
+### @coji/durably/server
+
+#### 新しいエンドポイント
+
+| エンドポイント                 | メソッド | 説明                     |
+|--------------------------------|----------|--------------------------|
+| `{basePath}/steps?runId=xxx`   | GET      | Run のステップ一覧を取得 |
+| `{basePath}/run?runId=xxx`     | DELETE   | Run を削除               |
+
+#### SSE イベント拡張
+
+`/runs/subscribe` エンドポイントで以下の新しいイベントを配信:
+
+- `run:trigger` - ジョブトリガー時
+- `run:cancel` - キャンセル時
+- `run:retry` - リトライ時
+
+### @coji/durably-react/client
+
+#### `useRunActions` の拡張
+
+新しいメソッドが追加された:
+
+| メソッド      | 説明              |
+|---------------|-------------------|
+| `deleteRun()` | Run を削除        |
+| `getRun()`    | Run を取得        |
+| `getSteps()`  | Steps を取得      |
+
+新しい型がエクスポートされた:
+
+- `RunRecord` - Run のレコード型
+- `StepRecord` - Step のレコード型
diff --git a/docs/spec.md b/docs/spec.md
index 66f25229..2e828163 100644
--- a/docs/spec.md
+++ b/docs/spec.md
@@ -441,6 +441,11 @@ await durably.migrate()
 ライブラリ内部で起きたことを外部に通知するためのイベントシステムを持つ。これにより、ログの永続化、外部サービスへの送信、リアルタイム UI 更新など、任意の処理を接続できる。
 
 ```ts
+durably.on('run:trigger', (event) => {
+  // { runId, jobName, payload, timestamp }
+  // ジョブがトリガーされた時（Worker 実行前）
+})
+
 durably.on('run:start', (event) => {
   // { runId, jobName, payload, timestamp }
 })
@@ -453,6 +458,16 @@ durably.on('run:fail', (event) => {
   // { runId, jobName, error, failedStepName, timestamp }
 })
 
+durably.on('run:cancel', (event) => {
+  // { runId, jobName, timestamp }
+  // Run がキャンセルされた時
+})
+
+durably.on('run:retry', (event) => {
+  // { runId, jobName, timestamp }
+  // Run がリトライされた時
+})
+
 durably.on('run:progress', (event) => {
   // { runId, jobName, progress: { current, total?, message? }, timestamp }
 })
@@ -495,6 +510,13 @@ interface BaseEvent {
 }
 
 // Run イベント
+interface RunTriggerEvent extends BaseEvent {
+  type: 'run:trigger'
+  runId: string
+  jobName: string
+  payload: unknown
+}
+
 interface RunStartEvent extends BaseEvent {
   type: 'run:start'
   runId: string
@@ -518,6 +540,18 @@ interface RunFailEvent extends BaseEvent {
   failedStepName: string
 }
 
+interface RunCancelEvent extends BaseEvent {
+  type: 'run:cancel'
+  runId: string
+  jobName: string
+}
+
+interface RunRetryEvent extends BaseEvent {
+  type: 'run:retry'
+  runId: string
+  jobName: string
+}
+
 interface RunProgressEvent extends BaseEvent {
   type: 'run:progress'
   runId: string
@@ -573,9 +607,12 @@ interface WorkerErrorEvent extends BaseEvent {
 
 // 全イベントの Union 型
 type DurablyEvent =
+  | RunTriggerEvent
   | RunStartEvent
   | RunCompleteEvent
   | RunFailEvent
+  | RunCancelEvent
+  | RunRetryEvent
   | RunProgressEvent
   | StepStartEvent
   | StepCompleteEvent
@@ -836,17 +873,20 @@ Run の取得クエリは以下の条件を満たすものを一件取得する
 
 ### イベント発火タイミング
 
-| イベント | 発火タイミング |
-|----------|----------------|
-| run:start | Run が running に遷移した直後 |
-| run:complete | Run が completed に遷移した直後 |
-| run:fail | Run が failed に遷移した直後 |
-| run:progress | step.progress が呼ばれた直後 |
-| step:start | ステップの実行を開始する直前 |
-| step:complete | ステップが成功し DB に記録した直後 |
-| step:fail | ステップが失敗し DB に記録した直後 |
-| log:write | step.log が呼ばれた直後 |
-| worker:error | ワーカー内部でエラーが発生した時（ハートビート失敗など） |
+| イベント       | 発火タイミング                                           |
+|----------------|----------------------------------------------------------|
+| run:trigger    | trigger() が呼ばれ、Run が pending として作成された直後   |
+| run:start      | Run が running に遷移した直後                             |
+| run:complete   | Run が completed に遷移した直後                           |
+| run:fail       | Run が failed に遷移した直後                              |
+| run:cancel     | cancel() が呼ばれ、Run が cancelled に遷移した直後        |
+| run:retry      | retry() が呼ばれ、Run が pending に戻った直後             |
+| run:progress   | step.progress が呼ばれた直後                              |
+| step:start     | ステップの実行を開始する直前                              |
+| step:complete  | ステップが成功し DB に記録した直後                        |
+| step:fail      | ステップが失敗し DB に記録した直後                        |
+| log:write      | step.log が呼ばれた直後                                   |
+| worker:error   | ワーカー内部でエラーが発生した時（ハートビート失敗など）   |
 
 ### 設定項目
 
diff --git a/packages/durably-react/README.md b/packages/durably-react/README.md
index c7b5fe74..77da82d5 100644
--- a/packages/durably-react/README.md
+++ b/packages/durably-react/README.md
@@ -19,9 +19,11 @@ npm install @coji/durably-react
 ## Quick Start
 
 ```tsx
-import { defineJob } from '@coji/durably'
+import { Suspense } from 'react'
+import { createDurably, defineJob } from '@coji/durably'
 import { DurablyProvider, useJob } from '@coji/durably-react'
 import { SQLocalKysely } from 'sqlocal/kysely'
+import { z } from 'zod'
 
 const myJob = defineJob({
   name: 'my-job',
@@ -33,13 +35,24 @@ const myJob = defineJob({
   },
 })
 
+// Initialize Durably
+async function initDurably() {
+  const sqlocal = new SQLocalKysely('app.sqlite3')
+  const durably = createDurably({ dialect: sqlocal.dialect })
+  durably.register({ myJob })
+  await durably.migrate()
+  return durably
+}
+
+const durablyPromise = initDurably()
+
 function App() {
   return (
-     new SQLocalKysely('app.sqlite3').dialect}
-    >
-      
-    
+    Loading...
      }>
+      
+        
+      
+    
   )
 }
 
@@ -53,6 +66,30 @@ function MyComponent() {
 }
 ```
 
+## Server-Connected Mode
+
+For full-stack apps, use hooks from `@coji/durably-react/client`:
+
+```tsx
+import { useJob } from '@coji/durably-react/client'
+
+function MyComponent() {
+  const { trigger, status, output, isRunning } = useJob<
+    { id: string },
+    { result: number }
+  >({
+    api: '/api/durably',
+    jobName: 'my-job',
+  })
+
+  return (
+    
+  )
+}
+```
+
 ## Documentation
 
 For full documentation, visit [coji.github.io/durably](https://coji.github.io/durably/).
diff --git a/packages/durably-react/docs/llms.md b/packages/durably-react/docs/llms.md
index 7edb63be..bce4f7ad 100644
--- a/packages/durably-react/docs/llms.md
+++ b/packages/durably-react/docs/llms.md
@@ -23,20 +23,38 @@ npm install @coji/durably-react
 
 ### DurablyProvider
 
-Wraps your app and initializes Durably:
+Wraps your app and provides the Durably instance to all hooks:
 
 ```tsx
+import { Suspense } from 'react'
 import { DurablyProvider } from '@coji/durably-react'
+import { createDurably } from '@coji/durably'
 import { SQLocalKysely } from 'sqlocal/kysely'
 
+// Create and initialize Durably
+async function initDurably() {
+  const sqlocal = new SQLocalKysely('app.sqlite3')
+  const durably = createDurably({ dialect: sqlocal.dialect })
+  await durably.migrate()
+  return durably
+}
+
+const durablyPromise = initDurably()
+
 function App() {
   return (
-     new SQLocalKysely('app.sqlite3').dialect}
-      options={{ pollingInterval: 100 }}
-      autoStart={true}
-      autoMigrate={true}
-    >
+    Loading...
    }>
+      
+        
+      
+    
+  )
+}
+
+// Or use the fallback prop
+function AppAlt() {
+  return (
+    Loading...
    }>
       
     
   )
@@ -45,11 +63,10 @@ function App() {
 
 **Props:**
 
-- `dialectFactory: () => Dialect` - Factory for Kysely dialect
-- `options?: DurablyOptions` - Durably configuration
+- `durably: Durably | Promise` - Durably instance or Promise
 - `autoStart?: boolean` - Auto-start worker (default: true)
-- `autoMigrate?: boolean` - Auto-run migrations (default: true)
 - `onReady?: (durably: Durably) => void` - Callback when ready
+- `fallback?: ReactNode` - Fallback to show while Promise resolves
 
 ### useDurably
 
@@ -101,9 +118,14 @@ function Component() {
     isPending,
     isCompleted,
     isFailed,
+    isCancelled,
     currentRunId,
     reset,
-  } = useJob(myJob, { initialRunId: undefined })
+  } = useJob(myJob, {
+    initialRunId: undefined,
+    autoResume: true, // Auto-resume pending/running jobs (default: true)
+    followLatest: true, // Switch to tracking new runs (default: true)
+  })
 
   // Trigger job
   const handleClick = async () => {
@@ -136,6 +158,16 @@ function Component() {
 }
 ```
 
+**Options:**
+
+```ts
+interface UseJobOptions {
+  initialRunId?: string // Initial Run ID to subscribe to
+  autoResume?: boolean // Auto-resume pending/running jobs (default: true)
+  followLatest?: boolean // Switch to tracking new runs (default: true)
+}
+```
+
 **Return type:**
 
 ```ts
@@ -143,7 +175,7 @@ interface UseJobResult {
   isReady: boolean
   trigger: (input: TInput) => Promise<{ runId: string }>
   triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }>
-  status: 'pending' | 'running' | 'completed' | 'failed' | null
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | null
   output: TOutput | null
   error: string | null
   logs: LogEntry[]
@@ -152,6 +184,7 @@ interface UseJobResult {
   isPending: boolean
   isCompleted: boolean
   isFailed: boolean
+  isCancelled: boolean
   currentRunId: string | null
   reset: () => void
 }
@@ -202,6 +235,7 @@ interface UseJobRunResult {
   isPending: boolean
   isCompleted: boolean
   isFailed: boolean
+  isCancelled: boolean
 }
 ```
 
@@ -254,6 +288,65 @@ interface LogEntry {
 }
 ```
 
+### useRuns
+
+List runs with pagination and real-time updates:
+
+```tsx
+import { useRuns } from '@coji/durably-react'
+
+function Dashboard() {
+  const {
+    isReady,
+    runs,
+    page,
+    hasMore,
+    isLoading,
+    nextPage,
+    prevPage,
+    goToPage,
+    refresh,
+  } = useRuns({
+    jobName: 'my-job', // Optional: filter by job
+    status: 'running', // Optional: filter by status
+    pageSize: 20, // Optional: items per page (default: 10)
+    realtime: true, // Optional: subscribe to updates (default: true)
+  })
+
+  return (
+    
    
+      {runs.map((run) => (
+        
    
+          {run.jobName}: {run.status}
+        
    
+      ))}
+      
+      
+    
    
+  )
+}
+```
+
+**Return type:**
+
+```ts
+interface UseRunsResult {
+  isReady: boolean
+  runs: Run[]
+  page: number
+  hasMore: boolean
+  isLoading: boolean
+  nextPage: () => void
+  prevPage: () => void
+  goToPage: (page: number) => void
+  refresh: () => Promise
+}
+```
+
 ## Server-Connected Mode
 
 Import hooks from `@coji/durably-react/client` for server-connected mode.
@@ -335,26 +428,28 @@ function Component({ runId }: { runId: string }) {
 
 ### Server Handler Setup
 
-On your server, use `createDurablyHandler` from `@coji/durably`:
+On your server, use `createDurablyHandler` from `@coji/durably/server`:
 
 ```ts
-import { createDurably, createDurablyHandler, defineJob } from '@coji/durably'
+import { createDurably, defineJob } from '@coji/durably'
+import { createDurablyHandler } from '@coji/durably/server'
 import { LibsqlDialect } from '@libsql/kysely-libsql'
 import { createClient } from '@libsql/client'
+import { z } from 'zod'
 
 const client = createClient({ url: 'file:local.db' })
 const dialect = new LibsqlDialect({ client })
 
 const durably = createDurably({ dialect })
-const handler = createDurablyHandler(durably)
 
-// Register jobs
+// Define and register jobs
 const syncJob = defineJob({
   name: 'sync-data',
   input: z.object({ userId: z.string() }),
   output: z.object({ count: z.number() }),
   run: async (step, payload) => {
     // Job logic
+    return { count: 42 }
   },
 })
 durably.register({ syncJob })
@@ -362,6 +457,9 @@ durably.register({ syncJob })
 await durably.migrate()
 durably.start()
 
+// Create handler
+const handler = createDurablyHandler(durably)
+
 // Express/Hono/etc route handlers
 app.post('/api/durably/trigger', async (req) => {
   return handler.trigger(req)
@@ -370,12 +468,152 @@ app.post('/api/durably/trigger', async (req) => {
 app.get('/api/durably/subscribe', (req) => {
   return handler.subscribe(req)
 })
+
+app.post('/api/durably/cancel', async (req) => {
+  return handler.cancel(req)
+})
+
+app.get('/api/durably/runs', async (req) => {
+  return handler.getRuns(req)
+})
+
+app.get('/api/durably/runs/:runId', async (req) => {
+  return handler.getRun(req)
+})
+```
+
+### Client useRuns
+
+List runs with pagination:
+
+```tsx
+import { useRuns } from '@coji/durably-react/client'
+
+function Dashboard() {
+  const {
+    runs,
+    page,
+    hasMore,
+    isLoading,
+    nextPage,
+    prevPage,
+    goToPage,
+    refresh,
+  } = useRuns({
+    api: '/api/durably',
+    jobName: 'sync-data', // Optional: filter by job
+    status: 'running', // Optional: filter by status
+    pageSize: 20, // Optional: items per page
+  })
+
+  return (
+    
    
+      {runs.map((run) => (
+        
    
+          {run.jobName}: {run.status}
+        
    
+      ))}
+    
    
+  )
+}
+```
+
+### Client useRunActions
+
+Get run details with steps and actions:
+
+```tsx
+import { useRunActions } from '@coji/durably-react/client'
+
+function RunDetail({ runId }: { runId: string }) {
+  const { run, steps, isLoading, cancel, retry, deleteRun } = useRunActions({
+    api: '/api/durably',
+    runId,
+  })
+
+  if (!run) return 
    Loading...
    
+
+  return (
+    
    
+      
    Run: {run.id}
    
+      
    Status: {run.status}
    
+      
    Steps:
    
+      
      
+        {steps.map((step) => (
+          
    • 
+            {step.name}: {step.status}
+          
      • 
+        ))}
+      
    
+      {run.status === 'running' && }
+      {run.status === 'failed' && }
+      
+    
    
+  )
+}
+```
+
+### Type-Safe Client Factories
+
+#### createJobHooks
+
+Create type-safe hooks for a single job:
+
+```tsx
+import type { importCsvJob } from '~/lib/durably.server'
+import { createJobHooks } from '@coji/durably-react/client'
+
+const importCsv = createJobHooks({
+  api: '/api/durably',
+  jobName: 'import-csv',
+})
+
+function CsvImporter() {
+  const { trigger, output, progress, isRunning } = importCsv.useJob()
+
+  return (
+    
+  )
+}
+```
+
+#### createDurablyClient
+
+Create a type-safe client for all registered jobs:
+
+```tsx
+// Server: register jobs (app/lib/durably.server.ts)
+export const jobs = durably.register({
+  importCsv: importCsvJob,
+  syncUsers: syncUsersJob,
+})
+
+// Client: create typed client (app/lib/durably.client.ts)
+import type { jobs } from '~/lib/durably.server'
+import { createDurablyClient } from '@coji/durably-react/client'
+
+export const durably = createDurablyClient({
+  api: '/api/durably',
+})
+
+// In your component - fully type-safe with autocomplete
+function CsvImporter() {
+  const { trigger, output, isRunning } = durably.importCsv.useJob()
+
+  return (
+    
+  )
+}
 ```
 
 ## Type Definitions
 
 ```ts
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed'
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
 
 interface Progress {
   current: number
diff --git a/packages/durably/README.md b/packages/durably/README.md
index d9fba2ba..0562b33b 100644
--- a/packages/durably/README.md
+++ b/packages/durably/README.md
@@ -18,8 +18,9 @@ See the [Getting Started Guide](https://coji.github.io/durably/guide/getting-sta
 
 ```ts
 import { createDurably, defineJob } from '@coji/durably'
+import { z } from 'zod'
 
-const job = defineJob({
+const myJob = defineJob({
   name: 'my-job',
   input: z.object({ id: z.string() }),
   run: async (step, payload) => {
@@ -30,11 +31,11 @@ const job = defineJob({
 })
 
 const durably = createDurably({ dialect })
-const { myJob } = durably.register({ myJob: job })
+const jobs = durably.register({ myJob })
 
 await durably.migrate()
 durably.start()
-await myJob.trigger({ id: '123' })
+await jobs.myJob.trigger({ id: '123' })
 ```
 
 ## Documentation
diff --git a/packages/durably/docs/llms.md b/packages/durably/docs/llms.md
index fa6684e0..ed4310e8 100644
--- a/packages/durably/docs/llms.md
+++ b/packages/durably/docs/llms.md
@@ -186,19 +186,23 @@ await durably.deleteRun(runId)
 Subscribe to job execution events:
 
 ```ts
+// Run lifecycle events
+durably.on('run:trigger', (e) => console.log('Triggered:', e.runId))
 durably.on('run:start', (e) => console.log('Started:', e.runId))
 durably.on('run:complete', (e) => console.log('Done:', e.output))
 durably.on('run:fail', (e) => console.error('Failed:', e.error))
+durably.on('run:cancel', (e) => console.log('Cancelled:', e.runId))
+durably.on('run:retry', (e) => console.log('Retried:', e.runId))
 durably.on('run:progress', (e) =>
   console.log('Progress:', e.progress.current, '/', e.progress.total),
 )
 
+// Step events
 durably.on('step:start', (e) => console.log('Step:', e.stepName))
 durably.on('step:complete', (e) => console.log('Step done:', e.stepName))
-durably.on('step:skip', (e) =>
-  console.log('Step skipped (cached):', e.stepName),
-)
+durably.on('step:fail', (e) => console.error('Step failed:', e.stepName))
 
+// Log events
 durably.on('log:write', (e) => console.log(`[${e.level}]`, e.message))
 ```
 
@@ -252,31 +256,44 @@ while (true) {
 Create HTTP handlers for client/server architecture using Web Standard Request/Response:
 
 ```ts
-import { createDurablyHandler } from '@coji/durably'
+import { createDurablyHandler } from '@coji/durably/server'
 
 const handler = createDurablyHandler(durably)
 
-// Trigger endpoint (POST)
-// Request body: { jobName, input, idempotencyKey?, concurrencyKey? }
-// Response: { runId }
-app.post('/api/durably/trigger', async (req) => {
-  return await handler.trigger(req)
+// Use the unified handle() method with automatic routing
+app.all('/api/durably/*', async (req) => {
+  return await handler.handle(req, '/api/durably')
 })
 
-// Subscribe endpoint (GET with SSE)
-// Query param: runId
-// Response: Server-Sent Events stream
-app.get('/api/durably/subscribe', (req) => {
-  return handler.subscribe(req)
-})
+// Or use individual endpoints
+app.post('/api/durably/trigger', (req) => handler.trigger(req))
+app.get('/api/durably/subscribe', (req) => handler.subscribe(req))
+app.get('/api/durably/runs', (req) => handler.runs(req))
+app.get('/api/durably/run', (req) => handler.run(req))
+app.get('/api/durably/steps', (req) => handler.steps(req))
+app.get('/api/durably/runs/subscribe', (req) => handler.runsSubscribe(req))
+app.post('/api/durably/retry', (req) => handler.retry(req))
+app.post('/api/durably/cancel', (req) => handler.cancel(req))
+app.delete('/api/durably/run', (req) => handler.delete(req))
 ```
 
 **Handler Interface:**
 
 ```ts
 interface DurablyHandler {
-  trigger(request: Request): Promise
-  subscribe(request: Request): Response
+  // Unified routing handler
+  handle(request: Request, basePath: string): Promise
+
+  // Individual endpoints
+  trigger(request: Request): Promise // POST /trigger
+  subscribe(request: Request): Response // GET /subscribe?runId=xxx (SSE)
+  runs(request: Request): Promise // GET /runs
+  run(request: Request): Promise // GET /run?runId=xxx
+  steps(request: Request): Promise // GET /steps?runId=xxx
+  runsSubscribe(request: Request): Response // GET /runs/subscribe (SSE)
+  retry(request: Request): Promise // POST /retry?runId=xxx
+  cancel(request: Request): Promise // POST /cancel?runId=xxx
+  delete(request: Request): Promise // DELETE /run?runId=xxx
 }
 
 interface TriggerRequest {
diff --git a/website/api/create-durably.md b/website/api/create-durably.md
index fc3effc9..9b5b649d 100644
--- a/website/api/create-durably.md
+++ b/website/api/create-durably.md
@@ -57,12 +57,24 @@ Stops the worker gracefully, waiting for the current job to complete.
 ### `register()`
 
 ```ts
-durably.register(
-  jobDef: JobDefinition
-): JobHandle
+durably.register>(
+  jobs: TJobs
+): { [K in keyof TJobs]: JobHandle }
 ```
 
-Registers a job definition and returns a job handle. See [defineJob](/api/define-job) for details.
+Registers one or more job definitions and returns an object of job handles. Also populates `durably.jobs` with the same handles for type-safe access.
+
+```ts
+const { syncUsers, processImage } = durably.register({
+  syncUsers: syncUsersJob,
+  processImage: processImageJob,
+})
+
+// Or access via durably.jobs
+await durably.jobs.syncUsers.trigger({ orgId: '123' })
+```
+
+See [defineJob](/api/define-job) for details.
 
 ### `on()`
 
@@ -81,7 +93,62 @@ Subscribes to an event. Returns an unsubscribe function. See [Events](/api/event
 await durably.retry(runId: string): Promise
 ```
 
-Retries a failed run by resetting its status to pending.
+Retries a failed or cancelled run by resetting its status to pending.
+
+### `cancel()`
+
+```ts
+await durably.cancel(runId: string): Promise
+```
+
+Cancels a pending or running run.
+
+### `deleteRun()`
+
+```ts
+await durably.deleteRun(runId: string): Promise
+```
+
+Deletes a run and its associated steps and logs.
+
+### `getRun()`
+
+```ts
+await durably.getRun(runId: string): Promise
+```
+
+Gets a single run by ID.
+
+### `getRuns()`
+
+```ts
+await durably.getRuns(filter?: RunFilter): Promise
+
+interface RunFilter {
+  jobName?: string
+  status?: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+  limit?: number
+  offset?: number
+}
+```
+
+Gets runs with optional filtering and pagination.
+
+### `getJob()`
+
+```ts
+durably.getJob(name: string): JobHandle | undefined
+```
+
+Gets a registered job by name.
+
+### `subscribe()`
+
+```ts
+durably.subscribe(runId: string): ReadableStream
+```
+
+Subscribes to events for a specific run as a ReadableStream. The stream automatically closes when the run completes or fails.
 
 ## Example
 
@@ -105,16 +172,20 @@ durably.start()
 
 // Define and register jobs
 import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const myJobDef = defineJob({
+  name: 'my-job',
+  input: z.object({ id: z.string() }),
+  run: async (step, payload) => {
+    // ...
+  },
+})
+
+const { myJob } = durably.register({ myJob: myJobDef })
 
-const myJob = durably.register(
-  defineJob({
-    name: 'my-job',
-    input: z.object({ id: z.string() }),
-    run: async (step, payload) => {
-      // ...
-    },
-  }),
-)
+// Or trigger via durably.jobs
+await durably.jobs.myJob.trigger({ id: '123' })
 
 // Clean shutdown
 process.on('SIGTERM', async () => {
diff --git a/website/api/durably-react.md b/website/api/durably-react.md
index 7eb6fd56..2f3b30bf 100644
--- a/website/api/durably-react.md
+++ b/website/api/durably-react.md
@@ -22,16 +22,23 @@ Wraps your app and initializes Durably.
 
 ```tsx
 import { DurablyProvider } from '@coji/durably-react'
+import { createDurably, defineJob } from '@coji/durably'
 import { SQLocalKysely } from 'sqlocal/kysely'
 
+// Create Durably instance
+async function createBrowserDurably() {
+  const { dialect } = new SQLocalKysely('app.sqlite3')
+  const durably = createDurably({ dialect, pollingInterval: 100 })
+  durably.register({ myJob: myJobDef })
+  await durably.migrate()
+  return durably
+}
+
+const durablyPromise = createBrowserDurably()
+
 function App() {
   return (
-     new SQLocalKysely('app.sqlite3').dialect}
-      options={{ pollingInterval: 100 }}
-      autoStart={true}
-      autoMigrate={true}
-    >
+    Loading...
    }>
       
         
   )
@@ -42,11 +49,10 @@ function App() {
 
 | Prop | Type | Default | Description |
 |------|------|---------|-------------|
-| `dialectFactory` | `() => Dialect` | required | Factory for Kysely dialect |
-| `options` | `DurablyOptions` | - | Durably configuration |
-| `autoStart` | `boolean` | `true` | Auto-start worker |
-| `autoMigrate` | `boolean` | `true` | Auto-run migrations |
+| `durably` | `Durably \| Promise` | required | Durably instance or Promise |
+| `autoStart` | `boolean` | `true` | Auto-start worker on mount |
 | `onReady` | `(durably: Durably) => void` | - | Callback when ready |
+| `fallback` | `ReactNode` | - | Loading fallback (wraps in Suspense) |
 
 ### useDurably
 
@@ -282,12 +288,14 @@ function Component({ runId }: { runId: string }) {
 
 ### Server Setup
 
-On your server, use `createDurablyHandler` from `@coji/durably`:
+On your server, use `createDurablyHandler` from `@coji/durably/server`:
 
 ```ts
-import { createDurably, createDurablyHandler, defineJob } from '@coji/durably'
+import { createDurably, defineJob } from '@coji/durably'
+import { createDurablyHandler } from '@coji/durably/server'
 import { LibsqlDialect } from '@libsql/kysely-libsql'
 import { createClient } from '@libsql/client'
+import { z } from 'zod'
 
 const client = createClient({ url: 'file:local.db' })
 const dialect = new LibsqlDialect({ client })
@@ -295,34 +303,119 @@ const dialect = new LibsqlDialect({ client })
 const durably = createDurably({ dialect })
 const handler = createDurablyHandler(durably)
 
-// Register jobs
-const syncJob = defineJob({
+// Define and register jobs
+const syncJobDef = defineJob({
   name: 'sync-data',
   input: z.object({ userId: z.string() }),
   output: z.object({ count: z.number() }),
   run: async (step, payload) => {
     // Job logic
+    return { count: 0 }
   },
 })
-durably.register({ syncJob })
+
+export const jobs = durably.register({ syncData: syncJobDef })
 
 await durably.migrate()
 durably.start()
 
-// Route handlers (Express/Hono/etc)
-app.post('/api/durably/trigger', async (req) => {
-  return handler.trigger(req)
+// Use the unified handle() method (recommended)
+app.all('/api/durably/*', async (req) => {
+  return handler.handle(req, '/api/durably')
 })
 
-app.get('/api/durably/subscribe', (req) => {
-  return handler.subscribe(req)
+// Or use individual route handlers
+app.post('/api/durably/trigger', (req) => handler.trigger(req))
+app.get('/api/durably/subscribe', (req) => handler.subscribe(req))
+app.get('/api/durably/runs', (req) => handler.runs(req))
+app.get('/api/durably/runs/subscribe', (req) => handler.runsSubscribe(req))
+```
+
+### createDurablyClient
+
+Create a type-safe client for all registered jobs:
+
+```ts
+// durably.client.ts
+import { createDurablyClient } from '@coji/durably-react/client'
+import type { jobs } from './durably.server'
+
+export const durably = createDurablyClient({
+  api: '/api/durably',
 })
+
+// Usage in components
+function Component() {
+  const { trigger, status, output } = durably.syncData.useJob()
+  // trigger() is type-safe!
+}
+```
+
+### useRuns
+
+List and paginate job runs with real-time updates:
+
+```tsx
+import { useRuns } from '@coji/durably-react/client'
+
+function Dashboard() {
+  const {
+    runs,
+    isLoading,
+    error,
+    page,
+    hasMore,
+    nextPage,
+    prevPage,
+    refresh,
+  } = useRuns({
+    api: '/api/durably',
+    jobName: 'sync-data', // optional filter
+    pageSize: 10,
+    realtime: true, // auto-refresh on SSE events
+  })
+
+  return (
+    
      
+      {runs.map((run) => (
+        
    • {run.status}
      • 
+      ))}
+    
    
+  )
+}
+```
+
+### useRunActions
+
+Perform actions on runs:
+
+```tsx
+import { useRunActions } from '@coji/durably-react/client'
+
+function RunActions({ runId }: { runId: string }) {
+  const {
+    cancel,
+    retry,
+    deleteRun,
+    getRun,
+    getSteps,
+    isLoading,
+  } = useRunActions({ api: '/api/durably' })
+
+  return (
+    
    
+      
+      
+      
+    
    
+  )
+}
 ```
 
 ## Type Definitions
 
 ```ts
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed'
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
 
 interface Progress {
   current: number
@@ -339,4 +432,25 @@ interface LogEntry {
   data: unknown
   timestamp: string
 }
+
+interface RunRecord {
+  id: string
+  jobName: string
+  status: RunStatus
+  payload: unknown
+  output: unknown
+  error: string | null
+  progress: Progress | null
+  createdAt: string
+  updatedAt: string
+}
+
+interface StepRecord {
+  name: string
+  status: 'completed' | 'failed'
+  output: unknown
+  error: string | null
+  startedAt: string
+  completedAt: string | null
+}
 ```
diff --git a/website/api/events.md b/website/api/events.md
index 8f9ab5fb..eb121a0b 100644
--- a/website/api/events.md
+++ b/website/api/events.md
@@ -12,6 +12,23 @@ durably.on(eventType: string, listener: (event) => void): void
 
 ### Run Events
 
+#### `run:trigger`
+
+Fired when a job is triggered (before worker picks it up).
+
+```ts
+durably.on('run:trigger', (event) => {
+  // event: {
+  //   type: 'run:trigger',
+  //   runId: string,
+  //   jobName: string,
+  //   payload: unknown,
+  //   timestamp: string,
+  //   sequence: number
+  // }
+})
+```
+
 #### `run:start`
 
 Fired when a run begins execution.
@@ -82,6 +99,38 @@ durably.on('run:progress', (event) => {
 })
 ```
 
+#### `run:cancel`
+
+Fired when a run is cancelled via `cancel()` API.
+
+```ts
+durably.on('run:cancel', (event) => {
+  // event: {
+  //   type: 'run:cancel',
+  //   runId: string,
+  //   jobName: string,
+  //   timestamp: string,
+  //   sequence: number
+  // }
+})
+```
+
+#### `run:retry`
+
+Fired when a failed or cancelled run is retried via `retry()` API.
+
+```ts
+durably.on('run:retry', (event) => {
+  // event: {
+  //   type: 'run:retry',
+  //   runId: string,
+  //   jobName: string,
+  //   timestamp: string,
+  //   sequence: number
+  // }
+})
+```
+
 ### Step Events
 
 #### `step:start`
@@ -203,9 +252,12 @@ interface BaseEvent {
 }
 
 type DurablyEvent =
+  | RunTriggerEvent
   | RunStartEvent
   | RunCompleteEvent
   | RunFailEvent
+  | RunCancelEvent
+  | RunRetryEvent
   | RunProgressEvent
   | StepStartEvent
   | StepCompleteEvent
diff --git a/website/guide/browser-only.md b/website/guide/browser-only.md
index e3ee6d61..a54bc8a1 100644
--- a/website/guide/browser-only.md
+++ b/website/guide/browser-only.md
@@ -59,12 +59,12 @@ export default defineConfig({
 
 ```tsx
 import { DurablyProvider, useJob } from '@coji/durably-react'
-import { defineJob } from '@coji/durably'
+import { createDurably, defineJob } from '@coji/durably'
 import { SQLocalKysely } from 'sqlocal/kysely'
 import { z } from 'zod'
 
 // Define job outside component
-const syncJob = defineJob({
+const syncJobDef = defineJob({
   name: 'sync-data',
   input: z.object({ userId: z.string() }),
   output: z.object({ count: z.number() }),
@@ -75,9 +75,21 @@ const syncJob = defineJob({
   },
 })
 
+// Create and configure Durably instance
+async function createBrowserDurably() {
+  const { dialect } = new SQLocalKysely('app.sqlite3')
+  const durably = createDurably({ dialect })
+  durably.register({ syncData: syncJobDef })
+  await durably.migrate()
+  return durably
+}
+
+// Create a promise that resolves to the durably instance
+const durablyPromise = createBrowserDurably()
+
 function SyncButton() {
   const { trigger, status, output, error, progress, isRunning, isCompleted } =
-    useJob(syncJob)
+    useJob(syncJobDef)
 
   return (
     
    
@@ -102,9 +114,7 @@ function SyncButton() {
 
 function App() {
   return (
-     new SQLocalKysely('app.sqlite3').dialect}
-    >
+    Loading...
    }>
       
         
   )
diff --git a/website/guide/full-stack.md b/website/guide/full-stack.md
index e3c501e6..0edba11c 100644
--- a/website/guide/full-stack.md
+++ b/website/guide/full-stack.md
@@ -44,7 +44,8 @@ app/
 
 ```ts
 // app/lib/durably.server.ts
-import { createDurably, createDurablyHandler, defineJob } from '@coji/durably'
+import { createDurably, defineJob } from '@coji/durably'
+import { createDurablyHandler } from '@coji/durably/server'
 import { LibsqlDialect } from '@libsql/kysely-libsql'
 import { createClient } from '@libsql/client'
 import { z } from 'zod'
@@ -73,7 +74,7 @@ const importCsvJob = defineJob({
           skipped++
         }
       })
-      step.setProgress({ current: i + 1, total: payload.rows.length })
+      step.progress(i + 1, payload.rows.length)
     }
 
     return { imported, skipped }

From f12918e9554830b407258545b8307627e8a2b7a1 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 21:04:06 +0900
Subject: [PATCH 081/101] docs(durably-react): fix useRunActions example in
 llms.md
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update example to show imperative API (getRun, getSteps functions)
instead of reactive values (run, steps properties).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/docs/llms.md | 48 +++++++++++++++++------------
 1 file changed, 28 insertions(+), 20 deletions(-)

diff --git a/packages/durably-react/docs/llms.md b/packages/durably-react/docs/llms.md
index bce4f7ad..f6ccbb7b 100644
--- a/packages/durably-react/docs/llms.md
+++ b/packages/durably-react/docs/llms.md
@@ -520,34 +520,42 @@ function Dashboard() {
 
 ### Client useRunActions
 
-Get run details with steps and actions:
+Imperative actions for runs (retry, cancel, delete, get):
 
 ```tsx
 import { useRunActions } from '@coji/durably-react/client'
 
-function RunDetail({ runId }: { runId: string }) {
-  const { run, steps, isLoading, cancel, retry, deleteRun } = useRunActions({
-    api: '/api/durably',
-    runId,
-  })
+function RunActions({ runId, status }: { runId: string; status: string }) {
+  const { retry, cancel, deleteRun, getRun, getSteps, isLoading, error } =
+    useRunActions({
+      api: '/api/durably',
+    })
 
-  if (!run) return 
    Loading...
    
+  const handleViewDetails = async () => {
+    const run = await getRun(runId)
+    const steps = await getSteps(runId)
+    console.log('Run:', run, 'Steps:', steps)
+  }
 
   return (
     
    
-      
    Run: {run.id}
    
-      
    Status: {run.status}
    
-      
    Steps:
    
-      
      
-        {steps.map((step) => (
-          
    • 
-            {step.name}: {step.status}
-          
      • 
-        ))}
-      
    
-      {run.status === 'running' && }
-      {run.status === 'failed' && }
-      
+      {(status === 'failed' || status === 'cancelled') && (
+        
+      )}
+      {(status === 'pending' || status === 'running') && (
+        
+      )}
+      
+      
+      {error && {error}}
     
    
   )
 }

From c31418d1b977d6af116aa95c4af6cf9cba62afd5 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 21:09:21 +0900
Subject: [PATCH 082/101] fix(durably-react): move setState out of render phase
 in client useJob
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move setIsPending(false) from render phase into useEffect to follow
React best practices and avoid potential infinite re-render loops.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/client/use-job.ts | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/packages/durably-react/src/client/use-job.ts b/packages/durably-react/src/client/use-job.ts
index 228e9f3d..bb460df5 100644
--- a/packages/durably-react/src/client/use-job.ts
+++ b/packages/durably-react/src/client/use-job.ts
@@ -1,4 +1,4 @@
-import { useCallback, useState } from 'react'
+import { useCallback, useEffect, useState } from 'react'
 import type { LogEntry, Progress, RunStatus } from '../types'
 import { useSSESubscription } from './use-sse-subscription'
 
@@ -151,9 +151,11 @@ export function useJob<
   const effectiveStatus = subscription.status ?? (isPending ? 'pending' : null)
 
   // Clear pending when we get a real status
-  if (subscription.status && isPending) {
-    setIsPending(false)
-  }
+  useEffect(() => {
+    if (subscription.status && isPending) {
+      setIsPending(false)
+    }
+  }, [subscription.status, isPending])
 
   return {
     isReady: true,

From b8836003e9f9ff841490c09bd36ab93bcdb27e46 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 21:13:27 +0900
Subject: [PATCH 083/101] fix(durably-react): guard against non-JSON error
 responses in useRunActions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Wrap response.json() in try-catch for all methods (retry, cancel,
deleteRun, getRun, getSteps) to gracefully handle servers that return
non-JSON error responses. Falls back to statusText when JSON parsing fails.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../src/client/use-run-actions.ts             | 70 +++++++++++++------
 .../tests/client/use-run-actions.test.tsx     | 58 +++++++++++++++
 2 files changed, 108 insertions(+), 20 deletions(-)

diff --git a/packages/durably-react/src/client/use-run-actions.ts b/packages/durably-react/src/client/use-run-actions.ts
index 42b79b10..26403d4c 100644
--- a/packages/durably-react/src/client/use-run-actions.ts
+++ b/packages/durably-react/src/client/use-run-actions.ts
@@ -109,10 +109,16 @@ export function useRunActions(
         const response = await fetch(url, { method: 'POST' })
 
         if (!response.ok) {
-          const data = await response.json()
-          throw new Error(
-            data.error || `Failed to retry: ${response.statusText}`,
-          )
+          let errorMessage = `Failed to retry: ${response.statusText}`
+          try {
+            const data = await response.json()
+            if (data.error) {
+              errorMessage = data.error
+            }
+          } catch {
+            // Response is not JSON, use statusText
+          }
+          throw new Error(errorMessage)
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : 'Unknown error'
@@ -135,10 +141,16 @@ export function useRunActions(
         const response = await fetch(url, { method: 'POST' })
 
         if (!response.ok) {
-          const data = await response.json()
-          throw new Error(
-            data.error || `Failed to cancel: ${response.statusText}`,
-          )
+          let errorMessage = `Failed to cancel: ${response.statusText}`
+          try {
+            const data = await response.json()
+            if (data.error) {
+              errorMessage = data.error
+            }
+          } catch {
+            // Response is not JSON, use statusText
+          }
+          throw new Error(errorMessage)
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : 'Unknown error'
@@ -161,10 +173,16 @@ export function useRunActions(
         const response = await fetch(url, { method: 'DELETE' })
 
         if (!response.ok) {
-          const data = await response.json()
-          throw new Error(
-            data.error || `Failed to delete: ${response.statusText}`,
-          )
+          let errorMessage = `Failed to delete: ${response.statusText}`
+          try {
+            const data = await response.json()
+            if (data.error) {
+              errorMessage = data.error
+            }
+          } catch {
+            // Response is not JSON, use statusText
+          }
+          throw new Error(errorMessage)
         }
       } catch (err) {
         const message = err instanceof Error ? err.message : 'Unknown error'
@@ -191,10 +209,16 @@ export function useRunActions(
         }
 
         if (!response.ok) {
-          const data = await response.json()
-          throw new Error(
-            data.error || `Failed to get run: ${response.statusText}`,
-          )
+          let errorMessage = `Failed to get run: ${response.statusText}`
+          try {
+            const data = await response.json()
+            if (data.error) {
+              errorMessage = data.error
+            }
+          } catch {
+            // Response is not JSON, use statusText
+          }
+          throw new Error(errorMessage)
         }
 
         return (await response.json()) as RunRecord
@@ -219,10 +243,16 @@ export function useRunActions(
         const response = await fetch(url)
 
         if (!response.ok) {
-          const data = await response.json()
-          throw new Error(
-            data.error || `Failed to get steps: ${response.statusText}`,
-          )
+          let errorMessage = `Failed to get steps: ${response.statusText}`
+          try {
+            const data = await response.json()
+            if (data.error) {
+              errorMessage = data.error
+            }
+          } catch {
+            // Response is not JSON, use statusText
+          }
+          throw new Error(errorMessage)
         }
 
         return (await response.json()) as StepRecord[]
diff --git a/packages/durably-react/tests/client/use-run-actions.test.tsx b/packages/durably-react/tests/client/use-run-actions.test.tsx
index 18827835..9bd05ef2 100644
--- a/packages/durably-react/tests/client/use-run-actions.test.tsx
+++ b/packages/durably-react/tests/client/use-run-actions.test.tsx
@@ -152,6 +152,35 @@ describe('useRunActions (client)', () => {
       )
     })
 
+    it('handles non-JSON error response', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Internal Server Error',
+        json: () => Promise.reject(new Error('Invalid JSON')),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let thrownError: Error | undefined
+      await act(async () => {
+        try {
+          await result.current.retry('run-123')
+        } catch (err) {
+          thrownError = err as Error
+        }
+      })
+
+      expect(thrownError?.message).toBe(
+        'Failed to retry: Internal Server Error',
+      )
+      expect(result.current.error).toBe(
+        'Failed to retry: Internal Server Error',
+      )
+    })
+
     it('clears error on new request', async () => {
       const fetchMock = vi
         .fn()
@@ -321,6 +350,35 @@ describe('useRunActions (client)', () => {
         'Failed to cancel: Internal Server Error',
       )
     })
+
+    it('handles non-JSON error response', async () => {
+      const fetchMock = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Internal Server Error',
+        json: () => Promise.reject(new Error('Invalid JSON')),
+      })
+      globalThis.fetch = fetchMock
+
+      const { result } = renderHook(() =>
+        useRunActions({ api: '/api/durably' }),
+      )
+
+      let thrownError: Error | undefined
+      await act(async () => {
+        try {
+          await result.current.cancel('run-456')
+        } catch (err) {
+          thrownError = err as Error
+        }
+      })
+
+      expect(thrownError?.message).toBe(
+        'Failed to cancel: Internal Server Error',
+      )
+      expect(result.current.error).toBe(
+        'Failed to cancel: Internal Server Error',
+      )
+    })
   })
 
   describe('shared state', () => {

From 42959ef73994371a99cd399f02770fa786b28735 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 21:26:43 +0900
Subject: [PATCH 084/101] fix(durably-react): handle cancelled status in
 triggerAndWait
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add cancelled status handling to triggerAndWait in both client and
browser modes. Previously, if a job was cancelled while waiting, the
Promise would never resolve. Now it properly rejects with 'Job cancelled'.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/client/use-job.ts  |  3 ++
 packages/durably-react/src/hooks/use-job.ts   |  2 +
 .../tests/browser/use-job.test.tsx            | 39 +++++++++++++++++++
 .../tests/client/use-job.test.tsx             |  2 +-
 4 files changed, 45 insertions(+), 1 deletion(-)

diff --git a/packages/durably-react/src/client/use-job.ts b/packages/durably-react/src/client/use-job.ts
index bb460df5..49d49b3d 100644
--- a/packages/durably-react/src/client/use-job.ts
+++ b/packages/durably-react/src/client/use-job.ts
@@ -134,6 +134,9 @@ export function useJob<
           } else if (subscription.status === 'failed') {
             clearInterval(checkInterval)
             reject(new Error(subscription.error ?? 'Job failed'))
+          } else if (subscription.status === 'cancelled') {
+            clearInterval(checkInterval)
+            reject(new Error('Job cancelled'))
           }
         }, 50)
       })
diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts
index e4249270..174bc115 100644
--- a/packages/durably-react/src/hooks/use-job.ts
+++ b/packages/durably-react/src/hooks/use-job.ts
@@ -317,6 +317,8 @@ export function useJob<
             resolve({ runId: run.id, output: updatedRun.output as TOutput })
           } else if (updatedRun.status === 'failed') {
             reject(new Error(updatedRun.error ?? 'Job failed'))
+          } else if (updatedRun.status === 'cancelled') {
+            reject(new Error('Job cancelled'))
           } else {
             // Still running, check again
             setTimeout(checkCompletion, 50)
diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx
index 7ff97884..ba1e1bee 100644
--- a/packages/durably-react/tests/browser/use-job.test.tsx
+++ b/packages/durably-react/tests/browser/use-job.test.tsx
@@ -54,6 +54,18 @@ const loggingJob = defineJob({
   },
 })
 
+const longRunningJob = defineJob({
+  name: 'long-running-job',
+  input: z.object({ input: z.string() }),
+  run: async (context) => {
+    // Simulate a long-running job by waiting
+    await context.run('wait', async () => {
+      await new Promise((resolve) => setTimeout(resolve, 5000))
+    })
+    return { done: true }
+  },
+})
+
 describe('useJob', () => {
   // Track all instances created during tests for cleanup
   const instances: Durably[] = []
@@ -414,4 +426,31 @@ describe('useJob', () => {
       expect(result.current.output).toEqual({ id: 1 })
     })
   })
+
+  it('triggerAndWait rejects on cancelled', async () => {
+    const durably = await createTestDurably({ pollingInterval: 50 })
+    instances.push(durably)
+
+    const { result } = renderHook(() => useJob(longRunningJob), {
+      wrapper: createWrapper(durably),
+    })
+
+    await waitFor(() => expect(result.current.isReady).toBe(true))
+
+    // Start the long-running job and get the promise
+    const waitPromise = result.current.triggerAndWait({ input: 'test' })
+
+    // Wait for the job to start running
+    await waitFor(() => {
+      expect(result.current.currentRunId).not.toBeNull()
+      expect(result.current.status).toBe('running')
+    })
+
+    // Cancel the job
+    const runId = result.current.currentRunId!
+    await durably.cancel(runId)
+
+    // The promise should reject with 'Job cancelled'
+    await expect(waitPromise).rejects.toThrow('Job cancelled')
+  })
 })
diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx
index 8813ea8a..3f4d05d0 100644
--- a/packages/durably-react/tests/client/use-job.test.tsx
+++ b/packages/durably-react/tests/client/use-job.test.tsx
@@ -333,7 +333,7 @@ describe('useJob (client)', () => {
 
   // Note: triggerAndWait tests are difficult to test with the polling-based implementation
   // because the hook needs to re-render to see the updated subscription.status.
-  // The triggerAndWait function is covered indirectly through the browser tests.
+  // The triggerAndWait function is covered by the browser tests which use real React re-renders.
 
   describe('initialRunId', () => {
     it('sets currentRunId from initialRunId', () => {

From 9c061320b700ce29d30ad8a5f79b28e5cdfcc4cb Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 21:29:25 +0900
Subject: [PATCH 085/101] fix(durably-react): track effectiveStatus for
 callbacks in client useJobRun
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change prevStatusRef to track effectiveStatus instead of subscription.status
to prevent onStart callback from firing twice when transitioning from
null to pending to running. The previous implementation could fire onStart
once for the initial pending state and again when SSE sent run:start.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../durably-react/src/client/use-job-run.ts   |  8 +-
 .../tests/client/use-job-run.test.tsx         | 94 +++++++++++++++++++
 2 files changed, 98 insertions(+), 4 deletions(-)

diff --git a/packages/durably-react/src/client/use-job-run.ts b/packages/durably-react/src/client/use-job-run.ts
index ac0ea6c6..415c3e6f 100644
--- a/packages/durably-react/src/client/use-job-run.ts
+++ b/packages/durably-react/src/client/use-job-run.ts
@@ -92,15 +92,15 @@ export function useJobRun(
   const isRunning = effectiveStatus === 'running'
   const isCancelled = effectiveStatus === 'cancelled'
 
-  // Track previous status to detect transitions
+  // Track previous status to detect transitions (use effectiveStatus, not subscription.status)
   const prevStatusRef = useRef(null)
 
   useEffect(() => {
     const prevStatus = prevStatusRef.current
-    prevStatusRef.current = subscription.status
+    prevStatusRef.current = effectiveStatus
 
     // Only fire callbacks on status transitions
-    if (prevStatus !== subscription.status) {
+    if (prevStatus !== effectiveStatus) {
       // Fire onStart when transitioning from null to pending/running
       if (prevStatus === null && (isPending || isRunning) && onStart) {
         onStart()
@@ -113,7 +113,7 @@ export function useJobRun(
       }
     }
   }, [
-    subscription.status,
+    effectiveStatus,
     isPending,
     isRunning,
     isCompleted,
diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx
index c2cc1fcb..4ddd585d 100644
--- a/packages/durably-react/tests/client/use-job-run.test.tsx
+++ b/packages/durably-react/tests/client/use-job-run.test.tsx
@@ -260,4 +260,98 @@ describe('useJobRun (client)', () => {
     await new Promise((r) => setTimeout(r, 50))
     expect(result.current.status).toBe('pending')
   })
+
+  describe('callbacks', () => {
+    it('fires onStart only once when transitioning from null to pending to running', async () => {
+      const onStart = vi.fn()
+
+      const { result } = renderHook(() =>
+        useJobRun({ api: '/api/durably', runId: 'callback-run', onStart }),
+      )
+
+      // Initially pending (runId exists but no SSE events yet)
+      await waitFor(() => {
+        expect(result.current.status).toBe('pending')
+      })
+
+      // onStart should have been called once for pending status
+      expect(onStart).toHaveBeenCalledTimes(1)
+
+      await waitFor(() => {
+        expect(mockEventSource.instances.length).toBeGreaterThan(0)
+      })
+
+      // Emit run:start to transition to running
+      act(() => {
+        mockEventSource.emit({ type: 'run:start', runId: 'callback-run' })
+      })
+
+      await waitFor(() => {
+        expect(result.current.status).toBe('running')
+      })
+
+      // onStart should NOT have been called again - still just once
+      expect(onStart).toHaveBeenCalledTimes(1)
+    })
+
+    it('fires onComplete when run completes', async () => {
+      const onComplete = vi.fn()
+
+      const { result } = renderHook(() =>
+        useJobRun({
+          api: '/api/durably',
+          runId: 'complete-callback-run',
+          onComplete,
+        }),
+      )
+
+      await waitFor(() => {
+        expect(mockEventSource.instances.length).toBeGreaterThan(0)
+      })
+
+      act(() => {
+        mockEventSource.emit({
+          type: 'run:complete',
+          runId: 'complete-callback-run',
+          output: { done: true },
+        })
+      })
+
+      await waitFor(() => {
+        expect(result.current.isCompleted).toBe(true)
+      })
+
+      expect(onComplete).toHaveBeenCalledTimes(1)
+    })
+
+    it('fires onFail when run fails', async () => {
+      const onFail = vi.fn()
+
+      const { result } = renderHook(() =>
+        useJobRun({
+          api: '/api/durably',
+          runId: 'fail-callback-run',
+          onFail,
+        }),
+      )
+
+      await waitFor(() => {
+        expect(mockEventSource.instances.length).toBeGreaterThan(0)
+      })
+
+      act(() => {
+        mockEventSource.emit({
+          type: 'run:fail',
+          runId: 'fail-callback-run',
+          error: 'Test error',
+        })
+      })
+
+      await waitFor(() => {
+        expect(result.current.isFailed).toBe(true)
+      })
+
+      expect(onFail).toHaveBeenCalledTimes(1)
+    })
+  })
 })

From 4486a12a9d258dd0423da12c12999256a010e613 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 21:32:27 +0900
Subject: [PATCH 086/101] fix(durably): add cancel handler for ReadableStream
 cleanup in subscribe
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Move closed flag and cleanup function to outer scope so they are
accessible from both start and cancel handlers. When the stream is
cancelled by the consumer, event listeners are now properly cleaned up
to prevent memory leaks.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../tests/browser/use-job.test.tsx            |  1 +
 packages/durably/src/durably.ts               | 18 +++++++---
 .../tests/node/core-extensions.test.ts        | 36 +++++++++++++++++++
 3 files changed, 51 insertions(+), 4 deletions(-)

diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx
index ba1e1bee..a9c1df79 100644
--- a/packages/durably-react/tests/browser/use-job.test.tsx
+++ b/packages/durably-react/tests/browser/use-job.test.tsx
@@ -57,6 +57,7 @@ const loggingJob = defineJob({
 const longRunningJob = defineJob({
   name: 'long-running-job',
   input: z.object({ input: z.string() }),
+  output: z.object({ done: z.boolean() }),
   run: async (context) => {
     // Simulate a long-running job by waiting
     await context.run('wait', async () => {
diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts
index 7fdf7c14..2496750e 100644
--- a/packages/durably/src/durably.ts
+++ b/packages/durably/src/durably.ts
@@ -269,10 +269,12 @@ function createDurablyInstance<
     },
 
     subscribe(runId: string): ReadableStream {
+      // Track closed state and cleanup function in outer scope for cancel handler
+      let closed = false
+      let cleanup: (() => void) | null = null
+
       return new ReadableStream({
         start: (controller) => {
-          let closed = false
-
           const unsubscribeStart = eventEmitter.on('run:start', (event) => {
             if (!closed && event.runId === runId) {
               controller.enqueue(event)
@@ -285,7 +287,7 @@ function createDurablyInstance<
               if (!closed && event.runId === runId) {
                 controller.enqueue(event)
                 closed = true
-                cleanup()
+                cleanup?.()
                 controller.close()
               }
             },
@@ -350,7 +352,8 @@ function createDurablyInstance<
             }
           })
 
-          const cleanup = () => {
+          // Assign cleanup function to outer scope for cancel handler
+          cleanup = () => {
             unsubscribeStart()
             unsubscribeComplete()
             unsubscribeFail()
@@ -363,6 +366,13 @@ function createDurablyInstance<
             unsubscribeLog()
           }
         },
+        cancel: () => {
+          // Clean up event listeners when stream is cancelled by consumer
+          if (!closed) {
+            closed = true
+            cleanup?.()
+          }
+        },
       })
     },
 
diff --git a/packages/durably/tests/node/core-extensions.test.ts b/packages/durably/tests/node/core-extensions.test.ts
index 92d099d6..ffec88fa 100644
--- a/packages/durably/tests/node/core-extensions.test.ts
+++ b/packages/durably/tests/node/core-extensions.test.ts
@@ -131,6 +131,42 @@ describe('Core Extensions', () => {
       expect(events.some((e) => e.type === 'step:start')).toBe(true)
       expect(events.some((e) => e.type === 'step:complete')).toBe(true)
     })
+
+    it('cleans up event listeners when stream is cancelled', async () => {
+      const longRunningJob = defineJob({
+        name: 'long-running-subscribe',
+        input: z.object({ input: z.string() }),
+        run: async (ctx) => {
+          await ctx.run('wait', async () => {
+            await new Promise((resolve) => setTimeout(resolve, 10000))
+          })
+        },
+      })
+
+      durably.register({ longRunningJob })
+      durably.start()
+
+      const job = durably.getJob('long-running-subscribe')!
+      const run = await job.trigger({ input: 'test' })
+
+      const stream = durably.subscribe(run.id)
+      const reader = stream.getReader()
+
+      // Read one event (run:start)
+      const { value } = await reader.read()
+      expect(value?.type).toBe('run:start')
+
+      // Cancel the stream before the job completes
+      await reader.cancel()
+
+      // The stream should be cancelled and no errors should occur
+      // If event listeners are not cleaned up, this would cause memory leaks
+      // Wait a bit to ensure no errors are thrown after cancellation
+      await new Promise((resolve) => setTimeout(resolve, 100))
+
+      // Cancel the run to clean up
+      await durably.cancel(run.id)
+    })
   })
 
   describe('createDurablyHandler', () => {

From d6b133f48ca8238b366a4dfda75ff9a574973263 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 22:16:40 +0900
Subject: [PATCH 087/101] feat(durably): add stepCount to Run type for step
 progress tracking
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add stepCount property to Run interface computed via LEFT JOIN query
- Update getRun, getRuns, getNextPendingRun to include step count
- Add currentStepIndex and stepCount to ClientRun and RunRecord types
- Add Step column to dashboard UI in all examples
- Separate step (resumable checkpoints) from progress (UI feedback)
- Add stepCount tests to storage.shared.ts
- Synchronize job definitions across examples (import-csv, data-sync, process-image)
- Unify dashboard table format across all examples

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 CHANGELOG.md                                  |  20 +-
 .../app/jobs/import-csv.ts                    |  92 ++++++++
 .../app/jobs/index.ts                         |   1 +
 .../app/routes/_index/dashboard.tsx           |  38 ++-
 .../src/components/dashboard.tsx              |  38 ++-
 .../app/jobs/data-sync.ts                     |  56 +++++
 .../app/jobs/import-csv.ts                    |  62 +++--
 .../fullstack-react-router/app/jobs/index.ts  |   2 +
 .../app/jobs/process-image.ts                 |  48 ++++
 .../app/routes/_index/dashboard.tsx           | 219 +++++++++++-------
 .../src/client/use-run-actions.ts             |   2 +
 packages/durably-react/src/client/use-runs.ts |   2 +
 .../tests/client/use-runs.test.tsx            |   2 +
 packages/durably/src/storage.ts               |  49 +++-
 .../durably/tests/shared/storage.shared.ts    |  92 ++++++++
 15 files changed, 584 insertions(+), 139 deletions(-)
 create mode 100644 examples/browser-react-router-spa/app/jobs/import-csv.ts
 create mode 100644 examples/fullstack-react-router/app/jobs/data-sync.ts
 create mode 100644 examples/fullstack-react-router/app/jobs/process-image.ts

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 522c1390..31cd96c0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,10 +17,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 #### @coji/durably
 
-- **New events for run lifecycle**:
-  - `run:trigger`: Emitted when a job is triggered (before worker picks it up)
-  - `run:cancel`: Emitted when a run is cancelled via `cancel()` API
-  - `run:retry`: Emitted when a failed/cancelled run is retried via `retry()` API
 - **Type-safe `durably.jobs` property**: Access registered jobs with full type inference
   ```ts
   const durably = createDurably({ dialect })
@@ -28,6 +24,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   await durably.jobs.processImage.trigger({ imageId: '123' }) // Type-safe
   ```
 - **Retry from cancelled state**: `retry()` now works on both `failed` and `cancelled` runs
+- **New events for run lifecycle**:
+  - `run:trigger`: Emitted when a job is triggered (before worker picks it up)
+  - `run:cancel`: Emitted when a run is cancelled via `cancel()` API
+  - `run:retry`: Emitted when a failed/cancelled run is retried via `retry()` API
+- **`stepCount` added to `Run` type**: Run now includes `stepCount` property reflecting the number of completed steps
+  - Computed dynamically via JOIN query (no schema change required)
+  - Available in `getRun()`, `getRuns()`, `getNextPendingRun()`
 
 #### @coji/durably/server
 
@@ -38,15 +41,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 #### @coji/durably-react
 
-- `useRuns`: List and paginate job runs with filtering and real-time updates
+- **`useRuns`**: List and paginate job runs with filtering and real-time updates
   - Supports filtering by `jobName` and `status`
   - Built-in pagination with `nextPage`, `prevPage`, `goToPage`
   - Real-time updates via `realtime` option (default: true)
-- `useJob` options:
+- **`useJob` options**:
   - `autoResume`: Automatically resume tracking pending/running jobs on mount (default: true)
   - `followLatest`: Automatically switch to tracking the latest running job (default: true)
-- `createDurablyClient`: Type-safe client factory for server-connected mode
-- `createJobHooks`: Per-job hook factory for server-connected mode
+- **`createDurablyClient`**: Type-safe client factory for server-connected mode
+- **`createJobHooks`**: Per-job hook factory for server-connected mode
 
 #### @coji/durably-react/client
 
@@ -54,6 +57,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   - `deleteRun(runId)`: Delete a completed/failed/cancelled run
   - `getRun(runId)`: Get a single run by ID
   - `getSteps(runId)`: Get steps for a run
+- **`stepCount` and `currentStepIndex`**: Added to `ClientRun` and `RunRecord` types for step progress display
 - **New type exports**: `RunRecord`, `StepRecord` for type-safe run and step data
 
 ### Changed
diff --git a/examples/browser-react-router-spa/app/jobs/import-csv.ts b/examples/browser-react-router-spa/app/jobs/import-csv.ts
new file mode 100644
index 00000000..b2ce147b
--- /dev/null
+++ b/examples/browser-react-router-spa/app/jobs/import-csv.ts
@@ -0,0 +1,92 @@
+/**
+ * CSV Import Job
+ *
+ * Demonstrates separation of steps (resumable units) and progress (UI feedback).
+ * - Steps: validate, import, finalize (3 resumable checkpoints)
+ * - Progress: fine-grained row-level feedback within each step
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+const csvRowSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string(),
+  amount: z.number(),
+})
+
+/** Output schema for type inference */
+const outputSchema = z.object({ imported: z.number(), failed: z.number() })
+
+/** Output type for use in components */
+export type ImportCsvOutput = z.infer
+
+export const importCsvJob = defineJob({
+  name: 'import-csv',
+  input: z.object({
+    filename: z.string(),
+    rows: z.array(csvRowSchema),
+  }),
+  output: outputSchema,
+  run: async (step, payload) => {
+    step.log.info(
+      `Starting import of ${payload.filename} (${payload.rows.length} rows)`,
+    )
+
+    // Step 1: Validate all rows
+    const validRows = await step.run('validate', async () => {
+      const valid: typeof payload.rows = []
+      const invalid: { row: (typeof payload.rows)[0]; reason: string }[] = []
+
+      for (let i = 0; i < payload.rows.length; i++) {
+        const row = payload.rows[i]
+        step.progress(i + 1, payload.rows.length, `Validating ${row.name}...`)
+        await delay(50)
+
+        if (row.amount < 0) {
+          invalid.push({ row, reason: `Invalid amount: ${row.amount}` })
+          step.log.warn(`Validation failed for ${row.name}: negative amount`)
+        } else {
+          valid.push(row)
+        }
+      }
+
+      step.log.info(
+        `Validation complete: ${valid.length} valid, ${invalid.length} invalid`,
+      )
+      return { valid, invalidCount: invalid.length }
+    })
+
+    // Step 2: Import valid rows
+    const importResult = await step.run('import', async () => {
+      let imported = 0
+
+      for (let i = 0; i < validRows.valid.length; i++) {
+        const row = validRows.valid[i]
+        step.progress(i + 1, validRows.valid.length, `Importing ${row.name}...`)
+        await delay(80)
+
+        // Simulate import
+        imported++
+        step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`)
+      }
+
+      return { imported }
+    })
+
+    // Step 3: Finalize
+    await step.run('finalize', async () => {
+      step.progress(1, 1, 'Finalizing...')
+      await delay(200)
+      step.log.info('Import finalized')
+    })
+
+    return {
+      imported: importResult.imported,
+      failed: validRows.invalidCount,
+    }
+  },
+})
diff --git a/examples/browser-react-router-spa/app/jobs/index.ts b/examples/browser-react-router-spa/app/jobs/index.ts
index 404d49a4..e87adee6 100644
--- a/examples/browser-react-router-spa/app/jobs/index.ts
+++ b/examples/browser-react-router-spa/app/jobs/index.ts
@@ -6,4 +6,5 @@
  */
 
 export { dataSyncJob } from './data-sync'
+export { importCsvJob, type ImportCsvOutput } from './import-csv'
 export { processImageJob } from './process-image'
diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
index b1305c1d..653cf1ea 100644
--- a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -11,9 +11,10 @@ import { useState } from 'react'
 
 export function Dashboard() {
   const { durably } = useDurably()
-  const { runs, page, hasMore, refresh, nextPage, prevPage } = useRuns({
-    pageSize: 6,
-  })
+  const { runs, page, hasMore, isLoading, refresh, nextPage, prevPage } =
+    useRuns({
+      pageSize: 6,
+    })
 
   const [selectedRun, setSelectedRun] = useState(null)
   const [steps, setSteps] = useState<
@@ -65,13 +66,18 @@ export function Dashboard() {
     
    
       
    
         
    Run History
    
-        
+        
    
+          {isLoading && (
+            Refreshing...
+          )}
+          
+        
    
       
    
 
       {runs.length === 0 ? (
@@ -91,6 +97,9 @@ export function Dashboard() {
                   
                     Status
                   
+                  
+                    Step
+                  
                   
                     Progress
                   
@@ -116,6 +125,15 @@ export function Dashboard() {
                         {run.status}
                       
                     
+                    
+                      {run.stepCount > 0 ? (
+                        
+                          {run.currentStepIndex}/{run.stepCount}
+                        
+                      ) : (
+                        -
+                      )}
+                    
                     
                       {run.progress ? (
                         
    
diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
index b1305c1d..653cf1ea 100644
--- a/examples/browser-vite-react/src/components/dashboard.tsx
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -11,9 +11,10 @@ import { useState } from 'react'
 
 export function Dashboard() {
   const { durably } = useDurably()
-  const { runs, page, hasMore, refresh, nextPage, prevPage } = useRuns({
-    pageSize: 6,
-  })
+  const { runs, page, hasMore, isLoading, refresh, nextPage, prevPage } =
+    useRuns({
+      pageSize: 6,
+    })
 
   const [selectedRun, setSelectedRun] = useState(null)
   const [steps, setSteps] = useState<
@@ -65,13 +66,18 @@ export function Dashboard() {
     
    
       
    
         
    Run History
    
-        
+        
    
+          {isLoading && (
+            Refreshing...
+          )}
+          
+        
    
       
    
 
       {runs.length === 0 ? (
@@ -91,6 +97,9 @@ export function Dashboard() {
                   
                     Status
                   
+                  
+                    Step
+                  
                   
                     Progress
                   
@@ -116,6 +125,15 @@ export function Dashboard() {
                         {run.status}
                       
                     
+                    
+                      {run.stepCount > 0 ? (
+                        
+                          {run.currentStepIndex}/{run.stepCount}
+                        
+                      ) : (
+                        -
+                      )}
+                    
                     
                       {run.progress ? (
                         
    
diff --git a/examples/fullstack-react-router/app/jobs/data-sync.ts b/examples/fullstack-react-router/app/jobs/data-sync.ts
new file mode 100644
index 00000000..1a3e9ebc
--- /dev/null
+++ b/examples/fullstack-react-router/app/jobs/data-sync.ts
@@ -0,0 +1,56 @@
+/**
+ * Data Sync Job
+ *
+ * Simulates syncing data with a remote server.
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const dataSyncJob = defineJob({
+  name: 'data-sync',
+  input: z.object({ userId: z.string() }),
+  output: z.object({ synced: z.number(), failed: z.number() }),
+  run: async (step, payload) => {
+    step.log.info(`Starting sync for user: ${payload.userId}`)
+
+    const items = await step.run('fetch-local', async () => {
+      step.progress(1, 4, 'Fetching local data...')
+      await delay(300)
+      return Array.from({ length: 10 }, (_, i) => ({
+        id: `item-${i}`,
+        data: `Data for ${payload.userId}`,
+      }))
+    })
+
+    let synced = 0
+    let failed = 0
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]
+      const success = await step.run(`sync-item-${item.id}`, async () => {
+        step.progress(2 + Math.floor(i / 5), 4, `Syncing item ${i + 1}...`)
+        await delay(100)
+        return Math.random() > 0.1 // 90% success rate
+      })
+
+      if (success) {
+        synced++
+      } else {
+        failed++
+        step.log.warn(`Failed to sync item: ${item.id}`)
+      }
+    }
+
+    await step.run('finalize', async () => {
+      step.progress(4, 4, 'Finalizing...')
+      await delay(200)
+    })
+
+    step.log.info(`Sync complete: ${synced} synced, ${failed} failed`)
+
+    return { synced, failed }
+  },
+})
diff --git a/examples/fullstack-react-router/app/jobs/import-csv.ts b/examples/fullstack-react-router/app/jobs/import-csv.ts
index 855e3232..b2ce147b 100644
--- a/examples/fullstack-react-router/app/jobs/import-csv.ts
+++ b/examples/fullstack-react-router/app/jobs/import-csv.ts
@@ -1,12 +1,16 @@
 /**
  * CSV Import Job
  *
- * Processes CSV rows with progress reporting.
+ * Demonstrates separation of steps (resumable units) and progress (UI feedback).
+ * - Steps: validate, import, finalize (3 resumable checkpoints)
+ * - Progress: fine-grained row-level feedback within each step
  */
 
 import { defineJob } from '@coji/durably'
 import { z } from 'zod'
 
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
 const csvRowSchema = z.object({
   id: z.number(),
   name: z.string(),
@@ -32,31 +36,57 @@ export const importCsvJob = defineJob({
       `Starting import of ${payload.filename} (${payload.rows.length} rows)`,
     )
 
-    let imported = 0
+    // Step 1: Validate all rows
+    const validRows = await step.run('validate', async () => {
+      const valid: typeof payload.rows = []
+      const invalid: { row: (typeof payload.rows)[0]; reason: string }[] = []
 
-    for (let i = 0; i < payload.rows.length; i++) {
-      const row = payload.rows[i]
-      const result = await step.run(`row-${i}`, async () => {
-        // Simulate processing with validation
-        await new Promise((r) => setTimeout(r, 100))
+      for (let i = 0; i < payload.rows.length; i++) {
+        const row = payload.rows[i]
+        step.progress(i + 1, payload.rows.length, `Validating ${row.name}...`)
+        await delay(50)
 
-        // Simulate occasional failures (negative amounts)
         if (row.amount < 0) {
-          throw new Error(`Invalid amount for ${row.name}: ${row.amount}`)
+          invalid.push({ row, reason: `Invalid amount: ${row.amount}` })
+          step.log.warn(`Validation failed for ${row.name}: negative amount`)
+        } else {
+          valid.push(row)
         }
+      }
+
+      step.log.info(
+        `Validation complete: ${valid.length} valid, ${invalid.length} invalid`,
+      )
+      return { valid, invalidCount: invalid.length }
+    })
+
+    // Step 2: Import valid rows
+    const importResult = await step.run('import', async () => {
+      let imported = 0
 
-        return { processed: true, id: row.id }
-      })
+      for (let i = 0; i < validRows.valid.length; i++) {
+        const row = validRows.valid[i]
+        step.progress(i + 1, validRows.valid.length, `Importing ${row.name}...`)
+        await delay(80)
 
-      if (result.processed) {
+        // Simulate import
         imported++
         step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`)
       }
 
-      step.progress(i + 1, payload.rows.length, `Processing ${row.name}`)
-    }
+      return { imported }
+    })
+
+    // Step 3: Finalize
+    await step.run('finalize', async () => {
+      step.progress(1, 1, 'Finalizing...')
+      await delay(200)
+      step.log.info('Import finalized')
+    })
 
-    step.log.info(`Import completed: ${imported} rows`)
-    return { imported, failed: 0 }
+    return {
+      imported: importResult.imported,
+      failed: validRows.invalidCount,
+    }
   },
 })
diff --git a/examples/fullstack-react-router/app/jobs/index.ts b/examples/fullstack-react-router/app/jobs/index.ts
index dbc665ba..e87adee6 100644
--- a/examples/fullstack-react-router/app/jobs/index.ts
+++ b/examples/fullstack-react-router/app/jobs/index.ts
@@ -5,4 +5,6 @@
  * When adding a new job, import and add it here.
  */
 
+export { dataSyncJob } from './data-sync'
 export { importCsvJob, type ImportCsvOutput } from './import-csv'
+export { processImageJob } from './process-image'
diff --git a/examples/fullstack-react-router/app/jobs/process-image.ts b/examples/fullstack-react-router/app/jobs/process-image.ts
new file mode 100644
index 00000000..aa8197eb
--- /dev/null
+++ b/examples/fullstack-react-router/app/jobs/process-image.ts
@@ -0,0 +1,48 @@
+/**
+ * Process Image Job
+ *
+ * Simulates image processing with multiple steps.
+ */
+
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const processImageJob = defineJob({
+  name: 'process-image',
+  input: z.object({ filename: z.string(), width: z.number() }),
+  output: z.object({ url: z.string(), size: z.number() }),
+  run: async (step, payload) => {
+    step.log.info(`Starting image processing: ${payload.filename}`)
+
+    // Download original image
+    const fileSize = await step.run('download', async () => {
+      step.progress(1, 3, 'Downloading...')
+      await delay(500)
+      return Math.floor(Math.random() * 1000000) + 500000 // 500KB-1.5MB
+    })
+
+    step.log.info(`Downloaded: ${fileSize} bytes`)
+
+    // Resize to target width
+    const resizedSize = await step.run('resize', async () => {
+      step.progress(2, 3, 'Resizing...')
+      await delay(600)
+      return Math.floor(fileSize * (payload.width / 1920))
+    })
+
+    step.log.info(`Resized to: ${resizedSize} bytes`)
+
+    // Upload to CDN
+    const url = await step.run('upload', async () => {
+      step.progress(3, 3, 'Uploading...')
+      await delay(400)
+      return `https://cdn.example.com/${payload.width}/${payload.filename}`
+    })
+
+    step.log.info(`Uploaded to: ${url}`)
+
+    return { url, size: resizedSize }
+  },
+})
diff --git a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
index c8b0e6f0..8729e1bf 100644
--- a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
@@ -13,7 +13,6 @@ export function Dashboard() {
   const { runs, isLoading, error, page, hasMore, nextPage, prevPage, refresh } =
     useRuns({
       api: '/api/durably',
-      jobName: 'import-csv',
       pageSize: 6,
     })
 
@@ -67,97 +66,151 @@ export function Dashboard() {
   }
 
   return (
-    
    
+    
    
       
    
-        
    Dashboard
    
-        {isLoading && (
-          Refreshing...
-        )}
+        
    Run History
    
+        
    
+          {isLoading && (
+            Refreshing...
+          )}
+          
+        
    
       
    
 
       {error && 
    Error: {error}
    }
 
       {runs.length === 0 ? (
-        
    No runs yet
    
+        
    No runs yet
    
       ) : (
         <>
-          
      
-            {runs.map((r) => (
-              
    • 
-                
      
-                  
      
-                    
-                      {r.id.slice(0, 8)}
-                    
-                    -
-                    
-                      {new Date(r.createdAt).toLocaleString()}
-                    
-                  
      
-                  {r.progress && (
-                    
      
-                      
      
-                        
      
-                      
      
-                      
-                        {r.progress.current}
-                        {r.progress.total && `/${r.progress.total}`}
+          
      
+            
+              
+                
+                  
+                  
+                  
+                  
+                  
+                  
+                  
+                
+              
+              
+                {runs.map((run) => (
+                  
+                    
+                    
+                    
+                    
+                    
+                    
+                    
+                  
+                ))}
+              
+            
      
+                    ID
+                  
+                    Job
+                  
+                    Status
+                  
+                    Step
+                  
+                    Progress
+                  
+                    Created
+                  
+                    Actions
+                  
      
+                      {run.id.slice(0, 8)}...
+                    {run.jobName}
+                      
+                        {run.status}
                       
-                    
-                  )}
-                
-                
      
-                  
-                  {(r.status === 'pending' || r.status === 'running') && (
-                    
-                  )}
-                  {(r.status === 'failed' || r.status === 'cancelled') && (
-                    
-                  )}
-                  {r.status !== 'running' && r.status !== 'pending' && (
-                    
-                  )}
-                  
-                    {r.status}
-                  
-                
      
-              
-            ))}
-          
+                          		
+                      {run.stepCount > 0 ? (
+                        
+                          {run.currentStepIndex}/{run.stepCount}
+                        
+                      ) : (
+                        -
+                      )}
+                    
+                      {run.progress ? (
+                        
      
+                          
      
+                            
      
+                          
      
+                          
+                            {run.progress.current}
+                            {run.progress.total && `/${run.progress.total}`}
+                          
+                        
      
+                      ) : (
+                        -
+                      )}
+                    
      		
+                      {formatDate(run.createdAt)}
+                    
+                      
      
+                        
+                        {(run.status === 'failed' ||
+                          run.status === 'cancelled') && (
+                          
+                        )}
+                        {(run.status === 'running' ||
+                          run.status === 'pending') && (
+                          
+                        )}
+                        {run.status !== 'running' &&
+                          run.status !== 'pending' && (
+                            
+                          )}
+                      
      
+                    
      
+          
      
 
           {/* Pagination */}
           
      
diff --git a/packages/durably-react/src/client/use-run-actions.ts b/packages/durably-react/src/client/use-run-actions.ts
index 26403d4c..0a26b473 100644
--- a/packages/durably-react/src/client/use-run-actions.ts
+++ b/packages/durably-react/src/client/use-run-actions.ts
@@ -11,6 +11,8 @@ export interface RunRecord {
   output: unknown | null
   error: string | null
   progress: { current: number; total?: number; message?: string } | null
+  currentStepIndex: number
+  stepCount: number
   createdAt: string
   startedAt: string | null
   completedAt: string | null
diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts
index 3503204b..adf7e5ea 100644
--- a/packages/durably-react/src/client/use-runs.ts
+++ b/packages/durably-react/src/client/use-runs.ts
@@ -11,6 +11,8 @@ export interface ClientRun {
   input: unknown
   output: unknown | null
   error: string | null
+  currentStepIndex: number
+  stepCount: number
   progress: Progress | null
   createdAt: string
   startedAt: string | null
diff --git a/packages/durably-react/tests/client/use-runs.test.tsx b/packages/durably-react/tests/client/use-runs.test.tsx
index 005479db..4ab5b9e9 100644
--- a/packages/durably-react/tests/client/use-runs.test.tsx
+++ b/packages/durably-react/tests/client/use-runs.test.tsx
@@ -19,6 +19,8 @@ const createMockRun = (overrides: Partial = {}): ClientRun => ({
   input: { value: 1 },
   output: null,
   error: null,
+  currentStepIndex: 0,
+  stepCount: 0,
   progress: null,
   createdAt: '2024-01-01T00:00:00.000Z',
   startedAt: null,
diff --git a/packages/durably/src/storage.ts b/packages/durably/src/storage.ts
index 33f4ee53..95b5ee5d 100644
--- a/packages/durably/src/storage.ts
+++ b/packages/durably/src/storage.ts
@@ -23,6 +23,7 @@ export interface Run {
   idempotencyKey: string | null
   concurrencyKey: string | null
   currentStepIndex: number
+  stepCount: number
   progress: { current: number; total?: number; message?: string } | null
   output: unknown | null
   error: string | null
@@ -133,7 +134,9 @@ export interface Storage {
 /**
  * Convert database row to Run object
  */
-function rowToRun(row: Database['durably_runs']): Run {
+function rowToRun(
+  row: Database['durably_runs'] & { step_count?: number | bigint | null },
+): Run {
   return {
     id: row.id,
     jobName: row.job_name,
@@ -142,6 +145,7 @@ function rowToRun(row: Database['durably_runs']): Run {
     idempotencyKey: row.idempotency_key,
     concurrencyKey: row.concurrency_key,
     currentStepIndex: row.current_step_index,
+    stepCount: Number(row.step_count ?? 0),
     progress: row.progress ? JSON.parse(row.progress) : null,
     output: row.output ? JSON.parse(row.output) : null,
     error: row.error,
@@ -316,24 +320,36 @@ export function createKyselyStorage(db: Kysely): Storage {
     async getRun(runId: string): Promise {
       const row = await db
         .selectFrom('durably_runs')
-        .selectAll()
-        .where('id', '=', runId)
+        .leftJoin('durably_steps', 'durably_runs.id', 'durably_steps.run_id')
+        .selectAll('durably_runs')
+        .select((eb) =>
+          eb.fn.count('durably_steps.id').as('step_count'),
+        )
+        .where('durably_runs.id', '=', runId)
+        .groupBy('durably_runs.id')
         .executeTakeFirst()
 
       return row ? rowToRun(row) : null
     },
 
     async getRuns(filter?: RunFilter): Promise {
-      let query = db.selectFrom('durably_runs').selectAll()
+      let query = db
+        .selectFrom('durably_runs')
+        .leftJoin('durably_steps', 'durably_runs.id', 'durably_steps.run_id')
+        .selectAll('durably_runs')
+        .select((eb) =>
+          eb.fn.count('durably_steps.id').as('step_count'),
+        )
+        .groupBy('durably_runs.id')
 
       if (filter?.status) {
-        query = query.where('status', '=', filter.status)
+        query = query.where('durably_runs.status', '=', filter.status)
       }
       if (filter?.jobName) {
-        query = query.where('job_name', '=', filter.jobName)
+        query = query.where('durably_runs.job_name', '=', filter.jobName)
       }
 
-      query = query.orderBy('created_at', 'desc')
+      query = query.orderBy('durably_runs.created_at', 'desc')
 
       if (filter?.limit !== undefined) {
         query = query.limit(filter.limit)
@@ -355,16 +371,25 @@ export function createKyselyStorage(db: Kysely): Storage {
     ): Promise {
       let query = db
         .selectFrom('durably_runs')
-        .selectAll()
-        .where('status', '=', 'pending')
-        .orderBy('created_at', 'asc')
+        .leftJoin('durably_steps', 'durably_runs.id', 'durably_steps.run_id')
+        .selectAll('durably_runs')
+        .select((eb) =>
+          eb.fn.count('durably_steps.id').as('step_count'),
+        )
+        .where('durably_runs.status', '=', 'pending')
+        .groupBy('durably_runs.id')
+        .orderBy('durably_runs.created_at', 'asc')
         .limit(1)
 
       if (excludeConcurrencyKeys.length > 0) {
         query = query.where((eb) =>
           eb.or([
-            eb('concurrency_key', 'is', null),
-            eb('concurrency_key', 'not in', excludeConcurrencyKeys),
+            eb('durably_runs.concurrency_key', 'is', null),
+            eb(
+              'durably_runs.concurrency_key',
+              'not in',
+              excludeConcurrencyKeys,
+            ),
           ]),
         )
       }
diff --git a/packages/durably/tests/shared/storage.shared.ts b/packages/durably/tests/shared/storage.shared.ts
index 812038da..fcf47c89 100644
--- a/packages/durably/tests/shared/storage.shared.ts
+++ b/packages/durably/tests/shared/storage.shared.ts
@@ -59,6 +59,98 @@ export function createStorageTests(createDialect: () => Dialect) {
         expect(run!.jobName).toBe('test-job')
       })
 
+      it('returns stepCount as 0 for new run', async () => {
+        const created = await durably.storage.createRun({
+          jobName: 'test-job',
+          payload: {},
+        })
+
+        const run = await durably.storage.getRun(created.id)
+
+        expect(run).not.toBeNull()
+        expect(run!.stepCount).toBe(0)
+      })
+
+      it('returns stepCount reflecting completed steps', async () => {
+        const created = await durably.storage.createRun({
+          jobName: 'test-job',
+          payload: {},
+        })
+
+        // Add 3 steps
+        await durably.storage.createStep({
+          runId: created.id,
+          name: 'step-1',
+          index: 0,
+          status: 'completed',
+          startedAt: new Date().toISOString(),
+        })
+        await durably.storage.createStep({
+          runId: created.id,
+          name: 'step-2',
+          index: 1,
+          status: 'completed',
+          startedAt: new Date().toISOString(),
+        })
+        await durably.storage.createStep({
+          runId: created.id,
+          name: 'step-3',
+          index: 2,
+          status: 'completed',
+          startedAt: new Date().toISOString(),
+        })
+
+        const run = await durably.storage.getRun(created.id)
+
+        expect(run).not.toBeNull()
+        expect(run!.stepCount).toBe(3)
+      })
+
+      it('returns stepCount in getRuns', async () => {
+        const run1 = await durably.storage.createRun({
+          jobName: 'job-a',
+          payload: {},
+        })
+        const run2 = await durably.storage.createRun({
+          jobName: 'job-b',
+          payload: {},
+        })
+
+        // Add 2 steps to run1
+        await durably.storage.createStep({
+          runId: run1.id,
+          name: 'step-1',
+          index: 0,
+          status: 'completed',
+          startedAt: new Date().toISOString(),
+        })
+        await durably.storage.createStep({
+          runId: run1.id,
+          name: 'step-2',
+          index: 1,
+          status: 'completed',
+          startedAt: new Date().toISOString(),
+        })
+
+        // Add 1 step to run2
+        await durably.storage.createStep({
+          runId: run2.id,
+          name: 'step-1',
+          index: 0,
+          status: 'completed',
+          startedAt: new Date().toISOString(),
+        })
+
+        const runs = await durably.storage.getRuns()
+
+        // runs are ordered by created_at desc
+        const foundRun1 = runs.find((r) => r.id === run1.id)
+        const foundRun2 = runs.find((r) => r.id === run2.id)
+
+        expect(foundRun1!.stepCount).toBe(2)
+        expect(foundRun2!.stepCount).toBe(1)
+      })
+
       it('returns null for non-existent run', async () => {
         const run = await durably.storage.getRun('non-existent-id')
         expect(run).toBeNull()

From b5794c0c89a7f96baeef0e235d015542899d86c9 Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 22:37:17 +0900
Subject: [PATCH 088/101] refactor(examples): unify react-router examples UI
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add tabs UI to fullstack-react-router (Image Processing / Data Sync)
- Register all 3 jobs (processImage, dataSync, importCsv) in fullstack
- Create form and progress components for each job type in fullstack
- Unify run-progress.tsx to use props-based pattern
- Add disabled button styles to browser-react-router-spa dashboard
- Use consistent step key (s.name) in both dashboards
- Add footer to fullstack-react-router

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/routes/_index/dashboard.tsx           |   8 +-
 .../app/lib/durably.server.ts                 |   4 +-
 .../app/routes/_index.tsx                     | 173 ++++++++----------
 .../app/routes/_index/data-sync-form.tsx      |  47 +++++
 .../app/routes/_index/data-sync-progress.tsx  |  44 +++++
 .../routes/_index/image-processing-form.tsx   |  64 +++++++
 .../_index/image-processing-progress.tsx      |  44 +++++
 .../app/routes/_index/run-progress.tsx        | 131 +++++++------
 8 files changed, 358 insertions(+), 157 deletions(-)
 create mode 100644 examples/fullstack-react-router/app/routes/_index/data-sync-form.tsx
 create mode 100644 examples/fullstack-react-router/app/routes/_index/data-sync-progress.tsx
 create mode 100644 examples/fullstack-react-router/app/routes/_index/image-processing-form.tsx
 create mode 100644 examples/fullstack-react-router/app/routes/_index/image-processing-progress.tsx

diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
index 653cf1ea..a3791675 100644
--- a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -171,7 +171,7 @@ export function Dashboard() {
                           
@@ -181,7 +181,7 @@ export function Dashboard() {
                           
@@ -191,7 +191,7 @@ export function Dashboard() {
                             
@@ -307,7 +307,7 @@ export function Dashboard() {
                     
        
                       {steps.map((s) => (
                         
      • 
                           {s.name}
diff --git a/examples/fullstack-react-router/app/lib/durably.server.ts b/examples/fullstack-react-router/app/lib/durably.server.ts
index c28e5d33..85392e05 100644
--- a/examples/fullstack-react-router/app/lib/durably.server.ts
+++ b/examples/fullstack-react-router/app/lib/durably.server.ts
@@ -10,13 +10,15 @@
  */
 
 import { createDurably, createDurablyHandler } from '@coji/durably'
-import { importCsvJob } from '~/jobs'
+import { dataSyncJob, importCsvJob, processImageJob } from '~/jobs'
 import { dialect } from './database.server'
 
 // Create Durably instance with registered jobs
 export const durably = createDurably({
   dialect,
 }).register({
+  processImage: processImageJob,
+  dataSync: dataSyncJob,
   importCsv: importCsvJob,
 })
 
diff --git a/examples/fullstack-react-router/app/routes/_index.tsx b/examples/fullstack-react-router/app/routes/_index.tsx
index 32cb5df3..c29c3c44 100644
--- a/examples/fullstack-react-router/app/routes/_index.tsx
+++ b/examples/fullstack-react-router/app/routes/_index.tsx
@@ -1,140 +1,125 @@
 /**
- * Home Page - CSV Import Demo
+ * Full-Stack React Router Example
  *
- * Demonstrates Durably with React Router v7:
- * - action: Trigger job via Form submit
- * - RunProgress: useJobRun for real-time progress via SSE
- * - Dashboard: useRuns with SSE for real-time updates and pagination
+ * This example demonstrates:
+ * - React Router v7 with server-side action
+ * - SSE streaming for real-time progress updates
+ * - action for Form-based job triggering
+ * - useJobRun hook for monitoring jobs via SSE
  */
 
-import { Form, useActionData, useNavigation } from 'react-router'
+import { useState } from 'react'
 import { durably } from '~/lib/durably.server'
 import type { Route } from './+types/_index'
 import { Dashboard } from './_index/dashboard'
-import { RunProgress } from './_index/run-progress'
+import { DataSyncForm } from './_index/data-sync-form'
+import { DataSyncProgress } from './_index/data-sync-progress'
+import { ImageProcessingForm } from './_index/image-processing-form'
+import { ImageProcessingProgress } from './_index/image-processing-progress'
 
 export function meta() {
   return [
-    { title: 'Durably + React Router Example' },
+    { title: 'Durably - Full-Stack React Router' },
     { name: 'description', content: 'Full-stack job processing with SSE' },
   ]
 }
 
-// Generate dummy CSV data
-function generateDummyRows(count: number) {
-  const names = [
-    'Alice',
-    'Bob',
-    'Charlie',
-    'Diana',
-    'Eve',
-    'Frank',
-    'Grace',
-    'Henry',
-  ]
-  const domains = ['example.com', 'test.org', 'demo.net']
-
-  return Array.from({ length: count }, (_, i) => ({
-    id: i + 1,
-    name: names[i % names.length],
-    email: `${names[i % names.length].toLowerCase()}${i}@${
-      domains[i % domains.length]
-    }`,
-    amount: Math.floor(Math.random() * 1000) + 10,
-  }))
-}
-
-// Action: Trigger job
+// Action: Trigger jobs
 export async function action({ request }: Route.ActionArgs) {
   const formData = await request.formData()
-  const filename = formData.get('filename') as string
-  const rowCount = Number(formData.get('rowCount') ?? 10)
+  const intent = formData.get('intent') as string
+
+  if (intent === 'image') {
+    const filename = formData.get('filename') as string
+    const width = Number(formData.get('width'))
+    const run = await durably.jobs.processImage.trigger({ filename, width })
+    return { intent: 'image', runId: run.id }
+  }
 
-  // Generate dummy CSV rows
-  const rows = generateDummyRows(rowCount)
+  if (intent === 'sync') {
+    const userId = formData.get('userId') as string
+    const run = await durably.jobs.dataSync.trigger({ userId })
+    return { intent: 'sync', runId: run.id }
+  }
 
-  const run = await durably.jobs.importCsv.trigger({ filename, rows })
-  return { runId: run.id }
+  return null
 }
 
-export default function Home() {
-  const actionData = useActionData()
-  const navigation = useNavigation()
-  const isSubmitting = navigation.state === 'submitting'
+export default function Index() {
+  const [activeJob, setActiveJob] = useState<'image' | 'sync'>('image')
 
   return (
     
        
       
        
         
        
           
        
-            Durably + React Router
+            Durably - Full-Stack React Router
           
        
           
        
-            Full-stack job processing with Form actions and SSE
+            React Router v7 with server action + SSE streaming
           
        
         
        
 
         
        
-          {/* Left: Trigger Form + Progress */}
+          {/* Left: Job Trigger + Progress */}
           
        
-            {/* Trigger Form */}
+            {/* Job Selection */}
             
        
-              
        Start CSV Import
        
-              
        
-                
        
-                  
-                  
-                
        
-                
        
-                  
-                  
-                
        
+              
        
+                
        Run Job
        
+              
        
+
+              
        
                 
-                {actionData?.runId && (
-                  
        
-                    Triggered:{' '}
-                    {actionData.runId}
-                  
        
-                )}
-              
+                
+              
        
+
+              {activeJob === 'image' ? (
+                
+              ) : (
+                
+              )}
             
        
 
-            {/* Run Progress */}
-            
+            {/* Progress Display */}
+            {activeJob === 'image' ? (
+              
+            ) : (
+              
+            )}
           
        
 
-          {/* Right: Dashboard with Real-time SSE Updates */}
+          {/* Right: Dashboard */}
           
         
        
+
+        
        
+          
        Data is stored on the server using SQLite (Turso/libSQL).
        
+          
        
+            Try reloading the page during job execution - progress updates via
+            SSE!
+          
        
+        
        
       
        
     
        
   )
diff --git a/examples/fullstack-react-router/app/routes/_index/data-sync-form.tsx b/examples/fullstack-react-router/app/routes/_index/data-sync-form.tsx
new file mode 100644
index 00000000..e9f7a8fe
--- /dev/null
+++ b/examples/fullstack-react-router/app/routes/_index/data-sync-form.tsx
@@ -0,0 +1,47 @@
+/**
+ * Data Sync Form Component
+ *
+ * Form for triggering data sync jobs via server action.
+ */
+
+import { Form, useActionData, useNavigation } from 'react-router'
+import type { action } from '../_index'
+
+export function DataSyncForm() {
+  const actionData = useActionData()
+  const navigation = useNavigation()
+  const isSubmitting = navigation.state === 'submitting'
+  const runId = actionData?.intent === 'sync' ? actionData.runId : null
+
+  return (
+    
        
+      
+      
        
+        
+        
+      
        
+      
+      {runId && (
+        
        
+          Triggered: {runId.slice(0, 8)}
+        
        
+      )}
+    
        
+  )
+}
diff --git a/examples/fullstack-react-router/app/routes/_index/data-sync-progress.tsx b/examples/fullstack-react-router/app/routes/_index/data-sync-progress.tsx
new file mode 100644
index 00000000..c698e8c8
--- /dev/null
+++ b/examples/fullstack-react-router/app/routes/_index/data-sync-progress.tsx
@@ -0,0 +1,44 @@
+/**
+ * Data Sync Progress Component
+ *
+ * Displays progress for the data sync job using useJobRun.
+ */
+
+import { useJobRun } from '@coji/durably-react/client'
+import { useActionData } from 'react-router'
+import type { action } from '../_index'
+import { RunProgress } from './run-progress'
+
+export function DataSyncProgress() {
+  const actionData = useActionData()
+  const runId = actionData?.intent === 'sync' ? actionData.runId : null
+
+  const {
+    progress,
+    output,
+    error,
+    logs,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+    isCancelled,
+  } = useJobRun({
+    api: '/api/durably',
+    runId,
+  })
+
+  return (
+    
+  )
+}
diff --git a/examples/fullstack-react-router/app/routes/_index/image-processing-form.tsx b/examples/fullstack-react-router/app/routes/_index/image-processing-form.tsx
new file mode 100644
index 00000000..e3bbe2e6
--- /dev/null
+++ b/examples/fullstack-react-router/app/routes/_index/image-processing-form.tsx
@@ -0,0 +1,64 @@
+/**
+ * Image Processing Form Component
+ *
+ * Form for triggering image processing jobs via server action.
+ */
+
+import { Form, useActionData, useNavigation } from 'react-router'
+import type { action } from '../_index'
+
+export function ImageProcessingForm() {
+  const actionData = useActionData()
+  const navigation = useNavigation()
+  const isSubmitting = navigation.state === 'submitting'
+  const runId = actionData?.intent === 'image' ? actionData.runId : null
+
+  return (
+    
        
+      
+      
        
+        
+        
+      
        
+      
        
+        
+        
+      
        
+      
+      {runId && (
+        
        
+          Triggered: {runId.slice(0, 8)}
+        
        
+      )}
+    
        
+  )
+}
diff --git a/examples/fullstack-react-router/app/routes/_index/image-processing-progress.tsx b/examples/fullstack-react-router/app/routes/_index/image-processing-progress.tsx
new file mode 100644
index 00000000..5d11af4f
--- /dev/null
+++ b/examples/fullstack-react-router/app/routes/_index/image-processing-progress.tsx
@@ -0,0 +1,44 @@
+/**
+ * Image Processing Progress Component
+ *
+ * Displays progress for the image processing job using useJobRun.
+ */
+
+import { useJobRun } from '@coji/durably-react/client'
+import { useActionData } from 'react-router'
+import type { action } from '../_index'
+import { RunProgress } from './run-progress'
+
+export function ImageProcessingProgress() {
+  const actionData = useActionData()
+  const runId = actionData?.intent === 'image' ? actionData.runId : null
+
+  const {
+    progress,
+    output,
+    error,
+    logs,
+    isPending,
+    isRunning,
+    isCompleted,
+    isFailed,
+    isCancelled,
+  } = useJobRun({
+    api: '/api/durably',
+    runId,
+  })
+
+  return (
+    
+  )
+}
diff --git a/examples/fullstack-react-router/app/routes/_index/run-progress.tsx b/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
index 2b04b348..9611fa54 100644
--- a/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/run-progress.tsx
@@ -1,107 +1,122 @@
 /**
  * RunProgress Component
  *
- * Displays real-time progress and result via SSE subscription.
+ * Displays real-time progress and result for jobs.
  */
 
-import { useJobRun } from '@coji/durably-react/client'
-import type { ImportCsvOutput } from '~/jobs'
+import type { LogEntry } from '@coji/durably-react/client'
 
 interface RunProgressProps {
-  runId: string | null
+  progress: { current: number; total?: number; message?: string } | null
+  output: unknown
+  error: string | null
+  logs: LogEntry[]
+  isPending: boolean
+  isRunning: boolean
+  isCompleted: boolean
+  isFailed: boolean
+  isCancelled: boolean
 }
 
-export function RunProgress({ runId }: RunProgressProps) {
-  const run = useJobRun({
-    api: '/api/durably',
-    runId,
-  })
-
-  // Don't render anything if no run
-  if (!runId) return null
+export function RunProgress({
+  progress,
+  output,
+  error,
+  logs,
+  isPending,
+  isRunning,
+  isCompleted,
+  isFailed,
+  isCancelled,
+}: RunProgressProps) {
+  // Don't render anything if no activity
+  if (!isPending && !isRunning && !isCompleted && !isFailed && !isCancelled) {
+    return null
+  }
 
   return (
     <>
       {/* Pending State */}
-      {run.isPending && (
+      {isPending && (
         
        
           
        Waiting to start...
        
         
        
       )}
 
       {/* Progress Display */}
-      {run.isRunning && run.progress && (
+      {isRunning && progress && (
         
        
           
        
             Progress
             
-              {run.progress.current}/{run.progress.total}
+              {progress.current}/{progress.total || '?'}
             
           
        
           
        
             
        
           
        
-          
        
-            {run.progress.message}
-          
        
-        
        
-      )}
-
-      {/* Cancelled State */}
-      {run.isCancelled && (
-        
        
-          
        Import Cancelled
        
-          
        
-            The import was cancelled before completion.
-          
        
+          {progress.message && (
+            
        {progress.message}
        
+          )}
         
        
       )}
 
       {/* Success Result */}
-      {run.isCompleted && run.output && (
+      {isCompleted && output !== null && output !== undefined && (
         
        
-          
        Import Completed!
        
-          
        
-            Imported: {run.output.imported} rows, Failed: {run.output.failed}{' '}
-            rows
-          
        
+          
        Completed!
        
+          
        +            {JSON.stringify(output, null, 2)}
+          
        
         
        
       )}
 
       {/* Error Result */}
-      {run.isFailed && (
+      {isFailed && (
         
        
-          
        Import Failed
        
-          
        {run.error}
        
+          
        Failed
        
+          
        {error}
        
         
        
       )}
 
-      {/* Logs Display */}
-      {run.logs.length > 0 && (
+      {/* Cancelled Result */}
+      {isCancelled && (
         
        
-          
        Logs
        
-          
        
-            {run.logs.map((log) => (
-              
        
-                [{log.level}] {log.message}
-              
        
-            ))}
+          
        Cancelled
        
+          
        
+            The job was cancelled before completion.
+          
        
+        
        
+      )}
+
+      {/* Logs */}
+      {logs.length > 0 && (
+        
        
+          
        Logs
        
+          
        
+            
          
+              {logs.map((log) => (
+                
        • 
+                  
+                    [{log.level}]
+                  {' '}
+                  {log.message}
+                
          • 
+              ))}
+            
        
           
        
         
        
       )}

From 563ef71f1e59f42672109e1f74d31e5db41d633b Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 22:40:12 +0900
Subject: [PATCH 089/101] refactor(examples): unify browser-vite-react
 dashboard with react-router examples
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add disabled button styles for consistency
- Use s.name as step key instead of s.index

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-vite-react/src/components/dashboard.tsx | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
index 653cf1ea..a3791675 100644
--- a/examples/browser-vite-react/src/components/dashboard.tsx
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -171,7 +171,7 @@ export function Dashboard() {
                           
@@ -181,7 +181,7 @@ export function Dashboard() {
                           
@@ -191,7 +191,7 @@ export function Dashboard() {
                             
@@ -307,7 +307,7 @@ export function Dashboard() {
                     
          
                       {steps.map((s) => (
                         
        • 
                           {s.name}

From 2b965dde584300d27ff5241783327caff4fd63fe Mon Sep 17 00:00:00 2001
From: coji 
Date: Fri, 2 Jan 2026 22:50:21 +0900
Subject: [PATCH 090/101] fix(examples): guard against division by zero in
 progress bar calculation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When both run.progress.current and run.progress.total are 0, the
previous calculation resulted in NaN. Now properly handles edge cases:
- If total exists, calculate percentage normally
- If no total but current > 0, show 100% (indeterminate progress)
- If both are 0, show 0%

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../browser-react-router-spa/app/routes/_index/dashboard.tsx    | 2 +-
 examples/browser-vite-react/src/components/dashboard.tsx        | 2 +-
 examples/fullstack-react-router/app/routes/_index/dashboard.tsx | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
index a3791675..b66b0fab 100644
--- a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -141,7 +141,7 @@ export function Dashboard() {
                             
           0 ? 100 : 0}%`,
                               }}
                             />
                           
          
diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
index a3791675..b66b0fab 100644
--- a/examples/browser-vite-react/src/components/dashboard.tsx
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -141,7 +141,7 @@ export function Dashboard() {
                             
           0 ? 100 : 0}%`,
                               }}
                             />
                           
          
diff --git a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
index 8729e1bf..69662503 100644
--- a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
@@ -146,7 +146,7 @@ export function Dashboard() {
                             
           0 ? 100 : 0}%`,
                               }}
                             />
                           
          

From 7b0d05590b63ad9b987b972b9a7d3a5da82d5a28 Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 11:59:48 +0900
Subject: [PATCH 091/101] feat(durably): add init() method and restructure
 documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add init() method to Durably class that combines migrate() and start()
for simpler initialization. Restructure website documentation with
new use-case focused guides and split React API docs into multiple files.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/lib/durably.server.ts                 |   3 +-
 examples/server-node/basic.ts                 |   7 +-
 packages/durably/docs/llms.md                 |  12 +-
 packages/durably/src/durably.ts               |  17 +
 website/.vitepress/config.ts                  |  24 +-
 website/api/create-durably.md                 |  98 +++-
 website/api/define-job.md                     |  65 +++
 website/api/durably-react.md                  | 456 ------------------
 website/api/durably-react/browser.md          | 270 +++++++++++
 website/api/durably-react/client.md           | 334 +++++++++++++
 website/api/durably-react/index.md            |  64 +++
 website/api/durably-react/types.md            | 107 ++++
 website/api/index.md                          | 173 ++++---
 website/api/step.md                           |   8 -
 website/guide/background-sync.md              | 229 +++++++++
 website/guide/browser-only.md                 | 148 ------
 website/guide/concepts.md                     | 164 +++++++
 website/guide/csv-import.md                   | 240 +++++++++
 website/guide/deployment.md                   | 147 ------
 website/guide/events.md                       | 143 ------
 website/guide/full-stack.md                   | 257 ----------
 website/guide/getting-started.md              | 186 ++++---
 website/guide/index.md                        |  79 +--
 website/guide/jobs-and-steps.md               | 126 -----
 website/guide/offline-app.md                  | 220 +++++++++
 website/guide/resumability.md                 | 134 -----
 website/guide/server.md                       | 182 -------
 .../public/images/fullstack-architecture.svg  |  67 +++
 .../images/getting-started-overview.svg       |  59 +++
 website/public/images/job-lifecycle.svg       |  58 +++
 website/public/images/resumability.svg        |  94 ++++
 31 files changed, 2367 insertions(+), 1804 deletions(-)
 delete mode 100644 website/api/durably-react.md
 create mode 100644 website/api/durably-react/browser.md
 create mode 100644 website/api/durably-react/client.md
 create mode 100644 website/api/durably-react/index.md
 create mode 100644 website/api/durably-react/types.md
 create mode 100644 website/guide/background-sync.md
 delete mode 100644 website/guide/browser-only.md
 create mode 100644 website/guide/concepts.md
 create mode 100644 website/guide/csv-import.md
 delete mode 100644 website/guide/deployment.md
 delete mode 100644 website/guide/events.md
 delete mode 100644 website/guide/full-stack.md
 delete mode 100644 website/guide/jobs-and-steps.md
 create mode 100644 website/guide/offline-app.md
 delete mode 100644 website/guide/resumability.md
 delete mode 100644 website/guide/server.md
 create mode 100644 website/public/images/fullstack-architecture.svg
 create mode 100644 website/public/images/getting-started-overview.svg
 create mode 100644 website/public/images/job-lifecycle.svg
 create mode 100644 website/public/images/resumability.svg

diff --git a/examples/fullstack-react-router/app/lib/durably.server.ts b/examples/fullstack-react-router/app/lib/durably.server.ts
index 85392e05..e62361d0 100644
--- a/examples/fullstack-react-router/app/lib/durably.server.ts
+++ b/examples/fullstack-react-router/app/lib/durably.server.ts
@@ -26,5 +26,4 @@ export const durably = createDurably({
 export const durablyHandler = createDurablyHandler(durably)
 
 // Initialize database and start worker
-await durably.migrate()
-durably.start()
+await durably.init()
diff --git a/examples/server-node/basic.ts b/examples/server-node/basic.ts
index 2368a78b..6f8224ba 100644
--- a/examples/server-node/basic.ts
+++ b/examples/server-node/basic.ts
@@ -31,11 +31,8 @@ async function main() {
   console.log('Durably Node.js Example')
   console.log('=======================\n')
 
-  await durably.migrate()
-  console.log('Migration completed')
-
-  durably.start()
-  console.log('Worker started\n')
+  await durably.init()
+  console.log('Initialized\n')
 
   // Trigger job and wait for completion
   const { id, output } = await durably.jobs.processImage.triggerAndWait({
diff --git a/packages/durably/docs/llms.md b/packages/durably/docs/llms.md
index ed4310e8..10d45cd6 100644
--- a/packages/durably/docs/llms.md
+++ b/packages/durably/docs/llms.md
@@ -70,11 +70,12 @@ const { syncUsers } = durably.register({
 ### 3. Starting the Worker
 
 ```ts
-// Run migrations (creates tables if needed)
-await durably.migrate()
+// Initialize: runs migrations and starts the worker
+await durably.init()
 
-// Start the worker (polls for pending jobs)
-durably.start()
+// Or separately if needed:
+// await durably.migrate()  // Run migrations only
+// durably.start()          // Start worker only
 ```
 
 ### 4. Triggering Jobs
@@ -345,8 +346,9 @@ const { myJob } = durably.register({
   }),
 })
 
+// For browser, use migrate() only if using DurablyProvider (it handles start())
+// Otherwise use init() for both migrations and worker
 await durably.migrate()
-durably.start()
 ```
 
 ## Run Lifecycle
diff --git a/packages/durably/src/durably.ts b/packages/durably/src/durably.ts
index 2496750e..1c341ede 100644
--- a/packages/durably/src/durably.ts
+++ b/packages/durably/src/durably.ts
@@ -84,6 +84,18 @@ export interface Durably<
    */
   readonly jobs: TJobs
 
+  /**
+   * Initialize Durably: run migrations and start the worker
+   * This is the recommended way to start Durably.
+   * Equivalent to calling migrate() then start().
+   * @example
+   * ```ts
+   * const durably = createDurably({ dialect }).register({ ... })
+   * await durably.init()
+   * ```
+   */
+  init(): Promise
+
   /**
    * Run database migrations
    * This is idempotent and safe to call multiple times
@@ -462,6 +474,11 @@ function createDurablyInstance<
 
       return state.migrating
     },
+
+    async init(): Promise {
+      await this.migrate()
+      this.start()
+    },
   }
 
   return durably
diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts
index 394e70af..1a0310b1 100644
--- a/website/.vitepress/config.ts
+++ b/website/.vitepress/config.ts
@@ -11,7 +11,7 @@ export default defineConfig({
     logo: '/logo.svg',
 
     nav: [
-      { text: 'Guide', link: '/guide/getting-started' },
+      { text: 'Guide', link: '/guide/' },
       { text: 'API', link: '/api/' },
       { text: 'Demo', link: 'https://durably-demo.vercel.app' },
       { text: 'llms.txt', link: '/durably/llms.txt' },
@@ -27,20 +27,17 @@ export default defineConfig({
           ],
         },
         {
-          text: 'Core Concepts',
+          text: 'Use Cases',
           items: [
-            { text: 'Jobs and Steps', link: '/guide/jobs-and-steps' },
-            { text: 'Resumability', link: '/guide/resumability' },
-            { text: 'Events', link: '/guide/events' },
+            { text: 'CSV Import (Full-Stack)', link: '/guide/csv-import' },
+            { text: 'Offline App (Browser)', link: '/guide/offline-app' },
+            { text: 'Background Sync (Server)', link: '/guide/background-sync' },
           ],
         },
         {
-          text: 'Usage',
+          text: 'Reference',
           items: [
-            { text: 'Server', link: '/guide/server' },
-            { text: 'Full-Stack', link: '/guide/full-stack' },
-            { text: 'Browser-Only', link: '/guide/browser-only' },
-            { text: 'Deployment', link: '/guide/deployment' },
+            { text: 'Core Concepts', link: '/guide/concepts' },
           ],
         },
       ],
@@ -57,7 +54,12 @@ export default defineConfig({
         },
         {
           text: 'React API',
-          items: [{ text: 'durably-react', link: '/api/durably-react' }],
+          items: [
+            { text: 'Overview', link: '/api/durably-react/' },
+            { text: 'Browser Mode', link: '/api/durably-react/browser' },
+            { text: 'Server Mode', link: '/api/durably-react/client' },
+            { text: 'Types', link: '/api/durably-react/types' },
+          ],
         },
       ],
     },
diff --git a/website/api/create-durably.md b/website/api/create-durably.md
index 9b5b649d..e7d3153a 100644
--- a/website/api/create-durably.md
+++ b/website/api/create-durably.md
@@ -30,13 +30,21 @@ interface DurablyOptions {
 
 Returns a `Durably` instance with the following methods:
 
+### `init()`
+
+```ts
+await durably.init(): Promise
+```
+
+Initialize Durably: runs database migrations and starts the worker. This is the recommended way to start Durably. Equivalent to calling `migrate()` then `start()`.
+
 ### `migrate()`
 
 ```ts
 await durably.migrate(): Promise
 ```
 
-Runs database migrations to create the required tables.
+Runs database migrations to create the required tables. Use this when you need to run migrations without starting the worker (e.g., in browser mode where `DurablyProvider` handles starting).
 
 ### `start()`
 
@@ -44,7 +52,7 @@ Runs database migrations to create the required tables.
 durably.start(): void
 ```
 
-Starts the worker that processes pending jobs.
+Starts the worker that processes pending jobs. Typically called after `migrate()`, or use `init()` for both.
 
 ### `stop()`
 
@@ -167,8 +175,8 @@ const durably = createDurably({
   staleThreshold: 30000,
 })
 
-await durably.migrate()
-durably.start()
+// Initialize (migrate + start)
+await durably.init()
 
 // Define and register jobs
 import { defineJob } from '@coji/durably'
@@ -192,3 +200,85 @@ process.on('SIGTERM', async () => {
   await durably.stop()
 })
 ```
+
+## createDurablyHandler
+
+Create HTTP handlers for exposing Durably via REST/SSE. Import from `@coji/durably/server`.
+
+```ts
+import { createDurablyHandler } from '@coji/durably/server'
+
+const handler = createDurablyHandler(durably, {
+  onRequest: async () => {
+    await durably.init()
+  },
+})
+```
+
+### Options
+
+```ts
+interface CreateDurablyHandlerOptions {
+  /** Called before handling each request */
+  onRequest?: () => Promise | void
+}
+```
+
+### handle(request, basePath)
+
+Handle all Durably HTTP requests with automatic routing.
+
+```ts
+// React Router / Remix
+export async function loader({ request }) {
+  return handler.handle(request, '/api/durably')
+}
+
+export async function action({ request }) {
+  return handler.handle(request, '/api/durably')
+}
+```
+
+### Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/subscribe?runId=xxx` | SSE stream for run events |
+| `GET` | `/runs` | List runs (query: jobName, status, limit, offset) |
+| `GET` | `/run?runId=xxx` | Get single run |
+| `GET` | `/steps?runId=xxx` | Get steps for a run |
+| `GET` | `/runs/subscribe` | SSE stream for run list updates |
+| `POST` | `/trigger` | Trigger a job |
+| `POST` | `/retry?runId=xxx` | Retry a failed run |
+| `POST` | `/cancel?runId=xxx` | Cancel a run |
+| `DELETE` | `/run?runId=xxx` | Delete a run |
+
+### Individual Handlers
+
+For custom routing, use individual handlers:
+
+```ts
+app.post('/api/durably/trigger', (req) => handler.trigger(req))
+app.get('/api/durably/subscribe', (req) => handler.subscribe(req))
+app.get('/api/durably/runs', (req) => handler.runs(req))
+app.get('/api/durably/run', (req) => handler.run(req))
+app.get('/api/durably/steps', (req) => handler.steps(req))
+app.post('/api/durably/retry', (req) => handler.retry(req))
+app.post('/api/durably/cancel', (req) => handler.cancel(req))
+app.delete('/api/durably/run', (req) => handler.delete(req))
+app.get('/api/durably/runs/subscribe', (req) => handler.runsSubscribe(req))
+```
+
+### Trigger Request Format
+
+```ts
+// POST /api/durably/trigger
+{
+  "jobName": "import-csv",
+  "input": { "file": "data.csv" },
+  "idempotencyKey": "unique-key",  // optional
+  "concurrencyKey": "user-123"      // optional
+}
+
+// Response: { "runId": "run_abc123" }
+```
diff --git a/website/api/define-job.md b/website/api/define-job.md
index 0da56119..b43f6bc1 100644
--- a/website/api/define-job.md
+++ b/website/api/define-job.md
@@ -79,6 +79,7 @@ Triggers a new job run.
 interface TriggerOptions {
   idempotencyKey?: string
   concurrencyKey?: string
+  timeout?: number  // For triggerAndWait only
 }
 ```
 
@@ -86,6 +87,70 @@ interface TriggerOptions {
 |--------|-------------|
 | `idempotencyKey` | Prevents duplicate runs with the same key |
 | `concurrencyKey` | Groups jobs for concurrency control |
+| `timeout` | Timeout in ms for `triggerAndWait()` |
+
+### `triggerAndWait()`
+
+```ts
+await job.triggerAndWait(
+  input: TInput,
+  options?: TriggerOptions
+): Promise<{ id: string; output: TOutput }>
+```
+
+Triggers a run and waits for completion. Throws if the run fails.
+
+```ts
+const { id, output } = await job.triggerAndWait({ orgId: 'org_123' })
+console.log('Completed:', output)
+
+// With timeout
+const { output } = await job.triggerAndWait(
+  { orgId: 'org_123' },
+  { timeout: 30000 }  // 30 seconds
+)
+```
+
+### `batchTrigger()`
+
+```ts
+await job.batchTrigger(
+  inputs: (TInput | { input: TInput; options?: TriggerOptions })[]
+): Promise[]>
+```
+
+Triggers multiple runs. All inputs are validated before any runs are created.
+
+```ts
+// Simple batch
+const runs = await job.batchTrigger([
+  { orgId: 'org_1' },
+  { orgId: 'org_2' },
+  { orgId: 'org_3' },
+])
+
+// With per-item options
+const runs = await job.batchTrigger([
+  { input: { orgId: 'org_1' }, options: { idempotencyKey: 'key-1' } },
+  { input: { orgId: 'org_2' }, options: { idempotencyKey: 'key-2' } },
+])
+```
+
+### `getRun()`
+
+```ts
+await job.getRun(id: string): Promise | null>
+```
+
+Gets a run by ID (only returns runs for this job).
+
+### `getRuns()`
+
+```ts
+await job.getRuns(filter?: { status?, limit?, offset? }): Promise[]>
+```
+
+Gets runs for this job with optional filtering.
 
 ## Example
 
diff --git a/website/api/durably-react.md b/website/api/durably-react.md
deleted file mode 100644
index 2f3b30bf..00000000
--- a/website/api/durably-react.md
+++ /dev/null
@@ -1,456 +0,0 @@
-# durably-react
-
-React bindings for Durably - hooks for triggering and monitoring jobs.
-
-## Installation
-
-```bash
-# Browser-complete mode
-npm install @coji/durably-react @coji/durably kysely zod sqlocal
-
-# Server-connected mode (client only)
-npm install @coji/durably-react
-```
-
-## Browser-Complete Mode
-
-Run Durably entirely in the browser using SQLite WASM.
-
-### DurablyProvider
-
-Wraps your app and initializes Durably.
-
-```tsx
-import { DurablyProvider } from '@coji/durably-react'
-import { createDurably, defineJob } from '@coji/durably'
-import { SQLocalKysely } from 'sqlocal/kysely'
-
-// Create Durably instance
-async function createBrowserDurably() {
-  const { dialect } = new SQLocalKysely('app.sqlite3')
-  const durably = createDurably({ dialect, pollingInterval: 100 })
-  durably.register({ myJob: myJobDef })
-  await durably.migrate()
-  return durably
-}
-
-const durablyPromise = createBrowserDurably()
-
-function App() {
-  return (
-    Loading...
          }>
-      
-              
-  )
-}
-```
-
-**Props:**
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `durably` | `Durably \| Promise` | required | Durably instance or Promise |
-| `autoStart` | `boolean` | `true` | Auto-start worker on mount |
-| `onReady` | `(durably: Durably) => void` | - | Callback when ready |
-| `fallback` | `ReactNode` | - | Loading fallback (wraps in Suspense) |
-
-### useDurably
-
-Access the Durably instance directly.
-
-```tsx
-import { useDurably } from '@coji/durably-react'
-
-function Component() {
-  const { durably, isReady, error } = useDurably()
-
-  if (!isReady) return 
          Loading...
          
-  if (error) return 
          Error: {error.message}
          
-
-  // Use durably instance directly
-}
-```
-
-### useJob
-
-Trigger and monitor a job.
-
-```tsx
-import { defineJob } from '@coji/durably'
-import { useJob } from '@coji/durably-react'
-import { z } from 'zod'
-
-const myJob = defineJob({
-  name: 'my-job',
-  input: z.object({ value: z.string() }),
-  output: z.object({ result: z.number() }),
-  run: async (step, payload) => {
-    const data = await step.run('process', () => process(payload.value))
-    return { result: data.length }
-  },
-})
-
-function Component() {
-  const {
-    isReady,
-    trigger,
-    triggerAndWait,
-    status,
-    output,
-    error,
-    logs,
-    progress,
-    isRunning,
-    isPending,
-    isCompleted,
-    isFailed,
-    currentRunId,
-    reset,
-  } = useJob(myJob, { initialRunId: undefined })
-
-  const handleClick = async () => {
-    const { runId } = await trigger({ value: 'test' })
-    console.log('Started:', runId)
-  }
-
-  return (
-    
          
-      
-      
          Status: {status}
          
-      {progress && 
          Progress: {progress.current}/{progress.total}
          }
-      {isCompleted && 
          Result: {output?.result}
          }
-      {isFailed && 
          Error: {error}
          }
-      
-    
          
-  )
-}
-```
-
-**Return Type:**
-
-```ts
-interface UseJobResult {
-  isReady: boolean
-  trigger: (input: TInput) => Promise<{ runId: string }>
-  triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }>
-  status: 'pending' | 'running' | 'completed' | 'failed' | null
-  output: TOutput | null
-  error: string | null
-  logs: LogEntry[]
-  progress: Progress | null
-  isRunning: boolean
-  isPending: boolean
-  isCompleted: boolean
-  isFailed: boolean
-  currentRunId: string | null
-  reset: () => void
-}
-```
-
-### useJobRun
-
-Subscribe to an existing run by ID.
-
-```tsx
-import { useJobRun } from '@coji/durably-react'
-
-function RunMonitor({ runId }: { runId: string | null }) {
-  const {
-    isReady,
-    status,
-    output,
-    error,
-    progress,
-    logs,
-    isRunning,
-    isCompleted,
-    isFailed,
-  } = useJobRun<{ result: number }>({ runId })
-
-  if (!runId) return 
          No run selected
          
-
-  return (
-    
          
-      
          Status: {status}
          
-      {isCompleted && 
          Output: {JSON.stringify(output)}
          }
-    
          
-  )
-}
-```
-
-### useJobLogs
-
-Subscribe to logs from a run.
-
-```tsx
-import { useJobLogs } from '@coji/durably-react'
-
-function LogViewer({ runId }: { runId: string | null }) {
-  const { isReady, logs, clearLogs } = useJobLogs({
-    runId,
-    maxLogs: 100,
-  })
-
-  return (
-    
          
-      
-      
            
-        {logs.map((log) => (
-          
          • 
-            [{log.level}] {log.message}
-            {log.data && 
            {JSON.stringify(log.data)}
            }
-          
            • 
-        ))}
-      
          
-    
          
-  )
-}
-```
-
-## Server-Connected Mode
-
-Import hooks from `@coji/durably-react/client` for server-connected mode.
-
-### useJob (Client)
-
-```tsx
-import { useJob } from '@coji/durably-react/client'
-
-function Component() {
-  const {
-    isReady, // Always true in client mode
-    trigger,
-    triggerAndWait,
-    status,
-    output,
-    error,
-    logs,
-    progress,
-    isRunning,
-    isCompleted,
-    currentRunId,
-    reset,
-  } = useJob<
-    { userId: string }, // Input type
-    { count: number }   // Output type
-  >({
-    api: '/api/durably',
-    jobName: 'sync-data',
-  })
-
-  const handleClick = async () => {
-    const { runId } = await trigger({ userId: 'user_123' })
-    console.log('Started:', runId)
-  }
-
-  return 
-}
-```
-
-### useJobRun (Client)
-
-```tsx
-import { useJobRun } from '@coji/durably-react/client'
-
-function Component({ runId }: { runId: string }) {
-  const { status, output, error, progress, logs } = useJobRun<{ count: number }>({
-    api: '/api/durably',
-    runId,
-  })
-
-  return 
          Status: {status}
          
-}
-```
-
-### useJobLogs (Client)
-
-```tsx
-import { useJobLogs } from '@coji/durably-react/client'
-
-function Component({ runId }: { runId: string }) {
-  const { logs, clearLogs } = useJobLogs({
-    api: '/api/durably',
-    runId,
-    maxLogs: 50,
-  })
-
-  return (
-    
            
-      {logs.map((log) => (
-        
          • {log.message}
            • 
-      ))}
-    
          
-  )
-}
-```
-
-### Server Setup
-
-On your server, use `createDurablyHandler` from `@coji/durably/server`:
-
-```ts
-import { createDurably, defineJob } from '@coji/durably'
-import { createDurablyHandler } from '@coji/durably/server'
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-import { createClient } from '@libsql/client'
-import { z } from 'zod'
-
-const client = createClient({ url: 'file:local.db' })
-const dialect = new LibsqlDialect({ client })
-
-const durably = createDurably({ dialect })
-const handler = createDurablyHandler(durably)
-
-// Define and register jobs
-const syncJobDef = defineJob({
-  name: 'sync-data',
-  input: z.object({ userId: z.string() }),
-  output: z.object({ count: z.number() }),
-  run: async (step, payload) => {
-    // Job logic
-    return { count: 0 }
-  },
-})
-
-export const jobs = durably.register({ syncData: syncJobDef })
-
-await durably.migrate()
-durably.start()
-
-// Use the unified handle() method (recommended)
-app.all('/api/durably/*', async (req) => {
-  return handler.handle(req, '/api/durably')
-})
-
-// Or use individual route handlers
-app.post('/api/durably/trigger', (req) => handler.trigger(req))
-app.get('/api/durably/subscribe', (req) => handler.subscribe(req))
-app.get('/api/durably/runs', (req) => handler.runs(req))
-app.get('/api/durably/runs/subscribe', (req) => handler.runsSubscribe(req))
-```
-
-### createDurablyClient
-
-Create a type-safe client for all registered jobs:
-
-```ts
-// durably.client.ts
-import { createDurablyClient } from '@coji/durably-react/client'
-import type { jobs } from './durably.server'
-
-export const durably = createDurablyClient({
-  api: '/api/durably',
-})
-
-// Usage in components
-function Component() {
-  const { trigger, status, output } = durably.syncData.useJob()
-  // trigger() is type-safe!
-}
-```
-
-### useRuns
-
-List and paginate job runs with real-time updates:
-
-```tsx
-import { useRuns } from '@coji/durably-react/client'
-
-function Dashboard() {
-  const {
-    runs,
-    isLoading,
-    error,
-    page,
-    hasMore,
-    nextPage,
-    prevPage,
-    refresh,
-  } = useRuns({
-    api: '/api/durably',
-    jobName: 'sync-data', // optional filter
-    pageSize: 10,
-    realtime: true, // auto-refresh on SSE events
-  })
-
-  return (
-    
            
-      {runs.map((run) => (
-        
          • {run.status}
            • 
-      ))}
-    
          
-  )
-}
-```
-
-### useRunActions
-
-Perform actions on runs:
-
-```tsx
-import { useRunActions } from '@coji/durably-react/client'
-
-function RunActions({ runId }: { runId: string }) {
-  const {
-    cancel,
-    retry,
-    deleteRun,
-    getRun,
-    getSteps,
-    isLoading,
-  } = useRunActions({ api: '/api/durably' })
-
-  return (
-    
          
-      
-      
-      
-    
          
-  )
-}
-```
-
-## Type Definitions
-
-```ts
-type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
-
-interface Progress {
-  current: number
-  total?: number
-  message?: string
-}
-
-interface LogEntry {
-  id: string
-  runId: string
-  stepName: string | null
-  level: 'info' | 'warn' | 'error'
-  message: string
-  data: unknown
-  timestamp: string
-}
-
-interface RunRecord {
-  id: string
-  jobName: string
-  status: RunStatus
-  payload: unknown
-  output: unknown
-  error: string | null
-  progress: Progress | null
-  createdAt: string
-  updatedAt: string
-}
-
-interface StepRecord {
-  name: string
-  status: 'completed' | 'failed'
-  output: unknown
-  error: string | null
-  startedAt: string
-  completedAt: string | null
-}
-```
diff --git a/website/api/durably-react/browser.md b/website/api/durably-react/browser.md
new file mode 100644
index 00000000..73c9f4e8
--- /dev/null
+++ b/website/api/durably-react/browser.md
@@ -0,0 +1,270 @@
+# Browser-Complete Mode
+
+Run Durably entirely in the browser using SQLite WASM with OPFS persistence.
+
+```tsx
+import { DurablyProvider, useDurably, useJob, useJobRun, useJobLogs, useRuns } from '@coji/durably-react'
+```
+
+## DurablyProvider
+
+Wraps your app and initializes Durably with a browser SQLite database.
+
+```tsx
+import { DurablyProvider } from '@coji/durably-react'
+import { createDurably } from '@coji/durably'
+import { SQLocalKysely } from 'sqlocal/kysely'
+
+const sqlocal = new SQLocalKysely('app.sqlite3')
+
+const durably = createDurably({
+  dialect: sqlocal.dialect,
+  pollingInterval: 100,
+}).register({
+  myJob: myJobDef,
+})
+
+await durably.migrate()
+
+function App() {
+  return (
+    Loading...
          }>
+      
+              
+  )
+}
+```
+
+### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `durably` | `Durably \| Promise` | required | Durably instance or Promise |
+| `autoStart` | `boolean` | `true` | Auto-start worker on mount |
+| `onReady` | `(durably: Durably) => void` | - | Callback when ready |
+| `fallback` | `ReactNode` | - | Loading fallback (wraps in Suspense) |
+
+---
+
+## useDurably
+
+Access the Durably instance directly.
+
+```tsx
+import { useDurably } from '@coji/durably-react'
+
+function Component() {
+  const { durably, isReady, error } = useDurably()
+
+  if (!isReady) return 
          Loading...
          
+  if (error) return 
          Error: {error.message}
          
+
+  // Use durably instance directly
+  const runs = await durably.storage.getRuns()
+}
+```
+
+### Return Type
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `durably` | `Durably \| null` | The Durably instance |
+| `isReady` | `boolean` | Whether Durably is initialized |
+| `error` | `Error \| null` | Initialization error |
+
+---
+
+## useJob
+
+Trigger and monitor a job. Pass a `JobDefinition` to get type-safe input/output.
+
+```tsx
+import { defineJob } from '@coji/durably'
+import { useJob } from '@coji/durably-react'
+import { z } from 'zod'
+
+const myJob = defineJob({
+  name: 'my-job',
+  input: z.object({ value: z.string() }),
+  output: z.object({ result: z.number() }),
+  run: async (step, payload) => {
+    const data = await step.run('process', () => process(payload.value))
+    return { result: data.length }
+  },
+})
+
+function Component() {
+  const {
+    isReady,
+    trigger,
+    triggerAndWait,
+    status,
+    output,
+    error,
+    logs,
+    progress,
+    isRunning,
+    isPending,
+    isCompleted,
+    isFailed,
+    currentRunId,
+    reset,
+  } = useJob(myJob)
+
+  const handleClick = async () => {
+    const { runId } = await trigger({ value: 'test' })
+    console.log('Started:', runId)
+  }
+
+  return (
+    
          
+      
+      
          Status: {status}
          
+      {progress && 
          Progress: {progress.current}/{progress.total}
          }
+      {isCompleted && 
          Result: {output?.result}
          }
+      {isFailed && 
          Error: {error}
          }
+      
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `initialRunId` | `string` | Resume subscription to an existing run |
+
+### Return Type
+
+```ts
+interface UseJobResult {
+  isReady: boolean
+  trigger: (input: TInput) => Promise<{ runId: string }>
+  triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }>
+  status: RunStatus | null
+  output: TOutput | null
+  error: string | null
+  logs: LogEntry[]
+  progress: Progress | null
+  isRunning: boolean
+  isPending: boolean
+  isCompleted: boolean
+  isFailed: boolean
+  currentRunId: string | null
+  reset: () => void
+}
+```
+
+---
+
+## useJobRun
+
+Subscribe to an existing run by ID.
+
+```tsx
+import { useJobRun } from '@coji/durably-react'
+
+function RunMonitor({ runId }: { runId: string | null }) {
+  const {
+    isReady,
+    status,
+    output,
+    error,
+    progress,
+    logs,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJobRun<{ result: number }>({ runId })
+
+  if (!runId) return 
          No run selected
          
+
+  return (
+    
          
+      
          Status: {status}
          
+      {isCompleted && 
          Output: {JSON.stringify(output)}
          }
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `runId` | `string \| null` | The run ID to subscribe to |
+
+---
+
+## useJobLogs
+
+Subscribe to logs from a run.
+
+```tsx
+import { useJobLogs } from '@coji/durably-react'
+
+function LogViewer({ runId }: { runId: string | null }) {
+  const { isReady, logs, clearLogs } = useJobLogs({
+    runId,
+    maxLogs: 100,
+  })
+
+  return (
+    
          
+      
+      
            
+        {logs.map((log) => (
+          
          • 
+            [{log.level}] {log.message}
+            {log.data && 
            {JSON.stringify(log.data)}
            }
+          
            • 
+        ))}
+      
          
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `runId` | `string \| null` | The run ID to subscribe to |
+| `maxLogs` | `number` | Maximum number of logs to keep |
+
+---
+
+## useRuns
+
+List runs with optional filtering.
+
+```tsx
+import { useRuns } from '@coji/durably-react'
+
+function RunList() {
+  const { runs, isLoading } = useRuns({
+    jobName: 'my-job',
+    status: 'completed',
+    limit: 10,
+  })
+
+  return (
+    
            
+      {runs.map(run => (
+        
          • {run.status}
            • 
+      ))}
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `jobName` | `string` | Filter by job name |
+| `status` | `RunStatus` | Filter by status |
+| `limit` | `number` | Maximum number of runs to return |
diff --git a/website/api/durably-react/client.md b/website/api/durably-react/client.md
new file mode 100644
index 00000000..8b8bd75a
--- /dev/null
+++ b/website/api/durably-react/client.md
@@ -0,0 +1,334 @@
+# Server-Connected Mode
+
+Connect to a Durably server via HTTP/SSE for real-time job monitoring.
+
+```tsx
+import {
+  createDurablyClient,
+  useJob,
+  useJobRun,
+  useJobLogs,
+  useRuns,
+  useRunActions,
+} from '@coji/durably-react/client'
+```
+
+## createDurablyClient
+
+Create a type-safe client for all registered jobs. This is the recommended way to use server-connected mode.
+
+### Server Setup
+
+```ts
+// app/lib/durably.server.ts
+import { createDurably, createDurablyHandler } from '@coji/durably'
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+import { createClient } from '@libsql/client'
+
+const client = createClient({ url: 'file:local.db' })
+const dialect = new LibsqlDialect({ client })
+
+export const durably = createDurably({ dialect }).register({
+  importCsv: importCsvJob,
+  syncUsers: syncUsersJob,
+})
+
+export const durablyHandler = createDurablyHandler(durably)
+
+await durably.migrate()
+durably.start()
+```
+
+```ts
+// app/routes/api.durably.$.ts
+import { durablyHandler } from '~/lib/durably.server'
+import type { Route } from './+types/api.durably.$'
+
+export async function loader({ request }: Route.LoaderArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+```
+
+### Client Setup
+
+```ts
+// app/lib/durably.client.ts
+import { createDurablyClient } from '@coji/durably-react/client'
+import type { durably } from './durably.server'
+
+export const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+```
+
+### Usage
+
+```tsx
+// Fully type-safe!
+function CsvImporter() {
+  const { trigger, status, output, isRunning } = durablyClient.importCsv.useJob()
+
+  return (
+    
+  )
+}
+
+// Subscribe to an existing run
+function RunViewer({ runId }: { runId: string }) {
+  const { status, output, progress } = durablyClient.importCsv.useRun(runId)
+  return 
          Status: {status}
          
+}
+
+// Subscribe to logs
+function LogViewer({ runId }: { runId: string }) {
+  const { logs } = durablyClient.importCsv.useLogs(runId)
+  return 
          {logs.map(l => l.message).join('\n')}
          
+}
+```
+
+---
+
+## useJob
+
+Direct hook for triggering jobs when not using `createDurablyClient`.
+
+```tsx
+import { useJob } from '@coji/durably-react/client'
+
+function Component() {
+  const {
+    isReady,
+    trigger,
+    triggerAndWait,
+    status,
+    output,
+    error,
+    logs,
+    progress,
+    isRunning,
+    isCompleted,
+    currentRunId,
+    reset,
+  } = useJob<
+    { userId: string },  // Input type
+    { count: number }    // Output type
+  >({
+    api: '/api/durably',
+    jobName: 'sync-data',
+    initialRunId: undefined,  // Optional: resume existing run
+  })
+
+  const handleClick = async () => {
+    const { runId } = await trigger({ userId: 'user_123' })
+    console.log('Started:', runId)
+  }
+
+  return 
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `api` | `string` | API base path (e.g., `/api/durably`) |
+| `jobName` | `string` | Name of the job to trigger |
+| `initialRunId` | `string` | Resume subscription to an existing run |
+
+---
+
+## useJobRun
+
+Subscribe to an existing run via SSE.
+
+```tsx
+import { useJobRun } from '@coji/durably-react/client'
+
+function Component({ runId }: { runId: string }) {
+  const { status, output, error, progress, logs } = useJobRun<{ count: number }>({
+    api: '/api/durably',
+    runId,
+  })
+
+  return 
          Status: {status}
          
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `api` | `string` | API base path |
+| `runId` | `string` | The run ID to subscribe to |
+
+---
+
+## useJobLogs
+
+Subscribe to logs from a run via SSE.
+
+```tsx
+import { useJobLogs } from '@coji/durably-react/client'
+
+function Component({ runId }: { runId: string }) {
+  const { logs, clearLogs } = useJobLogs({
+    api: '/api/durably',
+    runId,
+    maxLogs: 50,
+  })
+
+  return (
+    
            
+      {logs.map((log) => (
+        
          • {log.message}
            • 
+      ))}
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `api` | `string` | API base path |
+| `runId` | `string` | The run ID to subscribe to |
+| `maxLogs` | `number` | Maximum number of logs to keep |
+
+---
+
+## useRuns
+
+List and paginate job runs with real-time updates on the first page.
+
+```tsx
+import { useRuns } from '@coji/durably-react/client'
+
+function Dashboard() {
+  const {
+    runs,
+    isLoading,
+    error,
+    page,
+    hasMore,
+    nextPage,
+    prevPage,
+    goToPage,
+    refresh,
+  } = useRuns({
+    api: '/api/durably',
+    jobName: 'sync-data',  // Optional filter
+    status: 'completed',   // Optional filter
+    pageSize: 10,
+  })
+
+  return (
+    
          
+      
            
+        {runs.map((run) => (
+          
          • 
+            {run.jobName}: {run.status}
+            {run.progress && ` (${run.progress.current}/${run.progress.total})`}
+          
            • 
+        ))}
+      
          
+      
          
+        
+        Page {page + 1}
+        
+        
+      
          
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `api` | `string` | API base path |
+| `jobName` | `string` | Filter by job name |
+| `status` | `RunStatus` | Filter by status |
+| `pageSize` | `number` | Number of runs per page |
+
+### Return Type
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `runs` | `RunRecord[]` | List of runs |
+| `isLoading` | `boolean` | Loading state |
+| `error` | `string \| null` | Error message |
+| `page` | `number` | Current page (0-indexed) |
+| `hasMore` | `boolean` | Whether more pages exist |
+| `nextPage` | `() => void` | Go to next page |
+| `prevPage` | `() => void` | Go to previous page |
+| `goToPage` | `(page: number) => void` | Go to specific page |
+| `refresh` | `() => void` | Refresh current page |
+
+---
+
+## useRunActions
+
+Perform actions on runs (retry, cancel, delete).
+
+```tsx
+import { useRunActions } from '@coji/durably-react/client'
+
+function RunActions({ runId, status }: { runId: string; status: string }) {
+  const {
+    retry,
+    cancel,
+    deleteRun,
+    getRun,
+    getSteps,
+    isLoading,
+    error,
+  } = useRunActions({ api: '/api/durably' })
+
+  return (
+    
          
+      {(status === 'failed' || status === 'cancelled') && (
+        
+      )}
+      {(status === 'pending' || status === 'running') && (
+        
+      )}
+      {(status === 'completed' || status === 'failed' || status === 'cancelled') && (
+        
+      )}
+      {error && {error}}
+    
          
+  )
+}
+```
+
+### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `api` | `string` | API base path |
+
+### Return Type
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `retry` | `(runId: string) => Promise` | Retry a failed run |
+| `cancel` | `(runId: string) => Promise` | Cancel a running job |
+| `deleteRun` | `(runId: string) => Promise` | Delete a run |
+| `getRun` | `(runId: string) => Promise` | Get run details |
+| `getSteps` | `(runId: string) => Promise` | Get step details |
+| `isLoading` | `boolean` | Loading state |
+| `error` | `string \| null` | Error message |
diff --git a/website/api/durably-react/index.md b/website/api/durably-react/index.md
new file mode 100644
index 00000000..a9562664
--- /dev/null
+++ b/website/api/durably-react/index.md
@@ -0,0 +1,64 @@
+# durably-react
+
+React bindings for Durably - hooks for triggering and monitoring jobs.
+
+## Installation
+
+```bash
+# Browser-complete mode (runs Durably entirely in browser)
+npm install @coji/durably-react @coji/durably kysely zod sqlocal
+
+# Server-connected mode (connects to server via HTTP/SSE)
+npm install @coji/durably-react
+```
+
+## Two Modes
+
+Durably React provides two distinct modes for different use cases:
+
+### Browser-Complete Mode
+
+Run Durably entirely in the browser using SQLite WASM with OPFS. All job execution happens client-side.
+
+```tsx
+import { DurablyProvider, useJob } from '@coji/durably-react'
+```
+
+**Use when:**
+- Building offline-capable applications
+- Local-first apps where data stays on device
+- Prototyping without a backend
+
+[Browser-Complete Mode Reference →](./browser)
+
+### Server-Connected Mode
+
+Connect to a Durably server via HTTP/SSE. Jobs execute on the server, with real-time updates streamed to the client.
+
+```tsx
+import { createDurablyClient } from '@coji/durably-react/client'
+```
+
+**Use when:**
+- Building full-stack applications
+- Jobs need server-side resources (databases, APIs)
+- Sharing job state across multiple clients
+
+[Server-Connected Mode Reference →](./client)
+
+## Quick Comparison
+
+| Feature | Browser-Complete | Server-Connected |
+|---------|------------------|------------------|
+| Import | `@coji/durably-react` | `@coji/durably-react/client` |
+| Job Execution | Client-side | Server-side |
+| Persistence | OPFS (browser) | Server database |
+| Offline Support | Yes | No |
+| Multi-client | No (single tab) | Yes |
+| Setup | DurablyProvider | API endpoint |
+
+## Type Definitions
+
+Common types used across both modes.
+
+[Type Definitions →](./types)
diff --git a/website/api/durably-react/types.md b/website/api/durably-react/types.md
new file mode 100644
index 00000000..e07b81ad
--- /dev/null
+++ b/website/api/durably-react/types.md
@@ -0,0 +1,107 @@
+# Type Definitions
+
+Common types used across both Browser-Complete and Server-Connected modes.
+
+## RunStatus
+
+```ts
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+```
+
+| Status | Description |
+|--------|-------------|
+| `pending` | Job is queued, waiting to be picked up by worker |
+| `running` | Job is currently executing |
+| `completed` | Job finished successfully |
+| `failed` | Job encountered an error |
+| `cancelled` | Job was cancelled before completion |
+
+## Progress
+
+```ts
+interface Progress {
+  current: number
+  total?: number
+  message?: string
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `current` | `number` | Current progress value |
+| `total` | `number \| undefined` | Total expected value |
+| `message` | `string \| undefined` | Human-readable progress message |
+
+## LogEntry
+
+```ts
+interface LogEntry {
+  id: string
+  runId: string
+  stepName: string | null
+  level: 'info' | 'warn' | 'error'
+  message: string
+  data: unknown
+  timestamp: string
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Unique log entry ID |
+| `runId` | `string` | Associated run ID |
+| `stepName` | `string \| null` | Step that created the log |
+| `level` | `'info' \| 'warn' \| 'error'` | Log severity |
+| `message` | `string` | Log message |
+| `data` | `unknown` | Optional structured data |
+| `timestamp` | `string` | ISO timestamp |
+
+## RunRecord
+
+```ts
+interface RunRecord {
+  id: string
+  jobName: string
+  status: RunStatus
+  payload: unknown
+  output: unknown
+  error: string | null
+  progress: Progress | null
+  createdAt: string
+  updatedAt: string
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `id` | `string` | Unique run ID |
+| `jobName` | `string` | Name of the job |
+| `status` | `RunStatus` | Current status |
+| `payload` | `unknown` | Input payload |
+| `output` | `unknown` | Job output (when completed) |
+| `error` | `string \| null` | Error message (when failed) |
+| `progress` | `Progress \| null` | Current progress |
+| `createdAt` | `string` | ISO timestamp of creation |
+| `updatedAt` | `string` | ISO timestamp of last update |
+
+## StepRecord
+
+```ts
+interface StepRecord {
+  name: string
+  status: 'completed' | 'failed'
+  output: unknown
+  error: string | null
+  startedAt: string
+  completedAt: string | null
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `name` | `string` | Step name |
+| `status` | `'completed' \| 'failed'` | Step result |
+| `output` | `unknown` | Step return value |
+| `error` | `string \| null` | Error message (when failed) |
+| `startedAt` | `string` | ISO timestamp of start |
+| `completedAt` | `string \| null` | ISO timestamp of completion |
diff --git a/website/api/index.md b/website/api/index.md
index 61e39eb1..6015d60a 100644
--- a/website/api/index.md
+++ b/website/api/index.md
@@ -1,115 +1,156 @@
 # API Reference
 
-This section provides detailed API documentation for Durably.
+Complete API documentation for Durably.
 
 ## Core API (@coji/durably)
 
 | Export | Description |
 |--------|-------------|
 | [`createDurably`](/api/create-durably) | Create a Durably instance |
-| [`defineJob`](/api/define-job) | Define a job (standalone function) |
+| [`defineJob`](/api/define-job) | Define a job with type-safe schema |
 | [`Step`](/api/step) | Step context for job handlers |
 | [`Events`](/api/events) | Event types and subscriptions |
 
 ## React API (@coji/durably-react)
 
+### Browser-Complete Mode
+
 | Export | Description |
 |--------|-------------|
-| [`DurablyProvider`](/api/durably-react#durablyprovider) | React context provider |
-| [`useJob`](/api/durably-react#usejob) | Trigger and monitor a job |
-| [`useJobRun`](/api/durably-react#usejobrun) | Subscribe to an existing run |
-| [`useJobLogs`](/api/durably-react#usejoblogs) | Subscribe to logs from a run |
-| [`useDurably`](/api/durably-react#usedurably) | Access Durably instance directly |
+| [`DurablyProvider`](/api/durably-react/browser#durablyprovider) | React context provider |
+| [`useDurably`](/api/durably-react/browser#usedurably) | Access Durably instance directly |
+| [`useJob`](/api/durably-react/browser#usejob) | Trigger and monitor a job |
+| [`useJobRun`](/api/durably-react/browser#usejobrun) | Subscribe to an existing run |
+| [`useJobLogs`](/api/durably-react/browser#usejoblogs) | Subscribe to logs from a run |
+| [`useRuns`](/api/durably-react/browser#useruns) | List runs with filtering |
 
-See the [durably-react API reference](/api/durably-react) for detailed documentation.
+### Server-Connected Mode (@coji/durably-react/client)
 
-## Quick Reference
+| Export | Description |
+|--------|-------------|
+| [`createDurablyClient`](/api/durably-react/client#createdurablyclient) | Type-safe client for server mode |
+| [`useJob`](/api/durably-react/client#usejob) | Trigger job via HTTP |
+| [`useJobRun`](/api/durably-react/client#usejobrun) | Subscribe to run via SSE |
+| [`useJobLogs`](/api/durably-react/client#usejoblogs) | Subscribe to logs via SSE |
+| [`useRuns`](/api/durably-react/client#useruns) | List and paginate runs |
+| [`useRunActions`](/api/durably-react/client#userunactions) | Run actions (cancel, retry, delete) |
 
-### Creating an Instance
+[Full React API Reference →](/api/durably-react/)
 
-```ts
-import { createDurably, defineJob } from '@coji/durably'
+## Server API (@coji/durably)
 
-const durably = createDurably({
-  dialect,                    // Kysely SQLite dialect
-  pollingInterval: 1000,      // Worker polling interval (ms)
-  heartbeatInterval: 5000,    // Heartbeat update interval (ms)
-  staleThreshold: 30000,      // Time until job is considered stale (ms)
-})
-```
+| Export | Description |
+|--------|-------------|
+| [`createDurablyHandler`](/api/create-durably#createdurablyhandler) | Create HTTP handlers for Durably |
 
-### Instance Methods
+## Quick Start
 
-```ts
-// Lifecycle
-await durably.migrate()       // Run database migrations
-durably.start()               // Start the worker
-await durably.stop()          // Stop the worker gracefully
+### Installation
 
-// Job management
-const { job } = durably.register({ job: jobDef })  // Register jobs
-await durably.retry(runId)            // Retry a failed run
+```bash
+# Core package
+npm install @coji/durably kysely zod
 
-// Events
-const unsub = durably.on(event, handler)
+# React bindings (optional)
+npm install @coji/durably-react
+
+# SQLite driver (choose one)
+npm install @libsql/kysely-libsql   # Server (libSQL/Turso)
+npm install sqlocal                  # Browser (OPFS)
 ```
 
-### Defining and Registering Jobs
+### Basic Setup
 
 ```ts
-import { defineJob } from '@coji/durably'
-
-// Define a job
-const myJobDef = defineJob({
-  name: 'my-job',
-  input: z.object({ id: z.string() }),
-  output: z.object({ result: z.string() }),
+import { createDurably, defineJob } from '@coji/durably'
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+import { createClient } from '@libsql/client'
+import { z } from 'zod'
+
+// 1. Create SQLite dialect
+const client = createClient({ url: 'file:local.db' })
+const dialect = new LibsqlDialect({ client })
+
+// 2. Define job
+const processDataJob = defineJob({
+  name: 'process-data',
+  input: z.object({ items: z.array(z.string()) }),
+  output: z.object({ count: z.number() }),
   run: async (step, payload) => {
-    const result = await step.run('step-name', async () => {
-      return value
-    })
-    return { result }
+    for (let i = 0; i < payload.items.length; i++) {
+      await step.run(`process-${i}`, async () => {
+        // Process item
+      })
+      step.progress(i + 1, payload.items.length)
+    }
+    return { count: payload.items.length }
   },
 })
 
-// Register with durably instance
-const { myJob } = durably.register({
-  myJob: myJobDef,
+// 3. Create Durably instance with registered jobs
+const durably = createDurably({ dialect }).register({
+  processData: processDataJob,
 })
 
-// Trigger a new run
-await myJob.trigger(input, options?)
-```
-
-### Step Methods
-
-```ts
-defineJob({
-  name: 'example',
-  input: z.object({}),
-  run: async (step, payload) => {
-    // Execute a step
-    const result = await step.run('step-name', async () => {
-      return value
-    })
+// 4. Initialize and start
+await durably.migrate()
+durably.start()
 
-    // Log a message
-    step.log.info('message', { data })
-  },
-})
+// 5. Trigger a job
+const run = await durably.jobs.processData.trigger({ items: ['a', 'b', 'c'] })
+console.log('Run ID:', run.id)
 ```
 
 ## Type Exports
 
 ```ts
 import type {
+  // Core
   Durably,
   DurablyOptions,
+  DurablyPlugin,
+
+  // Job
   JobDefinition,
   JobHandle,
+  JobInput,
+  JobOutput,
+
+  // Step
   StepContext,
-  TriggerOptions,
+
+  // Run
+  Run,
+  RunFilter,
   RunStatus,
-  StepStatus,
+  TriggerOptions,
+  TriggerAndWaitResult,
+
+  // Events
+  DurablyEvent,
+  EventType,
+  EventListener,
+  Unsubscribe,
+  ErrorHandler,
+  RunStartEvent,
+  RunCompleteEvent,
+  RunFailEvent,
+  RunProgressEvent,
+  StepStartEvent,
+  StepCompleteEvent,
+  StepFailEvent,
+  LogWriteEvent,
+  WorkerErrorEvent,
+
+  // Server
+  DurablyHandler,
+  TriggerRequest,
+  TriggerResponse,
+
+  // Database (advanced)
+  Database,
+  RunsTable,
+  StepsTable,
+  LogsTable,
 } from '@coji/durably'
 ```
diff --git a/website/api/step.md b/website/api/step.md
index a1164164..bf7f7e4e 100644
--- a/website/api/step.md
+++ b/website/api/step.md
@@ -90,14 +90,6 @@ The unique identifier of the current run.
 const id: string = step.runId
 ```
 
-### `stepIndex`
-
-The current step index (0-based).
-
-```ts
-const index: number = step.stepIndex
-```
-
 ## Example
 
 ```ts
diff --git a/website/guide/background-sync.md b/website/guide/background-sync.md
new file mode 100644
index 00000000..a3a05cc5
--- /dev/null
+++ b/website/guide/background-sync.md
@@ -0,0 +1,229 @@
+# Background Sync (Server)
+
+Run batch jobs on Node.js without a frontend. Perfect for cron jobs, data pipelines, and CLI tools.
+
+**Example code:** [server-node](https://github.com/coji/durably/tree/main/examples/server-node)
+
+## When to Use
+
+- Scheduled batch processing (cron)
+- Data import/export pipelines
+- CLI tools with resumable operations
+- Microservice background workers
+
+## Installation
+
+```bash
+npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
+```
+
+## Project Structure
+
+```txt
+├── jobs/
+│   └── process-image.ts    # Job definition
+├── lib/
+│   ├── database.ts         # Database dialect
+│   └── durably.ts          # Durably instance
+└── basic.ts                # Entry point
+```
+
+## Setup
+
+### Database
+
+```ts
+// lib/database.ts
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+
+export const dialect = new LibsqlDialect({
+  url: process.env.TURSO_DATABASE_URL ?? 'file:local.db',
+  authToken: process.env.TURSO_AUTH_TOKEN,
+})
+```
+
+### Job Definition
+
+```ts
+// jobs/process-image.ts
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const processImageJob = defineJob({
+  name: 'process-image',
+  input: z.object({ filename: z.string() }),
+  output: z.object({ url: z.string() }),
+  run: async (step, payload) => {
+    // Step 1: Download
+    const data = await step.run('download', async () => {
+      await delay(500)
+      return { size: 1024000 }
+    })
+
+    // Step 2: Resize
+    await step.run('resize', async () => {
+      await delay(500)
+      return { width: 800, height: 600, size: data.size / 2 }
+    })
+
+    // Step 3: Upload
+    const uploaded = await step.run('upload', async () => {
+      await delay(500)
+      return { url: `https://cdn.example.com/${payload.filename}` }
+    })
+
+    return { url: uploaded.url }
+  },
+})
+```
+
+### Durably Instance
+
+```ts
+// lib/durably.ts
+import { createDurably } from '@coji/durably'
+import { processImageJob } from '../jobs/process-image'
+import { dialect } from './database'
+
+export const durably = createDurably({
+  dialect,
+  pollingInterval: 100,
+  heartbeatInterval: 500,
+  staleThreshold: 3000,
+}).register({
+  processImage: processImageJob,
+})
+```
+
+## Basic Usage
+
+```ts
+// basic.ts
+import { durably } from './lib/durably'
+
+async function main() {
+  await durably.init()
+
+  // Trigger job and wait for completion
+  const { id, output } = await durably.jobs.processImage.triggerAndWait({
+    filename: 'photo.jpg',
+  })
+  console.log(`Run ${id} completed`)
+  console.log(`Output: ${JSON.stringify(output)}`)
+
+  // Cleanup
+  await durably.stop()
+  await durably.db.destroy()
+}
+
+main().catch(console.error)
+```
+
+## Event Monitoring
+
+```ts
+durably.on('run:start', (event) => {
+  console.log(`[run:start] ${event.jobName}`)
+})
+
+durably.on('step:complete', (event) => {
+  console.log(`[step:complete] ${event.stepName}`)
+})
+
+durably.on('run:complete', (event) => {
+  console.log(`[run:complete] output=${JSON.stringify(event.output)} duration=${event.duration}ms`)
+})
+
+durably.on('run:fail', (event) => {
+  console.log(`[run:fail] ${event.error}`)
+})
+```
+
+## Cron Integration
+
+```ts
+// cron-job.ts
+import cron from 'node-cron'
+import { durably } from './lib/durably'
+
+await durably.init()
+
+// Run every hour
+cron.schedule('0 * * * *', async () => {
+  await durably.jobs.processImage.trigger({ filename: 'scheduled.jpg' })
+})
+
+// Keep process running
+```
+
+## CLI with Progress
+
+```ts
+// cli.ts
+import { program } from 'commander'
+import { durably } from './lib/durably'
+
+program
+  .command('process ')
+  .action(async (filename) => {
+    await durably.init()
+
+    durably.on('run:progress', ({ progress }) => {
+      process.stdout.write(`\r${progress.current}/${progress.total} - ${progress.message}`)
+    })
+
+    const { output } = await durably.jobs.processImage.triggerAndWait({ filename })
+    console.log(`\nDone: ${output.url}`)
+
+    await durably.stop()
+  })
+
+program.parse()
+```
+
+## Idempotency
+
+Prevent duplicate runs with idempotency keys:
+
+```ts
+await durably.jobs.processImage.trigger(
+  { filename: 'photo.jpg' },
+  { idempotencyKey: `process-${new Date().toISOString().slice(0, 10)}` }
+)
+// Same key = returns existing run instead of creating new one
+```
+
+## Concurrency Control
+
+Limit concurrent jobs:
+
+```ts
+await durably.jobs.processImage.trigger(
+  { filename: 'photo.jpg' },
+  { concurrencyKey: 'image-processing' }
+)
+// Only one job with this key runs at a time
+```
+
+## Error Handling & Retry
+
+```ts
+// Manual retry on failure
+const run = await durably.storage.getRun(runId)
+if (run?.status === 'failed') {
+  await durably.retry(runId)
+}
+
+// Or cancel a running job
+if (run?.status === 'running') {
+  await durably.cancel(runId)
+}
+```
+
+## Next Steps
+
+- [CSV Import](/guide/csv-import) — Add a React UI
+- [Events Reference](/api/events) — All event types
+- [API Reference](/api/create-durably) — Full configuration options
diff --git a/website/guide/browser-only.md b/website/guide/browser-only.md
deleted file mode 100644
index a54bc8a1..00000000
--- a/website/guide/browser-only.md
+++ /dev/null
@@ -1,148 +0,0 @@
-# Browser-Only
-
-Run Durably entirely in the browser without a server. Jobs execute in the browser using SQLite WASM with OPFS for persistence.
-
-## When to Use
-
-- Offline-capable applications
-- Local-first apps where data stays on the user's device
-- Prototyping without backend infrastructure
-
-## Installation
-
-```bash
-npm install @coji/durably-react @coji/durably kysely zod sqlocal
-```
-
-## Requirements
-
-### Secure Context
-
-Browser-only mode requires a [Secure Context](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) (HTTPS or localhost) for OPFS access.
-
-### COOP/COEP Headers
-
-SQLite WASM requires cross-origin isolation:
-
-```http
-Cross-Origin-Embedder-Policy: require-corp
-Cross-Origin-Opener-Policy: same-origin
-```
-
-**Vite Configuration:**
-
-```ts
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    {
-      name: 'configure-response-headers',
-      configureServer: (server) => {
-        server.middlewares.use((_req, res, next) => {
-          res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
-          res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
-          next()
-        })
-      },
-    },
-  ],
-  worker: {
-    format: 'es',
-  },
-  optimizeDeps: {
-    exclude: ['sqlocal'],
-  },
-})
-```
-
-## Usage
-
-```tsx
-import { DurablyProvider, useJob } from '@coji/durably-react'
-import { createDurably, defineJob } from '@coji/durably'
-import { SQLocalKysely } from 'sqlocal/kysely'
-import { z } from 'zod'
-
-// Define job outside component
-const syncJobDef = defineJob({
-  name: 'sync-data',
-  input: z.object({ userId: z.string() }),
-  output: z.object({ count: z.number() }),
-  run: async (step, payload) => {
-    const data = await step.run('fetch', () => api.fetch(payload.userId))
-    await step.run('save', () => db.save(data))
-    return { count: data.length }
-  },
-})
-
-// Create and configure Durably instance
-async function createBrowserDurably() {
-  const { dialect } = new SQLocalKysely('app.sqlite3')
-  const durably = createDurably({ dialect })
-  durably.register({ syncData: syncJobDef })
-  await durably.migrate()
-  return durably
-}
-
-// Create a promise that resolves to the durably instance
-const durablyPromise = createBrowserDurably()
-
-function SyncButton() {
-  const { trigger, status, output, error, progress, isRunning, isCompleted } =
-    useJob(syncJobDef)
-
-  return (
-    
          
-      
-
-      {progress && (
-        
          
-          Progress: {progress.current}/{progress.total}
-        
          
-      )}
-
-      {isCompleted && 
          Synced {output?.count} items
          }
-      {error && 
          Error: {error}
          }
-    
          
-  )
-}
-
-function App() {
-  return (
-    Loading...
          }>
-      
-              
-  )
-}
-```
-
-## Available Hooks
-
-| Hook | Description |
-|------|-------------|
-| `useJob` | Trigger and monitor a job with real-time status, progress, and logs |
-| `useJobRun` | Subscribe to an existing run by ID |
-| `useJobLogs` | Subscribe to logs from a run with optional limit |
-| `useDurably` | Access the Durably instance directly |
-
-See the [API Reference](/api/durably-react) for detailed documentation.
-
-## Limitations
-
-- **Single tab**: OPFS has exclusive access - only one tab can use the database
-- **Storage limits**: Browser storage quotas apply
-- **No background sync**: Jobs only run when the tab is active
-
-## Tab Suspension
-
-Browsers can suspend inactive tabs. Durably handles this automatically:
-
-1. Tab becomes inactive → heartbeat stops
-2. Job is marked stale after `staleThreshold`
-3. Tab becomes active → worker restarts
-4. Stale job is picked up and resumed
diff --git a/website/guide/concepts.md b/website/guide/concepts.md
new file mode 100644
index 00000000..d70d6297
--- /dev/null
+++ b/website/guide/concepts.md
@@ -0,0 +1,164 @@
+# Core Concepts
+
+Deep dive into Durably's architecture and behavior.
+
+## Jobs
+
+Jobs are defined with `defineJob()` and registered with `durably.register()`:
+
+```ts
+const myJob = defineJob({
+  name: 'my-job',
+  input: z.object({ id: z.string() }),
+  output: z.object({ result: z.string() }),
+  run: async (step, payload) => {
+    // Job implementation
+    return { result: 'done' }
+  },
+})
+
+const { myJob: job } = durably.register({ myJob })
+```
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `name` | Yes | Unique job identifier |
+| `input` | Yes | Zod schema for payload |
+| `output` | No | Zod schema for return value |
+| `run` | Yes | The job function |
+
+### Job Lifecycle
+
+![Job Lifecycle](/images/job-lifecycle.svg)
+
+## Steps
+
+Steps are checkpoints created with `step.run()`:
+
+```ts
+const result = await step.run('step-name', async () => {
+  return someValue  // Persisted to SQLite
+})
+```
+
+**First run:** Executes function, persists result.
+**Subsequent runs:** Returns cached result instantly.
+
+### Step Names Must Be Unique
+
+```ts
+// Good
+await step.run('fetch-user', () => fetchUser())
+await step.run('update-profile', () => updateProfile())
+
+// Bad - duplicate names
+await step.run('step', () => doA())
+await step.run('step', () => doB())  // Returns cached result from doA!
+```
+
+### Break Large Operations into Steps
+
+```ts
+// Bad - crash loses all progress
+await step.run('import-all', async () => {
+  for (const row of rows) await db.insert(row)
+})
+
+// Good - checkpoint per batch
+for (let i = 0; i < rows.length; i += 100) {
+  await step.run(`batch-${i}`, async () => {
+    for (const row of rows.slice(i, i + 100)) {
+      await db.insert(row)
+    }
+  })
+}
+```
+
+## Resumability
+
+### How It Works
+
+1. Each `step.run()` saves its result to SQLite
+2. If process crashes, restart picks up the job
+3. Completed steps return cached results
+4. Execution continues from next incomplete step
+
+```ts
+// First run
+const data = await step.run('fetch', () => api.fetch())  // Runs, saves
+await step.run('process', () => process(data))           // Crashes!
+
+// After restart
+const data = await step.run('fetch', () => api.fetch())  // Returns cached
+await step.run('process', () => process(data))           // Runs
+```
+
+### Heartbeat Mechanism
+
+Running jobs send heartbeats to indicate they're alive:
+
+```ts
+createDurably({
+  dialect,
+  heartbeatInterval: 5000,   // Send heartbeat every 5s
+  staleThreshold: 30000,     // Mark stale after 30s without heartbeat
+})
+```
+
+When a job's heartbeat expires, it's reset to `pending` and picked up again.
+
+### Idempotency
+
+Steps may re-run on failure. Design for safe retries:
+
+```ts
+// Good: Upsert instead of insert
+await step.run('save', () => db.upsert(user))
+
+// Good: Idempotency key with external APIs
+await step.run('charge', () =>
+  stripe.charges.create({
+    amount: 1000,
+    idempotency_key: `order_${orderId}`,
+  })
+)
+```
+
+## Trigger Options
+
+### Idempotency Key
+
+Prevent duplicate runs:
+
+```ts
+await job.trigger({ id: '123' }, {
+  idempotencyKey: 'request-abc'
+})
+// Same key returns existing run
+```
+
+### Concurrency Key
+
+Limit concurrent execution:
+
+```ts
+await job.trigger({ userId: '123' }, {
+  concurrencyKey: 'user_123'
+})
+// Only one job per key runs at a time
+```
+
+## Events
+
+Monitor job execution:
+
+```ts
+durably.on('run:start', ({ runId, jobName }) => { ... })
+durably.on('run:progress', ({ runId, progress }) => { ... })
+durably.on('run:complete', ({ runId, output }) => { ... })
+durably.on('run:fail', ({ runId, error }) => { ... })
+durably.on('step:start', ({ runId, stepName }) => { ... })
+durably.on('step:complete', ({ runId, stepName, output }) => { ... })
+```
+
+See [Events API](/api/events) for the full list.
diff --git a/website/guide/csv-import.md b/website/guide/csv-import.md
new file mode 100644
index 00000000..046bb377
--- /dev/null
+++ b/website/guide/csv-import.md
@@ -0,0 +1,240 @@
+# CSV Import (Full-Stack)
+
+A complete CSV import system with progress UI, run history, and job management.
+
+**Example code:** [fullstack-react-router](https://github.com/coji/durably/tree/main/examples/fullstack-react-router)
+
+## What You'll Build
+
+- CSV file upload with server-side parsing
+- Real-time progress bar via SSE
+- Run history dashboard with retry/cancel/delete
+- Type-safe client hooks
+
+## Architecture
+
+![Full-Stack Architecture](/images/fullstack-architecture.svg)
+
+## Project Structure
+
+```txt
+app/
+├── jobs/
+│   └── import-csv.ts          # Job definition
+├── lib/
+│   ├── durably.server.ts      # Durably instance
+│   └── durably.client.ts      # Type-safe hooks
+├── routes/
+│   ├── api.durably.$.ts       # Splat route for all API
+│   └── _index.tsx             # UI
+```
+
+## Key Code
+
+### Job Definition
+
+```ts
+// app/jobs/import-csv.ts
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+const csvRowSchema = z.object({
+  id: z.number(),
+  name: z.string(),
+  email: z.string(),
+  amount: z.number(),
+})
+
+const outputSchema = z.object({ imported: z.number(), failed: z.number() })
+
+/** Output type for use in components */
+export type ImportCsvOutput = z.infer
+
+export const importCsvJob = defineJob({
+  name: 'import-csv',
+  input: z.object({
+    filename: z.string(),
+    rows: z.array(csvRowSchema),
+  }),
+  output: outputSchema,
+  run: async (step, payload) => {
+    step.log.info(`Starting import of ${payload.filename} (${payload.rows.length} rows)`)
+
+    // Step 1: Validate all rows
+    const validRows = await step.run('validate', async () => {
+      const valid: typeof payload.rows = []
+      const invalid: { row: (typeof payload.rows)[0]; reason: string }[] = []
+
+      for (let i = 0; i < payload.rows.length; i++) {
+        const row = payload.rows[i]
+        step.progress(i + 1, payload.rows.length, `Validating ${row.name}...`)
+        await delay(50)
+
+        if (row.amount < 0) {
+          invalid.push({ row, reason: `Invalid amount: ${row.amount}` })
+          step.log.warn(`Validation failed for ${row.name}: negative amount`)
+        } else {
+          valid.push(row)
+        }
+      }
+
+      step.log.info(`Validation complete: ${valid.length} valid, ${invalid.length} invalid`)
+      return { valid, invalidCount: invalid.length }
+    })
+
+    // Step 2: Import valid rows
+    const importResult = await step.run('import', async () => {
+      let imported = 0
+
+      for (let i = 0; i < validRows.valid.length; i++) {
+        const row = validRows.valid[i]
+        step.progress(i + 1, validRows.valid.length, `Importing ${row.name}...`)
+        await delay(80)
+
+        // Simulate import
+        imported++
+        step.log.info(`Imported: ${row.name} (${row.email}) - $${row.amount}`)
+      }
+
+      return { imported }
+    })
+
+    // Step 3: Finalize
+    await step.run('finalize', async () => {
+      step.progress(1, 1, 'Finalizing...')
+      await delay(200)
+      step.log.info('Import finalized')
+    })
+
+    return {
+      imported: importResult.imported,
+      failed: validRows.invalidCount,
+    }
+  },
+})
+```
+
+### Server Setup
+
+```ts
+// app/lib/durably.server.ts
+import { createDurably, createDurablyHandler } from '@coji/durably'
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+import { createClient } from '@libsql/client'
+import { importCsvJob } from '~/jobs/import-csv'
+
+const client = createClient({ url: 'file:local.db' })
+const dialect = new LibsqlDialect({ client })
+
+export const durably = createDurably({ dialect }).register({
+  importCsv: importCsvJob,
+})
+
+export const durablyHandler = createDurablyHandler(durably)
+
+await durably.init()
+```
+
+### API Route (Splat)
+
+```ts
+// app/routes/api.durably.$.ts
+import { durablyHandler } from '~/lib/durably.server'
+import type { Route } from './+types/api.durably.$'
+
+export async function loader({ request }: Route.LoaderArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+```
+
+### Type-Safe Client
+
+```ts
+// app/lib/durably.client.ts
+import { createDurablyClient } from '@coji/durably-react/client'
+import type { durably } from './durably.server'
+
+export const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+```
+
+### Progress UI
+
+```tsx
+function ImportProgress({ runId }: { runId: string | null }) {
+  const { progress, output, isRunning, isCompleted, isFailed, error } =
+    durablyClient.importCsv.useRun(runId)
+
+  if (!runId) return null
+
+  return (
+    
          
+      {isRunning && progress && (
+        <>
+          
+          
          {progress.message}
          
+        
+      )}
+      {isCompleted && (
+        
          Imported {output?.imported}, failed {output?.failed}
          
+      )}
+      {isFailed && 
          Error: {error}
          }
+    
          
+  )
+}
+```
+
+### Dashboard with Actions
+
+```tsx
+import { useRuns, useRunActions } from '@coji/durably-react/client'
+
+function Dashboard() {
+  const { runs, refresh } = useRuns({ api: '/api/durably' })
+  const { retry, cancel, deleteRun } = useRunActions({ api: '/api/durably' })
+
+  return (
+    
+      {runs.map(run => (
+        
+          
+          
+          
+        
+      ))}
+    
          {run.jobName}{run.status}
+            {run.status === 'failed' && (
+              
+            )}
+            {run.status === 'running' && (
+              
+            )}
+          
          
+  )
+}
+```
+
+## Resumability
+
+If the server crashes mid-import:
+
+1. Restart the server
+2. `durably.init()` picks up the stale run
+3. Completed steps return cached results
+4. Import continues from the next step
+
+## Next Steps
+
+- [Offline App](/guide/offline-app) — Run in the browser without a server
+- [API Reference](/api/durably-react/) — All hooks and options
diff --git a/website/guide/deployment.md b/website/guide/deployment.md
deleted file mode 100644
index f267cd23..00000000
--- a/website/guide/deployment.md
+++ /dev/null
@@ -1,147 +0,0 @@
-# Deployment
-
-Durably requires a long-running process to poll for and execute jobs. This guide covers deployment options and limitations.
-
-## Requirements
-
-Durably workers need:
-
-- **Persistent process**: A process that runs continuously to poll for jobs
-- **SQLite access**: Either local file, Turso cloud, or browser OPFS
-- **No request timeouts**: Jobs may run for minutes or hours
-
-## Recommended Platforms
-
-### Fly.io
-
-Deploy as a long-running process:
-
-```dockerfile
-FROM node:20-slim
-WORKDIR /app
-COPY package*.json ./
-RUN npm install
-COPY . .
-CMD ["node", "worker.js"]
-```
-
-```toml
-# fly.toml
-[processes]
-  worker = "node worker.js"
-```
-
-### Railway
-
-Works out of the box with standard Node.js deployment. Set up a separate worker service or run alongside your web server.
-
-### Docker / VPS
-
-Any environment that supports long-running Node.js processes:
-
-```bash
-# PM2
-pm2 start worker.js --name durably-worker
-
-# systemd
-[Service]
-ExecStart=/usr/bin/node /app/worker.js
-Restart=always
-```
-
-### Render
-
-Use a "Background Worker" service type, not a "Web Service".
-
-## Not Recommended
-
-### Serverless Functions
-
-Durably is **not compatible** with serverless environments:
-
-| Platform | Limitation |
-|----------|------------|
-| Vercel Functions | 10s-300s timeout |
-| Cloudflare Workers | 30s CPU time limit |
-| AWS Lambda | 15min max timeout |
-| Netlify Functions | 10s-26s timeout |
-
-**Why it doesn't work:**
-
-1. **Polling model**: Durably continuously polls for pending jobs
-2. **Long-running jobs**: Steps may take minutes to complete
-3. **Cold starts**: Each invocation starts fresh, breaking continuity
-4. **Cost**: Constant polling would be expensive on pay-per-invocation models
-
-### Workarounds (Advanced)
-
-If you must use serverless for triggering jobs, you can:
-
-1. **Trigger only**: Use serverless to call `job.trigger()` and store jobs in Turso
-2. **Separate worker**: Run the actual worker on a long-running platform
-
-```ts
-// Vercel API route - trigger only
-export async function POST(req: Request) {
-  const payload = await req.json()
-  await myJob.trigger(payload) // Just inserts into DB
-  return Response.json({ status: 'queued' })
-}
-
-// Fly.io worker - processes jobs
-durably.start() // Long-running polling
-```
-
-## Browser Deployment
-
-For browser-based workers (using SQLite WASM with OPFS):
-
-- Host your static site anywhere (Vercel, Netlify, GitHub Pages)
-- The worker runs entirely in the user's browser
-- Data persists in OPFS (Origin Private File System)
-- Requires HTTPS (Secure Context) and COOP/COEP headers
-
-See [Browser-Only Guide](/guide/browser-only) for details.
-
-## Database Considerations
-
-### Turso (Recommended for Production)
-
-- Hosted SQLite-compatible database
-- Works from any platform (including serverless for triggers)
-- Built-in replication and backups
-
-### Local SQLite
-
-- Works for single-server deployments
-- Use persistent volumes on containerized platforms
-- Not suitable for horizontal scaling
-
-## Health Checks
-
-Monitor your worker with events:
-
-```ts
-durably.on('run:complete', (event) => {
-  metrics.increment('jobs.completed')
-})
-
-durably.on('run:fail', (event) => {
-  metrics.increment('jobs.failed')
-  alerting.notify(event.error)
-})
-```
-
-## Graceful Shutdown
-
-Always handle shutdown signals:
-
-```ts
-process.on('SIGTERM', async () => {
-  console.log('Shutting down...')
-  await durably.stop()
-  process.exit(0)
-})
-```
-
-This ensures in-progress jobs complete their current step before stopping.
diff --git a/website/guide/events.md b/website/guide/events.md
deleted file mode 100644
index 969b6566..00000000
--- a/website/guide/events.md
+++ /dev/null
@@ -1,143 +0,0 @@
-# Events
-
-Durably provides an event system to monitor job execution.
-
-::: tip
-Examples on this page assume you have a `durably` instance created via `createDurably()`. See [Getting Started](/guide/getting-started) for setup.
-:::
-
-## Available Events
-
-| Event | Description | Payload |
-|-------|-------------|---------|
-| `run:start` | Job execution started | `{ runId, jobName, input }` |
-| `run:complete` | Job completed successfully | `{ runId, jobName, output }` |
-| `run:fail` | Job failed with error | `{ runId, jobName, error }` |
-| `run:progress` | Progress updated | `{ runId, jobName, progress }` |
-| `step:start` | Step execution started | `{ runId, stepName, stepIndex }` |
-| `step:complete` | Step completed | `{ runId, stepName, stepIndex, output }` |
-| `step:skip` | Step skipped (cached) | `{ runId, stepName, stepIndex, output }` |
-| `log:write` | Log message written | `{ runId, level, message }` |
-
-## Subscribing to Events
-
-Use `durably.on()` to subscribe:
-
-```ts
-// Single event
-const unsubscribe = durably.on('run:complete', (event) => {
-  console.log(`Job ${event.jobName} completed:`, event.output)
-})
-
-// Multiple events
-durably.on('run:start', (e) => console.log('Started:', e.jobName))
-durably.on('run:fail', (e) => console.error('Failed:', e.error))
-durably.on('step:complete', (e) => console.log('Step done:', e.stepName))
-```
-
-## Unsubscribing
-
-The `on()` method returns an unsubscribe function:
-
-```ts
-const unsubscribe = durably.on('run:complete', handler)
-
-// Later...
-unsubscribe()
-```
-
-## React Integration
-
-Events are useful for updating UI state:
-
-```tsx
-function useDurably() {
-  const [status, setStatus] = useState<'idle' | 'running' | 'done'>('idle')
-  const [currentStep, setCurrentStep] = useState(null)
-
-  useEffect(() => {
-    const unsubscribes = [
-      durably.on('run:start', () => setStatus('running')),
-      durably.on('run:complete', () => {
-        setStatus('done')
-        setCurrentStep(null)
-      }),
-      durably.on('step:complete', (e) => setCurrentStep(e.stepName)),
-    ]
-
-    return () => unsubscribes.forEach((fn) => fn())
-  }, [])
-
-  return { status, currentStep }
-}
-```
-
-## Logging
-
-Use `step.log` within jobs to emit log events:
-
-```ts
-import { defineJob } from '@coji/durably'
-
-const myJob = durably.register(
-  defineJob({
-    name: 'my-job',
-    input: z.object({}),
-    run: async (step) => {
-      step.log.info('Starting processing')
-
-      await step.run('step1', async () => {
-        step.log.info('Step 1 details', { someData: 123 })
-        return result
-      })
-
-      step.log.info('Completed')
-    },
-  }),
-)
-
-// Subscribe to logs
-durably.on('log:write', (event) => {
-  console.log(`[${event.level}] ${event.message}`)
-})
-```
-
-## Event-Driven Patterns
-
-### Progress Tracking
-
-```ts
-let totalSteps = 5
-let completedSteps = 0
-
-durably.on('step:complete', () => {
-  completedSteps++
-  updateProgressBar(completedSteps / totalSteps * 100)
-})
-```
-
-### Metrics Collection
-
-```ts
-const metrics = {
-  jobsCompleted: 0,
-  jobsFailed: 0,
-  avgDuration: 0,
-}
-
-const startTimes = new Map()
-
-durably.on('run:start', (e) => {
-  startTimes.set(e.runId, Date.now())
-})
-
-durably.on('run:complete', (e) => {
-  metrics.jobsCompleted++
-  const duration = Date.now() - startTimes.get(e.runId)
-  // Update average...
-})
-
-durably.on('run:fail', () => {
-  metrics.jobsFailed++
-})
-```
diff --git a/website/guide/full-stack.md b/website/guide/full-stack.md
deleted file mode 100644
index 0edba11c..00000000
--- a/website/guide/full-stack.md
+++ /dev/null
@@ -1,257 +0,0 @@
-# Full-Stack
-
-Run jobs on the server and monitor them from a React frontend. The server handles job execution while the client provides real-time status updates via SSE.
-
-This guide uses [React Router v7](https://reactrouter.com/) as the full-stack framework.
-
-## When to Use
-
-- Web applications with long-running background jobs
-- Apps that need reliable server-side execution
-- When you want to show job progress in a React UI
-
-## Architecture
-
-```txt
-┌─────────────────┐     HTTP/SSE     ┌─────────────────┐
-│  React Client   │ ◄──────────────► │  React Router   │
-│  (durably hooks)│                  │  Server (Durably)│
-└─────────────────┘                  └─────────────────┘
-```
-
-## Installation
-
-```bash
-npm install @coji/durably @coji/durably-react kysely zod @libsql/client @libsql/kysely-libsql
-```
-
-## Project Structure
-
-```txt
-app/
-├── lib/
-│   ├── durably.server.ts # Durably instance and jobs (server-only)
-│   └── durably.client.ts # Type-safe client hooks (client-only)
-├── routes/
-│   ├── api.durably.trigger.ts   # POST /api/durably/trigger
-│   ├── api.durably.subscribe.ts # GET /api/durably/subscribe
-│   └── _index.tsx        # Upload form with action
-```
-
-## Setup
-
-### 1. Server (`durably.server.ts`)
-
-```ts
-// app/lib/durably.server.ts
-import { createDurably, defineJob } from '@coji/durably'
-import { createDurablyHandler } from '@coji/durably/server'
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-import { createClient } from '@libsql/client'
-import { z } from 'zod'
-
-const client = createClient({ url: 'file:local.db' })
-const dialect = new LibsqlDialect({ client })
-
-export const durably = createDurably({ dialect })
-export const handler = createDurablyHandler(durably)
-
-// Define jobs
-const importCsvJob = defineJob({
-  name: 'importCsv',
-  input: z.object({ rows: z.array(z.record(z.string())) }),
-  output: z.object({ imported: z.number(), skipped: z.number() }),
-  run: async (step, payload) => {
-    let imported = 0
-    let skipped = 0
-
-    for (let i = 0; i < payload.rows.length; i++) {
-      await step.run(`import-row-${i}`, async () => {
-        try {
-          await db.insert('users', payload.rows[i])
-          imported++
-        } catch {
-          skipped++
-        }
-      })
-      step.progress(i + 1, payload.rows.length)
-    }
-
-    return { imported, skipped }
-  },
-})
-
-// Register jobs
-export const jobs = durably.register({
-  importCsv: importCsvJob,
-  // Add more jobs here:
-  // syncUsers: syncUsersJob,
-})
-
-// Initialize on server start
-await durably.migrate()
-durably.start()
-```
-
-### 2. Client (`durably.client.ts`)
-
-Create a type-safe client once, import the jobs type using `import type`:
-
-```ts
-// app/lib/durably.client.ts
-import { createDurablyClient } from '@coji/durably-react/client'
-import type { jobs } from '~/lib/durably.server'
-
-export const durably = createDurablyClient({
-  api: '/api/durably',
-})
-```
-
-### 3. API Routes
-
-**Trigger Route:**
-
-```ts
-// app/routes/api.durably.trigger.ts
-import type { Route } from './+types/api.durably.trigger'
-import { handler } from '~/lib/durably.server'
-
-export async function action({ request }: Route.ActionArgs) {
-  return handler.trigger(request)
-}
-```
-
-**Subscribe Route (SSE):**
-
-```ts
-// app/routes/api.durably.subscribe.ts
-import type { Route } from './+types/api.durably.subscribe'
-import { handler } from '~/lib/durably.server'
-
-export async function loader({ request }: Route.LoaderArgs) {
-  return handler.subscribe(request)
-}
-```
-
-## Usage
-
-### Server-Side Trigger (Form with action)
-
-```tsx
-// app/routes/_index.tsx
-import { Form } from 'react-router'
-import type { Route } from './+types/_index'
-import { jobs } from '~/lib/durably.server'
-import { durably } from '~/lib/durably.client'
-
-function parseCSV(text: string): Record[] {
-  const lines = text.trim().split('\n')
-  const headers = lines[0].split(',')
-  return lines.slice(1).map((line) => {
-    const values = line.split(',')
-    return Object.fromEntries(headers.map((h, i) => [h, values[i]]))
-  })
-}
-
-export async function action({ request }: Route.ActionArgs) {
-  const formData = await request.formData()
-  const file = formData.get('file') as File
-  const text = await file.text()
-  const rows = parseCSV(text)
-
-  const { runId } = await jobs.importCsv.trigger({ rows })
-  return { runId }
-}
-
-export default function CsvImporter({ actionData }: Route.ComponentProps) {
-  const { progress, output, error, isRunning, isCompleted, isFailed } =
-    durably.importCsv.useRun(actionData?.runId ?? null)
-
-  return (
-    
          
-      
          
-        
-        
-      
          
-
-      {progress && (
-        
          
-          
-          
          {progress.current} / {progress.total} rows
          
-        
          
-      )}
-
-      {isCompleted && (
-        
          Done! Imported {output?.imported}, skipped {output?.skipped}
          
-      )}
-      {isFailed && 
          Error: {error}
          }
-    
          
-  )
-}
-```
-
-### Client-Side Trigger
-
-For cases where you trigger from the client:
-
-```tsx
-import { durably } from '~/lib/durably.client'
-
-function SimpleImporter() {
-  const { trigger, progress, isRunning, isCompleted, output } =
-    durably.importCsv.useJob()
-
-  const handleFileChange = async (e: React.ChangeEvent) => {
-    const file = e.target.files?.[0]
-    if (!file) return
-
-    const text = await file.text()
-    const rows = parseCSV(text)
-    trigger({ rows }) // Fully type-safe with autocomplete!
-  }
-
-  return (
-    
          
-      
-      {isRunning && 
          Progress: {progress?.current}/{progress?.total}
          }
-      {isCompleted && 
          Imported {output?.imported} rows
          }
-    
          
-  )
-}
-```
-
-### Subscribe to Logs
-
-```tsx
-import { durably } from '~/lib/durably.client'
-
-function ImportLogs({ runId }: { runId: string }) {
-  const { logs, clearLogs } = durably.importCsv.useLogs(runId, { maxLogs: 100 })
-
-  return (
-    
          
-      
-      
            
-        {logs.map((log) => (
-          
          • 
-            [{log.level}] {log.message}
-          
            • 
-        ))}
-      
          
-    
          
-  )
-}
-```
-
-## API Reference
-
-| Function                             | Description                          |
-| ------------------------------------ | ------------------------------------ |
-| `createDurablyClient()` | Create type-safe client for all jobs |
-| `durably.jobName.useJob()`           | Trigger and monitor a job            |
-| `durably.jobName.useRun(runId)`      | Subscribe to an existing run         |
-| `durably.jobName.useLogs(runId)`     | Subscribe to logs from a run         |
-
-See the [API Reference](/api/durably-react#server-connected-mode) for detailed documentation.
diff --git a/website/guide/getting-started.md b/website/guide/getting-started.md
index f561c785..006586a4 100644
--- a/website/guide/getting-started.md
+++ b/website/guide/getting-started.md
@@ -1,89 +1,165 @@
 # Getting Started
 
-## Choose Your Setup
+Build a CSV importer with real-time progress UI. This guide uses React Router v7 for full-stack development.
 
-| Setup | Description | Guide |
-|-------|-------------|-------|
-| **Server** | Run jobs on Node.js server | [→](/guide/server) |
-| **Full-Stack** | Server execution + React UI for monitoring | [→](/guide/full-stack) |
-| **Browser-Only** | Run entirely in the browser (no server) | [→](/guide/browser-only) |
+![Getting Started Overview](/images/getting-started-overview.svg)
 
-## Quick Start (Server)
-
-The simplest way to get started.
-
-### 1. Install
+## Install
 
 ```bash
-npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
+npm install @coji/durably @coji/durably-react kysely zod @libsql/client @libsql/kysely-libsql
 ```
 
-### 2. Define a Job
+## 1. Define a Job (Server)
 
 ```ts
-// jobs.ts
-import { createDurably, defineJob } from '@coji/durably'
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-import { createClient } from '@libsql/client'
+// app/jobs/import-csv.ts
+import { defineJob } from '@coji/durably'
 import { z } from 'zod'
 
-// Create Durably instance
-const client = createClient({ url: 'file:local.db' })
-const dialect = new LibsqlDialect({ client })
-const durably = createDurably({ dialect })
-
-// Define a CSV import job
-const importCsvJob = defineJob({
+export const importCsvJob = defineJob({
   name: 'import-csv',
-  input: z.object({ filePath: z.string() }),
-  output: z.object({ count: z.number() }),
+  input: z.object({
+    filename: z.string(),
+    rows: z.array(z.object({
+      name: z.string(),
+      email: z.string(),
+    })),
+  }),
+  output: z.object({ imported: z.number() }),
   run: async (step, payload) => {
-    // Step 1: Parse CSV
-    const rows = await step.run('parse', async () => {
-      const fs = await import('fs/promises')
-      const csv = await fs.readFile(payload.filePath, 'utf-8')
-      return csv.split('\n').slice(1).map((line) => line.split(','))
+    step.log.info(`Starting import of ${payload.filename}`)
+
+    // Step 1: Validate
+    const validRows = await step.run('validate', async () => {
+      step.progress(1, 3, 'Validating...')
+      return payload.rows.filter(row => row.email.includes('@'))
     })
 
-    // Step 2: Import rows
+    // Step 2: Import
     await step.run('import', async () => {
-      // Your database logic here
-      console.log(`Importing ${rows.length} rows`)
+      for (let i = 0; i < validRows.length; i++) {
+        step.progress(i + 1, validRows.length, `Importing ${validRows[i].name}...`)
+        // await db.insert('users', validRows[i])
+      }
     })
 
-    return { count: rows.length }
+    return { imported: validRows.length }
   },
 })
+```
 
-// Register the job
-const { importCsv } = durably.register({
+```ts
+// app/lib/durably.server.ts
+import { createDurably, createDurablyHandler } from '@coji/durably'
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+import { createClient } from '@libsql/client'
+import { importCsvJob } from '~/jobs/import-csv'
+
+const client = createClient({ url: 'file:local.db' })
+const dialect = new LibsqlDialect({ client })
+
+export const durably = createDurably({ dialect }).register({
   importCsv: importCsvJob,
 })
 
-// Initialize and start
-await durably.migrate()
-durably.start()
+export const durablyHandler = createDurablyHandler(durably)
 
-// Trigger a job
-await importCsv.trigger({ filePath: './data/users.csv' })
+await durably.init()
 ```
 
-### 3. Run
+## 2. Create API Route (Splat)
 
-```bash
-npx tsx jobs.ts
+```ts
+// app/routes/api.durably.$.ts
+import { durablyHandler } from '~/lib/durably.server'
+import type { Route } from './+types/api.durably.$'
+
+export async function loader({ request }: Route.LoaderArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
 ```
 
-If the process crashes after step 1, restarting will skip the parse and continue from step 2.
+## 3. Create Type-Safe Client
 
-## Next Steps
+```ts
+// app/lib/durably.client.ts
+import { createDurablyClient } from '@coji/durably-react/client'
+import type { durably } from './durably.server'
+
+export const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+```
 
-Learn the concepts:
-- [Jobs and Steps](/guide/jobs-and-steps) - How jobs and steps work
-- [Resumability](/guide/resumability) - How resumption works
-- [Events](/guide/events) - Monitor job execution
+## 4. Build the UI
+
+```tsx
+// app/routes/_index.tsx
+import { Form, useActionData } from 'react-router'
+import { durably } from '~/lib/durably.server'
+import { durablyClient } from '~/lib/durably.client'
+import type { Route } from './+types/_index'
+
+export async function action({ request }: Route.ActionArgs) {
+  const formData = await request.formData()
+  const file = formData.get('file') as File
+  const text = await file.text()
+  const rows = text.split('\n').slice(1).map(line => {
+    const [name, email] = line.split(',')
+    return { name, email }
+  })
+  const run = await durably.jobs.importCsv.trigger({
+    filename: file.name,
+    rows,
+  })
+  return { runId: run.id }
+}
+
+export default function Home() {
+  const actionData = useActionData()
+  const { progress, output, isRunning, isCompleted } =
+    durablyClient.importCsv.useRun(actionData?.runId ?? null)
+
+  return (
+    
          
+      
          
+        
+        
+      
          
+
+      {progress && (
+        
          Progress: {progress.current}/{progress.total} - {progress.message}
          
+      )}
+      {isCompleted && 
          Done! Imported {output?.imported} rows
          }
+    
          
+  )
+}
+```
+
+## Try It
+
+1. Create a `test.csv`:
+   ```csv
+   name,email
+   Alice,alice@example.com
+   Bob,bob@example.com
+   ```
+
+2. Run: `npm run dev`
+
+3. Upload the CSV and watch real-time progress!
+
+If you stop the server mid-import and restart, it resumes from where it left off.
+
+## Next Steps
 
-Choose your setup:
-- [Server](/guide/server) - Detailed server-side guide
-- [Full-Stack](/guide/full-stack) - React Router v7 + React hooks
-- [Browser-Only](/guide/browser-only) - Browser-only with SQLite WASM
+- **[CSV Import (Full-Stack)](/guide/csv-import)** — Complete tutorial with dashboard
+- **[Offline App (Browser-Only)](/guide/offline-app)** — Run entirely in the browser
+- **[Background Sync (Server)](/guide/background-sync)** — Server-only batch processing
diff --git a/website/guide/index.md b/website/guide/index.md
index b81c29fd..1c91c5c5 100644
--- a/website/guide/index.md
+++ b/website/guide/index.md
@@ -1,80 +1,49 @@
 # What is Durably?
 
-Durably is a **resumable job execution** library for Node.js and browsers. Split long-running tasks into steps, and if interrupted, resume from the last successful step.
+Durably is a **resumable job execution** library for TypeScript. Split long-running tasks into steps — if interrupted, resume from the last successful step.
 
-## Use Cases
+## The Problem
 
-### Long-Running Jobs with Progress UI
+Long-running tasks fail. Networks drop, servers restart, browsers close. Traditional approaches either:
 
-Import a CSV with thousands of rows and show real-time progress in your React app via SSE.
+- **Lose all progress** and restart from scratch
+- **Require complex infrastructure** like Redis queues or cloud services
 
-```tsx
-const { trigger, progress, isRunning } = useJob({
-  api: '/api/durably',
-  jobName: 'import-csv',
-})
-
-// Progress: 500/1000 rows
-```
-
-[Full-Stack Guide →](/guide/full-stack)
+## The Solution
 
-### Data Sync & Batch Processing
+Durably saves each step's result to SQLite. On resume, completed steps return cached results instantly.
 
-Fetch data from APIs, transform, and save. If the process fails midway, it resumes from where it left off.
+![Resumability](/images/resumability.svg)
 
 ```ts
-const importJob = defineJob({
+const job = defineJob({
   name: 'import-csv',
   run: async (step, payload) => {
-    // Step 1: Parse CSV (persisted after completion)
-    const rows = await step.run('parse', () => parseCSV(payload.csv))
+    // Step 1: Parse (cached after first run)
+    const rows = await step.run('parse', () => parseCSV(payload.file))
 
-    // Step 2: Import (skipped if already done)
+    // Step 2: Import each row
     for (const [i, row] of rows.entries()) {
       await step.run(`import-${i}`, () => db.insert(row))
+      step.progress(i + 1, rows.length)
     }
+
+    return { count: rows.length }
   },
 })
 ```
 
-[Server Guide →](/guide/server)
-
-### Offline-Capable Apps
-
-Run Durably entirely in the browser with SQLite WASM. Works offline, survives tab closes.
-
-```tsx
- new SQLocalKysely('app.db').dialect}>
-  
-
-```
-
-[Browser-Only Guide →](/guide/browser-only)
-
-## How It Works
-
-Each `step.run()` persists its result to SQLite. On resume, completed steps return their cached results instantly.
+If the process crashes after importing 500 of 1000 rows, restart picks up at row 501.
 
-```ts
-// First run: executes all steps
-// Second run (after crash): step 1 returns cached result, step 2 executes
-
-const result = await step.run('expensive-api-call', async () => {
-  return await fetch('/api/data').then((r) => r.json())
-})
-```
+## Where It Runs
 
-## Features
+| Environment | Storage | Use Case |
+|-------------|---------|----------|
+| **Node.js** | libsql/better-sqlite3 | Server-side batch jobs |
+| **Browser** | SQLite WASM + OPFS | Offline-capable apps |
 
-- **Step-level persistence** - Each step is a checkpoint
-- **Automatic resumption** - Resume from last successful step
-- **Cross-platform** - Node.js and browsers
-- **TypeScript** - Full type safety with Zod schemas
-- **Minimal dependencies** - Just Kysely and Zod
+Same job definition works in both environments.
 
-## Next Steps
+## Next Step
 
-- [Getting Started](/guide/getting-started) - Install and run your first job
-- [Jobs and Steps](/guide/jobs-and-steps) - Core concepts
-- [Live Demo](https://durably-demo.vercel.app) - Try it in your browser
+**[Getting Started →](/guide/getting-started)** — Build a CSV importer with progress UI in 5 minutes.
diff --git a/website/guide/jobs-and-steps.md b/website/guide/jobs-and-steps.md
deleted file mode 100644
index 57e93b95..00000000
--- a/website/guide/jobs-and-steps.md
+++ /dev/null
@@ -1,126 +0,0 @@
-# Jobs and Steps
-
-## Defining a Job
-
-Jobs are defined using the standalone `defineJob()` function and registered with `durably.register()`:
-
-```ts
-import { createDurably, defineJob } from '@coji/durably'
-import { z } from 'zod'
-
-// Create durably instance (see Getting Started for dialect setup)
-const durably = createDurably({ dialect })
-
-const myJobDef = defineJob({
-  name: 'my-job',
-  input: z.object({ id: z.string() }),
-  output: z.object({ result: z.string() }),
-  run: async (step, payload) => {
-    // Job implementation
-    return { result: 'done' }
-  },
-})
-
-// Register to get a job handle
-const { myJob } = durably.register({
-  myJob: myJobDef,
-})
-```
-
-### Job Options
-
-| Option | Type | Required | Description |
-|--------|------|----------|-------------|
-| `name` | `string` | Yes | Unique job identifier |
-| `input` | `ZodSchema` | Yes | Schema for job payload |
-| `output` | `ZodSchema` | No | Schema for job return value |
-| `run` | `Function` | Yes | The job's run function |
-
-## Creating Steps
-
-Steps are created using `step.run()`:
-
-```ts
-const result = await step.run('step-name', async () => {
-  // Step logic here
-  return someValue
-})
-```
-
-### Step Behavior
-
-1. **First execution**: The function runs and its return value is persisted
-2. **Subsequent executions**: The persisted value is returned without running the function
-3. **Type inference**: The return type is inferred from the function
-
-### Step Names
-
-Step names must be unique within a job:
-
-```ts
-// Good - unique names
-await step.run('fetch-user', async () => { ... })
-await step.run('update-profile', async () => { ... })
-
-// Bad - duplicate names will cause issues
-await step.run('step', async () => { ... })
-await step.run('step', async () => { ... }) // Won't work correctly
-```
-
-## Triggering Jobs
-
-### Basic Trigger
-
-```ts
-await myJob.trigger({ id: 'abc123' })
-```
-
-### With Idempotency Key
-
-Prevent duplicate job runs:
-
-```ts
-await myJob.trigger(
-  { id: 'abc123' },
-  { idempotencyKey: 'unique-request-id' }
-)
-```
-
-### With Concurrency Key
-
-Control concurrent execution:
-
-```ts
-await myJob.trigger(
-  { id: 'abc123' },
-  { concurrencyKey: 'user_123' }
-)
-```
-
-## Job Lifecycle
-
-```
-trigger() → pending → running → completed
-                  ↘           ↗
-                    → failed
-```
-
-1. **pending**: Job is queued, waiting for worker
-2. **running**: Worker is executing the job
-3. **completed**: Job finished successfully
-4. **failed**: Job encountered an error
-
-## Error Handling
-
-Errors in steps cause the job to fail:
-
-```ts
-await step.run('might-fail', async () => {
-  if (someCondition) {
-    throw new Error('Something went wrong')
-  }
-  return result
-})
-```
-
-The job status becomes `failed` and the error is stored. Failed jobs can be retried using `durably.retry(runId)`.
diff --git a/website/guide/offline-app.md b/website/guide/offline-app.md
new file mode 100644
index 00000000..b231fb50
--- /dev/null
+++ b/website/guide/offline-app.md
@@ -0,0 +1,220 @@
+# Offline App (Browser-Only)
+
+Run Durably entirely in the browser. Jobs execute locally using SQLite WASM with OPFS persistence. Works offline, survives tab closes.
+
+**Example code:** [browser-vite-react](https://github.com/coji/durably/tree/main/examples/browser-vite-react)
+
+## When to Use
+
+- Offline-capable applications
+- Local-first apps (data stays on device)
+- Prototyping without backend
+
+## Requirements
+
+### Secure Context
+
+Requires HTTPS or localhost for OPFS access.
+
+### COOP/COEP Headers
+
+SQLite WASM needs cross-origin isolation:
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    {
+      name: 'coop-coep',
+      configureServer: (server) => {
+        server.middlewares.use((_req, res, next) => {
+          res.setHeader('Cross-Origin-Embedder-Policy', 'require-corp')
+          res.setHeader('Cross-Origin-Opener-Policy', 'same-origin')
+          next()
+        })
+      },
+    },
+  ],
+  optimizeDeps: { exclude: ['sqlocal'] },
+})
+```
+
+## Installation
+
+```bash
+npm install @coji/durably @coji/durably-react kysely zod sqlocal
+```
+
+## Setup
+
+### Database
+
+```ts
+// lib/database.ts
+import { SQLocalKysely } from 'sqlocal/kysely'
+
+export const sqlocal = new SQLocalKysely('app.sqlite3')
+```
+
+### Job Definition
+
+```ts
+// jobs/data-sync.ts
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
+
+const delay = (ms: number) => new Promise((r) => setTimeout(r, ms))
+
+export const dataSyncJob = defineJob({
+  name: 'data-sync',
+  input: z.object({ userId: z.string() }),
+  output: z.object({ synced: z.number(), failed: z.number() }),
+  run: async (step, payload) => {
+    step.log.info(`Starting sync for user: ${payload.userId}`)
+
+    const items = await step.run('fetch-local', async () => {
+      step.progress(1, 4, 'Fetching local data...')
+      await delay(300)
+      return Array.from({ length: 10 }, (_, i) => ({
+        id: `item-${i}`,
+        data: `Data for ${payload.userId}`,
+      }))
+    })
+
+    let synced = 0
+    let failed = 0
+
+    for (let i = 0; i < items.length; i++) {
+      const item = items[i]
+      const success = await step.run(`sync-item-${item.id}`, async () => {
+        step.progress(2 + Math.floor(i / 5), 4, `Syncing item ${i + 1}...`)
+        await delay(100)
+        return Math.random() > 0.1 // 90% success rate
+      })
+
+      if (success) {
+        synced++
+      } else {
+        failed++
+        step.log.warn(`Failed to sync item: ${item.id}`)
+      }
+    }
+
+    await step.run('finalize', async () => {
+      step.progress(4, 4, 'Finalizing...')
+      await delay(200)
+    })
+
+    step.log.info(`Sync complete: ${synced} synced, ${failed} failed`)
+
+    return { synced, failed }
+  },
+})
+```
+
+### Durably Instance
+
+```ts
+// lib/durably.ts
+import { createDurably } from '@coji/durably'
+import { dataSyncJob } from '../jobs/data-sync'
+import { sqlocal } from './database'
+
+const durably = createDurably({
+  dialect: sqlocal.dialect,
+  pollingInterval: 100,
+  heartbeatInterval: 500,
+  staleThreshold: 3000,
+}).register({
+  dataSync: dataSyncJob,
+})
+
+await durably.migrate()
+
+export { durably }
+```
+
+## Usage
+
+```tsx
+// App.tsx
+import { DurablyProvider, useDurably } from '@coji/durably-react'
+import { useJob } from '@coji/durably-react'
+import { useState } from 'react'
+import { durably } from './lib/durably'
+import { dataSyncJob } from './jobs/data-sync'
+
+function SyncButton() {
+  const { isReady } = useDurably()
+  const [runId, setRunId] = useState(null)
+
+  const handleSync = async () => {
+    const run = await durably.jobs.dataSync.trigger({ userId: 'user_123' })
+    setRunId(run.id)
+  }
+
+  const { status, progress, output, isRunning, isCompleted, error } =
+    useJob(dataSyncJob, { initialRunId: runId ?? undefined })
+
+  return (
+    
          
+      
+
+      {progress && 
          {progress.current}/{progress.total} - {progress.message}
          }
+      {isCompleted && 
          Synced {output?.synced}, failed {output?.failed}
          }
+      {error && 
          Error: {error}
          }
+    
          
+  )
+}
+
+function Loading() {
+  return 
          Loading...
          
+}
+
+export function App() {
+  return (
+    }>
+      
+    
+  )
+}
+```
+
+## Hook Options
+
+```tsx
+const { trigger, ... } = useJob(dataSyncJob, {
+  initialRunId: 'run_123',  // Resume existing run
+  maxLogs: 100,             // Limit log entries
+})
+```
+
+## Available Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useJob(jobDef)` | Trigger and monitor a job |
+| `useJobRun({ runId })` | Subscribe to an existing run |
+| `useJobLogs({ runId })` | Subscribe to logs |
+| `useRuns()` | List runs with pagination |
+| `useDurably()` | Access Durably instance |
+
+## Limitations
+
+- **Single tab** — OPFS exclusive access
+- **Storage quotas** — Browser limits apply
+- **No background** — Jobs only run when tab is active
+
+## Tab Suspension
+
+Browsers suspend inactive tabs. Durably handles this:
+
+1. Tab inactive → heartbeat stops → job marked stale
+2. Tab active → worker restarts → job resumes
+
+## Next Steps
+
+- [CSV Import](/guide/csv-import) — Full-stack with server
+- [API Reference](/api/durably-react/) — All hooks and options
diff --git a/website/guide/resumability.md b/website/guide/resumability.md
deleted file mode 100644
index 08478de3..00000000
--- a/website/guide/resumability.md
+++ /dev/null
@@ -1,134 +0,0 @@
-# Resumability
-
-Durably's core feature is automatic job resumption. This page explains how it works.
-
-## How It Works
-
-### Step Persistence
-
-Every `step.run()` call creates a checkpoint:
-
-```ts
-// Step 1: Result persisted to SQLite
-const users = await step.run('fetch-users', async () => {
-  return await api.fetchUsers()  // Takes 5 seconds
-})
-
-// Step 2: If crash happens here...
-await step.run('process-users', async () => {
-  await processAll(users)  // Crash!
-})
-
-// Step 3: Never reached
-await step.run('notify', async () => {
-  await sendNotification()
-})
-```
-
-### On Resume
-
-When the job restarts:
-
-```ts
-// Step 1: Returns cached result instantly (no API call)
-const users = await step.run('fetch-users', async () => {
-  return await api.fetchUsers()  // Skipped!
-})
-
-// Step 2: Re-executes from the beginning
-await step.run('process-users', async () => {
-  await processAll(users)  // Runs again
-})
-
-// Step 3: Runs normally
-await step.run('notify', async () => {
-  await sendNotification()
-})
-```
-
-## Heartbeat Mechanism
-
-Durably uses heartbeats to detect abandoned jobs:
-
-```ts
-const durably = createDurably({
-  dialect,
-  heartbeatInterval: 5000,   // Update heartbeat every 5 seconds
-  staleThreshold: 30000,     // Consider stale after 30 seconds
-})
-```
-
-### How It Works
-
-1. Running jobs update their `heartbeat_at` timestamp periodically
-2. Worker checks for stale jobs (no heartbeat update for `staleThreshold` ms)
-3. Stale jobs are reset to `pending` and picked up again
-
-### Browser Tab Handling
-
-In browsers, tabs can be suspended. When the tab becomes active:
-
-1. The heartbeat resumes
-2. If the job was marked stale, it restarts from the last checkpoint
-
-## Idempotency
-
-Steps should be designed to be safely re-runnable:
-
-### Good: Idempotent Operations
-
-```ts
-// Using upsert instead of insert
-await step.run('save-user', async () => {
-  await db.upsertUser(user)  // Safe to retry
-})
-
-// Checking before action
-await step.run('send-email', async () => {
-  const sent = await db.wasEmailSent(userId)
-  if (!sent) {
-    await sendEmail(user)
-    await db.markEmailSent(userId)
-  }
-})
-```
-
-### Caution: Non-Idempotent Operations
-
-```ts
-// Be careful with operations that can't be safely repeated
-await step.run('charge-card', async () => {
-  // Use idempotency keys with payment providers
-  await stripe.charges.create({
-    amount: 1000,
-    idempotency_key: `charge_${orderId}`,
-  })
-})
-```
-
-## Partial Step Completion
-
-If a step crashes mid-execution, the entire step is re-run:
-
-```ts
-await step.run('process-items', async () => {
-  for (const item of items) {
-    await processItem(item)  // Crash after 50 items
-  }
-  // On resume: ALL items are processed again
-})
-```
-
-For large operations, consider breaking into smaller steps:
-
-```ts
-// Better: Process in batches
-for (let i = 0; i < items.length; i += 100) {
-  await step.run(`batch-${i}`, async () => {
-    const batch = items.slice(i, i + 100)
-    for (const item of batch) {
-      await processItem(item)
-    }
-  })
-}
-```
diff --git a/website/guide/server.md b/website/guide/server.md
deleted file mode 100644
index a558d90d..00000000
--- a/website/guide/server.md
+++ /dev/null
@@ -1,182 +0,0 @@
-# Server
-
-This guide covers running Durably on the server (Node.js).
-
-## SQLite Drivers
-
-Durably works with any Kysely-compatible SQLite dialect.
-
-### Turso / libsql (Recommended)
-
-[Turso](https://turso.tech) is a SQLite-compatible database built on [libsql](https://github.com/tursodatabase/libsql). Use local files for development and Turso cloud for production:
-
-```ts
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-
-// Local development
-const dialect = new LibsqlDialect({
-  url: 'file:local.db',
-})
-
-// Production (Turso cloud)
-const dialect = new LibsqlDialect({
-  url: process.env.TURSO_DATABASE_URL,
-  authToken: process.env.TURSO_AUTH_TOKEN,
-})
-
-const durably = createDurably({ dialect })
-```
-
-Install dependencies:
-
-```bash
-npm install @libsql/client @libsql/kysely-libsql
-```
-
-### better-sqlite3
-
-[better-sqlite3](https://github.com/WiseLibs/better-sqlite3) is a synchronous SQLite driver:
-
-```ts
-import SQLite from 'better-sqlite3'
-import { SqliteDialect } from 'kysely'
-
-const database = new SQLite('local.db')
-const dialect = new SqliteDialect({ database })
-
-const durably = createDurably({ dialect })
-```
-
-## Configuration
-
-```ts
-const durably = createDurably({
-  dialect,
-  pollingInterval: 1000,    // Check for pending jobs every 1s
-  heartbeatInterval: 5000,  // Update heartbeat every 5s
-  staleThreshold: 30000,    // Mark jobs stale after 30s
-})
-```
-
-## Lifecycle
-
-```ts
-// Run database migrations
-await durably.migrate()
-
-// Start the worker
-durably.start()
-
-// Trigger jobs
-await myJob.trigger({ data: 'value' })
-
-// Stop gracefully
-await durably.stop()
-```
-
-## Process Signals
-
-Handle graceful shutdown:
-
-```ts
-process.on('SIGTERM', async () => {
-  console.log('Shutting down...')
-  await durably.stop()
-  process.exit(0)
-})
-
-process.on('SIGINT', async () => {
-  console.log('Interrupted...')
-  await durably.stop()
-  process.exit(0)
-})
-```
-
-## Worker Patterns
-
-### Single Worker
-
-The simplest pattern - one worker per process:
-
-```ts
-const durably = createDurably({ dialect })
-await durably.migrate()
-durably.start()
-```
-
-### Multiple Processes
-
-Durably supports multiple workers competing for jobs:
-
-```ts
-// worker-1.ts
-const durably = createDurably({ dialect })
-durably.start()
-
-// worker-2.ts (separate process)
-const durably = createDurably({ dialect })
-durably.start()
-```
-
-Jobs are claimed atomically - only one worker processes each job.
-
-## Error Handling
-
-```ts
-durably.on('run:fail', (event) => {
-  console.error(`Job ${event.runId} failed:`, event.error)
-
-  // Send to error tracking
-  Sentry.captureException(new Error(event.error), {
-    extra: { runId: event.runId, jobName: event.jobName },
-  })
-})
-```
-
-## Retrying Failed Jobs
-
-```ts
-// Get failed runs
-const failedRuns = await durably.getFailedRuns()
-
-// Retry a specific run
-await durably.retry(failedRuns[0].id)
-```
-
-## Integration with Frameworks
-
-### Express
-
-```ts
-import express from 'express'
-
-const app = express()
-
-app.post('/api/trigger-job', async (req, res) => {
-  const { id } = req.body
-  await myJob.trigger({ id })
-  res.json({ status: 'triggered' })
-})
-
-// Start both
-await durably.migrate()
-durably.start()
-app.listen(3000)
-```
-
-### Fastify
-
-```ts
-import Fastify from 'fastify'
-
-const fastify = Fastify()
-
-fastify.post('/api/trigger-job', async (req) => {
-  await myJob.trigger(req.body)
-  return { status: 'triggered' }
-})
-
-await durably.migrate()
-durably.start()
-await fastify.listen({ port: 3000 })
-```
diff --git a/website/public/images/fullstack-architecture.svg b/website/public/images/fullstack-architecture.svg
new file mode 100644
index 00000000..af8767db
--- /dev/null
+++ b/website/public/images/fullstack-architecture.svg
@@ -0,0 +1,67 @@
+
+  
+    
+    
+      
+    
+    
+      
+    
+  
+
+  
+  
+  Browser
+
+  
+  
+  Form (CSV Upload)
+
+  
+  useRun(runId)
+
+  
+  Progress UI
+  50/100 rows
+
+  
+  
+  Server (React Router)
+
+  
+  
+  action: Parse CSV + Trigger Job
+  /api/durably/trigger
+
+  
+  Durably Worker
+  Execute steps, emit events
+
+  
+  SSE Stream
+  /api/durably/subscribe
+
+  
+  
+  
+  
+  POST
+
+  
+  
+  
+  SSE
+
+  
+  
+  
+  Request
+  
+  Events
+
diff --git a/website/public/images/getting-started-overview.svg b/website/public/images/getting-started-overview.svg
new file mode 100644
index 00000000..f8e0a26f
--- /dev/null
+++ b/website/public/images/getting-started-overview.svg
@@ -0,0 +1,59 @@
+
+  
+    
+    
+      
+    
+  
+
+  
+  
+  
+  1
+  Define Job
+  Create job with
+  steps and schema
+  durably.server.ts
+
+  
+  
+
+  
+  
+  
+  2
+  API Routes
+  Expose trigger
+  and subscribe
+  api.durably.*.ts
+
+  
+  
+
+  
+  
+  
+  3
+  Client Hooks
+  Type-safe React
+  hooks for UI
+  durably.client.ts
+
+  
+  
+
+  
+  
+  
+  4
+  Build UI
+  Form + Progress
+  with real-time SSE
+  _index.tsx
+
diff --git a/website/public/images/job-lifecycle.svg b/website/public/images/job-lifecycle.svg
new file mode 100644
index 00000000..70f2ec82
--- /dev/null
+++ b/website/public/images/job-lifecycle.svg
@@ -0,0 +1,58 @@
+
+  
+    
+    
+      
+    
+    
+      
+    
+  
+
+  
+  trigger()
+  
+
+  
+  
+  pending
+
+  
+  
+  worker
+
+  
+  
+  running
+
+  
+  
+
+  
+  
+
+  
+  
+  cancel()
+
+  
+  
+  completed
+
+  
+  
+  failed
+
+  
+  
+  cancelled
+
+  
+  
+  
+  retry()
+
diff --git a/website/public/images/resumability.svg b/website/public/images/resumability.svg
new file mode 100644
index 00000000..e5f9424f
--- /dev/null
+++ b/website/public/images/resumability.svg
@@ -0,0 +1,94 @@
+
+  
+    
+  
+
+  
+  First Run
+
+  
+  
+  Step 1: Parse
+
+  
+  Step 2: Import
+
+  
+  Step 3: Notify
+  CRASH!
+
+  
+  
+  
+
+  
+  
+  
+
+  
+  
+
+  
+  saved
+  saved
+
+  
+  
+  Process restarts...
+
+  
+  After Restart
+
+  
+  
+  Step 1: Parse
+  CACHED
+
+  
+  Step 2: Import
+  CACHED
+
+  
+  Step 3: Notify
+  RUNS
+
+  
+  
+  
+
+  
+  
+  skip completed steps
+
+  
+  
+
+  How Durably Works
+
+  
+  Each step.run() saves result to SQLite
+
+  
+  Process crashes mid-execution
+
+  
+  On restart: completed steps return
+  cached results instantly
+
+  
+  Execution continues from next
+  incomplete step
+
+  
+  
+    
+      
+    
+  
+

From b52487725282bbfef62fbf9266468df23a098bcf Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 13:03:45 +0900
Subject: [PATCH 092/101] refactor: unify browser examples to use init()
 instead of migrate()
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Both start() and init() are idempotent, so browser code can safely use
init() even when DurablyProvider also calls start() internally. This
provides a consistent initialization API across server and browser.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-react-router-spa/app/lib/durably.ts | 2 +-
 examples/browser-vite-react/src/lib/durably.ts       | 2 +-
 packages/durably/docs/llms.md                        | 5 ++---
 website/api/create-durably.md                        | 2 +-
 website/guide/offline-app.md                         | 2 +-
 5 files changed, 6 insertions(+), 7 deletions(-)

diff --git a/examples/browser-react-router-spa/app/lib/durably.ts b/examples/browser-react-router-spa/app/lib/durably.ts
index 9a384b4d..16c9f0e5 100644
--- a/examples/browser-react-router-spa/app/lib/durably.ts
+++ b/examples/browser-react-router-spa/app/lib/durably.ts
@@ -20,6 +20,6 @@ const durably = createDurably({
   dataSync: dataSyncJob,
 })
 
-await durably.migrate()
+await durably.init()
 
 export { durably }
diff --git a/examples/browser-vite-react/src/lib/durably.ts b/examples/browser-vite-react/src/lib/durably.ts
index 4d221967..ab40e303 100644
--- a/examples/browser-vite-react/src/lib/durably.ts
+++ b/examples/browser-vite-react/src/lib/durably.ts
@@ -20,6 +20,6 @@ const durably = createDurably({
   dataSync: dataSyncJob,
 })
 
-await durably.migrate()
+await durably.init()
 
 export { durably }
diff --git a/packages/durably/docs/llms.md b/packages/durably/docs/llms.md
index 10d45cd6..1d39cf63 100644
--- a/packages/durably/docs/llms.md
+++ b/packages/durably/docs/llms.md
@@ -346,9 +346,8 @@ const { myJob } = durably.register({
   }),
 })
 
-// For browser, use migrate() only if using DurablyProvider (it handles start())
-// Otherwise use init() for both migrations and worker
-await durably.migrate()
+// Initialize (same as Node.js)
+await durably.init()
 ```
 
 ## Run Lifecycle
diff --git a/website/api/create-durably.md b/website/api/create-durably.md
index e7d3153a..792eaca3 100644
--- a/website/api/create-durably.md
+++ b/website/api/create-durably.md
@@ -44,7 +44,7 @@ Initialize Durably: runs database migrations and starts the worker. This is the
 await durably.migrate(): Promise
 ```
 
-Runs database migrations to create the required tables. Use this when you need to run migrations without starting the worker (e.g., in browser mode where `DurablyProvider` handles starting).
+Runs database migrations to create the required tables. Use `init()` instead for most cases.
 
 ### `start()`
 
diff --git a/website/guide/offline-app.md b/website/guide/offline-app.md
index b231fb50..49b5cb8d 100644
--- a/website/guide/offline-app.md
+++ b/website/guide/offline-app.md
@@ -129,7 +129,7 @@ const durably = createDurably({
   dataSync: dataSyncJob,
 })
 
-await durably.migrate()
+await durably.init()
 
 export { durably }
 ```

From 371626bad5119cda5db106d24fea837268d12f12 Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 13:25:00 +0900
Subject: [PATCH 093/101] refactor(durably-react): simplify DurablyProvider,
 remove autoStart/onReady/isReady
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Since users now call init() before passing durably to DurablyProvider,
the provider no longer needs to manage initialization state. Removed:
- autoStart prop (init() already starts the worker)
- onReady callback (no async initialization)
- isReady/error from context and hooks (always ready after init())

This simplifies the API and reduces unnecessary state management.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 examples/browser-vite-react/src/App.tsx       |  6 +-
 .../durably-react/src/client/use-job-logs.ts  |  2 -
 .../durably-react/src/client/use-job-run.ts   |  2 -
 packages/durably-react/src/client/use-job.ts  |  2 -
 packages/durably-react/src/context.tsx        | 58 ++-----------
 .../durably-react/src/hooks/use-job-logs.ts   |  7 +-
 .../durably-react/src/hooks/use-job-run.ts    |  7 +-
 packages/durably-react/src/hooks/use-job.ts   | 10 +--
 packages/durably-react/src/hooks/use-runs.ts  | 11 +--
 .../tests/browser/provider.test.tsx           | 85 ++-----------------
 .../tests/browser/use-job-logs.test.tsx       | 16 ++--
 .../tests/browser/use-job-run.test.tsx        | 64 +++++---------
 .../tests/browser/use-job.test.tsx            | 15 ----
 .../tests/browser/use-runs.test.tsx           |  9 --
 .../client/create-durably-client.test.tsx     |  2 -
 .../tests/client/create-job-hooks.test.tsx    |  2 -
 .../tests/client/use-job-logs.test.tsx        |  1 -
 .../tests/client/use-job-run.test.tsx         |  1 -
 .../tests/client/use-job.test.tsx             |  1 -
 19 files changed, 46 insertions(+), 255 deletions(-)

diff --git a/examples/browser-vite-react/src/App.tsx b/examples/browser-vite-react/src/App.tsx
index 0871fbe8..3ade2321 100644
--- a/examples/browser-vite-react/src/App.tsx
+++ b/examples/browser-vite-react/src/App.tsx
@@ -8,7 +8,7 @@
  * - Tailwind CSS for styling
  */
 
-import { DurablyProvider, useDurably } from '@coji/durably-react'
+import { DurablyProvider } from '@coji/durably-react'
 import { useState } from 'react'
 import {
   Dashboard,
@@ -21,7 +21,6 @@ import { sqlocal } from './lib/database'
 import { durably } from './lib/durably'
 
 function AppContent() {
-  const { isReady } = useDurably()
   const [activeJob, setActiveJob] = useState<'image' | 'sync'>('image')
   const [imageRunId, setImageRunId] = useState(null)
   const [syncRunId, setSyncRunId] = useState(null)
@@ -86,8 +85,7 @@ function AppContent() {
                   
diff --git a/packages/durably-react/src/client/use-job-logs.ts b/packages/durably-react/src/client/use-job-logs.ts
index a8b22089..8e237b0a 100644
--- a/packages/durably-react/src/client/use-job-logs.ts
+++ b/packages/durably-react/src/client/use-job-logs.ts
@@ -20,7 +20,6 @@ export interface UseJobLogsClientResult {
   /**
    * Whether the hook is ready (always true for client mode)
    */
-  isReady: boolean
   /**
    * Logs collected during execution
    */
@@ -43,7 +42,6 @@ export function useJobLogs(
   const subscription = useSSESubscription(api, runId, { maxLogs })
 
   return {
-    isReady: true,
     logs: subscription.logs,
     clearLogs: subscription.clearLogs,
   }
diff --git a/packages/durably-react/src/client/use-job-run.ts b/packages/durably-react/src/client/use-job-run.ts
index 415c3e6f..6dfba8ef 100644
--- a/packages/durably-react/src/client/use-job-run.ts
+++ b/packages/durably-react/src/client/use-job-run.ts
@@ -29,7 +29,6 @@ export interface UseJobRunClientResult {
   /**
    * Whether the hook is ready (always true for client mode)
    */
-  isReady: boolean
   /**
    * Current run status
    */
@@ -124,7 +123,6 @@ export function useJobRun(
   ])
 
   return {
-    isReady: true,
     status: effectiveStatus,
     output: subscription.output,
     error: subscription.error,
diff --git a/packages/durably-react/src/client/use-job.ts b/packages/durably-react/src/client/use-job.ts
index 49d49b3d..f93f3547 100644
--- a/packages/durably-react/src/client/use-job.ts
+++ b/packages/durably-react/src/client/use-job.ts
@@ -22,7 +22,6 @@ export interface UseJobClientResult {
   /**
    * Whether the hook is ready (always true for client mode)
    */
-  isReady: boolean
   /**
    * Trigger the job with the given input
    */
@@ -161,7 +160,6 @@ export function useJob<
   }, [subscription.status, isPending])
 
   return {
-    isReady: true,
     trigger,
     triggerAndWait,
     status: effectiveStatus,
diff --git a/packages/durably-react/src/context.tsx b/packages/durably-react/src/context.tsx
index e1514402..eb346444 100644
--- a/packages/durably-react/src/context.tsx
+++ b/packages/durably-react/src/context.tsx
@@ -4,16 +4,11 @@ import {
   createContext,
   use,
   useContext,
-  useEffect,
-  useRef,
-  useState,
   type ReactNode,
 } from 'react'
 
 interface DurablyContextValue {
-  durably: Durably | null
-  isReady: boolean
-  error: Error | null
+  durably: Durably
 }
 
 const DurablyContext = createContext(null)
@@ -21,7 +16,7 @@ const DurablyContext = createContext(null)
 export interface DurablyProviderProps {
   /**
    * Durably instance or Promise that resolves to one.
-   * The instance should already be migrated and have jobs registered if needed.
+   * The instance should already be initialized via `await durably.init()`.
    *
    * When passing a Promise, wrap the provider with Suspense or use the fallback prop.
    *
@@ -40,15 +35,6 @@ export interface DurablyProviderProps {
    * 
    */
   durably: Durably | Promise
-  /**
-   * Whether to automatically call start() after mounting.
-   * @default true
-   */
-  autoStart?: boolean
-  /**
-   * Callback when Durably instance is ready.
-   */
-  onReady?: (durably: Durably) => void
   /**
    * Fallback to show while waiting for the Durably Promise to resolve.
    * This wraps the provider content in a Suspense boundary automatically.
@@ -62,40 +48,15 @@ export interface DurablyProviderProps {
  */
 function DurablyProviderInner({
   durably: durablyOrPromise,
-  autoStart = true,
-  onReady,
   children,
 }: Omit) {
-  // Resolve Promise using React 19's use() hook
-  const resolvedDurably =
+  const durably =
     durablyOrPromise instanceof Promise
       ? use(durablyOrPromise)
       : durablyOrPromise
 
-  const [durably, setDurably] = useState(null)
-  const [isReady, setIsReady] = useState(false)
-  const [error, setError] = useState(null)
-
-  const instanceRef = useRef(null)
-
-  useEffect(() => {
-    try {
-      instanceRef.current = resolvedDurably
-
-      if (autoStart) {
-        resolvedDurably.start()
-      }
-
-      setDurably(resolvedDurably)
-      setIsReady(true)
-      onReady?.(resolvedDurably)
-    } catch (err) {
-      setError(err instanceof Error ? err : new Error(String(err)))
-    }
-  }, [resolvedDurably, autoStart, onReady])
-
   return (
-    
+    
       {children}
     
   )
@@ -103,22 +64,13 @@ function DurablyProviderInner({
 
 export function DurablyProvider({
   durably,
-  autoStart = true,
-  onReady,
   fallback,
   children,
 }: DurablyProviderProps) {
   const inner = (
-    
-      {children}
-    
+    {children}
   )
 
-  // If fallback is provided, wrap in Suspense
   if (fallback !== undefined) {
     return {inner}
   }
diff --git a/packages/durably-react/src/hooks/use-job-logs.ts b/packages/durably-react/src/hooks/use-job-logs.ts
index fd4cf83b..ff3b87ed 100644
--- a/packages/durably-react/src/hooks/use-job-logs.ts
+++ b/packages/durably-react/src/hooks/use-job-logs.ts
@@ -14,10 +14,6 @@ export interface UseJobLogsOptions {
 }
 
 export interface UseJobLogsResult {
-  /**
-   * Whether the hook is ready (Durably is initialized)
-   */
-  isReady: boolean
   /**
    * Logs collected during execution
    */
@@ -33,13 +29,12 @@ export interface UseJobLogsResult {
  * Use this when you only need logs, not full run status.
  */
 export function useJobLogs(options: UseJobLogsOptions): UseJobLogsResult {
-  const { durably, isReady: isDurablyReady } = useDurably()
+  const { durably } = useDurably()
   const { runId, maxLogs } = options
 
   const subscription = useRunSubscription(durably, runId, { maxLogs })
 
   return {
-    isReady: isDurablyReady,
     logs: subscription.logs,
     clearLogs: subscription.clearLogs,
   }
diff --git a/packages/durably-react/src/hooks/use-job-run.ts b/packages/durably-react/src/hooks/use-job-run.ts
index c941691c..a9597517 100644
--- a/packages/durably-react/src/hooks/use-job-run.ts
+++ b/packages/durably-react/src/hooks/use-job-run.ts
@@ -11,10 +11,6 @@ export interface UseJobRunOptions {
 }
 
 export interface UseJobRunResult {
-  /**
-   * Whether the hook is ready (Durably is initialized)
-   */
-  isReady: boolean
   /**
    * Current run status
    */
@@ -64,7 +60,7 @@ export interface UseJobRunResult {
 export function useJobRun(
   options: UseJobRunOptions,
 ): UseJobRunResult {
-  const { durably, isReady: isDurablyReady } = useDurably()
+  const { durably } = useDurably()
   const { runId } = options
 
   const subscription = useRunSubscription(durably, runId)
@@ -84,7 +80,6 @@ export function useJobRun(
   }, [durably, runId])
 
   return {
-    isReady: isDurablyReady,
     status: subscription.status,
     output: subscription.output,
     error: subscription.error,
diff --git a/packages/durably-react/src/hooks/use-job.ts b/packages/durably-react/src/hooks/use-job.ts
index 174bc115..8b86c1fa 100644
--- a/packages/durably-react/src/hooks/use-job.ts
+++ b/packages/durably-react/src/hooks/use-job.ts
@@ -24,10 +24,6 @@ export interface UseJobOptions {
 }
 
 export interface UseJobResult {
-  /**
-   * Whether the hook is ready (Durably is initialized)
-   */
-  isReady: boolean
   /**
    * Trigger the job with the given input
    */
@@ -95,7 +91,7 @@ export function useJob<
   jobDefinition: JobDefinition,
   options?: UseJobOptions,
 ): UseJobResult {
-  const { durably, isReady: isDurablyReady } = useDurably()
+  const { durably } = useDurably()
 
   const [status, setStatus] = useState(null)
   const [output, setOutput] = useState(null)
@@ -113,7 +109,7 @@ export function useJob<
 
   // Register job and set up event listeners
   useEffect(() => {
-    if (!durably || !isDurablyReady) return
+    if (!durably) return
 
     // Register the job (use fixed key for simpler type handling)
     const d = durably.register({
@@ -236,7 +232,6 @@ export function useJob<
     }
   }, [
     durably,
-    isDurablyReady,
     jobDefinition,
     options?.initialRunId,
     options?.autoResume,
@@ -340,7 +335,6 @@ export function useJob<
   }, [])
 
   return {
-    isReady: isDurablyReady,
     trigger,
     triggerAndWait,
     status,
diff --git a/packages/durably-react/src/hooks/use-runs.ts b/packages/durably-react/src/hooks/use-runs.ts
index 669b6f75..8cc0d1c7 100644
--- a/packages/durably-react/src/hooks/use-runs.ts
+++ b/packages/durably-react/src/hooks/use-runs.ts
@@ -24,10 +24,6 @@ export interface UseRunsOptions {
 }
 
 export interface UseRunsResult {
-  /**
-   * Whether the hook is ready (Durably is initialized)
-   */
-  isReady: boolean
   /**
    * List of runs for the current page
    */
@@ -85,7 +81,7 @@ export interface UseRunsResult {
  * ```
  */
 export function useRuns(options?: UseRunsOptions): UseRunsResult {
-  const { durably, isReady: isDurablyReady } = useDurably()
+  const { durably } = useDurably()
   const pageSize = options?.pageSize ?? 10
   const realtime = options?.realtime ?? true
 
@@ -114,7 +110,7 @@ export function useRuns(options?: UseRunsOptions): UseRunsResult {
 
   // Initial fetch and subscribe to events
   useEffect(() => {
-    if (!durably || !isDurablyReady) return
+    if (!durably) return
 
     refresh()
 
@@ -134,7 +130,7 @@ export function useRuns(options?: UseRunsOptions): UseRunsResult {
         unsubscribe()
       }
     }
-  }, [durably, isDurablyReady, refresh, realtime])
+  }, [durably, refresh, realtime])
 
   const nextPage = useCallback(() => {
     if (hasMore) {
@@ -151,7 +147,6 @@ export function useRuns(options?: UseRunsOptions): UseRunsResult {
   }, [])
 
   return {
-    isReady: isDurablyReady,
     runs,
     page,
     hasMore,
diff --git a/packages/durably-react/tests/browser/provider.test.tsx b/packages/durably-react/tests/browser/provider.test.tsx
index 2f1d4639..c518aee3 100644
--- a/packages/durably-react/tests/browser/provider.test.tsx
+++ b/packages/durably-react/tests/browser/provider.test.tsx
@@ -1,13 +1,13 @@
 /**
  * DurablyProvider Tests
  *
- * Test DurablyProvider initialization, options, and cleanup
+ * Test DurablyProvider initialization and context
  */
 
 import type { Durably } from '@coji/durably'
 import { render, renderHook, waitFor } from '@testing-library/react'
 import { StrictMode } from 'react'
-import { afterEach, describe, expect, it, vi } from 'vitest'
+import { afterEach, describe, expect, it } from 'vitest'
 import { DurablyProvider, useDurably } from '../../src'
 import { createTestDurably } from '../helpers/create-test-durably'
 
@@ -27,7 +27,7 @@ describe('DurablyProvider', () => {
     await new Promise((r) => setTimeout(r, 200))
   })
 
-  it('initializes Durably and provides isReady=true', async () => {
+  it('provides Durably instance via context', async () => {
     const durably = await createTestDurably()
     instances.push(durably)
 
@@ -37,11 +37,7 @@ describe('DurablyProvider', () => {
       ),
     })
 
-    await waitFor(() => {
-      expect(result.current.isReady).toBe(true)
-    })
     expect(result.current.durably).toBe(durably)
-    expect(result.current.error).toBeNull()
   })
 
   it('works correctly in StrictMode', async () => {
@@ -49,11 +45,9 @@ describe('DurablyProvider', () => {
     instances.push(durably)
 
     function TestComponent() {
-      const { isReady, durably: d } = useDurably()
+      const { durably: d } = useDurably()
       return (
-        
          
-          {isReady ? 'ready' : 'loading'}-{d ? 'has-durably' : 'no-durably'}
-        
          
+        
          {d ? 'has-durably' : 'no-durably'}
          
       )
     }
 
@@ -66,71 +60,8 @@ describe('DurablyProvider', () => {
     )
 
     await waitFor(() => {
-      expect(getByTestId('status').textContent).toBe('ready-has-durably')
-    })
-  })
-
-  it('respects autoStart=false', async () => {
-    const durably = await createTestDurably()
-    instances.push(durably)
-
-    // Spy on start to verify it's not called
-    const startSpy = vi.spyOn(durably, 'start')
-
-    const { result } = renderHook(() => useDurably(), {
-      wrapper: ({ children }) => (
-        
-          {children}
-        
-      ),
-    })
-
-    await waitFor(() => {
-      expect(result.current.isReady).toBe(true)
-    })
-
-    expect(startSpy).not.toHaveBeenCalled()
-  })
-
-  it('calls start() by default (autoStart=true)', async () => {
-    const durably = await createTestDurably()
-    instances.push(durably)
-
-    // Spy on start to verify it's called
-    const startSpy = vi.spyOn(durably, 'start')
-
-    const { result } = renderHook(() => useDurably(), {
-      wrapper: ({ children }) => (
-        {children}
-      ),
-    })
-
-    await waitFor(() => {
-      expect(result.current.isReady).toBe(true)
+      expect(getByTestId('status').textContent).toBe('has-durably')
     })
-
-    expect(startSpy).toHaveBeenCalled()
-  })
-
-  it('calls onReady callback when ready', async () => {
-    const durably = await createTestDurably()
-    instances.push(durably)
-
-    const onReady = vi.fn()
-
-    const { result } = renderHook(() => useDurably(), {
-      wrapper: ({ children }) => (
-        
-          {children}
-        
-      ),
-    })
-
-    await waitFor(() => {
-      expect(result.current.isReady).toBe(true)
-    })
-
-    expect(onReady).toHaveBeenCalledWith(durably)
   })
 
   it('provides the same durably instance from useDurably', async () => {
@@ -143,10 +74,6 @@ describe('DurablyProvider', () => {
       ),
     })
 
-    await waitFor(() => {
-      expect(result.current.isReady).toBe(true)
-    })
-
     // Should be the exact same instance
     expect(result.current.durably).toBe(durably)
   })
diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx
index 5839de55..a3d78331 100644
--- a/packages/durably-react/tests/browser/use-job-logs.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx
@@ -54,13 +54,13 @@ describe('useJobLogs', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobLogs({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+        
         runId,
         setRunId,
       }
@@ -70,7 +70,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({
       _job: loggingJob,
@@ -100,7 +99,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     // With null runId, logs should be empty
     expect(result.current.logs).toEqual([])
@@ -111,13 +109,13 @@ describe('useJobLogs', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobLogs({ runId, maxLogs: 5 })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+        
         runId,
         setRunId,
       }
@@ -127,7 +125,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({
       _job: loggingJob,
@@ -147,13 +144,13 @@ describe('useJobLogs', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobLogs({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+        
         runId,
         setRunId,
       }
@@ -163,7 +160,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({
       _job: loggingJob,
diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx
index bbb9cc0f..c1c9563c 100644
--- a/packages/durably-react/tests/browser/use-job-run.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-run.test.tsx
@@ -78,13 +78,13 @@ describe('useJobRun', () => {
 
     // Use a combined hook that triggers then subscribes
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -94,8 +94,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     // Trigger job and set runId
     const d = durably.register({ _job: testJob })
     const run = await d.jobs._job.trigger({ input: 'test' })
@@ -120,8 +118,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     // With null runId, status should remain null
     expect(result.current.status).toBeNull()
     expect(result.current.output).toBeNull()
@@ -133,13 +129,13 @@ describe('useJobRun', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun<{ result: string }>({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -149,8 +145,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({ _job: testJob })
     const run = await d.jobs._job.trigger({ input: 'hello' })
     result.current.setRunId(run.id)
@@ -169,13 +163,13 @@ describe('useJobRun', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -185,8 +179,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({
       _job: failingJob,
     })
@@ -208,19 +200,17 @@ describe('useJobRun', () => {
 
     // Use autoStart=false wrapper so worker doesn't pick up the job
     const noAutoStartWrapper = ({ children }: { children: ReactNode }) => (
-      
-        {children}
-      
+      {children}
     )
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -230,8 +220,6 @@ describe('useJobRun', () => {
       wrapper: noAutoStartWrapper,
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({ _job: testJob })
     const run = await d.jobs._job.trigger({ input: 'test' })
     result.current.setRunId(run.id)
@@ -253,13 +241,13 @@ describe('useJobRun', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -269,8 +257,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({ _job: failingJob })
     const run = await d.jobs._job.trigger({ input: 'test' })
     result.current.setRunId(run.id)
@@ -323,13 +309,13 @@ describe('useJobRun', () => {
     })
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun<{ result: string }>({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -339,8 +325,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({ _job: retryableJob })
     const run = await d.jobs._job.trigger({ input: 'test' })
     result.current.setRunId(run.id)
@@ -372,19 +356,17 @@ describe('useJobRun', () => {
 
     // Use autoStart=false wrapper so we can control when the worker runs
     const noAutoStartWrapper = ({ children }: { children: ReactNode }) => (
-      
-        {children}
-      
+      {children}
     )
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun<{ result: string }>({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -394,8 +376,6 @@ describe('useJobRun', () => {
       wrapper: noAutoStartWrapper,
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({ _job: testJob })
     const run = await d.jobs._job.trigger({ input: 'test' })
     result.current.setRunId(run.id)
@@ -440,13 +420,13 @@ describe('useJobRun', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -456,8 +436,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({
       _job: progressJob,
     })
@@ -481,13 +459,13 @@ describe('useJobRun', () => {
     instances.push(durably)
 
     function useTriggerAndSubscribe() {
-      const { isReady: durablyReady } = useDurably()
+      const { durably: _ } = useDurably()
       const [runId, setRunId] = useState(null)
       const subscription = useJobRun({ runId })
 
       return {
         ...subscription,
-        isReady: durablyReady && subscription.isReady,
+
         runId,
         setRunId,
       }
@@ -497,8 +475,6 @@ describe('useJobRun', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
-
     const d = durably.register({ _job: testJob })
     const run = await d.jobs._job.trigger({ input: 'test' })
     result.current.setRunId(run.id)
diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx
index a9c1df79..cdb7883e 100644
--- a/packages/durably-react/tests/browser/use-job.test.tsx
+++ b/packages/durably-react/tests/browser/use-job.test.tsx
@@ -98,7 +98,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const { runId } = await result.current.trigger({ input: 'test' })
 
@@ -114,7 +113,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     expect(result.current.status).toBeNull()
 
@@ -140,7 +138,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     await result.current.trigger({ input: 'test' })
 
@@ -157,7 +154,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     await result.current.trigger({ input: 'test' })
 
@@ -175,7 +171,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     result.current.trigger({ input: 'test' })
 
@@ -198,7 +193,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     await result.current.trigger({ input: 'test' })
 
@@ -220,7 +214,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     expect(result.current.isRunning).toBe(false)
     expect(result.current.isPending).toBe(false)
@@ -256,7 +249,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const { runId, output } = await result.current.triggerAndWait({
       input: 'test',
@@ -274,7 +266,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     await expect(
       result.current.triggerAndWait({ input: 'test' }),
@@ -289,7 +280,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     await result.current.trigger({ input: 'test' })
     await waitFor(() => expect(result.current.isCompleted).toBe(true))
@@ -315,7 +305,6 @@ describe('useJob', () => {
       { wrapper: createWrapper(durably) },
     )
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     // Should have the initial runId set
     expect(result.current.currentRunId).toBe(fakeRunId)
@@ -329,7 +318,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     result.current.trigger({ input: 'test' })
 
@@ -361,7 +349,6 @@ describe('useJob', () => {
         wrapper: createWrapper(durably),
       })
 
-      await waitFor(() => expect(result.current.isReady).toBe(true))
 
       // Trigger first job
       const { runId: firstRunId } = await result.current.trigger({ id: 1 })
@@ -402,7 +389,6 @@ describe('useJob', () => {
         { wrapper: createWrapper(durably) },
       )
 
-      await waitFor(() => expect(result.current.isReady).toBe(true))
 
       // Trigger first job
       const { runId: firstRunId } = await result.current.trigger({ id: 1 })
@@ -436,7 +422,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     // Start the long-running job and get the promise
     const waitPromise = result.current.triggerAndWait({ input: 'test' })
diff --git a/packages/durably-react/tests/browser/use-runs.test.tsx b/packages/durably-react/tests/browser/use-runs.test.tsx
index 739e691a..5ed897c5 100644
--- a/packages/durably-react/tests/browser/use-runs.test.tsx
+++ b/packages/durably-react/tests/browser/use-runs.test.tsx
@@ -53,7 +53,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
     expect(result.current.runs).toEqual([])
     expect(result.current.page).toBe(0)
     expect(result.current.hasMore).toBe(false)
@@ -67,7 +66,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     // Trigger a job using the durably instance directly
     const d = durably.register({ testJobHandle: testJob })
@@ -95,7 +93,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({
       testJobHandle: testJob,
@@ -120,7 +117,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({ testJobHandle: testJob })
 
@@ -153,7 +149,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({ testJobHandle: testJob })
 
@@ -192,7 +187,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({ testJobHandle: testJob })
 
@@ -220,7 +214,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({ testJobHandle: testJob })
 
@@ -245,7 +238,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({ testJobHandle: testJob })
 
@@ -267,7 +259,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-    await waitFor(() => expect(result.current.isReady).toBe(true))
 
     const d = durably.register({ testJobHandle: testJob })
 
diff --git a/packages/durably-react/tests/client/create-durably-client.test.tsx b/packages/durably-react/tests/client/create-durably-client.test.tsx
index 9d0c38c6..2b27151c 100644
--- a/packages/durably-react/tests/client/create-durably-client.test.tsx
+++ b/packages/durably-react/tests/client/create-durably-client.test.tsx
@@ -121,7 +121,6 @@ describe('createDurablyClient', () => {
 
     // Verify the hook returns expected shape
     expect(result.current.status).toBeNull()
-    expect(result.current.isReady).toBe(true)
   })
 
   it('useLogs returns a hook function', () => {
@@ -131,6 +130,5 @@ describe('createDurablyClient', () => {
 
     // Verify the hook returns expected shape
     expect(result.current.logs).toEqual([])
-    expect(result.current.isReady).toBe(true)
   })
 })
diff --git a/packages/durably-react/tests/client/create-job-hooks.test.tsx b/packages/durably-react/tests/client/create-job-hooks.test.tsx
index 20faf923..5c177344 100644
--- a/packages/durably-react/tests/client/create-job-hooks.test.tsx
+++ b/packages/durably-react/tests/client/create-job-hooks.test.tsx
@@ -112,7 +112,6 @@ describe('createJobHooks', () => {
 
     // Verify the hook returns expected shape
     expect(result.current.status).toBeNull()
-    expect(result.current.isReady).toBe(true)
   })
 
   it('useLogs returns a hook function', () => {
@@ -125,6 +124,5 @@ describe('createJobHooks', () => {
 
     // Verify the hook returns expected shape
     expect(result.current.logs).toEqual([])
-    expect(result.current.isReady).toBe(true)
   })
 })
diff --git a/packages/durably-react/tests/client/use-job-logs.test.tsx b/packages/durably-react/tests/client/use-job-logs.test.tsx
index c17ff799..85915425 100644
--- a/packages/durably-react/tests/client/use-job-logs.test.tsx
+++ b/packages/durably-react/tests/client/use-job-logs.test.tsx
@@ -32,7 +32,6 @@ describe('useJobLogs (client)', () => {
       useJobLogs({ api: '/api/durably', runId: 'log-run' }),
     )
 
-    expect(result.current.isReady).toBe(true)
 
     await waitFor(() => {
       expect(mockEventSource.instances.length).toBeGreaterThan(0)
diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx
index 4ddd585d..0fb4e216 100644
--- a/packages/durably-react/tests/client/use-job-run.test.tsx
+++ b/packages/durably-react/tests/client/use-job-run.test.tsx
@@ -32,7 +32,6 @@ describe('useJobRun (client)', () => {
       useJobRun({ api: '/api/durably', runId: 'existing-run' }),
     )
 
-    expect(result.current.isReady).toBe(true)
 
     await waitFor(() => {
       expect(mockEventSource.instances.length).toBeGreaterThan(0)
diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx
index 3f4d05d0..65f7ecdf 100644
--- a/packages/durably-react/tests/client/use-job.test.tsx
+++ b/packages/durably-react/tests/client/use-job.test.tsx
@@ -41,7 +41,6 @@ describe('useJob (client)', () => {
       useJob({ api: '/api/durably', jobName: 'test-job' }),
     )
 
-    expect(result.current.isReady).toBe(true)
 
     const { runId } = await result.current.trigger({ input: 'test' })
 

From b5a4f824b0b1f68a6b654e71422532b8c8b2d14d Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 13:37:26 +0900
Subject: [PATCH 094/101] fix(durably-react): update tests for simplified
 DurablyProvider
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update createTestDurably to use init() instead of migrate()
- Add autoStart option to createTestDurably for tests that need worker control
- Remove isReady type assertions from types.test.ts
- Update tests that require worker not started to use autoStart: false

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/src/context.tsx            |  8 +-------
 .../durably-react/tests/browser/provider.test.tsx |  4 +---
 .../tests/browser/use-job-logs.test.tsx           | 10 +++-------
 .../tests/browser/use-job-run.test.tsx            | 14 ++++++++++----
 .../durably-react/tests/browser/use-job.test.tsx  | 15 ---------------
 .../durably-react/tests/browser/use-runs.test.tsx |  8 --------
 .../tests/client/use-job-logs.test.tsx            |  1 -
 .../tests/client/use-job-run.test.tsx             |  1 -
 .../durably-react/tests/client/use-job.test.tsx   |  1 -
 .../tests/helpers/create-test-durably.ts          | 15 +++++++++++++--
 packages/durably-react/tests/types.test.ts        |  2 --
 11 files changed, 28 insertions(+), 51 deletions(-)

diff --git a/packages/durably-react/src/context.tsx b/packages/durably-react/src/context.tsx
index eb346444..008e4cf5 100644
--- a/packages/durably-react/src/context.tsx
+++ b/packages/durably-react/src/context.tsx
@@ -1,11 +1,5 @@
 import type { Durably } from '@coji/durably'
-import {
-  Suspense,
-  createContext,
-  use,
-  useContext,
-  type ReactNode,
-} from 'react'
+import { Suspense, createContext, use, useContext, type ReactNode } from 'react'
 
 interface DurablyContextValue {
   durably: Durably
diff --git a/packages/durably-react/tests/browser/provider.test.tsx b/packages/durably-react/tests/browser/provider.test.tsx
index c518aee3..5eea0319 100644
--- a/packages/durably-react/tests/browser/provider.test.tsx
+++ b/packages/durably-react/tests/browser/provider.test.tsx
@@ -46,9 +46,7 @@ describe('DurablyProvider', () => {
 
     function TestComponent() {
       const { durably: d } = useDurably()
-      return (
-        
          {d ? 'has-durably' : 'no-durably'}
          
-      )
+      return 
          {d ? 'has-durably' : 'no-durably'}
          
     }
 
     const { getByTestId } = render(
diff --git a/packages/durably-react/tests/browser/use-job-logs.test.tsx b/packages/durably-react/tests/browser/use-job-logs.test.tsx
index a3d78331..06004ab7 100644
--- a/packages/durably-react/tests/browser/use-job-logs.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-logs.test.tsx
@@ -60,7 +60,7 @@ describe('useJobLogs', () => {
 
       return {
         ...subscription,
-        
+
         runId,
         setRunId,
       }
@@ -70,7 +70,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({
       _job: loggingJob,
     })
@@ -99,7 +98,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-
     // With null runId, logs should be empty
     expect(result.current.logs).toEqual([])
   })
@@ -115,7 +113,7 @@ describe('useJobLogs', () => {
 
       return {
         ...subscription,
-        
+
         runId,
         setRunId,
       }
@@ -125,7 +123,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({
       _job: loggingJob,
     })
@@ -150,7 +147,7 @@ describe('useJobLogs', () => {
 
       return {
         ...subscription,
-        
+
         runId,
         setRunId,
       }
@@ -160,7 +157,6 @@ describe('useJobLogs', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({
       _job: loggingJob,
     })
diff --git a/packages/durably-react/tests/browser/use-job-run.test.tsx b/packages/durably-react/tests/browser/use-job-run.test.tsx
index c1c9563c..9005079b 100644
--- a/packages/durably-react/tests/browser/use-job-run.test.tsx
+++ b/packages/durably-react/tests/browser/use-job-run.test.tsx
@@ -195,10 +195,13 @@ describe('useJobRun', () => {
   })
 
   it('updates status when run is cancelled', async () => {
-    const durably = await createTestDurably({ pollingInterval: 50 })
+    const durably = await createTestDurably({
+      pollingInterval: 50,
+      autoStart: false,
+    })
     instances.push(durably)
 
-    // Use autoStart=false wrapper so worker doesn't pick up the job
+    // Worker is not started, so we can cancel before the job runs
     const noAutoStartWrapper = ({ children }: { children: ReactNode }) => (
       {children}
     )
@@ -351,10 +354,13 @@ describe('useJobRun', () => {
   })
 
   it('tracks retry from cancelled through completion', async () => {
-    const durably = await createTestDurably({ pollingInterval: 50 })
+    const durably = await createTestDurably({
+      pollingInterval: 50,
+      autoStart: false,
+    })
     instances.push(durably)
 
-    // Use autoStart=false wrapper so we can control when the worker runs
+    // Worker is not started, so we can control when the worker runs
     const noAutoStartWrapper = ({ children }: { children: ReactNode }) => (
       {children}
     )
diff --git a/packages/durably-react/tests/browser/use-job.test.tsx b/packages/durably-react/tests/browser/use-job.test.tsx
index cdb7883e..b6ccffcf 100644
--- a/packages/durably-react/tests/browser/use-job.test.tsx
+++ b/packages/durably-react/tests/browser/use-job.test.tsx
@@ -98,7 +98,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const { runId } = await result.current.trigger({ input: 'test' })
 
     expect(runId).toBeDefined()
@@ -113,7 +112,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     expect(result.current.status).toBeNull()
 
     result.current.trigger({ input: 'test' })
@@ -138,7 +136,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     await result.current.trigger({ input: 'test' })
 
     await waitFor(() => {
@@ -154,7 +151,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     await result.current.trigger({ input: 'test' })
 
     await waitFor(() => {
@@ -171,7 +167,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     result.current.trigger({ input: 'test' })
 
     // Eventually should see progress (may not catch all intermediate states)
@@ -193,7 +188,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     await result.current.trigger({ input: 'test' })
 
     await waitFor(() => {
@@ -214,7 +208,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     expect(result.current.isRunning).toBe(false)
     expect(result.current.isPending).toBe(false)
     expect(result.current.isCompleted).toBe(false)
@@ -249,7 +242,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const { runId, output } = await result.current.triggerAndWait({
       input: 'test',
     })
@@ -266,7 +258,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     await expect(
       result.current.triggerAndWait({ input: 'test' }),
     ).rejects.toThrow('Something went wrong')
@@ -280,7 +271,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     await result.current.trigger({ input: 'test' })
     await waitFor(() => expect(result.current.isCompleted).toBe(true))
 
@@ -305,7 +295,6 @@ describe('useJob', () => {
       { wrapper: createWrapper(durably) },
     )
 
-
     // Should have the initial runId set
     expect(result.current.currentRunId).toBe(fakeRunId)
   })
@@ -318,7 +307,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     result.current.trigger({ input: 'test' })
 
     // Unmount while running
@@ -349,7 +337,6 @@ describe('useJob', () => {
         wrapper: createWrapper(durably),
       })
 
-
       // Trigger first job
       const { runId: firstRunId } = await result.current.trigger({ id: 1 })
 
@@ -389,7 +376,6 @@ describe('useJob', () => {
         { wrapper: createWrapper(durably) },
       )
 
-
       // Trigger first job
       const { runId: firstRunId } = await result.current.trigger({ id: 1 })
 
@@ -422,7 +408,6 @@ describe('useJob', () => {
       wrapper: createWrapper(durably),
     })
 
-
     // Start the long-running job and get the promise
     const waitPromise = result.current.triggerAndWait({ input: 'test' })
 
diff --git a/packages/durably-react/tests/browser/use-runs.test.tsx b/packages/durably-react/tests/browser/use-runs.test.tsx
index 5ed897c5..0e734666 100644
--- a/packages/durably-react/tests/browser/use-runs.test.tsx
+++ b/packages/durably-react/tests/browser/use-runs.test.tsx
@@ -66,7 +66,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     // Trigger a job using the durably instance directly
     const d = durably.register({ testJobHandle: testJob })
     await d.jobs.testJobHandle.trigger({ value: 10 })
@@ -93,7 +92,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({
       testJobHandle: testJob,
       otherJobHandle: otherJob,
@@ -117,7 +115,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({ testJobHandle: testJob })
 
     // Trigger and wait for completion
@@ -149,7 +146,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({ testJobHandle: testJob })
 
     // Create 3 runs
@@ -187,7 +183,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({ testJobHandle: testJob })
 
     // Create 3 runs
@@ -214,7 +209,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({ testJobHandle: testJob })
 
     // Initially empty
@@ -238,7 +232,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({ testJobHandle: testJob })
 
     expect(result.current.runs.length).toBe(0)
@@ -259,7 +252,6 @@ describe('useRuns', () => {
       wrapper: createWrapper(durably),
     })
 
-
     const d = durably.register({ testJobHandle: testJob })
 
     await d.jobs.testJobHandle.trigger({ value: 77 })
diff --git a/packages/durably-react/tests/client/use-job-logs.test.tsx b/packages/durably-react/tests/client/use-job-logs.test.tsx
index 85915425..20d78bb6 100644
--- a/packages/durably-react/tests/client/use-job-logs.test.tsx
+++ b/packages/durably-react/tests/client/use-job-logs.test.tsx
@@ -32,7 +32,6 @@ describe('useJobLogs (client)', () => {
       useJobLogs({ api: '/api/durably', runId: 'log-run' }),
     )
 
-
     await waitFor(() => {
       expect(mockEventSource.instances.length).toBeGreaterThan(0)
     })
diff --git a/packages/durably-react/tests/client/use-job-run.test.tsx b/packages/durably-react/tests/client/use-job-run.test.tsx
index 0fb4e216..d5afc5ec 100644
--- a/packages/durably-react/tests/client/use-job-run.test.tsx
+++ b/packages/durably-react/tests/client/use-job-run.test.tsx
@@ -32,7 +32,6 @@ describe('useJobRun (client)', () => {
       useJobRun({ api: '/api/durably', runId: 'existing-run' }),
     )
 
-
     await waitFor(() => {
       expect(mockEventSource.instances.length).toBeGreaterThan(0)
     })
diff --git a/packages/durably-react/tests/client/use-job.test.tsx b/packages/durably-react/tests/client/use-job.test.tsx
index 65f7ecdf..8f2e1049 100644
--- a/packages/durably-react/tests/client/use-job.test.tsx
+++ b/packages/durably-react/tests/client/use-job.test.tsx
@@ -41,7 +41,6 @@ describe('useJob (client)', () => {
       useJob({ api: '/api/durably', jobName: 'test-job' }),
     )
 
-
     const { runId } = await result.current.trigger({ input: 'test' })
 
     expect(fetchMock).toHaveBeenCalledWith(
diff --git a/packages/durably-react/tests/helpers/create-test-durably.ts b/packages/durably-react/tests/helpers/create-test-durably.ts
index 8e912c85..5540ced2 100644
--- a/packages/durably-react/tests/helpers/create-test-durably.ts
+++ b/packages/durably-react/tests/helpers/create-test-durably.ts
@@ -4,11 +4,16 @@ import { createBrowserDialect } from './browser-dialect'
 export interface TestDurablyOptions {
   pollingInterval?: number
   autoMigrate?: boolean
+  /**
+   * Whether to start the worker. When false, only migrate() is called.
+   * @default true
+   */
+  autoStart?: boolean
 }
 
 /**
  * Create a Durably instance for testing.
- * The instance is migrated unless autoMigrate is false.
+ * The instance is initialized (migrate + start) unless autoMigrate is false.
  */
 export async function createTestDurably(
   options?: TestDurablyOptions,
@@ -22,7 +27,13 @@ export async function createTestDurably(
   })
 
   if (options?.autoMigrate !== false) {
-    await durably.migrate()
+    if (options?.autoStart === false) {
+      // Only migrate, don't start the worker
+      await durably.migrate()
+    } else {
+      // Default: init() = migrate() + start()
+      await durably.init()
+    }
   }
 
   return durably
diff --git a/packages/durably-react/tests/types.test.ts b/packages/durably-react/tests/types.test.ts
index dd00d4d8..bb429e71 100644
--- a/packages/durably-react/tests/types.test.ts
+++ b/packages/durably-react/tests/types.test.ts
@@ -33,7 +33,6 @@ describe('Type inference', () => {
     it('infers correct return type', () => {
       type Result = UseJobResult<{ taskId: string }, { success: boolean }>
 
-      expectTypeOf().toEqualTypeOf()
       expectTypeOf().toEqualTypeOf<
         'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | null
       >()
@@ -106,7 +105,6 @@ describe('Type inference', () => {
 
       expectTypeOf().toBeArray()
       expectTypeOf().toBeFunction()
-      expectTypeOf().toEqualTypeOf()
     })
   })
 

From b29e9b5098b79745b9cf6a72bbd581d17526b80c Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 14:01:55 +0900
Subject: [PATCH 095/101] docs: update CHANGELOG and READMEs for 0.6.0 API
 changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Reorganize 0.6.0 changelog for clarity with per-package sections
- Add DurablyProvider simplification to breaking changes
- Document init() method addition
- Update READMEs to use init() instead of migrate()+start()

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 CHANGELOG.md                     | 62 +++++++++++++++++---------------
 packages/durably-react/README.md |  8 ++---
 packages/durably/README.md       |  8 ++---
 3 files changed, 40 insertions(+), 38 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 31cd96c0..ee3b6e3b 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,63 +9,67 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ### Breaking Changes
 
+#### @coji/durably
+
 - **`register()` API simplified**: `registerAll()` renamed to `register()`, old single-job signature removed
-  - New: `const { job } = durably.register({ job: jobDef })`
-  - Old (removed): `const job = durably.register(jobDef)`
+  ```diff
+  - const job = durably.register(jobDef)
+  + const { job } = durably.register({ job: jobDef })
+  ```
+
+#### @coji/durably-react
+
+- **`DurablyProvider` simplified**: Removed `autoStart`, `onReady` props and `isReady` state
+  - Provider now only provides context; durably instance must be initialized before passing
+  - All hooks no longer return `isReady` - always ready when durably is available
+  - Migration: Call `await durably.init()` before passing to `DurablyProvider`
+  ```diff
+  -  console.log('ready')}>
+  + 
+  ```
 
 ### Added
 
 #### @coji/durably
 
-- **Type-safe `durably.jobs` property**: Access registered jobs with full type inference
+- **`init()` method**: Combines `migrate()` and `start()` for simpler initialization
   ```ts
   const durably = createDurably({ dialect })
-    .register({ processImage, syncUsers })
+  await durably.init() // migrate + start in one call
+  ```
+- **Type-safe `durably.jobs` property**: Access registered jobs with full type inference
+  ```ts
+  const durably = createDurably({ dialect }).register({ processImage, syncUsers })
   await durably.jobs.processImage.trigger({ imageId: '123' }) // Type-safe
   ```
 - **Retry from cancelled state**: `retry()` now works on both `failed` and `cancelled` runs
-- **New events for run lifecycle**:
-  - `run:trigger`: Emitted when a job is triggered (before worker picks it up)
-  - `run:cancel`: Emitted when a run is cancelled via `cancel()` API
-  - `run:retry`: Emitted when a failed/cancelled run is retried via `retry()` API
-- **`stepCount` added to `Run` type**: Run now includes `stepCount` property reflecting the number of completed steps
-  - Computed dynamically via JOIN query (no schema change required)
-  - Available in `getRun()`, `getRuns()`, `getNextPendingRun()`
+- **New events**: `run:trigger`, `run:cancel`, `run:retry` for complete run lifecycle tracking
+- **`stepCount` on `Run` type**: Number of completed steps, available in `getRun()`, `getRuns()`
 
 #### @coji/durably/server
 
-- **New endpoints**:
-  - `GET /steps?runId=xxx`: Get steps for a run
-  - `DELETE /run?runId=xxx`: Delete a run
-- **SSE event streaming**: `/runs/subscribe` now streams `run:trigger`, `run:cancel`, `run:retry` events
+- **New endpoints**: `GET /steps?runId=xxx`, `DELETE /run?runId=xxx`
+- **SSE enhancements**: `/runs/subscribe` now streams `run:trigger`, `run:cancel`, `run:retry` events
 
 #### @coji/durably-react
 
-- **`useRuns`**: List and paginate job runs with filtering and real-time updates
-  - Supports filtering by `jobName` and `status`
-  - Built-in pagination with `nextPage`, `prevPage`, `goToPage`
-  - Real-time updates via `realtime` option (default: true)
-- **`useJob` options**:
-  - `autoResume`: Automatically resume tracking pending/running jobs on mount (default: true)
-  - `followLatest`: Automatically switch to tracking the latest running job (default: true)
+- **`useRuns` hook**: List and paginate runs with filtering (`jobName`, `status`) and real-time updates
+- **`useJob` options**: `autoResume` (track pending/running jobs on mount), `followLatest` (switch to latest run)
 - **`createDurablyClient`**: Type-safe client factory for server-connected mode
 - **`createJobHooks`**: Per-job hook factory for server-connected mode
 
 #### @coji/durably-react/client
 
-- **`useRunActions` enhancements**:
-  - `deleteRun(runId)`: Delete a completed/failed/cancelled run
-  - `getRun(runId)`: Get a single run by ID
-  - `getSteps(runId)`: Get steps for a run
-- **`stepCount` and `currentStepIndex`**: Added to `ClientRun` and `RunRecord` types for step progress display
-- **New type exports**: `RunRecord`, `StepRecord` for type-safe run and step data
+- **`useRunActions` enhancements**: `deleteRun()`, `getRun()`, `getSteps()`
+- **Step progress**: `stepCount` and `currentStepIndex` on `ClientRun` and `RunRecord` types
+- **New type exports**: `RunRecord`, `StepRecord`
 
 ### Changed
 
 - Simplified README files - detailed documentation moved to website
 - Updated all examples to use new `register()` API pattern
 - Added Turbo for monorepo task orchestration
-- Unified dashboard UI across all examples (View, Retry, Cancel, Delete, Progress, Steps)
+- Unified dashboard UI across all examples
 
 ### Fixed
 
diff --git a/packages/durably-react/README.md b/packages/durably-react/README.md
index 77da82d5..d18e5cca 100644
--- a/packages/durably-react/README.md
+++ b/packages/durably-react/README.md
@@ -38,12 +38,12 @@ const myJob = defineJob({
 // Initialize Durably
 async function initDurably() {
   const sqlocal = new SQLocalKysely('app.sqlite3')
-  const durably = createDurably({ dialect: sqlocal.dialect })
-  durably.register({ myJob })
-  await durably.migrate()
+  const durably = createDurably({ dialect: sqlocal.dialect }).register({
+    myJob,
+  })
+  await durably.init() // migrate + start
   return durably
 }
-
 const durablyPromise = initDurably()
 
 function App() {
diff --git a/packages/durably/README.md b/packages/durably/README.md
index 0562b33b..d842173c 100644
--- a/packages/durably/README.md
+++ b/packages/durably/README.md
@@ -30,12 +30,10 @@ const myJob = defineJob({
   },
 })
 
-const durably = createDurably({ dialect })
-const jobs = durably.register({ myJob })
+const durably = createDurably({ dialect }).register({ myJob })
 
-await durably.migrate()
-durably.start()
-await jobs.myJob.trigger({ id: '123' })
+await durably.init() // migrate + start
+await durably.jobs.myJob.trigger({ id: '123' })
 ```
 
 ## Documentation

From 73964eda176617ac7a4b8116c7f620d40e928cc6 Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 14:22:12 +0900
Subject: [PATCH 096/101] fix: add real-time step/progress updates to dashboard
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add step:start, step:complete, step:fail, log:write events to SSE /runs/subscribe
- Subscribe to step:start, step:complete, run:progress in browser useRuns hook
- Handle step events in client useRuns for real-time updates
- Fix dashboard display: show stepCount only (not currentStepIndex/stepCount)
- Require React 19+ in peerDependencies (uses React.use() hook)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 .../app/routes/_index/dashboard.tsx           |  4 +-
 .../src/components/dashboard.tsx              |  4 +-
 .../app/routes/_index/dashboard.tsx           |  4 +-
 packages/durably-react/package.json           |  4 +-
 packages/durably-react/src/client/use-runs.ts | 38 +++++++++++
 packages/durably-react/src/hooks/use-runs.ts  |  3 +
 packages/durably/src/server.ts                | 67 +++++++++++++++++++
 7 files changed, 116 insertions(+), 8 deletions(-)

diff --git a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
index b66b0fab..f7571c1f 100644
--- a/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
+++ b/examples/browser-react-router-spa/app/routes/_index/dashboard.tsx
@@ -98,7 +98,7 @@ export function Dashboard() {
                     Status
                   
                   
-                    Step
+                    Steps
                   
                   
                     Progress
@@ -128,7 +128,7 @@ export function Dashboard() {
                     
                       {run.stepCount > 0 ? (
                         
-                          {run.currentStepIndex}/{run.stepCount}
+                          {run.stepCount}
                         
                       ) : (
                         -
diff --git a/examples/browser-vite-react/src/components/dashboard.tsx b/examples/browser-vite-react/src/components/dashboard.tsx
index b66b0fab..f7571c1f 100644
--- a/examples/browser-vite-react/src/components/dashboard.tsx
+++ b/examples/browser-vite-react/src/components/dashboard.tsx
@@ -98,7 +98,7 @@ export function Dashboard() {
                     Status
                   
                   
-                    Step
+                    Steps
                   
                   
                     Progress
@@ -128,7 +128,7 @@ export function Dashboard() {
                     
                       {run.stepCount > 0 ? (
                         
-                          {run.currentStepIndex}/{run.stepCount}
+                          {run.stepCount}
                         
                       ) : (
                         -
diff --git a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
index 69662503..a9cd8211 100644
--- a/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
+++ b/examples/fullstack-react-router/app/routes/_index/dashboard.tsx
@@ -103,7 +103,7 @@ export function Dashboard() {
                     Status
                   
                   
-                    Step
+                    Steps
                   
                   
                     Progress
@@ -133,7 +133,7 @@ export function Dashboard() {
                     
                       {run.stepCount > 0 ? (
                         
-                          {run.currentStepIndex}/{run.stepCount}
+                          {run.stepCount}
                         
                       ) : (
                         -
diff --git a/packages/durably-react/package.json b/packages/durably-react/package.json
index 03d83bcf..02e26b3f 100644
--- a/packages/durably-react/package.json
+++ b/packages/durably-react/package.json
@@ -50,8 +50,8 @@
   },
   "homepage": "https://github.com/coji/durably#readme",
   "peerDependencies": {
-    "react": ">=18.0.0",
-    "react-dom": ">=18.0.0"
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
   },
   "peerDependenciesMeta": {
     "@coji/durably": {
diff --git a/packages/durably-react/src/client/use-runs.ts b/packages/durably-react/src/client/use-runs.ts
index adf7e5ea..2ade34bb 100644
--- a/packages/durably-react/src/client/use-runs.ts
+++ b/packages/durably-react/src/client/use-runs.ts
@@ -35,6 +35,29 @@ type RunUpdateEvent =
       jobName: string
     }
   | { type: 'run:progress'; runId: string; jobName: string; progress: Progress }
+  | {
+      type: 'step:start' | 'step:complete'
+      runId: string
+      jobName: string
+      stepName: string
+      stepIndex: number
+    }
+  | {
+      type: 'step:fail'
+      runId: string
+      jobName: string
+      stepName: string
+      stepIndex: number
+      error: string
+    }
+  | {
+      type: 'log:write'
+      runId: string
+      stepName: string | null
+      level: 'info' | 'warn' | 'error'
+      message: string
+      data: unknown
+    }
 
 export interface UseRunsClientOptions {
   /**
@@ -221,6 +244,21 @@ export function useRuns(options: UseRunsClientOptions): UseRunsClientResult {
             ),
           )
         }
+        // On step complete, update currentStepIndex
+        if (data.type === 'step:complete') {
+          setRuns((prev) =>
+            prev.map((run) =>
+              run.id === data.runId
+                ? { ...run, currentStepIndex: data.stepIndex + 1 }
+                : run,
+            ),
+          )
+        }
+        // On step start or fail, refresh to get latest state
+        if (data.type === 'step:start' || data.type === 'step:fail') {
+          refresh()
+        }
+        // log:write is handled by useJobLogs, not useRuns
       } catch {
         // Ignore parse errors
       }
diff --git a/packages/durably-react/src/hooks/use-runs.ts b/packages/durably-react/src/hooks/use-runs.ts
index 8cc0d1c7..1cd2bc94 100644
--- a/packages/durably-react/src/hooks/use-runs.ts
+++ b/packages/durably-react/src/hooks/use-runs.ts
@@ -123,6 +123,9 @@ export function useRuns(options?: UseRunsOptions): UseRunsResult {
       durably.on('run:fail', refresh),
       durably.on('run:cancel', refresh),
       durably.on('run:retry', refresh),
+      durably.on('run:progress', refresh),
+      durably.on('step:start', refresh),
+      durably.on('step:complete', refresh),
     ]
 
     return () => {
diff --git a/packages/durably/src/server.ts b/packages/durably/src/server.ts
index e9ed0ee1..318bf55b 100644
--- a/packages/durably/src/server.ts
+++ b/packages/durably/src/server.ts
@@ -539,6 +539,69 @@ export function createDurablyHandler(
             controller.enqueue(encoder.encode(data))
           })
 
+          const unsubscribeStepStart = durably.on('step:start', (event) => {
+            if (closed) return
+            if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'step:start',
+              runId: event.runId,
+              jobName: event.jobName,
+              stepName: event.stepName,
+              stepIndex: event.stepIndex,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
+          const unsubscribeStepComplete = durably.on(
+            'step:complete',
+            (event) => {
+              if (closed) return
+              if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+              const data = `data: ${JSON.stringify({
+                type: 'step:complete',
+                runId: event.runId,
+                jobName: event.jobName,
+                stepName: event.stepName,
+                stepIndex: event.stepIndex,
+              })}\n\n`
+              controller.enqueue(encoder.encode(data))
+            },
+          )
+
+          const unsubscribeStepFail = durably.on('step:fail', (event) => {
+            if (closed) return
+            if (jobNameFilter && event.jobName !== jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'step:fail',
+              runId: event.runId,
+              jobName: event.jobName,
+              stepName: event.stepName,
+              stepIndex: event.stepIndex,
+              error: event.error,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
+          const unsubscribeLogWrite = durably.on('log:write', (event) => {
+            if (closed) return
+            // log:write doesn't have jobName, so we can't filter by it
+            // Send all logs when no filter, or skip if filter is set
+            if (jobNameFilter) return
+
+            const data = `data: ${JSON.stringify({
+              type: 'log:write',
+              runId: event.runId,
+              stepName: event.stepName,
+              level: event.level,
+              message: event.message,
+              data: event.data,
+            })}\n\n`
+            controller.enqueue(encoder.encode(data))
+          })
+
           // Store cleanup function for cancel
           ;(controller as unknown as { cleanup: () => void }).cleanup = () => {
             closed = true
@@ -549,6 +612,10 @@ export function createDurablyHandler(
             unsubscribeCancel()
             unsubscribeRetry()
             unsubscribeProgress()
+            unsubscribeStepStart()
+            unsubscribeStepComplete()
+            unsubscribeStepFail()
+            unsubscribeLogWrite()
           }
         },
         cancel(controller) {

From 324ce098a7ee7f1fa5174bff5cc170edf025d97a Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 14:30:24 +0900
Subject: [PATCH 097/101] docs: update website with React 19 requirement and
 SSE events
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add React 19+ requirement note to durably-react index
- Document real-time event subscriptions in useRuns (browser mode)
- Document SSE event subscriptions in useRuns (client mode)
- Update CHANGELOG with complete SSE event list

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 CHANGELOG.md                         |  7 +++++-
 website/api/durably-react/browser.md | 33 ++++++++++++++++++++++------
 website/api/durably-react/client.md  |  7 ++++++
 website/api/durably-react/index.md   |  4 ++++
 4 files changed, 43 insertions(+), 8 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index ee3b6e3b..698beb96 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -27,6 +27,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   -  console.log('ready')}>
   + 
   ```
+- **React 19 required**: `peerDependencies` now requires React 19+ (uses `React.use()` hook)
 
 ### Added
 
@@ -49,11 +50,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 #### @coji/durably/server
 
 - **New endpoints**: `GET /steps?runId=xxx`, `DELETE /run?runId=xxx`
-- **SSE enhancements**: `/runs/subscribe` now streams `run:trigger`, `run:cancel`, `run:retry` events
+- **SSE enhancements**: `/runs/subscribe` now streams all lifecycle events
+  - Run events: `run:trigger`, `run:start`, `run:complete`, `run:fail`, `run:cancel`, `run:retry`, `run:progress`
+  - Step events: `step:start`, `step:complete`, `step:fail`
+  - Log events: `log:write`
 
 #### @coji/durably-react
 
 - **`useRuns` hook**: List and paginate runs with filtering (`jobName`, `status`) and real-time updates
+  - Subscribes to step and progress events for live dashboard updates
 - **`useJob` options**: `autoResume` (track pending/running jobs on mount), `followLatest` (switch to latest run)
 - **`createDurablyClient`**: Type-safe client factory for server-connected mode
 - **`createJobHooks`**: Per-job hook factory for server-connected mode
diff --git a/website/api/durably-react/browser.md b/website/api/durably-react/browser.md
index 73c9f4e8..2e78fb51 100644
--- a/website/api/durably-react/browser.md
+++ b/website/api/durably-react/browser.md
@@ -239,24 +239,35 @@ function LogViewer({ runId }: { runId: string | null }) {
 
 ## useRuns
 
-List runs with optional filtering.
+List runs with optional filtering and real-time updates.
+
+The hook automatically subscribes to Durably events and refreshes the list when runs change. It listens to:
+- `run:trigger`, `run:start`, `run:complete`, `run:fail`, `run:cancel`, `run:retry` - refresh list
+- `run:progress` - update progress in place
+- `step:start`, `step:complete` - refresh for step count updates
 
 ```tsx
 import { useRuns } from '@coji/durably-react'
 
 function RunList() {
-  const { runs, isLoading } = useRuns({
+  const { runs, isLoading, refresh } = useRuns({
     jobName: 'my-job',
     status: 'completed',
     limit: 10,
   })
 
   return (
-    
            
-      {runs.map(run => (
-        
          • {run.status}
            • 
-      ))}
-    
          
+    
          
+      
+      
            
+        {runs.map(run => (
+          
          • 
+            {run.jobName}: {run.status}
+            {run.progress && ` (${run.progress.current}/${run.progress.total})`}
+          
            • 
+        ))}
+      
          
+    
          
   )
 }
 ```
@@ -268,3 +279,11 @@ function RunList() {
 | `jobName` | `string` | Filter by job name |
 | `status` | `RunStatus` | Filter by status |
 | `limit` | `number` | Maximum number of runs to return |
+
+### Return Type
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `runs` | `Run[]` | List of runs |
+| `isLoading` | `boolean` | Loading state |
+| `refresh` | `() => void` | Manually refresh the list |
diff --git a/website/api/durably-react/client.md b/website/api/durably-react/client.md
index 8b8bd75a..bcdbd028 100644
--- a/website/api/durably-react/client.md
+++ b/website/api/durably-react/client.md
@@ -207,6 +207,13 @@ function Component({ runId }: { runId: string }) {
 
 List and paginate job runs with real-time updates on the first page.
 
+The first page (page 0) automatically subscribes to SSE for real-time updates. It listens to:
+- `run:trigger`, `run:start`, `run:complete`, `run:fail`, `run:cancel`, `run:retry` - refresh list
+- `run:progress` - update progress in place
+- `step:start`, `step:complete`, `step:fail` - refresh for step updates
+
+Other pages are static and require manual refresh.
+
 ```tsx
 import { useRuns } from '@coji/durably-react/client'
 
diff --git a/website/api/durably-react/index.md b/website/api/durably-react/index.md
index a9562664..f9a3b10b 100644
--- a/website/api/durably-react/index.md
+++ b/website/api/durably-react/index.md
@@ -2,6 +2,10 @@
 
 React bindings for Durably - hooks for triggering and monitoring jobs.
 
+## Requirements
+
+- **React 19+** (uses `React.use()` for Promise resolution)
+
 ## Installation
 
 ```bash

From 698b4a099d97f36320ff394825c925f59b19ab3a Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 15:06:50 +0900
Subject: [PATCH 098/101] docs(website): restructure API docs with hierarchical
 navigation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Add hierarchical sidebar menus for all major API sections
- Move Core Concepts from Reference to Introduction section
- Add Events submenu (Run/Step/Log/Worker events)
- Add Quick Reference page as API entry point
- Extract HTTP Handler to separate page
- Rename Browser-Complete Mode → Browser Hooks
- Rename Server-Connected Mode → Server Hooks
- Add mode selection guide to React Hooks overview
- Add explanations before code blocks in guide pages
- Change npm to pnpm in installation instructions

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 website/.vitepress/config.ts                  | 114 +++++-
 website/api/create-durably.md                 |  84 +----
 website/api/durably-react/browser.md          |   4 +-
 website/api/durably-react/client.md           |   4 +-
 website/api/durably-react/index.md            | 223 ++++++++++--
 website/api/http-handler.md                   | 199 +++++++++++
 website/api/index.md                          | 324 +++++++++++-------
 website/guide/background-sync.md              |  22 +-
 website/guide/csv-import.md                   |  14 +
 website/guide/getting-started.md              |  47 ++-
 website/guide/index.md                        |   2 +-
 website/guide/offline-app.md                  |  18 +-
 .../images/getting-started-overview.svg       |  74 ++--
 13 files changed, 823 insertions(+), 306 deletions(-)
 create mode 100644 website/api/http-handler.md

diff --git a/website/.vitepress/config.ts b/website/.vitepress/config.ts
index 1a0310b1..bbd99a6b 100644
--- a/website/.vitepress/config.ts
+++ b/website/.vitepress/config.ts
@@ -24,6 +24,7 @@ export default defineConfig({
           items: [
             { text: 'What is Durably?', link: '/guide/' },
             { text: 'Getting Started', link: '/guide/getting-started' },
+            { text: 'Core Concepts', link: '/guide/concepts' },
           ],
         },
         {
@@ -34,31 +35,116 @@ export default defineConfig({
             { text: 'Background Sync (Server)', link: '/guide/background-sync' },
           ],
         },
+      ],
+      '/api/': [
         {
-          text: 'Reference',
+          text: 'Getting Started',
           items: [
-            { text: 'Core Concepts', link: '/guide/concepts' },
+            { text: 'Quick Reference', link: '/api/' },
+          ],
+        },
+        {
+          text: 'Job Definition',
+          items: [
+            {
+              text: 'defineJob',
+              link: '/api/define-job',
+              collapsed: false,
+              items: [
+                { text: 'trigger', link: '/api/define-job#trigger' },
+                { text: 'triggerAndWait', link: '/api/define-job#triggerandwait' },
+                { text: 'batchTrigger', link: '/api/define-job#batchtrigger' },
+              ],
+            },
+            {
+              text: 'Step Context',
+              link: '/api/step',
+              collapsed: false,
+              items: [
+                { text: 'step.run', link: '/api/step#run' },
+                { text: 'step.progress', link: '/api/step#progress' },
+                { text: 'step.log', link: '/api/step#log' },
+              ],
+            },
+          ],
+        },
+        {
+          text: 'Instance & Lifecycle',
+          items: [
+            {
+              text: 'createDurably',
+              link: '/api/create-durably',
+              collapsed: false,
+              items: [
+                { text: 'init / migrate / start', link: '/api/create-durably#init' },
+                { text: 'register', link: '/api/create-durably#register' },
+                { text: 'on (events)', link: '/api/create-durably#on' },
+                { text: 'stop', link: '/api/create-durably#stop' },
+                { text: 'retry / cancel', link: '/api/create-durably#retry' },
+                { text: 'getRun / getRuns', link: '/api/create-durably#getrun' },
+              ],
+            },
+            {
+              text: 'Events',
+              link: '/api/events',
+              collapsed: false,
+              items: [
+                { text: 'Run Events', link: '/api/events#run-events' },
+                { text: 'Step Events', link: '/api/events#step-events' },
+                { text: 'Log Events', link: '/api/events#log-events' },
+                { text: 'Worker Events', link: '/api/events#worker-events' },
+              ],
+            },
           ],
         },
-      ],
-      '/api/': [
         {
-          text: 'Core API',
+          text: 'Server Integration',
           items: [
-            { text: 'Overview', link: '/api/' },
-            { text: 'createDurably', link: '/api/create-durably' },
-            { text: 'defineJob', link: '/api/define-job' },
-            { text: 'Step', link: '/api/step' },
-            { text: 'Events', link: '/api/events' },
+            {
+              text: 'HTTP Handler',
+              link: '/api/http-handler',
+              collapsed: false,
+              items: [
+                { text: 'createDurablyHandler', link: '/api/http-handler#createdurablyhandler' },
+                { text: 'Framework Integration', link: '/api/http-handler#framework-integration' },
+                { text: 'Endpoints', link: '/api/http-handler#endpoints' },
+                { text: 'SSE Events', link: '/api/http-handler#sse-event-stream' },
+                { text: 'Security', link: '/api/http-handler#security-considerations' },
+              ],
+            },
           ],
         },
         {
-          text: 'React API',
+          text: 'React Hooks',
           items: [
             { text: 'Overview', link: '/api/durably-react/' },
-            { text: 'Browser Mode', link: '/api/durably-react/browser' },
-            { text: 'Server Mode', link: '/api/durably-react/client' },
-            { text: 'Types', link: '/api/durably-react/types' },
+            {
+              text: 'Browser Hooks',
+              link: '/api/durably-react/browser',
+              collapsed: false,
+              items: [
+                { text: 'DurablyProvider', link: '/api/durably-react/browser#durablyprovider' },
+                { text: 'useDurably', link: '/api/durably-react/browser#usedurably' },
+                { text: 'useJob', link: '/api/durably-react/browser#usejob' },
+                { text: 'useJobRun', link: '/api/durably-react/browser#usejobrun' },
+                { text: 'useJobLogs', link: '/api/durably-react/browser#usejoblogs' },
+                { text: 'useRuns', link: '/api/durably-react/browser#useruns' },
+              ],
+            },
+            {
+              text: 'Server Hooks',
+              link: '/api/durably-react/client',
+              collapsed: false,
+              items: [
+                { text: 'createDurablyClient', link: '/api/durably-react/client#createdurablyclient' },
+                { text: 'useJob', link: '/api/durably-react/client#usejob' },
+                { text: 'useJobRun', link: '/api/durably-react/client#usejobrun' },
+                { text: 'useJobLogs', link: '/api/durably-react/client#usejoblogs' },
+                { text: 'useRuns', link: '/api/durably-react/client#useruns' },
+                { text: 'useRunActions', link: '/api/durably-react/client#userunactions' },
+              ],
+            },
+            { text: 'Type Definitions', link: '/api/durably-react/types' },
           ],
         },
       ],
diff --git a/website/api/create-durably.md b/website/api/create-durably.md
index 792eaca3..306b2729 100644
--- a/website/api/create-durably.md
+++ b/website/api/create-durably.md
@@ -201,84 +201,8 @@ process.on('SIGTERM', async () => {
 })
 ```
 
-## createDurablyHandler
+## See Also
 
-Create HTTP handlers for exposing Durably via REST/SSE. Import from `@coji/durably/server`.
-
-```ts
-import { createDurablyHandler } from '@coji/durably/server'
-
-const handler = createDurablyHandler(durably, {
-  onRequest: async () => {
-    await durably.init()
-  },
-})
-```
-
-### Options
-
-```ts
-interface CreateDurablyHandlerOptions {
-  /** Called before handling each request */
-  onRequest?: () => Promise | void
-}
-```
-
-### handle(request, basePath)
-
-Handle all Durably HTTP requests with automatic routing.
-
-```ts
-// React Router / Remix
-export async function loader({ request }) {
-  return handler.handle(request, '/api/durably')
-}
-
-export async function action({ request }) {
-  return handler.handle(request, '/api/durably')
-}
-```
-
-### Routes
-
-| Method | Path | Description |
-|--------|------|-------------|
-| `GET` | `/subscribe?runId=xxx` | SSE stream for run events |
-| `GET` | `/runs` | List runs (query: jobName, status, limit, offset) |
-| `GET` | `/run?runId=xxx` | Get single run |
-| `GET` | `/steps?runId=xxx` | Get steps for a run |
-| `GET` | `/runs/subscribe` | SSE stream for run list updates |
-| `POST` | `/trigger` | Trigger a job |
-| `POST` | `/retry?runId=xxx` | Retry a failed run |
-| `POST` | `/cancel?runId=xxx` | Cancel a run |
-| `DELETE` | `/run?runId=xxx` | Delete a run |
-
-### Individual Handlers
-
-For custom routing, use individual handlers:
-
-```ts
-app.post('/api/durably/trigger', (req) => handler.trigger(req))
-app.get('/api/durably/subscribe', (req) => handler.subscribe(req))
-app.get('/api/durably/runs', (req) => handler.runs(req))
-app.get('/api/durably/run', (req) => handler.run(req))
-app.get('/api/durably/steps', (req) => handler.steps(req))
-app.post('/api/durably/retry', (req) => handler.retry(req))
-app.post('/api/durably/cancel', (req) => handler.cancel(req))
-app.delete('/api/durably/run', (req) => handler.delete(req))
-app.get('/api/durably/runs/subscribe', (req) => handler.runsSubscribe(req))
-```
-
-### Trigger Request Format
-
-```ts
-// POST /api/durably/trigger
-{
-  "jobName": "import-csv",
-  "input": { "file": "data.csv" },
-  "idempotencyKey": "unique-key",  // optional
-  "concurrencyKey": "user-123"      // optional
-}
-
-// Response: { "runId": "run_abc123" }
-```
+- [HTTP Handler](/api/http-handler) — Expose Durably via HTTP/SSE for React clients
+- [defineJob](/api/define-job) — Define jobs with typed schemas
+- [Events](/api/events) — Subscribe to run and step events
diff --git a/website/api/durably-react/browser.md b/website/api/durably-react/browser.md
index 2e78fb51..e3ae3a26 100644
--- a/website/api/durably-react/browser.md
+++ b/website/api/durably-react/browser.md
@@ -1,6 +1,6 @@
-# Browser-Complete Mode
+# Browser Hooks
 
-Run Durably entirely in the browser using SQLite WASM with OPFS persistence.
+Run Durably entirely in the browser using SQLite WASM with OPFS persistence. Jobs execute client-side with data stored in the browser's Origin Private File System.
 
 ```tsx
 import { DurablyProvider, useDurably, useJob, useJobRun, useJobLogs, useRuns } from '@coji/durably-react'
diff --git a/website/api/durably-react/client.md b/website/api/durably-react/client.md
index bcdbd028..9223246a 100644
--- a/website/api/durably-react/client.md
+++ b/website/api/durably-react/client.md
@@ -1,6 +1,6 @@
-# Server-Connected Mode
+# Server Hooks
 
-Connect to a Durably server via HTTP/SSE for real-time job monitoring.
+Connect to a Durably server via HTTP/SSE for real-time job monitoring. Jobs run on the server with updates streamed to the client.
 
 ```tsx
 import {
diff --git a/website/api/durably-react/index.md b/website/api/durably-react/index.md
index f9a3b10b..a602b63f 100644
--- a/website/api/durably-react/index.md
+++ b/website/api/durably-react/index.md
@@ -1,68 +1,219 @@
-# durably-react
+# React Hooks
 
-React bindings for Durably - hooks for triggering and monitoring jobs.
+React bindings for Durably - hooks for triggering and monitoring jobs with real-time updates.
 
 ## Requirements
 
 - **React 19+** (uses `React.use()` for Promise resolution)
 
+## Which Mode Should I Use?
+
+Durably React provides two modes for different architectures:
+
+| Question | Browser Hooks | Server Hooks |
+|----------|---------------|--------------|
+| Where do jobs run? | In the browser | On the server |
+| Where is data stored? | Browser OPFS | Server database |
+| Works offline? | Yes | No |
+| Share state across tabs/users? | No | Yes |
+| Needs backend? | No | Yes |
+
+### Choose Browser Hooks when:
+
+- Building **offline-capable** or **local-first** apps
+- Data should stay on the user's device
+- Prototyping without a backend
+- Single-user, single-tab usage
+
+```tsx
+import { DurablyProvider, useJob } from '@coji/durably-react'
+```
+
+[Browser Hooks Reference →](./browser)
+
+### Choose Server Hooks when:
+
+- Building **full-stack** applications
+- Jobs need server resources (databases, APIs, secrets)
+- Multiple users or tabs need to see the same state
+- Need persistent storage across devices
+
+```tsx
+import { createDurablyClient } from '@coji/durably-react/client'
+```
+
+[Server Hooks Reference →](./client)
+
 ## Installation
 
 ```bash
-# Browser-complete mode (runs Durably entirely in browser)
-npm install @coji/durably-react @coji/durably kysely zod sqlocal
+# Browser mode - runs Durably in the browser
+pnpm add @coji/durably @coji/durably-react kysely zod sqlocal
 
-# Server-connected mode (connects to server via HTTP/SSE)
-npm install @coji/durably-react
+# Server mode - connects to Durably server
+pnpm add @coji/durably-react
 ```
 
-## Two Modes
+## Quick Examples
 
-Durably React provides two distinct modes for different use cases:
+### Browser Mode
 
-### Browser-Complete Mode
-
-Run Durably entirely in the browser using SQLite WASM with OPFS. All job execution happens client-side.
+Jobs run entirely in the browser with OPFS persistence.
 
 ```tsx
 import { DurablyProvider, useJob } from '@coji/durably-react'
+import { durably } from './lib/durably'
+import { importCsvJob } from './jobs/import-csv'
+
+function App() {
+  return (
+    Loading...
          }>
+      
+              
+  )
+}
+
+function ImportButton() {
+  const { trigger, progress, isRunning, isCompleted, output } = useJob(importCsvJob)
+
+  return (
+    
          
+      
+      {progress && 
          {progress.current}/{progress.total}
          }
+      {isCompleted && 
          Done: {output?.count} rows
          }
+    
          
+  )
+}
 ```
 
-**Use when:**
-- Building offline-capable applications
-- Local-first apps where data stays on device
-- Prototyping without a backend
+### Server Mode
 
-[Browser-Complete Mode Reference →](./browser)
+Jobs run on the server, with real-time updates via SSE.
 
-### Server-Connected Mode
+```tsx
+// 1. Create type-safe client (client-side file)
+import { createDurablyClient } from '@coji/durably-react/client'
+import type { durably } from './durably.server'
+
+export const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+
+// 2. Use in components
+function ImportButton() {
+  const { trigger, progress, isRunning, isCompleted, output } =
+    durablyClient.importCsv.useJob()
+
+  return (
+    
          
+      
+      {progress && 
          {progress.current}/{progress.total}
          }
+      {isCompleted && 
          Done: {output?.count} rows
          }
+    
          
+  )
+}
+```
+
+## Available Hooks
+
+### Both Modes
+
+| Hook | Description |
+|------|-------------|
+| `useJob` | Trigger and monitor a job |
+| `useJobRun` | Subscribe to an existing run by ID |
+| `useJobLogs` | Subscribe to logs from a run |
+| `useRuns` | List runs with filtering and pagination |
+
+### Browser Mode Only
+
+| Hook | Description |
+|------|-------------|
+| `useDurably` | Access the Durably instance directly |
+
+### Server Mode Only
+
+| Hook | Description |
+|------|-------------|
+| `useRunActions` | Retry, cancel, delete runs |
 
-Connect to a Durably server via HTTP/SSE. Jobs execute on the server, with real-time updates streamed to the client.
+## Common Patterns
+
+### Show Progress Bar
 
 ```tsx
-import { createDurablyClient } from '@coji/durably-react/client'
+function ProgressBar({ runId }: { runId: string }) {
+  const { progress, isRunning } = useJobRun({ runId })
+
+  if (!isRunning || !progress) return null
+
+  const percent = Math.round((progress.current / progress.total) * 100)
+
+  return (
+    
          
+      
+      {percent}% - {progress.message}
+    
          
+  )
+}
 ```
 
-**Use when:**
-- Building full-stack applications
-- Jobs need server-side resources (databases, APIs)
-- Sharing job state across multiple clients
+### Handle Errors
 
-[Server-Connected Mode Reference →](./client)
+```tsx
+function JobRunner() {
+  const { trigger, isFailed, error, reset } = useJob(myJob)
+
+  if (isFailed) {
+    return (
+      
          
+        
          Error: {error}
          
+        
+      
          
+    )
+  }
+
+  return 
+}
+```
 
-## Quick Comparison
+### Run Dashboard (Server Mode)
 
-| Feature | Browser-Complete | Server-Connected |
-|---------|------------------|------------------|
-| Import | `@coji/durably-react` | `@coji/durably-react/client` |
-| Job Execution | Client-side | Server-side |
-| Persistence | OPFS (browser) | Server database |
-| Offline Support | Yes | No |
-| Multi-client | No (single tab) | Yes |
-| Setup | DurablyProvider | API endpoint |
+```tsx
+function Dashboard() {
+  const { runs, page, hasMore, nextPage, prevPage } = useRuns({
+    api: '/api/durably',
+    pageSize: 10,
+  })
+  const { retry, cancel, deleteRun } = useRunActions({ api: '/api/durably' })
+
+  return (
+    
+      
+        
+      
+      
+        {runs.map(run => (
+          
+            
+            
+            
+          
+        ))}
+      
+    
          JobStatusActions
          {run.jobName}{run.status}
+              {run.status === 'failed' && }
+              {run.status === 'running' && }
+              
+            
          
+  )
+}
+```
 
 ## Type Definitions
 
-Common types used across both modes.
-
-[Type Definitions →](./types)
+See [Type Definitions](./types) for all exported types.
diff --git a/website/api/http-handler.md b/website/api/http-handler.md
new file mode 100644
index 00000000..9b4b47a9
--- /dev/null
+++ b/website/api/http-handler.md
@@ -0,0 +1,199 @@
+# HTTP Handler
+
+Expose Durably via HTTP/SSE endpoints for React clients and external integrations.
+
+## createDurablyHandler
+
+Create a handler that routes HTTP requests to the appropriate Durably operations.
+
+```ts
+import { createDurablyHandler } from '@coji/durably'
+
+const handler = createDurablyHandler(durably, {
+  onRequest: async () => {
+    // Called before each request - useful for lazy initialization
+    await durably.init()
+  },
+})
+```
+
+### Options
+
+```ts
+interface CreateDurablyHandlerOptions {
+  /** Called before handling each request */
+  onRequest?: () => Promise | void
+}
+```
+
+## Framework Integration
+
+### React Router / Remix
+
+Use a splat route to handle all Durably endpoints under a single path.
+
+```ts
+// app/routes/api.durably.$.ts
+import { durablyHandler } from '~/lib/durably.server'
+import type { Route } from './+types/api.durably.$'
+
+export async function loader({ request }: Route.LoaderArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+```
+
+### Next.js
+
+```ts
+// app/api/durably/[...path]/route.ts
+import { durablyHandler } from '@/lib/durably'
+
+export async function GET(request: Request) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function POST(request: Request) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function DELETE(request: Request) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+```
+
+### Express / Hono
+
+```ts
+// Express
+app.use('/api/durably', async (req, res, next) => {
+  const request = new Request(`http://localhost${req.url}`, {
+    method: req.method,
+    headers: req.headers,
+    body: req.method !== 'GET' ? JSON.stringify(req.body) : undefined,
+  })
+  const response = await handler.handle(request, '/api/durably')
+  res.status(response.status)
+  response.headers.forEach((v, k) => res.setHeader(k, v))
+  res.send(await response.text())
+})
+
+// Hono
+app.all('/api/durably/*', (c) => handler.handle(c.req.raw, '/api/durably'))
+```
+
+## Endpoints
+
+The handler provides these endpoints:
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/trigger` | Trigger a job |
+| `GET` | `/subscribe?runId=xxx` | SSE stream for run events |
+| `GET` | `/runs` | List runs with filtering |
+| `GET` | `/run?runId=xxx` | Get single run |
+| `GET` | `/steps?runId=xxx` | Get steps for a run |
+| `GET` | `/runs/subscribe` | SSE stream for run list updates |
+| `POST` | `/retry?runId=xxx` | Retry a failed run |
+| `POST` | `/cancel?runId=xxx` | Cancel a running job |
+| `DELETE` | `/run?runId=xxx` | Delete a run |
+
+## Trigger Request
+
+```ts
+// POST /api/durably/trigger
+{
+  "jobName": "import-csv",
+  "input": { "filename": "data.csv" },
+  "idempotencyKey": "unique-key",   // optional
+  "concurrencyKey": "user-123"      // optional
+}
+
+// Response
+{ "runId": "run_abc123" }
+```
+
+## SSE Event Stream
+
+The `/subscribe` endpoint returns Server-Sent Events for real-time updates.
+
+```ts
+// GET /api/durably/subscribe?runId=run_abc123
+
+// Events:
+data: {"type":"run:start","runId":"run_abc123","jobName":"import-csv",...}
+
+data: {"type":"run:progress","runId":"run_abc123","progress":{"current":1,"total":10},...}
+
+data: {"type":"step:complete","runId":"run_abc123","stepName":"parse",...}
+
+data: {"type":"run:complete","runId":"run_abc123","output":{"count":10},...}
+```
+
+The stream closes automatically when the run completes or fails.
+
+## List Runs
+
+```ts
+// GET /api/durably/runs?jobName=import-csv&status=completed&limit=10&offset=0
+
+// Response
+{
+  "runs": [
+    {
+      "id": "run_abc123",
+      "jobName": "import-csv",
+      "status": "completed",
+      "input": { "filename": "data.csv" },
+      "output": { "count": 10 },
+      "createdAt": "2024-01-01T00:00:00.000Z",
+      "completedAt": "2024-01-01T00:01:00.000Z"
+    }
+  ],
+  "total": 100,
+  "hasMore": true
+}
+```
+
+## Individual Handlers
+
+For custom routing, access individual handlers directly:
+
+```ts
+const handler = createDurablyHandler(durably)
+
+// Use specific handlers
+app.post('/jobs/trigger', (req) => handler.trigger(req))
+app.get('/jobs/subscribe', (req) => handler.subscribe(req))
+app.get('/jobs/runs', (req) => handler.runs(req))
+app.get('/jobs/run', (req) => handler.run(req))
+app.get('/jobs/steps', (req) => handler.steps(req))
+app.post('/jobs/retry', (req) => handler.retry(req))
+app.post('/jobs/cancel', (req) => handler.cancel(req))
+app.delete('/jobs/run', (req) => handler.delete(req))
+app.get('/jobs/runs/subscribe', (req) => handler.runsSubscribe(req))
+```
+
+## Security Considerations
+
+The handler exposes all registered jobs and run data. In production:
+
+1. **Authentication**: Add middleware to verify requests before reaching the handler
+2. **Authorization**: Check user permissions for specific jobs or runs
+3. **Rate Limiting**: Protect against abuse
+
+```ts
+// Example with authentication middleware
+export async function action({ request }: Route.ActionArgs) {
+  const user = await getUser(request)
+  if (!user) {
+    return new Response('Unauthorized', { status: 401 })
+  }
+
+  // Add user context to the request if needed
+  return durablyHandler.handle(request, '/api/durably')
+}
+```
diff --git a/website/api/index.md b/website/api/index.md
index 6015d60a..4d5ac289 100644
--- a/website/api/index.md
+++ b/website/api/index.md
@@ -1,156 +1,238 @@
-# API Reference
+# Quick Reference
 
-Complete API documentation for Durably.
+A one-page overview of the Durably API. Use this as a cheat sheet or starting point.
 
-## Core API (@coji/durably)
+## Installation
 
-| Export | Description |
-|--------|-------------|
-| [`createDurably`](/api/create-durably) | Create a Durably instance |
-| [`defineJob`](/api/define-job) | Define a job with type-safe schema |
-| [`Step`](/api/step) | Step context for job handlers |
-| [`Events`](/api/events) | Event types and subscriptions |
-
-## React API (@coji/durably-react)
-
-### Browser-Complete Mode
-
-| Export | Description |
-|--------|-------------|
-| [`DurablyProvider`](/api/durably-react/browser#durablyprovider) | React context provider |
-| [`useDurably`](/api/durably-react/browser#usedurably) | Access Durably instance directly |
-| [`useJob`](/api/durably-react/browser#usejob) | Trigger and monitor a job |
-| [`useJobRun`](/api/durably-react/browser#usejobrun) | Subscribe to an existing run |
-| [`useJobLogs`](/api/durably-react/browser#usejoblogs) | Subscribe to logs from a run |
-| [`useRuns`](/api/durably-react/browser#useruns) | List runs with filtering |
-
-### Server-Connected Mode (@coji/durably-react/client)
+```bash
+# Core package
+pnpm add @coji/durably kysely zod
 
-| Export | Description |
-|--------|-------------|
-| [`createDurablyClient`](/api/durably-react/client#createdurablyclient) | Type-safe client for server mode |
-| [`useJob`](/api/durably-react/client#usejob) | Trigger job via HTTP |
-| [`useJobRun`](/api/durably-react/client#usejobrun) | Subscribe to run via SSE |
-| [`useJobLogs`](/api/durably-react/client#usejoblogs) | Subscribe to logs via SSE |
-| [`useRuns`](/api/durably-react/client#useruns) | List and paginate runs |
-| [`useRunActions`](/api/durably-react/client#userunactions) | Run actions (cancel, retry, delete) |
+# React bindings (optional)
+pnpm add @coji/durably-react
 
-[Full React API Reference →](/api/durably-react/)
+# SQLite driver (choose one)
+pnpm add @libsql/client @libsql/kysely-libsql  # Server (libSQL/Turso)
+pnpm add sqlocal                                # Browser (OPFS)
+```
 
-## Server API (@coji/durably)
+## Define a Job
 
-| Export | Description |
-|--------|-------------|
-| [`createDurablyHandler`](/api/create-durably#createdurablyhandler) | Create HTTP handlers for Durably |
+Jobs are the core unit of work. Each job has a name, input schema, and a run function.
 
-## Quick Start
+```ts
+import { defineJob } from '@coji/durably'
+import { z } from 'zod'
 
-### Installation
+const importCsvJob = defineJob({
+  name: 'import-csv',
+  input: z.object({ filename: z.string() }),
+  output: z.object({ count: z.number() }),
+  run: async (step, payload) => {
+    // Step 1: Parse file (cached on resume)
+    const rows = await step.run('parse', async () => {
+      return parseCSV(payload.filename)
+    })
+
+    // Step 2: Import each row
+    for (const [i, row] of rows.entries()) {
+      await step.run(`import-${i}`, () => db.insert(row))
+      step.progress(i + 1, rows.length, `Importing row ${i + 1}`)
+    }
 
-```bash
-# Core package
-npm install @coji/durably kysely zod
+    step.log.info('Import complete', { count: rows.length })
+    return { count: rows.length }
+  },
+})
+```
 
-# React bindings (optional)
-npm install @coji/durably-react
+**See:** [defineJob](/api/define-job) | [Step Context](/api/step)
 
-# SQLite driver (choose one)
-npm install @libsql/kysely-libsql   # Server (libSQL/Turso)
-npm install sqlocal                  # Browser (OPFS)
-```
+## Create Instance
 
-### Basic Setup
+Create a Durably instance with a SQLite dialect and register jobs.
 
 ```ts
-import { createDurably, defineJob } from '@coji/durably'
+import { createDurably } from '@coji/durably'
 import { LibsqlDialect } from '@libsql/kysely-libsql'
 import { createClient } from '@libsql/client'
-import { z } from 'zod'
 
-// 1. Create SQLite dialect
 const client = createClient({ url: 'file:local.db' })
 const dialect = new LibsqlDialect({ client })
 
-// 2. Define job
-const processDataJob = defineJob({
-  name: 'process-data',
-  input: z.object({ items: z.array(z.string()) }),
-  output: z.object({ count: z.number() }),
-  run: async (step, payload) => {
-    for (let i = 0; i < payload.items.length; i++) {
-      await step.run(`process-${i}`, async () => {
-        // Process item
-      })
-      step.progress(i + 1, payload.items.length)
-    }
-    return { count: payload.items.length }
-  },
+const durably = createDurably({
+  dialect,
+  pollingInterval: 1000,    // Check for jobs every 1s
+  heartbeatInterval: 5000,  // Heartbeat every 5s
+  staleThreshold: 30000,    // Stale after 30s
+}).register({
+  importCsv: importCsvJob,
 })
 
-// 3. Create Durably instance with registered jobs
-const durably = createDurably({ dialect }).register({
-  processData: processDataJob,
+await durably.init()  // Migrate DB + start worker
+```
+
+**See:** [createDurably](/api/create-durably)
+
+## Trigger Jobs
+
+```ts
+// Fire and forget
+const run = await durably.jobs.importCsv.trigger({ filename: 'data.csv' })
+console.log('Started:', run.id)
+
+// Wait for completion
+const { id, output } = await durably.jobs.importCsv.triggerAndWait({
+  filename: 'data.csv'
 })
+console.log('Done:', output.count)
+
+// With options
+await durably.jobs.importCsv.trigger(
+  { filename: 'data.csv' },
+  {
+    idempotencyKey: 'import-2024-01-01',  // Prevent duplicates
+    concurrencyKey: 'csv-imports',         // Limit concurrency
+  }
+)
+```
+
+## Monitor Events
+
+```ts
+durably.on('run:start', (e) => console.log(`Started: ${e.jobName}`))
+durably.on('run:complete', (e) => console.log(`Done in ${e.duration}ms`))
+durably.on('run:fail', (e) => console.error(`Failed: ${e.error}`))
+durably.on('run:progress', (e) => console.log(`${e.progress.current}/${e.progress.total}`))
+```
+
+**See:** [Events](/api/events)
+
+## Server Integration
+
+Expose Durably via HTTP/SSE for React clients.
+
+```ts
+import { createDurablyHandler } from '@coji/durably'
+
+const handler = createDurablyHandler(durably)
+
+// React Router / Remix
+export async function loader({ request }) {
+  return handler.handle(request, '/api/durably')
+}
+
+export async function action({ request }) {
+  return handler.handle(request, '/api/durably')
+}
+```
+
+**See:** [HTTP Handler](/api/http-handler)
+
+## React Hooks
+
+### Server-Connected (Full-Stack)
+
+Connect to a Durably server via HTTP/SSE.
+
+```tsx
+// 1. Create type-safe client
+import { createDurablyClient } from '@coji/durably-react/client'
+import type { durably } from './durably.server'
+
+const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+
+// 2. Use in components
+function ImportButton() {
+  const { trigger, progress, isRunning, isCompleted, output } =
+    durablyClient.importCsv.useJob()
+
+  return (
+    
          
+      
+      {progress && 
          {progress.current}/{progress.total}
          }
+      {isCompleted && 
          Imported {output?.count} rows
          }
+    
          
+  )
+}
+```
+
+### Browser-Only (Offline)
+
+Run Durably entirely in the browser with OPFS persistence.
 
-// 4. Initialize and start
-await durably.migrate()
-durably.start()
+```tsx
+import { DurablyProvider, useJob } from '@coji/durably-react'
+import { durably } from './durably'
+import { importCsvJob } from './jobs'
 
-// 5. Trigger a job
-const run = await durably.jobs.processData.trigger({ items: ['a', 'b', 'c'] })
-console.log('Run ID:', run.id)
+function App() {
+  return (
+    Loading...
          }>
+      
+              
+  )
+}
+
+function ImportButton() {
+  const { trigger, progress, isRunning } = useJob(importCsvJob)
+  // ...
+}
 ```
 
+**See:** [React Hooks Overview](/api/durably-react/) | [Browser Hooks](/api/durably-react/browser) | [Server Hooks](/api/durably-react/client)
+
+## API at a Glance
+
+### Core (@coji/durably)
+
+| Export | Description |
+|--------|-------------|
+| `createDurably(options)` | Create instance with SQLite dialect |
+| `defineJob(config)` | Define a job with typed schema |
+| `createDurablyHandler(durably)` | Create HTTP/SSE handler |
+
+### Instance Methods
+
+| Method | Description |
+|--------|-------------|
+| `init()` | Migrate database and start worker |
+| `register(jobs)` | Register job definitions |
+| `on(event, handler)` | Subscribe to events |
+| `stop()` | Stop worker gracefully |
+| `retry(runId)` | Retry failed run |
+| `cancel(runId)` | Cancel running job |
+
+### Step Context
+
+| Method | Description |
+|--------|-------------|
+| `step.run(name, fn)` | Create resumable checkpoint |
+| `step.progress(current, total, msg)` | Report progress |
+| `step.log.info/warn/error(msg)` | Write structured logs |
+
+### React Hooks (@coji/durably-react)
+
+| Hook | Mode | Description |
+|------|------|-------------|
+| `useJob` | Both | Trigger and monitor jobs |
+| `useJobRun` | Both | Subscribe to existing run |
+| `useRuns` | Both | List runs with pagination |
+| `useRunActions` | Server | Retry, cancel, delete runs |
+| `useDurably` | Browser | Access Durably instance |
+
 ## Type Exports
 
 ```ts
 import type {
-  // Core
-  Durably,
-  DurablyOptions,
-  DurablyPlugin,
-
-  // Job
-  JobDefinition,
-  JobHandle,
-  JobInput,
-  JobOutput,
-
-  // Step
-  StepContext,
-
-  // Run
-  Run,
-  RunFilter,
-  RunStatus,
+  Durably, DurablyOptions,
+  JobDefinition, JobHandle,
+  StepContext, Run, RunStatus,
   TriggerOptions,
-  TriggerAndWaitResult,
-
-  // Events
-  DurablyEvent,
-  EventType,
-  EventListener,
-  Unsubscribe,
-  ErrorHandler,
-  RunStartEvent,
-  RunCompleteEvent,
-  RunFailEvent,
-  RunProgressEvent,
-  StepStartEvent,
-  StepCompleteEvent,
-  StepFailEvent,
-  LogWriteEvent,
-  WorkerErrorEvent,
-
-  // Server
-  DurablyHandler,
-  TriggerRequest,
-  TriggerResponse,
-
-  // Database (advanced)
-  Database,
-  RunsTable,
-  StepsTable,
-  LogsTable,
+  DurablyEvent, EventType,
 } from '@coji/durably'
 ```
diff --git a/website/guide/background-sync.md b/website/guide/background-sync.md
index a3a05cc5..6e7c1237 100644
--- a/website/guide/background-sync.md
+++ b/website/guide/background-sync.md
@@ -14,7 +14,7 @@ Run batch jobs on Node.js without a frontend. Perfect for cron jobs, data pipeli
 ## Installation
 
 ```bash
-npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
+pnpm add @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
 ```
 
 ## Project Structure
@@ -32,6 +32,8 @@ npm install @coji/durably kysely zod @libsql/client @libsql/kysely-libsql
 
 ### Database
 
+Create a libsql dialect for SQLite persistence. Supports both local files and Turso cloud databases.
+
 ```ts
 // lib/database.ts
 import { LibsqlDialect } from '@libsql/kysely-libsql'
@@ -44,6 +46,8 @@ export const dialect = new LibsqlDialect({
 
 ### Job Definition
 
+Define a job with multiple steps. Each `step.run()` creates a checkpoint - if the process crashes, it resumes from the last completed step.
+
 ```ts
 // jobs/process-image.ts
 import { defineJob } from '@coji/durably'
@@ -81,6 +85,8 @@ export const processImageJob = defineJob({
 
 ### Durably Instance
 
+Create the Durably instance and register jobs. The shorter intervals are suitable for development; use longer intervals in production to reduce database load.
+
 ```ts
 // lib/durably.ts
 import { createDurably } from '@coji/durably'
@@ -99,6 +105,8 @@ export const durably = createDurably({
 
 ## Basic Usage
 
+Use `triggerAndWait()` to trigger a job and wait for completion. This blocks until the job finishes and returns the output.
+
 ```ts
 // basic.ts
 import { durably } from './lib/durably'
@@ -123,6 +131,8 @@ main().catch(console.error)
 
 ## Event Monitoring
 
+Subscribe to events to monitor job execution. Useful for logging, metrics, and debugging.
+
 ```ts
 durably.on('run:start', (event) => {
   console.log(`[run:start] ${event.jobName}`)
@@ -143,6 +153,8 @@ durably.on('run:fail', (event) => {
 
 ## Cron Integration
 
+Combine Durably with node-cron for scheduled job execution. Jobs remain resumable even when triggered by cron.
+
 ```ts
 // cron-job.ts
 import cron from 'node-cron'
@@ -160,6 +172,8 @@ cron.schedule('0 * * * *', async () => {
 
 ## CLI with Progress
 
+Build command-line tools with real-time progress output using the `run:progress` event.
+
 ```ts
 // cli.ts
 import { program } from 'commander'
@@ -185,7 +199,7 @@ program.parse()
 
 ## Idempotency
 
-Prevent duplicate runs with idempotency keys:
+Prevent duplicate runs with idempotency keys. If a run with the same key already exists, it returns the existing run instead of creating a new one.
 
 ```ts
 await durably.jobs.processImage.trigger(
@@ -197,7 +211,7 @@ await durably.jobs.processImage.trigger(
 
 ## Concurrency Control
 
-Limit concurrent jobs:
+Limit concurrent jobs with concurrency keys. Only one job with the same key can run at a time - others wait in the queue.
 
 ```ts
 await durably.jobs.processImage.trigger(
@@ -209,6 +223,8 @@ await durably.jobs.processImage.trigger(
 
 ## Error Handling & Retry
 
+Durably doesn't auto-retry failures. Use `retry()` to manually retry failed runs, or `cancel()` to stop running jobs.
+
 ```ts
 // Manual retry on failure
 const run = await durably.storage.getRun(runId)
diff --git a/website/guide/csv-import.md b/website/guide/csv-import.md
index 046bb377..820e4fb0 100644
--- a/website/guide/csv-import.md
+++ b/website/guide/csv-import.md
@@ -33,6 +33,10 @@ app/
 
 ### Job Definition
 
+Define the import job with validation and import steps. Each step is a checkpoint - if the server crashes, the job resumes from the last completed step.
+
+The job uses `step.progress()` to report real-time progress and `step.log` for structured logging.
+
 ```ts
 // app/jobs/import-csv.ts
 import { defineJob } from '@coji/durably'
@@ -118,6 +122,8 @@ export const importCsvJob = defineJob({
 
 ### Server Setup
 
+Create the Durably instance with libsql dialect and register the job. The `createDurablyHandler` provides HTTP/SSE endpoints for the client.
+
 ```ts
 // app/lib/durably.server.ts
 import { createDurably, createDurablyHandler } from '@coji/durably'
@@ -139,6 +145,8 @@ await durably.init()
 
 ### API Route (Splat)
 
+Use a React Router splat route to expose all Durably endpoints under `/api/durably/*`. This handles trigger, subscribe, and management endpoints.
+
 ```ts
 // app/routes/api.durably.$.ts
 import { durablyHandler } from '~/lib/durably.server'
@@ -155,6 +163,8 @@ export async function action({ request }: Route.ActionArgs) {
 
 ### Type-Safe Client
 
+Create a type-safe client using the server's Durably type. This gives you full TypeScript inference for job inputs and outputs without bundling server code.
+
 ```ts
 // app/lib/durably.client.ts
 import { createDurablyClient } from '@coji/durably-react/client'
@@ -167,6 +177,8 @@ export const durablyClient = createDurablyClient({
 
 ### Progress UI
 
+Use the `useRun` hook to subscribe to real-time progress via SSE. The hook returns status flags (`isRunning`, `isCompleted`, `isFailed`) and current progress.
+
 ```tsx
 function ImportProgress({ runId }: { runId: string | null }) {
   const { progress, output, isRunning, isCompleted, isFailed, error } =
@@ -193,6 +205,8 @@ function ImportProgress({ runId }: { runId: string | null }) {
 
 ### Dashboard with Actions
 
+Build a dashboard showing all runs with retry, cancel, and delete actions. The `useRuns` hook provides paginated run history, while `useRunActions` provides mutation functions.
+
 ```tsx
 import { useRuns, useRunActions } from '@coji/durably-react/client'
 
diff --git a/website/guide/getting-started.md b/website/guide/getting-started.md
index 006586a4..02914359 100644
--- a/website/guide/getting-started.md
+++ b/website/guide/getting-started.md
@@ -7,10 +7,16 @@ Build a CSV importer with real-time progress UI. This guide uses React Router v7
 ## Install
 
 ```bash
-npm install @coji/durably @coji/durably-react kysely zod @libsql/client @libsql/kysely-libsql
+pnpm add @coji/durably @coji/durably-react kysely zod @libsql/client @libsql/kysely-libsql
 ```
 
-## 1. Define a Job (Server)
+---
+
+## Server
+
+### 1. Define a Job
+
+Define a job with multiple steps using `step.run()`. Each step's completion state is automatically persisted to SQLite.
 
 ```ts
 // app/jobs/import-csv.ts
@@ -49,6 +55,8 @@ export const importCsvJob = defineJob({
 })
 ```
 
+Create a Durably instance and register the job. `createDurablyHandler` provides HTTP/SSE endpoints for the client.
+
 ```ts
 // app/lib/durably.server.ts
 import { createDurably, createDurablyHandler } from '@coji/durably'
@@ -68,7 +76,9 @@ export const durablyHandler = createDurablyHandler(durably)
 await durably.init()
 ```
 
-## 2. Create API Route (Splat)
+### 2. Create API Route
+
+Use a React Router splat route to expose the Durably API. This automatically provides `/api/durably/trigger`, `/api/durably/subscribe`, and other endpoints.
 
 ```ts
 // app/routes/api.durably.$.ts
@@ -84,11 +94,18 @@ export async function action({ request }: Route.ActionArgs) {
 }
 ```
 
-## 3. Create Type-Safe Client
+---
+
+## Client
+
+### 3. Create Type-Safe Client
+
+Create a type-safe client using the server's Durably type. This gives you full type inference for job inputs and outputs.
 
 ```ts
 // app/lib/durably.client.ts
 import { createDurablyClient } from '@coji/durably-react/client'
+// Type-only import: no server code is bundled, just TypeScript types
 import type { durably } from './durably.server'
 
 export const durablyClient = createDurablyClient({
@@ -96,15 +113,21 @@ export const durablyClient = createDurablyClient({
 })
 ```
 
-## 4. Build the UI
+### 4. Build the UI
+
+Build the UI with real-time progress updates.
+
+- **action**: Trigger the job on the server when form is submitted
+- **useRun**: Subscribe to job progress via SSE
 
 ```tsx
 // app/routes/_index.tsx
-import { Form, useActionData } from 'react-router'
+import { Form } from 'react-router'
 import { durably } from '~/lib/durably.server'
 import { durablyClient } from '~/lib/durably.client'
 import type { Route } from './+types/_index'
 
+// Server: trigger job on form submit
 export async function action({ request }: Route.ActionArgs) {
   const formData = await request.formData()
   const file = formData.get('file') as File
@@ -120,8 +143,8 @@ export async function action({ request }: Route.ActionArgs) {
   return { runId: run.id }
 }
 
-export default function Home() {
-  const actionData = useActionData()
+// Client: subscribe to real-time progress via SSE
+export default function Home({ actionData }: Route.ComponentProps) {
   const { progress, output, isRunning, isCompleted } =
     durablyClient.importCsv.useRun(actionData?.runId ?? null)
 
@@ -143,20 +166,22 @@ export default function Home() {
 }
 ```
 
+---
+
 ## Try It
 
-1. Create a `test.csv`:
+1. Create `test.csv`:
    ```csv
    name,email
    Alice,alice@example.com
    Bob,bob@example.com
    ```
 
-2. Run: `npm run dev`
+2. Start server: `pnpm dev`
 
 3. Upload the CSV and watch real-time progress!
 
-If you stop the server mid-import and restart, it resumes from where it left off.
+**Resume support**: Stop the server mid-import and restart — it picks up right where it left off.
 
 ## Next Steps
 
diff --git a/website/guide/index.md b/website/guide/index.md
index 1c91c5c5..582d0476 100644
--- a/website/guide/index.md
+++ b/website/guide/index.md
@@ -39,7 +39,7 @@ If the process crashes after importing 500 of 1000 rows, restart picks up at row
 
 | Environment | Storage | Use Case |
 |-------------|---------|----------|
-| **Node.js** | libsql/better-sqlite3 | Server-side batch jobs |
+| **Node.js** | @libsql/client, better-sqlite3 | Server-side batch jobs |
 | **Browser** | SQLite WASM + OPFS | Offline-capable apps |
 
 Same job definition works in both environments.
diff --git a/website/guide/offline-app.md b/website/guide/offline-app.md
index 49b5cb8d..b4270272 100644
--- a/website/guide/offline-app.md
+++ b/website/guide/offline-app.md
@@ -42,13 +42,15 @@ export default defineConfig({
 ## Installation
 
 ```bash
-npm install @coji/durably @coji/durably-react kysely zod sqlocal
+pnpm add @coji/durably @coji/durably-react kysely zod sqlocal
 ```
 
 ## Setup
 
 ### Database
 
+Create a SQLocal instance for SQLite WASM with OPFS persistence. This database file will be stored in the browser's Origin Private File System.
+
 ```ts
 // lib/database.ts
 import { SQLocalKysely } from 'sqlocal/kysely'
@@ -58,6 +60,8 @@ export const sqlocal = new SQLocalKysely('app.sqlite3')
 
 ### Job Definition
 
+Define a job with multiple steps. Each `step.run()` call creates a checkpoint - if the browser tab is closed mid-execution, the job will resume from the last completed step.
+
 ```ts
 // jobs/data-sync.ts
 import { defineJob } from '@coji/durably'
@@ -114,6 +118,8 @@ export const dataSyncJob = defineJob({
 
 ### Durably Instance
 
+Create the Durably instance with SQLocal's dialect. The shorter intervals are optimized for browser environments where tab suspension can occur more frequently.
+
 ```ts
 // lib/durably.ts
 import { createDurably } from '@coji/durably'
@@ -122,9 +128,9 @@ import { sqlocal } from './database'
 
 const durably = createDurably({
   dialect: sqlocal.dialect,
-  pollingInterval: 100,
-  heartbeatInterval: 500,
-  staleThreshold: 3000,
+  pollingInterval: 100,    // Check for pending jobs every 100ms
+  heartbeatInterval: 500,  // Send heartbeat every 500ms
+  staleThreshold: 3000,    // Mark job as stale after 3s without heartbeat
 }).register({
   dataSync: dataSyncJob,
 })
@@ -136,6 +142,10 @@ export { durably }
 
 ## Usage
 
+Wrap your app with `DurablyProvider` to enable the hooks. The `fallback` component is shown while the database is initializing.
+
+Use `useJob` to trigger jobs and subscribe to their progress. The hook returns the current status, progress, and output.
+
 ```tsx
 // App.tsx
 import { DurablyProvider, useDurably } from '@coji/durably-react'
diff --git a/website/public/images/getting-started-overview.svg b/website/public/images/getting-started-overview.svg
index f8e0a26f..a4f66e46 100644
--- a/website/public/images/getting-started-overview.svg
+++ b/website/public/images/getting-started-overview.svg
@@ -1,10 +1,11 @@
-
+
   
     
     
@@ -12,48 +13,57 @@
     
   
 
+  
+  
+  SERVER
+
   
-  
-  
-  1
-  Define Job
-  Create job with
-  steps and schema
-  durably.server.ts
+  
+  
+  1
+  Define Job
+  Create job with
+  steps and schema
+  import-csv.ts
+  durably.server.ts
 
   
-  
+  
 
   
-  
-  
-  2
-  API Routes
-  Expose trigger
-  and subscribe
-  api.durably.*.ts
+  
+  
+  2
+  API Route
+  Expose HTTP
+  and SSE endpoints
+  api.durably.$.ts
+
+  
+  
+  CLIENT
 
   
-  
+  
 
   
-  
-  
-  3
-  Client Hooks
-  Type-safe React
-  hooks for UI
-  durably.client.ts
+  
+  
+  3
+  Create Client
+  Type-safe hooks
+  from server types
+  durably.client.ts
 
   
-  
+  
 
   
-  
-  
-  4
-  Build UI
-  Form + Progress
-  with real-time SSE
-  _index.tsx
+  
+  
+  4
+  Build UI
+  Form + Progress
+  with real-time SSE
+  _index.tsx
 

From e3c94a8aa1f83f7dbbbea25294964512e0bf1c5c Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 15:14:50 +0900
Subject: [PATCH 099/101] docs: update llms.md for both packages to match
 latest API
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

durably:
- Change npm to pnpm in installation
- Fix createDurablyHandler import path (@coji/durably)
- Fix withLogPersistence import path (@coji/durably)

durably-react:
- Add React 19+ requirement
- Rename Browser-Complete Mode → Browser Hooks
- Rename Server-Connected Mode → Server Hooks
- Simplify DurablyProvider props (durably, fallback only)
- Remove isReady from useDurably, useJob, useJobRun return types
- Add createDurablyClient as recommended approach
- Update Server Handler setup with handle() method
- Change npm to pnpm

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 
---
 packages/durably-react/docs/llms.md | 341 ++++++++++------------------
 packages/durably/docs/llms.md       |   8 +-
 2 files changed, 126 insertions(+), 223 deletions(-)

diff --git a/packages/durably-react/docs/llms.md b/packages/durably-react/docs/llms.md
index f6ccbb7b..a3501a51 100644
--- a/packages/durably-react/docs/llms.md
+++ b/packages/durably-react/docs/llms.md
@@ -2,31 +2,36 @@
 
 > React bindings for Durably - step-oriented resumable batch execution.
 
+## Requirements
+
+- **React 19+** (uses `React.use()` for Promise resolution)
+
 ## Overview
 
 `@coji/durably-react` provides React hooks for triggering and monitoring Durably jobs. It supports two modes:
 
-1. **Browser-complete mode**: Run Durably entirely in the browser with SQLite WASM
-2. **Server-connected mode**: Connect to a remote Durably server via SSE
+1. **Browser Hooks**: Run Durably entirely in the browser with SQLite WASM (OPFS)
+2. **Server Hooks**: Connect to a remote Durably server via HTTP/SSE
 
 ## Installation
 
 ```bash
-# Browser-complete mode
-npm install @coji/durably-react @coji/durably kysely zod sqlocal
+# Browser mode - runs Durably in the browser
+pnpm add @coji/durably-react @coji/durably kysely zod sqlocal
 
-# Server-connected mode (client only)
-npm install @coji/durably-react
+# Server mode - connects to Durably server
+pnpm add @coji/durably-react
 ```
 
-## Browser-Complete Mode
+## Browser Hooks
+
+Import from `@coji/durably-react` for browser-complete mode.
 
 ### DurablyProvider
 
 Wraps your app and provides the Durably instance to all hooks:
 
 ```tsx
-import { Suspense } from 'react'
 import { DurablyProvider } from '@coji/durably-react'
 import { createDurably } from '@coji/durably'
 import { SQLocalKysely } from 'sqlocal/kysely'
@@ -35,38 +40,37 @@ import { SQLocalKysely } from 'sqlocal/kysely'
 async function initDurably() {
   const sqlocal = new SQLocalKysely('app.sqlite3')
   const durably = createDurably({ dialect: sqlocal.dialect })
-  await durably.migrate()
+  await durably.init()
   return durably
 }
 
 const durablyPromise = initDurably()
 
+// With fallback prop (recommended)
 function App() {
   return (
-    Loading...
      }>
-      
-        
-      
-    
+    Loading...
      }>
+      
+    
   )
 }
 
-// Or use the fallback prop
+// Or with external Suspense
 function AppAlt() {
   return (
-    Loading...
      }>
-      
-    
+    Loading...
      }>
+      
+        
+      
+    
   )
 }
 ```
 
 **Props:**
 
-- `durably: Durably | Promise` - Durably instance or Promise
-- `autoStart?: boolean` - Auto-start worker (default: true)
-- `onReady?: (durably: Durably) => void` - Callback when ready
-- `fallback?: ReactNode` - Fallback to show while Promise resolves
+- `durably: Durably | Promise` - Durably instance or Promise (should be initialized via `await durably.init()`)
+- `fallback?: ReactNode` - Fallback to show while Promise resolves (wraps in Suspense automatically)
 
 ### useDurably
 
@@ -76,12 +80,20 @@ Access the Durably instance directly:
 import { useDurably } from '@coji/durably-react'
 
 function Component() {
-  const { durably, isReady, error } = useDurably()
-
-  if (!isReady) return 
      Loading...
      
-  if (error) return 
      Error: {error.message}
      
+  const { durably } = useDurably()
 
   // Use durably instance directly
+  const handleGetRuns = async () => {
+    const runs = await durably.getRuns()
+  }
+}
+```
+
+**Return type:**
+
+```ts
+interface UseDurablyResult {
+  durably: Durably
 }
 ```
 
@@ -106,7 +118,6 @@ const myJob = defineJob({
 
 function Component() {
   const {
-    isReady,
     trigger,
     triggerAndWait,
     status,
@@ -141,7 +152,7 @@ function Component() {
 
   return (
     
      
-      
       
      Status: {status}
      
@@ -172,7 +183,6 @@ interface UseJobOptions {
 
 ```ts
 interface UseJobResult {
-  isReady: boolean
   trigger: (input: TInput) => Promise<{ runId: string }>
   triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }>
   status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | null
@@ -199,7 +209,6 @@ import { useJobRun } from '@coji/durably-react'
 
 function RunMonitor({ runId }: { runId: string | null }) {
   const {
-    isReady,
     status,
     output,
     error,
@@ -221,24 +230,6 @@ function RunMonitor({ runId }: { runId: string | null }) {
 }
 ```
 
-**Return type:**
-
-```ts
-interface UseJobRunResult {
-  isReady: boolean
-  status: RunStatus | null
-  output: TOutput | null
-  error: string | null
-  progress: Progress | null
-  logs: LogEntry[]
-  isRunning: boolean
-  isPending: boolean
-  isCompleted: boolean
-  isFailed: boolean
-  isCancelled: boolean
-}
-```
-
 ### useJobLogs
 
 Subscribe to logs from a run:
@@ -247,7 +238,7 @@ Subscribe to logs from a run:
 import { useJobLogs } from '@coji/durably-react'
 
 function LogViewer({ runId }: { runId: string | null }) {
-  const { isReady, logs, clearLogs } = useJobLogs({
+  const { logs, clearLogs } = useJobLogs({
     runId,
     maxLogs: 100, // Optional: limit stored logs
   })
@@ -268,97 +259,95 @@ function LogViewer({ runId }: { runId: string | null }) {
 }
 ```
 
-**Return type:**
-
-```ts
-interface UseJobLogsResult {
-  isReady: boolean
-  logs: LogEntry[]
-  clearLogs: () => void
-}
-
-interface LogEntry {
-  id: string
-  runId: string
-  stepName: string | null
-  level: 'info' | 'warn' | 'error'
-  message: string
-  data: unknown
-  timestamp: string
-}
-```
-
 ### useRuns
 
-List runs with pagination and real-time updates:
+List runs with filtering and real-time updates:
 
 ```tsx
 import { useRuns } from '@coji/durably-react'
 
 function Dashboard() {
-  const {
-    isReady,
-    runs,
-    page,
-    hasMore,
-    isLoading,
-    nextPage,
-    prevPage,
-    goToPage,
-    refresh,
-  } = useRuns({
+  const { runs, isLoading, refresh } = useRuns({
     jobName: 'my-job', // Optional: filter by job
     status: 'running', // Optional: filter by status
-    pageSize: 20, // Optional: items per page (default: 10)
-    realtime: true, // Optional: subscribe to updates (default: true)
+    limit: 10, // Optional: maximum runs
   })
 
   return (
     
      
+      
       {runs.map((run) => (
         
      
           {run.jobName}: {run.status}
         
      
       ))}
-      
-      
     
      
   )
 }
 ```
 
-**Return type:**
+## Server Hooks
 
-```ts
-interface UseRunsResult {
-  isReady: boolean
-  runs: Run[]
-  page: number
-  hasMore: boolean
-  isLoading: boolean
-  nextPage: () => void
-  prevPage: () => void
-  goToPage: (page: number) => void
-  refresh: () => Promise
+Import from `@coji/durably-react/client` for server-connected mode.
+
+### createDurablyClient
+
+Create a type-safe client for all registered jobs (recommended):
+
+```tsx
+// Server: register jobs (app/lib/durably.server.ts)
+import { createDurably, createDurablyHandler } from '@coji/durably'
+
+export const durably = createDurably({ dialect }).register({
+  importCsv: importCsvJob,
+  syncUsers: syncUsersJob,
+})
+
+export const durablyHandler = createDurablyHandler(durably)
+
+await durably.init()
+
+// Client: create typed client (app/lib/durably.client.ts)
+import type { durably } from '~/lib/durably.server'
+import { createDurablyClient } from '@coji/durably-react/client'
+
+export const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+
+// In your component - fully type-safe with autocomplete
+function CsvImporter() {
+  const { trigger, output, isRunning } = durablyClient.importCsv.useJob()
+
+  return (
+    
+  )
 }
-```
 
-## Server-Connected Mode
+// Subscribe to an existing run
+function RunViewer({ runId }: { runId: string }) {
+  const { status, output, progress } = durablyClient.importCsv.useRun(runId)
+  return 
      Status: {status}
      
+}
 
-Import hooks from `@coji/durably-react/client` for server-connected mode.
+// Subscribe to logs
+function LogViewer({ runId }: { runId: string }) {
+  const { logs } = durablyClient.importCsv.useLogs(runId)
+  return 
      {logs.map(l => l.message).join('\n')}
      
+}
+```
 
 ### Client useJob
 
+Direct hook when not using `createDurablyClient`:
+
 ```tsx
 import { useJob } from '@coji/durably-react/client'
 
 function Component() {
   const {
-    isReady, // Always true in client mode
     trigger,
     triggerAndWait,
     status,
@@ -376,6 +365,7 @@ function Component() {
   >({
     api: '/api/durably',
     jobName: 'sync-data',
+    initialRunId: undefined, // Optional: resume existing run
   })
 
   const handleClick = async () => {
@@ -426,65 +416,9 @@ function Component({ runId }: { runId: string }) {
 }
 ```
 
-### Server Handler Setup
-
-On your server, use `createDurablyHandler` from `@coji/durably/server`:
-
-```ts
-import { createDurably, defineJob } from '@coji/durably'
-import { createDurablyHandler } from '@coji/durably/server'
-import { LibsqlDialect } from '@libsql/kysely-libsql'
-import { createClient } from '@libsql/client'
-import { z } from 'zod'
-
-const client = createClient({ url: 'file:local.db' })
-const dialect = new LibsqlDialect({ client })
-
-const durably = createDurably({ dialect })
-
-// Define and register jobs
-const syncJob = defineJob({
-  name: 'sync-data',
-  input: z.object({ userId: z.string() }),
-  output: z.object({ count: z.number() }),
-  run: async (step, payload) => {
-    // Job logic
-    return { count: 42 }
-  },
-})
-durably.register({ syncJob })
-
-await durably.migrate()
-durably.start()
-
-// Create handler
-const handler = createDurablyHandler(durably)
-
-// Express/Hono/etc route handlers
-app.post('/api/durably/trigger', async (req) => {
-  return handler.trigger(req)
-})
-
-app.get('/api/durably/subscribe', (req) => {
-  return handler.subscribe(req)
-})
-
-app.post('/api/durably/cancel', async (req) => {
-  return handler.cancel(req)
-})
-
-app.get('/api/durably/runs', async (req) => {
-  return handler.getRuns(req)
-})
-
-app.get('/api/durably/runs/:runId', async (req) => {
-  return handler.getRun(req)
-})
-```
-
 ### Client useRuns
 
-List runs with pagination:
+List runs with pagination and real-time updates:
 
 ```tsx
 import { useRuns } from '@coji/durably-react/client'
@@ -513,6 +447,8 @@ function Dashboard() {
           {run.jobName}: {run.status}
         
      
       ))}
+      
+      
     
    
   )
 }
@@ -520,7 +456,7 @@ function Dashboard() {
 
 ### Client useRunActions
 
-Imperative actions for runs (retry, cancel, delete, get):
+Actions for runs (retry, cancel, delete):
 
 ```tsx
 import { useRunActions } from '@coji/durably-react/client'
@@ -531,12 +467,6 @@ function RunActions({ runId, status }: { runId: string; status: string }) {
       api: '/api/durably',
     })
 
-  const handleViewDetails = async () => {
-    const run = await getRun(runId)
-    const steps = await getSteps(runId)
-    console.log('Run:', run, 'Steps:', steps)
-  }
-
   return (
     
    
       {(status === 'failed' || status === 'cancelled') && (
@@ -549,9 +479,6 @@ function RunActions({ runId, status }: { runId: string; status: string }) {
           Cancel
         
       )}
-      
       
@@ -561,60 +488,38 @@ function RunActions({ runId, status }: { runId: string; status: string }) {
 }
 ```
 
-### Type-Safe Client Factories
+## Server Handler Setup
 
-#### createJobHooks
+On your server, use `createDurablyHandler`:
 
-Create type-safe hooks for a single job:
+```ts
+// app/lib/durably.server.ts
+import { createDurably } from '@coji/durably'
+import { createDurablyHandler } from '@coji/durably'
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+import { createClient } from '@libsql/client'
 
-```tsx
-import type { importCsvJob } from '~/lib/durably.server'
-import { createJobHooks } from '@coji/durably-react/client'
+const client = createClient({ url: 'file:local.db' })
+const dialect = new LibsqlDialect({ client })
 
-const importCsv = createJobHooks({
-  api: '/api/durably',
-  jobName: 'import-csv',
+export const durably = createDurably({ dialect }).register({
+  syncData: syncDataJob,
 })
 
-function CsvImporter() {
-  const { trigger, output, progress, isRunning } = importCsv.useJob()
+export const durablyHandler = createDurablyHandler(durably)
 
-  return (
-    
-  )
-}
-```
+await durably.init()
 
-#### createDurablyClient
+// app/routes/api.durably.$.ts (React Router / Remix)
+import { durablyHandler } from '~/lib/durably.server'
+import type { Route } from './+types/api.durably.$'
 
-Create a type-safe client for all registered jobs:
-
-```tsx
-// Server: register jobs (app/lib/durably.server.ts)
-export const jobs = durably.register({
-  importCsv: importCsvJob,
-  syncUsers: syncUsersJob,
-})
-
-// Client: create typed client (app/lib/durably.client.ts)
-import type { jobs } from '~/lib/durably.server'
-import { createDurablyClient } from '@coji/durably-react/client'
-
-export const durably = createDurablyClient({
-  api: '/api/durably',
-})
-
-// In your component - fully type-safe with autocomplete
-function CsvImporter() {
-  const { trigger, output, isRunning } = durably.importCsv.useJob()
+export async function loader({ request }: Route.LoaderArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
 
-  return (
-    
-  )
+export async function action({ request }: Route.ActionArgs) {
+  return durablyHandler.handle(request, '/api/durably')
 }
 ```
 
@@ -646,9 +551,7 @@ interface LogEntry {
 
 ```tsx
 function Component() {
-  const { isReady, isRunning, trigger } = useJob(myJob)
-
-  if (!isReady) return 
+  const { isRunning, trigger } = useJob(myJob)
 
   return (
     
    }>
+      
+    
+  )
+}
+
+// Or with external Suspense
+function AppAlt() {
+  return (
+    Loading...
    }>
+      
+        
+      
+    
+  )
+}
+```
+
+**Props:**
+
+- `durably: Durably | Promise` - Durably instance or Promise (should be initialized via `await durably.init()`)
+- `fallback?: ReactNode` - Fallback to show while Promise resolves (wraps in Suspense automatically)
+
+### useDurably
+
+Access the Durably instance directly:
+
+```tsx
+import { useDurably } from '@coji/durably-react'
+
+function Component() {
+  const { durably } = useDurably()
+
+  // Use durably instance directly
+  const handleGetRuns = async () => {
+    const runs = await durably.getRuns()
+  }
+}
+```
+
+**Return type:**
+
+```ts
+interface UseDurablyResult {
+  durably: Durably
+}
+```
+
+### useJob
+
+Trigger and monitor a job:
+
+```tsx
+import { defineJob } from '@coji/durably'
+import { useJob } from '@coji/durably-react'
+import { z } from 'zod'
+
+const myJob = defineJob({
+  name: 'my-job',
+  input: z.object({ value: z.string() }),
+  output: z.object({ result: z.number() }),
+  run: async (step, payload) => {
+    const data = await step.run('process', () => process(payload.value))
+    return { result: data.length }
+  },
+})
+
+function Component() {
+  const {
+    trigger,
+    triggerAndWait,
+    status,
+    output,
+    error,
+    logs,
+    progress,
+    isRunning,
+    isPending,
+    isCompleted,
+    isFailed,
+    isCancelled,
+    currentRunId,
+    reset,
+  } = useJob(myJob, {
+    initialRunId: undefined,
+    autoResume: true, // Auto-resume pending/running jobs (default: true)
+    followLatest: true, // Switch to tracking new runs (default: true)
+  })
+
+  // Trigger job
+  const handleClick = async () => {
+    const { runId } = await trigger({ value: 'test' })
+    console.log('Started:', runId)
+  }
+
+  // Or trigger and wait for result
+  const handleSync = async () => {
+    const { runId, output } = await triggerAndWait({ value: 'test' })
+    console.log('Result:', output.result)
+  }
+
+  return (
+    
    
+      
+      
    Status: {status}
    
+      {progress && (
+        
    
+          Progress: {progress.current}/{progress.total}
+        
    
+      )}
+      {isCompleted && 
    Result: {output?.result}
    }
+      {isFailed && 
    Error: {error}
    }
+      
+    
    
+  )
+}
+```
+
+**Options:**
+
+```ts
+interface UseJobOptions {
+  initialRunId?: string // Initial Run ID to subscribe to
+  autoResume?: boolean // Auto-resume pending/running jobs (default: true)
+  followLatest?: boolean // Switch to tracking new runs (default: true)
+}
+```
+
+**Return type:**
+
+```ts
+interface UseJobResult {
+  trigger: (input: TInput) => Promise<{ runId: string }>
+  triggerAndWait: (input: TInput) => Promise<{ runId: string; output: TOutput }>
+  status: 'pending' | 'running' | 'completed' | 'failed' | 'cancelled' | null
+  output: TOutput | null
+  error: string | null
+  logs: LogEntry[]
+  progress: Progress | null
+  isRunning: boolean
+  isPending: boolean
+  isCompleted: boolean
+  isFailed: boolean
+  isCancelled: boolean
+  currentRunId: string | null
+  reset: () => void
+}
+```
+
+### useJobRun
+
+Subscribe to an existing run by ID:
+
+```tsx
+import { useJobRun } from '@coji/durably-react'
+
+function RunMonitor({ runId }: { runId: string | null }) {
+  const {
+    status,
+    output,
+    error,
+    progress,
+    logs,
+    isRunning,
+    isCompleted,
+    isFailed,
+  } = useJobRun<{ result: number }>({ runId })
+
+  if (!runId) return 
    No run selected
    
+
+  return (
+    
    
+      
    Status: {status}
    
+      {isCompleted && 
    Output: {JSON.stringify(output)}
    }
+    
    
+  )
+}
+```
+
+### useJobLogs
+
+Subscribe to logs from a run:
+
+```tsx
+import { useJobLogs } from '@coji/durably-react'
+
+function LogViewer({ runId }: { runId: string | null }) {
+  const { logs, clearLogs } = useJobLogs({
+    runId,
+    maxLogs: 100, // Optional: limit stored logs
+  })
+
+  return (
+    
    
+      
+      
      
+        {logs.map((log) => (
+          
    • 
+            [{log.level}] {log.message}
+            {log.data && 
      {JSON.stringify(log.data)}
      }
+          
      • 
+        ))}
+      
    
+    
    
+  )
+}
+```
+
+### useRuns
+
+List runs with filtering and real-time updates:
+
+```tsx
+import { useRuns } from '@coji/durably-react'
+
+function Dashboard() {
+  const { runs, isLoading, refresh } = useRuns({
+    jobName: 'my-job', // Optional: filter by job
+    status: 'running', // Optional: filter by status
+    limit: 10, // Optional: maximum runs
+  })
+
+  return (
+    
    
+      
+      {runs.map((run) => (
+        
    
+          {run.jobName}: {run.status}
+        
    
+      ))}
+    
    
+  )
+}
+```
+
+## Server Hooks
+
+Import from `@coji/durably-react/client` for server-connected mode.
+
+### createDurablyClient
+
+Create a type-safe client for all registered jobs (recommended):
+
+```tsx
+// Server: register jobs (app/lib/durably.server.ts)
+import { createDurably, createDurablyHandler } from '@coji/durably'
+
+export const durably = createDurably({ dialect }).register({
+  importCsv: importCsvJob,
+  syncUsers: syncUsersJob,
+})
+
+export const durablyHandler = createDurablyHandler(durably)
+
+await durably.init()
+
+// Client: create typed client (app/lib/durably.client.ts)
+import type { durably } from '~/lib/durably.server'
+import { createDurablyClient } from '@coji/durably-react/client'
+
+export const durablyClient = createDurablyClient({
+  api: '/api/durably',
+})
+
+// In your component - fully type-safe with autocomplete
+function CsvImporter() {
+  const { trigger, output, isRunning } = durablyClient.importCsv.useJob()
+
+  return (
+    
+  )
+}
+
+// Subscribe to an existing run
+function RunViewer({ runId }: { runId: string }) {
+  const { status, output, progress } = durablyClient.importCsv.useRun(runId)
+  return 
    Status: {status}
    
+}
+
+// Subscribe to logs
+function LogViewer({ runId }: { runId: string }) {
+  const { logs } = durablyClient.importCsv.useLogs(runId)
+  return 
    {logs.map(l => l.message).join('\n')}
    
+}
+```
+
+### Client useJob
+
+Direct hook when not using `createDurablyClient`:
+
+```tsx
+import { useJob } from '@coji/durably-react/client'
+
+function Component() {
+  const {
+    trigger,
+    triggerAndWait,
+    status,
+    output,
+    error,
+    logs,
+    progress,
+    isRunning,
+    isCompleted,
+    currentRunId,
+    reset,
+  } = useJob<
+    { userId: string }, // Input type
+    { count: number } // Output type
+  >({
+    api: '/api/durably',
+    jobName: 'sync-data',
+    initialRunId: undefined, // Optional: resume existing run
+  })
+
+  const handleClick = async () => {
+    const { runId } = await trigger({ userId: 'user_123' })
+    console.log('Started:', runId)
+  }
+
+  return 
+}
+```
+
+### Client useJobRun
+
+```tsx
+import { useJobRun } from '@coji/durably-react/client'
+
+function Component({ runId }: { runId: string }) {
+  const { status, output, error, progress, logs } = useJobRun<{
+    count: number
+  }>({
+    api: '/api/durably',
+    runId,
+  })
+
+  return 
    Status: {status}
    
+}
+```
+
+### Client useJobLogs
+
+```tsx
+import { useJobLogs } from '@coji/durably-react/client'
+
+function Component({ runId }: { runId: string }) {
+  const { logs, clearLogs } = useJobLogs({
+    api: '/api/durably',
+    runId,
+    maxLogs: 50,
+  })
+
+  return (
+    
      
+      {logs.map((log) => (
+        
    • {log.message}
      • 
+      ))}
+    
    
+  )
+}
+```
+
+### Client useRuns
+
+List runs with pagination and real-time updates:
+
+```tsx
+import { useRuns } from '@coji/durably-react/client'
+
+function Dashboard() {
+  const {
+    runs,
+    page,
+    hasMore,
+    isLoading,
+    nextPage,
+    prevPage,
+    goToPage,
+    refresh,
+  } = useRuns({
+    api: '/api/durably',
+    jobName: 'sync-data', // Optional: filter by job
+    status: 'running', // Optional: filter by status
+    pageSize: 20, // Optional: items per page
+  })
+
+  return (
+    
    
+      {runs.map((run) => (
+        
    
+          {run.jobName}: {run.status}
+        
    
+      ))}
+      
+      
+    
    
+  )
+}
+```
+
+### Client useRunActions
+
+Actions for runs (retry, cancel, delete):
+
+```tsx
+import { useRunActions } from '@coji/durably-react/client'
+
+function RunActions({ runId, status }: { runId: string; status: string }) {
+  const { retry, cancel, deleteRun, getRun, getSteps, isLoading, error } =
+    useRunActions({
+      api: '/api/durably',
+    })
+
+  return (
+    
    
+      {(status === 'failed' || status === 'cancelled') && (
+        
+      )}
+      {(status === 'pending' || status === 'running') && (
+        
+      )}
+      
+      {error && {error}}
+    
    
+  )
+}
+```
+
+## Server Handler Setup
+
+On your server, use `createDurablyHandler`:
+
+```ts
+// app/lib/durably.server.ts
+import { createDurably } from '@coji/durably'
+import { createDurablyHandler } from '@coji/durably'
+import { LibsqlDialect } from '@libsql/kysely-libsql'
+import { createClient } from '@libsql/client'
+
+const client = createClient({ url: 'file:local.db' })
+const dialect = new LibsqlDialect({ client })
+
+export const durably = createDurably({ dialect }).register({
+  syncData: syncDataJob,
+})
+
+export const durablyHandler = createDurablyHandler(durably)
+
+await durably.init()
+
+// app/routes/api.durably.$.ts (React Router / Remix)
+import { durablyHandler } from '~/lib/durably.server'
+import type { Route } from './+types/api.durably.$'
+
+export async function loader({ request }: Route.LoaderArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+
+export async function action({ request }: Route.ActionArgs) {
+  return durablyHandler.handle(request, '/api/durably')
+}
+```
+
+## Type Definitions
+
+```ts
+type RunStatus = 'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
+
+interface Progress {
+  current: number
+  total?: number
+  message?: string
+}
+
+interface LogEntry {
+  id: string
+  runId: string
+  stepName: string | null
+  level: 'info' | 'warn' | 'error'
+  message: string
+  data: unknown
+  timestamp: string
+}
+```
+
+## Common Patterns
+
+### Loading States
+
+```tsx
+function Component() {
+  const { isRunning, trigger } = useJob(myJob)
+
+  return (
+    
+  )
+}
+```
+
+### Error Handling
+
+```tsx
+function Component() {
+  const { trigger, error, isFailed, reset } = useJob(myJob)
+
+  const handleClick = async () => {
+    try {
+      await trigger({ value: 'test' })
+    } catch (e) {
+      console.error('Trigger failed:', e)
+    }
+  }
+
+  if (isFailed) {
+    return (
+      
    
+        
    Error: {error}
    
+        
+      
    
+    )
+  }
+
+  return 
+}
+```
+
+### Progress Tracking
+
+```tsx
+function Component() {
+  const { trigger, progress, isRunning } = useJob(progressJob)
+
+  return (
+    
    
+      
+      {isRunning && progress && (
+        
    
+          
+          
    {progress.message}
    
+        
    
+      )}
+    
    
+  )
+}
+```
+
+### Reconnecting to Existing Run
+
+```tsx
+function Component({ existingRunId }: { existingRunId?: string }) {
+  const { status, output } = useJob(myJob, {
+    initialRunId: existingRunId,
+  })
+
+  // Will automatically subscribe to the existing run
+  return 
    Status: {status}
    
+}
+```
+
+## License
+
+MIT
+
diff --git a/website/scripts/generate-llms.js b/website/scripts/generate-llms.js
new file mode 100644
index 00000000..2b6842db
--- /dev/null
+++ b/website/scripts/generate-llms.js
@@ -0,0 +1,33 @@
+/**
+ * Generate combined llms.txt from package documentation
+ *
+ * This script concatenates llms.md from both @coji/durably and @coji/durably-react
+ * into a single llms.txt file for the website.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const rootDir = join(__dirname, '..')
+
+const coreLlms = readFileSync(
+  join(rootDir, '../packages/durably/docs/llms.md'),
+  'utf-8',
+)
+const reactLlms = readFileSync(
+  join(rootDir, '../packages/durably-react/docs/llms.md'),
+  'utf-8',
+)
+
+const combined = `${coreLlms}
+
+---
+
+${reactLlms}
+`
+
+writeFileSync(join(rootDir, 'public/llms.txt'), combined)
+
+console.log('Generated public/llms.txt')

From 767f46133f199e7ea76276e3e57b754020484364 Mon Sep 17 00:00:00 2001
From: coji 
Date: Sat, 3 Jan 2026 15:20:23 +0900
Subject: [PATCH 101/101] fix: improve button formatting in Dashboard component

---
 packages/durably-react/docs/llms.md | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/packages/durably-react/docs/llms.md b/packages/durably-react/docs/llms.md
index a3501a51..f2ceffc6 100644
--- a/packages/durably-react/docs/llms.md
+++ b/packages/durably-react/docs/llms.md
@@ -447,8 +447,12 @@ function Dashboard() {
           {run.jobName}: {run.status}
         
    
       ))}
-      
-      
+      
+      
     
    
   )
 }