@schlenkr/ragents 0.1.0

package/apps/web/src/column/host-contract.ts

@@ -0,0 +1,83 @@
+/** Vertrag zwischen der Arbeitsspalte (column.html) und einem Host, der sie in einem iframe zeigt; importfrei, die VS-Code-Erweiterung bündelt ihn mit. */
+
+export const COLUMN_PAGE = "column.html";
+
+export type ColumnLayout = "column" | "app";
+export type ColumnTheme = "light" | "dark";
+
+export interface ColumnPageQuery {
+  layout?: ColumnLayout;
+  run?: string;
+  element?: string;
+  host?: "vscode";
+  theme?: ColumnTheme;
+  access?: string;
+}
+
+export const columnPageUrl = (serverUrl: string, query: ColumnPageQuery): string => {
+  const url = new URL(COLUMN_PAGE, serverUrl.endsWith("/") ? serverUrl : `${serverUrl}/`);
+  for (const [key, value] of Object.entries(query)) if (value !== undefined) url.searchParams.set(key, value);
+  return url.toString();
+};
+
+/** Nachrichten des Panels an seinen Host. */
+export type ColumnHostMessage =
+  | { type: "ready" }
+  | { type: "runChanged"; runId: string | null }
+  | { type: "openInCenter"; runId: string; elementId: string; title: string }
+  | { type: "returnToColumn"; runId: string; elementId: string }
+  | { type: "login" }
+  | { type: "logout" }
+  | { type: "openExternal"; url: string }
+  | { type: "openPage"; url: string; title: string };
+
+/** Nachrichten des Hosts an das Panel. */
+export type HostColumnMessage =
+  | { type: "selectRun"; runId: string | null }
+  | { type: "newRun"; startOptions?: Record<string, unknown>; entryId?: string }
+  | { type: "placements"; runId: string; center: string[] }
+  | { type: "theme"; theme: ColumnTheme };
+
+const isObject = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null;
+const isText = (value: unknown): value is string => typeof value === "string" && value.length > 0;
+
+export const isColumnTheme = (value: unknown): value is ColumnTheme => value === "light" || value === "dark";
+
+export const isColumnHostMessage = (value: unknown): value is ColumnHostMessage => {
+  if (!isObject(value)) return false;
+  switch (value.type) {
+    case "ready":
+    case "login":
+    case "logout":
+      return true;
+    case "runChanged":
+      return value.runId === null || isText(value.runId);
+    case "openInCenter":
+      return isText(value.runId) && isText(value.elementId) && typeof value.title === "string";
+    case "returnToColumn":
+      return isText(value.runId) && isText(value.elementId);
+    case "openExternal":
+      return isText(value.url);
+    case "openPage":
+      return isText(value.url) && typeof value.title === "string";
+    default:
+      return false;
+  }
+};
+
+export const isHostColumnMessage = (value: unknown): value is HostColumnMessage => {
+  if (!isObject(value)) return false;
+  switch (value.type) {
+    case "selectRun":
+      return value.runId === null || isText(value.runId);
+    case "newRun":
+      return (value.startOptions === undefined || (isObject(value.startOptions) && !Array.isArray(value.startOptions)))
+        && (value.entryId === undefined || isText(value.entryId));
+    case "placements":
+      return isText(value.runId) && Array.isArray(value.center) && value.center.every(isText);
+    case "theme":
+      return isColumnTheme(value.theme);
+    default:
+      return false;
+  }
+};

package/apps/web/src/column/host.ts

