refactor(backend): modular server split with new routes, persistence and agent layer

- Introduce create-app factory to compose routes, middleware and Hocuspocus in isolation
- Extract route modules (auth, chat, publish) and move storage logic into persistence.ts
- Harden auth + HF storage integration (user token fallback, secure cookie in production)
- Add embed studio AI pipeline (embed-chat, embed-tools, system prompt) and shared stream handler
- Cover the new surface with api-routes, persistence and agent-chat test suites
- Ship .env.example and .gitignore so new contributors can boot without guesswork

Made-with: Cursor

backend/.env.example

@@ -0,0 +1,7 @@
+# OAuth - Create an app at https://huggingface.co/settings/connected-applications
+# Set redirect URI to: http://localhost:8080/auth/callback
+OAUTH_CLIENT_ID=
+OAUTH_CLIENT_SECRET=
+
+# AI model routing
+OPENROUTER_API_KEY=

backend/.gitignore

@@ -0,0 +1,2 @@
+.e2e-data-*
+test-results/

backend/src/agent/chat.ts

@@ -1,74 +1,27 @@
-import { streamText, convertToModelMessages } from "ai";
-import { createOpenRouter } from "@openrouter/ai-sdk-provider";
 import { editorTools } from "./tools.js";
 import { SYSTEM_PROMPT, buildMessages } from "./system-prompt.js";
+import { streamChatResponse } from "./stream-handler.js";
 import type { Request, Response } from "express";
 
-const DEFAULT_MODEL = "anthropic/claude-sonnet-4";
-
-function getProvider() {
-  const apiKey = process.env.OPENROUTER_API_KEY;
-  if (!apiKey) {
-    throw new Error("OPENROUTER_API_KEY environment variable is required");
-  }
-  return createOpenRouter({ apiKey });
-}
+export const AVAILABLE_MODELS = [
+  { id: "google/gemini-2.5-flash", label: "Gemini 2.5 Flash", context: "1M", cost: "$" },
+  { id: "google/gemini-2.5-pro", label: "Gemini 2.5 Pro", context: "1M", cost: "$$" },
+  { id: "anthropic/claude-sonnet-4", label: "Claude Sonnet 4", context: "200K", cost: "$$$" },
+  { id: "anthropic/claude-3.5-haiku", label: "Claude 3.5 Haiku", context: "200K", cost: "$" },
+  { id: "openai/gpt-4.1-mini", label: "GPT-4.1 Mini", context: "1M", cost: "$" },
+  { id: "openai/gpt-4.1", label: "GPT-4.1", context: "1M", cost: "$$" },
+];
 
 export async function handleChat(req: Request, res: Response) {
-  try {
-    const { messages, context, model } = req.body;
-
-    if (!messages || !Array.isArray(messages)) {
-      res.status(400).json({ error: "messages array is required" });
-      return;
-    }
-
-    const provider = getProvider();
-    const modelId = model || process.env.OPENROUTER_MODEL || DEFAULT_MODEL;
-
-    const contextBlock = buildMessages(context?.document, context?.selection, context?.frontmatter);
-    const systemMessages = contextBlock
-      ? `${SYSTEM_PROMPT}\n\n## Current context\n\n${contextBlock}`
-      : SYSTEM_PROMPT;
-
-    const modelMessages = await convertToModelMessages(messages);
-
-    const result = streamText({
-      model: provider.chat(modelId),
-      system: systemMessages,
-      messages: modelMessages,
-      tools: editorTools,
-    });
-
-    const webResponse = result.toUIMessageStreamResponse({
-      onError: (error) => {
-        console.error("[chat] stream error:", error);
-        return error instanceof Error ? error.message : "Stream error";
-      },
-    });
-
-    res.writeHead(
-      webResponse.status,
-      Object.fromEntries(webResponse.headers.entries()),
-    );
-    const reader = webResponse.body!.getReader();
-    const pump = async (): Promise<void> => {
-      const { done, value } = await reader.read();
-      if (done) {
-        res.end();
-        return;
-      }
-      res.write(value);
-      return pump();
-    };
-    await pump();
-  } catch (error: unknown) {
-    const message =
-      error instanceof Error ? error.message : "Internal server error";
-    console.error("[chat] error:", message);
-
-    if (!res.headersSent) {
-      res.status(500).json({ error: message });
-    }
-  }
+  const { context } = req.body;
+  const contextBlock = buildMessages(context?.document, context?.selection, context?.frontmatter);
+  const systemPrompt = contextBlock
+    ? `${SYSTEM_PROMPT}\n\n## Current context\n\n${contextBlock}`
+    : SYSTEM_PROMPT;
+
+  return streamChatResponse(req, res, {
+    systemPrompt,
+    tools: editorTools,
+    logPrefix: "chat",
+  });
 }

backend/src/agent/embed-chat.ts

@@ -0,0 +1,25 @@
+import {
+  EMBED_SYSTEM_PROMPT,
+  BANNER_SYSTEM_PROMPT,
+  buildEmbedContext,
+} from "./embed-system-prompt.js";
+import { embedTools } from "./embed-tools.js";
+import { streamChatResponse } from "./stream-handler.js";
+import type { Request, Response } from "express";
+
+export async function handleEmbedChat(req: Request, res: Response) {
+  const { context } = req.body;
+  const contextBlock = buildEmbedContext(context?.embedHtml);
+  const isBanner = Boolean(context?.isBanner);
+
+  const parts = [EMBED_SYSTEM_PROMPT];
+  if (isBanner) parts.push(BANNER_SYSTEM_PROMPT);
+  if (contextBlock) parts.push(`## Current chart\n\n${contextBlock}`);
+  const systemPrompt = parts.join("\n\n");
+
+  return streamChatResponse(req, res, {
+    systemPrompt,
+    tools: embedTools,
+    logPrefix: "embed-chat",
+  });
+}

backend/src/agent/embed-system-prompt.ts

