Diagnose setup by what is certain, and deliver errors the way the client asked

Review of the branch found the persona diagnosis was mostly truncation
wearing a name tag. The <.> marker sits at the start of the system
message and the persona marker after the card, so a card Janitor cut
short arrives with the prompt present and the persona gone — and was
told its persona was wrong, with truncation as an afterthought. The
original message was only ever about context size, which is the best
evidence there is about what actually happens.

diagnoseSetup() now says only what the markers make certain. A missing
<.> is a missing prompt, since truncation cannot remove the first three
characters. A persona marker that is present but not "." is a wrong
description, quoted back so there is nothing to guess. A persona marker
that is gone, or cut off mid-tag, leads with truncation and mentions the
persona second.

The error path decided "streaming?" from the Accept header while the
success path used body.stream, so a client that sent stream:true without
that header got JSON back for every error and never displayed it. The
flag is hoisted above the try; the header is only a fallback for when
the body could not be read.

Token search is restricted to after the greeting, in order. A card built
from a sucker-proxied chat could carry an expired token in its text, and
a lookup on it would fail forever. Conversation order also means the
token a chat was started with always wins over one pasted later. The
system fallback now takes a role-less first message only; a request with
roles but no system turn is reported as such rather than misdiagnosed as
a missing prompt. The echo feature reads the parser's lastUser instead of
its own case-sensitive lookup. "Nothing was saved" is dropped from the
unknown-error message, since it is not guaranteed.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NX2SsmUqQftWTZAY4BDuFa

.env.example

@@ -0,0 +1,5 @@
+# Environment Variables for Sucker
+
+# Disable Discord community banner (optional)
+# Uncomment the line below to hide the Discord banner
+# NEXT_PUBLIC_DISABLE_DISCORD_BANNER=true

.github/copilot-instructions.md

@@ -0,0 +1,47 @@
+# Copilot Instructions for sucker.severian.dev
+
+## Project Overview
+- This is a Next.js project with a custom proxy API and UI components, using Tailwind CSS and PostCSS for styling.
+- The main app logic is in `src/app/`, with global styles in `globals.css` and layout in `layout.tsx`.
+- API routes are under `src/app/api/proxy/`, including image proxying (`image/route.ts`).
+- UI components are in `src/components/ui/` and utility functions in `src/components/lib/`.
+
+## Architecture & Data Flow
+- The app uses Next.js routing and API routes for backend logic. The proxy API handles requests to external services, including image fetching and transformation.
+- UI components follow a modular pattern, with reusable elements (e.g., `button.tsx`, `card.tsx`).
+- Data flows from API routes to UI via React props and hooks. No global state management library is present.
+
+## Developer Workflows
+- **Build & Dev:** Use `npm run dev` to start the development server. Check `package.json` for other scripts.
+- **Styling:** Tailwind CSS is configured via `tailwind.config.js` and PostCSS via `postcss.config.js`.
+- **API:** Custom logic for proxying and image handling is in `src/app/api/proxy/`. Review these files for request/response patterns.
+- **No test suite detected.** If adding tests, follow Next.js and React conventions.
+
+## Project-Specific Conventions
+- API routes use Next.js `route.ts` files, with custom logic for proxying and image manipulation.
+- UI components are colocated in `src/components/ui/` and use Tailwind utility classes.
+- Utility functions (e.g., PNG handling) are in `src/components/lib/`.
+- Minimal documentation; refer to code for implementation details.
+- Changelog is maintained in `README.md`.
+
+## Integration Points & External Dependencies
+- Relies on Next.js, React, Tailwind CSS, and PostCSS.
+- External requests are proxied via custom API routes.
+- Docker support via `docker-compose.yml` and `dockerfile` for containerization.
+
+## Examples
+- To add a new API route: create a `route.ts` under `src/app/api/yourroute/`.
+- To add a new UI component: place a `.tsx` file in `src/components/ui/` and use Tailwind for styling.
+- For image processing, review `src/app/api/proxy/image/route.ts` and `src/components/lib/png.ts`.
+
+## Key Files & Directories
+- `src/app/` — Main app logic and API routes
+- `src/components/ui/` — UI components
+- `src/components/lib/` — Utility functions
+- `tailwind.config.js`, `postcss.config.js` — Styling configuration
+- `docker-compose.yml`, `dockerfile` — Containerization
+- `README.md` — Changelog and minimal project notes
+
+---
+
+If any section is unclear or missing important project-specific details, please provide feedback to improve these instructions.

.gitignore

@@ -1,2 +1,4 @@
 node_modules
 .next
+.env.local
+.env*.local

README.md

@@ -1,10 +1,29 @@
 # Sucker
 
-Check package.json for commands, I can't be bothered.
+### Environment Variables
+
+Add these to your `.env.local` file (optional):
+
+```bash
+# Disable Discord community banner (defaults to showing banner)
+NEXT_PUBLIC_DISABLE_DISCORD_BANNER=true
+```
+
+### Usage
+
+Pull this repostory and build with `npm run build`. You can start the server with `node ./.next/standalone/server.js`
+
+You can also build and run Sucker as a Docker container with `docker compose build` and `docker compose up`.
 
 ### Changelog
 
-- 2.0: Multimessage support! Tracks changes to character descriptions and scenarios across multiple extractions. Shows version badges, message counts, and provides detailed change history viewer.
+- 2.5: Real error messages instead of one blanket "dingus" reply; unexplained failures now ask you to DM @lyseverian. Unread dot on the Changelog button. Fixed extraction for users whose Janitor sends a request without the blank turn before the first message — sucker read the parts by position rather than by role, so for them it read the wrong ones and errored. Now resolved by role, with tests for both shapes.
+- 2.4: CSS editor for Janitor profiles. New banner links to the live-preview editor at tools.from-avalon.com/janitor-profile-maker.
+- 2.3: ECHO. Put ECHO: anywhere in a message and sucker repeats whatever comes after it in the reply — for triggering char-side script and lorebook keywords.
+- 2.2: Added support for directly inputting webp file names or character image links when creating PNG character cards
+- 2.1: updated deps, note about image fetching, list of mirrors
+- 2.0: from Tui: Multimessage support! Tracks changes to character descriptions and scenarios across multiple extractions. Shows version badges, message counts, and provides detailed change history viewer.
+- also 2.0: V2 charcard format and alternate greetings.
 - 1.9: Not again. They changed stuff again. What is this?
 - 1.8: Handling for new prompt structure, new instructions
 - 1.7: Handling for nested XML character tags

cardextractor_severian_dev.ipynb

