slapflow 1.0.2 → 1.2.0

package/README.md

@@ -14,6 +14,12 @@ Slapflow takes care of orchestration, concurrency, cancellation, and diagnostics
 - **Make async behavior deliberate.** Choose `parallel`, `latest`, `queue`, or `drop` for each event source. Actions receive an `AbortSignal` when cancellation matters.
 - **Use the same flow in more than one place.** The chain can start from a typed bus, DOM event, API callback, timer, worker, or WebSocket message.
 
+### When to use Slapflow
+
+Slapflow orchestrates a control flow that lives and finishes inside a single process. Reach for it when a scenario spans several steps, branches, and failure paths and you want it in one place rather than spread across handlers and callbacks.
+
+**What it is not:** a web framework (no routing, no middleware stack — pair it with Express, Hono, or Next.js routes) or a job queue (no built-in persistence, no distributed workers). It is also not a durable workflow engine: a chain runs inside a live process and stops with it — a `core.loop` can spin indefinitely while the process runs, but unlike Temporal there is no state that survives a crash or restart unless your application prevails it. It is closest to a lightweight, in-process state machine: decisions, ordering, concurrency, and cancellation live in a chain, while your application keeps the domain state and side effects.
+
 ## Installation
 
 ```bash
@@ -156,13 +162,14 @@ const config = {
 - A broad set of [built-in conditions](SPEC.md#built-in-conditions) for comparisons, type checks, collections, and compound logic.
 - Typed PubSub bindings and delegated DOM bindings.
 - `parallel`, `latest`, `queue`, and `drop` concurrency modes with per-entity lanes.
-- A WebSocket bridge for forwarding selected bus events.
+- A native WebSocket client that proxies socket events into the bus.
 - `core.fetch` with response parsing, cancellation, and retry backoff.
 - Normalized results, execution trace, validation, and lifecycle diagnostics such as `slapflow.run.started` and `slapflow.run.failed`.
 - Runtime variables for configuration values, templates, and expressions.
 
 ## Where to go next
 
+- See [slapflow-studio](https://github.com/khalilov/slapflow-studio), a working application built entirely on Slapflow.
 - Read the complete [technical specification](SPEC.md) for the runner API, built-in actions and conditions, expressions, validation, safety limits, transport behavior, and lifecycle semantics.
 - Russian documentation: [README-RU.md](README-RU.md) and [SPEC-RU.md](SPEC-RU.md).
 

package/SPEC-RU.md

@@ -12,23 +12,20 @@
 
 ```ts
 import {
-  createActionsRegistry,
-  createConditionsRegistry,
+  BUILTIN_ACTIONS,
+  BUILTIN_CONDITIONS,
   createMemoryTraceSink,
   defineErrorReporter,
   createPubSub,
   PubSub,
   createFlow,
-  createWS,
+  createWebSocket,
   catchError,
 } from 'slapflow'
 ```
 
 ```ts
-const flow = createFlow<Context, Patch>(
-  { config: { strategies: {} } },
-  { context: () => ({} as Context) }
-)
+const flow = createFlow<Context, Patch>({ config: { strategies: {} } }, { context: () => ({}) as Context })
 const runner = flow.runner
 
 runner.registerAction('jobs.execute', executeJob)
@@ -45,8 +42,11 @@ type Config = {
   version?: 1
   strategies: Record<string, Strategy>
   entrypoints?: Record<string, string>
+  guards?: Record<string, ConditionExpression>
 }
 
