@vellumai/assistant 0.12.0 → 0.12.1-staging.1

package/src/desktop/desktop-wallpaper.test.ts

@@ -0,0 +1,191 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, beforeEach, expect, test } from "bun:test";
+
+import sharp from "sharp";
+
+import {
+  __resetResvgCacheForTests,
+  __setResvgCacheForTests,
+} from "../avatar/resvg-lazy.js";
+import {
+  renderCurrentDesktopWallpaper,
+  renderDesktopWallpaper,
+} from "./desktop-wallpaper.js";
+
+let workspace: string;
+let previousWorkspace: string | undefined;
+beforeEach(() => {
+  workspace = mkdtempSync(join(tmpdir(), "desktop-wallpaper-test-"));
+  previousWorkspace = process.env.VELLUM_WORKSPACE_DIR;
+  process.env.VELLUM_WORKSPACE_DIR = workspace;
+  mkdirSync(join(workspace, "data/avatar"), { recursive: true });
+});
+afterEach(() => {
+  __resetResvgCacheForTests();
+  if (previousWorkspace === undefined) {
+    delete process.env.VELLUM_WORKSPACE_DIR;
+  } else {
+    process.env.VELLUM_WORKSPACE_DIR = previousWorkspace;
+  }
+  rmSync(workspace, { recursive: true, force: true });
+});
+
+function manifest(state: Record<string, unknown>): void {
+  writeFileSync(
+    join(workspace, "data/avatar/avatar.json"),
+    JSON.stringify(state),
+  );
+}
+
+async function centerPixel(png: Buffer): Promise<number[]> {
+  const { data, info } = await sharp(png)
+    .ensureAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const offset =
+    (Math.round(info.height * 0.46) * info.width + info.width / 2) * 4;
+  return [...data.subarray(offset, offset + 4)];
+}
+
+test("renders the current uploaded avatar into an opaque desktop wallpaper", async () => {
+  const png = await sharp({
+    create: { width: 32, height: 32, channels: 4, background: "#ff0000" },
+  })
+    .png()
+    .toBuffer();
+  writeFileSync(join(workspace, "data/avatar/avatar-image.png"), png);
+  manifest({
+    kind: "image",
+    source: "upload",
+    traits: null,
+    image: { updatedAt: "2026-01-01T00:00:00Z", etag: "test" },
+    accent: null,
+  });
+  const result = (await renderCurrentDesktopWallpaper(480, 300))!;
+  expect(await centerPixel(result)).toEqual([255, 0, 0, 255]);
+  const metadata = await sharp(result).metadata();
+  expect([metadata.width, metadata.height]).toEqual([480, 300]);
+  expect((await sharp(result).stats()).isOpaque).toBe(true);
+});
+
+test("regenerates a character from current traits when its raster is missing", async () => {
+  manifest({
+    kind: "character",
+    source: "pool",
+    traits: { bodyShape: "blob", eyeStyle: "curious", color: "green" },
+    image: null,
+    accent: null,
+  });
+  const result = (await renderCurrentDesktopWallpaper(480, 300))!;
+  const empty = renderDesktopWallpaper(480, 300, null, null);
+  expect(await centerPixel(result)).not.toEqual(await centerPixel(empty));
+});
+
+test("missing and unreadable avatars produce the same neutral background", async () => {
+  const missing = await renderCurrentDesktopWallpaper(480, 300);
+  manifest({
+    kind: "image",
+    source: "upload",
+    traits: null,
+    image: { updatedAt: "2026-01-01T00:00:00Z", etag: "test" },
+    accent: null,
+  });
+  writeFileSync(
+    join(workspace, "data/avatar/avatar-image.png"),
+    "not an image",
+  );
+  expect(await renderCurrentDesktopWallpaper(480, 300)).toEqual(missing);
+  expect((await sharp(missing!).stats()).isOpaque).toBe(true);
+});
+
+test("accent changes tint the background and malformed accents fall back safely", async () => {
+  const neutral = renderDesktopWallpaper(480, 300, null, null);
+  expect(
+    renderDesktopWallpaper(480, 300, null, '\"/><image href="file:///test"/>'),
+  ).toEqual(neutral);
+  const red = await centerPixel(
+    renderDesktopWallpaper(480, 300, null, "#ff0000"),
+  );
+  const blue = await centerPixel(
+    renderDesktopWallpaper(480, 300, null, "#0000ff"),
+  );
+  expect(red[0]!).toBeGreaterThan(blue[0]!);
+  expect(blue[2]!).toBeGreaterThan(red[2]!);
+});
+
+test("a missing native renderer leaves the existing desktop background alone", async () => {
+  __setResvgCacheForTests({
+    available: false,
+    error: new Error("unavailable"),
+  });
+  expect(await renderCurrentDesktopWallpaper(480, 300)).toBeNull();
+});
+
+async function wordmarkPixels(
+  png: Buffer,
+): Promise<{ x: number; y: number }[]> {
+  const { data, info } = await sharp(png)
+    .removeAlpha()
+    .raw()
+    .toBuffer({ resolveWithObject: true });
+  const pixels: { x: number; y: number }[] = [];
+  for (let y = 0; y < info.height; y++) {
+    for (let x = 0; x < info.width; x++) {
+      const offset = (y * info.width + x) * info.channels;
+      if (
+        data[offset]! > 150 &&
+        data[offset + 1]! > 150 &&
+        data[offset + 2]! > 150
+      ) {
+        pixels.push({ x, y });
+      }
+    }
+  }
+  return pixels;
+}
+
+test("renders the current identity name and picks up a rename on the next refresh", async () => {
+  const identity = join(workspace, "IDENTITY.md");
+  writeFileSync(identity, "- **Name:** Alice\n");
+  const first = (await renderCurrentDesktopWallpaper(480, 300))!;
+  expect(first).toEqual(renderDesktopWallpaper(480, 300, null, null, "Alice"));
+  const pixels = await wordmarkPixels(first);
+  expect(pixels.length).toBeGreaterThan(100);
+  expect(pixels.every(({ y }) => y > 300 * 0.6 && y < 300 * 0.72)).toBe(true);
+
+  writeFileSync(identity, "- **Name:** Bob\n");
+  const renamed = await renderCurrentDesktopWallpaper(480, 300);
+  expect(renamed).not.toEqual(first);
+  expect(renamed).toEqual(renderDesktopWallpaper(480, 300, null, null, "Bob"));
+});
+
+test("an unset or template identity displays Vellum OS", async () => {
+  const fallback = renderDesktopWallpaper(480, 300, null, null, "Vellum");
+  expect(await renderCurrentDesktopWallpaper(480, 300)).toEqual(fallback);
+  writeFileSync(
+    join(workspace, "IDENTITY.md"),
+    "- **Name:** _(not yet chosen)_\n",
+  );
+  expect(await renderCurrentDesktopWallpaper(480, 300)).toEqual(fallback);
+});
+
+test("long names fit inside the wallpaper without losing the wordmark", async () => {
+  const png = renderDesktopWallpaper(480, 300, null, null, "W".repeat(32));
+  const pixels = await wordmarkPixels(png);
+  expect(pixels.length).toBeGreaterThan(100);
+  expect(pixels.every(({ x }) => x > 480 * 0.13 && x < 480 * 0.87)).toBe(true);
+});
+
+test("names containing XML are rendered as text without injecting SVG shapes", async () => {
+  const name =
+    'Alice & </text><rect width="480" height="300" fill="red"/><text>';
+  const png = renderDesktopWallpaper(480, 300, null, null, name);
+  const fallback = renderDesktopWallpaper(480, 300, null, null);
+  const top = { left: 0, top: 0, width: 480, height: 150 };
+  expect(await sharp(png).extract(top).raw().toBuffer()).toEqual(
+    await sharp(fallback).extract(top).raw().toBuffer(),
+  );
+  expect((await wordmarkPixels(png)).length).toBeGreaterThan(0);
+});

