feat: add @coji/durably-react package

.gitignore

@@ -5,7 +5,11 @@ dist/
 __screenshots__/
 local.db
 .serena/
+.turbo/
 
 # VitePress
 website/.vitepress/cache/
 website/.vitepress/dist/
+
+# test coverage
+coverage

.prettierignore

@@ -1 +1,9 @@
 pnpm-lock.yaml
+dist/
+node_modules/
+.turbo/
+__screenshots__/
+website/.vitepress/cache/
+website/.vitepress/dist/
+*.log
+CHANGELOG.md

CHANGELOG.md

@@ -5,22 +5,117 @@ 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] - 2026-01-02
+
+### Breaking Changes
+
+#### @coji/durably
+
+- **`register()` API simplified**: `registerAll()` renamed to `register()`, old single-job signature removed
+  ```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
+  - <DurablyProvider durably={durably} autoStart onReady={() => console.log('ready')}>
+  + <DurablyProvider durably={durably}>
+  ```
+- **React 19 required**: `peerDependencies` now requires React 19+ (uses `React.use()` hook)
+
+### Added
+
+#### @coji/durably
+
+- **`init()` method**: Combines `migrate()` and `start()` for simpler initialization
+  ```ts
+  const durably = createDurably({ dialect })
+  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**: `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`, `DELETE /run?runId=xxx`
+- **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
+
+#### @coji/durably-react/client
+
+- **`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
+
+### 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
 
 ### 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
 
 ### Breaking Changes
 
 - **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
 
@@ -34,15 +129,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

CLAUDE.md

@@ -20,13 +20,14 @@ 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
 
 ## 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

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
@@ -13,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
-
-```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
+## Quick Start
 
-- [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
 

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"
+          }
+        }
+      }
+    }
+  ]
 }