@ignex/nova 0.1.1 → 0.1.3

package/docs/events.md

@@ -0,0 +1,170 @@
+# Events layer — typed event-driven system on the FlatBuffer core
+
+The events layer (`@ignex/nova/events`, opt-in via `createServer({ events })`) is
+the application-facing, event-driven surface on top of the transport: **an
+events file receives events, and a global emit sends events through
+websockets** — with first-class client records, named groups, and
+cross-instance sync for horizontally scaled deployments.
+
+Enable it (everything else is opt-in):
+
+```ts
+import { createServer } from "@ignex/nova/server";
+
+const server = createServer({
+  port: 3000,
+  events: {
+    onConnect: (client) => client.data.set("connectedAt", client.connectedAt),
+  },
+});
+```
+
+`server.events` is the hub; the module-global singleton
+(`@ignex/nova/events`) is bound to it by default.
+
+## The events file (receiving events)
+
+Declare handlers like routes — a dedicated events file where inbound events
+arrive. The handler receives the payload and a context describing **who sent
+it and how to reply**:
+
+```ts
+// app/events.ts
+import { on, emitToUser, emitToGroup } from "@ignex/nova/events";
+
+on("chat.message", (payload, ctx) => {
+  // ctx.client — the sender's connection record (id, userId, data, groups…)
+  // ctx.emit / ctx.emitToUser / … — reply without importing the singleton
+  emitToUser(payload.to, "chat.delivered", { id: payload.id });
+});
+
+on("order.created", (payload, ctx) => {
+  emitToGroup("backoffice", "order.alert", { orderId: payload.orderId });
+});
+```
+
+- `hub.on(name, handler)` / `off` / `once` / `onAny` — multiple handlers per
+  event, per-handler error isolation (one throwing handler never blocks the
+  others; failures count in `metrics().handlerErrors`).
+- `hub.onServerEvent(name, handler)` — server-side handling of events that
+  arrive from OTHER instances or the NATS bridge (`ctx.source` is
+  `"remote"`/`"bridge"`, `ctx.client` is undefined). Do NOT re-emit the same
+  event from these handlers (loop).
+- `on` auto-allows the event for inbound clients (`server.allowInbound`);
+  `onAny` sees every event listed in `events.inbound`.
+
+## The global emit (sending events through websockets)
+
+`emit` and friends are importable anywhere — no server reference needed:
+
+```ts
+import { emit, emitToGroup, emitToUser, emitToClient, emitToTopic } from "@ignex/nova/events";
+
+emit("quote", { symbol: "AAPL", bid: 180.1, ask: 180.2 });          // broadcast
+emitToGroup("traders", "alert", { text: "halt" });                  // group fan-out
+emitToUser("u-42", "order.update", { orderId: "o-1" });             // user's sockets
+emitToClient("c-123", "session.expired", { reason: "idle" });       // one connection
+```
+
+Or the discriminated `EmitTarget` — the API's way of **differentiating**
+between addressing modes:
+
+```ts
+server.events.emit("quote", payload, { type: "group", group: "traders" });
+server.events.emit("quote", payload, { type: "user", userId: "u-42" });
+```
+
+When the cluster is configured, every emit is cluster-aware: the target is
+matched against clients on ALL instances.
+
+## Client records — who is connected, on whose behalf
+
+Each active connection is a `client` record:
+
+```ts
+interface EventClient {
+  id: string;              // connection id (unique per socket)
+  userId?: string;         // identity this connection acts ON BEHALF OF
+  meta?: Record<string, unknown>; // auth metadata
+  data: ClientData;        // per-connection app store (auto-cleared on close)
+  groups: ReadonlySet<string>;    // client groups (shared with ws.data)
+  topics: ReadonlySet<string>;    // joined topics (shared with ws.data)
+  connectedAt: number; ip: string; closed: boolean; ws: ServerWebSocket;
+}
+```
+
+- `userId` — "on what behalf": set from `authenticate` (`{ userId }`),
+  `hub.setUserId(clientId, userId)`, or later. Several sockets may share one
+  `userId` (multi-tab / multi-device); `hub.clientsByUser(userId)` groups
+  them and `emitToUser` reaches all of them.
+- `data` — per-connection state (`client.data.set(key, value)` or
+  `hub.setClientData(clientId, key, value)`); with a shared state store it
+  syncs cluster-wide (`hub.remoteClientData(clientId)`).
+- `hub.client(id)` / `clients()` / `clientCount` — live introspection.
+- Lifecycle hooks: `events.onConnect(client)` (seed data) and
+  `events.onDisconnect(client)`.
+
+## Groups — broadcast to groups vs individual users
+
+Two group kinds, clearly differentiated:
+
+| | `hub.group(name)` | `hub.userGroup(name)` |
+|---|---|---|
+| membership | connection ids | user ids |
+| fan-out | members' sockets | every socket of each member user |
+| shares transport groups | yes (`ws.data.groups`, control frames, `server.joinGroup`) | hub-managed |
+| cluster membership | shared state store (`clusterGroupMembers`) | shared state store (`clusterUserGroupMembers`) |
+
+```ts
+const traders = server.events.group("traders");       // client group
+traders.add(clientId); traders.remove(clientId);
+traders.members(); traders.emit("quote", payload);
+
+const ops = server.events.userGroup("ops");           // user group
+ops.add("u-42"); ops.emit("alert", { text: "pager" }); // all of u-42's sockets
+```
+
+## Horizontal scaling (cluster sync)
+
+When multiple instances share a broker, every emit is delivered to the
+target's clients on every instance. Heavy work never runs on the hot path:
+local delivery is synchronous (encode once via the transport scratch + `ws.send`),
+everything else (broker publishes, state-store writes, presence maintenance) is
+deferred to a bounded offload queue (`events.queue`, drop-newest on overflow).
+
+- **NATS** (server ⇄ server): reuse the server bridge with
+  `cluster: { nats: true }`, or a dedicated/different bridge
+  (`nats: NatsBridgeOptions | NatsBridge`).
+- **Redis**: `cluster: { redis: { url: "redis://…" } }` (lazy `ioredis`
+  optional peer dependency — `bun add ioredis`).
+- **Custom**: `cluster: { transport: MyClusterTransport }` (tests use an
+  in-memory bus).
+- Self-delivery dedupe: frames carry the origin `instanceId`
+  (`cluster.instanceId`, random by default); an instance drops its own frames,
+  so a broadcast is delivered exactly once per socket.
+- **Presence with no shared state**: join/leave + periodic heartbeat messages
+  — `hub.clusterClients()` lists connections on other instances.
+- **Shared state store** (`cluster.state`, default per-instance memory;
+  production: `createRedisStateStore(...)`): user→clients index
+  (`clusterUserClients`), cluster group membership, cluster-wide client data.
+- **Server-side events**: other instances' events reach `onServerEvent`
+  handlers with `ctx.source === "remote"` (delivered to clients AND handlers);
+  NATS-inbound events reach them with `source === "bridge"`.
+
+## Metrics & shutdown
+
+`server.getMetrics().events` (or `hub.metrics()`) exposes emitted counts per
+target, delivered local frames, cluster received/self-dropped/errors,
+queue and handler errors, presence sizes. `hub.close()` unsubscribes,
+flushes the queue, announces leaves, and closes owned transports; call it via
+`server.drain()` / `server.stop()`.
+
+## Performance notes
+
+- Zero-alloc local encode + fan-out (the transport scratch is reused; Bun
+  copies on `ws.send`) — the emit call is O(target sockets).
+- The cluster publish copies the frame once (required — the scratch is
+  reused) and enqueues; a slow or offline broker never blocks the socket loop
+  and never throws into it.
+- Without `events`, there is zero overhead; the global functions throw a
+  descriptive error if no hub is bound.