package/src/desktop/desktop-wallpaper.ts

@@ -0,0 +1,113 @@
+import { readAvatarState } from "../avatar/avatar-manifest.js";
+import {
+  renderNotificationAvatarPng,
+  resolveNotificationAccentHex,
+} from "../avatar/notification-avatar.js";
+import { getResvg, isResvgAvailable } from "../avatar/resvg-lazy.js";
+import { isTemplatePlaceholder } from "../daemon/handlers/identity.js";
+import { getAssistantName } from "../daemon/identity-helpers.js";
+import { escapeXmlContent } from "../util/xml.js";
+
+function wallpaperWordmark(
+  width: number,
+  height: number,
+  name: string | null,
+): string {
+  const normalized = name?.replace(/\s+/g, " ").trim();
+  const label =
+    normalized && !isTemplatePlaceholder(normalized) ? normalized : "Vellum";
+  const text = `<text id="wordmark" font-family="Liberation Sans, Arial, sans-serif" font-size="64" font-weight="700" letter-spacing="1.5">${escapeXmlContent(`${label} OS`)}</text>`;
+  const Resvg = getResvg();
+  const bounds = new Resvg(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">${text}</svg>`,
+  ).getBBox();
+  if (!bounds || bounds.width === 0) {
+    return "";
+  }
+  const depth = 6;
+  const scale = Math.min(
+    (height * 0.06) / 64,
+    (width * 0.72) / (bounds.width + depth),
+  );
+  const x = width / 2 - (bounds.x + (bounds.width + depth) / 2) * scale;
+  const layers = Array.from({ length: depth }, (_, index) => {
+    const offset = depth - index;
+    return `<use href="#wordmark" transform="translate(${offset} ${offset})" fill="#40535b"/>`;
+  }).join("");
+  return `<defs>
+    ${text}
+    <linearGradient id="letter-face" x2="0" y2="1">
+      <stop stop-color="#ffffff"/><stop offset=".48" stop-color="#e0e9e7"/>
+      <stop offset="1" stop-color="#9eb4ba"/>
+    </linearGradient>
+  </defs>
+  <g transform="translate(${x} ${height * 0.69}) scale(${scale})">
+    <use href="#wordmark" transform="translate(9 12)" fill="#080f14" opacity=".35"/>
+    ${layers}
+    <use href="#wordmark" fill="url(#letter-face)" stroke="#e8f1ed" stroke-opacity=".4" stroke-width=".5"/>
+  </g>`;
+}
+
+export function renderDesktopWallpaper(
+  width: number,
+  height: number,
+  avatar: Buffer | null,
+  accentHex: string | null,
+  assistantName: string | null = null,
+): Buffer {
+  const accent = /^#[\da-f]{6}$/i.test(accentHex ?? "")
+    ? accentHex!
+    : "#91a6b0";
+  const cx = width / 2;
+  const cy = height * 0.46;
+  const size = Math.min(width, height) * 0.24;
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">
+    <defs>
+      <linearGradient id="base" x2="1" y2="1">
+        <stop stop-color="#202a30"/><stop offset="1" stop-color="#10171c"/>
+      </linearGradient>
+      <radialGradient id="glow">
+        <stop stop-color="${accent}" stop-opacity=".24"/>
+        <stop offset="1" stop-color="${accent}" stop-opacity="0"/>
+      </radialGradient>
+      <radialGradient id="shadow">
+        <stop stop-color="#000" stop-opacity=".25"/>
+        <stop offset="1" stop-color="#000" stop-opacity="0"/>
+      </radialGradient>
+    </defs>
+    <path fill="url(#base)" d="M0 0H${width}V${height}H0z"/>
+    <ellipse cx="${cx}" cy="${cy}" rx="${height * 0.7}" ry="${height * 0.6}" fill="url(#glow)"/>
+    <g fill="none" stroke="${accent}">
+      <circle cx="${cx}" cy="${cy}" r="${size * 0.76}" stroke-opacity=".16"/>
+      <circle cx="${cx}" cy="${cy}" r="${size * 1.25}" stroke-opacity=".09"/>
+      <circle cx="${cx}" cy="${cy}" r="${size * 1.9}" stroke-opacity=".05"/>
+    </g>
+    ${
+      avatar
+        ? `<ellipse cx="${cx}" cy="${cy + size * 0.48}" rx="${size * 0.7}" ry="${size * 0.16}" fill="url(#shadow)"/>
+    <image x="${cx - size / 2}" y="${cy - size / 2}" width="${size}" height="${size}" href="data:image/png;base64,${avatar.toString("base64")}"/>`
+        : ""
+    }
+    ${wallpaperWordmark(width, height, assistantName)}
+  </svg>`;
+  const Resvg = getResvg();
+  return Buffer.from(new Resvg(svg).render().asPng());
+}
+
+export async function renderCurrentDesktopWallpaper(
+  width: number,
+  height: number,
+): Promise<Buffer | null> {
+  if (!isResvgAvailable()) {
+    return null;
+  }
+  const state = readAvatarState();
+  const name = getAssistantName();
+  return renderDesktopWallpaper(
+    width,
+    height,
+    await renderNotificationAvatarPng(state),
+    resolveNotificationAccentHex(state),
+    name,
+  );
+}

package/src/desktop/desktop-window-theme.ts

@@ -0,0 +1,170 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { escapeXmlAttr, escapeXmlContent } from "../util/xml.js";
+
+const BUTTON_MASKS = {
+  close: [0x201, 0x102, 0x084, 0x048, 0x030, 0x030, 0x048, 0x084, 0x102, 0x201],
+  max: [0x3ff, 0x201, 0x201, 0x201, 0x201, 0x201, 0x201, 0x201, 0x201, 0x3ff],
+  max_toggled: [
+    0x3fc, 0x204, 0x27f, 0x241, 0x241, 0x241, 0x3c1, 0x041, 0x041, 0x07f,
+  ],
+  iconify: [0, 0, 0, 0, 0x3ff, 0x3ff, 0, 0, 0, 0],
+};
+
+function windowTheme(accentHex: string | null): string {
+  const tint = (base: string, amount: number): string => {
+    if (!accentHex || !/^#[\da-f]{6}$/i.test(accentHex)) {
+      return base;
+    }
+    return (
+      "#" +
+      [1, 3, 5]
+        .map((offset) => {
+          const from = parseInt(base.slice(offset, offset + 2), 16);
+          const to = parseInt(accentHex.slice(offset, offset + 2), 16);
+          return Math.round(from + (to - from) * amount)
+            .toString(16)
+            .padStart(2, "0");
+        })
+        .join("")
+    );
+  };
+  return `
+border.width: 1
+padding.width: 8
+padding.height: 7
+window.client.padding.width: 0
+window.client.padding.height: 0
+window.handle.width: 3
+window.label.text.justify: Center
+window.*.label.text.font: shadow=n
+window.*.title.bg: Flat Solid
+window.*.label.bg: Parentrelative
+window.*.handle.bg: Flat Solid
+window.*.grip.bg: Flat Solid
+window.*.button.*.bg: Parentrelative
+window.*.button.*.hover.bg: Flat Solid
+window.*.button.*.pressed.bg: Flat Solid
+window.active.title.bg: Flat Gradient Horizontal
+window.active.title.bg.color: ${tint("#292930", 0.28)}
+window.active.title.bg.colorTo: #292930
+window.active.border.color: #4a4a54
+window.active.title.separator.color: #202026
+window.active.label.text.color: #f0f0f4
+window.active.handle.bg.color: #292930
+window.active.grip.bg.color: #292930
+window.active.button.*.image.color: #d4d4dc
+window.active.button.*.hover.bg.color: ${tint("#45454f", 0.22)}
+window.active.button.*.pressed.bg.color: ${tint("#555561", 0.18)}
+window.active.button.*.disabled.image.color: #62626e
+window.active.button.close.hover.bg.color: #b64150
+window.active.button.close.pressed.bg.color: #963442
+window.inactive.title.bg.color: #232329
+window.inactive.border.color: #36363f
+window.inactive.title.separator.color: #202026
+window.inactive.label.text.color: #a6a6b2
+window.inactive.handle.bg.color: #232329
+window.inactive.grip.bg.color: #232329
+window.inactive.button.*.image.color: #858592
+window.inactive.button.*.hover.bg.color: #3b3b45
+window.inactive.button.*.pressed.bg.color: #4a4a54
+window.inactive.button.*.disabled.image.color: #565660
+menu.border.width: 1
+menu.border.color: #4a4a54
+menu.title.bg: Flat Solid
+menu.title.bg.color: #292930
+menu.title.text.color: #f0f0f4
+menu.title.text.font: shadow=n
+menu.items.bg: Flat Solid
+menu.items.bg.color: #232329
+menu.items.text.color: #e6e6ee
+menu.items.disabled.text.color: #858592
+menu.items.active.bg: Flat Solid
+menu.items.active.bg.color: #45454f
+menu.items.active.text.color: #ffffff
+menu.items.active.disabled.text.color: #a6a6b2
+menu.separator.color: #45454f
+osd.bg: Flat Solid
+osd.bg.color: #292930
+osd.border.color: #4a4a54
+osd.label.text.color: #f0f0f4
+`;
+}
+
+/** Keep Openbox bindings and placement rules while styling its decorations. */
+export function writeDesktopWindowTheme(
+  configDir: string,
+  home?: string,
+  accentHex: string | null = null,
+): string {
+  let source: string | undefined;
+  let sourcePath = "";
+  const candidates = [
+    ...(home ? [join(home, ".config", "openbox", "rc.xml")] : []),
+    "/etc/xdg/openbox/rc.xml",
+  ];
+  for (const path of candidates) {
+    try {
+      source = readFileSync(path, "utf8");
+      sourcePath = path;
+      break;
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw err;
+      }
+    }
+  }
+  if (!source || !/<theme>[^]*?<\/theme>/.test(source)) {
+    throw new Error("Openbox theme configuration is unavailable");
+  }
+  const root = source.match(/<openbox_config\b[^>]*>/)?.[0];
+  if (!root || /\bxml:base\s*=/.test(root)) {
+    throw new Error("Openbox configuration requires its original base URI");
+  }
+  // Relative XIncludes keep resolving beside the source configuration.
+  source = source.replace(root, () =>
+    root.replace(
+      "<openbox_config",
+      `<openbox_config xml:base="${escapeXmlAttr(pathToFileURL(sourcePath).href)}"`,
+    ),
+  );
+  const themeDir = join(configDir, "window-theme");
+  mkdirSync(join(themeDir, "openbox-3"), { recursive: true });
+  writeFileSync(
+    join(themeDir, "openbox-3", "themerc"),
+    windowTheme(accentHex).trimStart(),
+  );
+  for (const [name, rows] of Object.entries(BUTTON_MASKS)) {
+    const bytes = rows.flatMap((row) => [row & 0xff, row >> 8]);
+    writeFileSync(
+      join(themeDir, "openbox-3", `${name}.xbm`),
+      `#define button_width 10\n#define button_height 10\nstatic unsigned char button_bits[] = {\n${bytes.map((byte) => `0x${byte.toString(16)}`).join(",")}};\n`,
+    );
+  }
+  const fonts = [
+    "ActiveWindow",
+    "InactiveWindow",
+    "MenuHeader",
+    "MenuItem",
+    "ActiveOnScreenDisplay",
+    "InactiveOnScreenDisplay",
+  ].map(
+    (place) =>
+      `<font place="${place}"><name>sans</name><size>10</size><weight>normal</weight><slant>normal</slant></font>`,
+  );
+  const theme = `<theme>
+  <name>${escapeXmlContent(themeDir)}</name>
+  <titleLayout>LIMC</titleLayout>
+  <keepBorder>yes</keepBorder>
+  <animateIconify>yes</animateIconify>
+  ${fonts.join("\n  ")}
+</theme>`;
+  const configPath = join(configDir, "window-manager.xml");
+  writeFileSync(
+    configPath,
+    source.replace(/<theme>[^]*?<\/theme>/, () => theme),
+  );
+  return configPath;
+}

