@ignex/nova 0.1.1 → 0.1.3

package/src/codegen/schema-model.ts

@@ -0,0 +1,338 @@
+/**
+ * Normalizes TypeBox schemas into a simple wire model shared by every emitter
+ * (.fbs, Rust glue, TS registry). All emitters derive field order / naming from
+ * this single model, so the Rust builder and the flatc-generated TS decoders
+ * are wire-compatible by construction.
+ */
+import type { TSchema } from "@sinclair/typebox";
+
+export type FieldKind =
+  | "string"
+  | "double"
+  | "int64"
+  | "bool"
+  | "enum"
+  | "table"
+  | "vector-string"
+  | "vector-double"
+  | "vector-int64"
+  | "vector-bool"
+  | "vector-enum"
+  | "vector-table";
+
+export interface FieldDef {
+  /** camelCase, matches the TypeBox/Events key */
+  jsonName: string;
+  /** snake_case, the wire (.fbs / flatc) field name */
+  fbName: string;
+  /** whether the field is required in the TypeBox schema */
+  required: boolean;
+  kind: FieldKind;
+  enumName?: string;
+  tableName?: string;
+  /** int64 field decoded/encoded as `bigint` (Type.Integer({ bigint: true })) — exact beyond 2^53 */
+  bigint?: boolean;
+}
+
+export interface TableDef {
+  name: string;
+  fields: FieldDef[];
+}
+
+export interface EnumDef {
+  name: string;
+  values: string[];
+}
+
+export interface EventDef {
+  name: string;
+  tableName: string;
+  /** transport-internal event (hello/subscribe/ping/...); hidden from the public Events surface */
+  control?: boolean;
+}
+
+export interface Model {
+  enums: EnumDef[];
+  tables: TableDef[];
+  events: EventDef[];
+}
+
+/**
+ * Codegen context shared by every emitter. In-repo generation (scripts/
+ * generate.ts) leaves it empty and the generated files import the repo's own
+ * modules with relative paths. User-mode generation (public/generate.ts) sets
+ * `schemaImport: null` (the generated code emits self-contained local payload
+ * types instead of importing the user's schema module) and `libraryImport` to
+ * the package the internal helpers should come from.
+ */
+export interface EmitContext {
+  /** import specifier for schema TYPE imports ("../schema" in-repo). null → local types. */
+  schemaImport?: string | null;
+  /** user mode: where internal runtime helpers (codec / int64-guard / pooledByteBuffer / assembleBindings) come from. */
+  libraryImport?: string;
+}
+
+/** A table is "flat" when every field maps to a direct FFI arg (no tables/vectors). */
+export function isFlatTable(t: TableDef): boolean {
+  return t.fields.every(
+    (f) =>
+      f.kind === "string" ||
+      f.kind === "double" ||
+      f.kind === "int64" ||
+      f.kind === "bool" ||
+      f.kind === "enum",
+  );
+}
+
+/**
+ * A table is "directable" when every field is either a flat scalar/string/enum
+ * OR a packed vector (scalars/strings/enums, or tables whose elements are flat).
+ * Directable events serialize with ZERO allocations and NO JSON — vectors travel
+ * as a packed binary blob (`read_packed_*` on the Rust side).
+ */
+export function isDirectableTable(m: Model, t: TableDef): boolean {
+  return t.fields.every((f) => {
+    switch (f.kind) {
+      case "string":
+      case "double":
+      case "int64":
+      case "bool":
+      case "enum":
+        return true;
+      case "vector-table": {
+        const elem = m.tables.find((e) => e.name === f.tableName);
+        return elem ? isFlatTable(elem) : false;
+      }
+      case "vector-string":
+      case "vector-double":
+      case "vector-int64":
+      case "vector-bool":
+      case "vector-enum":
+        return true;
+      default:
+        return false;
+    }
+  });
+}
+
+export function isDirectableEvent(m: Model, ev: EventDef): boolean {
+  const t = m.tables.find((t) => t.name === ev.tableName);
+  return !!t && t.fields.length > 0 && isDirectableTable(m, t);
+}
+
+export function toSnake(s: string): string {
+  return s
+    .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+    .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+    .toLowerCase();
+}
+
+export function toPascal(s: string): string {
+  const cleaned = s.replace(/[^a-zA-Z0-9]+(.)?/g, (_m, c: string) => (c ? c.toUpperCase() : ""));
+  return cleaned.charAt(0).toUpperCase() + cleaned.slice(1);
+}
+
+type AnySchema = Record<string, any>;
+
+interface Ctx {
+  named: Map<object, string>;
+  used: Set<string>;
+  enums: EnumDef[];
+  tables: TableDef[];
+  events: EventDef[];
+  enumById: Map<object, string>;
+  tableById: Map<object, string>;
+}
+
+function uniqueName(ctx: Ctx, base: string): string {
+  let name = base;
+  let i = 2;
+  while (ctx.used.has(name)) {
+    name = `${base}${i}`;
+    i++;
+  }
+  ctx.used.add(name);
+  return name;
+}
+
+function unionMembers(s: AnySchema): AnySchema[] {
+  return (s.anyOf ?? s.oneOf ?? []) as AnySchema[];
+}
+
+const isStringLiteral = (m: AnySchema): boolean => typeof m?.const === "string";
+const isNullMember = (m: AnySchema): boolean => m?.type === "null";
+const isObjectLike = (m: AnySchema): boolean => m?.type === "object" && typeof m?.properties === "object";
+
+function registerEnum(ctx: Ctx, schema: AnySchema, values: string[], jsonName: string): string {
+  const existing = ctx.enumById.get(schema);
+  if (existing) return existing;
+  const name = uniqueName(ctx, toPascal(jsonName));
+  ctx.enums.push({ name, values });
+  ctx.enumById.set(schema, name);
+  return name;
+}
+
+function ensureTable(ctx: Ctx, schema: AnySchema, fallbackName: string): string {
+  const existing = ctx.tableById.get(schema);
+  if (existing) return existing;
+
+  const name = ctx.named.get(schema) ?? uniqueName(ctx, fallbackName);
+  if (!ctx.used.has(name)) ctx.used.add(name);
+  ctx.tableById.set(schema, name);
+  // placeholder first so recursive/self references terminate
+  ctx.tables.push({ name, fields: [] });
+
+  const props = (schema.properties ?? {}) as Record<string, AnySchema>;
+  const required: string[] = schema.required ?? [];
+  const fields: FieldDef[] = [];
+  for (const [jsonName, propSchema] of Object.entries(props)) {
+    const resolved = resolveFieldType(ctx, propSchema, jsonName, name);
+    fields.push({
+      jsonName,
+      fbName: toSnake(jsonName),
+      required: required.includes(jsonName),
+      ...resolved,
+    });
+  }
+  const table = ctx.tables.find((t) => t.name === name)!;
+  table.fields = fields;
+  return name;
+}
+
+function resolveFieldType(
+  ctx: Ctx,
+  schema: AnySchema,
+  jsonName: string,
+  parentName: string,
+): { kind: FieldKind; enumName?: string; tableName?: string; bigint?: boolean } {
+  const members = unionMembers(schema);
+  if (members.length > 0) {
+    if (members.every(isStringLiteral)) {
+      const enumName = registerEnum(ctx, schema, members.map((m) => m.const as string), jsonName);
+      return { kind: "enum", enumName };
+    }
+    const tableMember = members.find(isObjectLike);
+    if (tableMember && members.filter((m) => !isNullMember(m)).length === 1) {
+      const tableName = ensureTable(ctx, tableMember, `${parentName}${toPascal(jsonName)}`);
+      return { kind: "table", tableName };
+    }
+    return { kind: "string" };
+  }
+
+  switch (schema.type) {
+    case "string": {
+      if (typeof schema.const === "string") {
+        const enumName = registerEnum(ctx, schema, [schema.const], jsonName);
+        return { kind: "enum", enumName };
+      }
+      return { kind: "string" };
+    }
+    case "number":
+      return { kind: "double" };
+    case "integer":
+      return { kind: "int64" };
+    case "bigint":
+      // Type.BigInt() → EXACT int64 (decoded/encoded as bigint, not number)
+      return { kind: "int64", bigint: true };
+    case "boolean":
+      return { kind: "bool" };
+    case "array": {
+      const items = schema.items as AnySchema | undefined;
+      if (!items) return { kind: "vector-double" };
+      if (isObjectLike(items)) {
+        const tableName = ensureTable(ctx, items, `${parentName}${toPascal(jsonName)}Item`);
+        return { kind: "vector-table", tableName };
+      }
+      const itemMembers = unionMembers(items);
+      if (itemMembers.length > 0 && itemMembers.every(isStringLiteral)) {
+        const enumName = registerEnum(ctx, items, itemMembers.map((m) => m.const as string), jsonName);
+        return { kind: "vector-enum", enumName };
+      }
+      switch (items.type) {
+        case "string":
+          return { kind: "vector-string" };
+        case "number":
+          return { kind: "vector-double" };
+        case "integer":
+          return { kind: "vector-int64" };
+        case "boolean":
+          return { kind: "vector-bool" };
+        default:
+          return { kind: "vector-double" };
+      }
+    }
+    case "object": {
+      if (!isObjectLike(schema)) return { kind: "string" };
+      const tableName = ensureTable(ctx, schema, `${parentName}${toPascal(jsonName)}`);
+      return { kind: "table", tableName };
+    }
+    default:
+      return { kind: "string" };
+  }
+}
+
+/** TS type expression for a plain-object field (used by user-mode codegen). */
+export function plainTsType(m: Model, f: FieldDef, suffix = "Payload"): string {
+  switch (f.kind) {
+    case "string":
+      return f.required ? "string" : "string | undefined";
+    case "double":
+      return "number";
+    case "int64":
+      return f.bigint ? "bigint" : "number";
+    case "bool":
+      return "boolean";
+    case "enum":
+      return enumUnion(m, f);
+    case "table":
+      return f.required ? `${f.tableName}${suffix}` : `${f.tableName}${suffix} | undefined`;
+    case "vector-string":
+      return `string[]${f.required ? "" : " | undefined"}`;
+    case "vector-double":
+      return `number[]${f.required ? "" : " | undefined"}`;
+    case "vector-int64":
+      return `number[]${f.required ? "" : " | undefined"}`;
+    case "vector-bool":
+      return `boolean[]${f.required ? "" : " | undefined"}`;
+    case "vector-enum":
+      return `(${enumUnion(m, f)})[]${f.required ? "" : " | undefined"}`;
+    case "vector-table":
+      return `${f.tableName}${suffix}[]${f.required ? "" : " | undefined"}`;
+    default:
+      return "unknown";
+  }
+}
+
+/** string literal union of the enum values, e.g. `"buy" | "sell"`. */
+export function enumUnion(m: Model, f: FieldDef): string {
+  const values = m.enums.find((e) => e.name === f.enumName)?.values ?? [];
+  return values.map((v) => JSON.stringify(v)).join(" | ");
+}
+
+export function buildModel(
+  namedSchemas: Record<string, TSchema>,
+  eventSchemas: Record<string, TSchema>,
+  controlEventSchemas: Record<string, TSchema> = {},
+): Model {
+  const ctx: Ctx = {
+    named: new Map(),
+    used: new Set(),
+    enums: [],
+    tables: [],
+    events: [],
+    enumById: new Map(),
+    tableById: new Map(),
+  };
+  for (const [name, schema] of Object.entries(namedSchemas)) {
+    ctx.named.set(schema as object, name);
+  }
+  for (const [name, schema] of Object.entries(eventSchemas)) {
+    const tableName = ensureTable(ctx, schema as AnySchema, toPascal(name));
+    ctx.events.push({ name, tableName });
+  }
+  for (const [name, schema] of Object.entries(controlEventSchemas)) {
+    const tableName = ensureTable(ctx, schema as AnySchema, toPascal(name));
+    ctx.events.push({ name, tableName, control: true });
+  }
+  return { enums: ctx.enums, tables: ctx.tables, events: ctx.events };
+}