package/docs/generic-bindings.md

@@ -0,0 +1,197 @@
+# Generic bindings — bring your own schema
+
+`@ignex/nova` is schema-driven: **any** TypeBox schema you define in your app can
+be turned into a full wire stack (FlatBuffers schema, TS decoders, pure-JS
+encoder, Rust FFI fast path, NATS wire registry) with one function call —
+`generateBindings(schema)` — and then served / consumed / bridged through the
+same `createServer` / `createClient` / `createNatsBridge` APIs, fully typed
+against **your** events.
+
+```
+your app
+  src/schema.ts (TypeBox — source of truth)
+        │  scripts/generate-bindings.ts
+        │  import { generateBindings } from "@ignex/nova/generate";
+        ▼
+  ignex/generated/  (backend.fbs, ts/decoders, registry.ts, ts-ser.ts,
+                     direct-ser.ts, wire-registry.json, rust/ crate, index.ts)
+        │  makeBindings(yourSchema) → Bindings
+        ▼
+  createServer({ bindings }) · createClient(url, { bindings }) · createNatsBridge({ bindings })
+```
+
+## 1. Define your schema (TypeBox)
+
+```ts
+// src/schema.ts — your app's single source of truth
+import { Type } from "@sinclair/typebox";
+
+export const ChatMsg = Type.Object(
+  { room: Type.String(), text: Type.String(), ts: Type.Integer() },
+  { additionalProperties: false },
+);
+export const Telemetry = Type.Object(
+  { device: Type.String(), readings: Type.Array(Type.Number()), ok: Type.Boolean() },
+  { additionalProperties: false },
+);
+
+export const schemas = { ChatMsg, Telemetry };
+export const events = { chat: ChatMsg, telemetry: Telemetry };
+export const controlEvents = {}; // optional extra transport-internal events
+```
+
+Rules (same as the built-in registry):
+
+- `Type.Object({...}, { additionalProperties: false })` for payloads.
+- `Type.Integer()` → int64; `Type.Integer({ bigint: true })` / `Type.BigInt()`
+  → exact bigint int64 (lossless beyond 2^53).
+- String-literal unions (`Type.Union([Type.Literal("a"), ...])`) → enums.
+- Arrays of scalars / strings / enums / flat objects → vectors (packed on the
+  direct fast path). Nested objects → tables. Tables-in-tables fall back to the
+  JSON path.
+- The transport control events (hello / welcome / subscribe / unsubscribe /
+  joinGroup / leaveGroup / snapshotRequest / ping / pong) are ALWAYS included —
+  you can add your own but cannot override the standard ones.
+
+## 2. Generate bindings
+
+> `scripts/generate-bindings.ts` is an example filename **you** give a script in your own app — it is not a file shipped in the `@ignex/nova` package, so don't go looking for it in `node_modules`.
+
+```ts
+// scripts/generate-bindings.ts — run once per schema change
+import { generateBindings } from "@ignex/nova/generate";
+import { schemas, events, controlEvents } from "../src/schema";
+
+const gen = generateBindings(
+  { schemas, events, controlEvents },
+  { outDir: "./ignex/generated" }, // default
+);
+const written = gen.write(); // e.g. 26 files under ignex/generated/
+console.log("generated:", written.length, "files");
+```
+
+Requirements: `flatc` on PATH (the FlatBuffers compiler — the same prerequisite
+as the built-in registry: `brew install flatbuffers` /
+`apt install flatbuffers-compiler`). Pass `rust: false` to skip the Rust crate
+scaffold (you lose the FFI fast path; the pure-JS encoder is still used).
+
+The output folder contains:
+
+| File | Role |
+| --- | --- |
+| `backend.fbs` | FlatBuffers schema (wire layout for independent consumers) |
+| `ts/*.ts` | flatc-generated decoders (browser + Bun) |
+| `registry.ts` | event ids, `readFrameHeader` / `decodePayload` / `decodeFrame`, `SCHEMA_FINGERPRINT` |
+| `ts-ser.ts` | pure-JS encoder (works in the browser) |
+| `direct-ser.ts` | direct fast-path serde (Bun server, when FFI is used) |
+| `wire-registry.json` | machine-readable event-id registry for NATS consumers |
+| `rust/` | a complete cargo crate — build it for the FFI fast path |
+| `index.ts` | `makeBindings(schema)` — assembles the runtime `Bindings` |
+
+## 3. Assemble the bindings and use the APIs
+
+```ts
+// bindings.ts
+import { makeBindings } from "./ignex/generated"; // generated
+import * as schema from "../src/schema";
+
+export const bindings = makeBindings(schema);
+export type AppEvents = import("@ignex/nova").EventsOf<typeof bindings>;
+```
+
+```ts
+// server.ts (Bun)
+import { createServer } from "@ignex/nova/server";
+import { bindings } from "./bindings";
+
+const server = createServer({
+  port: 3000,
+  bindings,
+  inbound: ["chat"],                       // events clients may send
+  nats: { servers: ["nats://localhost:4222"], inbound: true, bridgeClientEvents: true },
+});
+server.publish("chat", { room: "lobby", text: "hello", ts: Date.now() }); // typed!
+server.on("chat", (msg, ws) => console.log(msg.room, msg.text));
+```
+
+```ts
+// FE (browser or Bun)
+import { createClient } from "@ignex/nova/client";
+import { bindings } from "./bindings";
+
+const client = createClient("ws://localhost:3000/ws", { bindings });
+client.on("telemetry", (t) => console.log(t.device, t.readings)); // typed!
+client.send("chat", { room: "lobby", text: "hi from FE", ts: Date.now() });
+client.connect();
+```
+
+The whole public surface is generic:
+
+- `createServer({ bindings })` → `publish` / `publishToTopic` / `publishToGroup`
+  / `on` / … typed against your `Events`.
+- `createClient(url, { bindings })` → `on` / `send` / `once` / `onAny` / …
+  typed against your `Events`.
+- `createNatsBridge({ bindings })` → decodes inbound frames with your schema.
+
+## Rust FFI fast path (optional)
+
+By default generated bindings use `ffiMode: "optional"`: the server tries the
+Rust addon only when you point `IGNEX_FFI_PATH` at one — otherwise it silently
+uses the pure-JS encoder (correct everywhere, just not zero-allocation). To get
+the fast path:
+
+```bash
+cd ignex/generated/rust
+cargo build --release            # produces libignex_ffi.so/.dylib/.dll
+IGNEX_FFI_PATH=$(pwd)/target/release/libignex_ffi.so bun run your-server.ts
+```
+
+The cdylib exports a **schema fingerprint** (`fb_schema_fingerprint`) that the
+bind-time self-test checks against `SCHEMA_FINGERPRINT` in your generated
+registry — a stale or schema-mismatched addon fails loudly instead of producing
+undecodable frames. (`ffiMode: "required"` makes a missing/mismatched addon a
+hard error.)
+
+## NATS & horizontal scaling
+
+Point every server instance at the same NATS and the same subject prefix, and
+they behave as one hub:
+
+- Every `publish` / `publishToTopic` / `publishToGroup` is ALSO published to
+  NATS as the identical wire frame (`{prefix}.broadcast.<event>`,
+  `{prefix}.topic.<topic>.<event>`, `{prefix}.group.<group>.<event>`) — any
+  backend (BE) service can consume them with the wire registry +
+  `backend.fbs`.
+- External producers (or BE services) publish on `{prefix}.inbound.>`; every
+  server forwards those events to its own clients.
+- With `nats.bridgeClientEvents: true`, events that a client sends to ONE
+  server are re-published to `{prefix}.inbound.<event>`, so all other servers'
+  clients receive them too — client messages become cluster-wide. Loop
+  prevention is built in: frames that arrive via NATS are forwarded to clients
+  but never re-bridged.
+
+```
+             ┌─────────────┐  publish("chat", …)   ┌─────────────┐
+ FE client ─▶│ server A    │──────▶ NATS ◀─────────│ server B    │◀─ FE client
+             │ ignex.*     │                        │ ignex.*     │
+             └─────────────┘                        └─────────────┘
+                     │  inbound.<event> (client-sent, bridgeClientEvents)
+                     └──────────────▶ BE consumers (any language)
+```
+
+Because the wire bytes are schema-derived, all instances must run the SAME
+generated bindings (same event names → same FNV-1a ids). Changing the schema
+changes the fingerprint — regenerate all instances together.
+
+## Independent (non-JS) consumers
+
+`wire-registry.json` maps event names → stable FNV-1a ids, and `backend.fbs`
+is the FlatBuffer layout — decode bridged NATS frames in any language. See
+`docs/wire-format.md` for the envelope.
+
+## What about the built-in events?
+
+The built-in registry (quote/trade/portfolio/…) is just the default
+`Bindings` (`defaultBindings`); every API accepts `bindings` and defaults to
+it, so existing code is untouched. Use the built-in events as a reference for
+schema style — your app's schema works exactly the same way.

