bonescript-compiler 0.8.0 → 0.11.0

package/src/emit_colyseus.ts

@@ -0,0 +1,867 @@
+/**
+ * BoneScript Colyseus Target Emitter
+ *
+ * Generates a Colyseus.io game server (v0.17) from `channel` declarations.
+ * One `Room` subclass per channel; authoritative state lives in a `Schema`
+ * class derived from the channel.
+ *
+ * Output:
+ *   src/index.ts            Colyseus Server bootstrap, registerRoom for each
+ *   src/rooms/<name>.ts     Room subclass per channel
+ *   src/state/<name>.ts     Schema class per channel
+ *   src/auth.ts             JWT verification helper (mirrors emit_runtime auth)
+ *   package.json, tsconfig.json, README.md
+ *
+ * Why a separate target rather than a flag on the Express target:
+ *   Colyseus rooms are authoritative process-locally. They speak msgpack-
+ *   encoded schema deltas over WebSocket. Mixing into the Express target
+ *   would mean co-hosting both servers, which is supported but adds
+ *   operational complexity for users who don't need realtime games.
+ */
+
+import * as IR from "./ir";
+import { EmittedFile } from "./emitter";
+
+function toSnakeCase(s: string): string {
+  return s.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase();
+}
+
+function toPascalCase(s: string): string {
+  return s.replace(/(^|[-_\s])(\w)/g, (_, __, c: string) => c.toUpperCase());
+}
+
+// ─── Type mapping for Colyseus @type decorators ────────────────────────────────
+
+const COLYSEUS_TYPE_MAP: Record<string, string> = {
+  string: '"string"',
+  uint: '"number"',
+  int: '"number"',
+  float: '"number"',
+  bool: '"boolean"',
+  timestamp: '"string"',
+  uuid: '"string"',
+  bytes: '"string"',
+  json: '"string"', // serialized JSON (Colyseus schemas don't have a JSON primitive)
+};
+
+function toColyseusType(irType: string): string {
+  return COLYSEUS_TYPE_MAP[irType] || '"string"';
+}
+
+function toTsTypeForSchema(irType: string): string {
+  switch (irType) {
+    case "string":
+    case "timestamp":
+    case "uuid":
+    case "bytes":
+    case "json":
+      return "string";
+    case "uint":
+    case "int":
+    case "float":
+      return "number";
+    case "bool":
+      return "boolean";
+    default:
+      return "string";
+  }
+}
+
+function defaultValueForType(irType: string): string {
+  switch (irType) {
+    case "string":
+    case "timestamp":
+    case "uuid":
+    case "bytes":
+    case "json":
+      return '""';
+    case "uint":
+    case "int":
+    case "float":
+      return "0";
+    case "bool":
+      return "false";
+    default:
+      return '""';
+  }
+}
+
+// ─── Per-channel state schema ─────────────────────────────────────────────────
+
+function emitStateSchema(channel: IR.IRModule, system: IR.IRSystem): EmittedFile {
+  void system;
+  const lines: string[] = [];
+  const channelName = toPascalCase(channel.name);
+  const stateName = `${channelName}State`;
+  const playerName = `${channelName}Player`;
+
+  // Auto-derived player fields from the channel's participant entity. The
+  // lowering serialised these as a JSON string in config.participant_fields.
+  // We fall back to a minimal {userId, sessionId, joinedAt} default if the
+  // channel doesn't reference an entity.
+  let participantFields: { name: string; type: string }[] = [];
+  const raw = channel.config["participant_fields"];
+  if (typeof raw === "string" && raw.length > 0) {
+    try {
+      const parsed = JSON.parse(raw);
+      if (Array.isArray(parsed)) participantFields = parsed;
+    } catch { /* ignore */ }
+  }
+
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Colyseus schema for channel: ${channel.name}`);
+  if (channel.config["participant_entity"]) {
+    lines.push(`// Player schema derived from entity: ${channel.config["participant_entity"]}`);
+  }
+  lines.push(``);
+  lines.push(`import { Schema, type, MapSchema } from "@colyseus/schema";`);
+  lines.push(``);
+  lines.push(`export class ${playerName} extends Schema {`);
+  // Always-present identity fields
+  lines.push(`  @type("string") userId: string = "";`);
+  lines.push(`  @type("string") sessionId: string = "";`);
+  lines.push(`  @type("number") joinedAt: number = 0;`);
+  // Auto-derived fields from the entity
+  for (const f of participantFields) {
+    if (["userId", "sessionId", "joinedAt", "id", "created_at", "updated_at"].includes(f.name)) continue;
+    const tsType = toTsTypeForSchema(f.type);
+    const dv = defaultValueForType(f.type);
+    lines.push(`  @type(${toColyseusType(f.type)}) ${f.name}: ${tsType} = ${dv};`);
+  }
+  lines.push(`}`);
+  lines.push(``);
+  lines.push(`export class ${stateName} extends Schema {`);
+  lines.push(`  @type({ map: ${playerName} }) players = new MapSchema<${playerName}>();`);
+  lines.push(`  @type("number") tick: number = 0;`);
+  lines.push(`  // Add channel-wide state fields here.`);
+  lines.push(`}`);
+  lines.push(``);
+
+  return {
+    path: `src/state/${toSnakeCase(channel.name)}.ts`,
+    content: lines.join("\n"),
+    language: "typescript",
+    source_module: channel.id,
+  };
+}
+
+// ─── Per-channel Room class ───────────────────────────────────────────────────
+
+function emitRoom(channel: IR.IRModule, _system: IR.IRSystem): EmittedFile {
+  const lines: string[] = [];
+  const channelName = toPascalCase(channel.name);
+  const roomName = `${channelName}Room`;
+  const stateName = `${channelName}State`;
+  const playerName = `${channelName}Player`;
+  const stateModule = toSnakeCase(channel.name);
+
+  const maxClients = (channel.config["max_size"] as number) || 16;
+  const ordering = (channel.config["ordering"] as string) || "fifo";
+  const persistence = (channel.config["persistence"] as string) || "none";
+
+  // Persistence: "last_N" → keep last N messages in room.history
+  // "database" → snapshot to disk on dispose, reload on create
+  const historyLimit = (() => {
+    const m = persistence.match(/^last_(\d+)$/);
+    if (m) return parseInt(m[1], 10);
+    if (persistence === "none") return 0;
+    if (persistence === "database") return 0; // db handles durability separately
+    return 100;
+  })();
+  const usesDatabase = persistence === "database";
+
+  // Capabilities to expose as typed onMessage handlers (everything past the
+  // 3 base methods: connect, subscribe, publish).
+  const allMethods = channel.interfaces[0]?.methods ?? [];
+  const baseMethodNames = new Set(["connect", "subscribe", "publish"]);
+  const capabilities = allMethods.filter(m => !baseMethodNames.has(m.name));
+
+  // Participant entity name (for typed param hints in capability signatures).
+  const participantEntity = (channel.config["participant_entity"] as string | undefined);
+
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Colyseus room for channel: ${channel.name}`);
+  lines.push(`// transport: ${channel.config["transport"] || "websocket"}`);
+  lines.push(`// ordering:  ${ordering}`);
+  lines.push(`// persistence: ${persistence}`);
+  if (capabilities.length > 0) {
+    lines.push(`// capabilities: ${capabilities.map(c => c.name).join(", ")}`);
+  }
+  lines.push(``);
+  lines.push(`import { Room, Client, ServerError, AuthContext } from "colyseus";`);
+  lines.push(`import { ${stateName}, ${playerName} } from "../state/${stateModule}";`);
+  lines.push(`import { verifyToken } from "../auth";`);
+  if (usesDatabase) {
+    lines.push(`import { loadSnapshot, saveSnapshot } from "../persistence";`);
+  }
+  lines.push(``);
+  lines.push(`interface AuthData {`);
+  lines.push(`  userId: string;`);
+  lines.push(`}`);
+  lines.push(``);
+
+  // Per-capability message payload interfaces. Lets handlers be type-safe.
+  for (const cap of capabilities) {
+    const inputs = cap.input.filter(i => {
+      if (!participantEntity) return true;
+      // Drop the participant entity param itself — that's "the calling client",
+      // resolved from sessionId rather than wire payload.
+      return i.type !== participantEntity;
+    });
+    if (inputs.length === 0) {
+      lines.push(`type ${toPascalCase(cap.name)}Payload = Record<string, never>;`);
+    } else {
+      lines.push(`interface ${toPascalCase(cap.name)}Payload {`);
+      for (const inp of inputs) {
+        lines.push(`  ${inp.name}: ${toTsTypeForSchema(inp.type)};`);
+      }
+      lines.push(`}`);
+    }
+  }
+  if (capabilities.length > 0) lines.push(``);
+
+  lines.push(`/**`);
+  lines.push(` * Channel: ${channel.name}`);
+  lines.push(` *`);
+  lines.push(` * Client connection example:`);
+  lines.push(` *`);
+  lines.push(` *   import { Client } from "@colyseus/sdk";`);
+  lines.push(` *   const client = new Client("ws://host:2567");`);
+  lines.push(` *   client.auth.token = "<jwt>";`);
+  lines.push(` *   const room = await client.joinOrCreate("${channel.name}");`);
+  lines.push(` *   room.state.players.onAdd((player, key) => { ... });`);
+  if (capabilities.length > 0) {
+    lines.push(` *   room.send("${capabilities[0].name}", { ... });  // → triggers capability`);
+  }
+  lines.push(` */`);
+  lines.push(`export class ${roomName} extends Room<{ state: ${stateName} }> {`);
+  lines.push(`  maxClients = ${maxClients};`);
+  lines.push(``);
+  lines.push(`  // Ring buffer of recent messages, replayed to new joiners when persistence != "none".`);
+  lines.push(`  private history: { type: string; payload: unknown; from: string; ts: number }[] = [];`);
+  lines.push(`  private readonly historyLimit = ${historyLimit};`);
+  if (usesDatabase) {
+    lines.push(``);
+    lines.push(`  // Save a snapshot every ${SNAPSHOT_INTERVAL_MS}ms while the room is active.`);
+    lines.push(`  private snapshotTimer: NodeJS.Timeout | null = null;`);
+  }
+  lines.push(``);
+  lines.push(`  /**`);
+  lines.push(`   * JWT-based auth. Token comes from the Authorization header set by the`);
+  lines.push(`   * client SDK via \`client.auth.token = "..."\`.`);
+  lines.push(`   *`);
+  lines.push(`   * Returns the user data (userId) on success. Throws ServerError on bad`);
+  lines.push(`   * tokens so the matchmaking call fails on the client.`);
+  lines.push(`   */`);
+  lines.push(`  static async onAuth(token: string, _options: Record<string, unknown>, _context: AuthContext): Promise<AuthData> {`);
+  lines.push(`    if (!token) throw new ServerError(401, "Missing auth token");`);
+  lines.push(`    const claims = verifyToken(token);`);
+  lines.push(`    if (!claims) throw new ServerError(401, "Invalid auth token");`);
+  lines.push(`    return { userId: claims.sub };`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  async onCreate(_options: Record<string, unknown>) {`);
+  lines.push(`    this.setState(new ${stateName}());`);
+
+  if (usesDatabase) {
+    lines.push(``);
+    lines.push(`    // Try to restore snapshot from durable storage on room creation.`);
+    lines.push(`    try {`);
+    lines.push(`      const snapshot = await loadSnapshot("${channel.name}", this.roomId);`);
+    lines.push(`      if (snapshot && typeof snapshot === "object") {`);
+    lines.push(`        const s = this.state as unknown as Record<string, unknown>;`);
+    lines.push(`        for (const [k, v] of Object.entries(snapshot)) {`);
+    lines.push(`          if (k === "players") continue; // sessions are not portable`);
+    lines.push(`          if (k in s) (s as any)[k] = v;`);
+    lines.push(`        }`);
+    lines.push(`        console.log(\`[${channel.name}] restored snapshot for room \${this.roomId}\`);`);
+    lines.push(`      }`);
+    lines.push(`    } catch (e: any) {`);
+    lines.push(`      console.warn(\`[${channel.name}] snapshot load failed: \${e.message}\`);`);
+    lines.push(`    }`);
+    lines.push(``);
+    lines.push(`    // Periodically save state to durable storage so a crash doesn't lose work.`);
+    lines.push(`    this.snapshotTimer = setInterval(() => {`);
+    lines.push(`      void saveSnapshot("${channel.name}", this.roomId, this.serializeStateForSnapshot()).catch(() => {});`);
+    lines.push(`    }, ${SNAPSHOT_INTERVAL_MS});`);
+  }
+
+  // Register typed handlers for each capability
+  for (const cap of capabilities) {
+    lines.push(``);
+    lines.push(`    // ${cap.name} — capability dispatch`);
+    lines.push(`    this.onMessage("${cap.name}", (client, payload: ${toPascalCase(cap.name)}Payload) => {`);
+    lines.push(`      this.handle${toPascalCase(cap.name)}(client, payload);`);
+    lines.push(`    });`);
+  }
+
+  lines.push(``);
+  lines.push(`    // Default fallback: rebroadcast unknown messages with sender attribution.`);
+  lines.push(`    // Handlers for known message types above take precedence (Colyseus 0.17`);
+  lines.push(`    // routes "*" only when no specific handler matches).`);
+  lines.push(`    this.onMessage("*", (client, type, payload) => {`);
+  lines.push(`      const userId = (client.userData as { userId?: string } | undefined)?.userId ?? client.sessionId;`);
+  lines.push(`      const msg = { type: String(type), payload, from: userId, ts: Date.now() };`);
+  lines.push(`      this.recordHistory(msg);`);
+  lines.push(`      this.broadcast(String(type), msg, { except: client });`);
+  lines.push(`    });`);
+  lines.push(`  }`);
+
+  // Per-capability handler implementations. Each applies effects to the
+  // calling client's player record (or the room state) and broadcasts.
+  for (const cap of capabilities) {
+    lines.push(``);
+    lines.push(emitCapabilityHandler(cap, participantEntity, channel.name));
+  }
+
+  lines.push(``);
+  lines.push(`  onJoin(client: Client, _options: Record<string, unknown>, auth: AuthData) {`);
+  lines.push(`    client.userData = { userId: auth.userId };`);
+  lines.push(``);
+  lines.push(`    const player = new ${playerName}();`);
+  lines.push(`    player.userId = auth.userId;`);
+  lines.push(`    player.sessionId = client.sessionId;`);
+  lines.push(`    player.joinedAt = Date.now();`);
+  lines.push(`    this.state.players.set(client.sessionId, player);`);
+  lines.push(``);
+  lines.push(`    console.log(\`[${channel.name}] \${auth.userId} joined (\${this.clients.length} clients, sessionId=\${client.sessionId})\`);`);
+  lines.push(``);
+  lines.push(`    // Replay history if configured`);
+  lines.push(`    if (this.historyLimit > 0 && this.history.length > 0) {`);
+  lines.push(`      client.send("__history__", { events: this.history });`);
+  lines.push(`    }`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  onLeave(client: Client, _code: number) {`);
+  lines.push(`    this.state.players.delete(client.sessionId);`);
+  lines.push(`    const userId = (client.userData as { userId?: string } | undefined)?.userId ?? client.sessionId;`);
+  lines.push(`    console.log(\`[${channel.name}] \${userId} left (\${this.clients.length} clients)\`);`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  async onDispose() {`);
+  if (usesDatabase) {
+    lines.push(`    if (this.snapshotTimer) { clearInterval(this.snapshotTimer); this.snapshotTimer = null; }`);
+    lines.push(`    try {`);
+    lines.push(`      await saveSnapshot("${channel.name}", this.roomId, this.serializeStateForSnapshot());`);
+    lines.push(`      console.log(\`[${channel.name}] saved final snapshot for room \${this.roomId}\`);`);
+    lines.push(`    } catch (e: any) {`);
+    lines.push(`      console.warn(\`[${channel.name}] snapshot save failed: \${e.message}\`);`);
+    lines.push(`    }`);
+  }
+  lines.push(`    console.log(\`[${channel.name}] room disposed\`);`);
+  lines.push(`  }`);
+  lines.push(``);
+  lines.push(`  private recordHistory(msg: { type: string; payload: unknown; from: string; ts: number }) {`);
+  lines.push(`    if (this.historyLimit <= 0) return;`);
+  lines.push(`    this.history.push(msg);`);
+  lines.push(`    while (this.history.length > this.historyLimit) this.history.shift();`);
+  lines.push(`  }`);
+
+  if (usesDatabase) {
+    lines.push(``);
+    lines.push(`  /**`);
+    lines.push(`   * Snapshot the channel-wide state. We exclude the players map because`);
+    lines.push(`   * sessions don't persist across processes; players reconnect with new`);
+    lines.push(`   * sessionIds when the room is restored.`);
+    lines.push(`   */`);
+    lines.push(`  private serializeStateForSnapshot(): Record<string, unknown> {`);
+    lines.push(`    const out: Record<string, unknown> = {};`);
+    lines.push(`    for (const [k, v] of Object.entries(this.state as unknown as Record<string, unknown>)) {`);
+    lines.push(`      if (k === "players") continue;`);
+    lines.push(`      if (typeof v === "string" || typeof v === "number" || typeof v === "boolean") {`);
+    lines.push(`        out[k] = v;`);
+    lines.push(`      }`);
+    lines.push(`    }`);
+    lines.push(`    return out;`);
+    lines.push(`  }`);
+  }
+
+  lines.push(`}`);
+  lines.push(``);
+
+  return {
+    path: `src/rooms/${stateModule}.ts`,
+    content: lines.join("\n"),
+    language: "typescript",
+    source_module: channel.id,
+  };
+}
+
+const SNAPSHOT_INTERVAL_MS = 5000;
+
+/**
+ * Emit a capability handler.
+ *
+ * Translates IR effects to TypeScript that mutates the calling client's
+ * player record (or the room state) and broadcasts the result. Effects
+ * targeting `<participantParam>.<field>` map to the player; everything
+ * else maps to room state.
+ *
+ * Only `assign` op is fully supported in Phase 2. `add` / `remove` on
+ * scalars work for numbers; `add` on collections falls back to broadcasting
+ * a hint without mutating state (left as TODO with a comment).
+ */
+function emitCapabilityHandler(method: IR.IRMethod, participantEntity: string | undefined, channelName: string): string {
+  const lines: string[] = [];
+  const handlerName = `handle${toPascalCase(method.name)}`;
+  const payloadType = `${toPascalCase(method.name)}Payload`;
+
+  // Find the participant param name (used to discriminate state vs player effects).
+  const partParam = method.input.find(i => i.type === participantEntity);
+  const partParamName = partParam?.name ?? null;
+
+  lines.push(`  /**`);
+  lines.push(`   * Handle "${method.name}" capability message.`);
+  if (method.preconditions.length > 0) {
+    lines.push(`   *`);
+    lines.push(`   * Preconditions:`);
+    for (const pre of method.preconditions) lines.push(`   *   - ${pre.expression}`);
+  }
+  if (method.effects.length > 0) {
+    lines.push(`   *`);
+    lines.push(`   * Effects:`);
+    for (const eff of method.effects) {
+      const opSym = eff.op === "assign" ? "=" : eff.op === "add" ? "+=" : "-=";
+      lines.push(`   *   - ${eff.target} ${opSym} ${eff.value}`);
+    }
+  }
+  lines.push(`   */`);
+  lines.push(`  private ${handlerName}(client: Client, payload: ${payloadType}): void {`);
+  lines.push(`    const player = this.state.players.get(client.sessionId);`);
+  lines.push(`    if (!player) return;`);
+
+  // Compile preconditions to runtime checks. Best-effort: we only check
+  // simple expressions referring to the participant or payload params.
+  if (method.preconditions.length > 0) {
+    lines.push(`    // Preconditions`);
+    for (const pre of method.preconditions) {
+      const expr = compileExprForRoom(pre.expression, partParamName, method.input);
+      if (expr) {
+        lines.push(`    if (!(${expr})) {`);
+        lines.push(`      client.send("${method.name}_failed", { reason: "precondition: ${escapeStringLiteral(pre.description)}" });`);
+        lines.push(`      return;`);
+        lines.push(`    }`);
+      }
+    }
+  }
+
+  // Compile effects
+  for (const eff of method.effects) {
+    const compiled = compileEffectForRoom(eff, partParamName, method.input);
+    if (compiled) {
+      lines.push(`    ${compiled}`);
+    } else {
+      lines.push(`    // TODO: effect "${eff.target} ${eff.op} ${eff.value}" — not auto-translated`);
+    }
+  }
+
+  // Broadcast the resulting change to all clients (including sender so they
+  // see authoritative state). Colyseus's @type system already syncs state
+  // diffs, so this broadcast is just for clients listening to the explicit
+  // "<capability>_applied" event for animation cues etc.
+  lines.push(`    this.broadcast("${method.name}_applied", { from: player.userId, payload });`);
+  lines.push(`  }`);
+
+  void channelName;
+  return lines.join("\n");
+}
+
+/**
+ * Compile an effect expression to a TS statement that mutates state or player.
+ *
+ * Supported targets:
+ *   <partParam>.<field>           → player.<field>  (calling client's player)
+ *   <field>                        → this.state.<field>  (room-wide state)
+ *   <some-other-entity>.<field>    → not auto-translated; returns null
+ *
+ * Supported values:
+ *   identifier matching a payload param name → payload.<name>
+ *   number / string / bool literal           → as-is
+ *   simple binary expr referencing scalars   → translated by compileExprForRoom
+ */
+function compileEffectForRoom(
+  eff: IR.IREffect,
+  partParamName: string | null,
+  inputs: IR.IRField[],
+): string | null {
+  const path = eff.target.split(".");
+  let lhs: string;
+  if (path.length === 2 && partParamName && path[0] === partParamName) {
+    lhs = `player.${path[1]}`;
+  } else if (path.length === 1) {
+    lhs = `(this.state as any).${path[0]}`;
+  } else {
+    return null; // can't safely translate cross-entity effects
+  }
+
+  const rhs = compileExprForRoom(eff.value, partParamName, inputs) ?? `(payload as any).${eff.value}`;
+
+  switch (eff.op) {
+    case "assign": return `${lhs} = ${rhs};`;
+    case "add":    return `${lhs} = (${lhs} as number) + (${rhs} as number);`;
+    case "remove": return `${lhs} = (${lhs} as number) - (${rhs} as number);`;
+  }
+}
+
+/**
+ * Compile an IR expression string to a TS expression usable inside a room
+ * handler. Best-effort — we recognise:
+ *   - the participant param name → `player`
+ *   - any payload input name → `payload.<name>`
+ *   - bare identifiers we can't resolve → null (caller falls back)
+ *   - simple binary expressions like "x > 0", "qty <= player.capacity"
+ *
+ * For complex expressions involving function calls, returns the original
+ * expression unchanged. If that fails to compile, the user gets a tsc
+ * error pointing at the generated code; better than silent wrong behaviour.
+ */
+function compileExprForRoom(
+  expr: string,
+  partParamName: string | null,
+  inputs: IR.IRField[],
+): string | null {
+  const trimmed = expr.trim();
+  // Number literal
+  if (/^-?\d+(\.\d+)?$/.test(trimmed)) return trimmed;
+  // String literal
+  if (/^"[^"]*"$/.test(trimmed)) return trimmed;
+  // Boolean
+  if (trimmed === "true" || trimmed === "false") return trimmed;
+
+  // Replace identifiers with their compiled form.
+  // We do a simple word-boundary substitution which is safe for the
+  // expressions we generate (no shadowing, no string contents to worry about).
+  const inputNames = new Set(inputs.map(i => i.name));
+  const partOk = partParamName && partParamName.length > 0;
+  let out = trimmed;
+
+  // <partParam>.<field> → player.<field>
+  if (partOk) {
+    const re = new RegExp(`\\b${partParamName}\\.(\\w+)`, "g");
+    out = out.replace(re, "player.$1");
+  }
+  // <payloadParam>.<x> or <payloadParam> → payload.<...>
+  for (const inp of inputs) {
+    if (partOk && inp.name === partParamName) continue;
+    const re = new RegExp(`\\b${inp.name}\\b`, "g");
+    out = out.replace(re, `(payload as any).${inp.name}`);
+  }
+
+  // If after substitution we still have bare identifiers we don't recognise,
+  // we leave them in — tsc will flag them at compile time so the user can
+  // fix the .bone source.
+  void inputNames;
+  return out;
+}
+
+function escapeStringLiteral(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+
+// ─── Auth helper (JWT verification) ───────────────────────────────────────────
+
+function emitColyseusAuth(): string {
+  return [
+    `// Generated by BoneScript compiler. DO NOT EDIT.`,
+    `// JWT verification helper. Mirrors the Express target's auth.ts: HS256-only,`,
+    `// 1h max-age cap, sub must be a non-empty string.`,
+    ``,
+    `import jwt from "jsonwebtoken";`,
+    ``,
+    `const JWT_SECRET = (() => {`,
+    `  const secret = process.env.JWT_SECRET;`,
+    `  if (!secret) {`,
+    `    if (process.env.NODE_ENV === "production") {`,
+    `      console.error("[FATAL] JWT_SECRET is not set. Refusing to start in production.");`,
+    `      process.exit(1);`,
+    `    }`,
+    `    console.warn("[WARN] JWT_SECRET is not set. Using insecure default — do not use in production.");`,
+    `    return "bonescript-dev-secret-do-not-use-in-production";`,
+    `  }`,
+    `  if (secret.length < 32) {`,
+    `    console.warn("[WARN] JWT_SECRET is shorter than 32 characters.");`,
+    `  }`,
+    `  return secret;`,
+    `})();`,
+    ``,
+    `export interface JwtClaims {`,
+    `  sub: string;`,
+    `}`,
+    ``,
+    `export function verifyToken(token: string): JwtClaims | null {`,
+    `  try {`,
+    `    const decoded = jwt.verify(token, JWT_SECRET, {`,
+    `      algorithms: ["HS256"],`,
+    `      maxAge: process.env.JWT_MAX_AGE || "1h",`,
+    `    }) as { sub?: unknown };`,
+    `    if (typeof decoded.sub !== "string" || decoded.sub.length === 0) return null;`,
+    `    return { sub: decoded.sub };`,
+    `  } catch {`,
+    `    return null;`,
+    `  }`,
+    `}`,
+    ``,
+  ].join("\n");
+}
+
+function emitColyseusPersistence(): string {
+  // Filesystem-based snapshot store. Default location: ./snapshots/<channel>/<roomId>.json.
+  // Override SNAPSHOT_DIR env var. To swap in a real DB (Postgres, Redis,
+  // etc.), replace the body of loadSnapshot/saveSnapshot — the interface
+  // is intentionally minimal.
+  return [
+    `// Generated by BoneScript compiler. DO NOT EDIT.`,
+    `// Snapshot persistence for rooms with \`persistence: database\`.`,
+    `//`,
+    `// Default implementation: JSON files under SNAPSHOT_DIR (./snapshots).`,
+    `// Replace with your DB / Redis / object store as needed — the only`,
+    `// contract is loadSnapshot/saveSnapshot returning Promise<unknown | null>.`,
+    ``,
+    `import * as fs from "fs/promises";`,
+    `import * as path from "path";`,
+    ``,
+    `const ROOT = path.resolve(process.env.SNAPSHOT_DIR || "./snapshots");`,
+    ``,
+    `function snapshotPath(channel: string, roomId: string): string {`,
+    `  // Filenames are limited to a safe character set so a malicious roomId`,
+    `  // can't escape the snapshot dir. Colyseus roomIds are alphanumeric so`,
+    `  // this is belt-and-braces.`,
+    `  const safeChannel = channel.replace(/[^a-zA-Z0-9_-]/g, "_");`,
+    `  const safeRoom = roomId.replace(/[^a-zA-Z0-9_-]/g, "_");`,
+    `  return path.join(ROOT, safeChannel, safeRoom + ".json");`,
+    `}`,
+    ``,
+    `export async function loadSnapshot(channel: string, roomId: string): Promise<unknown | null> {`,
+    `  const file = snapshotPath(channel, roomId);`,
+    `  try {`,
+    `    const data = await fs.readFile(file, "utf-8");`,
+    `    return JSON.parse(data);`,
+    `  } catch (e: any) {`,
+    `    if (e.code === "ENOENT") return null;`,
+    `    throw e;`,
+    `  }`,
+    `}`,
+    ``,
+    `export async function saveSnapshot(channel: string, roomId: string, state: unknown): Promise<void> {`,
+    `  const file = snapshotPath(channel, roomId);`,
+    `  await fs.mkdir(path.dirname(file), { recursive: true });`,
+    `  // Write to a temp file then rename — atomic on POSIX, near-atomic on Windows.`,
+    `  const tmp = file + ".tmp";`,
+    `  await fs.writeFile(tmp, JSON.stringify(state, null, 2), "utf-8");`,
+    `  await fs.rename(tmp, file);`,
+    `}`,
+    ``,
+    `export async function deleteSnapshot(channel: string, roomId: string): Promise<void> {`,
+    `  const file = snapshotPath(channel, roomId);`,
+    `  try { await fs.unlink(file); } catch { /* swallow */ }`,
+    `}`,
+    ``,
+  ].join("\n");
+}
+
+// ─── Server entry point ───────────────────────────────────────────────────────
+
+function emitColyseusIndex(system: IR.IRSystem): string {
+  const channels = system.modules.filter(m => m.kind === "realtime_service");
+  const lines: string[] = [];
+
+  lines.push(`// Generated by BoneScript compiler. DO NOT EDIT.`);
+  lines.push(`// Colyseus server entry point.`);
+  lines.push(``);
+  lines.push(`require("dotenv").config();`);
+  lines.push(`import { Server } from "colyseus";`);
+  lines.push(`import { WebSocketTransport } from "@colyseus/ws-transport";`);
+  lines.push(`import { createServer } from "http";`);
+  for (const ch of channels) {
+    const stateModule = toSnakeCase(ch.name);
+    const roomName = `${toPascalCase(ch.name)}Room`;
+    lines.push(`import { ${roomName} } from "./rooms/${stateModule}";`);
+  }
+  lines.push(``);
+  lines.push(`const PORT = parseInt(process.env.PORT || "2567", 10);`);
+  lines.push(``);
+  lines.push(`const httpServer = createServer();`);
+  lines.push(`const gameServer = new Server({`);
+  lines.push(`  transport: new WebSocketTransport({ server: httpServer }),`);
+  lines.push(`});`);
+  lines.push(``);
+
+  for (const ch of channels) {
+    const roomName = `${toPascalCase(ch.name)}Room`;
+    lines.push(`gameServer.define("${ch.name}", ${roomName});`);
+  }
+
+  lines.push(``);
+  lines.push(`gameServer.listen(PORT).then(() => {`);
+  lines.push(`  console.log(\`[${system.name}] Colyseus listening on ws://localhost:\${PORT}\`);`);
+  for (const ch of channels) {
+    lines.push(`  console.log(\`  - room: ${ch.name}\`);`);
+  }
+  lines.push(`});`);
+  lines.push(``);
+  lines.push(`process.on("SIGTERM", () => { gameServer.gracefullyShutdown().then(() => process.exit(0)); });`);
+  lines.push(`process.on("SIGINT", () => { gameServer.gracefullyShutdown().then(() => process.exit(0)); });`);
+  lines.push(``);
+
+  return lines.join("\n");
+}
+
+// ─── Package config ──────────────────────────────────────────────────────────
+
+function emitColyseusPackageJson(system: IR.IRSystem): string {
+  return JSON.stringify({
+    name: toSnakeCase(system.name),
+    version: system.version,
+    private: true,
+    scripts: {
+      build: "tsc",
+      start: "node dist/index.js",
+      dev: "ts-node src/index.ts",
+    },
+    dependencies: {
+      // Pinned to known-working 0.17.x minor versions. These are the line
+      // Colyseus moved to in 2026; @colyseus/schema is now 4.x. Bump together.
+      colyseus: "^0.17.10",
+      "@colyseus/schema": "^4.0.25",
+      "@colyseus/ws-transport": "^0.17.13",
+      jsonwebtoken: "9.0.2",
+      dotenv: "16.4.7",
+    },
+    devDependencies: {
+      "@types/node": "20.14.0",
+      "@types/jsonwebtoken": "9.0.7",
+      typescript: "5.6.3",
+      "ts-node": "10.9.2",
+      // Tests / clients use the new SDK package name.
+      "@colyseus/sdk": "^0.17.42",
+    },
+  }, null, 2);
+}
+
+function emitColyseusTsConfig(): string {
+  // Colyseus schemas use class decorators; experimentalDecorators is required
+  // for @type to register at runtime.
+  return JSON.stringify({
+    compilerOptions: {
+      target: "ES2020",
+      module: "commonjs",
+      lib: ["ES2020"],
+      outDir: "./dist",
+      rootDir: "./src",
+      strict: true,
+      esModuleInterop: true,
+      skipLibCheck: true,
+      experimentalDecorators: true,
+      emitDecoratorMetadata: true,
+      forceConsistentCasingInFileNames: true,
+      declaration: true,
+      sourceMap: true,
+    },
+    include: ["src/**/*"],
+    exclude: ["node_modules", "dist"],
+  }, null, 2);
+}
+
+function emitColyseusReadme(system: IR.IRSystem): string {
+  const channels = system.modules.filter(m => m.kind === "realtime_service");
+  const channelDocs = channels.length === 0
+    ? "_No channels declared._"
+    : channels.map(c => `- \`${c.name}\` (max ${c.config["max_size"] ?? 16} clients, ${c.config["persistence"] ?? "none"})`).join("\n");
+
+  return `# ${system.name} (Colyseus target)
+
+Generated by BoneScript compiler. Source hash: ${system.source_hash}
+
+## Quick Start
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+
+The server listens on \`ws://localhost:2567\` by default. Set \`PORT\` to change.
+Set \`JWT_SECRET\` to your token-signing secret; \`onAuth\` enforces HS256 + 1h max-age.
+
+## Rooms
+
+${channelDocs}
+
+## Client example
+
+\`\`\`typescript
+import { Client } from "@colyseus/sdk";
+
+const client = new Client("ws://localhost:2567");
+client.auth.token = "<jwt>"; // signed with JWT_SECRET, alg HS256, sub = user id
+const room = await client.joinOrCreate("${channels[0]?.name ?? "lobby"}");
+
+room.state.players.onAdd((player, key) => {
+  console.log("player joined:", player.userId);
+});
+
+room.send("chat", { text: "hello" });
+\`\`\`
+
+## What this target generates
+
+- One \`Room\` subclass per channel (\`src/rooms/\`)
+- One \`Schema\` state class per channel (\`src/state/\`)
+- JWT auth helper (\`src/auth.ts\`) — same algorithm pinning as the Express target
+- A Colyseus \`Server\` bootstrap (\`src/index.ts\`) that registers all rooms
+
+## What this target does NOT generate
+
+- HTTP REST routes — use the default Express target alongside this
+- Persistence to a database — the room state lives in memory; bridge to your
+  own DB or compile the Express target separately for CRUD
+- Lobby matchmaking beyond \`joinOrCreate\` — see the
+  [Colyseus matchmaking guide](https://docs.colyseus.io/matchmaker)
+  for advanced patterns
+`;
+}
+
+// ─── Top-level emitter ────────────────────────────────────────────────────────
+
+export class ColyseusEmitter {
+  emit(system: IR.IRSystem): EmittedFile[] {
+    const files: EmittedFile[] = [];
+    const channels = system.modules.filter(m => m.kind === "realtime_service");
+
+    files.push({ path: "package.json", content: emitColyseusPackageJson(system), language: "json", source_module: "root" });
+    files.push({ path: "tsconfig.json", content: emitColyseusTsConfig(), language: "json", source_module: "root" });
+    files.push({ path: "README.md", content: emitColyseusReadme(system), language: "yaml", source_module: "root" });
+    files.push({ path: ".env.example", content: this.emitEnvExample(), language: "yaml", source_module: "root" });
+    files.push({ path: "src/auth.ts", content: emitColyseusAuth(), language: "typescript", source_module: "infra" });
+    files.push({ path: "src/index.ts", content: emitColyseusIndex(system), language: "typescript", source_module: "root" });
+
+    // Emit the persistence bridge only when at least one channel needs it.
+    const needsPersistence = channels.some(c => c.config["persistence"] === "database");
+    if (needsPersistence) {
+      files.push({
+        path: "src/persistence.ts",
+        content: emitColyseusPersistence(),
+        language: "typescript",
+        source_module: "infra",
+      });
+    }
+
+    for (const ch of channels) {
+      files.push(emitStateSchema(ch, system));
+      files.push(emitRoom(ch, system));
+    }
+
+    return files;
+  }
+
+  private emitEnvExample(): string {
+    return `# JWT verification secret. Required in production.
+# Generate with: node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"
+JWT_SECRET=
+
+# Colyseus server port (default 2567).
+PORT=2567
+
+NODE_ENV=development
+`;
+  }
+}