@@ -0,0 +1,101 @@
+import { createContext, useContext, useSyncExternalStore } from "react";
+import type { ColumnHostKind } from "./column-location";
+import { isHostColumnMessage, type ColumnHostMessage, type ColumnTheme, type HostColumnMessage } from "./host-contract";
+
+export interface ColumnHost {
+  readonly kind: ColumnHostKind;
+  /** Elemente des Runs, die der Host gerade in der Mitte zeigt; im Browser immer leer. */
+  centerElements(runId: string): ReadonlySet<string>;
+  subscribe(listener: () => void): () => void;
+  openInCenter(runId: string, elementId: string, title: string): void;
+  returnToColumn(runId: string, elementId: string): void;
+  requestLogin(): void;
+  /** Der Host hält den Sitzungstoken und beendet die Sitzung selbst. */
+  requestLogout(): void;
+  openExternal(url: string): void;
+  /** Zeigt eine Webseite im Host, etwa als Reiter im Simple Browser von VS Code. */
+  openPage(url: string, title: string): void;
+  onCommand(listener: (message: HostColumnMessage) => void): () => void;
+  /** Meldet dem Host, dass das Panel bereit ist oder ihren Run gewechselt hat. */
+  notify(message: Extract<ColumnHostMessage, { type: "ready" | "runChanged" }>): void;
+}
+
+const emptySet: ReadonlySet<string> = new Set();
+
+const unsupported = (action: string) => (): never => {
+  throw new Error(`${action} gibt es nur in VS Code.`);
+};
+
+export function createBrowserHost(browser: Window): ColumnHost {
+  return {
+    kind: "browser",
+    centerElements: () => emptySet,
+    subscribe: () => () => undefined,
+    openInCenter: unsupported("Eine Mini-App in die Mitte legen"),
+    returnToColumn: unsupported("Eine Mini-App zurückholen"),
+    requestLogin: unsupported("Die Anmeldung über den Host"),
+    requestLogout: unsupported("Die Abmeldung über den Host"),
+    openExternal: (url) => { browser.open(url, "_blank", "noopener"); },
+    openPage: unsupported("Eine Webseite im Host zeigen"),
+    onCommand: () => () => undefined,
+    notify: () => undefined,
+  };
+}
+
+/** Das Panel im iframe eines VS-Code-Webviews: Nachrichten laufen über das umgebende Webview zur Erweiterung. */
+export function createVsCodeHost(browser: Window): ColumnHost {
+  const parent = browser.parent;
+  if (parent === browser) throw new Error("Das Panel läuft mit host=vscode, ist aber in kein Webview eingebettet.");
+  const placements = new Map<string, ReadonlySet<string>>();
+  const placementListeners = new Set<() => void>();
+  const commandListeners = new Set<(message: HostColumnMessage) => void>();
+  const post = (message: ColumnHostMessage) => parent.postMessage(message, "*");
+  browser.addEventListener("message", (event) => {
+    if (event.source !== parent || !isHostColumnMessage(event.data)) return;
+    const message = event.data;
+    if (message.type === "placements") {
+      placements.set(message.runId, new Set(message.center));
+      for (const listener of placementListeners) listener();
+    }
+    for (const listener of commandListeners) listener(message);
+  });
+  return {
+    kind: "vscode",
+    centerElements: (runId) => placements.get(runId) ?? emptySet,
+    subscribe: (listener) => {
+      placementListeners.add(listener);
+      return () => { placementListeners.delete(listener); };
+    },
+    openInCenter: (runId, elementId, title) => post({ type: "openInCenter", runId, elementId, title }),
+    returnToColumn: (runId, elementId) => post({ type: "returnToColumn", runId, elementId }),
+    requestLogin: () => post({ type: "login" }),
+    requestLogout: () => post({ type: "logout" }),
+    openExternal: (url) => post({ type: "openExternal", url }),
+    openPage: (url, title) => post({ type: "openPage", url, title }),
+    onCommand: (listener) => {
+      commandListeners.add(listener);
+      return () => { commandListeners.delete(listener); };
+    },
+    notify: post,
+  };
+}
+
+export const createColumnHost = (kind: ColumnHostKind, browser: Window): ColumnHost =>
+  kind === "vscode" ? createVsCodeHost(browser) : createBrowserHost(browser);
+
+const ColumnHostContext = createContext<ColumnHost | undefined>(undefined);
+
+export const ColumnHostProvider = ColumnHostContext.Provider;
+
+export function useColumnHost(): ColumnHost {
+  const host = useContext(ColumnHostContext);
+  if (!host) throw new Error("Das Panel läuft ohne Host-Provider.");
+  return host;
+}
+
+export function useCenterElements(runId: string): ReadonlySet<string> {
+  const host = useColumnHost();
+  return useSyncExternalStore(host.subscribe, () => host.centerElements(runId), () => emptySet);
+}
+
+export type { ColumnTheme };

package/apps/web/src/column/use-session-list.ts