package/docs/publishing.md

@@ -10,9 +10,9 @@ mirrors how the `@ignex/*` packages in the Ignex monorepo are shipped.
 | Field | Value | Why |
 | --- | --- | --- |
 | `main` / `module` / `types` | `./index.ts` | source entrypoint (Bun-native) |
-| `exports` | `.` → `index.ts`, `./server` → `public/server.ts`, `./client` → `public/client.ts`, `./nats` → `public/nats.ts`, `./package.json` | typed subpath API |
+| `exports` | `@ignex/nova` → `index.ts`; `@ignex/nova/server` → `public/server.ts`; `@ignex/nova/client` → `public/client.ts`; `@ignex/nova/nats` → `public/nats.ts`; `@ignex/nova/events` → `public/events.ts`; `@ignex/nova/bindings` → `public/bindings.ts`; `@ignex/nova/generate` → `public/generate.ts`; `@ignex/nova/internal` → `public/internal.ts`; `@ignex/nova/package.json` → `package.json` | typed subpath API |
 | `files` | `index.ts`, `public`, `src`, `rust`, `prebuilds`, `docs`, `README.md`, `LICENSE` | everything consumers need, nothing they don't |
-| `publishConfig` | `{ "access": "public" }` | unscoped package must be public |
+| `publishConfig` | `{ "access": "public" }` | scoped packages are restricted by default — `access: public` publishes `@ignex/nova` publicly |
 | `engines` | `{ "bun": ">=1.4" }` | Bun-only runtime |
 | `sideEffects` | `false` | safe to tree-shake / mark in bundlers |
 