package/src/codegen/ts-ser-gen.ts

@@ -0,0 +1,221 @@
+import type { EmitContext, FieldDef, Model } from "./schema-model";
+import { plainTsType, toSnake } from "./schema-model";
+
+/**
+ * Emits `src/generated/ts-ser.ts` — the PURE-JS (browser-safe) object → FlatBuffer
+ * encoder, built on flatc's generated object API (`.T` classes + `pack()`).
+ *
+ * This is the OTHER half of bidirectionality: the Rust FFI serializer only
+ * exists on the Bun server, so browser clients cannot use it. `ts-ser` gives
+ * any JS runtime (browser or Bun) a way to encode EVERY event — including the
+ * transport control frames (hello/subscribe/ping/...) — into the same wire
+ * format `[WIRE_VERSION][event_id:u32][size-prefixed FlatBuffer]`.
+ *
+ * Key points:
+ *   - Reuses a single pooled `flatbuffers.Builder` (`getBuilder()`); each
+ *     encode clears it, so `encodeEventFrame` (which copies into a fresh
+ *     frame) is the safe public API.
+ *   - int64 fields convert `number → BigInt` (the flatc object API uses bigint);
+ *   - string enums map to flatc numeric enum values via generated lookups.
+ *   - Emits `build<Table>T` helpers for nested tables (table / vector-table).
+ *
+ * `ctx.schemaImport === null` (user-mode codegen) emits self-contained local
+ * `Events` / `ControlEvents` payload maps (over the already-local `XxxPlain`
+ * types) instead of importing the app schema.
+ */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: string-emitting codegen is inherently branchy
+export function emitTsSer(m: Model, ctx: EmitContext = {}): string {
+  const needed = new Set<string>();
+  const visit = (name: string) => {
+    if (needed.has(name)) return;
+    needed.add(name);
+    const t = m.tables.find((t) => t.name === name)!;
+    for (const f of t.fields) {
+      if (f.kind === "table" || f.kind === "vector-table") visit(f.tableName!);
+    }
+  };
+  for (const ev of m.events) visit(ev.tableName);
+  const neededTables = m.tables.filter((t) => needed.has(t.name));
+
+  // enums actually used by a needed table
+  const usedEnums = new Map<string, string[]>();
+  for (const t of neededTables) {
+    for (const f of t.fields) {
+      if (f.kind === "enum" || f.kind === "vector-enum") {
+        const e = m.enums.find((e) => e.name === f.enumName!);
+        if (e) usedEnums.set(e.name, e.values);
+      }
+    }
+  }
+
+  const userMode = ctx.schemaImport === null;
+  const schemaImport = userMode ? "" : (ctx.schemaImport ?? "../schema");
+
+  const lines: string[] = [];
+  lines.push("// @generated by src/codegen/ts-ser-gen.ts — DO NOT EDIT");
+  lines.push('import * as flatbuffers from "flatbuffers";');
+  lines.push("import {");
+  for (const t of neededTables) lines.push(`  ${t.name}T,`);
+  lines.push('} from "./ts/backend";');
+  lines.push('import { anyEventNameToId, WIRE_HEADER_LEN, WIRE_VERSION } from "./registry";');
+  if (!userMode) {
+    lines.push(
+      `import type { AnyEventName, ControlEvents, Events } from ${JSON.stringify(schemaImport)};`,
+    );
+  }
+  lines.push("");
+  if (userMode) lines.push(...emitLocalTypeMap(m, appEventsOf(m), controlEventsOf(m)));
+  lines.push("/** string → flatc numeric enum value lookups */");
+  for (const [name, values] of usedEnums) {
+    const entries = values.map((v) => `${v}: ${values.indexOf(v)}`).join(", ");
+    lines.push(`const ${toSnake(name).toUpperCase()} = { ${entries} } as const;`);
+  }
+  if (usedEnums.size > 0) lines.push("");
+  lines.push(
+    "/** pooled builder — each encode clears it (safe because encodeEventFrame copies). */",
+  );
+  lines.push("let shared: flatbuffers.Builder | null = null;");
+  lines.push("function getBuilder(): flatbuffers.Builder {");
+  lines.push("  if (!shared) shared = new flatbuffers.Builder(1024);");
+  lines.push("  return shared;");
+  lines.push("}");
+  lines.push("");
+
+  // per-table plain input types
+  for (const t of neededTables) {
+    lines.push(`type ${t.name}Plain = {`);
+    for (const f of t.fields)
+      lines.push(`  ${f.jsonName}${f.required ? "" : "?"}: ${plainTsType(m, f, "Plain")};`);
+    lines.push("};");
+    lines.push("");
+  }
+
+  // per-table builders (plain object → flatc .T)
+  for (const t of neededTables) {
+    lines.push(`function build${t.name}T(o: ${t.name}Plain): ${t.name}T {`);
+    lines.push("  return new " + t.name + "T(");
+    for (const f of t.fields) lines.push(`    ${ctorArg(f, "o")},`);
+    lines.push("  );");
+    lines.push("}");
+    lines.push("");
+  }
+
+  // per-event payload encoders (size-prefixed flatbuffer only)
+  for (const ev of m.events) {
+    const annot = ev.control
+      ? `ControlEvents[${JSON.stringify(ev.name)}]`
+      : `Events[${JSON.stringify(ev.name)}]`;
+    lines.push(
+      `/** ${ev.control ? "control " : ""}payload encoder: plain object → size-prefixed FlatBuffer. */`,
+    );
+    lines.push(
+      `export function encode${pascal(ev.name)}Payload(o: ${annot}, b: flatbuffers.Builder = getBuilder()): Uint8Array {`,
+    );
+    lines.push("  b.clear();");
+    lines.push(`  b.finishSizePrefixed(build${ev.tableName}T(o).pack(b));`);
+    lines.push("  return b.asUint8Array();");
+    lines.push("}");
+    lines.push("");
+  }
+
+  lines.push("export type JsEncoder = (o: unknown, b?: flatbuffers.Builder) => Uint8Array;");
+  lines.push("");
+  lines.push("export const jsEncoders: Record<string, JsEncoder> = {");
+  for (const ev of m.events)
+    lines.push(`  ${ev.name}: encode${pascal(ev.name)}Payload as JsEncoder,`);
+  lines.push("};");
+  lines.push("");
+  lines.push("/** Encode a payload (app or control event) → size-prefixed FlatBuffer. */");
+  lines.push(
+    "export function encodeJsPayload(name: AnyEventName, o: unknown, b?: flatbuffers.Builder): Uint8Array {",
+  );
+  lines.push("  const enc = jsEncoders[name];");
+  lines.push('  if (!enc) throw new Error(`ignex: no JS encoder for "${name}" — regenerate`);');
+  lines.push("  return enc(o, b);");
+  lines.push("}");
+  lines.push("");
+  lines.push(
+    "/** Encode a payload into a full wire frame `[version][event_id:u32][size-prefixed FB]`. */",
+  );
+  lines.push(
+    "export function encodeEventFrame(name: AnyEventName, o: unknown, b?: flatbuffers.Builder): Uint8Array {",
+  );
+  lines.push("  const payload = encodeJsPayload(name, o, b);");
+  lines.push("  const id = anyEventNameToId[name]!;");
+  lines.push("  const frame = new Uint8Array(WIRE_HEADER_LEN + payload.byteLength);");
+  lines.push("  frame[0] = WIRE_VERSION;");
+  lines.push("  new DataView(frame.buffer).setUint32(1, id, true);");
+  lines.push("  frame.set(payload, WIRE_HEADER_LEN);");
+  lines.push("  return frame;");
+  lines.push("}");
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function appEventsOf(m: Model) {
+  return m.events.filter((e) => !e.control);
+}
+function controlEventsOf(m: Model) {
+  return m.events.filter((e) => e.control);
+}
+
+/** Local `EventName` / `Events` / `ControlEvents` type map over the XxxPlain types. */
+function emitLocalTypeMap(
+  _m: Model,
+  appEvents: Model["events"],
+  controlEvents: Model["events"],
+): string[] {
+  const lines: string[] = [];
+  lines.push(`export type EventName = ${appEvents.map((e) => `"${e.name}"`).join(" | ")};`);
+  lines.push(
+    `export type ControlEventName = ${controlEvents.map((e) => `"${e.name}"`).join(" | ")};`,
+  );
+  lines.push("export type AnyEventName = EventName | ControlEventName;");
+  lines.push("");
+  lines.push("export type Events = {");
+  for (const ev of appEvents) lines.push(`  ${JSON.stringify(ev.name)}: ${ev.tableName}Plain;`);
+  lines.push("};");
+  lines.push("export type ControlEvents = {");
+  for (const ev of controlEvents) lines.push(`  ${JSON.stringify(ev.name)}: ${ev.tableName}Plain;`);
+  lines.push("};");
+  lines.push("");
+  return lines;
+}
+
+function ctorArg(f: FieldDef, o: string): string {
+  const j = `${o}.${f.jsonName}`;
+  switch (f.kind) {
+    case "string":
+      // flatc .T strings are nullable; absent optional → null
+      return f.required ? j : `${j} ?? null`;
+    case "double":
+      return j;
+    case "int64":
+      // bigint-annotated fields are already bigint (pass through); plain int64
+      // are `number` in the Events type → BigInt for the flatc object API
+      return f.bigint ? j : `${j} === undefined ? 0n : BigInt(${j})`;
+    case "bool":
+      return j;
+    case "enum":
+      return `${toSnake(f.enumName!).toUpperCase()}[${j}]`;
+    case "table":
+      return f.required ? `build${f.tableName}T(${j})` : `${j} ? build${f.tableName}T(${j}) : null`;
+    case "vector-string":
+    case "vector-double":
+    case "vector-bool":
+      return `(${j} ?? [])`;
+    case "vector-int64":
+      return `(${j} ?? []).map((v) => BigInt(v))`;
+    case "vector-enum":
+      return `(${j} ?? []).map((v) => ${toSnake(f.enumName!).toUpperCase()}[v])`;
+    case "vector-table":
+      return `(${j} ?? []).map((v) => build${f.tableName}T(v))`;
+    default:
+      return j;
+  }
+}
+
+function pascal(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}

package/src/codegen/typebox-to-fbs.ts

@@ -0,0 +1,60 @@
+import type { FieldDef, Model } from "./schema-model";
+
+function fbTypeOf(f: FieldDef): string {
+  switch (f.kind) {
+    case "string":
+      return "string";
+    case "double":
+      return "double";
+    case "int64":
+      return "int64";
+    case "bool":
+      return "bool";
+    case "enum":
+      return f.enumName!;
+    case "table":
+      return f.tableName!;
+    case "vector-string":
+      return "[string]";
+    case "vector-double":
+      return "[double]";
+    case "vector-int64":
+      return "[int64]";
+    case "vector-bool":
+      return "[bool]";
+    case "vector-enum":
+      return `[${f.enumName}]`;
+    case "vector-table":
+      return `[${f.tableName}]`;
+  }
+}
+
+/**
+ * TypeBox model → FlatBuffers schema (.fbs). No namespace is used so both
+ * `flatc --ts` and `flatc --rust` emit flat, predictable modules. Each event
+ * table is its own root (finished size-prefixed on the Rust side, read with
+ * `getSizePrefixedRootAsXxx` on the TS side).
+ */
+export function emitFbs(m: Model): string {
+  const lines: string[] = [];
+  lines.push("// @generated by src/codegen/typebox-to-fbs.ts — DO NOT EDIT");
+  lines.push("// FlatBuffers schema derived from the TypeBox events registry (schema/index.ts).");
+  lines.push("");
+  lines.push('file_identifier "IGNX";');
+  lines.push("");
+  for (const e of m.enums) {
+    lines.push(`enum ${e.name} : int32 {`);
+    e.values.forEach((v, i) => lines.push(`  ${v.toUpperCase()} = ${i},`));
+    lines.push("}");
+    lines.push("");
+  }
+  for (const t of m.tables) {
+    lines.push(`table ${t.name} {`);
+    for (const f of t.fields) {
+      lines.push(`  ${f.fbName}:${fbTypeOf(f)};`);
+    }
+    lines.push("}");
+    lines.push("");
+  }
+  return lines.join("\n");
+}

package/src/core/auth.ts

@@ -47,7 +47,8 @@ export async function checkUpgrade(
     topics: new Set(),
     groups: new Set(authMeta?.groups ?? []),
     id,
-    meta: authMeta?.meta,
+    ...(authMeta?.userId !== undefined ? { userId: authMeta.userId } : {}),
+    ...(authMeta?.meta !== undefined ? { meta: authMeta.meta } : {}),
     connectedAt: Date.now(),
   };
   // bun-types requires the WebSocketData options arg when Data != undefined

package/src/core/client-heartbeat.ts

@@ -2,8 +2,9 @@
  * Client app-level Ping/Pong heartbeat — detects half-open connections and
  * forces a close so the reconnect path re-establishes the socket.
  */
-import { sendControl } from "./client-wire";
+
 import type { ClientState } from "./client-state";
+import { sendControl } from "./client-wire";
 
 export function startHeartbeat(state: ClientState): void {
   const ms = state.opts.heartbeatMs ?? 15000;

package/src/core/client-reconnect.ts

@@ -3,10 +3,17 @@
  * drives the state machine. `connect` is passed in by the composition root so
  * the timer can re-establish the socket.
  */
-import { setStatus, type ClientState, type IgnClientOptions, type IgnReconnectOptions } from "./client-state";
+
+import type { Bindings } from "../bindings/types";
+import {
+  type ClientState,
+  type IgnClientOptions,
+  type IgnReconnectOptions,
+  setStatus,
+} from "./client-state";
 
 /** Resolve the effective reconnect options (defaults applied). */
-export function reconnectOpts(opts: IgnClientOptions): IgnReconnectOptions | null {
+export function reconnectOpts(opts: IgnClientOptions<Bindings>): IgnReconnectOptions | null {
   const rc = opts.reconnect;
   if (rc === undefined || rc === false) return null;
   if (rc === true) return { initialDelay: 250, maxDelay: 30000, jitter: true };