Upload folder using huggingface_hub

.vscode/launch.json

@@ -0,0 +1,15 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "type": "chrome",
+            "request": "launch",
+            "name": "Launch Chrome against localhost",
+            "url": "http://localhost:8080",
+            "webRoot": "${workspaceFolder}"
+        }
+    ]
+}

README.md

@@ -1,23 +1,58 @@
----
-license: llama3
-datasets:
-- shareAI/ShareGPT-Chinese-English-90k
-- OpenAssistant/oasst2
-- tatsu-lab/alpaca
-language:
-- en
-base_model:
-- meta-llama/Meta-Llama-3-8B-Instruct
-pipeline_tag: text-generation
-library_name: transformers
-tags:
-- text-generation
-- chat
-- assistant
-- lora
-- conversational
-- qlora
-- fine-tuned
-- llama
-- transformers
----
+# NovaChat Platform
+
+A production-grade AI chatbot platform with live web search, streaming responses, and a modern UI.
+
+## Folder Structure
+- backend
+  - src
+    - ai (routing, memory, context compression)
+    - search (search, extraction, ranking, cache)
+    - utils (LLM streaming client)
+- frontend
+  - src (React UI)
+
+## Requirements
+- Node.js 20+
+- npm 10+
+
+## Backend Setup
+```bash
+cd backend
+npm install
+npm run build
+set LLM_API_KEY=YOUR_KEY_HERE
+set LLM_MODEL=gpt-4o-mini
+set LLM_API_BASE=https://api.openai.com
+npm start
+```
+
+## Frontend Setup
+```bash
+cd frontend
+npm install
+npm run dev
+```
+
+The frontend is proxied to `http://localhost:8080` for API calls.
+
+## Docker Setup (Compose)
+```bash
+set LLM_API_KEY=YOUR_KEY_HERE
+set LLM_MODEL=gpt-4o-mini
+set LLM_API_BASE=https://api.openai.com
+docker compose up --build
+```
+
+Open `http://localhost:4173`.
+
+## Performance Notes
+- SSE streaming for token-by-token delivery.
+- Parallel search fetch + content extraction.
+- LRU caches for search results and conversation memory.
+- Minimal sync blocking in the request path.
+
+## Environment Variables
+- `LLM_API_KEY`: API key for OpenAI-compatible endpoint
+- `LLM_API_BASE`: Base URL for the OpenAI-compatible API (default: `https://api.openai.com`)
+- `LLM_MODEL`: Model id (default: `gpt-4o-mini`)
+- `PORT`: Backend port (default: `8080`)

backend/Dockerfile

@@ -0,0 +1,17 @@
+# Backend Dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm install
+
+COPY tsconfig.json ./
+COPY src ./src
+
+RUN npm run build
+
+ENV PORT=8080
+EXPOSE 8080
+
+CMD ["npm", "start"]

backend/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ai-chatbot-backend",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch --enable-source-maps dist/index.js",
+    "build": "tsc -p tsconfig.json",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@fastify/cors": "^10.0.0",
+    "@mozilla/readability": "^0.5.0",
+    "fastify": "^5.2.1",
+    "jsdom": "^26.0.0",
+    "lru-cache": "^11.0.2",
+    "undici": "^6.21.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2"
+  }
+}

backend/src/ai/context.ts

@@ -0,0 +1,20 @@
+import { ChatMessage } from "../types.js";
+
+const SENTENCE_SPLIT = /(?<=[.!?])\s+/;
+
+export function summarizeExtractive(messages: ChatMessage[], maxSentences = 5) {
+  const text = messages.map((m) => `${m.role}: ${m.content}`).join(" ");
+  const sentences = text.split(SENTENCE_SPLIT).filter(Boolean);
+  if (sentences.length <= maxSentences) return sentences.join(" ");
+  const head = sentences.slice(0, Math.ceil(maxSentences / 2));
+  const tail = sentences.slice(-Math.floor(maxSentences / 2));
+  return [...head, ...tail].join(" ");
+}
+
+export function estimateTokens(text: string) {
+  return Math.ceil(text.split(/\s+/).length * 1.35);
+}
+
+export function totalTokens(messages: ChatMessage[]) {
+  return messages.reduce((acc, msg) => acc + estimateTokens(msg.content), 0);
+}

backend/src/ai/engine.ts

@@ -0,0 +1,89 @@
+import { ChatMessage, ChatRequest, SearchSummary } from "../types.js";
+import { memoryStore } from "./memory.js";
+import { summarizeExtractive, totalTokens } from "./context.js";
+import { buildSystemPrompt, shouldSearch, trimHistory } from "./router.js";
+import { searchWeb } from "../search/search.js";
+import { streamChatCompletion } from "../utils/stream.js";
+
+const MAX_CONTEXT_TOKENS = 2600;
+
+export type EngineEvents = {
+  onStatus: (message: string) => void;
+  onToken: (token: string) => void;
+  onDone: () => void;
+  onError: (message: string) => void;
+};
+
+function buildSearchContext(summary: SearchSummary) {
+  const lines: string[] = [];
+  summary.results.forEach((r, idx) => {
+    lines.push(`Source ${idx + 1}: ${r.title} (${r.url})`);
+    lines.push(r.snippet);
+  });
+  summary.topContent.forEach((c, idx) => {
+    lines.push(`Content ${idx + 1}: ${c.title}`);
+    lines.push(c.content.slice(0, 1200));
+  });
+  return lines.join("\n");
+}
+
+export async function handleChat(request: ChatRequest, events: EngineEvents) {
+  const session = memoryStore.get(request.sessionId);
+  const userMessage: ChatMessage = {
+    id: `msg_${Date.now()}`,
+    role: "user",
+    content: request.message,
+    createdAt: Date.now()
+  };
+
+  session.messages.push(userMessage);
+
+  const useSearch = shouldSearch(request.message, request.mode ?? "auto");
+  let searchSummary: SearchSummary | null = null;
+
+  if (useSearch) {
+    events.onStatus("Searching web...");
+    try {
+      searchSummary = await searchWeb(request.message);
+      events.onStatus("Summarizing sources...");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : "Search failed";
+      events.onStatus("Search failed, continuing without web context.");
+      events.onError(msg);
+    }
+  }
+
+  if (totalTokens(session.messages) > MAX_CONTEXT_TOKENS) {
+    const trimmed = trimHistory(session.messages, 12);
+    session.summary = summarizeExtractive(trimmed, 6);
+    session.messages = trimmed;
+  }
+
+  const searchContext = searchSummary ? buildSearchContext(searchSummary) : null;
+  const systemPrompt = buildSystemPrompt(session.summary, searchContext);
+
+  const payloadMessages = [
+    { role: "system", content: systemPrompt },
+    ...session.messages.map((m) => ({ role: m.role, content: m.content }))
+  ];
+
+  const assistantMessage: ChatMessage = {
+    id: `msg_${Date.now()}_assistant`,
+    role: "assistant",
+    content: "",
+    createdAt: Date.now()
+  };
+
+  try {
+    await streamChatCompletion(payloadMessages, (token) => {
+      assistantMessage.content += token;
+      events.onToken(token);
+    });
+    session.messages.push(assistantMessage);
+    memoryStore.set(request.sessionId, session);
+    events.onDone();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : "LLM call failed";
+    events.onError(msg);
+  }
+}

backend/src/ai/memory.ts

@@ -0,0 +1,34 @@
+import { ChatMessage } from "../types.js";
+import { LRUCache } from "lru-cache";
+
+export type SessionState = {
+  messages: ChatMessage[];
+  summary: string;
+  lastAccess: number;
+};
+
+const sessions = new LRUCache<string, SessionState>({
+  max: 5000,
+  ttl: 1000 * 60 * 60 * 6
+});
+
+export const memoryStore = {
+  get(sessionId: string): SessionState {
+    const existing = sessions.get(sessionId);
+    if (existing) {
+      existing.lastAccess = Date.now();
+      return existing;
+    }
+    const created: SessionState = {
+      messages: [],
+      summary: "",
+      lastAccess: Date.now()
+    };
+    sessions.set(sessionId, created);
+    return created;
+  },
+  set(sessionId: string, state: SessionState) {
+    state.lastAccess = Date.now();
+    sessions.set(sessionId, state);
+  }
+};