package/docs/wire-format.md

@@ -113,8 +113,8 @@ Bridge state is observable via `server.getMetrics()`
 ### Decoding bridged frames (external consumers)
 
 `bun run generate` emits `src/generated/wire-registry.json` — a machine-readable
-`{ version, events: { name: id } }` map of the FNV-1a ids. A consumer in any
-language:
+`{ version, fingerprint, events: { name: id } }` map of the FNV-1a ids. A
+consumer in any language:
 
 1. reads `version` (byte 0) and `event_id` (bytes 1..5) from the frame,
 2. maps `event_id` → name via `wire-registry.json`,
@@ -123,6 +123,13 @@ language:
 
 See `examples/nats-consumer.ts` for a working reference.
 
+For YOUR OWN schema, `generateBindings` (see
+[docs/generic-bindings.md](generic-bindings.md)) emits the same
+`backend.fbs` + `wire-registry.json` into your project, plus a `fingerprint`
+field — the cdylib and the generated registry share it, so a schema-mismatched
+native addon fails the bind-time self-test instead of emitting undecodable
+frames.
+
 ## Heartbeat
 
 Clients send `ping` every `heartbeatMs` (default 15000). The server replies

package/index.ts

@@ -2,45 +2,61 @@
  * ignex-nova — public package root.
  *
  * Re-exports the full typed pub/sub API (server + client + NATS bridge +
- * schema types) so a single `import ... from "ignex-nova"` works in Bun
- * projects.
+ * schema types + generic bindings codegen) so a single `import ... from
+ * "@ignex/nova"` works in Bun projects.
  *
  * For leaner / target-specific imports use the subpath entrypoints — each
  * resolves to its own source file and tree-shakes independently:
  *