@@ -0,0 +1,220 @@
+/**
+ * System prompt for the Embed Studio AI.
+ *
+ * Injected only when the Embed Studio panel is open, keeping the main
+ * article chat lightweight.
+ */
+
+export const EMBED_SYSTEM_PROMPT = `You are a D3.js data visualization expert embedded in a chart editor.
+You help users create, edit, and improve interactive data visualizations.
+
+## Tools
+
+- **createEmbed**: Create or fully replace the chart HTML. Use for new charts or extensive rewrites.
+- **patchEmbed**: Surgically edit a specific part of the chart. Preferred for small changes.
+  The search string must be an exact verbatim copy from the current HTML.
+  Call readEmbed first if you're unsure of the exact content.
+- **readEmbed**: Read the full current HTML. Call before patching.
+
+## Chart conventions
+
+Every chart is a self-contained HTML fragment with:
+1. A single root \`<div class="d3-<name>">\`
+2. A scoped \`<style>\` block (all rules under the root class)
+3. An IIFE \`<script>\` that mounts the chart
+
+### Structure template
+
+\`\`\`html
+<div class="d3-yourname"></div>
+<style>
+  .d3-yourname { /* scoped styles */ }
+</style>
+<script>
+(() => {
+  const ensureD3 = (cb) => {
+    if (window.d3 && typeof window.d3.select === 'function') return cb();
+    let s = document.getElementById('d3-cdn-script');
+    if (!s) { s = document.createElement('script'); s.id = 'd3-cdn-script'; s.src = 'https://cdn.jsdelivr.net/npm/d3@7/dist/d3.min.js'; document.head.appendChild(s); }
+    const onReady = () => { if (window.d3 && typeof window.d3.select === 'function') cb(); };
+    s.addEventListener('load', onReady, { once: true });
+    if (window.d3) onReady();
+  };
+
+  const bootstrap = () => {
+    const scriptEl = document.currentScript;
+    let container = scriptEl ? scriptEl.previousElementSibling : null;
+    if (!(container && container.classList.contains('d3-yourname'))) {
+      const cs = Array.from(document.querySelectorAll('.d3-yourname'))
+        .filter(el => el.dataset.mounted !== 'true');
+      container = cs[cs.length - 1] || null;
+    }
+    if (!container) return;
+    if (container.dataset.mounted === 'true') return;
+    container.dataset.mounted = 'true';
+
+    // Chart code here...
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', () => ensureD3(bootstrap), { once: true });
+  } else {
+    ensureD3(bootstrap);
+  }
+})();
+</script>
+\`\`\`
+
+### Colors & theming (MANDATORY)
+- Get colors from \`window.ColorPalettes\`:
+  - \`ColorPalettes.getColors('categorical', 8)\` - 8-color categorical palette
+  - \`ColorPalettes.getColors('sequential', 8)\` - sequential blues
+  - \`ColorPalettes.getColors('diverging', 9)\` - red-blue diverging
+  - \`ColorPalettes.getPrimary()\` - current primary accent color
+- Use CSS variables for theming: \`--primary-color\`, \`--text-color\`, \`--muted-color\`, \`--surface-bg\`, \`--border-color\`
+- Axis/tick/grid: \`--axis-color\`, \`--tick-color\`, \`--grid-color\`
+- NEVER hardcode color arrays
+
+### Layout rules
+- SVG for chart primitives (marks, axes, gridlines) only
+- Legends, controls, tooltips: HTML elements (not SVG)
+- Legend: visible title "Legend", swatch 14x14px, border-radius 3px
+- Controls: plain HTML selects/inputs, styled consistently
+- Tooltip: single \`.d3-tooltip\` absolutely positioned inside container
+
+### Background (MANDATORY)
+- The embed root \`<div>\` MUST be **transparent**: no \`background\`,
+  \`background-color\`, \`background-image\` or gradient, no opaque fill.
+- The embed sits on top of the article surface and inherits its colour
+  in both light and dark mode. Adding a background creates a visible
+  rectangle that breaks the flow of the page.
+- Do NOT set a background on \`body\`, \`html\` or wrapper containers.
+- The ONLY exception: the user explicitly asks for one (e.g. "add a
+  light grey background", "give it a card look", "highlight the chart
+  area"). Even then, prefer \`var(--surface-bg)\` /
+  \`var(--surface-elevated-bg)\` over hardcoded colours so it adapts to
+  the theme.
+
+### Responsiveness
+- Compute width from \`container.clientWidth\`
+- Height derived from width (e.g. \`width / 3\`), with minimum
+- Use \`ResizeObserver\` on the container
+- Recompute scales/axes on every render
+
+### Mounting
+- Gate with \`data-mounted\` to avoid double initialization
+- Select closest previous sibling with root class, fallback to last unmounted
+
+### Data
+- For inline data, embed it directly in the script
+- For CSV loading, implement \`fetchFirstAvailable(['/data/file.csv', './assets/data/file.csv'])\`
+- Handle errors gracefully with a red \`<pre>\` message
+
+## Guidelines
+
+1. **Act immediately.** When the user asks for a chart, create it right away with createEmbed.
+2. **Use patchEmbed for edits.** Read the current chart first, then apply surgical patches.
+3. **Follow conventions strictly.** Every chart must have: root div, scoped style, IIFE script, ColorPalettes, mount guard, responsive layout.
+4. **Be creative with design.** Make charts visually appealing with clean typography, proper spacing, and smooth transitions.
+5. **Keep it concise.** Don't explain what you're doing unless asked.
+
+## Context
+
+The current chart HTML (if any) is provided between <embed> tags.
+Use this to understand the existing chart structure before making edits.`;
+
+export function buildEmbedContext(embedHtml?: string): string {
+  if (!embedHtml) return "";
+  return `<embed>\n${embedHtml}\n</embed>`;
+}
+
+/**
+ * Extra instructions layered on top of the base system prompt when the
+ * chart being edited is the article banner (top-of-article hero).
+ *
+ * Banners are visual mood-setters with a fixed aspect-ratio container
+ * (5:2, max-width 980px). They should fill the container edge-to-edge,
+ * drop most UI chrome (legend, controls, tooltip) and lean abstract.
+ */
+export const BANNER_SYSTEM_PROMPT = `## Banner mode
+
+You are creating or editing the **article banner** (the hero visual at the
+top of the article). Banners have their own rules on top of the general
+chart conventions:
+
+### Host environment
+
+Banners are rendered inside an iframe configured in **fullBleed mode**:
+
+- \`html, body\` already have \`height: 100%; width: 100%;\`.
+- \`body\` has \`padding: 0\` (no inner margins). Your root \`<div>\` hits
+  the viewport edges directly.
+- \`body > :first-child\` is forced to \`width: 100%; height: 100%;\` by
+  the host so a properly-styled root fills the iframe automatically.
+- **No height-reporter runs**, so you MUST NOT rely on the parent
+  resizing the iframe based on body scrollHeight. The iframe size is
+  fixed by the outer layout.
+
+### Container
+
+- The outer container has a **fixed aspect ratio of 5:2** and a
+  **max-width of 980px** (natural height 980 * 2 / 5 = **392px**).
+  On narrow screens the aspect-ratio is relaxed, so ALWAYS read the
+  actual size from the container at runtime.
+- Your root element MUST set \`width: 100%; height: 100%; overflow: hidden;\`.
+- Compute BOTH \`width = container.clientWidth\` AND
+  \`height = container.clientHeight\`. Do NOT derive height from width
+  (that is only for regular embeds that can grow vertically).
+- The SVG (or canvas) must have \`width: 100%; height: 100%; display: block\`
+  and use a \`viewBox\` that matches the measured \`w x h\` so shapes
+  scale correctly on resize.
+
+### Style
+- Banners are **decorative**, not analytical. No legend, no metric select,
+  no tooltip unless the brief explicitly asks for them.
+- Prefer abstract / generative visuals: particle fields, flow fields,
+  animated noise, wave forms, constellations, isotype grids, topographic
+  lines, neural meshes. Data can be synthetic.
+- **Background**: the global "transparent embed" rule applies to banners
+  TOO. The root \`<div>\` MUST be transparent (no \`background\`,
+  \`background-color\` or gradient fill on the container or on
+  \`html\`/\`body\`). Banners inherit the article hero surface so they
+  blend with the page in light and dark mode. Carry visual weight through
+  shapes, lines, motion and colour - not through filled rectangles.
+- Use a **small margin** (e.g. 0 or 8px) so the visual bleeds to the edges.
+- Lean on \`--primary-color\`, \`--text-color\` and
+  \`window.ColorPalettes\` for palette coherence with the rest of the
+  article.
+- Subtle motion is welcome (gentle drift, slow rotation) but nothing
+  distracting or seizure-inducing. Respect \`prefers-reduced-motion\`.
+
+### Responsiveness
+- Observe the container with \`ResizeObserver\` and re-render. The banner
+  must look good at 980x392 AND at narrow mobile widths (~360x360).
+
+### Example scaffolding
+
+\`\`\`js
+const bootstrap = () => {
+  // ... standard mount guard + container selection ...
+  container.style.width = '100%';
+  container.style.height = '100%';
+  container.style.overflow = 'hidden';
+
+  const svg = d3.select(container).append('svg')
+    .attr('width', '100%')
+    .attr('height', '100%')
+    .style('display', 'block');
+
+  function render() {
+    const w = container.clientWidth || 980;
+    const h = container.clientHeight || 392;
+    svg.attr('viewBox', \`0 0 \${w} \${h}\`);
+    // draw full-bleed using w and h directly
+  }
+
+  render();
+  if (window.ResizeObserver) new ResizeObserver(render).observe(container);
+};
+\`\`\`
+`;

backend/src/agent/embed-tools.ts

@@ -0,0 +1,60 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+/**
+ * Tools for the Embed Studio AI. These return instructions that the
+ * frontend executes on the EmbedStore (Y.Map). The backend never
+ * touches the Yjs document directly.
+ */
+
+export const embedTools = {
+  createEmbed: tool({
+    description:
+      "Create or fully replace an HTML embed chart. Use when building a new chart from scratch " +
+      "or when changes are so extensive that a full rewrite is cleaner than patching. " +
+      "The HTML must be a self-contained fragment following D3 embed conventions " +
+      "(root div + scoped style + IIFE script).",
+    inputSchema: z.object({
+      html: z
+        .string()
+        .describe(
+          "Complete self-contained HTML fragment (root div + scoped style + IIFE script)",
+        ),
+      title: z
+        .string()
+        .optional()
+        .describe("Short descriptive title for the chart"),
+      source: z
+        .string()
+        .optional()
+        .describe("Data source attribution"),
+    }),
+  }),
+
+  patchEmbed: tool({
+    description:
+      "Replace a specific block of code in the current chart HTML. " +
+      "Use for targeted edits (color change, label update, data tweak, bug fix). " +
+      "Always prefer this over createEmbed when modifying an existing chart. " +
+      "The search string must be an exact verbatim excerpt from the current HTML " +
+      "(whitespace included). Call readEmbed first if unsure of the exact content.",
+    inputSchema: z.object({
+      search: z
+        .string()
+        .describe(
+          "Exact verbatim excerpt from the current chart HTML to find and replace. " +
+          "Must be long enough to be unique (at least 3-5 lines of context).",
+        ),
+      replace: z
+        .string()
+        .describe("The new code that replaces the search block"),
+    }),
+  }),
+
+  readEmbed: tool({
+    description:
+      "Read the full current chart HTML. Use before calling patchEmbed " +
+      "to verify the exact content, or to understand the current structure before editing.",
+    inputSchema: z.object({}),
+  }),
+};

backend/src/agent/stream-handler.ts

@@ -0,0 +1,76 @@
+import { streamText, convertToModelMessages } from "ai";
+import { createOpenRouter } from "@openrouter/ai-sdk-provider";
+import type { Request, Response } from "express";
+
+export const DEFAULT_MODEL = "google/gemini-2.5-flash";
+
+export function getProvider() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    throw new Error("OPENROUTER_API_KEY environment variable is required");
+  }
+  return createOpenRouter({ apiKey });
+}
+
+interface StreamChatOptions {
+  systemPrompt: string;
+  tools: Parameters<typeof streamText>[0]["tools"];
+  logPrefix: string;
+}
+
+export async function streamChatResponse(
+  req: Request,
+  res: Response,
+  { systemPrompt, tools, logPrefix }: StreamChatOptions,
+) {
+  try {
+    const { messages, context, model } = req.body;
+
+    if (!messages || !Array.isArray(messages)) {
+      res.status(400).json({ error: "messages array is required" });
+      return;
+    }
+
+    const provider = getProvider();
+    const modelId = model || process.env.OPENROUTER_MODEL || DEFAULT_MODEL;
+    const modelMessages = await convertToModelMessages(messages);
+
+    const result = streamText({
+      model: provider.chat(modelId),
+      system: systemPrompt,
+      messages: modelMessages,
+      tools,
+    });
+
+    const webResponse = result.toUIMessageStreamResponse({
+      onError: (error) => {
+        console.error(`[${logPrefix}] stream error:`, error);
+        return error instanceof Error ? error.message : "Stream error";
+      },
+    });
+
+    res.writeHead(
+      webResponse.status,
+      Object.fromEntries(webResponse.headers.entries()),
+    );
+    const reader = webResponse.body!.getReader();
+    const pump = async (): Promise<void> => {
+      const { done, value } = await reader.read();
+      if (done) {
+        res.end();
+        return;
+      }
+      res.write(value);
+      return pump();
+    };
+    await pump();
+  } catch (error: unknown) {
+    const message =
+      error instanceof Error ? error.message : "Internal server error";
+    console.error(`[${logPrefix}] error:`, message);
+
+    if (!res.headersSent) {
+      res.status(500).json({ error: message });
+    }
+  }
+}

backend/src/auth.ts

@@ -19,15 +19,24 @@ const OPENID_PROVIDER_URL = process.env.OPENID_PROVIDER_URL || "https://huggingf
 
 const COOKIE_NAME = "hf_access_token";
 