backend/src/ai/router.ts

@@ -0,0 +1,47 @@
+import { ChatMessage } from "../types.js";
+
+const SEARCH_HINTS = [
+  "search",
+  "browse",
+  "look up",
+  "latest",
+  "today",
+  "current",
+  "news",
+  "price",
+  "stock",
+  "weather",
+  "schedule",
+  "open ai",
+  "openai",
+  "documentation",
+  "docs"
+];
+
+export function shouldSearch(userMessage: string, mode: "auto" | "search" | "no-search") {
+  if (mode === "search") return true;
+  if (mode === "no-search") return false;
+  const normalized = userMessage.toLowerCase();
+  return SEARCH_HINTS.some((hint) => normalized.includes(hint));
+}
+
+export function buildSystemPrompt(summary: string, searchContext: string | null) {
+  const base = [
+    "You are a production-grade AI assistant. Be concise, accurate, and clear.",
+    "Use markdown only when it improves clarity.",
+    "If citing sources, include short parenthetical source labels like (Source 1).",
+    "If you use web results, prefer them over memory."
+  ];
+  if (summary) {
+    base.push(`Conversation summary: ${summary}`);
+  }
+  if (searchContext) {
+    base.push(`Web context:\n${searchContext}`);
+  }
+  return base.join("\n");
+}
+
+export function trimHistory(messages: ChatMessage[], max = 20) {
+  if (messages.length <= max) return messages;
+  return messages.slice(messages.length - max);
+}

backend/src/index.ts

@@ -0,0 +1,93 @@
+import Fastify from "fastify";
+import cors from "@fastify/cors";
+import { z } from "zod";
+import { handleChat } from "./ai/engine.js";
+import { ChatRequest } from "./types.js";
+
+const server = Fastify({
+  logger: true
+});
+
+await server.register(cors, {
+  origin: true,
+  credentials: true
+});
+
+server.get("/health", async () => ({ status: "ok" }));
+
+server.post("/api/chat", async (request, reply) => {
+  const body = request.body as ChatRequest;
+  const schema = z.object({
+    sessionId: z.string().min(1),
+    message: z.string().min(1),
+    mode: z.enum(["auto", "search", "no-search"]).optional()
+  });
+  const parsed = schema.safeParse(body);
+  if (!parsed.success) {
+    reply.status(400);
+    return { error: parsed.error.flatten() };
+  }
+
+  const chunks: string[] = [];
+  await handleChat(parsed.data, {
+    onStatus: () => {},
+    onToken: (token) => chunks.push(token),
+    onDone: () => {},
+    onError: () => {}
+  });
+
+  return { message: chunks.join("") };
+});
+
+server.get("/api/chat/stream", async (request, reply) => {
+  const query = request.query as Record<string, string>;
+  const schema = z.object({
+    sessionId: z.string().min(1),
+    message: z.string().min(1),
+    mode: z.enum(["auto", "search", "no-search"]).optional()
+  });
+  const parsed = schema.safeParse(query);
+  if (!parsed.success) {
+    reply.status(400);
+    return reply.send({ error: parsed.error.flatten() });
+  }
+
+  reply.raw.writeHead(200, {
+    "Content-Type": "text/event-stream",
+    "Cache-Control": "no-cache, no-transform",
+    Connection: "keep-alive",
+    "X-Accel-Buffering": "no"
+  });
+  reply.raw.flushHeaders?.();
+
+  const writeEvent = (event: string, data: string) => {
+    reply.raw.write(`event: ${event}\n`);
+    reply.raw.write(`data: ${data}\n\n`);
+  };
+
+  const requestPayload: ChatRequest = {
+    sessionId: parsed.data.sessionId,
+    message: parsed.data.message,
+    mode: parsed.data.mode
+  };
+
+  let closed = false;
+  request.raw.on("close", () => {
+    closed = true;
+  });
+
+  await handleChat(requestPayload, {
+    onStatus: (message) => !closed && writeEvent("status", JSON.stringify({ message })),
+    onToken: (token) => !closed && writeEvent("delta", JSON.stringify({ token })),
+    onDone: () => !closed && writeEvent("done", JSON.stringify({ ok: true })),
+    onError: (message) => !closed && writeEvent("error", JSON.stringify({ message }))
+  });
+
+  reply.raw.end();
+});
+
+const port = Number(process.env.PORT ?? 8080);
+server.listen({ port, host: "0.0.0.0" }).catch((err) => {
+  server.log.error(err);
+  process.exit(1);
+});

backend/src/search/cache.ts

@@ -0,0 +1,15 @@
+import { LRUCache } from "lru-cache";
+import { SearchSummary } from "../types.js";
+
+const cache = new LRUCache<string, SearchSummary>({
+  max: 200,
+  ttl: 1000 * 60 * 10
+});
+
+export function getCached(query: string) {
+  return cache.get(query);
+}
+
+export function setCached(query: string, summary: SearchSummary) {
+  cache.set(query, summary);
+}

backend/src/search/duckduckgo.ts

@@ -0,0 +1,34 @@
+import { JSDOM } from "jsdom";
+import { fetchText } from "./fetch.js";
+
+export type RawSearchResult = {
+  title: string;
+  url: string;
+  snippet: string;
+};
+
+export async function searchDuckDuckGo(query: string, limit = 6): Promise<RawSearchResult[]> {
+  const url = `https://lite.duckduckgo.com/lite/?q=${encodeURIComponent(query)}`;
+  const html = await fetchText(url, {
+    headers: {
+      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36"
+    }
+  });
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  const links = Array.from(document.querySelectorAll("a.result-link"));
+  const results: RawSearchResult[] = [];
+
+  for (const link of links) {
+    if (results.length >= limit) break;
+    const title = link.textContent?.trim() ?? "";
+    const url = link.getAttribute("href") ?? "";
+    const snippetEl = link.closest("tr")?.nextElementSibling?.querySelector("td.result-snippet");
+    const snippet = snippetEl?.textContent?.trim() ?? "";
+    if (title && url) {
+      results.push({ title, url, snippet });
+    }
+  }
+
+  return results;
+}

backend/src/search/extract.ts

@@ -0,0 +1,26 @@
+import { JSDOM } from "jsdom";
+import { Readability } from "@mozilla/readability";
+import { fetchText } from "./fetch.js";
+
+export async function extractReadable(url: string) {
+  const html = await fetchText(url, {
+    headers: {
+      "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120 Safari/537.36"
+    }
+  });
+  const dom = new JSDOM(html, { url });
+  const reader = new Readability(dom.window.document);
+  const article = reader.parse();
+  if (article?.textContent) {
+    return {
+      title: article.title ?? "",
+      content: article.textContent.replace(/\s+/g, " ").trim()
+    };
+  }
+
+  const fallbackText = dom.window.document.body?.textContent ?? "";
+  return {
+    title: dom.window.document.title ?? "",
+    content: fallbackText.replace(/\s+/g, " ").trim()
+  };
+}

backend/src/search/fetch.ts

@@ -0,0 +1,13 @@
+import { request } from "undici";
+
+export async function fetchText(url: string, init?: { headers?: Record<string, string> }) {
+  const { body } = await request(url, {
+    method: "GET",
+    headers: {
+      "Accept": "text/html,application/xhtml+xml",
+      ...(init?.headers ?? {})
+    },
+    maxRedirections: 5
+  });
+  return await body.text();
+}

backend/src/search/rank.ts