@@ -0,0 +1,42 @@
+import { useCallback, useEffect, useRef, useState } from "react";
+import { listSessions, type SessionInfo } from "../api";
+import { coreContracts } from "@aicontainer/server/api/contracts";
+import { rpc } from "../rpc";
+
+const POLL_INTERVAL_MS = 5000;
+
+/** Die Run-Liste des Servers, live über den Sitzungskanal und als Sicherheitsnetz alle fünf Sekunden neu geladen. */
+export function useSessionList(enabled: boolean): { sessions: SessionInfo[]; unreachable: boolean; refresh: () => Promise<void> } {
+  const [sessions, setSessions] = useState<SessionInfo[]>([]);
+  const [unreachable, setUnreachable] = useState(false);
+  const refreshing = useRef<Promise<void> | undefined>(undefined);
+  const requested = useRef(false);
+  const refresh = useCallback((): Promise<void> => {
+    if (!enabled) return Promise.resolve();
+    if (refreshing.current) {
+      requested.current = true;
+      return refreshing.current;
+    }
+    const update = async () => {
+      do {
+        requested.current = false;
+        try {
+          setSessions(await listSessions());
+          setUnreachable(false);
+        } catch { setUnreachable(true); }
+      } while (requested.current);
+    };
+    refreshing.current = update().finally(() => { refreshing.current = undefined; });
+    return refreshing.current;
+  }, [enabled]);
+
+  useEffect(() => {
+    if (!enabled) return;
+    void refresh();
+    const unsubscribe = rpc.subscribe(coreContracts.channels.sessions, {}, () => void refresh());
+    const timer = setInterval(() => void refresh(), POLL_INTERVAL_MS);
+    return () => { unsubscribe(); clearInterval(timer); };
+  }, [enabled, refresh]);
+
+  return { sessions, unreachable, refresh };
+}

package/apps/web/src/column.tsx

@@ -0,0 +1,43 @@
+import "./ui/tailwind.css";
+// Fremde Klassen von highlight.js und react-diff-view; hier statt in den Komponenten, die auch Mini-Apps bündeln.
+import "./highlighting.css";
+import "./diff-view.css";
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { Button } from "./ui";
+import { AccessGate, AccessScreen } from "./AccessContext";
+import { installAccessToken } from "./access-token";
+import { ColumnApp, HostLogin } from "./column/ColumnApp";
+import { parseColumnLocation } from "./column/column-location";
+import { ColumnHostProvider, createColumnHost } from "./column/host";
+import { PageOpenerProvider } from "./page-opener";
+import { initializeTheme } from "./theme";
+
+const root = document.getElementById("root");
+if (!root) throw new Error("Root-Element fehlt");
+
+const reactRoot = createRoot(root);
+try {
+  const location = parseColumnLocation(window.location.search);
+  if (location.access !== undefined) installAccessToken(location.access);
+  const host = createColumnHost(location.host, window);
+  const theme = initializeTheme(window);
+  if (location.theme !== undefined) theme.setPreference(location.theme);
+  host.onCommand((message) => { if (message.type === "theme") theme.setPreference(message.theme); });
+  import.meta.hot?.dispose(() => theme.dispose());
+  reactRoot.render(
+    <StrictMode>
+      <ColumnHostProvider value={host}>
+        <PageOpenerProvider value={location.host === "vscode" ? { open: host.openPage } : undefined}>
+          <AccessGate Login={location.host === "vscode" ? HostLogin : undefined}><ColumnApp location={location} /></AccessGate>
+        </PageOpenerProvider>
+      </ColumnHostProvider>
+    </StrictMode>,
+  );
+} catch (cause) {
+  reactRoot.render(<AccessScreen>
+    <h1 className="my-3 text-[1.5rem]">Das RAgents-Panel konnte nicht geladen werden</h1>
+    <p className="mb-6 leading-normal" role="alert">{cause instanceof Error ? cause.message : String(cause)}</p>
+    <Button onClick={() => window.location.reload()} variant="outline">Erneut laden</Button>
+  </AccessScreen>);
+}

package/apps/web/src/diff-view.css

@@ -0,0 +1,38 @@
+/* react-diff-view erzeugt diese Klassennamen selbst; nur deshalb bleibt hier CSS statt Utilities. */
+
+@import "react-diff-view/style/index.css";
+
+.diff {
+  font-size: 10.5px;
+}
+
+.diff-line {
+  line-height: 1.45;
+}
+
+.diff-code {
+  white-space: pre;
+  word-break: normal;
+  overflow-wrap: normal;
+}
+
+.diff-code-edit {
+  border-radius: 2px;
+}
+
+.diff-gutter {
+  color: var(--muted-foreground);
+}
+
+.diff-gutter-insert,
+.diff-gutter-delete {
+  font-weight: 600;
+}
+
+.diff-gutter-insert:first-child {
+  box-shadow: inset 3px 0 0 var(--success);
+}
+
+.diff-gutter-delete:first-child {
+  box-shadow: inset 3px 0 0 var(--destructive);
+}

package/apps/web/src/help-samples.ts