+const IS_DEV = !SPACE_ID;
+
 export function isOAuthEnabled(): boolean {
-  return Boolean(SPACE_ID && OAUTH_CLIENT_ID);
+  return Boolean(OAUTH_CLIENT_ID && OAUTH_CLIENT_SECRET);
 }
 
 function getRedirectUri(): string {
   if (SPACE_HOST) return `https://${SPACE_HOST}/auth/callback`;
+  // In dev, the callback goes through the Vite proxy (port 5678) -> backend
   return "http://localhost:8080/auth/callback";
 }
 
+function getPostLoginRedirect(): string {
+  if (SPACE_HOST) return "/editor";
+  // In dev, redirect to Vite dev server
+  return "http://localhost:5678/";
+}
+
 // In-memory state store for CSRF protection (short-lived)
 const pendingStates = new Map<string, number>();
 
@@ -95,13 +104,13 @@ export async function handleOAuthCallback(req: Request, res: Response) {
 
     res.cookie(COOKIE_NAME, tokenData.access_token, {
       httpOnly: true,
-      secure: true,
-      sameSite: "none",
+      secure: !IS_DEV,
+      sameSite: IS_DEV ? "lax" : "none",
       maxAge,
       path: "/",
     });
 
-    res.redirect("/editor");
+    res.redirect(getPostLoginRedirect());
   } catch (err) {
     console.error("[auth] callback error:", err);
     res.status(500).send("OAuth callback error");
@@ -136,8 +145,8 @@ export async function resolveUser(
     const fullName = info.fullname || name;
     const avatarUrl = info.avatarUrl || "";
 
-    const canEdit = await checkWriteAccess(accessToken, name);
-    console.log(`[auth] user=${name} canEdit=${canEdit}`);
+    const canEdit = IS_DEV ? true : await checkWriteAccess(accessToken, name);
+    console.log(`[auth] user=${name} canEdit=${canEdit}${IS_DEV ? " (dev mode)" : ""}`);
 
     return { name, fullName, avatarUrl, canEdit };
   } catch (err) {

backend/src/create-app.ts

@@ -0,0 +1,219 @@
+import express from "express";
+import { createServer } from "http";
+import { WebSocketServer } from "ws";
+import { Hocuspocus } from "@hocuspocus/server";
+import { Database } from "@hocuspocus/extension-database";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import * as Y from "yjs";
+import { extractToken, isOAuthEnabled } from "./auth.js";
+import { isHfStorageEnabled, setUserToken, pullDocument } from "./hf-storage.js";
+import { citationsRouter } from "./citations.js";
+import { getDataDir, docPath, sanitizeName } from "./utils.js";
+import { debouncedSave, ensurePublishedRestored } from "./persistence.js";
+import { createAuthRouter, createRequireEditor } from "./routes/auth.js";
+import { createChatRouter } from "./routes/chat.js";
+import { createPublishRouter } from "./routes/publish.js";
+import { createUploadRouter } from "./routes/upload.js";
+
+export { debouncedSave, resetSaveTimers, resetPublishedRestored } from "./persistence.js";
+
+const DEFAULT_DOC_NAME = "default";
+
+function sendLoginPage(res: express.Response) {
+  res.status(200).send(`<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Research Article Template Editor</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    body { display: flex; align-items: center; justify-content: center; height: 100vh;
+           font-family: system-ui, -apple-system, sans-serif; background: #0a0a0a; color: #aaa; }
+    .card { text-align: center; max-width: 420px; padding: 2rem; }
+    h1 { color: #fff; font-size: 1.5rem; margin-bottom: 0.5rem; }
+    p { margin-bottom: 1.5rem; line-height: 1.5; }
+    a.btn { display: inline-block; padding: 0.6rem 1.5rem; border-radius: 8px;
+            background: #958DF1; color: #fff; text-decoration: none; font-weight: 500;
+            transition: opacity 0.15s; }
+    a.btn:hover { opacity: 0.85; }
+  </style>
+</head>
+<body>
+  <div class="card">
+    <h1>This article is not yet published</h1>
+    <p>Log in with your Hugging Face account to access the editor.</p>
+    <a class="btn" href="/oauth/authorize" target="_blank">Sign in with Hugging Face</a>
+  </div>
+</body>
+</html>`);
+}
+
+export function createApp() {
+  const DATA_DIR = getDataDir();
+  mkdirSync(DATA_DIR, { recursive: true });
+
+  const oauthEnabled = isOAuthEnabled();
+
+  // ---------- Hocuspocus (Y.js collaboration server) ----------
+
+  const hocuspocus = new Hocuspocus({
+    async onAuthenticate({ token, context }: { token: string; context: any }) {
+      if (!oauthEnabled) return;
+
+      const { resolveUser } = await import("./auth.js");
+      const authToken = token || context?.token;
+      const user = await resolveUser(authToken);
+      if (!user || !user.canEdit) {
+        throw new Error("Unauthorized: no write access");
+      }
+      if (authToken) setUserToken(authToken);
+      return { user };
+    },
+    extensions: [
+      new Database({
+        fetch: async ({ documentName }: { documentName: string }) => {
+          try {
+            const p = docPath(documentName);
+            if (existsSync(p)) {
+              const buf = readFileSync(p);
+              console.log(`[persist] fetch "${documentName}" from disk: ${buf.length} bytes`);
+              return buf;
+            }
+            console.log(`[persist] fetch "${documentName}": no file on disk`);
+
+            if (isHfStorageEnabled()) {
+              const data = await pullDocument(documentName);
+              if (data) {
+                writeFileSync(p, data);
+                console.log(`[persist] pulled ${documentName} from HF`);
+                return Buffer.from(data);
+              }
+            }
+          } catch (err) {
+            console.error(`[persist] fetch "${documentName}" failed:`, (err as Error).message);
+          }
+          return null;
+        },
+        store: async () => {},
+      }),
+      {
+        async onChange({ documentName, document }: { documentName: string; document: any }) {
+          console.log(`[persist] onChange "${documentName}"`);
+          debouncedSave(documentName, document);
+        },
+        async afterLoadDocument({ documentName }: { documentName: string }) {
+          console.log(`[persist] loaded "${documentName}"`);
+        },
+      } as any,
+    ],
+  });
+
+  // ---------- Express app ----------
+
+  const app = express();
+  const httpServer = createServer(app);
+
+  app.use(express.json({ limit: "1mb" }));
+
+  const authCtx = { oauthEnabled };
+  const requireEditor = createRequireEditor(authCtx);
+
+  app.use(createAuthRouter(authCtx));
+  app.use(createChatRouter(requireEditor));
+  app.use("/api/citations", citationsRouter);
+  app.use(createPublishRouter({ oauthEnabled, hocuspocus }));
+  app.use(createUploadRouter());
+
+  // ---------- Collab WebSocket ----------
+
+  const wss = new WebSocketServer({ noServer: true });
+
+  httpServer.on("upgrade", (req, socket, head) => {
+    const url = req.url || "";
+    if (url === "/collab" || url.startsWith("/collab/") || url.startsWith("/collab?")) {
+      console.log(`[ws] upgrade request for ${url}`);
+      wss.handleUpgrade(req, socket, head, (ws) => {
+        ws.setMaxListeners(Infinity);
+        ws.on("error", (error) => {
+          console.error("[ws] socket error:", error.message);
+        });
+        if (process.env.NODE_ENV !== "production") {
+          ws.on("message", (data: Buffer, isBinary: boolean) => {
+            const buf = Buffer.isBuffer(data) ? data : Buffer.from(data as any);
+            console.log(`[ws-debug] msg ${buf.length}B binary=${isBinary} first20=${buf.slice(0, 20).toString("hex")}`);
+          });
+        }
+        const token = extractToken(req.headers.cookie);
+        hocuspocus.handleConnection(ws, req, { token });
+      });
+    } else {
+      console.log(`[ws] rejected upgrade for ${url}`);
+      socket.destroy();
+    }
+  });
+
+  // ---------- Static assets ----------
+
+  app.use("/uploads", express.static(join(DATA_DIR, "uploads")));
+  app.use("/published", express.static(join(DATA_DIR, "published")));
+
+  const staticDir =
+    process.env.NODE_ENV === "production"
+      ? join(DATA_DIR, "..", "frontend-dist")
+      : join(DATA_DIR, "..", "..", "frontend", "dist");
+
+  function getPublishedPath(docName: string): string {
+    return join(DATA_DIR, "published", docName, "index.html");
+  }
+
+  if (existsSync(staticDir)) {
+    app.use(express.static(staticDir, { index: false }));
+
+    app.get("/editor", async (req, res) => {
+      if (oauthEnabled) {
+        const { resolveUser } = await import("./auth.js");
+        const token = extractToken(req.headers.cookie);
+        const user = await resolveUser(token);
+
+        if (!user || !user.canEdit) {
+          res.status(200).send(`<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
+<title>Sign in required</title>
+<style>*{margin:0;padding:0;box-sizing:border-box}body{display:flex;align-items:center;justify-content:center;height:100vh;font-family:system-ui,-apple-system,sans-serif;background:#0a0a0a;color:#aaa}.card{text-align:center;max-width:420px;padding:2rem}h1{color:#fff;font-size:1.5rem;margin-bottom:.5rem}p{margin-bottom:1.5rem;line-height:1.5}a.btn{display:inline-block;padding:.6rem 1.5rem;border-radius:8px;background:#958DF1;color:#fff;text-decoration:none;font-weight:500;transition:opacity .15s}a.btn:hover{opacity:.85}</style></head>
+<body><div class="card">
+<h1>Editor access</h1>
+<p>Sign in with your Hugging Face account to start editing.</p>
+<a class="btn" href="/oauth/authorize" target="_blank">Sign in with Hugging Face</a>
+<p style="margin-top:1rem;font-size:.85rem;color:#666">After signing in, come back and <a href="/editor" style="color:#958DF1">refresh this page</a>.</p>
+</div></body></html>`);
+          return;
+        }
+      }
+
+      res.sendFile(join(staticDir, "index.html"));
+    });
+
+    app.get("*", async (req, res) => {
+      if (!oauthEnabled) {
+        res.sendFile(join(staticDir, "index.html"));
+        return;
+      }
+
+      const visitorToken = extractToken(req.headers.cookie) ?? undefined;
+      await ensurePublishedRestored(visitorToken);
+
+      const publishedPath = getPublishedPath(DEFAULT_DOC_NAME);
+      if (existsSync(publishedPath)) {
+        res.sendFile(publishedPath);
+        return;
+      }
+
+      sendLoginPage(res);
+    });
+  }
+
+  return { app, httpServer, hocuspocus, wss };
+}

backend/src/persistence.ts

@@ -0,0 +1,90 @@
+import { writeFileSync, existsSync } from "fs";
+import { join } from "path";
+import * as Y from "yjs";
+import { getDataDir, docPath, sanitizeName } from "./utils.js";
+import {
+  isHfStorageEnabled,
+  getDatasetId,
+  setUserToken,
+  pullPublishedAssets,
+  schedulePush,
+} from "./hf-storage.js";
+
+const DEFAULT_DOC_NAME = "default";
+const SAVE_DEBOUNCE_MS = 2000;
+const saveTimers = new Map<string, ReturnType<typeof setTimeout>>();
+const lastSaveTimestamp = new Map<string, number>();
+
+/** @internal - exported for testing */
+export function debouncedSave(documentName: string, ydoc: Y.Doc) {
+  const existing = saveTimers.get(documentName);
+  if (existing) clearTimeout(existing);
+
+  saveTimers.set(documentName, setTimeout(() => {
+    saveTimers.delete(documentName);
+    try {
+      const state = Y.encodeStateAsUpdate(ydoc);
+      const buf = Buffer.from(state);
+      writeFileSync(docPath(documentName), buf);
+      lastSaveTimestamp.set(documentName, Date.now());
+      console.log(`[persist] saved "${documentName}": ${buf.length} bytes`);
+
+      if (isHfStorageEnabled()) {
+        schedulePush(documentName, buf);
+      }
+    } catch (err) {
+      console.error(`[persist] failed to save "${documentName}":`, (err as Error).message);
+    }
+  }, SAVE_DEBOUNCE_MS));
+}
+
+/** Reset debounce state between tests */
+export function resetSaveTimers() {
+  for (const t of saveTimers.values()) clearTimeout(t);
+  saveTimers.clear();
+  lastSaveTimestamp.clear();
+}
+
+let _publishedRestored = false;
+let _restoreInProgress: Promise<void> | null = null;
+
+export async function ensurePublishedRestored(token?: string): Promise<void> {
+  const DATA_DIR = getDataDir();
+  if (_publishedRestored) return;
+  if (!getDatasetId()) return;
+
+  const publishedPath = join(DATA_DIR, "published", sanitizeName(DEFAULT_DOC_NAME), "index.html");
+  if (existsSync(publishedPath)) {
+    _publishedRestored = true;
+    return;
+  }
+
+  if (_restoreInProgress) {
+    await _restoreInProgress;
+    return;
+  }
+
+  if (token) setUserToken(token);
+
+  _restoreInProgress = (async () => {
+    try {
+      const found = await pullPublishedAssets(DEFAULT_DOC_NAME, DATA_DIR);
+      if (found) {
+        _publishedRestored = true;
+        console.log("[server] restored published article from HF dataset");
+      }
+    } catch (err) {
+      console.warn("[server] failed to restore published:", (err as Error).message);
+    } finally {
+      _restoreInProgress = null;
+    }
+  })();
+
+  await _restoreInProgress;
+}
+
+/** Reset restore state between tests */
+export function resetPublishedRestored() {
+  _publishedRestored = false;
+  _restoreInProgress = null;
+}

backend/src/routes/auth.ts

@@ -0,0 +1,67 @@
+import { Router } from "express";
+import type express from "express";
+import { resolveUser, extractToken, handleOAuthAuthorize, handleOAuthCallback } from "../auth.js";
+import { setUserToken } from "../hf-storage.js";
+import { ensurePublishedRestored } from "../persistence.js";
+
+export interface AuthContext {
+  oauthEnabled: boolean;
+}
+
+/**
+ * Middleware that requires editor-level access when OAuth is enabled.
+ * Reusable across route modules.
+ */
+export function createRequireEditor(ctx: AuthContext): express.RequestHandler {
+  return async (req, res, next) => {
+    if (!ctx.oauthEnabled) return next();
+    const token = extractToken(req.headers.cookie);
+    const user = await resolveUser(token);
+    if (!user || !user.canEdit) {
+      res.status(403).json({ error: "Unauthorized" });
+      return;
+    }
+    next();
+  };
+}
+
+export function createAuthRouter(ctx: AuthContext): Router {
+  const router = Router();
+
+  if (ctx.oauthEnabled) {
+    router.get("/oauth/authorize", handleOAuthAuthorize);
+    router.get("/auth/callback", handleOAuthCallback);
+  }
+
+  router.get("/api/auth/status", async (req, res) => {
+    if (!ctx.oauthEnabled) {
+      res.json({ authenticated: true, canEdit: true, user: null });
+      return;
+    }
+
+    const token = extractToken(req.headers.cookie);
+    const user = await resolveUser(token);
+
+    if (!user) {
+      res.json({ authenticated: false, canEdit: false, user: null, loginUrl: "/oauth/authorize" });
+      return;
+    }
+
+    if (user.canEdit && token) {
+      setUserToken(token);
+      ensurePublishedRestored(token).catch(() => {});
+    }
+
+    res.json({
+      authenticated: true,
+      canEdit: user.canEdit,
+      user: {
+        name: user.name,
+        fullName: user.fullName,
+        avatarUrl: user.avatarUrl,
+      },
+    });
+  });
+
+  return router;
+}

backend/src/routes/chat.ts

@@ -0,0 +1,14 @@
+import { Router } from "express";
+import type express from "express";
+import { handleChat, AVAILABLE_MODELS } from "../agent/chat.js";
+import { handleEmbedChat } from "../agent/embed-chat.js";
+
+export function createChatRouter(requireEditor: express.RequestHandler): Router {
+  const router = Router();
+
+  router.get("/api/models", (_req, res) => res.json(AVAILABLE_MODELS));
+  router.post("/api/chat", requireEditor, handleChat);
+  router.post("/api/embed-chat", requireEditor, handleEmbedChat);
+
+  return router;
+}

backend/src/routes/publish.ts

@@ -0,0 +1,339 @@
+import { Router } from "express";
+import { writeFileSync, existsSync } from "fs";
+import { randomUUID } from "crypto";
+import { EventEmitter } from "events";
+import * as Y from "yjs";
+import type { Hocuspocus } from "@hocuspocus/server";
+import { resolveUser, extractToken } from "../auth.js";
+import { isHfStorageEnabled, setUserToken } from "../hf-storage.js";
+import {
+  publishDocument,
+  previewDocument,
+  type PublishResult,
+  type PublishStage,
+} from "../publisher/index.js";
+import { docPath } from "../utils.js";
+
+const DEFAULT_DOC_NAME = "default";
+
+export interface PublishContext {
+  oauthEnabled: boolean;
+  hocuspocus: Hocuspocus;
+}
+
+/** Lock descriptor kept while a publish is running for a given docName. */
+interface PublishLock {
+  jobId: string;
+  startedAt: number;
+  userName?: string;
+}
+
+interface PublishJob {
+  emitter: EventEmitter;
+  /** Latest stage so a late SSE subscriber can immediately show the current label. */
+  stage?: { stage: string; detail?: Record<string, unknown> };
+  finished?: { ok: true; result: PublishResult } | { ok: false; error: string };
+}
+
+/** Per-docName mutex: a doc can only be published by one request at a time. */
+const publishLocks = new Map<string, PublishLock>();
+
+/** Active/finished jobs indexed by jobId so `/api/publish/stream` can attach. */
+const publishJobs = new Map<string, PublishJob>();
+
+/** How long we keep a finished job in memory so a late subscriber can still see the final event. */
+const JOB_RETENTION_MS = 30_000;
+
+/**
+ * Broadcast publish status into the Y.Doc via a dedicated Y.Map("publish-status").
+ * Every collaborative editor observes this map and disables its Publish button
+ * while a publish is active. Called at the start and end of a publish.
+ */
+async function broadcastPublishStatus(
+  hocuspocus: Hocuspocus,
+  docName: string,
+  status: { active: boolean; userName?: string; startedAt?: number; jobId?: string }
+): Promise<void> {
+  try {
+    const conn = await hocuspocus.openDirectConnection(docName);
+    if (conn.document) {
+      const statusMap = conn.document.getMap("publish-status");
+      conn.document.transact(() => {
+        statusMap.set("active", status.active);
+        statusMap.set("userName", status.userName ?? null);
+        statusMap.set("startedAt", status.startedAt ?? null);
+        statusMap.set("jobId", status.jobId ?? null);
+      });
+    }
+    await conn.disconnect();
+  } catch (err) {
+    console.warn("[publish] failed to broadcast publish status:", (err as Error).message);
+  }
+}
+
+export function createPublishRouter(ctx: PublishContext): Router {
+  const router = Router();
+
+  // ---------- Preview ----------
+
+  router.get("/api/preview/:docName", async (req, res) => {
+    const docName = req.params.docName || DEFAULT_DOC_NAME;
+
+    if (ctx.oauthEnabled) {
+      const token = extractToken(req.headers.cookie);
+      const user = await resolveUser(token);
+      if (!user || !user.canEdit) {
+        res.status(403).json({ error: "Unauthorized" });
+        return;
+      }
+    }
+
+    try {
+      const conn = await ctx.hocuspocus.openDirectConnection(docName);
+      if (conn.document) {
+        const update = Y.encodeStateAsUpdate(conn.document);
+        writeFileSync(docPath(docName), Buffer.from(update));
+      }
+      await conn.disconnect();
+
+      const result = await previewDocument(docName);
+      if ("error" in result) {
+        res.status(404).json({ error: result.error });
+        return;
+      }
+      res.setHeader("Content-Type", "text/html; charset=utf-8");
+      res.send(result.html);
+    } catch (err: any) {
+      console.error("[preview] error:", err);
+      res.status(500).json({ error: err.message || "Preview failed" });
+    }
+  });
+
+  // ---------- Publish ----------
+
+  router.post("/api/publish", async (req, res) => {
+    let userToken: string | undefined;
+    let userName: string | undefined;
+
+    if (ctx.oauthEnabled) {
+      const token = extractToken(req.headers.cookie);
+      const user = await resolveUser(token);
+      if (!user) {
+        console.warn("[publish] no valid user from token, cookie present:", !!token);
+        res.status(403).json({ error: "Unauthorized: please log in first" });
+        return;
+      }
+      if (!user.canEdit) {
+        console.warn("[publish] user lacks write access:", user.name);
+        res.status(403).json({ error: "Unauthorized: write access required" });
+        return;
+      }
+      userToken = token ?? undefined;
+      userName = user.name;
+      if (userToken) setUserToken(userToken);
+    }
+
+    const docName = DEFAULT_DOC_NAME;
+
+    // Mutex: reject with 409 if another publish is already in progress.
+    const existing = publishLocks.get(docName);
+    if (existing) {
+      res.status(409).json({
+        error: "Publish already in progress",
+        jobId: existing.jobId,
+        startedAt: existing.startedAt,
+        userName: existing.userName ?? null,
+      });
+      return;
+    }
+
+    const jobId = randomUUID();
+    const startedAt = Date.now();
+    const emitter = new EventEmitter();
+    emitter.setMaxListeners(32);
+    const job: PublishJob = { emitter };
+    publishJobs.set(jobId, job);
+    publishLocks.set(docName, { jobId, startedAt, userName });
+
+    // Broadcast "publishing" status to all collaborators immediately so their
+    // Publish buttons become disabled.
+    broadcastPublishStatus(ctx.hocuspocus, docName, {
+      active: true,
+      userName,
+      startedAt,
+      jobId,
+    }).catch(() => {});
+
+    // Return the jobId right away so the client can open the SSE stream.
+    res.json({ jobId });
+
+    // Run the publish pipeline asynchronously; SSE subscribers receive events.
+    try {
+      // Snapshot the Y.Doc state to disk (as before) so publishDocument can
+      // reload it from a stable .yjs file.
+      try {
+        const conn = await ctx.hocuspocus.openDirectConnection(docName);
+        if (conn.document) {
+          const update = Y.encodeStateAsUpdate(conn.document);
+          writeFileSync(docPath(docName), Buffer.from(update));
+        }
+        await conn.disconnect();
+      } catch (err) {
+        console.warn("[publish] snapshot failed:", (err as Error).message);
+      }
+
+      const emitStage = (stage: PublishStage | string, detail?: Record<string, unknown>) => {
+        const event = { stage, detail };
+        job.stage = event;
+        emitter.emit("stage", event);
+      };
+
+      const result = await publishDocument(docName, userToken, { onStage: emitStage });
+
+      if (!result.success) {
+        job.finished = { ok: false, error: result.error || "Publish failed" };
+        emitter.emit("done", { success: false, error: result.error || "Publish failed" });
+      } else {
+        job.finished = { ok: true, result };
+        emitter.emit("done", { success: true, result });
+      }
+    } catch (err: any) {
+      console.error("[publish] error:", err);
+      const message = err?.message || "Publish failed";
+      job.finished = { ok: false, error: message };
+      emitter.emit("done", { success: false, error: message });
+    } finally {
+      publishLocks.delete(docName);
+      broadcastPublishStatus(ctx.hocuspocus, docName, { active: false }).catch(() => {});
+
+      // Keep the finished job around briefly so late SSE subscribers still receive the outcome.
+      setTimeout(() => {
+        publishJobs.delete(jobId);
+      }, JOB_RETENTION_MS);
+    }
+  });
+
+  // ---------- SSE stream ----------
+
+  router.get("/api/publish/stream", async (req, res) => {
+    const jobId = typeof req.query.jobId === "string" ? req.query.jobId : "";
+    const job = publishJobs.get(jobId);
+
+    if (ctx.oauthEnabled) {
+      const token = extractToken(req.headers.cookie);
+      const user = await resolveUser(token);
+      if (!user || !user.canEdit) {
+        res.status(403).end();
+        return;
+      }
+    }
+
+    if (!job) {
+      res.status(404).end();
+      return;
+    }
+
+    res.setHeader("Content-Type", "text/event-stream");
+    res.setHeader("Cache-Control", "no-cache, no-transform");
+    res.setHeader("Connection", "keep-alive");
+    res.setHeader("X-Accel-Buffering", "no");
+    res.flushHeaders?.();
+
+    const write = (event: string, payload: unknown) => {
+      res.write(`event: ${event}\n`);
+      res.write(`data: ${JSON.stringify(payload)}\n\n`);
+    };
+
+    // Immediately replay the current stage (if any) so the subscriber sees the latest label.
+    if (job.stage) write("stage", job.stage);
+
+    const onStage = (payload: { stage: string; detail?: Record<string, unknown> }) => {
+      write("stage", payload);
+    };
+    const onDone = (payload: { success: boolean; error?: string; result?: PublishResult }) => {
+      write("done", payload);
+      cleanup();
+      res.end();
+    };
+
+    // If the job already finished (rare: client subscribed after completion),
+    // emit the final event and close.
+    if (job.finished) {
+      if (job.finished.ok) {
+        write("done", { success: true, result: job.finished.result });
+      } else {
+        write("done", { success: false, error: job.finished.error });
+      }
+      res.end();
+      return;
+    }
+
+    job.emitter.on("stage", onStage);
+    job.emitter.on("done", onDone);
+
+    // Keep-alive comments every 15s to defeat proxy idle timeouts.
+    const keepAlive = setInterval(() => {
+      res.write(`: keepalive ${Date.now()}\n\n`);
+    }, 15_000);
+
+    const cleanup = () => {
+      clearInterval(keepAlive);
+      job.emitter.off("stage", onStage);
+      job.emitter.off("done", onDone);
+    };
+
+    req.on("close", () => {
+      cleanup();
+      res.end();
+    });
+  });
+
+  // ---------- Status (used by non-collaborative fallback) ----------
+
+  router.get("/api/publish/status", (_req, res) => {
+    const lock = publishLocks.get(DEFAULT_DOC_NAME);
+    if (!lock) {
+      res.json({ active: false });
+      return;
+    }
+    res.json({
+      active: true,
+      jobId: lock.jobId,
+      startedAt: lock.startedAt,
+      userName: lock.userName ?? null,
+    });
+  });
+
+  // ---------- Reset Document ----------
+
+  router.post("/api/admin/reset-document", async (req, res) => {
+    if (ctx.oauthEnabled) {
+      const token = extractToken(req.headers.cookie);
+      const user = await resolveUser(token);
+      if (!user || !user.canEdit) {
+        res.status(403).json({ error: "Unauthorized" });
+        return;
+      }
+      if (token) setUserToken(token);
+    }
+
+    try {
+      const p = docPath(DEFAULT_DOC_NAME);
+      if (existsSync(p)) {
+        const { unlinkSync } = await import("fs");
+        unlinkSync(p);
+        console.log("[admin] deleted local Y.Doc file:", p);
+      }
+
+      await ctx.hocuspocus.closeConnections(DEFAULT_DOC_NAME);
+      console.log("[admin] closed connections for", DEFAULT_DOC_NAME);
+
+      res.json({ success: true, message: "Document reset. Refresh the editor to start fresh." });
+    } catch (err: any) {
+      console.error("[admin] reset error:", err);
+      res.status(500).json({ error: err.message || "Reset failed" });
+    }
+  });
+
+  return router;
+}

backend/src/server.ts

@@ -1,81 +1,10 @@
 import "dotenv/config";
-import express from "express";
-import { createServer } from "http";
-import { WebSocketServer } from "ws";
-import { Hocuspocus } from "@hocuspocus/server";
-import { Database } from "@hocuspocus/extension-database";
-import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
-import { join } from "path";
-import { randomUUID } from "crypto";
-import multer from "multer";
-import * as Y from "yjs";
-import { handleChat } from "./agent/chat.js";
-import { citationsRouter } from "./citations.js";
-import {
-  isHfStorageEnabled,
-  ensureDatasetExists,
-  getDatasetId,
-  setUserToken,
-  uploadImageToHf,
-  pullDocument,
-  pullPublishedAssets,
-  schedulePush,
-  flushAll,
-} from "./hf-storage.js";
-import { resolveUser, extractToken, isOAuthEnabled, handleOAuthAuthorize, handleOAuthCallback } from "./auth.js";
-import { publishDocument, previewDocument } from "./publisher/index.js";
-import { DATA_DIR, docPath, sanitizeName } from "./utils.js";
+import { isHfStorageEnabled, getDatasetId, flushAll } from "./hf-storage.js";
+import { isOAuthEnabled } from "./auth.js";
+import { createApp } from "./create-app.js";
 
 const PORT = parseInt(process.env.PORT || "8080", 10);
 
-/** Single collab document; URL `?doc=` is not supported. */
-const DEFAULT_DOC_NAME = "default";
-
-/**
- * Lazy restore of published assets from HF dataset.
- * Called at startup and on every request until successful.
- * Dataset is public so no token is required for reads.
- */
-let _publishedRestored = false;
-let _restoreInProgress: Promise<void> | null = null;
-
-async function ensurePublishedRestored(token?: string): Promise<void> {
-  if (_publishedRestored) return;
-  if (!getDatasetId()) return;
-
-  const publishedPath = join(DATA_DIR, "published", sanitizeName(DEFAULT_DOC_NAME), "index.html");
-  if (existsSync(publishedPath)) {
-    _publishedRestored = true;
-    return;
-  }
-
-  // Prevent concurrent pulls (multiple requests arriving at the same time)
-  if (_restoreInProgress) {
-    await _restoreInProgress;
-    return;
-  }
-
-  if (token) setUserToken(token);
-
-  _restoreInProgress = (async () => {
-    try {
-      const found = await pullPublishedAssets(DEFAULT_DOC_NAME, DATA_DIR);
-      if (found) {
-        _publishedRestored = true;
-        console.log("[server] restored published article from HF dataset");
-      }
-    } catch (err) {
-      console.warn("[server] failed to restore published:", (err as Error).message);
-    } finally {
-      _restoreInProgress = null;
-    }
-  })();
-
-  await _restoreInProgress;
-}
-
-mkdirSync(DATA_DIR, { recursive: true });
-
 if (isHfStorageEnabled()) {
   console.log("[server] HF Dataset persistence enabled");
 } else if (getDatasetId()) {
@@ -92,405 +21,12 @@ if (oauthEnabled) {
   console.log("[server] HF OAuth disabled (no SPACE_ID), all users can edit");
 }
 
-const hocuspocus = new Hocuspocus({
-  async onAuthenticate({ token, context }: { token: string; context: any }) {
-    if (!oauthEnabled) return;
-
-    // Prefer WebSocket protocol token, fall back to cookie token passed via context
-    const authToken = token || context?.token;
-    const user = await resolveUser(authToken);
-    if (!user || !user.canEdit) {
-      throw new Error("Unauthorized: no write access");
-    }
-    if (authToken) setUserToken(authToken);
-    return { user };
-  },
-  extensions: [
-    new Database({
-      fetch: async ({ documentName }: { documentName: string }) => {
-        const p = docPath(documentName);
-        if (existsSync(p)) return readFileSync(p);
-
-        if (isHfStorageEnabled()) {
-          const data = await pullDocument(documentName);
-          if (data) {
-            writeFileSync(p, data);
-            console.log(`[server] pulled ${documentName} from HF`);
-            return Buffer.from(data);
-          }
-        }
-
-        return null;
-      },
-      store: async ({
-        documentName,
-        state,
-      }: {
-        documentName: string;
-        state: Buffer;
-      }) => {
-        writeFileSync(docPath(documentName), state);
-
-        if (isHfStorageEnabled()) {
-          schedulePush(documentName, state);
-        }
-      },
-    }),
-  ],
-});
-
-const app = express();
-const httpServer = createServer(app);
-
-app.use(express.json({ limit: "1mb" }));
-
-// ---------- OAuth routes ----------
-
-if (oauthEnabled) {
-  app.get("/oauth/authorize", handleOAuthAuthorize);
-  app.get("/auth/callback", handleOAuthCallback);
-}
-
-// ---------- Auth ----------
-
-app.get("/api/auth/status", async (req, res) => {
-  if (!oauthEnabled) {
-    res.json({ authenticated: true, canEdit: true, user: null });
-    return;
-  }
-
-  const token = extractToken(req.headers.cookie);
-  const user = await resolveUser(token);
-
-  if (!user) {
-    res.json({ authenticated: false, canEdit: false, user: null });
-    return;
-  }
-
-  // Cache the user's OAuth token for HF API calls (dataset storage)
-  if (user.canEdit && token) {
-    setUserToken(token);
-    // Lazy-restore published article on first authenticated request
-    ensurePublishedRestored(token).catch(() => {});
-  }
-
-  res.json({
-    authenticated: true,
-    canEdit: user.canEdit,
-    user: {
-      name: user.name,
-      fullName: user.fullName,
-      avatarUrl: user.avatarUrl,
-    },
-  });
-});
-
-// ---------- Collab WebSocket (native ws upgrade, no express-ws) ----------
-
-const wss = new WebSocketServer({ noServer: true });
-
-httpServer.on("upgrade", (req, socket, head) => {
-  const url = req.url || "";
-  // Hocuspocus v3 provider connects to /collab (no document name in path)
-  if (url === "/collab" || url.startsWith("/collab/") || url.startsWith("/collab?")) {
-    console.log(`[ws] upgrade request for ${url}`);
-    wss.handleUpgrade(req, socket, head, (ws) => {
-      ws.setMaxListeners(Infinity);
-      ws.on("error", (error) => {
-        console.error("[ws] socket error:", error.message);
-      });
-      if (process.env.NODE_ENV !== "production") {
-        ws.on("message", (data: Buffer, isBinary: boolean) => {
-          const buf = Buffer.isBuffer(data) ? data : Buffer.from(data as any);
-          console.log(`[ws-debug] msg ${buf.length}B binary=${isBinary} first20=${buf.slice(0, 20).toString("hex")}`);
-        });
-      }
-      const token = extractToken(req.headers.cookie);
-      hocuspocus.handleConnection(ws, req, { token });
-    });
-  } else {
-    console.log(`[ws] rejected upgrade for ${url}`);
-    socket.destroy();
-  }
-});
-
-// ---------- AI Chat ----------
-
-app.post("/api/chat", handleChat);
-
-// ---------- Citations ----------
-
-app.use("/api/citations", citationsRouter);
-
-// ---------- Preview (render without saving) ----------
-
-app.get("/api/preview/:docName", async (req, res) => {
-  const docName = req.params.docName || DEFAULT_DOC_NAME;
-
-  if (oauthEnabled) {
-    const token = extractToken(req.headers.cookie);
-    const user = await resolveUser(token);
-    if (!user || !user.canEdit) {
-      res.status(403).json({ error: "Unauthorized" });
-      return;
-    }
-  }
-
-  try {
-    // Flush the live Hocuspocus doc to disk first
-    const conn = await hocuspocus.openDirectConnection(docName);
-    if (conn.document) {
-      const update = Y.encodeStateAsUpdate(conn.document);
-      writeFileSync(docPath(docName), Buffer.from(update));
-    }
-    await conn.disconnect();
-
-    const result = await previewDocument(docName);
-    if ("error" in result) {
-      res.status(404).json({ error: result.error });
-      return;
-    }
-    res.setHeader("Content-Type", "text/html; charset=utf-8");
-    res.send(result.html);
-  } catch (err: any) {
-    console.error("[preview] error:", err);
-    res.status(500).json({ error: err.message || "Preview failed" });
-  }
-});
-
-// ---------- Publish ----------
-
-app.post("/api/publish", async (req, res) => {
-  let userToken: string | undefined;
-
-  if (oauthEnabled) {
-    const token = extractToken(req.headers.cookie);
-    const user = await resolveUser(token);
-    if (!user) {
-      console.warn("[publish] no valid user from token, cookie present:", !!token);
-      res.status(403).json({ error: "Unauthorized: please log in first" });
-      return;
-    }
-    if (!user.canEdit) {
-      console.warn("[publish] user lacks write access:", user.name);
-      res.status(403).json({ error: "Unauthorized: write access required" });
-      return;
-    }
-    userToken = token ?? undefined;
-    if (userToken) setUserToken(userToken);
-  }
-
-  try {
-    const conn = await hocuspocus.openDirectConnection(DEFAULT_DOC_NAME);
-    if (conn.document) {
-      const liveTypes: string[] = [];
-      conn.document.share.forEach((_v, k) => liveTypes.push(k));
-      console.log("[publish] Live Hocuspocus doc shared types:", liveTypes);
-      const liveFragment = conn.document.getXmlFragment("default");
-      console.log("[publish] Live XmlFragment length:", liveFragment.length);
-
-      const update = Y.encodeStateAsUpdate(conn.document);
-      console.log("[publish] Encoded state size:", update.byteLength, "bytes");
-      writeFileSync(docPath(DEFAULT_DOC_NAME), Buffer.from(update));
-    } else {
-      console.warn("[publish] openDirectConnection returned no document");
-    }
-    await conn.disconnect();
-
-    const result = await publishDocument(DEFAULT_DOC_NAME, userToken);
-    if (!result.success) {
-      res.status(500).json({ error: result.error || "Publish failed" });
-      return;
-    }
-    res.json(result);
-  } catch (err: any) {
-    console.error("[publish] error:", err);
-    res.status(500).json({ error: err.message || "Publish failed" });
-  }
-});
-
-// ---------- Reset Document ----------
-
-app.post("/api/admin/reset-document", async (req, res) => {
-  if (oauthEnabled) {
-    const token = extractToken(req.headers.cookie);
-    const user = await resolveUser(token);
-    if (!user || !user.canEdit) {
-      res.status(403).json({ error: "Unauthorized" });
-      return;
-    }
-    if (token) setUserToken(token);
-  }
-
-  try {
-    // Delete the local .yjs file so the next connection starts fresh
-    const p = docPath(DEFAULT_DOC_NAME);
-    if (existsSync(p)) {
-      const { unlinkSync } = await import("fs");
-      unlinkSync(p);
-      console.log("[admin] deleted local Y.Doc file:", p);
-    }
-
-    // Close existing connections to force reload
-    await hocuspocus.closeConnections(DEFAULT_DOC_NAME);
-    console.log("[admin] closed connections for", DEFAULT_DOC_NAME);
-
-    res.json({ success: true, message: "Document reset. Refresh the editor to start fresh." });
-  } catch (err: any) {
-    console.error("[admin] reset error:", err);
-    res.status(500).json({ error: err.message || "Reset failed" });
-  }
-});
-
-// ---------- Image Upload ----------
-
-const upload = multer({ storage: multer.memoryStorage(), limits: { fileSize: 10 * 1024 * 1024 } });
-
-app.post("/api/upload", upload.single("file"), async (req, res) => {
-  try {
-    const file = (req as any).file as Express.Multer.File | undefined;
-    if (!file) {
-      res.status(400).json({ error: "No file provided" });
-      return;
-    }
-
-    const ext = file.originalname.split(".").pop() || "png";
-    const filename = `${randomUUID()}.${ext}`;
-
-    const userToken = extractToken(req.headers.cookie) ?? undefined;
-    if (userToken) setUserToken(userToken);
-
-    if (isHfStorageEnabled()) {
-      const url = await uploadImageToHf(file.buffer, filename, userToken);
-      res.json({ url });
-      return;
-    }
-
-    // Fallback: save locally and serve via /uploads/
-    const uploadsDir = join(DATA_DIR, "uploads");
-    mkdirSync(uploadsDir, { recursive: true });
-    writeFileSync(join(uploadsDir, filename), file.buffer);
-    res.json({ url: `/uploads/${filename}` });
-  } catch (err: any) {
-    console.error("[upload] error:", err);
-    res.status(500).json({ error: err.message || "Upload failed" });
-  }
-});
-
-// Serve locally uploaded images
-app.use("/uploads", express.static(join(DATA_DIR, "uploads")));
-
-// Serve locally published articles
-app.use("/published", express.static(join(DATA_DIR, "published")));
-
-// ---------- Static frontend ----------
-
-const staticDir =
-  process.env.NODE_ENV === "production"
-    ? join(DATA_DIR, "..", "frontend-dist")
-    : join(DATA_DIR, "..", "..", "frontend", "dist");
-
-function getPublishedPath(docName: string): string {
-  return join(DATA_DIR, "published", docName, "index.html");
-}
-
-function sendLoginPage(res: express.Response) {
-  res.status(200).send(`<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Research Article Template Editor</title>
-  <style>
-    * { margin: 0; padding: 0; box-sizing: border-box; }
-    body { display: flex; align-items: center; justify-content: center; height: 100vh;
-           font-family: system-ui, -apple-system, sans-serif; background: #0a0a0a; color: #aaa; }
-    .card { text-align: center; max-width: 420px; padding: 2rem; }
-    h1 { color: #fff; font-size: 1.5rem; margin-bottom: 0.5rem; }
-    p { margin-bottom: 1.5rem; line-height: 1.5; }
-    a.btn { display: inline-block; padding: 0.6rem 1.5rem; border-radius: 8px;
-            background: #958DF1; color: #fff; text-decoration: none; font-weight: 500;
-            transition: opacity 0.15s; }
-    a.btn:hover { opacity: 0.85; }
-  </style>
-</head>
-<body>
-  <div class="card">
-    <h1>This article is not yet published</h1>
-    <p>Log in with your Hugging Face account to access the editor.</p>
-    <a class="btn" href="/oauth/authorize" target="_blank">Sign in with Hugging Face</a>
-  </div>
-</body>
-</html>`);
-}
-
-if (existsSync(staticDir)) {
-  // Serve JS/CSS/assets but NOT index.html (routing handles that)
-  app.use(express.static(staticDir, { index: false }));
-
-  // GET /editor → requires auth, serves the SPA
-  app.get("/editor", async (req, res) => {
-    if (oauthEnabled) {
-      const token = extractToken(req.headers.cookie);
-      const user = await resolveUser(token);
-
-      if (!user || !user.canEdit) {
-        // Not logged in or no write access → show login prompt
-        // Can't navigate top frame from sandboxed iframe, so show a button
-        res.status(200).send(`<!DOCTYPE html>
-<html lang="en">
-<head><meta charset="utf-8"/><meta name="viewport" content="width=device-width,initial-scale=1"/>
-<title>Sign in required</title>
-<style>*{margin:0;padding:0;box-sizing:border-box}body{display:flex;align-items:center;justify-content:center;height:100vh;font-family:system-ui,-apple-system,sans-serif;background:#0a0a0a;color:#aaa}.card{text-align:center;max-width:420px;padding:2rem}h1{color:#fff;font-size:1.5rem;margin-bottom:.5rem}p{margin-bottom:1.5rem;line-height:1.5}a.btn{display:inline-block;padding:.6rem 1.5rem;border-radius:8px;background:#958DF1;color:#fff;text-decoration:none;font-weight:500;transition:opacity .15s}a.btn:hover{opacity:.85}</style></head>
-<body><div class="card">
-<h1>Editor access</h1>
-<p>Sign in with your Hugging Face account to start editing.</p>
-<a class="btn" href="/oauth/authorize" target="_blank">Sign in with Hugging Face</a>
-<p style="margin-top:1rem;font-size:.85rem;color:#666">After signing in, come back and <a href="/editor" style="color:#958DF1">refresh this page</a>.</p>
-</div></body></html>`);
-        return;
-      }
-    }
-
-    res.sendFile(join(staticDir, "index.html"));
-  });
-
-  // GET / (and all other paths) → public article or login prompt
-  app.get("*", async (req, res) => {
-    if (!oauthEnabled) {
-      // Dev mode: serve editor directly
-      res.sendFile(join(staticDir, "index.html"));
-      return;
-    }
-
-    // Try lazy-restore on every request until successful.
-    // Dataset is public, so no token is needed for reads.
-    // An OAuth token is passed when available for extra reliability.
-    const visitorToken = extractToken(req.headers.cookie) ?? undefined;
-    await ensurePublishedRestored(visitorToken);
-
-    // In production with OAuth: serve the published article if it exists
-    const publishedPath = getPublishedPath(DEFAULT_DOC_NAME);
-
-    if (existsSync(publishedPath)) {
-      res.sendFile(publishedPath);
-      return;
-    }
-
-    // No published version → login page
-    sendLoginPage(res);
-  });
-}
-
-// ---------- Start ----------
+const { httpServer } = createApp();
 
 const server = httpServer.listen(PORT, async () => {
   console.log(`[server] running on http://localhost:${PORT}`);
   console.log(`[server] collab websocket at ws://localhost:${PORT}/collab`);
   console.log(`[server] SPACE_ID=${process.env.SPACE_ID || "(not set)"} HF_DATASET_ID=${getDatasetId() || "(empty)"} HF_TOKEN=${process.env.HF_TOKEN ? "set" : "not set"}`);
-
-  // Eager restore: dataset is public, works without token
-  await ensurePublishedRestored();
 });
 
 async function gracefulShutdown(signal: string) {

backend/src/utils.ts

@@ -3,12 +3,26 @@ import { fileURLToPath } from "url";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
-export const DATA_DIR = join(__dirname, "..", "data");
+const DEFAULT_DATA_DIR = join(__dirname, "..", "data");
+
+let _dataDir: string | undefined;
+
+/** Override DATA_DIR for testing. Pass undefined to reset to default. */
+export function setDataDir(dir: string | undefined) {
+  _dataDir = dir;
+}
+
+export function getDataDir(): string {
+  return _dataDir ?? process.env.DATA_DIR ?? DEFAULT_DATA_DIR;
+}
+
+/** @deprecated Use getDataDir() instead */
+export const DATA_DIR = DEFAULT_DATA_DIR;
 
 export function sanitizeName(name: string): string {
   return name.replace(/[^a-zA-Z0-9_-]/g, "_");
 }
 
 export function docPath(name: string): string {
-  return join(DATA_DIR, `${sanitizeName(name)}.yjs`);
+  return join(getDataDir(), `${sanitizeName(name)}.yjs`);
 }

backend/tests/agent-chat.test.ts

@@ -0,0 +1,128 @@
+/**
+ * Agent Chat Tests
+ *
+ * Tests for /api/chat and /api/embed-chat routes:
+ * - Input validation (missing messages)
+ * - Missing API key handling
+ * - Model list endpoint
+ */
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import request from "supertest";
+import { mkdtempSync, rmSync } from "fs";
+import { mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { setDataDir } from "../src/utils.js";
+import { createApp, resetSaveTimers } from "../src/create-app.js";
+
+let tmpDir: string;
+let app: ReturnType<typeof createApp>["app"];
+let httpServer: ReturnType<typeof createApp>["httpServer"];
+let hocuspocus: ReturnType<typeof createApp>["hocuspocus"];
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "collab-agent-test-"));
+  mkdirSync(tmpDir, { recursive: true });
+  setDataDir(tmpDir);
+  const result = createApp();
+  app = result.app;
+  httpServer = result.httpServer;
+  hocuspocus = result.hocuspocus;
+});
+
+afterEach(async () => {
+  resetSaveTimers();
+  try { await hocuspocus.destroy(); } catch {}
+  try { httpServer.close(); } catch {}
+  setDataDir(undefined);
+  try { rmSync(tmpDir, { recursive: true, force: true }); } catch {}
+  vi.restoreAllMocks();
+});
+
+describe("/api/models", () => {
+  it("returns a non-empty array of models", async () => {
+    const res = await request(app).get("/api/models").expect(200);
+    expect(Array.isArray(res.body)).toBe(true);
+    expect(res.body.length).toBeGreaterThan(0);
+    expect(res.body[0]).toHaveProperty("id");
+    expect(res.body[0]).toHaveProperty("label");
+    expect(res.body[0]).toHaveProperty("context");
+    expect(res.body[0]).toHaveProperty("cost");
+  });
+});
+
+describe("/api/chat - validation", () => {
+  it("rejects request without messages", async () => {
+    const res = await request(app)
+      .post("/api/chat")
+      .send({ context: {} })
+      .expect(400);
+
+    expect(res.body).toHaveProperty("error");
+    expect(res.body.error).toContain("messages");
+  });
+
+  it("rejects request with non-array messages", async () => {
+    const res = await request(app)
+      .post("/api/chat")
+      .send({ messages: "not-an-array" })
+      .expect(400);
+
+    expect(res.body).toHaveProperty("error");
+  });
+
+  it("returns 500 when OPENROUTER_API_KEY is missing", async () => {
+    const original = process.env.OPENROUTER_API_KEY;
+    delete process.env.OPENROUTER_API_KEY;
+
+    const res = await request(app)
+      .post("/api/chat")
+      .send({
+        messages: [{ id: "1", role: "user", parts: [{ type: "text", text: "hello" }] }],
+      })
+      .expect(500);
+
+    expect(res.body).toHaveProperty("error");
+    expect(res.body.error).toContain("OPENROUTER_API_KEY");
+
+    if (original) process.env.OPENROUTER_API_KEY = original;
+  });
+});
+
+describe("/api/embed-chat - validation", () => {
+  it("rejects request without messages", async () => {
+    const res = await request(app)
+      .post("/api/embed-chat")
+      .send({ context: {} })
+      .expect(400);
+
+    expect(res.body).toHaveProperty("error");
+    expect(res.body.error).toContain("messages");
+  });
+
+  it("rejects request with non-array messages", async () => {
+    const res = await request(app)
+      .post("/api/embed-chat")
+      .send({ messages: 42 })
+      .expect(400);
+
+    expect(res.body).toHaveProperty("error");
+  });
+
+  it("returns 500 when OPENROUTER_API_KEY is missing", async () => {
+    const original = process.env.OPENROUTER_API_KEY;
+    delete process.env.OPENROUTER_API_KEY;
+
+    const res = await request(app)
+      .post("/api/embed-chat")
+      .send({
+        messages: [{ id: "1", role: "user", parts: [{ type: "text", text: "make a chart" }] }],
+      })
+      .expect(500);
+
+    expect(res.body).toHaveProperty("error");
+    expect(res.body.error).toContain("OPENROUTER_API_KEY");
+
+    if (original) process.env.OPENROUTER_API_KEY = original;
+  });
+});

backend/tests/api-routes.test.ts

@@ -0,0 +1,156 @@
+/**
+ * API Routes Tests (Section 3 of TESTS.md)
+ *
+ * Integration tests using Supertest against createApp().
+ * Runs with OAuth disabled (no SPACE_ID) so all routes are accessible.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import request from "supertest";
+import { mkdtempSync, rmSync, writeFileSync, existsSync } from "fs";
+import { mkdirSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import * as Y from "yjs";
+import { setDataDir, docPath } from "../src/utils.js";
+import { createApp } from "../src/create-app.js";
+import { resetSaveTimers } from "../src/create-app.js";
+
+let tmpDir: string;
+let app: ReturnType<typeof createApp>["app"];
+let httpServer: ReturnType<typeof createApp>["httpServer"];
+let hocuspocus: ReturnType<typeof createApp>["hocuspocus"];
+
+function seedDoc(name: string, text: string) {
+  const ydoc = new Y.Doc();
+  const fragment = ydoc.getXmlFragment("default");
+  const el = new Y.XmlElement("paragraph");
+  el.insert(0, [new Y.XmlText(text)]);
+  fragment.insert(0, [el]);
+
+  const frontmatter = ydoc.getMap("frontmatter");
+  frontmatter.set("title", "Test Article");
+  frontmatter.set("description", "A test article");
+
+  const state = Y.encodeStateAsUpdate(ydoc);
+  writeFileSync(docPath(name), Buffer.from(state));
+}
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "collab-api-test-"));
+  mkdirSync(tmpDir, { recursive: true });
+  setDataDir(tmpDir);
+
+  const result = createApp();
+  app = result.app;
+  httpServer = result.httpServer;
+  hocuspocus = result.hocuspocus;
+});
+
+afterEach(async () => {
+  resetSaveTimers();
+  try {
+    await hocuspocus.destroy();
+  } catch {}
+  try {
+    httpServer.close();
+  } catch {}
+  setDataDir(undefined);
+  try {
+    rmSync(tmpDir, { recursive: true, force: true });
+  } catch {}
+});
+
+/**
+ * Drive the async publish pipeline end-to-end: POST returns a jobId, then we
+ * consume /api/publish/stream until the "done" SSE event fires. Supertest
+ * buffers the full response body once the server closes the stream, which
+ * happens right after `done`.
+ */
+async function runPublishAndWait(): Promise<{
+  success: boolean;
+  result?: { htmlUrl: string | null; pdfUrl: string | null; thumbUrl: string | null; success: boolean };
+  error?: string;
+}> {
+  const post = await request(app).post("/api/publish").expect(200);
+  expect(post.body).toHaveProperty("jobId");
+  const jobId: string = post.body.jobId;
+
+  const stream = await request(app)
+    .get(`/api/publish/stream?jobId=${encodeURIComponent(jobId)}`)
+    .buffer(true)
+    .parse((res, cb) => {
+      let data = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk: string) => { data += chunk; });
+      res.on("end", () => cb(null, data));
+    });
+
+  const body = stream.text ?? (stream.body as unknown as string);
+  const match = /event: done\ndata: (.+)/.exec(body);
+  if (!match) throw new Error(`No done event in SSE body: ${body.slice(0, 500)}`);
+  return JSON.parse(match[1]);
+}
+
+describe("3.1 Publish routes", () => {
+  it("3.1.1 POST /api/publish returns a jobId and the SSE stream reports success", async () => {
+    seedDoc("default", "Hello from the test article.");
+
+    const done = await runPublishAndWait();
+
+    expect(done.success).toBe(true);
+    expect(done.result?.success).toBe(true);
+    expect(typeof done.result?.htmlUrl).toBe("string");
+  }, 60_000);
+
+  it("3.1.2 Publish writes local HTML file", async () => {
+    seedDoc("default", "Published content goes here.");
+
+    await runPublishAndWait();
+
+    const publishedPath = join(tmpDir, "published", "default", "index.html");
+    expect(existsSync(publishedPath)).toBe(true);
+  }, 60_000);
+
+  it("3.1.3 Concurrent POST /api/publish returns 409 for the second request", async () => {
+    seedDoc("default", "Concurrency check.");
+
+    // Fire both in the same tick. The mutex is set synchronously inside the
+    // first handler before `res.json({ jobId })` is returned, so the second
+    // handler (scheduled right after) must see it and respond with 409.
+    const [a, b] = await Promise.all([
+      request(app).post("/api/publish"),
+      request(app).post("/api/publish"),
+    ]);
+
+    const statuses = [a.status, b.status].sort((x, y) => x - y);
+    expect(statuses).toEqual([200, 409]);
+
+    const winner = a.status === 200 ? a : b;
+    expect(winner.body).toHaveProperty("jobId");
+    const loser = a.status === 409 ? a : b;
+    expect(loser.body).toHaveProperty("error");
+
+    // Drain the SSE stream so the job releases cleanly and the test harness
+    // doesn't leak open sockets.
+    await request(app)
+      .get(`/api/publish/stream?jobId=${encodeURIComponent(winner.body.jobId)}`)
+      .buffer(true)
+      .parse((res, cb) => {
+        let data = "";
+        res.setEncoding("utf8");
+        res.on("data", (chunk: string) => { data += chunk; });
+        res.on("end", () => cb(null, data));
+      });
+  }, 60_000);
+});
+
+describe("3.2 Auth status", () => {
+  it("returns authenticated=true when OAuth is disabled", async () => {
+    const res = await request(app)
+      .get("/api/auth/status")
+      .expect(200);
+
+    expect(res.body).toHaveProperty("authenticated", true);
+    expect(res.body).toHaveProperty("canEdit", true);
+  });
+});

