@smoothglue/sync-whiteboard 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BrainGu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+## Overview
+
+A simple standalone NodeJS-based sync server designed to provide a realtime, collaborative whiteboard experience for frontends integrated with tlDraw. It functions as a microservice, handling websocket connections to sync shared whiteboard edits in real-time using tlDraw's `sync-core` library.
+
+The core responsibilities of this service include:
+
+- Managing WebSocket connections for real-time synchronization of whiteboard edits.
+- Facilitating data persistence (snapshots) via a backend API.
+- Handling storage of assets (like images or videos) via a backend API.
+
+## Features
+
+- **Real-time Collaboration:** Leverages WebSockets and `@tldraw/sync-core` for multi-user interaction on a shared whiteboard via Fastify and `@fastify/websocket`.
+- **Snapshot Persistence:** Delegates saving and loading whiteboard state snapshots to a configurable backend service. The development environment includes a mock backend for this.
+- **Asset Handling:** Delegates uploading and retrieving large binary assets to a configurable backend service. The development environment includes a mock backend for this.
+
+## Architecture
+
+This service is designed as a NodeJS microservice using Fastify . It connects to client applications using tlDraw via WebSockets for real-time data synchronization. It relies on external services (configurable via environment variables) for persisting snapshots and storing assets.
+
+## Development Environment (Docker)
+
+This project includes a Docker-based development environment configured in `dev-env/docker-compose.yml`. This makes it easy to run the `sync-whiteboard` server along with its dependencies (mock backend API, database, object storage) and a mock frontend client.
+
+**Prerequisites:**
+
+- Docker ([https://www.docker.com/get-started](https://www.docker.com/get-started))
+- Docker Compose ([https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/))
+
+**Configuration:**
+
+1.  Navigate to the `dev-env` directory:
+    ```bash
+    cd sync-whiteboard/dev-env
+    ```
+2.  Create a `.env` file by copying the example or using your own settings. This file is used by `docker-compose.yml` to configure services like the database and object storage. Key variables include:
+    - `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD` for the database.
+    - `MINIO_ROOT_USER`, `MINIO_ROOT_PASSWORD`, `MINIO_BUCKET` for the object storage.
+    - The `SNAPSHOT_STORAGE_URL` and `ASSET_STORAGE_URL` environment variables for the `sync-whiteboard` service itself are set within the `docker-compose.yml` to point to the `mock-backend` service.
+
+**Running the Environment:**
+
+1.  From the `dev-env` directory, run:
+    ```bash
+    docker-compose up --build
+    ```
+
+**Services:**
+
+The Docker Compose setup starts the following services:
+
+- **`sync-whiteboard`**: The main NodeJS sync server.
+  - Accessible via WebSocket at `ws://localhost:5858`. Builds from the `Dockerfile` in the parent directory.
+- **`mock-backend`**: A Flask-based API simulating backend storage for snapshots (using PostgreSQL) and assets (using MinIO).
+  - Accessible at `http://localhost:5000`.
+- **`postgres`**: PostgreSQL database for the mock backend.
+  - Data is persisted in a Docker volume (`postgres_data`).
+  - Port `5433` on the host is mapped to `5432` in the container.
+- **`minio`**: MinIO object storage for the mock backend.
+  - Data is persisted in a Docker volume (`minio_data`).
+  - API accessible at `http://localhost:9000`.
+  - Console accessible at `http://localhost:9001`.
+- **`mock-frontend`**: A simple Vite+React frontend client for testing.
+  - Accessible at `http://localhost:8080`.

package/dist/assets.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.storeAsset = storeAsset;
+exports.loadAsset = loadAsset;
+const stream_1 = require("stream");
+// --- Configuration ---
+const ASSET_STORAGE_URL = process.env.ASSET_STORAGE_URL;
+if (!ASSET_STORAGE_URL) {
+    // Critical configuration missing, exit the process.
+    console.error("FATAL ERROR: ASSET_STORAGE_URL environment variable is not set.");
+    process.exit(1);
+}
+console.log(`[ASSETS] Using Asset Storage URL: ${ASSET_STORAGE_URL}`);
+// --- End Configuration ---
+/**
+ * Stores an asset by proxying a PUT request to the configured asset storage backend.
+ * @param id - The unique identifier for the asset (generated by the client).
+ * @param fileStream - The readable stream containing the asset data (from the client request).
+ * @param contentType - The MIME type of the asset.
+ * @param originalFilename - The original filename provided by the client.
+ * @returns The asset ID upon successful storage.
+ * @throws Throws an error if the request to the backend fails.
+ */
+async function storeAsset(id, fileStream, contentType = "application/octet-stream", originalFilename) {
+    const url = `${ASSET_STORAGE_URL}/${id}`;
+    console.log(`[ASSETS] Storing asset id: ${id}, filename: ${originalFilename}. Target URL: ${url}`);
+    // Ensure we have a readable stream
+    if (!(fileStream instanceof stream_1.Readable)) {
+        console.error("[ASSETS] Error: storeAsset received a non-readable stream type.");
+        throw new Error("Invalid stream type provided to storeAsset.");
+    }
+    let webStream = null;
+    try {
+        // Convert Node.js stream to Web Standard stream for fetch body
+        webStream = stream_1.Readable.toWeb(fileStream);
+        // Make the PUT request to the actual asset storage backend (mock-backend in this case)
+        const response = await fetch(url, {
+            method: "PUT",
+            headers: {
+                "Content-Type": contentType,
+                // Pass original filename for backend to determine correct mimetype on GET
+                "X-Original-Filename": encodeURIComponent(originalFilename),
+            },
+            body: webStream, // Cast is necessary due to type mismatches
+            // @ts-ignore - duplex: 'half' is required for streaming request bodies with Node fetch
+            duplex: "half",
+        });
+        console.log(`[ASSETS] Backend PUT response status for ${id}: ${response.status}`);
+        // Handle backend errors
+        if (!response.ok) {
+            const errorBody = await response.text();
+            console.error(`[ASSETS] Error response from backend storing asset ${id}: ${response.status} ${response.statusText}`, errorBody);
+            // Ensure streams are closed on error
+            if (webStream) {
+                await webStream
+                    .cancel()
+                    .catch((err) => console.error(`[ASSETS] Error cancelling upload webStream for ${id} after failed fetch:`, err));
+            }
+            throw new Error(`Backend failed to store asset ${id}. Status: ${response.status}. Body: ${errorBody}`);
+        }
+        console.log(`[ASSETS] Successfully proxied storage for asset ${id} to ${url}`);
+        return id; // Return the ID, confirming success
+    }
+    catch (error) {
+        console.error(`[ASSETS] Network or fetch error storing asset ${id} to ${url}:`, error);
+        // Clean up streams on error
+        if (fileStream instanceof stream_1.Readable && !fileStream.destroyed) {
+            fileStream.destroy(error instanceof Error ? error : new Error(String(error)));
+        }
+        if (webStream) {
+            await webStream
+                .cancel()
+                .catch((err) => console.error(`[ASSETS] Error cancelling upload webStream during error handling for ${id}:`, err));
+        }
+        throw error; // Re-throw error for the server handler
+    }
+}
+/**
+ * Loads an asset by proxying a GET request to the configured asset storage backend.
+ * @param id - The unique identifier for the asset.
+ * @returns An object containing the asset's data as a Readable stream and its Content-Type.
+ * @throws Throws an error if the request to the backend fails or the asset is not found.
+ */
+async function loadAsset(id) {
+    const url = `${ASSET_STORAGE_URL}/${id}`;
+    console.log(`[ASSETS] Loading asset id: ${id}. Target URL: ${url}`);
+    try {
+        // Make the GET request to the actual asset storage backend
+        const response = await fetch(url, {
+            method: "GET",
+        });
+        console.log(`[ASSETS] Backend GET response status for ${id}: ${response.status}`);
+        // Handle backend errors (like 404 Not Found)
+        if (!response.ok) {
+            if (response.status === 404) {
+                console.warn(`[ASSETS] Asset ${id} not found at backend ${url} (404)`);
+                const notFoundError = new Error(`Asset ${id} not found.`);
+                notFoundError.code = "ENOENT"; // Mimic filesystem error code
+                throw notFoundError;
+            }
+            // Handle other non-OK statuses
+            const errorBody = await response.text();
+            console.error(`[ASSETS] Error response from backend loading asset ${id}: ${response.status} ${response.statusText}`, errorBody);
+            throw new Error(`Backend failed to load asset ${id}. Status: ${response.status}. Body: ${errorBody}`);
+        }
+        // Ensure response body exists
+        if (!response.body) {
+            console.error(`[ASSETS] No response body received from backend for asset ${id} from ${url}`);
+            throw new Error(`No response body received for asset ${id}.`);
+        }
+        // Get the Content-Type header provided by the backend
+        const contentType = response.headers.get("Content-Type") || "application/octet-stream";
+        console.log(`[ASSETS] Received Content-Type from backend for ${id}: ${contentType}`);
+        // Convert the Web Standard stream from fetch response to a Node.js stream
+        const nodeStream = stream_1.Readable.fromWeb(response.body);
+        // Return the stream and content type for the server handler to use
+        return { stream: nodeStream, contentType: contentType };
+    }
+    catch (error) {
+        // Avoid double-logging known 'Not Found' errors
+        if (error.code !== "ENOENT") {
+            console.error(`[ASSETS] Network or fetch error loading asset ${id} from ${url}:`, error);
+        }
+        throw error; // Re-throw error for the server handler
+    }
+}

package/dist/rooms.js

@@ -0,0 +1,195 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getOrCreateRoom = getOrCreateRoom;
+const sync_core_1 = require("@tldraw/sync-core");
+const schema_1 = require("./schema");
+// --- Configuration ---
+const SNAPSHOT_STORAGE_URL = process.env.SNAPSHOT_STORAGE_URL;
+if (!SNAPSHOT_STORAGE_URL) {
+    console.error("FATAL ERROR: SNAPSHOT_STORAGE_URL environment variable is not set.");
+    process.exit(1);
+}
+console.log(`[ROOMS] Using Snapshot Storage URL: ${SNAPSHOT_STORAGE_URL}`);
+const SAVE_INTERVAL_MS = process.env.SAVE_INTERVAL_MS
+    ? parseInt(process.env.SAVE_INTERVAL_MS, 10)
+    : 5000;
+console.log(`[ROOMS] Snapshot save interval: ${SAVE_INTERVAL_MS}ms`);
+// In-memory map holding active room states, keyed by roomId
+const rooms = new Map();
+// Mutex to prevent race conditions when multiple requests try to create the same room simultaneously
+let createRoomMutex = Promise.resolve(undefined);
+// --- End Room State Tracking ---
+/**
+ * Reads the latest snapshot for a room from the backend API via HTTP GET.
+ * @param roomId - The ID of the room.
+ * @returns The snapshot data, or undefined if the backend returns 404.
+ * @throws Throws an error for non-404 HTTP errors or network issues.
+ */
+async function readSnapshotFromBackend(roomId) {
+    const url = `${SNAPSHOT_STORAGE_URL}/${roomId}`;
+    console.log(`[ROOMS] Loading snapshot for room ${roomId} from ${url}`);
+    try {
+        const response = await fetch(url, {
+            method: "GET",
+            headers: {
+                Accept: "application/json" /* TODO: Add auth headers if needed */,
+            },
+        });
+        if (response.ok) {
+            const snapshot = await response.json();
+            console.log(`[ROOMS] Snapshot loaded successfully for room ${roomId}`);
+            return snapshot;
+        }
+        else if (response.status === 404) {
+            console.log(`[ROOMS] No existing snapshot found for room ${roomId} (404)`);
+            return undefined; // Expected case for a new room
+        }
+        else {
+            // Handle unexpected errors from the backend
+            const errorBody = await response.text();
+            console.error(`[ROOMS] Error loading snapshot for room ${roomId}: ${response.status} ${response.statusText}`, errorBody);
+            throw new Error(`Backend failed to load snapshot for ${roomId}. Status: ${response.status}. Body: ${errorBody}`);
+        }
+    }
+    catch (error) {
+        console.error(`[ROOMS] Network or fetch error loading snapshot for room ${roomId} from ${url}:`, error);
+        throw error; // Propagate error to getOrCreateRoom
+    }
+}
+/**
+ * Saves the current room snapshot to the backend API via HTTP POST.
+ * @param roomId - The ID of the room.
+ * @param room - The TLSocketRoom instance containing the state to save.
+ */
+async function saveSnapshotToBackend(roomId, room) {
+    const url = `${SNAPSHOT_STORAGE_URL}/${roomId}`;
+    const snapshot = room.getCurrentSnapshot();
+    console.log(`[ROOMS] Saving snapshot for room ${roomId} to ${url}`);
+    try {
+        const response = await fetch(url, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json" /* TODO: Add auth headers if needed */,
+            },
+            body: JSON.stringify(snapshot),
+        });
+        if (!response.ok) {
+            const errorBody = await response.text();
+            console.error(`[ROOMS] Error saving snapshot for room ${roomId}: ${response.status} ${response.statusText}`, errorBody);
+            // Log error but don't throw, to avoid breaking the save interval
+        }
+        else {
+            console.log(`[ROOMS] Snapshot saved successfully for room ${roomId}`);
+        }
+    }
+    catch (error) {
+        console.error(`[ROOMS] Network or fetch error saving snapshot for room ${roomId} to ${url}:`, error);
+        // Log error but don't throw
+    }
+}
+/**
+ * Retrieves an existing active room instance from memory or creates a new one.
+ * If creating, it loads the initial state from the backend.
+ * Uses a mutex to handle concurrent requests safely.
+ * @param roomId - The ID of the room to get or create.
+ * @returns A promise resolving to the TLSocketRoom instance.
+ * @throws Throws an error if backend interaction fails during creation.
+ */
+async function getOrCreateRoom(roomId) {
+    // Chain onto the mutex promise to ensure sequential access to the `rooms` map
+    createRoomMutex = createRoomMutex.then(async () => {
+        // Check if an active room instance already exists
+        if (rooms.has(roomId)) {
+            const existingRoomState = rooms.get(roomId);
+            if (!existingRoomState.room.isClosed()) {
+                return; // Room exists and is active
+            }
+            else {
+                console.log(`[ROOMS] Found closed room ${roomId}, removing before creating new one.`);
+                rooms.delete(roomId); // Clean up closed room reference
+            }
+        }
+        console.log(`[ROOMS] Creating or recreating room: ${roomId}`);
+        // Fetch initial state from the backend API (can throw error)
+        const initialSnapshot = await readSnapshotFromBackend(roomId);
+        // Define logger for the tldraw room instance
+        const logger = {
+            warn: (...args) => console.warn(`[TLDRAW ROOM ${roomId} WARN]`, ...args),
+            error: (...args) => console.error(`[TLDRAW ROOM ${roomId} ERROR]`, ...args),
+        };
+        // Create the new room state object
+        const newRoomState = {
+            id: roomId,
+            needsPersist: false,
+            persistPromise: null,
+            room: new sync_core_1.TLSocketRoom({
+                schema: schema_1.whiteboardSchema, // Our defined tldraw schema
+                initialSnapshot, // Initial state from backend (or undefined)
+                log: logger, // Logger for internal tldraw messages
+                /** Callback when a user session is removed (e.g., disconnects/times out) */
+                onSessionRemoved(room, args) {
+                    console.log(`[ROOMS] Session removed from room ${roomId}. Remaining: ${args.numSessionsRemaining}`);
+                    // If last user leaves, trigger a final save and close the room
+                    if (args.numSessionsRemaining === 0) {
+                        console.log(`[ROOMS] Last user left room ${roomId}. Triggering final save.`);
+                        // Ensure any pending periodic save completes first
+                        const savePromise = newRoomState.persistPromise ?? Promise.resolve();
+                        savePromise.finally(() => {
+                            console.log(`[ROOMS] Performing final save for room ${roomId}...`);
+                            saveSnapshotToBackend(roomId, room).finally(() => {
+                                console.log(`[ROOMS] Closing room ${roomId} after final save.`);
+                                room.close(); // Mark the tldraw room as closed
+                            });
+                        });
+                    }
+                },
+                /** Callback when data within the room changes */
+                onDataChange() {
+                    // Flag that the room needs to be saved on the next interval
+                    newRoomState.needsPersist = true;
+                },
+            }),
+        };
+        // Store the new room state in our map
+        rooms.set(roomId, newRoomState);
+        console.log(`[ROOMS] Room ${roomId} created successfully.`);
+    });
+    // Wait for the mutex-protected operation (lookup/creation) to complete
+    await createRoomMutex;
+    // Retrieve the room state (should always exist after the mutex)
+    const roomState = rooms.get(roomId);
+    if (!roomState || roomState.room.isClosed()) {
+        // Defensive check in case something went wrong
+        console.error(`[ROOMS] Failed to get or create a valid room instance for ${roomId} after mutex.`);
+        throw new Error(`Failed to retrieve valid room instance for ${roomId}`);
+    }
+    // Return the tldraw room object
+    return roomState.room;
+}
+// --- Periodic Persistence ---
+// Saves snapshots for rooms marked as `needsPersist` at regular intervals.
+setInterval(() => {
+    for (const roomState of rooms.values()) {
+        // Clean up closed rooms from memory
+        if (roomState.room.isClosed()) {
+            console.log(`[ROOMS] Removing closed room ${roomState.id} during periodic check.`);
+            rooms.delete(roomState.id);
+            continue;
+        }
+        // If room has changes and isn't already saving, start a save operation
+        if (roomState.needsPersist && !roomState.persistPromise) {
+            roomState.needsPersist = false; // Reset flag
+            // Track the save operation promise
+            roomState.persistPromise = saveSnapshotToBackend(roomState.id, roomState.room)
+                .catch((error) => {
+                // Log errors from periodic save but don't stop the interval
+                console.error(`[ROOMS] Periodic save failed for room ${roomState.id}:`, error);
+            })
+                .finally(() => {
+                // Clear the promise tracker when done
+                roomState.persistPromise = null;
+            });
+        }
+    }
+}, SAVE_INTERVAL_MS);
+// --- End Periodic Persistence ---