- *   import { createServer } from "ignex-nova/server";   // Bun-only (Rust FFI)
- *   import { createClient } from "ignex-nova/client";   // browser + Bun
- *   import { createNatsBridge } from "ignex-nova/nats"; // standalone bridge
+ *   import { createServer } from "@ignex/nova/server";     // Bun-only (Rust FFI)
+ *   import { createClient } from "@ignex/nova/client";     // browser + Bun
+ *   import { createNatsBridge } from "@ignex/nova/nats";   // standalone bridge
+ *   import { on, emit } from "@ignex/nova/events";         // events layer + global emit
+ *   import { generateBindings } from "@ignex/nova/generate"; // ANY-schema codegen
+ *   import { assembleBindings, defaultBindings } from "@ignex/nova/bindings";
+ *   import { encodeUtf8Into } from "@ignex/nova/internal";   // codegen helpers
  *
  * Note: the root entry also pulls in the Bun-only server + FFI path, so
- * browser bundles should import "ignex-nova/client" instead.
+ * browser bundles should import "@ignex/nova/client" instead.
  *
  * The README (and docs/publishing.md) covers consuming this from an npm
- * package: `bun add ignex-nova`, then use the subpaths above.
+ * package: `bun add @ignex/nova`, then use the subpaths above.
  */