@@ -0,0 +1,31 @@
+import { RawSearchResult } from "./duckduckgo.js";
+
+export function rankResults(query: string, results: RawSearchResult[]) {
+  const terms = tokenize(query);
+  return results
+    .map((r) => ({
+      ...r,
+      score: scoreDoc(terms, `${r.title} ${r.snippet}`)
+    }))
+    .sort((a, b) => b.score - a.score);
+}
+
+function tokenize(text: string) {
+  return text
+    .toLowerCase()
+    .split(/\W+/)
+    .filter((t) => t.length > 2);
+}
+
+function scoreDoc(terms: string[], text: string) {
+  const tokens = tokenize(text);
+  if (!tokens.length) return 0;
+  const freq = new Map<string, number>();
+  tokens.forEach((t) => freq.set(t, (freq.get(t) ?? 0) + 1));
+  let score = 0;
+  terms.forEach((term) => {
+    const count = freq.get(term) ?? 0;
+    score += count;
+  });
+  return score / tokens.length;
+}

backend/src/search/search.ts

@@ -0,0 +1,51 @@
+import { SearchSummary, SearchResult } from "../types.js";
+import { searchDuckDuckGo } from "./duckduckgo.js";
+import { rankResults } from "./rank.js";
+import { extractReadable } from "./extract.js";
+import { getCached, setCached } from "./cache.js";
+
+export async function searchWeb(query: string): Promise<SearchSummary> {
+  const cached = getCached(query);
+  if (cached) return cached;
+
+  const raw = await searchDuckDuckGo(query, 8);
+  const ranked = rankResults(query, raw);
+  const top = ranked.slice(0, 5);
+
+  const contentResults: Array<{
+    url: string;
+    title: string;
+    content: string;
+  }> = [];
+
+  await Promise.all(
+    top.map(async (item) => {
+      try {
+        const article = await extractReadable(item.url);
+        if (article.content) {
+          contentResults.push({
+            url: item.url,
+            title: article.title || item.title,
+            content: article.content
+          });
+        }
+      } catch {
+        // Ignore extraction errors per-source
+      }
+    })
+  );
+
+  const summary: SearchSummary = {
+    query,
+    results: top.map((r, idx) => ({
+      title: r.title,
+      url: r.url,
+      snippet: r.snippet,
+      score: r.score + (top.length - idx) * 0.01
+    })),
+    topContent: contentResults
+  };
+
+  setCached(query, summary);
+  return summary;
+}

backend/src/types.ts

@@ -0,0 +1,37 @@
+export type Role = "system" | "user" | "assistant" | "tool";
+
+export type ChatMessage = {
+  id: string;
+  role: Role;
+  content: string;
+  createdAt: number;
+};
+
+export type ChatRequest = {
+  sessionId: string;
+  message: string;
+  mode?: "auto" | "search" | "no-search";
+};
+
+export type SearchResult = {
+  title: string;
+  url: string;
+  snippet: string;
+  score: number;
+  content: string;
+};
+
+export type SearchSummary = {
+  query: string;
+  results: Array<{
+    title: string;
+    url: string;
+    snippet: string;
+    score: number;
+  }>;
+  topContent: Array<{
+    url: string;
+    title: string;
+    content: string;
+  }>;
+};

backend/src/utils/stream.ts