@@ -1,290 +0,0 @@
-{
-  "cells": [
-    {
-      "cell_type": "markdown",
-      "metadata": {
-        "id": "zMVSOtXUASM8"
-      },
-      "source": [
-        "## **Card Definition Extractor**\n",
-        "\n",
-        "Standalone version with directions: https://sucker.severian.dev\n",
-        "\n",
-        "I've gotten into making models at [trashpanda-org](https://huggingface.co/trashpanda-org), check out hasnonname's [Mullein](https://huggingface.co/trashpanda-org/MS-24B-Mullein-v0)!\n",
-        "\n",
-        "> _lmk on Discord if you have any issues while using this - Severian_\n",
-        "\n",
-        "---\n",
-        "\n",
-        "**Changelog:**\n",
-        "- v0.2: fixed to handle Janitor making changes due to R1 handling.\n"
-      ]
-    },
-    {
-      "cell_type": "code",
-      "execution_count": null,
-      "metadata": {
-        "colab": {
-          "background_save": true,
-          "base_uri": "https://localhost:8080/"
-        },
-        "id": "a0pFE9KCDh8P",
-        "outputId": "d647688d-e541-4e5f-e13d-4b385ee84d8b"
-      },
-      "outputs": [
-        {
-          "name": "stdout",
-          "output_type": "stream",
-          "text": [
-            "Requirement already satisfied: flask-cors in /usr/local/lib/python3.11/dist-packages (5.0.0)\n",
-            "Requirement already satisfied: Flask>=0.9 in /usr/local/lib/python3.11/dist-packages (from flask-cors) (3.1.0)\n",
-            "Requirement already satisfied: Werkzeug>=3.1 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (3.1.3)\n",
-            "Requirement already satisfied: Jinja2>=3.1.2 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (3.1.5)\n",
-            "Requirement already satisfied: itsdangerous>=2.2 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (2.2.0)\n",
-            "Requirement already satisfied: click>=8.1.3 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (8.1.8)\n",
-            "Requirement already satisfied: blinker>=1.9 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (1.9.0)\n",
-            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.11/dist-packages (from Jinja2>=3.1.2->Flask>=0.9->flask-cors) (3.0.2)\n",
-            "Requirement already satisfied: flask-cors in /usr/local/lib/python3.11/dist-packages (5.0.0)\n",
-            "Requirement already satisfied: flask_cloudflared in /usr/local/lib/python3.11/dist-packages (0.0.14)\n",
-            "Requirement already satisfied: Flask>=0.9 in /usr/local/lib/python3.11/dist-packages (from flask-cors) (3.1.0)\n",
-            "Requirement already satisfied: requests in /usr/local/lib/python3.11/dist-packages (from flask_cloudflared) (2.32.3)\n",
-            "Requirement already satisfied: Werkzeug>=3.1 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (3.1.3)\n",
-            "Requirement already satisfied: Jinja2>=3.1.2 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (3.1.5)\n",
-            "Requirement already satisfied: itsdangerous>=2.2 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (2.2.0)\n",
-            "Requirement already satisfied: click>=8.1.3 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (8.1.8)\n",
-            "Requirement already satisfied: blinker>=1.9 in /usr/local/lib/python3.11/dist-packages (from Flask>=0.9->flask-cors) (1.9.0)\n",
-            "Requirement already satisfied: charset-normalizer<4,>=2 in /usr/local/lib/python3.11/dist-packages (from requests->flask_cloudflared) (3.4.1)\n",
-            "Requirement already satisfied: idna<4,>=2.5 in /usr/local/lib/python3.11/dist-packages (from requests->flask_cloudflared) (3.10)\n",
-            "Requirement already satisfied: urllib3<3,>=1.21.1 in /usr/local/lib/python3.11/dist-packages (from requests->flask_cloudflared) (2.3.0)\n",
-            "Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.11/dist-packages (from requests->flask_cloudflared) (2024.12.14)\n",
-            "Requirement already satisfied: MarkupSafe>=2.0 in /usr/local/lib/python3.11/dist-packages (from Jinja2>=3.1.2->Flask>=0.9->flask-cors) (3.0.2)\n",
-            " * Serving Flask app '__main__'\n",
-            " * Debug mode: off\n"
-          ]
-        },
-        {
-          "name": "stderr",
-          "output_type": "stream",
-          "text": [
-            "INFO:werkzeug:\u001b[31m\u001b[1mWARNING: This is a development server. Do not use it in a production deployment. Use a production WSGI server instead.\u001b[0m\n",
-            " * Running on http://127.0.0.1:5000\n",
-            "INFO:werkzeug:\u001b[33mPress CTRL+C to quit\u001b[0m\n"
-          ]
-        },
-        {
-          "name": "stdout",
-          "output_type": "stream",
-          "text": [
-            " * Running on https://little-disputes-posting-palmer.trycloudflare.com\n",
-            " * Traffic stats available on http://127.0.0.1:8396/metrics\n"
-          ]
-        },
-        {
-          "name": "stderr",
-          "output_type": "stream",
-          "text": [
-            "INFO:werkzeug:127.0.0.1 - - [04/Feb/2025 22:53:13] \"OPTIONS / HTTP/1.1\" 200 -\n"
-          ]
-        },
-        {
-          "name": "stdout",
-          "output_type": "stream",
-          "text": [
-            "Card definition JSON created at: /tmp/tmpynlda8kv.json\n"
-          ]
-        },
-        {
-          "data": {
-            "application/javascript": "\n    async function download(id, filename, size) {\n      if (!google.colab.kernel.accessAllowed) {\n        return;\n      }\n      const div = document.createElement('div');\n      const label = document.createElement('label');\n      label.textContent = `Downloading \"${filename}\": `;\n      div.appendChild(label);\n      const progress = document.createElement('progress');\n      progress.max = size;\n      div.appendChild(progress);\n      document.body.appendChild(div);\n\n      const buffers = [];\n      let downloaded = 0;\n\n      const channel = await google.colab.kernel.comms.open(id);\n      // Send a message to notify the kernel that we're ready.\n      channel.send({})\n\n      for await (const message of channel.messages) {\n        // Send a message to notify the kernel that we're ready.\n        channel.send({})\n        if (message.buffers) {\n          for (const buffer of message.buffers) {\n            buffers.push(buffer);\n            downloaded += buffer.byteLength;\n            progress.value = downloaded;\n          }\n        }\n      }\n      const blob = new Blob(buffers, {type: 'application/binary'});\n      const a = document.createElement('a');\n      a.href = window.URL.createObjectURL(blob);\n      a.download = filename;\n      div.appendChild(a);\n      a.click();\n      div.remove();\n    }\n  ",
-            "text/plain": [
-              "<IPython.core.display.Javascript object>"
-            ]
-          },
-          "metadata": {},
-          "output_type": "display_data"
-        },
-        {
-          "data": {
-            "application/javascript": "download(\"download_8462ad82-aca0-40a4-8cbb-0342ff5a7e1c\", \"tmpynlda8kv.json\", 14791)",
-            "text/plain": [
-              "<IPython.core.display.Javascript object>"
-            ]
-          },
-          "metadata": {},
-          "output_type": "display_data"
-        },
-        {
-          "name": "stderr",
-          "output_type": "stream",
-          "text": [
-            "INFO:werkzeug:127.0.0.1 - - [04/Feb/2025 22:53:14] \"POST / HTTP/1.1\" 200 -\n"
-          ]
-        }
-      ],
-      "source": [
-        "# @title Card Definition Extractor\n",
-        "\n",
-        "# @markdown Directions for use:\n",
-        "# @markdown - If enabled, starts the proxy in character card extraction mode.\n",
-        "# @markdown - Use the proxy as normal, and start a new chat with your character of choice.\n",
-        "# @markdown - After sending the first message, the proxy will process the character card in v1 format\n",
-        "# @markdown - Stop the proxy and Colab will download the JSON file on your device\n",
-        "# @markdown - Your custom prompt will appear on the description field so this is best used with a cleared-out custom prompt section on janitor.ai\n",
-        "# @markdown - You can start multiple new chats and send messages for the extractor to capture cards, and when you stop the notebook, it will download all extracted files at once.\n",
-        "\n",
-        "# @markdown **Select Tunnel Provider**\n",
-        "tunnel_provider = \"Cloudflare\"  # @param [\"Cloudflare\", \"Localtunnel\", \"Ngrok\"]\n",
-        "\n",
-        "# @markdown **Ngrok Auth Token**: If using ngrok, sign up for an auth token at https://dashboard.ngrok.com/signup\n",
-        "ngrok_auth_token = \"\"  # @param {type:\"string\"}\n",
-        "\n",
-        "card_definition_extractor = True\n",
-        "!pip install flask-cors\n",
-        "\n",
-        "import json\n",
-        "import requests\n",
-        "import time\n",
-        "from flask import Flask, request, jsonify\n",
-        "from flask_cors import CORS\n",
-        "import re\n",
-        "import tempfile\n",
-        "import os\n",
-        "\n",
-        "app = Flask(__name__)\n",
-        "CORS(app)\n",
-        "\n",
-        "# Depending on the provider, set up the tunnel\n",
-        "if tunnel_provider == \"Cloudflare\":\n",
-        "    !pip install flask-cors flask_cloudflared\n",
-        "    from flask_cloudflared import run_with_cloudflared\n",
-        "    run_with_cloudflared(app)\n",
-        "elif tunnel_provider == \"Localtunnel\":\n",
-        "    !pip install flask-cors flask_localtunnel\n",
-        "    from flask_lt import run_with_lt\n",
-        "    run_with_lt(app)\n",
-        "elif tunnel_provider == \"Ngrok\":\n",
-        "    !pip install flask-cors pyngrok==7.1.2\n",
-        "    from pyngrok import ngrok\n",
-        "    if ngrok_auth_token.strip():\n",
-        "        ngrok.set_auth_token(ngrok_auth_token.strip())\n",
-        "    public_url = ngrok.connect(5000).public_url\n",
-        "    print(\"Public URL:\", public_url)\n",
-        "\n",
-        "def extract_between_tags(content, tag):\n",
-        "    \"\"\"\n",
-        "    Extracts content between XML-like tags.\n",
-        "    Returns empty string if tag not found.\n",
-        "    \"\"\"\n",
-        "    start_tag = f\"<{tag}>\"\n",
-        "    end_tag = f\"</{tag}>\"\n",
-        "    start_idx = content.find(start_tag)\n",
-        "    if start_idx == -1:\n",
-        "        return \"\"\n",
-        "    \n",
-        "    end_idx = content.find(end_tag, start_idx)\n",
-        "    if end_idx == -1:\n",
-        "        return \"\"\n",
-        "    \n",
-        "    return content[start_idx + len(start_tag):end_idx].strip()\n",
-        "\n",
-        "def find_tags_between(content, start_marker, end_marker):\n",
-        "    \"\"\"\n",
-        "    Finds all XML-like tags and their content between two marker tags.\n",
-        "    Returns list of {tag, content} dictionaries.\n",
-        "    \"\"\"\n",
-        "    start_idx = content.find(f\"<{start_marker}>\")\n",
-        "    if start_idx == -1:\n",
-        "        return []\n",
-        "    \n",
-        "    end_idx = content.find(f\"<{end_marker}>\")\n",
-        "    if end_idx == -1:\n",
-        "        return []\n",
-        "    \n",
-        "    section = content[start_idx + len(start_marker) + 2:end_idx]\n",
-        "    tag_regex = r\"<([^/>]+)>([^<]+)</\\1>\"\n",
-        "    matches = re.finditer(tag_regex, section)\n",
-        "    \n",
-        "    return [{\"tag\": match.group(1), \"content\": match.group(2).strip()} for match in matches]\n",
-        "\n",
-        "def extract_card_data(messages):\n",
-        "    content0 = messages[0][\"content\"]\n",
-        "    content1 = messages[2][\"content\"]\n",
-        "\n",
-        "    # Find all persona tags between system and scenario, take the last one as character\n",
-        "    personas = find_tags_between(content0, \"system\", \"scenario\")\n",
-        "    char_persona = personas[-1] if personas else {\"tag\": \"\", \"content\": \"\"}\n",
-        "    char_name = char_persona[\"tag\"]\n",
-        "\n",
-        "    card_data = {\n",
-        "        \"name\": char_name,\n",
-        "        \"description\": char_persona[\"content\"],\n",
-        "        \"scenario\": extract_between_tags(content0, \"scenario\"),\n",
-        "        \"mes_example\": extract_between_tags(content0, \"example_dialogs\"),\n",
-        "        \"personality\": \"\",  # This field isn't used in the new format\n",
-        "        \"first_mes\": content1\n",
-        "    }\n",
-        "\n",
-        "    # Replace character name with placeholder in all fields\n",
-        "    def safe_replace(text, old, new):\n",
-        "        return text.replace(old, new) if old else text\n",
-        "\n",
-        "    for field in card_data:\n",
-        "        if field != \"name\":  # Exclude the \"name\" field\n",
-        "            val = card_data[field]\n",
-        "            val = safe_replace(val, char_name, \"{{char}}\")\n",
-        "            card_data[field] = val\n",
-        "\n",
-        "    return card_data\n",
-        "\n",
-        "@app.route('/', methods=['GET'])\n",
-        "def default():\n",
-        "    return {\"status\": \"online\"}\n",
-        "\n",
-        "@app.route('/', methods=['POST'])\n",
-        "def process_card():\n",
-        "    body = request.json\n",
-        "    if 'messages' not in body:\n",
-        "        return jsonify(error=\"Missing 'messages' in request body\"), 400\n",
-        "\n",
-        "    if card_definition_extractor and len(body[\"messages\"]) >= 2:\n",
-        "        card_data = extract_card_data(body[\"messages\"])\n",
-        "        # If running in Colab, download the file\n",
-        "        try:\n",
-        "            from google.colab import files\n",
-        "            import tempfile\n",
-        "            temp_json = tempfile.NamedTemporaryFile(delete=False, suffix=\".json\")\n",
-        "            with open(temp_json.name, 'w', encoding='utf-8') as f:\n",
-        "                json.dump(card_data, f, ensure_ascii=False, indent=2)\n",
-        "            print(\"Card definition JSON created at:\", temp_json.name)\n",
-        "            files.download(temp_json.name)\n",
-        "        except ImportError:\n",
-        "            pass  # Not in Colab, just return JSON\n",
-        "\n",
-        "        return jsonify(card_data), 200\n",
-        "    else:\n",
-        "        return jsonify(status=\"Card definition extractor not enabled or insufficient messages\"), 200\n",
-        "\n",
-        "if __name__ == '__main__':\n",
-        "    if tunnel_provider != \"Cloudflare\":\n",
-        "        print('\\n Colab IP: ', end='')\n",
-        "        !curl ipecho.net/plain\n",
-        "        print('\\n')\n",
-        "    app.run()\n"
-      ]
-    }
-  ],
-  "metadata": {
-    "colab": {
-      "provenance": []
-    },
-    "kernelspec": {
-      "display_name": "Python 3",
-      "name": "python3"
-    },
-    "language_info": {
-      "name": "python"
-    }
-  },
-  "nbformat": 4,
-  "nbformat_minor": 0
-}