@@ -0,0 +1,11 @@
+export function helpSampleRequest(event: Pick<MessageEvent, "source" | "origin" | "data">,
+  frame: Window | null, origin: string, entries: readonly string[]): { type: "ready" } | { type: "start"; entry: string } | undefined {
+  if (!frame || event.source !== frame || event.origin !== origin) return;
+  const data: unknown = event.data;
+  if (!data || typeof data !== "object" || Array.isArray(data)) return;
+  if (!("type" in data)) return;
+  if (data.type === "ragents:help-ready") return { type: "ready" };
+  if (data.type === "ragents:start-sample" && "entry" in data && typeof data.entry === "string" && entries.includes(data.entry)) {
+    return { type: "start", entry: data.entry };
+  }
+}

package/apps/web/src/highlighting.css

@@ -0,0 +1,74 @@
+/* highlight.js erzeugt diese Klassennamen selbst; nur deshalb bleibt hier CSS statt Utilities. */
+
+.hljs-keyword,
+.hljs-selector-tag,
+.hljs-doctag,
+.hljs-template-tag {
+  color: var(--primary);
+}
+
+.hljs-string,
+.hljs-regexp,
+.hljs-addition {
+  color: color-mix(in srgb, var(--success) 76%, var(--foreground));
+}
+
+.hljs-title,
+.hljs-name,
+.hljs-section,
+.hljs-selector-id,
+.hljs-selector-class {
+  color: var(--info);
+}
+
+.hljs-type,
+.hljs-title.class_,
+.hljs-built_in,
+.hljs-builtin-name,
+.hljs-symbol,
+.hljs-bullet {
+  color: var(--teal);
+}
+
+.hljs-number,
+.hljs-literal,
+.hljs-link {
+  color: var(--warning);
+}
+
+.hljs-meta,
+.hljs-attr,
+.hljs-attribute,
+.hljs-variable,
+.hljs-template-variable,
+.hljs-selector-attr,
+.hljs-selector-pseudo {
+  color: color-mix(in srgb, var(--primary) 70%, var(--foreground));
+}
+
+.hljs-property,
+.hljs-params,
+.hljs-tag,
+.hljs-punctuation,
+.hljs-operator,
+.hljs-subst {
+  color: inherit;
+}
+
+.hljs-comment,
+.hljs-quote {
+  color: var(--muted-foreground);
+  font-style: italic;
+}
+
+.hljs-deletion {
+  color: var(--destructive);
+}
+
+.hljs-emphasis {
+  font-style: italic;
+}
+
+.hljs-strong {
+  font-weight: 600;
+}

package/apps/web/src/highlighting.ts