-export { createServer } from "./public/server";
-export type {
-  IgnServer,
-  ClientInfo,
-  IgnServerOptions,
-  IgnBackpressureOptions,
-  BackpressurePolicy,
-  WsData,
-  ClientMeta,
-  AuthResult,
-  MetricsSnapshot,
-  Int64GuardMode,
-} from "./public/server";
 
-export { createClient } from "./public/client";
 export type {
+  AssembleOptions,
+  Bindings,
+  BindingsParts,
+  ControlEventNameOf,
+  ControlEventsOf,
+  DefaultBindings,
+  DirectCall,
+  DirectEncoder,
+  DirectTables,
+  EventNameOf,
+  EventsOf,
+} from "./public/bindings";
+export { assembleBindings, defaultBindings } from "./public/bindings";
+export type {
+  ClientStatus,
   IgnClient,
   IgnClientOptions,
   IgnReconnectOptions,
-  ClientStatus,
 } from "./public/client";
 
-export { createNatsBridge, createSubjectBuilder } from "./public/nats";
+export { createClient } from "./public/client";
+export type { GeneratedBindings, GenerateOptions, SchemaRegistry } from "./public/generate";
+// ── generic bindings (ANY schema) ──────────────────────────────────────────
+export { generateBindings } from "./public/generate";
+// runtime helpers used by generated code (also exported via `@ignex/nova/internal`)
+export {
+  checkInt64,
+  encodeUtf8Into,
+  ensureCapacity,
+  pooledByteBuffer,
+  setInt64GuardMode,
+  utf8Len,
+} from "./public/internal";
 export type {
   NatsBridge,
   NatsBridgeOptions,
@@ -49,13 +65,45 @@ export type {
   NatsTransport,
   SubjectBuilder,
 } from "./public/nats";
+export { createNatsBridge, createSubjectBuilder } from "./public/nats";
+// events layer types (the runtime singleton API is `@ignex/nova/events`)
+export type {
+  AuthResult,
+  BackpressurePolicy,
+  ClientData,
+  ClientGroup,
+  ClientInfo,
+  ClientMeta,
+  ClusterStateStore,
+  ClusterTransport,
+  EmitTarget,
+  EmitTargetKind,
+  EventClient,
+  EventContext,
+  EventHandler,
+  EventsClusterOptions,
+  EventsHub,
+  EventsMetricsSnapshot,
+  EventsOptions,
+  IgnBackpressureOptions,
+  IgnServer,
+  IgnServerOptions,
+  Int64GuardMode,
+  MetricsSnapshot,
+  RedisConnectionOptions,
+  RemoteClient,
+  ServerEventHandler,
+  UserGroup,
+  WsData,
+} from "./public/server";
+export { createServer } from "./public/server";
 
 // Plain-object payload types consumers type against (e.g. `Events["quote"]`).
 // Import as types only — the runtime `events` registry is transport-internal.
 export type {
-  Events,
-  EventName,
   AnyEventName,
-  ControlEvents,
   ControlEventName,
-} from "./src/schema";
+  ControlEvents,
+  EventName,
+  Events,
+} from "./src/schema";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ignex/nova",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "type": "module",
   "description": "TypeBox-driven FlatBuffer transport: Rust FFI serializer + Bun WebSocket + typed pub/sub API for server and FE.",
   "license": "MIT",