docker-compose.yml

@@ -0,0 +1,7 @@
+services:
+  web:
+    build: .
+    image: sucker
+    restart: unless-stopped
+    ports:
+      - "3000:3000"

dockerfile

@@ -0,0 +1,31 @@
+FROM node:22-alpine AS base
+WORKDIR /app
+FROM base AS deps
+COPY package.json package-lock.json* yarn.lock* pnpm-lock.yaml* ./
+RUN \
+  if [ -f package-lock.json ]; then npm ci; \
+  elif [ -f yarn.lock ]; then yarn install --frozen-lockfile; \
+  elif [ -f pnpm-lock.yaml ]; then npm install -g pnpm && pnpm install --frozen-lockfile; \
+  else echo "No lockfile found." && npm install; \
+  fi
+
+FROM base AS builder
+WORKDIR /app
+
+ENV NODE_ENV=production
+
+COPY --from=deps /app/node_modules ./node_modules
+COPY . .
+RUN npm run build
+
+FROM node:22-alpine AS runner
+WORKDIR /app
+RUN addgroup --system --gid 1001 nodejs && adduser --system --uid 1001 nextjs
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+
+USER nextjs
+
+EXPOSE 3000
+CMD ["node", "server.js"]

next-env.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="next" />
 /// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

next.config.js

