Phase 1: chunk store, tile rendering pipeline, and Leaflet viewer

api: WS gateway with token auth (Postgres-backed servers table, seeded via
`bun run seed`), column-granularity chunk store (hand-written SQL
migrations, no drizzle-kit CLI — its config loader needs esbuild, which
doesn't install cleanly here), dirty-chunk Redis stream producer with
per-flush dedup, and a tile-serving route.

worker: consumes the dirty-chunk stream via a proper consumer group,
rasterizes each chunk's columns into a single-resolution top-down PNG
(static pre-Flattening block-id palette), uploads to MinIO, and upserts
the tile pointer.

frontend: barebones Leaflet 2D viewer (CRS.Simple, one native zoom level)
wired to /api/servers and /api/tiles.

Object storage: tiles live in a dedicated `mcmapper-tiles` bucket on the
existing shared MinIO instance (devstack-minio on octo-winsrv) instead of
a per-stack container, via a scoped access key limited to that one bucket
— see README's "Object storage" section. MINIO_SECRET_KEY is real and is
deliberately not committed; docker-compose layers an untracked .env over
.env.example for it.

Full pipeline verified end-to-end against live containers: WS auth ->
Postgres upsert -> deduped Redis dirty-chunk event -> worker rasterize ->
MinIO upload -> tile fetch through the api route, including from the
actual mod-side WS client (see MCMapper-Mod's matching commit).

api/src/ws-gateway.ts

@@ -0,0 +1,123 @@
+import { eq } from "drizzle-orm";
+import { db } from "./db/client";
+import { chunkColumns, servers } from "./db/schema";
+import { markChunkDirty } from "./redis";
+
+// Wire protocol (mod <-> api), one JSON object per WS text frame:
+//
+//   mod -> api  {"type":"hello","token":"<serverToken>"}
+//   api -> mod  {"type":"hello_ack","ok":true,"serverId":"<uuid>"}
+//               {"type":"hello_ack","ok":false,"error":"..."}  (connection closed after)
+//
+//   mod -> api  {"type":"columns","dimension":0,"columns":[{"x":..,"z":..,"height":..,"blockId":..,"blockMeta":..}]}
+//
+// `columns` doubles as both initial backfill (one message per loaded chunk, 256 columns) and
+// live deltas (one message per flush tick, just the columns that changed) — both are just "here
+// is the current topmost block + height for these XZ columns", the mod recomputes it from its
+// own world access rather than the api trying to infer a post-break top block from a raw diff.
+// Full per-voxel data (needed for Phase 2 3D meshing) is a natural extension of this same
+// connection once the chunk store grows a full block-data column.
+
+interface Column {
+  x: number;
+  z: number;
+  height: number;
+  blockId: number;
+  blockMeta: number;
+}
+
+interface ConnState {
+  serverId: string;
+}
+
+const connections = new Map<string | number, ConnState>();
+
+function chunkOf(coord: number): number {
+  return Math.floor(coord / 16);
+}
+
+export const wsGateway = {
+  async open() {
+    // Nothing to do until `hello` arrives — see message().
+  },
+
+  async message(ws: any, raw: unknown) {
+    let msg: any;
+    try {
+      msg = typeof raw === "string" ? JSON.parse(raw) : raw;
+    } catch {
+      ws.send(JSON.stringify({ type: "error", error: "invalid_json" }));
+      return;
+    }
+
+    const state = connections.get(ws.id);
+
+    if (msg.type === "hello") {
+      const [row] = await db.select().from(servers).where(eq(servers.token, msg.token)).limit(1);
+      if (!row) {
+        ws.send(JSON.stringify({ type: "hello_ack", ok: false, error: "invalid_token" }));
+        ws.close();
+        return;
+      }
+      connections.set(ws.id, { serverId: row.id });
+      ws.send(JSON.stringify({ type: "hello_ack", ok: true, serverId: row.id }));
+      console.log(`[ws] server '${row.name}' (${row.id}) authenticated`);
+      return;
+    }
+
+    if (!state) {
+      ws.send(JSON.stringify({ type: "error", error: "not_authenticated" }));
+      ws.close();
+      return;
+    }
+
+    if (msg.type === "columns") {
+      const dimension: number = msg.dimension;
+      const columns: Column[] = msg.columns ?? [];
+      if (columns.length === 0) return;
+
+      await db
+        .insert(chunkColumns)
+        .values(
+          columns.map((c) => ({
+            serverId: state.serverId,
+            dimension,
+            x: c.x,
+            z: c.z,
+            blockId: c.blockId,
+            blockMeta: c.blockMeta,
+            height: c.height,
+          })),
+        )
+        .onConflictDoUpdate({
+          target: [chunkColumns.serverId, chunkColumns.dimension, chunkColumns.x, chunkColumns.z],
+          set: {
+            blockId: sqlExcluded("block_id"),
+            blockMeta: sqlExcluded("block_meta"),
+            height: sqlExcluded("height"),
+            updatedAt: new Date(),
+          },
+        });
+
+      const dirtyChunks = new Set<string>();
+      for (const c of columns) dirtyChunks.add(`${chunkOf(c.x)},${chunkOf(c.z)}`);
+      for (const key of dirtyChunks) {
+        const [cx, cz] = key.split(",").map(Number);
+        await markChunkDirty(state.serverId, dimension, cx, cz);
+      }
+      return;
+    }
+  },
+
+  close(ws: any) {
+    connections.delete(ws.id);
+  },
+};
+
+// Small helper: drizzle's onConflictDoUpdate `set` needs a raw `excluded.<col>` reference for
+// "use the value that would have been inserted" — drizzle-orm doesn't expose a typed helper for
+// this on postgres-js yet, so build the sql fragment directly.
+import { sql } from "drizzle-orm";
+function sqlExcluded(column: string) {
+  return sql.raw(`excluded.${column}`);
+}