@@ -48,6 +48,10 @@
     "./server": "./public/server.ts",
     "./client": "./public/client.ts",
     "./nats": "./public/nats.ts",
+    "./events": "./public/events.ts",
+    "./bindings": "./public/bindings.ts",
+    "./generate": "./public/generate.ts",
+    "./internal": "./public/internal.ts",
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -57,7 +61,7 @@
     "generate": "bun scripts/generate.ts",
     "build:rust": "cargo build --release --manifest-path rust/Cargo.toml",
     "build:client": "bun build ./client/main.ts --outdir ./client-dist --target=browser --splitting",
-    "build:dist": "bun build ./index.ts ./public/server.ts ./public/client.ts ./public/nats.ts --outdir ./dist --target=bun --splitting && bunx tsc --emitDeclarationOnly -p tsconfig.dist.json",
+    "build:dist": "bun build ./index.ts ./public/server.ts ./public/client.ts ./public/nats.ts ./public/events.ts ./public/bindings.ts ./public/generate.ts ./public/internal.ts --outdir ./dist --target=bun --splitting && bunx tsc --emitDeclarationOnly -p tsconfig.dist.json",
     "build": "bun run generate && bun run build:rust && bun run build:client",
     "prebuild": "bun scripts/build-prebuild.ts",
     "test": "bun test",
@@ -65,6 +69,7 @@
     "typecheck": "bunx tsc --noEmit -p tsconfig.json",
     "verify": "bun run typecheck && bun run lint && bun test",
     "pack:check": "bun scripts/check-pack.ts",
+    "gen:ai-map": "bun scripts/gen-ai-map.ts",
     "serve": "bun run src/server.ts",
     "bench:serialize": "bun run bench/serialize.ts",
     "bench:throughput": "bun run bench/throughput.ts",
@@ -85,5 +90,10 @@
   },
   "peerDependencies": {
     "typescript": "^7"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    }
   }
 }

package/public/bindings.ts

@@ -0,0 +1,24 @@
+/**
+ * Public bindings API — `@ignex/nova/bindings`.
+ *
+ *   import { assembleBindings, defaultBindings } from "@ignex/nova/bindings";
+ *   import type { Bindings, EventsOf } from "@ignex/nova/bindings";
+ *
+ * `defaultBindings` is the built-in registry's wire stack; `assembleBindings`
+ * builds a `Bindings` from generated parts (see `@ignex/nova/generate`).
+ */
+
+export type { AssembleOptions, BindingsParts } from "../src/bindings/assemble";
+export { assembleBindings } from "../src/bindings/assemble";
+export { defaultBindings } from "../src/bindings/default";
+export type {
+  Bindings,
+  ControlEventNameOf,
+  ControlEventsOf,
+  DefaultBindings,
+  DirectCall,
+  DirectEncoder,
+  DirectTables,
+  EventNameOf,
+  EventsOf,
+} from "../src/bindings/types";

package/public/client.ts

@@ -3,7 +3,7 @@
  * build stable). The implementation lives in the functional modules under
  * `src/core/`; this file just exposes the public surface.
  *
- *   import { createClient } from "ignex-nova/client";
+ *   import { createClient } from "@ignex/nova/client";
  *
  *   const client = createClient("ws://localhost:3000/ws", { reconnect: true });
  *   client.on("quote", (q) => { /* q: Events["quote"] — a plain object *\/ });
@@ -11,6 +11,10 @@
  *   client.send("chat", {...});     // typed client→server (server must allow it)
  *   client.connect();
  *
+ *   // your own schema (see @ignex/nova/generate):
+ *   const client = createClient("ws://localhost:3000/ws", { bindings });
+ *   client.on("yourEvent", (e) => {...}); // typed against YOUR Events
+ *
  * Works in the browser (bundle with `bun build --target=browser`) AND in Bun.
  * Outgoing frames are encoded by the generated PURE-JS encoder — no Rust FFI
  * needed, so the browser can send too.