@@ -0,0 +1,7 @@
+/** @type {import('next').NextConfig} */
+const nextConfig = {
+  output: 'standalone',
+  productionBrowserSourceMaps: false,
+};
+
+module.exports = nextConfig;

package.json

@@ -6,16 +6,18 @@
     "dev": "next dev",
     "build": "next build",
     "start": "next start",
-    "lint": "next lint"
+    "lint": "next lint",
+    "test": "node --experimental-strip-types --test \"tests/**/*.test.ts\""
   },
   "dependencies": {
     "@radix-ui/react-accordion": "^1.2.2",
     "@radix-ui/react-collapsible": "^1.1.2",
     "@radix-ui/react-dialog": "^1.1.4",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-separator": "^1.1.1",
     "@radix-ui/react-slot": "^1.1.1",
-    "@types/react": "^18.2.39",
+    "@types/react": "^19.2.7",
-    "@types/react-dom": "^18.2.17",
+    "@types/react-dom": "^19.2.3",
     "axios": "^1.6.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -23,9 +25,9 @@
     "crc-32": "^1.2.2",
     "html2canvas": "^1.4.1",
     "lucide-react": "^0.471.0",
-    "next": "^14.0.3",
+    "next": "^16.0.7",
-    "react": "^18.2.0",
+    "react": "^19.2.1",
-    "react-dom": "^18.2.0",
+    "react-dom": "^19.2.1",
     "tailwind-merge": "^2.6.0",
     "tailwindcss-animate": "^1.0.7",
     "typescript": "^5.3.2"

src/components/ui/banner-carousel.tsx

@@ -0,0 +1,85 @@
+"use client";
+
+import { useState, useEffect, ReactNode } from "react";
+import { ChevronLeft, ChevronRight } from "lucide-react";
+
+interface BannerCarouselProps {
+  slides: ReactNode[];
+  intervalMs?: number;
+  className?: string;
+}
+
+export function BannerCarousel({
+  slides,
+  intervalMs = 8000,
+  className = "",
+}: BannerCarouselProps) {
+  const [index, setIndex] = useState(0);
+
+  // Pick a random starting slide on the client to avoid hydration mismatch
+  useEffect(() => {
+    setIndex(Math.floor(Math.random() * slides.length));
+  }, [slides.length]);
+
+  // Re-keyed on index so a manual change restarts the countdown
+  useEffect(() => {
+    const id = setTimeout(
+      () => setIndex((i) => (i + 1) % slides.length),
+      intervalMs
+    );
+    return () => clearTimeout(id);
+  }, [index, intervalMs, slides.length]);
+
+  const go = (delta: number) =>
+    setIndex((i) => (i + delta + slides.length) % slides.length);
+
+  return (
+    <div className={`relative ${className}`}>
+      {/* Slides stacked in one grid cell so the container fits the tallest */}
+      <div className="grid">
+        {slides.map((slide, i) => (
+          <div
+            key={i}
+            className={`[grid-area:1/1] transition-opacity duration-500 ${
+              i === index ? "opacity-100" : "opacity-0 pointer-events-none"
+            }`}
+            aria-hidden={i !== index}
+          >
+            {slide}
+          </div>
+        ))}
+      </div>
+
+      <button
+        type="button"
+        onClick={() => go(-1)}
+        aria-label="Previous banner"
+        className="absolute left-1.5 top-1/2 -translate-y-1/2 rounded-full bg-black/50 hover:bg-black/70 text-white p-1 transition-colors"
+      >
+        <ChevronLeft className="h-4 w-4" />
+      </button>
+      <button
+        type="button"
+        onClick={() => go(1)}
+        aria-label="Next banner"
+        className="absolute right-1.5 top-1/2 -translate-y-1/2 rounded-full bg-black/50 hover:bg-black/70 text-white p-1 transition-colors"
+      >
+        <ChevronRight className="h-4 w-4" />
+      </button>
+
+      <div className="absolute bottom-2 left-1/2 -translate-x-1/2 flex gap-1.5">
+        {slides.map((_, i) => (
+          <button
+            key={i}
+            type="button"
+            onClick={() => setIndex(i)}
+            aria-label={`Show banner ${i + 1}`}
+            className={`h-1.5 rounded-full transition-all ${
+              i === index ? "w-4 bg-white" : "w-1.5 bg-white/50"
+            }`}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

src/components/ui/css-editor-banner.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { useEffect, useRef } from "react";
+
+interface CssEditorBannerProps {
+  href?: string;
+  className?: string;
+  /** "contain" letterboxes the video so its caption is never cropped */
+  fit?: "cover" | "contain";
+}
+
+export function CssEditorBanner({
+  href = "https://tools.from-avalon.com/janitor-profile-maker/",
+  className = "",
+  fit = "cover",
+}: CssEditorBannerProps) {
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+
+  // Browsers like Opera GX overlay pop-out controls on large <video> elements.
+  // The real video stays 1px and invisible; its frames are painted onto a canvas.
+  useEffect(() => {
+    const video = videoRef.current;
+    const canvas = canvasRef.current;
+    const ctx = canvas?.getContext("2d");
+    if (!video || !canvas || !ctx) return;
+
+    const resize = () => {
+      const dpr = window.devicePixelRatio || 1;
+      canvas.width = Math.round(canvas.clientWidth * dpr);
+      canvas.height = Math.round(canvas.clientHeight * dpr);
+    };
+    resize();
+    const observer = new ResizeObserver(resize);
+    observer.observe(canvas);
+
+    let frame = 0;
+    const draw = () => {
+      const vw = video.videoWidth;
+      const vh = video.videoHeight;
+      const cw = canvas.width;
+      const ch = canvas.height;
+      if (vw && vh && cw && ch) {
+        const scale =
+          fit === "contain"
+            ? Math.min(cw / vw, ch / vh)
+            : Math.max(cw / vw, ch / vh);
+        const w = vw * scale;
+        const h = vh * scale;
+        ctx.clearRect(0, 0, cw, ch);
+        ctx.drawImage(video, (cw - w) / 2, (ch - h) / 2, w, h);
+      }
+      frame = requestAnimationFrame(draw);
+    };
+    frame = requestAnimationFrame(draw);
+
+    // Browsers may pause muted videos they consider hidden; keep it looping.
+    const resume = () => {
+      if (video.paused && document.visibilityState === "visible") {
+        video.play().catch(() => {});
+      }
+    };
+    resume();
+    video.addEventListener("pause", resume);
+    document.addEventListener("visibilitychange", resume);
+    const keepAlive = setInterval(resume, 1000);
+
+    return () => {
+      cancelAnimationFrame(frame);
+      observer.disconnect();
+      clearInterval(keepAlive);
+      video.removeEventListener("pause", resume);
+      document.removeEventListener("visibilitychange", resume);
+    };
+  }, [fit]);
+
+  return (
+    <a
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      aria-label="Open the Janitor profile CSS editor"
+      className={`block relative rounded-lg overflow-hidden shadow-lg bg-black ${className}`}
+    >
+      <video
+        ref={videoRef}
+        src="/avalon/css-banner.mp4"
+        autoPlay
+        loop
+        muted
+        playsInline
+        disablePictureInPicture
+        preload="auto"
+        aria-hidden
+        className="absolute top-0 left-0 w-px h-px opacity-[0.01] pointer-events-none"
+      />
+      <canvas ref={canvasRef} className="absolute inset-0 w-full h-full" />
+    </a>
+  );
+}

src/components/ui/discord-banner-permanent.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import Image from "next/image";
+
+interface DiscordBannerPermanentProps {
+  inviteLink: string;
+  serverName?: string;
+  description?: string;
+  ctaText?: string;
+  className?: string;
+}
+
+export function DiscordBannerPermanent({
+  inviteLink,
+  serverName = "Avalon",
+  description = "Avalon is an enchanted creative haven for a growing collective of botmakers and users—part workshop, part myth, part digital forest where strange and beautiful ideas come to life. Enter our little woodland here:",
+  ctaText = "Join Server",
+  className = "mb-4",
+}: DiscordBannerPermanentProps) {
+  return (
+    <div className={`relative rounded-lg overflow-hidden shadow-lg bg-[#36393f] ${className}`}>
+      {/* Background Image */}
+      <div className="absolute inset-0">
+        <Image
+          src="/avalon/bg.webp"
+          alt="Background"
+          fill
+          className="object-cover opacity-20"
+        />
+      </div>
+
+      {/* Content */}
+      <div className="relative p-3 sm:p-4">
+        {/* Chat Message Style */}
+        <div className="flex gap-3 mb-2">
+          {/* Morgana Avatar */}
+          <div className="flex-shrink-0 pt-0.5">
+            <Image
+              src="/avalon/morgana-thumb.webp"
+              alt="Morgana"
+              width={40}
+              height={40}
+              className="rounded-full w-10 h-10"
+            />
+          </div>
+
+          {/* Message Content */}
+          <div className="flex-1 min-w-0">
+            <div className="flex items-baseline gap-2 mb-0.5">
+              <span className="text-white font-medium text-[15px]">Morgana</span>
+              <span className="text-[#a3a6aa] text-[11px] font-medium">Today at {new Date().toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit', hour12: true })}</span>
+            </div>
+            <div className="text-[#dcddde] text-[15px] leading-[1.375rem] mb-2">
+              {description}
+            </div>
+
+            {/* Server Invite Embed */}
+            <div className="bg-[#2f3136] rounded border-l-4 border-[#5865F2] overflow-hidden max-w-[432px]">
+              <div className="p-4 pb-3">
+                <div className="text-[#00b0f4] text-xs font-semibold uppercase mb-2">
+                  You&apos;ve been invited to join a server
+                </div>
+                <div className="flex items-center gap-4">
+                  <Image
+                    src="/avalon/avalon-pfp.webp"
+                    alt="Avalon"
+                    width={50}
+                    height={50}
+                    className="rounded-2xl w-[50px] h-[50px] flex-shrink-0"
+                  />
+                  <div className="flex-1 min-w-0">
+                    <div className="text-white font-semibold text-base mb-0.5">{serverName}</div>
+                    <div className="text-[#b9bbbe] text-sm space-y-0.5">
+                      <div className="font-medium">885 members</div>
+                      <a
+                        href="https://from-avalon.com"
+                        target="_blank"
+                        rel="noopener noreferrer"
+                        className="text-[#00aff4] hover:underline text-xs inline-block"
+                      >
+                        from-avalon.com
+                      </a>
+                    </div>
+                  </div>
+                  <a
+                    href={inviteLink}
+                    target="_blank"
+                    rel="noopener noreferrer"
+                    className="bg-[#248046] hover:bg-[#1a6334] text-white px-4 py-2 text-sm rounded font-medium transition-colors flex-shrink-0"
+                  >
+                    {ctaText}
+                  </a>
+                </div>
+              </div>
+            </div>
+          </div>
+        </div>
+
+        {/* Trash Panda Icon - Bottom Right */}
+        <div className="absolute bottom-1.5 right-1.5">
+          <Image
+            src="/avalon/trashpanda.webp"
+            alt=""
+            width={20}
+            height={20}
+            className="rounded-full w-5 h-5 ring-1 ring-black/20 opacity-60 hover:opacity-100 transition-opacity"
+          />
+        </div>
+      </div>
+    </div>
+  );
+}

src/components/ui/dropdown-menu.tsx

@@ -0,0 +1,41 @@
+"use client";
+
+import * as React from "react";
+import * as DropdownMenuPrimitive from "@radix-ui/react-dropdown-menu";
+
+const DropdownMenu = DropdownMenuPrimitive.Root;
+
+const DropdownMenuTrigger = DropdownMenuPrimitive.Trigger;
+
+const DropdownMenuContent = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Content>
+>(({ className = "", sideOffset = 4, ...props }, ref) => (
+  <DropdownMenuPrimitive.Portal>
+    <DropdownMenuPrimitive.Content
+      ref={ref}
+      sideOffset={sideOffset}
+      className={`z-50 min-w-[8rem] overflow-hidden rounded-md border bg-popover p-1 text-popover-foreground shadow-md animate-in data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 ${className}`}
+      {...props}
+    />
+  </DropdownMenuPrimitive.Portal>
+));
+DropdownMenuContent.displayName = DropdownMenuPrimitive.Content.displayName;
+
+const DropdownMenuItem = React.forwardRef<
+  React.ElementRef<typeof DropdownMenuPrimitive.Item>,
+  React.ComponentPropsWithoutRef<typeof DropdownMenuPrimitive.Item> & {
+    inset?: boolean;
+  }
+>(({ className = "", inset, ...props }, ref) => (
+  <DropdownMenuPrimitive.Item
+    ref={ref}
+    className={`relative flex cursor-pointer select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none transition-colors focus:bg-accent focus:text-accent-foreground data-[disabled]:pointer-events-none data-[disabled]:opacity-50 ${
+      inset ? "pl-8" : ""
+    } ${className}`}
+    {...props}
+  />
+));
+DropdownMenuItem.displayName = DropdownMenuPrimitive.Item.displayName;
+
+export { DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuItem };

src/lib/errors.ts

@@ -0,0 +1,161 @@
+/**
+ * Telling people what actually went wrong.
+ *
+ * Every failure used to produce one message: "You dingus, read the directions
+ * on sucker before trying again", with a note about context size. For a
+ * truncated card that was fair. For anything else it blamed the user for
+ * something they could not have done anything about.
+ *
+ * The split that matters is not explained-vs-unexplained, it is
+ * **fixable-vs-not**:
+ *
+ *   - A setup step or a truncated card is something a user can act on;
+ *     those messages are shown verbatim, and name the step.
+ *   - Everything else — a request with no card in it, no greeting, nothing
+ *     at all — cannot happen through Janitor, and if it does the user has no
+ *     way to cause or fix it. Telling them to "open the chat properly" would
+ *     be the old message wearing a new coat. Those say plainly that it is not
+ *     their fault and ask them to report it, carrying a short tag so the
+ *     report identifies which assumption broke.
+ */
+
+/** Where to send someone when sucker is at fault. */
+export const CONTACT = "DM @lyseverian on Discord";
+
+/** A failure the person who hit it can actually do something about. */
+export class SuckerError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SuckerError";
+  }
+}
+
+/**
+ * A request shaped in a way Janitor does not produce. Not the user's fault
+ * and not theirs to fix; `detail` exists so their report says which
+ * assumption broke, not so they can act on it.
+ */
+export class ImpossibleRequest extends Error {
+  readonly detail: string;
+  constructor(detail: string) {
+    super(`impossible request: ${detail}`);
+    this.name = "ImpossibleRequest";
+    this.detail = detail;
+  }
+}
+
+/**
+ * Both are checked by name as well as by identity: Next can bundle a module
+ * into more than one chunk, and a mismatched class would quietly send every
+ * classified error down the wrong path.
+ */
+const named = (error: unknown, name: string): boolean =>
+  typeof error === "object" &&
+  error !== null &&
+  (error as { name?: unknown }).name === name;
+
+export function isSuckerError(error: unknown): error is SuckerError {
+  return error instanceof SuckerError || named(error, "SuckerError");
+}
+
+export function isImpossibleRequest(error: unknown): error is ImpossibleRequest {
+  return error instanceof ImpossibleRequest || named(error, "ImpossibleRequest");
+}
+
+export function userFacingMessage(error: unknown): string {
+  if (isSuckerError(error)) return error.message;
+  const detail = isImpossibleRequest(error) ? ` (${error.detail})` : "";
+  return (
+    "Something went wrong that sucker has no explanation for. This one is " +
+    "not your fault and there is nothing for you to fix — " +
+    `please ${CONTACT} and say what you were pulling, because unreported ones ` +
+    `do not get fixed.${detail}`
+  );
+}
+
+const PERSONA_OPEN = "<UserPersona>";
+const PERSONA_CLOSE = "</UserPersona>";
+
+/** What the persona marker says, or null if it is absent or cut off mid-tag. */
+function personaDescription(content: string): string | null {
+  const open = content.indexOf(PERSONA_OPEN);
+  if (open === -1) return null;
+  const close = content.indexOf(PERSONA_CLOSE, open + PERSONA_OPEN.length);
+  if (close === -1) return null;
+  return content.slice(open + PERSONA_OPEN.length, close);
+}
+
+/** A short, single-line quote of what the user actually set. */
+function quoted(text: string): string {
+  if (text.trim() === "") return "empty";
+  const flat = text.replace(/\s+/g, " ").trim();
+  return `"${flat.length > 40 ? flat.slice(0, 40) + "…" : flat}"`;
+}
+
+/**
+ * Reads the two markers the two REQUIRED setup steps produce and says which
+ * step is wrong — or, when a marker is simply gone, that the card was
+ * probably cut short. Returns null when both are as they should be.
+ *
+ * `<.>` is the custom prompt and sits at the very start of the system
+ * message, so if it is missing the prompt is not set: truncation cannot
+ * remove the first three characters. `<UserPersona>…</UserPersona>` is the
+ * persona description and sits after the card, so:
+ *
+ *   - present with something other than "." inside → the description is
+ *     wrong. Certain, and the message quotes what it currently says.
+ *   - absent, or cut off mid-tag → either the persona is not set or Janitor
+ *     truncated the card because the bot is bigger than the context size.
+ *     Truncation is the common one, so it leads.
+ */
+export function diagnoseSetup(content: string): SuckerError | null {
+  const hasPrompt = content.includes("<.>");
+  const persona = personaDescription(content);
+  const personaOk = persona === ".";
+  if (hasPrompt && personaOk) return null;
+
+  const stillStuck = `Still stuck: ${CONTACT}.`;
+
+  if (!hasPrompt) {
+    let also = "";
+    if (persona === null) {
+      also =
+        " Your persona did not come through either: it needs the name " +
+        "{{user}} and a description of just a dot.";
+    } else if (!personaOk) {
+      also = ` Your persona description is ${quoted(persona)} as well — it has to be just a dot.`;
+    }
+    return new SuckerError(
+      "Sucker could not read that card: your custom prompt is not coming " +
+        "through as <.> — set it in your API settings." +
+        also +
+        ` Save, then refresh Janitor, not sucker. ${stillStuck}`
+    );
+  }
+
+  if (persona !== null) {
+    // Present but not "." — the one case that is certain.
+    return new SuckerError(
+      `Sucker could not read that card: your persona description is ${quoted(persona)} — ` +
+        "it has to be just a dot, with the name {{user}}. Save, then refresh " +
+        `Janitor, not sucker. ${stillStuck}`
+    );
+  }
+
+  // Prompt is fine and the persona marker is gone entirely: the end of the
+  // card is missing, and the usual reason is that Janitor cut it short.
+  return new SuckerError(
+    "Sucker could not read that card: the end of it is missing. That usually " +
+      "means the bot is bigger than your context size and Janitor cut it " +
+      "short — raise Context Size in Generation Settings and try again. If it " +
+      "is already generous, check your persona: name {{user}}, description " +
+      `just a dot, then refresh Janitor. ${stillStuck}`
+  );
+}
+
+// None of these can happen through Janitor. They exist so that if one ever
+// does, the reply is honest about whose problem it is and the report says
+// which assumption broke.
+export const NO_CARD = new ImpossibleRequest("no system message in the request");
+export const NO_GREETING = new ImpossibleRequest("no greeting in the request");
+export const TOO_FEW_MESSAGES = new ImpossibleRequest("fewer than two messages in the request");

src/lib/messages.ts

@@ -0,0 +1,117 @@
+/**
+ * Locating the parts of a JanitorAI request.
+ *
+ * JanitorAI does not send a fixed number of messages. Most clients put a
+ * throwaway "." user turn between the card and the greeting; some do not.
+ * Sucker used to read fixed indices, so on the shorter shape it read the name
+ * slot as the greeting and the slot after that did not exist at all — a
+ * TypeError that reached the user as the "you dingus" message, blaming them
+ * for something they had no control over.
+ *
+ * So nothing here depends on a position. What is actually stable, in both
+ * shapes and however long the conversation runs:
+ *
+ *   - the card is the system turn;
+ *   - the greeting is the FIRST assistant turn;
+ *   - the name is the first user turn AFTER the greeting — the one the user
+ *     typed to start, which stays put as more turns are appended;
+ *   - what the user typed most recently is the LAST user turn.
+ *
+ * Roles are compared case-insensitively and content is flattened to text
+ * first, because neither is guaranteed: a client may send "Assistant", or
+ * content as OpenAI's multipart array rather than a plain string. Getting
+ * either wrong looks exactly like the bug above.
+ *
+ * If JanitorAI changes the shape again, this is the only file that should
+ * need to know.
+ */
+
+export interface Message {
+  role?: string;
+  content?: unknown;
+}
+
+export interface MessageSlots {
+  /** The character card. */
+  system: string | undefined;
+  /** The character's opening message. */
+  greeting: string | undefined;
+  /** The name — or conversation token — the user typed to start the chat. */
+  nameSlot: string | undefined;
+  /** Whatever the user typed most recently. */
+  lastUser: string | undefined;
+}
+
+/** "Assistant", " user " and "USER" all have to count. */
+function roleOf(message: Message | undefined): string {
+  return typeof message?.role === "string" ? message.role.trim().toLowerCase() : "";
+}
+
+/**
+ * Content is usually a string, but the OpenAI shape allows an array of parts
+ * ({ type: "text", text: "…" }). Anything else — null, a number, a missing
+ * key — flattens to "" so it is simply skipped rather than throwing.
+ */
+export function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (Array.isArray(content)) {
+    return content
+      .map((part) => {
+        if (typeof part === "string") return part;
+        const text = (part as { text?: unknown } | null)?.text;
+        return typeof text === "string" ? text : "";
+      })
+      .join("");
+  }
+  return "";
+}
+
+/** Messages with usable text, paired with their normalised role. */
+function usable(messages: Message[] | undefined): { role: string; text: string }[] {
+  return (Array.isArray(messages) ? messages : [])
+    .map((m) => ({ role: roleOf(m), text: textOf(m?.content) }))
+    .filter((m) => m.text.length > 0);
+}
+
+export function selectMessageSlots(messages: Message[] | undefined): MessageSlots {
+  const list = usable(messages);
+  const greetingIndex = list.findIndex((m) => m.role === "assistant");
+  const users = list.filter((m) => m.role === "user");
+
+  return {
+    // A first message with no role at all is taken as the card, which is
+    // where it has always been. A request that has roles but no system turn
+    // is left with no card, so it is reported rather than misdiagnosed.
+    system: (list.find((m) => m.role === "system") ?? (list[0]?.role === "" ? list[0] : undefined))?.text,
+    greeting: greetingIndex === -1 ? undefined : list[greetingIndex].text,
+    nameSlot:
+      greetingIndex === -1
+        ? undefined
+        : list.slice(greetingIndex + 1).find((m) => m.role === "user")?.text,
+    lastUser: users[users.length - 1]?.text,
+  };
+}
+
+/**
+ * Message contents to search for a conversation token, in conversation order,
+ * starting after the greeting.
+ *
+ * A legitimate token lives in exactly one of two places, both after the
+ * greeting: the first user turn, when a chat was started with one to capture
+ * an alternate greeting, or sucker's own first reply, which issued it. Every
+ * later reply says "updated" or "unchanged" with no token in it, so a long
+ * conversation has to be searched back to its start or the link is lost and a
+ * duplicate card gets created.
+ *
+ * The card and the greeting are deliberately excluded. A card built from a
+ * sucker-proxied chat could carry an old token in its text, and a lookup on
+ * that would fail forever — the card would never be extractable.
+ * Conversation order also means the token a chat was started with always
+ * wins over one pasted later, so a chat cannot flip between cards.
+ */
+export function tokenCandidates(messages: Message[] | undefined): string[] {
+  const list = usable(messages);
+  const greetingIndex = list.findIndex((m) => m.role === "assistant");
+  if (greetingIndex === -1) return [];
+  return list.slice(greetingIndex + 1).map((m) => m.text);
+}

tests/errors.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Which failures a user can act on, which just need reporting, and whether
+ * the setup diagnosis names the right step.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  CONTACT,
+  ImpossibleRequest,
+  NO_CARD,
+  NO_GREETING,
+  SuckerError,
+  TOO_FEW_MESSAGES,
+  diagnoseSetup,
+  isImpossibleRequest,
+  isSuckerError,
+  userFacingMessage,
+} from "../src/lib/errors.ts";
+
+const CARD = "<Gaius's Persona>a tired innkeeper</Gaius's Persona>";
+const ok = (prompt: string, persona: string) => `${prompt}\n${CARD}\n${persona}`;
+
+test("a correctly set up card has nothing to diagnose", () => {
+  assert.equal(diagnoseSetup(ok("<.>", "<UserPersona>.</UserPersona>")), null);
+});
+
+test("a missing custom prompt is named with certainty, not blamed on truncation", () => {
+  const msg = diagnoseSetup(ok("", "<UserPersona>.</UserPersona>"))!.message;
+  assert.match(msg, /custom prompt is not coming through as <\.>/);
+  assert.ok(!/cut it short|Context Size/.test(msg), "truncation cannot remove the first three characters");
+  assert.ok(!/persona/i.test(msg), "the persona is fine and must not be mentioned");
+});
+
+test("a wrong persona description is quoted back, so there is nothing to guess", () => {
+  const msg = diagnoseSetup(ok("<.>", "<UserPersona>I am a knight</UserPersona>"))!.message;
+  assert.match(msg, /persona description is "I am a knight"/);
+  assert.match(msg, /just a dot/);
+  assert.ok(!/Context Size/.test(msg), "this case is certain; truncation is not the story");
+});
+
+test("an empty persona description says so", () => {
+  assert.match(diagnoseSetup(ok("<.>", "<UserPersona></UserPersona>"))!.message, /description is empty/);
+});
+
+test("a long persona description is trimmed to one readable line", () => {
+  const long = "x".repeat(80) + "\n\n  y";
+  const msg = diagnoseSetup(ok("<.>", `<UserPersona>${long}</UserPersona>`))!.message;
+  assert.match(msg, /"x{40}…"/);
+  assert.ok(!msg.includes("\n"), "no raw newlines from user content");
+});
+
+test("a persona marker that is gone leads with truncation, the common cause", () => {
+  const msg = diagnoseSetup(ok("<.>", ""))!.message;
+  assert.match(msg, /end of it is missing/);
+  assert.ok(msg.indexOf("Context Size") < msg.indexOf("persona"), "truncation first, persona second");
+});
+
+test("a persona marker cut off mid-tag is truncation, not a wrong description", () => {
+  const msg = diagnoseSetup(ok("<.>", "<UserPersona>.</UserPe"))!.message;
+  assert.match(msg, /Context Size/);
+  assert.ok(!/description is/.test(msg));
+});
+
+test("both settings wrong at once are both named", () => {
+  const msg = diagnoseSetup(ok("", "<UserPersona>knight</UserPersona>"))!.message;
+  assert.match(msg, /custom prompt is not coming through/);
+  assert.match(msg, /description is "knight" as well/);
+  const neither = diagnoseSetup(ok("", ""))!.message;
+  assert.match(neither, /custom prompt is not coming through/);
+  assert.match(neither, /persona did not come through either/);
+});
+
+test("every setup message is shown verbatim and says where to go when stuck", () => {
+  for (const card of [ok("", "<UserPersona>.</UserPersona>"), ok("<.>", "<UserPersona>x</UserPersona>"), ok("<.>", ""), ok("", "")]) {
+    const e = diagnoseSetup(card)!;
+    assert.ok(isSuckerError(e));
+    assert.equal(userFacingMessage(e), e.message);
+    assert.ok(e.message.includes(CONTACT));
+  }
+});
+
+test("shapes Janitor cannot produce never tell the user to fix them", () => {
+  for (const e of [NO_CARD, NO_GREETING, TOO_FEW_MESSAGES]) {
+    const msg = userFacingMessage(e);
+    assert.match(msg, /not your fault and there is nothing for you to fix/i);
+    assert.ok(msg.includes(CONTACT), "must say where to report it");
+    assert.ok(!/open the chat|try again|point sucker|nothing was saved/i.test(msg), `overclaim or advice leaked into: ${msg}`);
+  }
+});
+
+test("the report carries which assumption broke, so it is useful", () => {
+  assert.match(userFacingMessage(NO_GREETING), /\(no greeting in the request\)/);
+  assert.match(userFacingMessage(NO_CARD), /\(no system message in the request\)/);
+  assert.match(userFacingMessage(TOO_FEW_MESSAGES), /\(fewer than two messages/);
+});
+
+test("a genuine bug reports itself without leaking internals", () => {
+  const msg = userFacingMessage(new TypeError("Cannot read properties of undefined"));
+  assert.match(msg, /not your fault/i);
+  assert.ok(msg.includes(CONTACT));
+  assert.ok(!msg.includes("Cannot read properties"));
+  assert.ok(!/\($/.test(msg.trim()), "no empty detail parenthesis");
+});
+
+test("nobody is called a dingus", () => {
+  for (const e of [diagnoseSetup("nothing")!, NO_CARD, NO_GREETING, TOO_FEW_MESSAGES, new Error("x")]) {
+    assert.ok(!/dingus/i.test(userFacingMessage(e)));
+  }
+});
+
+test("classified across module boundaries, not just by identity", () => {
+  assert.ok(isSuckerError(new SuckerError("x")));
+  assert.ok(isSuckerError({ name: "SuckerError", message: "x" }));
+  assert.ok(isImpossibleRequest(new ImpossibleRequest("x")));
+  assert.ok(isImpossibleRequest({ name: "ImpossibleRequest", detail: "x" }));
+  assert.ok(!isSuckerError(new Error("x")));
+  assert.ok(!isImpossibleRequest(new SuckerError("x")));
+  assert.ok(!isSuckerError(null));
+});

tests/messages.test.ts

@@ -0,0 +1,149 @@
+/**
+ * Every request shape we have actually seen, plus the malformed ones a client
+ * could plausibly send. Run with `npm test` — no framework, node's own runner.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { selectMessageSlots, tokenCandidates, textOf } from "../src/lib/messages.ts";
+
+const CARD =
+  "<.>\n<Gaius's Persona>a tired innkeeper</Gaius's Persona><UserPersona>.</UserPersona>";
+const GREETING = "The clink of bottles is the only greeting you get.";
+const NAME = "{{user}}: Gaius";
+const TOKEN = "[sucker:conv=abc123]";
+
+/** What most clients send: a throwaway "." user turn before the greeting. */
+const withProbe = [
+  { role: "system", content: CARD },
+  { role: "user", content: "." },
+  { role: "assistant", content: GREETING },
+  { role: "user", content: NAME },
+];
+
+/** What some clients send: no "." turn, so every index shifts by one. */
+const withoutProbe = [
+  { role: "system", content: CARD },
+  { role: "assistant", content: GREETING },
+  { role: "user", content: NAME },
+];
+
+/** Three turns in. Only sucker's FIRST reply carries the token. */
+const continued = [
+  ...withProbe,
+  { role: "assistant", content: `New character "Gaius" created (v1). ${TOKEN}` },
+  { role: "user", content: "{{user}}: keep going" },
+  { role: "assistant", content: "Character data unchanged (v1, message 2)." },
+  { role: "user", content: "{{user}}: and again" },
+];
+
+test("both shapes resolve to the same slots", () => {
+  for (const [label, messages] of [
+    ["with probe", withProbe],
+    ["without probe", withoutProbe],
+  ] as const) {
+    const slots = selectMessageSlots(messages);
+    assert.equal(slots.system, CARD, `${label}: card`);
+    assert.equal(slots.greeting, GREETING, `${label}: greeting`);
+    assert.equal(slots.nameSlot, NAME, `${label}: name`);
+  }
+});
+
+test("the greeting and the name stay put as a conversation grows", () => {
+  const slots = selectMessageSlots(continued);
+  assert.equal(slots.greeting, GREETING);
+  // Not "keep going" or "and again": the name is what started the chat.
+  assert.equal(slots.nameSlot, NAME);
+  assert.equal(slots.lastUser, "{{user}}: and again");
+});
+
+test("the token is still found once later replies stop carrying it", () => {
+  const found = tokenCandidates(continued).find((c) => c.includes("sucker:conv="));
+  assert.ok(found, "a token must still be discoverable three turns in");
+  assert.match(found!, /\[sucker:conv=abc123\]/);
+});
+
+test("the token a chat was started with outranks one pasted later, so a chat cannot flip between cards", () => {
+  const candidates = tokenCandidates([
+    ...withProbe,
+    { role: "assistant", content: `created (v1). ${TOKEN}` },
+    { role: "user", content: "{{user}}: [sucker:conv=zzz999]" },
+  ]);
+  const first = candidates.find((c) => c.includes("sucker:conv="));
+  assert.match(first!, /abc123/);
+});
+
+test("a token in the card or the greeting is never a candidate", () => {
+  const stale = "[sucker:conv=stale00]";
+  const candidates = tokenCandidates([
+    { role: "system", content: `${CARD} made with sucker: ${stale}` },
+    { role: "user", content: "." },
+    { role: "assistant", content: `${GREETING} ${stale}` },
+    { role: "user", content: NAME },
+  ]);
+  assert.ok(!candidates.some((c) => c.includes(stale)), "an expired token baked into a card would make it unextractable forever");
+  assert.deepEqual(candidates, [NAME]);
+});
+
+test("roles are matched whatever their casing", () => {
+  const slots = selectMessageSlots([
+    { role: "System", content: CARD },
+    { role: " Assistant ", content: GREETING },
+    { role: "USER", content: NAME },
+  ]);
+  assert.equal(slots.system, CARD);
+  assert.equal(slots.greeting, GREETING);
+  assert.equal(slots.nameSlot, NAME);
+});
+
+test("content sent as OpenAI's multipart array is read as text", () => {
+  assert.equal(textOf([{ type: "text", text: "one " }, { type: "text", text: "two" }]), "one two");
+  const slots = selectMessageSlots([
+    { role: "system", content: [{ type: "text", text: CARD }] },
+    { role: "assistant", content: [{ type: "text", text: GREETING }] },
+    { role: "user", content: NAME },
+  ]);
+  assert.equal(slots.system, CARD);
+  assert.equal(slots.greeting, GREETING);
+});
+
+test("messages with no usable content are skipped, not treated as slots", () => {
+  const slots = selectMessageSlots([
+    { role: "system", content: CARD },
+    { role: "assistant", content: null },
+    { role: "assistant" },
+    { role: "assistant", content: GREETING },
+    { role: "user", content: NAME },
+  ]);
+  // The empty assistant turns must not be mistaken for the greeting.
+  assert.equal(slots.greeting, GREETING);
+  assert.equal(slots.nameSlot, NAME);
+});
+
+test("a request with roles but no system turn has no card, rather than a misdiagnosed one", () => {
+  const slots = selectMessageSlots([
+    { role: "assistant", content: GREETING },
+    { role: "user", content: NAME },
+  ]);
+  // Taking the greeting as the card would produce a "custom prompt not set"
+  // message for a request the user could never have fixed.
+  assert.equal(slots.system, undefined);
+  assert.equal(slots.greeting, GREETING);
+});
+
+test("a card with no role on the system turn still resolves", () => {
+  const slots = selectMessageSlots([
+    { content: CARD },
+    { role: "assistant", content: GREETING },
+    { role: "user", content: NAME },
+  ]);
+  assert.equal(slots.system, CARD);
+});
+
+test("nothing throws on empty or malformed input", () => {
+  for (const input of [[], undefined, [{}, { role: "user" }], [null], [{ content: 42 }]]) {
+    assert.doesNotThrow(() => selectMessageSlots(input as never));
+    assert.doesNotThrow(() => tokenCandidates(input as never));
+  }
+  assert.equal(selectMessageSlots([]).greeting, undefined);
+  assert.deepEqual(tokenCandidates(undefined), []);
+});

tsconfig.json

@@ -2,8 +2,14 @@
   "compilerOptions": {
     "baseUrl": ".",
     "target": "es5",
-    "lib": ["dom", "dom.iterable", "esnext"],
+    "lib": [
-    "types": ["node"],
+      "dom",
+      "dom.iterable",
+      "esnext"
+    ],
+    "types": [
+      "node"
+    ],
     "allowJs": true,
     "skipLibCheck": true,
     "strict": true,
@@ -13,7 +19,7 @@
     "moduleResolution": "bundler",
     "resolveJsonModule": true,
     "isolatedModules": true,
-    "jsx": "preserve",
+    "jsx": "react-jsx",
     "incremental": true,
     "plugins": [
       {
@@ -21,9 +27,19 @@
       }
     ],
     "paths": {
-      "@/*": ["./src/*"]
+      "@/*": [
+        "./src/*"
+      ]
     }
   },
-  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", ".next/types/**/*.ts"],
+  "include": [
-  "exclude": ["node_modules"]
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
 }