@@ -0,0 +1,63 @@
+import { request } from "undici";
+
+const API_BASE = process.env.LLM_API_BASE ?? "https://api.openai.com";
+const API_KEY = process.env.LLM_API_KEY ?? "";
+const MODEL = process.env.LLM_MODEL ?? "gpt-4o-mini";
+
+export async function streamChatCompletion(
+  messages: Array<{ role: string; content: string }>,
+  onToken: (token: string) => void
+) {
+  if (!API_KEY) {
+    throw new Error("Missing LLM_API_KEY environment variable.");
+  }
+
+  const payload = {
+    model: MODEL,
+    messages,
+    stream: true,
+    temperature: 0.3
+  };
+
+  const { body, statusCode } = await request(`${API_BASE}/v1/chat/completions`, {
+    method: "POST",
+    headers: {
+      "Authorization": `Bearer ${API_KEY}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify(payload)
+  });
+
+  if (statusCode < 200 || statusCode >= 300) {
+    const errorText = await body.text();
+    throw new Error(`LLM request failed (${statusCode}): ${errorText.slice(0, 200)}`);
+  }
+
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+
+    let boundary = buffer.indexOf("\n\n");
+    while (boundary !== -1) {
+      const chunk = buffer.slice(0, boundary).trim();
+      buffer = buffer.slice(boundary + 2);
+      if (chunk.startsWith("data:")) {
+        const data = chunk.replace(/^data:\s*/, "").trim();
+        if (data === "[DONE]") return;
+        try {
+          const parsed = JSON.parse(data);
+          const delta = parsed.choices?.[0]?.delta?.content;
+          if (delta) onToken(delta);
+        } catch {
+          // Ignore JSON parse errors in partial chunks
+        }
+      }
+      boundary = buffer.indexOf("\n\n");
+    }
+  }
+}

backend/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

docker-compose.yml

@@ -0,0 +1,23 @@
+services:
+  backend:
+    build:
+      context: ./backend
+    environment:
+      - LLM_API_KEY=${LLM_API_KEY}
+      - LLM_MODEL=${LLM_MODEL:-gpt-4o-mini}
+      - LLM_API_BASE=${LLM_API_BASE:-https://api.openai.com}
+      - PORT=8080
+    ports:
+      - "8080:8080"
+    restart: unless-stopped
+
+  frontend:
+    build:
+      context: ./frontend
+    environment:
+      - VITE_API_BASE=http://localhost:8080
+    ports:
+      - "4173:4173"
+    depends_on:
+      - backend
+    restart: unless-stopped

frontend/Dockerfile

@@ -0,0 +1,16 @@
+# Frontend Dockerfile
+FROM node:20-alpine
+
+WORKDIR /app
+
+COPY package.json package-lock.json* ./
+RUN npm install
+
+COPY vite.config.ts tsconfig.json index.html ./
+COPY src ./src
+
+RUN npm run build
+
+EXPOSE 4173
+
+CMD ["npm", "run", "preview", "--", "--host", "0.0.0.0", "--port", "4173"]

frontend/index.html

@@ -0,0 +1,15 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>NovaChat</title>
+    <link rel="preconnect" href="https://fonts.googleapis.com" />
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+    <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@300;400;500;600;700&family=IBM+Plex+Mono:wght@300;400;500&display=swap" rel="stylesheet" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

frontend/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-chatbot-frontend",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vite build",
+    "preview": "vite preview"
+  },
+  "dependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "@vitejs/plugin-react": "^4.3.4",
+    "typescript": "^5.7.2",
+    "vite": "^6.0.4"
+  }
+}

frontend/src/App.tsx

@@ -0,0 +1,265 @@
+import { useEffect, useMemo, useRef, useState } from "react";
+
+type Role = "user" | "assistant" | "system";
+
+type ChatMessage = {
+  id: string;
+  role: Role;
+  content: string;
+  createdAt: number;
+};
+
+type StatusEvent = {
+  message: string;
+};
+
+const SHORTCUTS = [
+  { combo: "Ctrl+Enter", action: "Send" },
+  { combo: "Ctrl+K", action: "Focus input" },
+  { combo: "Esc", action: "Clear" }
+];
+
+function useSessionId() {
+  const [sessionId] = useState(() => {
+    const cached = localStorage.getItem("novachat_session");
+    if (cached) return cached;
+    const created = crypto.randomUUID();
+    localStorage.setItem("novachat_session", created);
+    return created;
+  });
+  return sessionId;
+}
+
+export default function App() {
+  const sessionId = useSessionId();
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [input, setInput] = useState("");
+  const [status, setStatus] = useState("Idle");
+  const [isStreaming, setIsStreaming] = useState(false);
+  const [theme, setTheme] = useState(() => localStorage.getItem("novachat_theme") ?? "dark");
+  const inputRef = useRef<HTMLTextAreaElement | null>(null);
+  const bottomRef = useRef<HTMLDivElement | null>(null);
+  const streamRef = useRef<EventSource | null>(null);
+
+  useEffect(() => {
+    document.documentElement.dataset.theme = theme;
+    localStorage.setItem("novachat_theme", theme);
+  }, [theme]);
+
+  useEffect(() => {
+    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
+  }, [messages, status]);
+
+  useEffect(() => {
+    const handler = (event: KeyboardEvent) => {
+      if (event.ctrlKey && event.key.toLowerCase() === "k") {
+        event.preventDefault();
+        inputRef.current?.focus();
+      }
+      if (event.ctrlKey && event.key === "Enter") {
+        event.preventDefault();
+        handleSend();
+      }
+      if (event.key === "Escape") {
+        setInput("");
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  });
+
+  const groupedMessages = useMemo(() => {
+    const groups: ChatMessage[][] = [];
+    messages.forEach((msg) => {
+      const lastGroup = groups[groups.length - 1];
+      if (lastGroup && lastGroup[lastGroup.length - 1].role === msg.role) {
+        lastGroup.push(msg);
+      } else {
+        groups.push([msg]);
+      }
+    });
+    return groups;
+  }, [messages]);
+
+  const handleSend = () => {
+    const trimmed = input.trim();
+    if (!trimmed || isStreaming) return;
+
+    const userMessage: ChatMessage = {
+      id: `user_${Date.now()}`,
+      role: "user",
+      content: trimmed,
+      createdAt: Date.now()
+    };
+
+    setMessages((prev) => [...prev, userMessage]);
+    setInput("");
+    setIsStreaming(true);
+    setStatus("Connecting...");
+
+    streamRef.current?.close();
+    const url = new URL("/api/chat/stream", window.location.origin);
+    url.searchParams.set("sessionId", sessionId);
+    url.searchParams.set("message", trimmed);
+
+    const stream = new EventSource(url);
+    streamRef.current = stream;
+
+    let assistantId = `assistant_${Date.now()}`;
+
+    const appendAssistant = (token: string) => {
+      setMessages((prev) => {
+        const next = [...prev];
+        const existing = next.find((msg) => msg.id === assistantId);
+        if (existing) {
+          existing.content += token;
+          return [...next];
+        }
+        return [...next, { id: assistantId, role: "assistant", content: token, createdAt: Date.now() }];
+      });
+    };
+
+    stream.addEventListener("status", (event) => {
+      const data = JSON.parse((event as MessageEvent).data) as StatusEvent;
+      setStatus(data.message);
+    });
+
+    stream.addEventListener("delta", (event) => {
+      const data = JSON.parse((event as MessageEvent).data) as { token: string };
+      appendAssistant(data.token);
+      setStatus("Responding...");
+    });
+
+    stream.addEventListener("done", () => {
+      setIsStreaming(false);
+      setStatus("Idle");
+      stream.close();
+    });
+
+    stream.addEventListener("error", (event) => {
+      setIsStreaming(false);
+      setStatus("Connection error");
+      stream.close();
+    });
+  };
+
+  return (
+    <div className="app">
+      <header className="topbar">
+        <div className="brand">
+          <div className="brand-mark" />
+          <div>
+            <div className="brand-title">NovaChat</div>
+            <div className="brand-subtitle">Real-time intelligence engine</div>
+          </div>
+        </div>
+        <div className="topbar-actions">
+          <button className="ghost" onClick={() => setTheme(theme === "dark" ? "light" : "dark")}>
+            {theme === "dark" ? "Light" : "Dark"} mode
+          </button>
+          <button className="ghost" onClick={() => setMessages([])}>
+            New session
+          </button>
+        </div>
+      </header>
+
+      <main className="layout">
+        <section className="chat">
+          <div className="chat-header">
+            <div>
+              <div className="chat-title">Control Room</div>
+              <div className="chat-subtitle">Ultra-low latency responses with live web search.</div>
+            </div>
+            <div className="status">
+              <span className={isStreaming ? "pulse" : "dot"} />
+              {status}
+            </div>
+          </div>
+
+          <div className="chat-body">
+            {groupedMessages.length === 0 ? (
+              <div className="empty">
+                <h2>Ask anything. Get fast, grounded answers.</h2>
+                <p>Type a request and NovaChat will decide when to pull live web sources.</p>
+                <div className="shortcut-grid">
+                  {SHORTCUTS.map((shortcut) => (
+                    <div key={shortcut.combo} className="shortcut-card">
+                      <div className="shortcut-combo">{shortcut.combo}</div>
+                      <div className="shortcut-action">{shortcut.action}</div>
+                    </div>
+                  ))}
+                </div>
+              </div>
+            ) : (
+              groupedMessages.map((group) => (
+                <div key={group[0].id} className={`message-group ${group[0].role}`}>
+                  <div className="message-meta">{group[0].role === "user" ? "You" : "Nova"}</div>
+                  <div className="message-stack">
+                    {group.map((msg) => (
+                      <div key={msg.id} className="message-bubble">
+                        {msg.content}
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              ))
+            )}
+            {isStreaming && (
+              <div className="typing">
+                <span />
+                <span />
+                <span />
+              </div>
+            )}
+            <div ref={bottomRef} />
+          </div>
+
+          <div className="chat-input">
+            <textarea
+              ref={inputRef}
+              placeholder="Ask NovaChat to research, summarize, or build something..."
+              value={input}
+              onChange={(event) => setInput(event.target.value)}
+              rows={2}
+            />
+            <div className="input-actions">
+              <div className="input-hint">Session: {sessionId.slice(0, 8)}</div>
+              <button className="primary" onClick={handleSend} disabled={isStreaming || !input.trim()}>
+                {isStreaming ? "Streaming..." : "Send"}
+              </button>
+            </div>
+          </div>
+        </section>
+
+        <aside className="sidebar">
+          <div className="card">
+            <h3>Live Ops</h3>
+            <p>Search cache and streaming are running in parallel for zero-lag delivery.</p>
+            <div className="metric">
+              <span>Latency target</span>
+              <strong>&lt; 800ms</strong>
+            </div>
+            <div className="metric">
+              <span>Streaming</span>
+              <strong>Token-by-token</strong>
+            </div>
+          </div>
+          <div className="card">
+            <h3>Search Stack</h3>
+            <p>Multi-source fetch, extraction, ranking, and summarization pipeline.</p>
+            <div className="badge-row">
+              <span>DuckDuckGo</span>
+              <span>Readability</span>
+              <span>LRU Cache</span>
+            </div>
+          </div>
+          <div className="card">
+            <h3>Controls</h3>
+            <p>NovaChat automatically decides when to search the web.</p>
+            <button className="ghost full" onClick={() => setStatus("Manual search mode coming soon")}>Enable manual search</button>
+          </div>
+        </aside>
+      </main>
+    </div>
+  );
+}

frontend/src/main.tsx

@@ -0,0 +1,10 @@
+import React from "react";
+import ReactDOM from "react-dom/client";
+import App from "./App";
+import "./styles.css";
+
+ReactDOM.createRoot(document.getElementById("root")!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);

frontend/src/styles.css

@@ -0,0 +1,422 @@
+:root {
+  color-scheme: light dark;
+  --bg: #0e0f13;
+  --bg-muted: #16181f;
+  --panel: #1d2029;
+  --text: #f6f4f0;
+  --text-muted: #b9becb;
+  --accent: #f68b1f;
+  --accent-soft: rgba(246, 139, 31, 0.18);
+  --border: rgba(255, 255, 255, 0.08);
+  --shadow: 0 30px 60px rgba(0, 0, 0, 0.35);
+  --mono: "IBM Plex Mono", ui-monospace, SFMono-Regular, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  --sans: "Space Grotesk", "Segoe UI", sans-serif;
+}
+
+:root[data-theme="light"] {
+  --bg: #f6f3ee;
+  --bg-muted: #efe8de;
+  --panel: #ffffff;
+  --text: #1b1a19;
+  --text-muted: #5f5b56;
+  --accent: #db3a2f;
+  --accent-soft: rgba(219, 58, 47, 0.15);
+  --border: rgba(0, 0, 0, 0.1);
+  --shadow: 0 30px 60px rgba(12, 12, 12, 0.15);
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: var(--sans);
+  background: radial-gradient(circle at top left, rgba(246, 139, 31, 0.12), transparent 55%),
+    radial-gradient(circle at 20% 20%, rgba(115, 143, 255, 0.15), transparent 45%),
+    var(--bg);
+  color: var(--text);
+  min-height: 100vh;
+}
+
+.app {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+.topbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 24px 40px;
+  border-bottom: 1px solid var(--border);
+  backdrop-filter: blur(14px);
+  position: sticky;
+  top: 0;
+  z-index: 10;
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.brand-mark {
+  width: 44px;
+  height: 44px;
+  border-radius: 14px;
+  background: linear-gradient(135deg, var(--accent), #f7c975);
+  box-shadow: 0 12px 30px rgba(246, 139, 31, 0.35);
+}
+
+.brand-title {
+  font-weight: 600;
+  letter-spacing: 0.04em;
+}
+
+.brand-subtitle {
+  font-size: 0.85rem;
+  color: var(--text-muted);
+}
+
+.topbar-actions {
+  display: flex;
+  gap: 12px;
+}
+
+.layout {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) 320px;
+  gap: 28px;
+  padding: 28px 40px 40px;
+  flex: 1;
+}
+
+.chat {
+  background: var(--panel);
+  border-radius: 28px;
+  box-shadow: var(--shadow);
+  display: flex;
+  flex-direction: column;
+  min-height: 70vh;
+  border: 1px solid var(--border);
+}
+
+.chat-header {
+  padding: 28px 28px 16px;
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  border-bottom: 1px solid var(--border);
+}
+
+.chat-title {
+  font-size: 1.2rem;
+  font-weight: 600;
+}
+
+.chat-subtitle {
+  font-size: 0.9rem;
+  color: var(--text-muted);
+}
+
+.status {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-size: 0.85rem;
+  color: var(--text-muted);
+}
+
+.dot,
+.pulse {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  background: var(--accent);
+}
+
+.pulse {
+  position: relative;
+}
+
+.pulse::after {
+  content: "";
+  position: absolute;
+  inset: -4px;
+  border-radius: 50%;
+  border: 1px solid var(--accent);
+  animation: pulse 1.6s ease-in-out infinite;
+}
+
+@keyframes pulse {
+  0% {
+    transform: scale(0.6);
+    opacity: 0.6;
+  }
+  100% {
+    transform: scale(1.6);
+    opacity: 0;
+  }
+}
+
+.chat-body {
+  padding: 24px 28px;
+  display: flex;
+  flex-direction: column;
+  gap: 22px;
+  overflow-y: auto;
+  flex: 1;
+}
+
+.empty {
+  padding: 40px 0 20px;
+}
+
+.empty h2 {
+  font-size: 1.8rem;
+  margin-bottom: 12px;
+}
+
+.empty p {
+  color: var(--text-muted);
+  max-width: 520px;
+}
+
+.shortcut-grid {
+  margin-top: 24px;
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(140px, 1fr));
+  gap: 12px;
+}
+
+.shortcut-card {
+  background: var(--bg-muted);
+  padding: 14px;
+  border-radius: 16px;
+  border: 1px solid var(--border);
+}
+
+.shortcut-combo {
+  font-family: var(--mono);
+  font-size: 0.85rem;
+  color: var(--accent);
+}
+
+.shortcut-action {
+  font-size: 0.85rem;
+  color: var(--text-muted);
+}
+
+.message-group {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.message-group.user {
+  align-items: flex-end;
+}
+
+.message-group.assistant {
+  align-items: flex-start;
+}
+
+.message-meta {
+  font-size: 0.75rem;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  color: var(--text-muted);
+}
+
+.message-stack {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+}
+
+.message-bubble {
+  padding: 14px 18px;
+  border-radius: 18px;
+  max-width: 520px;
+  line-height: 1.5;
+  background: var(--bg-muted);
+  border: 1px solid var(--border);
+}
+
+.message-group.user .message-bubble {
+  background: linear-gradient(135deg, var(--accent), #f4b36c);
+  color: #1b1a19;
+  border: none;
+}
+
+.typing {
+  display: flex;
+  gap: 6px;
+  align-items: center;
+  padding-left: 8px;
+}
+
+.typing span {
+  width: 8px;
+  height: 8px;
+  background: var(--accent);
+  border-radius: 50%;
+  animation: bounce 1.2s infinite ease-in-out;
+}
+
+.typing span:nth-child(2) {
+  animation-delay: 0.2s;
+}
+
+.typing span:nth-child(3) {
+  animation-delay: 0.4s;
+}
+
+@keyframes bounce {
+  0%, 80%, 100% {
+    transform: translateY(0);
+  }
+  40% {
+    transform: translateY(-6px);
+  }
+}
+
+.chat-input {
+  border-top: 1px solid var(--border);
+  padding: 18px 24px 24px;
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.chat-input textarea {
+  width: 100%;
+  border: 1px solid var(--border);
+  border-radius: 16px;
+  padding: 14px;
+  font-family: var(--sans);
+  font-size: 1rem;
+  background: var(--bg);
+  color: var(--text);
+  resize: none;
+  min-height: 74px;
+}
+
+.input-actions {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+}
+
+.input-hint {
+  font-family: var(--mono);
+  font-size: 0.75rem;
+  color: var(--text-muted);
+}
+
+button {
+  font-family: var(--sans);
+  border: none;
+  border-radius: 12px;
+  padding: 10px 18px;
+  cursor: pointer;
+  transition: transform 0.2s ease, box-shadow 0.2s ease;
+}
+
+button:disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+button.primary {
+  background: var(--accent);
+  color: #121212;
+  font-weight: 600;
+  box-shadow: 0 14px 30px rgba(246, 139, 31, 0.3);
+}
+
+button.primary:hover:not(:disabled) {
+  transform: translateY(-1px);
+}
+
+button.ghost {
+  background: transparent;
+  border: 1px solid var(--border);
+  color: var(--text);
+}
+
+button.ghost.full {
+  width: 100%;
+}
+
+.sidebar {
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+}
+
+.card {
+  background: var(--panel);
+  border-radius: 24px;
+  padding: 20px;
+  border: 1px solid var(--border);
+  box-shadow: var(--shadow);
+}
+
+.card h3 {
+  margin-top: 0;
+}
+
+.card p {
+  color: var(--text-muted);
+}
+
+.metric {
+  display: flex;
+  justify-content: space-between;
+  margin-top: 12px;
+  font-size: 0.9rem;
+}
+
+.badge-row {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 8px;
+}
+
+.badge-row span {
+  font-size: 0.75rem;
+  padding: 4px 10px;
+  border-radius: 999px;
+  border: 1px solid var(--border);
+  background: var(--bg-muted);
+}
+
+@media (max-width: 1024px) {
+  .layout {
+    grid-template-columns: 1fr;
+  }
+
+  .sidebar {
+    order: -1;
+  }
+}
+
+@media (max-width: 720px) {
+  .topbar {
+    flex-direction: column;
+    align-items: flex-start;
+    gap: 12px;
+  }
+
+  .layout {
+    padding: 20px;
+  }
+
+  .chat {
+    border-radius: 20px;
+  }
+}

frontend/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true
+  },
+  "include": ["src"]
+}

frontend/vite.config.ts

@@ -0,0 +1,16 @@
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+
+export default defineConfig({
+  plugins: [react()],
+  server: {
+    port: 5173,
+    proxy: {
+      "/api": "http://localhost:8080"
+    }
+  },
+  preview: {
+    host: "0.0.0.0",
+    port: 4173
+  }
+});

game/index.html

@@ -0,0 +1,63 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Star Courier</title>
+    <link rel="stylesheet" href="styles.css" />
+  </head>
+  <body>
+    <div class="app">
+      <header>
+        <div class="brand">
+          <span class="logo"></span>
+          <div>
+            <h1>Star Courier</h1>
+            <p>Thread the asteroid field, grab energy cells, and survive the surge.</p>
+          </div>
+        </div>
+        <div class="hud">
+          <div><span>Score</span><strong id="score">0</strong></div>
+          <div><span>Shield</span><strong id="shield">100</strong></div>
+          <div><span>Wave</span><strong id="wave">1</strong></div>
+        </div>
+      </header>
+
+      <main>
+        <div class="panel">
+          <canvas id="game" width="960" height="560"></canvas>
+          <div class="overlay" id="overlay">
+            <div class="card">
+              <h2 id="title">Ready?</h2>
+              <p id="subtitle">Use WASD or arrow keys to fly. Space = boost. Collect orbs, dodge rocks.</p>
+              <input id="pilot" placeholder="Pilot name" maxlength="14" />
+              <div class="row">
+                <button id="start">Start Run</button>
+                <button id="spectate" class="ghost">Spectate</button>
+              </div>
+              <small id="ws-status">Offline</small>
+            </div>
+          </div>
+        </div>
+        <aside>
+          <h3>Squad Roster</h3>
+          <div class="roster" id="roster"></div>
+          <h3>Controls</h3>
+          <ul>
+            <li><strong>Move</strong> WASD / Arrow keys</li>
+            <li><strong>Boost</strong> Space (drains shield)</li>
+            <li><strong>Pause</strong> P</li>
+          </ul>
+          <h3>Objective</h3>
+          <p>Survive as long as you can. Every 30 seconds, the field intensifies.</p>
+          <h3>Tips</h3>
+          <p>Boost through narrow gaps. Grab energy orbs to restore shield.</p>
+        </aside>
+      </main>
+      <footer>
+        Built for speed. No fluff.
+      </footer>
+    </div>
+    <script src="main.js"></script>
+  </body>
+</html>

game/main.js

@@ -0,0 +1,422 @@
+const canvas = document.getElementById("game");
+const ctx = canvas.getContext("2d");
+
+const scoreEl = document.getElementById("score");
+const shieldEl = document.getElementById("shield");
+const waveEl = document.getElementById("wave");
+const overlay = document.getElementById("overlay");
+const startBtn = document.getElementById("start");
+const spectateBtn = document.getElementById("spectate");
+const titleEl = document.getElementById("title");
+const subtitleEl = document.getElementById("subtitle");
+const pilotInput = document.getElementById("pilot");
+const rosterEl = document.getElementById("roster");
+const wsStatus = document.getElementById("ws-status");
+
+const state = {
+  running: false,
+  paused: false,
+  time: 0,
+  score: 0,
+  shield: 100,
+  wave: 1,
+  boost: false,
+  spectate: false,
+  player: {
+    x: canvas.width * 0.2,
+    y: canvas.height * 0.5,
+    vx: 0,
+    vy: 0,
+    radius: 16,
+    color: "#4ed1ff",
+    name: "Pilot"
+  },
+  asteroids: [],
+  orbs: [],
+  stars: [],
+  remotePlayers: new Map(),
+  socket: null,
+  playerId: null,
+  lastSend: 0
+};
+
+const keys = new Set();
+
+const connectSocket = () => {
+  const url = `ws://${window.location.host}`;
+  const socket = new WebSocket(url);
+  state.socket = socket;
+
+  socket.addEventListener("open", () => {
+    wsStatus.textContent = "Online";
+    socket.send(
+      JSON.stringify({
+        type: "join",
+        name: pilotInput.value.trim() || "Pilot"
+      })
+    );
+  });
+
+  socket.addEventListener("message", (event) => {
+    let message;
+    try {
+      message = JSON.parse(event.data);
+    } catch {
+      return;
+    }
+
+    if (message.type === "welcome") {
+      state.playerId = message.id;
+      state.player.color = message.color;
+      return;
+    }
+
+    if (message.type === "roster") {
+      state.remotePlayers.clear();
+      message.players.forEach((player) => {
+        if (player.id !== state.playerId) {
+          state.remotePlayers.set(player.id, player);
+        }
+      });
+      updateRoster(message.players);
+    }
+  });
+
+  socket.addEventListener("close", () => {
+    wsStatus.textContent = "Offline";
+    state.remotePlayers.clear();
+  });
+};
+
+const updateRoster = (players) => {
+  rosterEl.innerHTML = "";
+  players
+    .sort((a, b) => b.score - a.score)
+    .forEach((player) => {
+      const row = document.createElement("div");
+      row.className = "roster-item";
+      row.innerHTML = `
+        <div class="roster-left">
+          <span class="dot" style="background:${player.color}"></span>
+          <span>${player.name}</span>
+        </div>
+        <strong>${Math.floor(player.score)}</strong>
+      `;
+      rosterEl.appendChild(row);
+    });
+};
+
+const spawnStarField = () => {
+  state.stars = Array.from({ length: 120 }, () => ({
+    x: Math.random() * canvas.width,
+    y: Math.random() * canvas.height,
+    z: Math.random() * 1.8 + 0.2
+  }));
+};
+
+const resetGame = () => {
+  state.time = 0;
+  state.score = 0;
+  state.shield = 100;
+  state.wave = 1;
+  state.player.x = canvas.width * 0.2;
+  state.player.y = canvas.height * 0.5;
+  state.player.vx = 0;
+  state.player.vy = 0;
+  state.asteroids = [];
+  state.orbs = [];
+  spawnStarField();
+  updateHud();
+};
+
+const updateHud = () => {
+  scoreEl.textContent = Math.floor(state.score).toString();
+  shieldEl.textContent = Math.max(0, Math.floor(state.shield)).toString();
+  waveEl.textContent = state.wave.toString();
+};
+
+const spawnAsteroid = () => {
+  const size = 12 + Math.random() * 26;
+  state.asteroids.push({
+    x: canvas.width + size + Math.random() * 100,
+    y: Math.random() * canvas.height,
+    vx: -(2.8 + Math.random() * (1.4 + state.wave * 0.35)),
+    vy: (Math.random() - 0.5) * 1.5,
+    radius: size,
+    spin: Math.random() * 2
+  });
+};
+
+const spawnOrb = () => {
+  state.orbs.push({
+    x: canvas.width + 40 + Math.random() * 300,
+    y: 80 + Math.random() * (canvas.height - 160),
+    vx: -(2.2 + Math.random() * 1.2),
+    radius: 10 + Math.random() * 4
+  });
+};
+
+const applyInput = () => {
+  const accel = state.boost ? 0.5 : 0.28;
+  if (keys.has("ArrowUp") || keys.has("KeyW")) state.player.vy -= accel;
+  if (keys.has("ArrowDown") || keys.has("KeyS")) state.player.vy += accel;
+  if (keys.has("ArrowLeft") || keys.has("KeyA")) state.player.vx -= accel * 0.75;
+  if (keys.has("ArrowRight") || keys.has("KeyD")) state.player.vx += accel * 0.75;
+};
+
+const updatePlayer = () => {
+  state.player.vx *= 0.94;
+  state.player.vy *= 0.94;
+  state.player.x += state.player.vx;
+  state.player.y += state.player.vy;
+
+  if (state.player.x < 20) state.player.x = 20;
+  if (state.player.x > canvas.width - 20) state.player.x = canvas.width - 20;
+  if (state.player.y < 20) state.player.y = 20;
+  if (state.player.y > canvas.height - 20) state.player.y = canvas.height - 20;
+
+  if (state.boost) {
+    state.shield -= 0.2;
+  }
+};
+
+const updateEntities = () => {
+  state.asteroids.forEach((rock) => {
+    rock.x += rock.vx;
+    rock.y += rock.vy;
+  });
+  state.orbs.forEach((orb) => {
+    orb.x += orb.vx;
+  });
+
+  state.asteroids = state.asteroids.filter((rock) => rock.x > -80);
+  state.orbs = state.orbs.filter((orb) => orb.x > -40);
+};
+
+const handleCollisions = () => {
+  state.asteroids.forEach((rock) => {
+    const dx = rock.x - state.player.x;
+    const dy = rock.y - state.player.y;
+    const dist = Math.hypot(dx, dy);
+    if (dist < rock.radius + state.player.radius) {
+      state.shield -= 18 + Math.random() * 8;
+      rock.x += 120;
+      rock.y = Math.random() * canvas.height;
+    }
+  });
+
+  state.orbs = state.orbs.filter((orb) => {
+    const dx = orb.x - state.player.x;
+    const dy = orb.y - state.player.y;
+    const dist = Math.hypot(dx, dy);
+    if (dist < orb.radius + state.player.radius) {
+      state.shield = Math.min(100, state.shield + 20);
+      state.score += 120;
+      return false;
+    }
+    return true;
+  });
+};
+
+const updateWave = () => {
+  const nextWave = Math.floor(state.time / 30000) + 1;
+  if (nextWave !== state.wave) {
+    state.wave = nextWave;
+  }
+};
+
+const updateStars = () => {
+  state.stars.forEach((star) => {
+    star.x -= 0.5 + star.z * 1.2 + state.wave * 0.1;
+    if (star.x < -2) {
+      star.x = canvas.width + Math.random() * 60;
+      star.y = Math.random() * canvas.height;
+    }
+  });
+};
+
+const renderStars = () => {
+  ctx.fillStyle = "#06080f";
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+
+  state.stars.forEach((star) => {
+    ctx.fillStyle = `rgba(180, 210, 255, ${0.4 + star.z * 0.3})`;
+    ctx.fillRect(star.x, star.y, 2 * star.z, 2 * star.z);
+  });
+};
+
+const renderPlayer = () => {
+  ctx.save();
+  ctx.translate(state.player.x, state.player.y);
+  ctx.rotate(state.player.vy * 0.02);
+  ctx.fillStyle = state.player.color;
+  ctx.beginPath();
+  ctx.moveTo(18, 0);
+  ctx.lineTo(-12, 10);
+  ctx.lineTo(-8, 0);
+  ctx.lineTo(-12, -10);
+  ctx.closePath();
+  ctx.fill();
+
+  ctx.strokeStyle = "rgba(255,255,255,0.6)";
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  ctx.arc(2, 0, 12, 0, Math.PI * 2);
+  ctx.stroke();
+  ctx.restore();
+};
+
+const renderRemotePlayers = () => {
+  state.remotePlayers.forEach((player) => {
+    ctx.save();
+    ctx.translate(player.x, player.y);
+    ctx.fillStyle = player.color;
+    ctx.beginPath();
+    ctx.arc(0, 0, 12, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.restore();
+
+    ctx.fillStyle = "rgba(255,255,255,0.7)";
+    ctx.font = "12px Segoe UI";
+    ctx.fillText(player.name, player.x + 14, player.y - 14);
+  });
+};
+
+const renderAsteroids = () => {
+  ctx.strokeStyle = "rgba(255, 179, 71, 0.8)";
+  ctx.fillStyle = "rgba(255, 179, 71, 0.15)";
+  state.asteroids.forEach((rock) => {
+    ctx.beginPath();
+    ctx.arc(rock.x, rock.y, rock.radius, 0, Math.PI * 2);
+    ctx.fill();
+    ctx.stroke();
+  });
+};
+
+const renderOrbs = () => {
+  ctx.fillStyle = "rgba(78, 255, 179, 0.9)";
+  state.orbs.forEach((orb) => {
+    ctx.beginPath();
+    ctx.arc(orb.x, orb.y, orb.radius, 0, Math.PI * 2);
+    ctx.fill();
+  });
+};
+
+const renderBoostTrail = () => {
+  if (!state.boost) return;
+  ctx.strokeStyle = "rgba(78, 209, 255, 0.45)";
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  ctx.moveTo(state.player.x - 10, state.player.y);
+  ctx.lineTo(state.player.x - 40, state.player.y + Math.random() * 12 - 6);
+  ctx.stroke();
+};
+
+const renderShield = () => {
+  ctx.strokeStyle = `rgba(78, 209, 255, ${0.2 + state.shield / 220})`;
+  ctx.lineWidth = 3;
+  ctx.beginPath();
+  ctx.arc(state.player.x, state.player.y, state.player.radius + 6, 0, Math.PI * 2);
+  ctx.stroke();
+};
+
+const render = () => {
+  renderStars();
+  renderOrbs();
+  renderAsteroids();
+  renderBoostTrail();
+  renderShield();
+  renderPlayer();
+  renderRemotePlayers();
+};
+
+const sendState = (time) => {
+  if (!state.socket || state.socket.readyState !== 1) return;
+  if (time - state.lastSend < 60) return;
+  state.lastSend = time;
+
+  state.socket.send(
+    JSON.stringify({
+      type: "state",
+      x: state.player.x,
+      y: state.player.y,
+      score: state.score,
+      shield: state.shield,
+      wave: state.wave
+    })
+  );
+};
+
+const update = (delta, time) => {
+  if (!state.running || state.paused) return;
+
+  state.time += delta;
+  state.score += delta * 0.02 + state.wave * 0.15;
+  state.boost = !state.spectate && keys.has("Space") && state.shield > 5;
+
+  if (!state.spectate) {
+    applyInput();
+    updatePlayer();
+    handleCollisions();
+  }
+
+  updateEntities();
+  updateStars();
+  updateWave();
+
+  if (Math.random() < 0.03 + state.wave * 0.004) spawnAsteroid();
+  if (Math.random() < 0.008) spawnOrb();
+
+  if (state.shield <= 0 && !state.spectate) {
+    endGame();
+  }
+
+  updateHud();
+  sendState(time);
+};
+
+const endGame = () => {
+  state.running = false;
+  overlay.style.display = "grid";
+  titleEl.textContent = "Run Ended";
+  subtitleEl.textContent = `Final score: ${Math.floor(state.score)}. Hit Start to try again.`;
+};
+
+let lastFrame = performance.now();
+const loop = (time) => {
+  const delta = time - lastFrame;
+  lastFrame = time;
+  update(delta, time);
+  render();
+  requestAnimationFrame(loop);
+};
+
+const beginRun = (spectate) => {
+  state.spectate = spectate;
+  state.player.name = pilotInput.value.trim() || "Pilot";
+  resetGame();
+  state.running = true;
+  state.paused = false;
+  overlay.style.display = "none";
+};
+
+startBtn.addEventListener("click", () => beginRun(false));
+spectateBtn.addEventListener("click", () => beginRun(true));
+
+window.addEventListener("keydown", (event) => {
+  if (["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight", "Space"].includes(event.code)) {
+    event.preventDefault();
+  }
+  if (event.code === "KeyP") {
+    state.paused = !state.paused;
+  }
+  keys.add(event.code);
+});
+
+window.addEventListener("keyup", (event) => {
+  keys.delete(event.code);
+});
+
+spawnStarField();
+connectSocket();
+requestAnimationFrame(loop);

game/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "star-courier-multiplayer",
+  "version": "1.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node server.js"
+  },
+  "dependencies": {
+    "ws": "^8.17.1"
+  }
+}

game/server.js

@@ -0,0 +1,108 @@
+import http from "node:http";
+import fs from "node:fs";
+import path from "node:path";
+import { WebSocketServer } from "ws";
+
+const PORT = 8787;
+const ROOT = path.resolve(process.cwd());
+
+const server = http.createServer((req, res) => {
+  const url = req.url === "/" ? "/index.html" : req.url;
+  const filePath = path.join(ROOT, url);
+
+  fs.readFile(filePath, (err, data) => {
+    if (err) {
+      res.writeHead(404, { "Content-Type": "text/plain" });
+      res.end("Not found");
+      return;
+    }
+
+    const ext = path.extname(filePath);
+    const typeMap = {
+      ".html": "text/html",
+      ".css": "text/css",
+      ".js": "text/javascript"
+    };
+    res.writeHead(200, { "Content-Type": typeMap[ext] ?? "text/plain" });
+    res.end(data);
+  });
+});
+
+const wss = new WebSocketServer({ server });
+
+const palette = ["#4ed1ff", "#ffb347", "#7cff6b", "#ff6be5", "#9f8bff", "#ffd86b"];
+let paletteIndex = 0;
+
+const players = new Map();
+
+const broadcast = (payload) => {
+  const message = JSON.stringify(payload);
+  for (const client of wss.clients) {
+    if (client.readyState === 1) {
+      client.send(message);
+    }
+  }
+};
+
+wss.on("connection", (socket) => {
+  let playerId = null;
+
+  socket.on("message", (data) => {
+    let message;
+    try {
+      message = JSON.parse(data.toString());
+    } catch {
+      return;
+    }
+
+    if (message.type === "join") {
+      playerId = `p_${Math.random().toString(36).slice(2, 9)}`;
+      const color = palette[paletteIndex % palette.length];
+      paletteIndex += 1;
+      const name = String(message.name || "Pilot").slice(0, 14);
+      players.set(playerId, {
+        id: playerId,
+        name,
+        color,
+        x: 0,
+        y: 0,
+        score: 0,
+        shield: 100,
+        wave: 1,
+        lastSeen: Date.now()
+      });
+      socket.send(JSON.stringify({ type: "welcome", id: playerId, color }));
+      return;
+    }
+
+    if (message.type === "state" && playerId && players.has(playerId)) {
+      const player = players.get(playerId);
+      player.x = message.x;
+      player.y = message.y;
+      player.score = message.score;
+      player.shield = message.shield;
+      player.wave = message.wave;
+      player.lastSeen = Date.now();
+    }
+  });
+
+  socket.on("close", () => {
+    if (playerId) {
+      players.delete(playerId);
+    }
+  });
+});
+
+setInterval(() => {
+  const now = Date.now();
+  for (const [id, player] of players.entries()) {
+    if (now - player.lastSeen > 8000) {
+      players.delete(id);
+    }
+  }
+  broadcast({ type: "roster", players: Array.from(players.values()) });
+}, 120);
+
+server.listen(PORT, () => {
+  console.log(`Star Courier running on http://localhost:${PORT}`);
+});

game/styles.css

@@ -0,0 +1,242 @@
+:root {
+  --bg: #0a0d14;
+  --panel: #121826;
+  --accent: #4ed1ff;
+  --accent-2: #ffb347;
+  --text: #f5f7ff;
+  --muted: #9ba7c7;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: "Segoe UI", system-ui, sans-serif;
+  background: radial-gradient(circle at 20% 20%, rgba(78, 209, 255, 0.12), transparent 50%),
+    radial-gradient(circle at 80% 20%, rgba(255, 179, 71, 0.1), transparent 45%),
+    var(--bg);
+  color: var(--text);
+}
+
+.app {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+  gap: 20px;
+  padding: 24px 28px 32px;
+}
+
+header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 24px;
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.logo {
+  width: 48px;
+  height: 48px;
+  border-radius: 14px;
+  background: linear-gradient(135deg, var(--accent), #6af1ff);
+  box-shadow: 0 12px 30px rgba(78, 209, 255, 0.35);
+}
+
+.brand h1 {
+  margin: 0;
+  font-size: 1.5rem;
+}
+
+.brand p {
+  margin: 4px 0 0;
+  color: var(--muted);
+}
+
+.hud {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(90px, 1fr));
+  gap: 16px;
+}
+
+.hud div {
+  background: var(--panel);
+  padding: 10px 14px;
+  border-radius: 12px;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+.hud span {
+  font-size: 0.7rem;
+  text-transform: uppercase;
+  color: var(--muted);
+  letter-spacing: 0.08em;
+}
+
+.hud strong {
+  font-size: 1.1rem;
+}
+
+main {
+  display: grid;
+  grid-template-columns: 1fr 280px;
+  gap: 24px;
+  flex: 1;
+}
+
+.panel {
+  position: relative;
+  background: var(--panel);
+  border-radius: 24px;
+  padding: 16px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  box-shadow: 0 25px 50px rgba(0, 0, 0, 0.4);
+}
+
+canvas {
+  width: 100%;
+  height: auto;
+  border-radius: 16px;
+  background: #06080f;
+  display: block;
+}
+
+.overlay {
+  position: absolute;
+  inset: 16px;
+  display: grid;
+  place-items: center;
+  background: rgba(6, 8, 15, 0.75);
+  border-radius: 16px;
+}
+
+.card {
+  background: rgba(18, 24, 38, 0.95);
+  padding: 24px 32px;
+  border-radius: 18px;
+  text-align: center;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  display: grid;
+  gap: 12px;
+}
+
+.card h2 {
+  margin: 0;
+  font-size: 1.6rem;
+}
+
+.card p {
+  margin: 0;
+  color: var(--muted);
+}
+
+.card input {
+  border: 1px solid rgba(255, 255, 255, 0.1);
+  border-radius: 10px;
+  background: rgba(9, 12, 20, 0.8);
+  padding: 10px 12px;
+  color: var(--text);
+}
+
+.card small {
+  color: var(--muted);
+}
+
+.row {
+  display: flex;
+  gap: 10px;
+  justify-content: center;
+}
+
+button {
+  border: none;
+  background: var(--accent);
+  color: #041018;
+  font-weight: 600;
+  padding: 10px 18px;
+  border-radius: 10px;
+  cursor: pointer;
+}
+
+button.ghost {
+  background: transparent;
+  border: 1px solid rgba(255, 255, 255, 0.12);
+  color: var(--text);
+}
+
+aside {
+  background: var(--panel);
+  padding: 18px 20px;
+  border-radius: 20px;
+  border: 1px solid rgba(255, 255, 255, 0.08);
+  color: var(--muted);
+  display: flex;
+  flex-direction: column;
+  gap: 16px;
+}
+
+aside h3 {
+  color: var(--text);
+  margin: 0;
+}
+
+aside ul {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+aside li strong {
+  color: var(--text);
+  margin-right: 6px;
+}
+
+.roster {
+  display: grid;
+  gap: 8px;
+}
+
+.roster-item {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  padding: 8px 10px;
+  border-radius: 10px;
+  background: rgba(255, 255, 255, 0.05);
+  border: 1px solid rgba(255, 255, 255, 0.08);
+}
+
+.roster-left {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+}
+
+footer {
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+@media (max-width: 960px) {
+  main {
+    grid-template-columns: 1fr;
+  }
+}

upload_and_test.py

@@ -0,0 +1,38 @@
+import os
+from huggingface_hub import login, upload_folder
+from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
+
+# -------------------------------
+# 1️⃣ Login safely
+# -------------------------------
+# Use environment variable for your token
+token = os.environ.get("HF_TOKEN")
+if not token:
+    token = input("Enter your Hugging Face token (won't be saved): ")
+login(token=token)
+
+# -------------------------------
+# 2️⃣ Upload the model folder
+# -------------------------------
+# This folder should contain pytorch_model.bin, config.json, tokenizer.json
+upload_folder(
+    folder_path=".",  # current folder
+    repo_id="picklefried706/NEON",  # your HF repo
+    repo_type="model"
+)
+print("✅ Upload complete!")
+
+# -------------------------------
+# 3️⃣ Test your model
+# -------------------------------
+model_name = "picklefried706/NEON"
+
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForCausalLM.from_pretrained(model_name, device_map="auto")
+
+chat = pipeline("text-generation", model=model, tokenizer=tokenizer)
+
+prompt = "User: Hello! How are you?\nAssistant:"
+response = chat(prompt, max_new_tokens=150)
+print("\n--- Model Response ---")
+print(response[0]['generated_text'])