package/dist/schema.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.whiteboardSchema = void 0;
+const tlschema_1 = require("@tldraw/tlschema");
+exports.whiteboardSchema = (0, tlschema_1.createTLSchema)({
+    shapes: {
+        ...tlschema_1.defaultShapeSchemas,
+        //TODO: add custom shapes here
+    },
+    bindings: tlschema_1.defaultBindingSchemas,
+});

package/dist/server.js

@@ -0,0 +1,147 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fastify_1 = __importDefault(require("fastify"));
+const websocket_1 = __importDefault(require("@fastify/websocket"));
+const cors_1 = __importDefault(require("@fastify/cors"));
+const rooms_1 = require("./rooms");
+const assets_1 = require("./assets");
+const stream_1 = require("stream");
+// Configuration
+const PORT = parseInt(process.env.PORT || "5858", 10);
+const HOST = process.env.HOST || "0.0.0.0"; // Listen on all interfaces by default
+// Initialize Fastify app with logging
+const app = (0, fastify_1.default)({ logger: { level: "info" } }); // Use 'info' level for less verbosity
+// --- Register Plugins ---
+app.register(websocket_1.default); // Enable WebSocket support
+app.register(cors_1.default, {
+    // Configure CORS
+    origin: "*", // Allow all origins (restrict in production)
+    methods: ["GET", "PUT", "POST", "DELETE", "OPTIONS"], // Allowed HTTP methods
+    allowedHeaders: ["Content-Type", "Authorization", "X-Original-Filename"], // Allowed headers
+});
+// --- Define Routes ---
+app.register(async (app) => {
+    // Health check endpoint
+    app.get("/", async () => ({
+        status: "sync-whiteboard is running",
+        time: new Date().toISOString(),
+    }));
+    // WebSocket connection endpoint for tldraw sync
+    app.get("/connect/:roomId", { websocket: true }, async (socket, req) => {
+        const { roomId } = req.params;
+        const sessionId = req.query?.sessionId;
+        // Client provides sessionId via query param, handled by TLSocketRoom
+        try {
+            // Get or create the room instance (loads/creates state)
+            const room = await (0, rooms_1.getOrCreateRoom)(roomId);
+            app.log.info(`[SERVER] Handling WebSocket connection for room ${roomId}`);
+            // Connect the client's socket to the tldraw room handler
+            room.handleSocketConnect({ sessionId, socket });
+        }
+        catch (error) {
+            app.log.error(`[SERVER] Error initializing room ${roomId}:`, error);
+            // Close socket with error code if room initialization fails
+            socket.close(1011, "Internal server error during room initialization");
+        }
+    });
+    // --- Asset Handling ---
+    // Allow raw body parsing for asset uploads
+    app.addContentTypeParser("*", (_, __, done) => done(null));
+    /**
+     * Handles asset uploads (PUT /assets/:id).
+     * Proxies the request body stream to the asset storage backend via storeAsset.
+     */
+    app.put("/assets/:id", async (req, reply) => {
+        const { id } = req.params;
+        const contentType = req.headers["content-type"] || "application/octet-stream";
+        // Extract original filename from custom header
+        const originalFilenameHeaderRaw = req.headers["x-original-filename"];
+        const originalFilenameHeader = Array.isArray(originalFilenameHeaderRaw)
+            ? originalFilenameHeaderRaw[0]
+            : originalFilenameHeaderRaw;
+        let originalFilename = "unknown_asset";
+        if (typeof originalFilenameHeader === "string" &&
+            originalFilenameHeader.length > 0) {
+            try {
+                originalFilename = decodeURIComponent(originalFilenameHeader);
+            }
+            catch (e) {
+                app.log.warn(`[SERVER] Failed to decode X-Original-Filename header: ${originalFilenameHeader}`);
+                originalFilename = "decode_error";
+            }
+        }
+        else {
+            app.log.warn(`[SERVER] X-Original-Filename header missing or invalid: ${originalFilenameHeaderRaw}`);
+        }
+        app.log.info(`[SERVER] PUT /assets/${id}, Content-Type: ${contentType}, Filename: ${originalFilename}`);
+        // Validate request body is a stream
+        if (!(req.raw instanceof stream_1.Readable)) {
+            app.log.error(`[SERVER] Error: Request raw body is not a Readable stream for asset ${id}`);
+            return reply.code(500).send({
+                success: false,
+                error: "Internal server error: Invalid request body stream.",
+            });
+        }
+        try {
+            // Call the asset storage logic (which proxies to the backend)
+            await (0, assets_1.storeAsset)(id, req.raw, contentType, originalFilename);
+            app.log.info(`[SERVER] Asset ${id} stored successfully.`);
+            reply.code(200).send({ success: true });
+        }
+        catch (error) {
+            app.log.error(`[SERVER] Error storing asset ${id}:`, error);
+            const statusCode = error?.code === "ENOENT" ? 404 : 500; // Check for specific errors if needed
+            reply.code(statusCode).send({
+                success: false,
+                error: error.message || "Failed to store asset",
+            });
+        }
+    });
+    /**
+     * Handles asset retrieval (GET /assets/:id).
+     * Proxies the request to the asset storage backend via loadAsset and streams the response.
+     */
+    app.get("/assets/:id", async (req, reply) => {
+        const { id } = req.params;
+        app.log.info(`[SERVER] GET /assets/${id}`);
+        try {
+            // Call the asset loading logic (which proxies to the backend)
+            const { stream: dataStream, contentType } = await (0, assets_1.loadAsset)(id);
+            app.log.info(`[SERVER] Asset ${id} loaded. Content-Type: ${contentType}. Sending reply...`);
+            // Set the correct Content-Type header and send the stream
+            reply.header("Content-Type", contentType);
+            reply.send(dataStream);
+        }
+        catch (error) {
+            app.log.error(`[SERVER] Error loading asset ${id}:`, error);
+            if (error.code === "ENOENT") {
+                // Asset not found by the backend
+                reply.code(404).send({ success: false, error: "Asset not found" });
+            }
+            else {
+                // Other errors during load
+                reply.code(500).send({
+                    success: false,
+                    error: error.message || "Failed to load asset",
+                });
+            }
+        }
+    });
+    // --- End Asset Handling ---
+});
+// --- End Define Routes ---
+// --- Start Server ---
+const start = async () => {
+    try {
+        await app.listen({ port: PORT, host: HOST });
+        app.log.info(`Sync Whiteboard server running on http://${HOST}:${PORT}`);
+    }
+    catch (err) {
+        app.log.error(err);
+        process.exit(1); // Exit if server fails to start
+    }
+};
+start();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@smoothglue/sync-whiteboard",
+  "version": "0.1.0",
+  "main": "dist/server.js",
+  "scripts": {
+    "dev": "ts-node-dev --respawn --transpile-only src/server.ts",
+    "build": "tsc",
+    "start": "node dist/server.js"
+  },
+  "keywords": [],
+  "author": "Wade Tait",
+  "license": "MIT",
+  "description": "A minimal sync server for tlDraw based whiteboards",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "homepage": "https://gitlab.com/braingu/realtime-sync/-/blob/main/sync-whiteboard/README.md",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/braingu/realtime-sync/-/tree/main/sync-whiteboard"
+  },
+  "devDependencies": {
+    "@types/node": "^22.14.1",
+    "@types/ws": "^8.18.1",
+    "ts-node": "^10.9.2",
+    "ts-node-dev": "^2.0.0",
+    "typescript": "^5.8.3"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.0.1",
+    "@fastify/websocket": "^11.0.2",
+    "@tldraw/sync-core": "^3.12.0",
+    "@tldraw/tlschema": "^3.12.0",
+    "fastify": "^5.3.0",
+    "ws": "^8.18.1"
+  }
+}