backend/tests/persistence.test.ts

@@ -0,0 +1,110 @@
+/**
+ * Persistence Tests (Section 2 of TESTS.md)
+ *
+ * Tests debouncedSave, local file read/write, and flushAll.
+ * Uses a temporary directory to avoid polluting real data.
+ */
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdirSync, existsSync, readFileSync, writeFileSync } from "fs";
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import * as Y from "yjs";
+import { setDataDir, getDataDir, docPath } from "../src/utils.js";
+import { debouncedSave, resetSaveTimers } from "../src/create-app.js";
+
+let tmpDir: string;
+
+beforeEach(() => {
+  tmpDir = mkdtempSync(join(tmpdir(), "collab-test-"));
+  mkdirSync(tmpDir, { recursive: true });
+  setDataDir(tmpDir);
+});
+
+afterEach(() => {
+  resetSaveTimers();
+  setDataDir(undefined);
+  try {
+    rmSync(tmpDir, { recursive: true, force: true });
+  } catch {}
+});
+
+function makeDoc(text: string): Y.Doc {
+  const ydoc = new Y.Doc();
+  const fragment = ydoc.getXmlFragment("default");
+  const el = new Y.XmlElement("paragraph");
+  el.insert(0, [new Y.XmlText(text)]);
+  fragment.insert(0, [el]);
+  return ydoc;
+}
+
+describe("2.1 Local persistence", () => {
+  it("2.1.1 debouncedSave writes .yjs file after debounce", async () => {
+    const ydoc = makeDoc("Hello world");
+
+    debouncedSave("test-doc", ydoc);
+
+    // File should NOT exist immediately (debounce is 2s)
+    const p = docPath("test-doc");
+    expect(existsSync(p)).toBe(false);
+
+    // Wait for debounce to fire
+    await new Promise((r) => setTimeout(r, 2500));
+
+    expect(existsSync(p)).toBe(true);
+    const buf = readFileSync(p);
+    expect(buf.length).toBeGreaterThan(0);
+
+    // Verify it's valid Yjs binary by applying it to a new doc
+    const restored = new Y.Doc();
+    Y.applyUpdate(restored, new Uint8Array(buf));
+    const fragment = restored.getXmlFragment("default");
+    expect(fragment.length).toBeGreaterThan(0);
+  });
+
+  it("2.1.2 docPath reads from configured DATA_DIR", () => {
+    // Write a .yjs file manually, then verify docPath points to it
+    const ydoc = makeDoc("Existing content");
+    const state = Y.encodeStateAsUpdate(ydoc);
+    const p = docPath("existing");
+    writeFileSync(p, Buffer.from(state));
+
+    // Read it back and verify content
+    expect(existsSync(p)).toBe(true);
+    const buf = readFileSync(p);
+    const restored = new Y.Doc();
+    Y.applyUpdate(restored, new Uint8Array(buf));
+    const fragment = restored.getXmlFragment("default");
+    expect(fragment.length).toBeGreaterThan(0);
+  });
+
+  it("2.1.3 debounce collapses rapid saves into one write", async () => {
+    const ydoc = makeDoc("Version 1");
+
+    // Trigger 3 rapid saves
+    debouncedSave("rapid", ydoc);
+
+    const ydoc2 = makeDoc("Version 2");
+    debouncedSave("rapid", ydoc2);
+
+    const ydoc3 = makeDoc("Version 3");
+    debouncedSave("rapid", ydoc3);
+
+    const p = docPath("rapid");
+
+    // Nothing written yet
+    expect(existsSync(p)).toBe(false);
+
+    // Wait for the single debounced write
+    await new Promise((r) => setTimeout(r, 2500));
+
+    expect(existsSync(p)).toBe(true);
+
+    // The file should contain the last version (ydoc3)
+    const buf = readFileSync(p);
+    const restored = new Y.Doc();
+    Y.applyUpdate(restored, new Uint8Array(buf));
+    const fragment = restored.getXmlFragment("default");
+    expect(fragment.length).toBeGreaterThan(0);
+  });
+});