package/src/hooks/types.ts

@@ -679,3 +679,36 @@ export interface ConversationDeletedContext
  * {@link BaseHookContext}.
  */
 export type ConversationsClearedContext = BaseHookContext;
+
+// ─── Message-deleted hook context ────────────────────────────────────────────
+
+/**
+ * Context passed to the `message-deleted` hook. Fires once per deleted
+ * message row, from the shared single-message delete primitive, after the row
+ * is removed. Whole-conversation deletes dispatch `conversation-deleted`
+ * instead.
+ *
+ * Fire-and-forget like `conversation-deleted`: the primitive is synchronous
+ * and does not wait for the chain. The row is gone by the time a hook runs,
+ * so the context carries the row's `createdAt` alongside its id. Together
+ * they are the `(createdAt, id)` position the row held, which is what a hook
+ * keeping a cursor on that row needs to record once the row can no longer be
+ * looked up. The default memory plugin contributes a hook here that stamps
+ * its retrospective cursor.
+ */
+export interface MessageDeletedInputContext {
+  /** ID of the conversation that owned the row. */
+  readonly conversationId: string;
+  /** ID of the deleted message row. */
+  readonly messageId: string;
+  /** The deleted row's `createdAt`. */
+  readonly createdAt: number;
+}
+
+/**
+ * The full `message-deleted` context a hook receives: the dispatching call
+ * site's {@link MessageDeletedInputContext} plus the pipeline-stamped
+ * {@link BaseHookContext} capabilities.
+ */
+export interface MessageDeletedContext
+  extends MessageDeletedInputContext, BaseHookContext {}