+type ConditionExpression = boolean | [operator: string, ...args: unknown[]] | ['guard', name: string]
+
 type Strategy = {
   fn: string
   props?: Record<string, unknown>
@@ -79,7 +79,7 @@ const reportError = defineErrorReporter({
 
 const flow = createFlow(
   { config: { strategies: {} } },
-  { context: () => ({} as Context), trace: true, onError: reportError }
+  { context: () => ({}) as Context, trace: true, onError: reportError }
 )
 ```
 
@@ -113,29 +113,38 @@ type ErrorStage = {
 
 Если ошибка обработана через `catch`, `onError` всё равно вызывается для исходного сбоя, а итоговый `run` может завершиться со статусом `success`.
 
+## Нормализация возврата действия
+
+Возвращаемое значение действия нормализуется в один итог. Соответствие:
+
+| Возврат                                           | Итог                                                          |
+| ------------------------------------------------- | ------------------------------------------------------------- |
+| `undefined` / `null`                              | `success`                                                     |
+| `false`                                           | `skipped`                                                     |
+| `{ type: 'skip', reason?, data? }`                | `skipped` (селектор пробует следующую ветку)                  |
+| `{ type: 'stop', reason?, patch?, events? }`      | `stopped` (цепочка останавливается без ошибки)                |
+| `{ type: 'fail', reason?, data?, error? }`        | `failed` (запускается `catch`, затем `onError`)               |
+| `{ context?, data?, patch?, events?, continue? }` | `success`; `continue: false` прерывает оставшиеся `then`-цели |
+
+Брошенное исключение трактуется как `fail`. Возврат `false` и `{ type: 'skip' }` эквивалентны.
+
 ## Модель реестров
 
-Исполнитель использует собственные реестры:
+Встроенные элементы живут в двух общих константах — по одной на вид:
 
-```text
-src/registry/
-  actions.ts
-  conditions.ts
+```ts
+import { BUILTIN_ACTIONS, BUILTIN_CONDITIONS } from 'slapflow'
 ```
 
-`createActionsRegistry()` создаёт `Map`, предварительно заполненный встроенными действиями.
+`BUILTIN_ACTIONS` — это readonly-список `[name, action][]`, предварительно заполненный встроенными действиями; `BUILTIN_CONDITIONS` содержит встроенные условия. Каждый исполнитель получает собственный `new Map(BUILTIN_ACTIONS)` / `new Map(BUILTIN_CONDITIONS)`, поэтому регистрации остаются изолированными по исполнителям.
 
-`createConditionsRegistry()` создаёт `Map`, предварительно заполненный встроенными условиями.
-
-Каждый исполнитель получает собственную изменяемую копию реестра. Приложения могут переопределить любое встроенное действие или условие:
+Встроенные элементы неизменяемы: `registerAction` и `registerCondition` отклоняют попытку переопределить встроенное имя.
 
 ```ts
 runner.registerAction('app.setData', customSetData)
-runner.registerCondition('eq', customEq)
+runner.registerCondition('hasQueue', hasItems)
 ```
 
-Таким образом, встроенные элементы являются значениями по умолчанию, а не отдельным неизменяемым слоем.
-
 Проверка конфигурации обращается к реестрам через минимальный контракт `has(name)`.
 
 ## Встроенные действия
@@ -225,6 +234,18 @@ export const config = {
 
 `parallel` запускает цели `then` независимо. Простые объекты и массивы контекста и runtime data копируются для каждой ветки; инфраструктурные значения вроде функций, DOM-узлов и экземпляров классов остаются ссылками. Safety limits, включая `maxStepCount`, остаются общими для всего запуска. Полученные патчи и события возвращаются вызывающей стороне; исполнитель их не применяет.
 
+### Прерывание цепочки
+
+Не-`success` итог шага меняет дальнейшее поведение в зависимости от режима:
+
+| Итог      | `sequence`            | `selector`              |
+| --------- | --------------------- | ----------------------- |
+| `skipped` | **прерывает остаток** | пробует следующую ветку |
+
+`sequence` — режим по умолчанию, и он прерывает оставшиеся `then`-цели на _любом_ не-`success` (`skipped`, `stopped`, `failed`) — не только на сбое. Условный шаг внутри последовательности — это, таким образом, скрытый ранний выход для всего остатка. Если пропуск шага не должен рвать цепочку, заверните его в селектор с запасным `core.noop`.
+
+`terminal: true` останавливает `then`-цепочку после этой стратегии даже при `success`; `continue: false` в `ActionSuccess` даёт тот же эффект.
+
 ## Вспомогательные средства среды выполнения
 
 ```ts
@@ -261,6 +282,29 @@ type Runtime = {
 
 Чтение и запись путей во время выполнения реализованы непосредственно через `objwalk`.
 
+## Guards
+
+Переиспользуемые выражения `when` живут в карте `guards` на `Config` и подключаются к `when` стратегии (или шага `then`/`catch`) узлом `['guard', имя]`:
+
+```ts
+const config = {
+  guards: {
+    'has-colony': ['truthy', '$data.colonyId'],
+    'same-colony': ['eq', '$input.colonyId', '$context.colonyId'],
+  },
+  strategies: {
+    'colony.join': {
+      fn: 'colony.join',
+      when: ['and', ['guard', 'has-colony'], ['not', ['guard', 'same-colony']]],
+    },
+  },
+}
+```
+
+Guard — это обычное `ConditionExpression`, и сам может ссылаться на другие guards. Ссылки раскрываются один раз при загрузке конфигурации (`loadConfig`), до того как рантайм что-либо вычисляет, поэтому рантайм никогда не видит узел `['guard', ...]`. Guards раскрываются рекурсивно через `and`/`or`/`not`; ссылка на несуществующий guard даёт ошибку валидации `GUARD_NOT_FOUND`, а взаимные ссылки — `GUARD_CYCLE`. Значение guard должно быть выражением-условием, а не строкой `$path`.
+
+Guards существуют, чтобы критерий истинности жил в одном месте, а не дублировался по стратегиям; это вычисляемые данные, а не зарегистрированный код (в отличие от `registerCondition`, который регистрирует функцию-оператор).
+
 ## Проверка конфигурации
 
 `validateConfig` проверяет:
@@ -270,7 +314,8 @@ type Runtime = {
 - отсутствующие стратегии в `then`, `catch` и `entrypoints`;
 - недопустимые режимы;
 - недопустимые ссылки на пути;
-- циклы без завершающего шага.
+- циклы без завершающего шага;
+- ссылки на guards (`GUARD_NOT_FOUND`, `GUARD_CYCLE`, `GUARD_INVALID`).
 
 ## Трассировка
 
@@ -308,11 +353,14 @@ unsubscribe()
 
 ```ts
 type Bus<TEvents extends object = Record<string, unknown>> = {
-  on<TEvent extends keyof TEvents>(
-    event: TEvent,
-    handler: (event: BusEvent<TEvents[TEvent]>) => void
-  ): () => void
-  off<TEvent extends keyof TEvents>(event: TEvent, handler?: (event: BusEvent<TEvents[TEvent]>) => void): void
+  on: {
+    <TEvent extends keyof TEvents>(event: TEvent, handler: (event: BusEvent<TEvents[TEvent]>) => void): () => void
+    (event: EventPattern, handler: (event: BusEvent<unknown>) => void): () => void
+  }
+  off: {
+    <TEvent extends keyof TEvents>(event: TEvent, handler?: (event: BusEvent<TEvents[TEvent]>) => void): void
+    (event: EventPattern, handler?: (event: BusEvent<unknown>) => void): void
+  }
   emit<TEvent extends keyof TEvents>(
     topic: TEvent,
     payload: TEvents[TEvent],
@@ -320,6 +368,8 @@ type Bus<TEvents extends object = Record<string, unknown>> = {
   ): BusEvent<TEvents[TEvent]>
 }
 
+type EventPattern = `${string}*${string}`
+
 type BusEvent<TPayload> = {
   id: string
   topic: string
@@ -332,6 +382,18 @@ type BusEvent<TPayload> = {
 
 `emit` создаёт конверт и сериализует полезную нагрузку один раз до запуска подписчиков. Идентификаторы событий — непрозрачные 12-символьные буквенно-цифровые runtime-ID для корреляции и подавления эха. Они не криптографически стойкие: не используйте их для access token, подписей, публичных ссылок или иных security-sensitive задач. `on` возвращает функцию отписки. `off(event, handler)` удаляет один обработчик, а `off(event)` очищает канал. Ошибка одного подписчика не блокирует остальных; `createPubSub({ onError })` получает ошибку и исходное событие. При ошибке сериализации шина передаёт `{ error }` в качестве `parsed` и тело ошибки в качестве `serialized`, после чего вызывает `onError` с исходной причиной.
 
+### Подписка по шаблону
+
+На тему можно подписаться по шаблону, где `*` соответствует ровно одному сегменту, разделённому точкой. Шаблонный символ не пересекает границу `.`.
+
+```ts
+bus.on('hub.user.*', ({ parsed }) => {}) // hub.user.created, hub.user.deleted
+bus.on('hub.*.created', ({ parsed }) => {}) // hub.user.created, hub.team.created
+bus.on('hub.*.export', ({ parsed }) => {}) // НЕ hub.user.audit.export (один сегмент)
+```
+
+Подписки с точным именем остаются O(1); шаблоны обрабатываются отдельно, поэтому регистрации без `*` не несут накладных затрат на сравнение. Обработчик шаблона получает `parsed` как `unknown` — сужайте тип перед использованием. Шаблоны работают в `bus.on`/`bus.off`.
+
 ## Поток
 
 `createFlow` объединяет конфигурацию, действия, условия, поставщик контекста и привязки событий. Функция создаёт исполнитель (доступный через `flow.runner`) и поддерживает жизненный цикл `start`/`stop`.
@@ -415,24 +477,30 @@ type ConcurrencyOptions<TPayload> = {
 
 `defaultInput` имеет тип `{ type, value?, dataset, form? }`. `dataset` содержит все атрибуты `data-*` совпавшего элемента в виде ключей camelCase. `form` строится по ближайшему элементу `<form>`; повторяющиеся поля формы превращаются в массивы, а `File` остаётся `File`. Для `submit` значение `preventDefault` по умолчанию равно `true`; для остальных событий оно и `stopPropagation` по умолчанию равны `false`.
 
-### WebSocket-мост
+### WebSocket-клиент
 
-`createWS` подключает шину к WebSocket-подобному транспорту. Мост принимает `createSocket`, поэтому одинаково работает с браузерным WebSocket и серверным адаптером.
+`createWebSocket` открывает нативный `WebSocket` по `url` и проксирует каждое событие сокета в шину. Формат провода не предполагается — каждое событие отправляется с фиксированной темой и конвертом, где `parsed` содержит сырую полезную нагрузку.
 
 ```ts
-const ws = createWS({
+const socket = createWebSocket({
+  url,
   bus,
-  createSocket: () => new WebSocket(url),
-  inboundTopics: ['order.created'],
-  outboundTopics: ['slapflow.run.finished'],
-  origin: 'worker',
-  retry: { initialDelay: 500, maxDelay: 10_000, multiplier: 2, jitter: true, maxAttempts: 5 },
+  origin: 'client',
 })
 
-ws.start()
+socket.start()
 ```
 
-Входящие темы проходят через явный список разрешений. Мост разбирает JSON-конверт и вызывает `bus.dispatch(event)`, сохраняя `id`, `occurredAt`, `origin`, `parsed` и `serialized`; принятые входящие идентификаторы запоминаются и не отправляются обратно наружу. Исходящие темы отправляют полный JSON-конверт события, поэтому удалённый мост может передать его в шину, не создавая новый идентификатор. `maxAttempts` ограничивает reconnect; без него повторы идут бесконечно. `start`, `stop`, `reconnect` и `status` управляют жизненным циклом транспорта. Диагностические события: `slapflow.ws.connecting`, `slapflow.ws.connected`, `slapflow.ws.disconnected`, `slapflow.ws.retrying` и `slapflow.ws.message.rejected`.
+```ts
+bus.on('message', ({ parsed }) => {}) // parsed = сырое сообщение (JSON-декодированное, когда возможно)
+bus.on('open', ({ parsed }) => {}) // { url }
+bus.on('close', ({ parsed }) => {}) // { code, reason }
+bus.on('error', ({ parsed }) => {}) // { error }
+```
+
+События сокета приходят с темой `open`, `message`, `close` или `error`. Полезная нагрузка `message` JSON-декодируется в `parsed`, если валидна, иначе остаётся сырой строкой. Фильтрация тем — забота потребителя: внутри клиента ничего не разрешается и не отклоняется. `reconnect` принимает `initialDelay`, `maxDelay`, `multiplier`, `jitter` и `maxAttempts`; без `maxAttempts` повторы идут бесконечно. `start`, `stop`, `reconnect` и `status` управляют жизненным циклом; статус — одно из `idle`, `connecting`, `connected`, `reconnecting` или `stopped`.
+
+`createWS` помечен как deprecated и будет удалён; мигрируйте на `createWebSocket`.
 
 ## Ограничения безопасности
 

package/SPEC.md

@@ -12,23 +12,20 @@ The package is not coupled to a UI, server framework, scheduler, or domain model
 
 ```ts
 import {
-  createActionsRegistry,
-  createConditionsRegistry,
+  BUILTIN_ACTIONS,
+  BUILTIN_CONDITIONS,
   createMemoryTraceSink,
   defineErrorReporter,
   createPubSub,
   PubSub,
   createFlow,
-  createWS,
+  createWebSocket,
   catchError,
 } from 'slapflow'
 ```
 
 ```ts
-const flow = createFlow<Context, Patch>(
-  { config: { strategies: {} } },
-  { context: () => ({} as Context) }
-)
+const flow = createFlow<Context, Patch>({ config: { strategies: {} } }, { context: () => ({}) as Context })
 const runner = flow.runner
 
 runner.registerAction('jobs.execute', executeJob)
@@ -45,8 +42,11 @@ type Config = {
   version?: 1
   strategies: Record<string, Strategy>
   entrypoints?: Record<string, string>
+  guards?: Record<string, ConditionExpression>
 }
 
+type ConditionExpression = boolean | [operator: string, ...args: unknown[]] | ['guard', name: string]
+
 type Strategy = {
   fn: string
   props?: Record<string, unknown>
@@ -79,7 +79,7 @@ const reportError = defineErrorReporter({
 
 const flow = createFlow(
   { config: { strategies: {} } },
-  { context: () => ({} as Context), trace: true, onError: reportError }
+  { context: () => ({}) as Context, trace: true, onError: reportError }
 )
 ```
 
@@ -113,29 +113,38 @@ type ErrorStage = {
 
 If an error is recovered through `catch`, `onError` is still invoked for the original failure and the final `run` may finish with `success`.
 
+## Action Return Normalization
+
+An action's return value is normalized into one outcome. The mapping:
+
+| Return                                            | Outcome                                                         |
+| ------------------------------------------------- | --------------------------------------------------------------- |
+| `undefined` / `null`                              | `success`                                                       |
+| `false`                                           | `skipped`                                                       |
+| `{ type: 'skip', reason?, data? }`                | `skipped` (a selector tries the next branch)                    |
+| `{ type: 'stop', reason?, patch?, events? }`      | `stopped` (the chain halts without error)                       |
+| `{ type: 'fail', reason?, data?, error? }`        | `failed` (`catch` runs, then `onError`)                         |
+| `{ context?, data?, patch?, events?, continue? }` | `success`; `continue: false` halts the remaining `then` targets |
+
+A thrown exception is treated as `fail`. Returning `false` and `{ type: 'skip' }` are equivalent.
+
 ## Registry Model
 
-The runner uses runner-scoped registries:
+Built-ins live in two shared constants, one per kind:
 
-```text
-src/registry/
-  actions.ts
-  conditions.ts
+```ts
+import { BUILTIN_ACTIONS, BUILTIN_CONDITIONS } from 'slapflow'
 ```
 
-`createActionsRegistry()` creates a `Map` prepopulated with built-in actions.
+`BUILTIN_ACTIONS` is a readonly `[name, action][]` list prepopulated with built-in actions; `BUILTIN_CONDITIONS` holds built-in conditions. Each runner receives its own `new Map(BUILTIN_ACTIONS)` / `new Map(BUILTIN_CONDITIONS)` seed, so registrations stay isolated per runner.
 
-`createConditionsRegistry()` creates a `Map` prepopulated with built-in conditions.
-
-Each runner receives its own mutable registry copy. Applications can override any built-in action or condition:
+Built-ins are immutable defaults: `registerAction` and `registerCondition` reject an attempt to override a built-in name.
 
 ```ts
 runner.registerAction('app.setData', customSetData)
-runner.registerCondition('eq', customEq)
+runner.registerCondition('hasQueue', hasItems)
 ```
 
-Built-ins are therefore default values, not a separate immutable layer.
-
 Configuration validation accesses registries through the minimal `has(name)` contract.
 
 ## Built-In Actions
@@ -225,6 +234,18 @@ export const config = {
 
 `parallel` runs `then` targets independently. Plain objects and arrays in runtime context and data are cloned for each branch; infrastructure values such as functions, DOM nodes, and class instances remain references. Safety limits, including `maxStepCount`, remain shared by the whole run. Resulting patches and events are returned to the caller; the runner does not apply them.
 
+### Chain interruption
+
+A non-`success` outcome at a step changes what happens next, depending on the mode:
+
+| Outcome   | `sequence`              | `selector`            |
+| --------- | ----------------------- | --------------------- |
+| `skipped` | **interrupts the rest** | tries the next branch |
+
+`sequence` is the default mode and interrupts the remaining `then` targets on _any_ non-`success` (`skipped`, `stopped`, `failed`) — not only on failure. A conditional step inside a sequence is therefore a hidden early exit for the whole remainder. When skipping a step must not break the chain, wrap it in a selector with a `core.noop` fallback.
+
+`terminal: true` stops the `then` chain after that strategy even on `success`; `continue: false` in `ActionSuccess` has the same effect.
+
 ## Runtime Helpers
 
 ```ts
@@ -261,6 +282,29 @@ type Runtime = {
 
 Runtime path get/set is implemented directly through `objwalk`.
 
+## Guards
+
+Reusable `when` expressions live in the `guards` map on `Config` and are referenced from a strategy's `when` (or a `then`/`catch` step's `when`) with the `['guard', name]` node:
+
+```ts
+const config = {
+  guards: {
+    'has-colony': ['truthy', '$data.colonyId'],
+    'same-colony': ['eq', '$input.colonyId', '$context.colonyId'],
+  },
+  strategies: {
+    'colony.join': {
+      fn: 'colony.join',
+      when: ['and', ['guard', 'has-colony'], ['not', ['guard', 'same-colony']]],
+    },
+  },
+}
+```
+
+A guard is a plain `ConditionExpression` and may itself reference other guards. References are expanded once when the config is loaded (`loadConfig`), before the runtime evaluates anything, so the runtime never sees a `['guard', ...]` node. Guards are resolved recursively through `and`/`or`/`not`; a reference to an undefined guard is a `GUARD_NOT_FOUND` validation error, and mutually referencing guards produce `GUARD_CYCLE`. A guard value must be a condition expression, not a `$path` string.
+
+Guards exist so a truth criterion can live in one place instead of being duplicated across strategies; they are evaluated data, not registered code (unlike `registerCondition`, which registers an operator function).
+
 ## Validation
 
 `validateConfig` validates:
@@ -270,7 +314,8 @@ Runtime path get/set is implemented directly through `objwalk`.
 - missing strategies in `then`, `catch`, and `entrypoints`;
 - invalid modes;
 - invalid path references;
-- cycles without a terminal step.
+- cycles without a terminal step;
+- guard references (`GUARD_NOT_FOUND`, `GUARD_CYCLE`, `GUARD_INVALID`).
 
 ## Trace
 
@@ -308,11 +353,14 @@ unsubscribe()
 
 ```ts
 type Bus<TEvents extends object = Record<string, unknown>> = {
-  on<TEvent extends keyof TEvents>(
-    event: TEvent,
-    handler: (event: BusEvent<TEvents[TEvent]>) => void
-  ): () => void
-  off<TEvent extends keyof TEvents>(event: TEvent, handler?: (event: BusEvent<TEvents[TEvent]>) => void): void
+  on: {
+    <TEvent extends keyof TEvents>(event: TEvent, handler: (event: BusEvent<TEvents[TEvent]>) => void): () => void
+    (event: EventPattern, handler: (event: BusEvent<unknown>) => void): () => void
+  }
+  off: {
+    <TEvent extends keyof TEvents>(event: TEvent, handler?: (event: BusEvent<TEvents[TEvent]>) => void): void
+    (event: EventPattern, handler?: (event: BusEvent<unknown>) => void): void
+  }
   emit<TEvent extends keyof TEvents>(
     topic: TEvent,
     payload: TEvents[TEvent],
@@ -320,6 +368,8 @@ type Bus<TEvents extends object = Record<string, unknown>> = {
   ): BusEvent<TEvents[TEvent]>
 }
 
+type EventPattern = `${string}*${string}`
+
 type BusEvent<TPayload> = {
   id: string
   topic: string
@@ -332,6 +382,18 @@ type BusEvent<TPayload> = {
 
 `emit` creates an envelope and serializes the payload once before subscribers run. Event identifiers are opaque 12-character alphanumeric runtime IDs for correlation and echo suppression. They are not cryptographically secure and must not be used for access tokens, signatures, public links, or any security-sensitive purpose. `on` returns an unsubscribe function. `off(event, handler)` removes one handler, while `off(event)` clears the channel. An error in one subscriber does not block the others; `createPubSub({ onError })` receives the error and original event. On serialization failure, the bus delivers `{ error }` as `parsed` and the error body as `serialized`, then calls `onError` with the original cause.
 
+### Wildcard subscriptions
+
+A topic may be subscribed by pattern, using `*` to match exactly one dot-delimited segment. A wildcard does not cross a `.` boundary.
+
+```ts
+bus.on('hub.user.*', ({ parsed }) => {}) // hub.user.created, hub.user.deleted
+bus.on('hub.*.created', ({ parsed }) => {}) // hub.user.created, hub.team.created
+bus.on('hub.*.export', ({ parsed }) => {}) // NOT hub.user.audit.export (wildcard spans one segment)
+```
+
+Exact-name subscriptions stay O(1); wildcard patterns are matched separately, so registrations without `*` pay no matching cost. A wildcard handler receives `parsed` as `unknown` — narrow it before use. Wildcards work in `bus.on`/`bus.off`.
+
 ## Flow
 
 `createFlow` combines configuration, actions, conditions, a context provider, and event bindings. It creates a runner (accessible via `flow.runner`) and supports the `start`/`stop` lifecycle.
@@ -415,24 +477,30 @@ A DOM binding key uses the `[dom] <css-selector>:<event>` format. Slapflow insta
 
 `defaultInput` has type `{ type, value?, dataset, form? }`. `dataset` contains all `data-*` attributes from the matching element as camelCase keys. `form` is built from the nearest `<form>`; repeated form entries become arrays and `File` remains `File`. For `submit`, `preventDefault` defaults to `true`; for other events, it and `stopPropagation` default to `false`.
 
-### WebSocket Bridge
+### WebSocket Client
 
-`createWS` connects a bus to a WebSocket-like transport. The bridge accepts `createSocket`, so it works with browser WebSocket and a server adapter alike.
+`createWebSocket` opens a native `WebSocket` to `url` and proxies every socket event into the bus. No wire format is assumed — each event is dispatched with a fixed topic and an envelope whose `parsed` holds the raw payload.
 
 ```ts
-const ws = createWS({
+const socket = createWebSocket({
+  url,
   bus,
-  createSocket: () => new WebSocket(url),
-  inboundTopics: ['order.created'],
-  outboundTopics: ['slapflow.run.finished'],
-  origin: 'worker',
-  retry: { initialDelay: 500, maxDelay: 10_000, multiplier: 2, jitter: true, maxAttempts: 5 },
+  origin: 'client',
 })
 
-ws.start()
+socket.start()
 ```
 
-Inbound topics pass an explicit allowlist. The bridge parses a JSON envelope and calls `bus.dispatch(event)`, preserving `id`, `occurredAt`, `origin`, `parsed`, and `serialized`; it remembers accepted inbound IDs and does not send them back outbound. Outbound topics send the complete event envelope as JSON, so the remote bridge can dispatch it without recreating its identity. `maxAttempts` limits reconnects; omitting it retries indefinitely. `start`, `stop`, `reconnect`, and `status` manage the transport lifecycle. Diagnostics: `slapflow.ws.connecting`, `slapflow.ws.connected`, `slapflow.ws.disconnected`, `slapflow.ws.retrying`, and `slapflow.ws.message.rejected`.
+```ts
+bus.on('message', ({ parsed }) => {}) // parsed = the raw message (JSON-decoded when possible)
+bus.on('open', ({ parsed }) => {}) // { url }
+bus.on('close', ({ parsed }) => {}) // { code, reason }
+bus.on('error', ({ parsed }) => {}) // { error }
+```
+
+Socket events are forwarded with the topic `open`, `message`, `close`, or `error`. `message` payloads are JSON-decoded into `parsed` when valid, otherwise kept as the raw string. Filtering topics is the consumer's responsibility — nothing is allow-listed or rejected inside the client. `reconnect` accepts `initialDelay`, `maxDelay`, `multiplier`, `jitter`, and `maxAttempts`; omitting `maxAttempts` retries indefinitely. `start`, `stop`, `reconnect`, and `status` manage the lifecycle; status is one of `idle`, `connecting`, `connected`, `reconnecting`, or `stopped`.
+
+`createWS` is deprecated and will be removed; migrate to `createWebSocket`.
 
 ## Safety Limits