@@ -0,0 +1,262 @@
+import hljs from "highlight.js/lib/core";
+import bash from "highlight.js/lib/languages/bash";
+import c from "highlight.js/lib/languages/c";
+import cpp from "highlight.js/lib/languages/cpp";
+import csharp from "highlight.js/lib/languages/csharp";
+import css from "highlight.js/lib/languages/css";
+import diff from "highlight.js/lib/languages/diff";
+import dockerfile from "highlight.js/lib/languages/dockerfile";
+import fsharp from "highlight.js/lib/languages/fsharp";
+import go from "highlight.js/lib/languages/go";
+import graphql from "highlight.js/lib/languages/graphql";
+import ini from "highlight.js/lib/languages/ini";
+import java from "highlight.js/lib/languages/java";
+import javascript from "highlight.js/lib/languages/javascript";
+import json from "highlight.js/lib/languages/json";
+import kotlin from "highlight.js/lib/languages/kotlin";
+import less from "highlight.js/lib/languages/less";
+import makefile from "highlight.js/lib/languages/makefile";
+import markdown from "highlight.js/lib/languages/markdown";
+import php from "highlight.js/lib/languages/php";
+import plaintext from "highlight.js/lib/languages/plaintext";
+import powershell from "highlight.js/lib/languages/powershell";
+import properties from "highlight.js/lib/languages/properties";
+import python from "highlight.js/lib/languages/python";
+import ruby from "highlight.js/lib/languages/ruby";
+import rust from "highlight.js/lib/languages/rust";
+import scss from "highlight.js/lib/languages/scss";
+import sql from "highlight.js/lib/languages/sql";
+import swift from "highlight.js/lib/languages/swift";
+import typescript from "highlight.js/lib/languages/typescript";
+import xml from "highlight.js/lib/languages/xml";
+import yaml from "highlight.js/lib/languages/yaml";
+
+hljs.registerLanguage("bash", bash);
+hljs.registerLanguage("c", c);
+hljs.registerLanguage("cpp", cpp);
+hljs.registerLanguage("csharp", csharp);
+hljs.registerLanguage("css", css);
+hljs.registerLanguage("diff", diff);
+hljs.registerLanguage("dockerfile", dockerfile);
+hljs.registerLanguage("fsharp", fsharp);
+hljs.registerLanguage("go", go);
+hljs.registerLanguage("graphql", graphql);
+hljs.registerLanguage("ini", ini);
+hljs.registerLanguage("java", java);
+hljs.registerLanguage("javascript", javascript);
+hljs.registerLanguage("json", json);
+hljs.registerLanguage("kotlin", kotlin);
+hljs.registerLanguage("less", less);
+hljs.registerLanguage("makefile", makefile);
+hljs.registerLanguage("markdown", markdown);
+hljs.registerLanguage("php", php);
+hljs.registerLanguage("plaintext", plaintext);
+hljs.registerLanguage("powershell", powershell);
+hljs.registerLanguage("properties", properties);
+hljs.registerLanguage("python", python);
+hljs.registerLanguage("ruby", ruby);
+hljs.registerLanguage("rust", rust);
+hljs.registerLanguage("scss", scss);
+hljs.registerLanguage("sql", sql);
+hljs.registerLanguage("swift", swift);
+hljs.registerLanguage("typescript", typescript);
+hljs.registerLanguage("xml", xml);
+hljs.registerLanguage("yaml", yaml);
+
+const EXTENSIONS: Record<string, string> = {
+  ".bash": "bash",
+  ".c": "c",
+  ".cc": "cpp",
+  ".cjs": "javascript",
+  ".cpp": "cpp",
+  ".cs": "csharp",
+  ".csproj": "xml",
+  ".css": "css",
+  ".csv": "plaintext",
+  ".cts": "typescript",
+  ".diff": "diff",
+  ".dockerfile": "dockerfile",
+  ".editorconfig": "ini",
+  ".env": "bash",
+  ".fs": "fsharp",
+  ".fsproj": "xml",
+  ".fsx": "fsharp",
+  ".gitignore": "plaintext",
+  ".go": "go",
+  ".graphql": "graphql",
+  ".h": "c",
+  ".hpp": "cpp",
+  ".htm": "xml",
+  ".html": "xml",
+  ".ini": "ini",
+  ".java": "java",
+  ".js": "javascript",
+  ".json": "json",
+  ".jsonc": "json",
+  ".jsx": "javascript",
+  ".kt": "kotlin",
+  ".kts": "kotlin",
+  ".less": "less",
+  ".lock": "plaintext",
+  ".log": "plaintext",
+  ".md": "markdown",
+  ".mjs": "javascript",
+  ".mts": "typescript",
+  ".patch": "diff",
+  ".php": "php",
+  ".plist": "xml",
+  ".props": "xml",
+  ".properties": "properties",
+  ".ps1": "powershell",
+  ".py": "python",
+  ".razor": "xml",
+  ".rb": "ruby",
+  ".rs": "rust",
+  ".scss": "scss",
+  ".sh": "bash",
+  ".sln": "ini",
+  ".sql": "sql",
+  ".svelte": "xml",
+  ".svg": "xml",
+  ".swift": "swift",
+  ".targets": "xml",
+  ".toml": "ini",
+  ".ts": "typescript",
+  ".tsx": "typescript",
+  ".txt": "plaintext",
+  ".vue": "xml",
+  ".xaml": "xml",
+  ".xml": "xml",
+  ".yaml": "yaml",
+  ".yml": "yaml",
+  ".zsh": "bash",
+};
+
+const FILE_NAMES: Record<string, string> = {
+  dockerfile: "dockerfile",
+  makefile: "makefile",
+};
+
+const AUTO_DETECT = ["typescript", "csharp", "fsharp", "json", "xml", "yaml", "bash", "markdown", "python", "css", "sql"];
+
+const ALIASES: Record<string, string> = {
+  "c#": "csharp",
+  "c++": "cpp",
+  cs: "csharp",
+  fs: "fsharp",
+  fsharp: "fsharp",
+  js: "javascript",
+  jsx: "javascript",
+  kt: "kotlin",
+  md: "markdown",
+  ps1: "powershell",
+  py: "python",
+  rb: "ruby",
+  rs: "rust",
+  sh: "bash",
+  shell: "bash",
+  text: "plaintext",
+  toml: "ini",
+  ts: "typescript",
+  tsx: "typescript",
+  txt: "plaintext",
+  yml: "yaml",
+  zsh: "bash",
+};
+
+export interface HighlightedSource {
+  html: string;
+  language: string;
+}
+
+export interface HighlightToken {
+  children?: HighlightToken[];
+  className?: string;
+  type: "element" | "text";
+  value?: string;
+}
+
+export const resolveLanguage = (path: string, language?: string) => {
+  if (language) {
+    const normalized = language.toLowerCase();
+    return ALIASES[normalized] ?? normalized;
+  }
+  const name = path.toLowerCase();
+  const fileName = name.split("/").at(-1) ?? name;
+  const extension = Object.keys(EXTENSIONS).find((candidate) => name.endsWith(candidate));
+  return FILE_NAMES[fileName] ?? (extension ? EXTENSIONS[extension] : undefined);
+};
+
+export const highlightSource = (content: string, path: string, language?: string): HighlightedSource => {
+  const resolved = resolveLanguage(path, language);
+  const result = resolved && hljs.getLanguage(resolved)
+    ? hljs.highlight(content, { language: resolved, ignoreIllegals: true })
+    : hljs.highlightAuto(content, AUTO_DETECT);
+  return { language: result.language ?? "plaintext", html: result.value };
+};
+
+export const highlightTokens = (content: string, path: string, language?: string): HighlightToken[] =>
+  tokensFrom(highlightSource(content, path, language).html);
+
+export const highlightLines = (content: string, path: string, language?: string): HighlightedLines => {
+  const source = highlightSource(content, path, language);
+  const tokens = tokensFrom(source.html);
+  const lines: string[] = [];
+  const open: string[] = [];
+  let current = "";
+  const walk = (nodes: HighlightToken[]) => {
+    for (const node of nodes) {
+      if (node.type === "text") {
+        (node.value ?? "").split("\n").forEach((part, index) => {
+          if (index > 0) {
+            lines.push(current + "</span>".repeat(open.length));
+            current = open.map((className) => `<span class="${className}">`).join("");
+          }
+          current += escapeHtml(part);
+        });
+        continue;
+      }
+      const className = node.className ?? "";
+      open.push(className);
+      current += `<span class="${className}">`;
+      walk(node.children ?? []);
+      current += "</span>";
+      open.pop();
+    }
+  };
+  walk(tokens);
+  lines.push(current);
+  return { language: source.language, lines };
+};
+
+export interface HighlightedLines {
+  language: string;
+  lines: string[];
+}
+
+const escapeHtml = (text: string) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+const ENTITIES: Record<string, string> = { "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#x27;": "'" };
+
+const unescapeHtml = (text: string) => text.replace(/&(?:amp|lt|gt|quot|#x27);/g, (entity) => ENTITIES[entity]);
+
+const tokensFrom = (html: string): HighlightToken[] => {
+  const root: HighlightToken = { type: "element", children: [] };
+  const stack = [root];
+  const parts = html.split(/(<span class="[^"]*">|<\/span>)/);
+  for (const part of parts) {
+    if (!part) continue;
+    const parent = stack[stack.length - 1];
+    const opening = /^<span class="([^"]*)">$/.exec(part);
+    if (opening) {
+      const element: HighlightToken = { type: "element", className: opening[1], children: [] };
+      parent.children?.push(element);
+      stack.push(element);
+    } else if (part === "</span>") {
+      if (stack.length > 1) stack.pop();
+    } else {
+      parent.children?.push({ type: "text", value: unescapeHtml(part) });
+    }
+  }
+  return root.children ?? [];
+};

package/apps/web/src/lib/format.ts

@@ -0,0 +1,5 @@
+export const formatBytes = (size: number) => {
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} KB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+};

package/apps/web/src/lib/guards.ts

@@ -0,0 +1,8 @@
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+export const hasExactKeys = (value: Record<string, unknown>, keys: string[]): boolean => {
+  const actual = Object.keys(value).sort();
+  const expected = [...keys].sort();
+  return actual.length === expected.length && actual.every((key, index) => key === expected[index]);
+};

package/apps/web/src/lib/http.ts

@@ -0,0 +1,9 @@
+import { isRecord } from "./guards";
+
+export const errorFrom = async (response: Response, fallback: string): Promise<Error> => {
+  try {
+    const body = await response.json() as unknown;
+    if (isRecord(body) && typeof body.error === "string" && body.error.trim()) return new Error(body.error);
+  } catch {}
+  return new Error(fallback);
+};