package/src/i18n/AGENTS.md

@@ -0,0 +1,22 @@
+# Daemon i18n
+
+User-facing copy the assistant generates as a hardcoded constant goes
+through `assistant/src/i18n/`. The web app has its own catalogs. This
+module is for constants the daemon writes or emits.
+
+## Rules
+
+1. Add a key to `MESSAGE_KEYS` and to every locale in `MESSAGE_CATALOGS`.
+2. Persist the key when a column holds a system constant. Never persist a
+   translated string.
+3. Resolve with `t(key, locale)` or a typed helper (`resolveConversationTitle`)
+   at the edge that emits the string.
+4. Do not match stored display strings back to keys. A stored title may be
+   in any language on purpose.
+5. Locale comes from `Accept-Language` (`localeFromAcceptLanguage`) or an
+   explicit CLI flag. Default `en` lives in this module, not at each caller.
+
+Conversation titles persist `conversation.title.generating` /
+`conversation.title.untitled`. `resolveConversationTitle` turns those keys
+into catalog copy. Legacy English placeholders stay replaceable via the
+title service patterns and pass through on the wire until they are retitled.

package/src/i18n/__tests__/i18n.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  DEFAULT_LOCALE,
+  isMessageKey,
+  localeFromAcceptLanguage,
+  MESSAGE_CATALOGS,
+  MESSAGE_KEYS,
+  negotiateLocale,
+  resolveConversationTitle,
+  SUPPORTED_LOCALES,
+  t,
+} from "../index.js";
+
+describe("negotiateLocale", () => {
+  test("matches a full shipped tag", () => {
+    expect(negotiateLocale(["es"])).toBe("es");
+    expect(negotiateLocale(["zh-TW"])).toBe("zh-TW");
+  });
+
+  test("falls back from a regional tag to the primary language", () => {
+    expect(negotiateLocale(["es-MX", "en"])).toBe("es");
+  });
+
+  test("maps Traditional Chinese tags to zh-TW", () => {
+    expect(negotiateLocale(["zh-Hant"])).toBe("zh-TW");
+    expect(negotiateLocale(["zh-HK"])).toBe("zh-TW");
+  });
+
+  test("defaults when nothing matches", () => {
+    expect(negotiateLocale([])).toBe(DEFAULT_LOCALE);
+    expect(negotiateLocale(["xx"])).toBe(DEFAULT_LOCALE);
+  });
+});
+
+describe("localeFromAcceptLanguage", () => {
+  test("honors quality values", () => {
+    expect(localeFromAcceptLanguage("fr;q=0.8, es;q=0.9, en;q=0.5")).toBe(
+      "es",
+    );
+  });
+
+  test("defaults on missing or empty", () => {
+    expect(localeFromAcceptLanguage(null)).toBe(DEFAULT_LOCALE);
+    expect(localeFromAcceptLanguage("")).toBe(DEFAULT_LOCALE);
+  });
+});
+
+describe("catalog completeness", () => {
+  test("every locale has every key", () => {
+    const keys = Object.values(MESSAGE_KEYS);
+    for (const locale of SUPPORTED_LOCALES) {
+      for (const key of keys) {
+        expect(MESSAGE_CATALOGS[locale][key].length).toBeGreaterThan(0);
+      }
+    }
+  });
+});
+
+describe("t", () => {
+  test("resolves generating and untitled per locale", () => {
+    expect(t(MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING, "en")).toBe(
+      "Generating title...",
+    );
+    expect(t(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED, "en")).toBe(
+      "Untitled Conversation",
+    );
+    expect(t(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED, "es")).toBe(
+      "Sin título",
+    );
+  });
+});
+
+describe("resolveConversationTitle", () => {
+  test("resolves a stored key and an empty title", () => {
+    expect(
+      resolveConversationTitle(MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING, "zh"),
+    ).toBe("标题生成中...");
+    expect(resolveConversationTitle(null, "es")).toBe("Sin título");
+    expect(resolveConversationTitle("")).toBe("Untitled Conversation");
+  });
+
+  test("passes stored display strings through, including English placeholders", () => {
+    expect(resolveConversationTitle("Untitled Conversation", "es")).toBe(
+      "Untitled Conversation",
+    );
+    expect(resolveConversationTitle("Generating title...", "zh")).toBe(
+      "Generating title...",
+    );
+    expect(resolveConversationTitle("Auth Middleware Rewrite", "es")).toBe(
+      "Auth Middleware Rewrite",
+    );
+  });
+
+  test("defaults locale inside the helper", () => {
+    expect(
+      resolveConversationTitle(MESSAGE_KEYS.CONVERSATION_TITLE_GENERATING),
+    ).toBe("Generating title...");
+  });
+});
+
+describe("isMessageKey", () => {
+  test("recognizes catalog keys only", () => {
+    expect(isMessageKey(MESSAGE_KEYS.CONVERSATION_TITLE_UNTITLED)).toBe(true);
+    expect(isMessageKey("Untitled Conversation")).toBe(false);
+    expect(isMessageKey("Untitled")).toBe(false);
+  });
+});

package/src/i18n/index.ts

@@ -0,0 +1,16 @@
+export {
+  DEFAULT_LOCALE,
+  isSupportedLocale,
+  localeFromAcceptLanguage,
+  negotiateLocale,
+  SUPPORTED_LOCALES,
+  type SupportedLocale,
+} from "./locales.js";
+export {
+  isMessageKey,
+  MESSAGE_CATALOGS,
+  MESSAGE_KEYS,
+  type MessageKey,
+  t,
+} from "./messages.js";
+export { resolveConversationTitle } from "./title.js";