@vellumai/cli 0.11.11-staging.1 → 0.11.11-staging.2

package/node_modules/@vellumai/avatar-manifest/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./accent": "./src/accent.ts"
+    "./accent": "./src/accent.ts",
+    "./notification-avatar": "./src/notification-avatar.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+  NOTIFICATION_AVATAR_INSET,
+  NOTIFICATION_AVATAR_MAX_BYTES,
+  NOTIFICATION_AVATAR_MAX_LOCAL_BYTES,
+  NOTIFICATION_AVATAR_SIZE,
+  NOTIFICATION_AVATAR_SPEC_VERSION,
+  notificationAvatarDiscHex,
+  notificationAvatarGeometry,
+  notificationAvatarSvg,
+} from "../notification-avatar.js";
+
+function allAttributes(tag: string, svg: string): Record<string, string>[] {
+  return [...svg.matchAll(new RegExp(`<${tag}\\s([^>]*)/>`, "g"))].map(
+    (match) => {
+      const out: Record<string, string> = {};
+      for (const [, name, value] of match[1]!.matchAll(
+        /([\w:-]+)="([^"]*)"/g,
+      )) {
+        out[name!] = value!;
+      }
+      return out;
+    },
+  );
+}
+
+function attributes(tag: string, svg: string): Record<string, string> {
+  const all = allAttributes(tag, svg);
+  expect(all.length).toBeGreaterThan(0);
+  return all[0]!;
+}
+
+function countOf(tag: string, svg: string): number {
+  return svg.split(`<${tag}`).length - 1;
+}
+
+const PNG_BASE64 = "iVBORw0KGgo=";
+
+describe("notificationAvatarDiscHex", () => {
+  test("mixes the accent into white", () => {
+    expect(notificationAvatarDiscHex("#E9642F")).toBe("#FCE9E2");
+    expect(notificationAvatarDiscHex("#4C9B50")).toBe("#E6F1E7");
+  });
+
+  test("is case insensitive and always returns uppercase #RRGGBB", () => {
+    expect(notificationAvatarDiscHex("#e9642f")).toBe("#FCE9E2");
+  });
+
+  test("keeps white white and lifts black to near white", () => {
+    expect(notificationAvatarDiscHex("#FFFFFF")).toBe("#FFFFFF");
+    expect(notificationAvatarDiscHex("#000000")).toBe("#DBDBDB");
+  });
+
+  test.each([
+    ["null", null],
+    ["short form", "#abc"],
+    ["no hash", "e9642f"],
+    ["garbage", "not a colour"],
+    ["empty", ""],
+  ])("falls back to the neutral disc for %s", (_label, value) => {
+    expect(notificationAvatarDiscHex(value as string | null)).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarSvg", () => {
+  test("draws one disc and one inset avatar at the default size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(countOf("svg", svg)).toBe(1);
+    expect(countOf("image", svg)).toBe(1);
+
+    expect(svg.startsWith("<svg ")).toBe(true);
+    expect(svg).toContain(`width="256" height="256"`);
+    expect(svg).toContain(`viewBox="0 0 256 256"`);
+
+    const circle = attributes("circle", svg);
+    expect(circle).toMatchObject({ cx: "128", cy: "128", r: "128" });
+    expect(circle.fill).toBe("#FCE9E2");
+
+    const inset = NOTIFICATION_AVATAR_SIZE * NOTIFICATION_AVATAR_INSET;
+    const inner = NOTIFICATION_AVATAR_SIZE - 2 * inset;
+    const image = attributes("image", svg);
+    expect(Number(image.x)).toBeCloseTo(inset, 3);
+    expect(Number(image.y)).toBeCloseTo(inset, 3);
+    expect(Number(image.width)).toBeCloseTo(inner, 3);
+    expect(Number(image.height)).toBeCloseTo(inner, 3);
+    expect(image.href).toBe(`data:image/png;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("cover-crops a non-square raster and clips it to the disc", () => {
+    // The builder never sees the source dimensions, so what makes a 1024x512
+    // upload fill the square instead of letterboxing is the pair of attributes
+    // asserted here.
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.preserveAspectRatio).toBe("xMidYMid slice");
+
+    const clipRef = image["clip-path"]!;
+    const clipId = clipRef.match(/^url\(#([\w-]+)\)$/)?.[1];
+    expect(clipId).toBeTruthy();
+    expect(svg).toContain(`<clipPath id="${clipId}">`);
+
+    // The clip circle carries the disc geometry and nothing else, so the
+    // painted disc and the boundary can never drift apart.
+    const [disc, clip] = allAttributes("circle", svg);
+    expect(clip).toEqual({ cx: "128", cy: "128", r: "128" });
+    expect(disc).toMatchObject({ cx: "128", cy: "128", r: "128" });
+  });
+
+  test("scales the geometry to a custom size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+      size: 100,
+    });
+
+    expect(svg).toContain(`width="100" height="100"`);
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: "50",
+      cy: "50",
+      r: "50",
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: "11",
+      y: "11",
+      width: "78",
+      height: "78",
+    });
+  });
+
+  test("carries a non-PNG inner raster with its own media type", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      innerMediaType: "image/jpeg",
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.href).toBe(`data:image/jpeg;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("paints the fallback disc when there is no accent", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+    });
+    expect(attributes("circle", svg).fill).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarGeometry", () => {
+  test("derives the disc, the border and the avatar edge from the size", () => {
+    expect(notificationAvatarGeometry(100)).toEqual({
+      radius: 50,
+      offset: 11,
+      inner: 78,
+    });
+  });
+
+  test("measures the default size when given none", () => {
+    expect(notificationAvatarGeometry()).toEqual(
+      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    );
+  });
+
+  test("is the geometry the SVG is drawn with", () => {
+    const size = 100;
+    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+      size,
+    });
+
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: String(radius),
+      cy: String(radius),
+      r: String(radius),
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: String(offset),
+      y: String(offset),
+      width: String(inner),
+      height: String(inner),
+    });
+  });
+});
+
+describe("the transport contract", () => {
+  test("caps a notification PNG at 128 KB for the platform sync", () => {
+    expect(NOTIFICATION_AVATAR_MAX_BYTES).toBe(128 * 1024);
+  });
+
+  test("gives the local desktop path a looser cap of its own", () => {
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBe(512 * 1024);
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBeGreaterThan(
+      NOTIFICATION_AVATAR_MAX_BYTES,
+    );
+  });
+
+  test("stamps the drawing with a spec version", () => {
+    expect(Number.isInteger(NOTIFICATION_AVATAR_SPEC_VERSION)).toBe(true);
+    expect(NOTIFICATION_AVATAR_SPEC_VERSION).toBeGreaterThan(0);
+  });
+});

package/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -0,0 +1,139 @@
+/**
+ * The notification avatar: the assistant's avatar centered on an accent-tinted
+ * disc, the icon a native notification shows as the sender.
+ *
+ * The disc is inscribed in the square, so the four corners stay transparent.
+ * That is deliberate: iOS, Android, and the Windows toast logo slot all
+ * circle-crop what they are handed, and a square of colour behind the disc
+ * would only show through as a ring on any surface that does not crop. The
+ * disc itself is fully opaque, and so is everything inside it.
+ *
+ * Every platform draws the same picture with a different rasterizer (resvg in
+ * the daemon, a canvas in the desktop renderer), so the geometry and the disc
+ * colour live here once. Pure arithmetic and string building, no decoder and
+ * no node builtins, so a browser can call it too.
+ */
+
+import { isAvatarAccentHex } from "./accent.js";
+
+/** Output edge in pixels: large enough for an iOS notification thumbnail. */
+export const NOTIFICATION_AVATAR_SIZE = 256;
+
+/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+export const NOTIFICATION_AVATAR_INSET = 0.11;
+
+/** The disc when the assistant has no accent. */
+export const NOTIFICATION_AVATAR_FALLBACK_DISC_HEX = "#ECEFEA";
+
+/** How much of the accent survives the mix into white. */
+const ACCENT_MIX = 0.14;
+
+/**
+ * Largest notification PNG the platform sync ships, in bytes. It bounds the
+ * `notification_avatar_base64` field of the PATCH that uploads the disc, which
+ * is what APNs and FCM later hand their clients a URL and a hash for. A
+ * photographic avatar is quantised (or dropped) to fit.
+ */
+export const NOTIFICATION_AVATAR_MAX_BYTES = 128 * 1024;
+
+/**
+ * Largest notification PNG the local desktop path carries, in bytes. The
+ * renderer composites the disc, hands it to the Electron host over IPC and the
+ * host caches it on disk, so nothing crosses a push transport and a
+ * photographic avatar that renders past the sync cap still shows.
+ */
+export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
+
+/**
+ * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
+ * a disc rendered by an older spec even when the avatar itself is unchanged.
+ */
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+
+/** The id the inner raster's clip path is referenced by inside the document. */
+const CLIP_ID = "notification-avatar-disc";
+
+/**
+ * The disc fill for an accent: the accent mixed into white, so the avatar reads
+ * against it at notification size. Uppercase `#RRGGBB`; the neutral fallback
+ * when there is no accent or the value is not a hex.
+ */
+export function notificationAvatarDiscHex(accentHex: string | null): string {
+  if (!isAvatarAccentHex(accentHex)) {
+    return NOTIFICATION_AVATAR_FALLBACK_DISC_HEX;
+  }
+  const rgb = parseInt(accentHex.slice(1), 16);
+  const mixed = (shift: number) => {
+    const channel = (rgb >> shift) & 0xff;
+    return Math.round(255 + (channel - 255) * ACCENT_MIX)
+      .toString(16)
+      .padStart(2, "0");
+  };
+  return `#${mixed(16)}${mixed(8)}${mixed(0)}`.toUpperCase();
+}
+
+/** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
+export type NotificationAvatarMediaType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/gif";
+
+/**
+ * The three measurements the drawing derives from the edge: the disc's radius,
+ * which is also its centre; the free border around the avatar; and the
+ * avatar's own edge. Every rasterizer reads them from here, so the daemon's
+ * SVG and the desktop canvas cannot drift.
+ */
+export function notificationAvatarGeometry(
+  size: number = NOTIFICATION_AVATAR_SIZE,
+): { radius: number; offset: number; inner: number } {
+  const offset = size * NOTIFICATION_AVATAR_INSET;
+  return { radius: size / 2, offset, inner: size - 2 * offset };
+}
+
+export interface NotificationAvatarSvgOptions {
+  /** The avatar raster to draw inside the disc, base64 with no data prefix. */
+  innerPngBase64: string;
+  /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
+  innerMediaType?: NotificationAvatarMediaType;
+  accentHex: string | null;
+  size?: number;
+}
+
+/** Trims the float noise a fractional inset leaves in the coordinates. */
+function px(value: number): string {
+  return String(Number(value.toFixed(3)));
+}
+
+/**
+ * The notification avatar as an SVG document: a filled disc with the avatar
+ * drawn inset into it.
+ *
+ * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
+ * canvas does, so a portrait or landscape upload fills the square instead of
+ * being letterboxed onto the disc. It is then clipped to the disc, so the disc
+ * edge is the hard boundary no matter how far a cover-crop overflows.
+ *
+ * The `<image href="data:...">` shape is the one `downscaleRaster()` in
+ * `assistant/src/platform/sync-avatar.ts` already feeds resvg, so the daemon's
+ * rasterizer is known to render it.
+ */
+export function notificationAvatarSvg({
+  innerPngBase64,
+  innerMediaType = "image/png",
+  accentHex,
+  size = NOTIFICATION_AVATAR_SIZE,
+}: NotificationAvatarSvgOptions): string {
+  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const href = `data:${innerMediaType};base64,${innerPngBase64}`;
+  const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+    `width="${px(size)}" height="${px(size)}" viewBox="0 0 ${px(size)} ${px(size)}">` +
+    `<circle ${disc} fill="${notificationAvatarDiscHex(accentHex)}"/>` +
+    `<defs><clipPath id="${CLIP_ID}"><circle ${disc}/></clipPath></defs>` +
+    `<image x="${px(offset)}" y="${px(offset)}" width="${px(inner)}" height="${px(inner)}" ` +
+    `preserveAspectRatio="xMidYMid slice" clip-path="url(#${CLIP_ID})" ` +
+    `href="${href}" xlink:href="${href}"/></svg>`
+  );
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/package.json

@@ -6,7 +6,8 @@
   "type": "module",
   "exports": {
     ".": "./src/index.ts",
-    "./accent": "./src/accent.ts"
+    "./accent": "./src/accent.ts",
+    "./notification-avatar": "./src/notification-avatar.ts"
   },
   "scripts": {
     "typecheck": "bunx tsc --noEmit",

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/src/__tests__/notification-avatar.test.ts

@@ -0,0 +1,220 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+  NOTIFICATION_AVATAR_INSET,
+  NOTIFICATION_AVATAR_MAX_BYTES,
+  NOTIFICATION_AVATAR_MAX_LOCAL_BYTES,
+  NOTIFICATION_AVATAR_SIZE,
+  NOTIFICATION_AVATAR_SPEC_VERSION,
+  notificationAvatarDiscHex,
+  notificationAvatarGeometry,
+  notificationAvatarSvg,
+} from "../notification-avatar.js";
+
+function allAttributes(tag: string, svg: string): Record<string, string>[] {
+  return [...svg.matchAll(new RegExp(`<${tag}\\s([^>]*)/>`, "g"))].map(
+    (match) => {
+      const out: Record<string, string> = {};
+      for (const [, name, value] of match[1]!.matchAll(
+        /([\w:-]+)="([^"]*)"/g,
+      )) {
+        out[name!] = value!;
+      }
+      return out;
+    },
+  );
+}
+
+function attributes(tag: string, svg: string): Record<string, string> {
+  const all = allAttributes(tag, svg);
+  expect(all.length).toBeGreaterThan(0);
+  return all[0]!;
+}
+
+function countOf(tag: string, svg: string): number {
+  return svg.split(`<${tag}`).length - 1;
+}
+
+const PNG_BASE64 = "iVBORw0KGgo=";
+
+describe("notificationAvatarDiscHex", () => {
+  test("mixes the accent into white", () => {
+    expect(notificationAvatarDiscHex("#E9642F")).toBe("#FCE9E2");
+    expect(notificationAvatarDiscHex("#4C9B50")).toBe("#E6F1E7");
+  });
+
+  test("is case insensitive and always returns uppercase #RRGGBB", () => {
+    expect(notificationAvatarDiscHex("#e9642f")).toBe("#FCE9E2");
+  });
+
+  test("keeps white white and lifts black to near white", () => {
+    expect(notificationAvatarDiscHex("#FFFFFF")).toBe("#FFFFFF");
+    expect(notificationAvatarDiscHex("#000000")).toBe("#DBDBDB");
+  });
+
+  test.each([
+    ["null", null],
+    ["short form", "#abc"],
+    ["no hash", "e9642f"],
+    ["garbage", "not a colour"],
+    ["empty", ""],
+  ])("falls back to the neutral disc for %s", (_label, value) => {
+    expect(notificationAvatarDiscHex(value as string | null)).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarSvg", () => {
+  test("draws one disc and one inset avatar at the default size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    expect(countOf("svg", svg)).toBe(1);
+    expect(countOf("image", svg)).toBe(1);
+
+    expect(svg.startsWith("<svg ")).toBe(true);
+    expect(svg).toContain(`width="256" height="256"`);
+    expect(svg).toContain(`viewBox="0 0 256 256"`);
+
+    const circle = attributes("circle", svg);
+    expect(circle).toMatchObject({ cx: "128", cy: "128", r: "128" });
+    expect(circle.fill).toBe("#FCE9E2");
+
+    const inset = NOTIFICATION_AVATAR_SIZE * NOTIFICATION_AVATAR_INSET;
+    const inner = NOTIFICATION_AVATAR_SIZE - 2 * inset;
+    const image = attributes("image", svg);
+    expect(Number(image.x)).toBeCloseTo(inset, 3);
+    expect(Number(image.y)).toBeCloseTo(inset, 3);
+    expect(Number(image.width)).toBeCloseTo(inner, 3);
+    expect(Number(image.height)).toBeCloseTo(inner, 3);
+    expect(image.href).toBe(`data:image/png;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("cover-crops a non-square raster and clips it to the disc", () => {
+    // The builder never sees the source dimensions, so what makes a 1024x512
+    // upload fill the square instead of letterboxing is the pair of attributes
+    // asserted here.
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.preserveAspectRatio).toBe("xMidYMid slice");
+
+    const clipRef = image["clip-path"]!;
+    const clipId = clipRef.match(/^url\(#([\w-]+)\)$/)?.[1];
+    expect(clipId).toBeTruthy();
+    expect(svg).toContain(`<clipPath id="${clipId}">`);
+
+    // The clip circle carries the disc geometry and nothing else, so the
+    // painted disc and the boundary can never drift apart.
+    const [disc, clip] = allAttributes("circle", svg);
+    expect(clip).toEqual({ cx: "128", cy: "128", r: "128" });
+    expect(disc).toMatchObject({ cx: "128", cy: "128", r: "128" });
+  });
+
+  test("scales the geometry to a custom size", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: "#E9642F",
+      size: 100,
+    });
+
+    expect(svg).toContain(`width="100" height="100"`);
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: "50",
+      cy: "50",
+      r: "50",
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: "11",
+      y: "11",
+      width: "78",
+      height: "78",
+    });
+  });
+
+  test("carries a non-PNG inner raster with its own media type", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      innerMediaType: "image/jpeg",
+      accentHex: "#E9642F",
+    });
+
+    const image = attributes("image", svg);
+    expect(image.href).toBe(`data:image/jpeg;base64,${PNG_BASE64}`);
+    expect(image["xlink:href"]).toBe(image.href);
+  });
+
+  test("paints the fallback disc when there is no accent", () => {
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+    });
+    expect(attributes("circle", svg).fill).toBe(
+      NOTIFICATION_AVATAR_FALLBACK_DISC_HEX,
+    );
+  });
+});
+
+describe("notificationAvatarGeometry", () => {
+  test("derives the disc, the border and the avatar edge from the size", () => {
+    expect(notificationAvatarGeometry(100)).toEqual({
+      radius: 50,
+      offset: 11,
+      inner: 78,
+    });
+  });
+
+  test("measures the default size when given none", () => {
+    expect(notificationAvatarGeometry()).toEqual(
+      notificationAvatarGeometry(NOTIFICATION_AVATAR_SIZE),
+    );
+  });
+
+  test("is the geometry the SVG is drawn with", () => {
+    const size = 100;
+    const { radius, offset, inner } = notificationAvatarGeometry(size);
+    const svg = notificationAvatarSvg({
+      innerPngBase64: PNG_BASE64,
+      accentHex: null,
+      size,
+    });
+
+    expect(attributes("circle", svg)).toMatchObject({
+      cx: String(radius),
+      cy: String(radius),
+      r: String(radius),
+    });
+    expect(attributes("image", svg)).toMatchObject({
+      x: String(offset),
+      y: String(offset),
+      width: String(inner),
+      height: String(inner),
+    });
+  });
+});
+
+describe("the transport contract", () => {
+  test("caps a notification PNG at 128 KB for the platform sync", () => {
+    expect(NOTIFICATION_AVATAR_MAX_BYTES).toBe(128 * 1024);
+  });
+
+  test("gives the local desktop path a looser cap of its own", () => {
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBe(512 * 1024);
+    expect(NOTIFICATION_AVATAR_MAX_LOCAL_BYTES).toBeGreaterThan(
+      NOTIFICATION_AVATAR_MAX_BYTES,
+    );
+  });
+
+  test("stamps the drawing with a spec version", () => {
+    expect(Number.isInteger(NOTIFICATION_AVATAR_SPEC_VERSION)).toBe(true);
+    expect(NOTIFICATION_AVATAR_SPEC_VERSION).toBeGreaterThan(0);
+  });
+});

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/avatar-manifest/src/notification-avatar.ts

@@ -0,0 +1,139 @@
+/**
+ * The notification avatar: the assistant's avatar centered on an accent-tinted
+ * disc, the icon a native notification shows as the sender.
+ *
+ * The disc is inscribed in the square, so the four corners stay transparent.
+ * That is deliberate: iOS, Android, and the Windows toast logo slot all
+ * circle-crop what they are handed, and a square of colour behind the disc
+ * would only show through as a ring on any surface that does not crop. The
+ * disc itself is fully opaque, and so is everything inside it.
+ *
+ * Every platform draws the same picture with a different rasterizer (resvg in
+ * the daemon, a canvas in the desktop renderer), so the geometry and the disc
+ * colour live here once. Pure arithmetic and string building, no decoder and
+ * no node builtins, so a browser can call it too.
+ */
+
+import { isAvatarAccentHex } from "./accent.js";
+
+/** Output edge in pixels: large enough for an iOS notification thumbnail. */
+export const NOTIFICATION_AVATAR_SIZE = 256;
+
+/** Free disc on each side, as a fraction of the edge; the avatar gets the rest. */
+export const NOTIFICATION_AVATAR_INSET = 0.11;
+
+/** The disc when the assistant has no accent. */
+export const NOTIFICATION_AVATAR_FALLBACK_DISC_HEX = "#ECEFEA";
+
+/** How much of the accent survives the mix into white. */
+const ACCENT_MIX = 0.14;
+
+/**
+ * Largest notification PNG the platform sync ships, in bytes. It bounds the
+ * `notification_avatar_base64` field of the PATCH that uploads the disc, which
+ * is what APNs and FCM later hand their clients a URL and a hash for. A
+ * photographic avatar is quantised (or dropped) to fit.
+ */
+export const NOTIFICATION_AVATAR_MAX_BYTES = 128 * 1024;
+
+/**
+ * Largest notification PNG the local desktop path carries, in bytes. The
+ * renderer composites the disc, hands it to the Electron host over IPC and the
+ * host caches it on disk, so nothing crosses a push transport and a
+ * photographic avatar that renders past the sync cap still shows.
+ */
+export const NOTIFICATION_AVATAR_MAX_LOCAL_BYTES = 512 * 1024;
+
+/**
+ * Bumped whenever the drawing above changes, so a sync keyed on it re-uploads
+ * a disc rendered by an older spec even when the avatar itself is unchanged.
+ */
+export const NOTIFICATION_AVATAR_SPEC_VERSION = 1;
+
+/** The id the inner raster's clip path is referenced by inside the document. */
+const CLIP_ID = "notification-avatar-disc";
+
+/**
+ * The disc fill for an accent: the accent mixed into white, so the avatar reads
+ * against it at notification size. Uppercase `#RRGGBB`; the neutral fallback
+ * when there is no accent or the value is not a hex.
+ */
+export function notificationAvatarDiscHex(accentHex: string | null): string {
+  if (!isAvatarAccentHex(accentHex)) {
+    return NOTIFICATION_AVATAR_FALLBACK_DISC_HEX;
+  }
+  const rgb = parseInt(accentHex.slice(1), 16);
+  const mixed = (shift: number) => {
+    const channel = (rgb >> shift) & 0xff;
+    return Math.round(255 + (channel - 255) * ACCENT_MIX)
+      .toString(16)
+      .padStart(2, "0");
+  };
+  return `#${mixed(16)}${mixed(8)}${mixed(0)}`.toUpperCase();
+}
+
+/** Raster formats an `<image>` href carries here; what resvg and a canvas both decode. */
+export type NotificationAvatarMediaType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/gif";
+
+/**
+ * The three measurements the drawing derives from the edge: the disc's radius,
+ * which is also its centre; the free border around the avatar; and the
+ * avatar's own edge. Every rasterizer reads them from here, so the daemon's
+ * SVG and the desktop canvas cannot drift.
+ */
+export function notificationAvatarGeometry(
+  size: number = NOTIFICATION_AVATAR_SIZE,
+): { radius: number; offset: number; inner: number } {
+  const offset = size * NOTIFICATION_AVATAR_INSET;
+  return { radius: size / 2, offset, inner: size - 2 * offset };
+}
+
+export interface NotificationAvatarSvgOptions {
+  /** The avatar raster to draw inside the disc, base64 with no data prefix. */
+  innerPngBase64: string;
+  /** What `innerPngBase64` holds; PNG unless an upload arrived as a JPEG or a GIF. */
+  innerMediaType?: NotificationAvatarMediaType;
+  accentHex: string | null;
+  size?: number;
+}
+
+/** Trims the float noise a fractional inset leaves in the coordinates. */
+function px(value: number): string {
+  return String(Number(value.toFixed(3)));
+}
+
+/**
+ * The notification avatar as an SVG document: a filled disc with the avatar
+ * drawn inset into it.
+ *
+ * The inner raster is cover-cropped (`xMidYMid slice`), matching what the web
+ * canvas does, so a portrait or landscape upload fills the square instead of
+ * being letterboxed onto the disc. It is then clipped to the disc, so the disc
+ * edge is the hard boundary no matter how far a cover-crop overflows.
+ *
+ * The `<image href="data:...">` shape is the one `downscaleRaster()` in
+ * `assistant/src/platform/sync-avatar.ts` already feeds resvg, so the daemon's
+ * rasterizer is known to render it.
+ */
+export function notificationAvatarSvg({
+  innerPngBase64,
+  innerMediaType = "image/png",
+  accentHex,
+  size = NOTIFICATION_AVATAR_SIZE,
+}: NotificationAvatarSvgOptions): string {
+  const { radius, offset, inner } = notificationAvatarGeometry(size);
+  const href = `data:${innerMediaType};base64,${innerPngBase64}`;
+  const disc = `cx="${px(radius)}" cy="${px(radius)}" r="${px(radius)}"`;
+  return (
+    `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" ` +
+    `width="${px(size)}" height="${px(size)}" viewBox="0 0 ${px(size)} ${px(size)}">` +
+    `<circle ${disc} fill="${notificationAvatarDiscHex(accentHex)}"/>` +
+    `<defs><clipPath id="${CLIP_ID}"><circle ${disc}/></clipPath></defs>` +
+    `<image x="${px(offset)}" y="${px(offset)}" width="${px(inner)}" height="${px(inner)}" ` +
+    `preserveAspectRatio="xMidYMid slice" clip-path="url(#${CLIP_ID})" ` +
+    `href="${href}" xlink:href="${href}"/></svg>`
+  );
+}

package/node_modules/@vellumai/local-mode/node_modules/@vellumai/service-contracts/src/reactions.ts

@@ -7,11 +7,13 @@
  * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
  * that separates the namespace from the name.
  *
- * `shortcode` is a name in a channel's own namespace whose kind the channel
- * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
- * for a workspace upload with nothing to tell them apart, and only the
- * workspace token can resolve the second. It is a distinct kind from
- * `unicode`, not a stand-in for an unknown one.
+ * `shortcode` is a name in a channel's own namespace that the channel's
+ * adapter could not place among the standard emoji. Slack sends `+1` and
+ * `blob_wave` alike, as names; its normalizer resolves the standard ones to
+ * `unicode` from Slack's own list, and what remains is a workspace upload
+ * only the workspace can render. It is a distinct kind from `unicode`, not
+ * a stand-in for an unknown one, and nothing past an adapter needs a
+ * channel's naming to read it.
  */
 import { z } from "zod";
 
@@ -39,6 +41,12 @@ export const ReactionEmojiFieldsSchema = z.object({
 });
 export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
 
+/** The typed fields with the kind and name known. */
+export type ReactionEmojiIdentity = ReactionEmojiFields & {
+  emojiKind: ReactionEmojiKind;
+  emojiName: string;
+};
+
 /**
  * The typed emoji fields a source actually carries, with undefined ones
  * omitted: an absent key and a present-but-undefined one serialize alike, but the
@@ -58,3 +66,75 @@ export function pickReactionEmojiFields(
       : {}),
   };
 }
+
+/**
+ * Parse Discord's custom-emoji mention form. The form travels the wire as a
+ * reaction's spelling, so more than one package reads it: the daemon rebuilds
+ * a REST path from it when the assistant reacts, and a row carrying only the
+ * spelling recovers its kind from it. One parser, so the two cannot disagree
+ * about what counts as one.
+ *
+ * `animated` reports whether the spelling carries the `a` marker. Discord's
+ * normalizer never writes that marker, so it is read only from spellings that
+ * arrive from elsewhere: a row written by another producer, or a value the
+ * model hands back as it received it.
+ */
+export function parseDiscordEmojiMention(
+  emoji: string,
+): { name: string; id: string; animated: boolean } | null {
+  const match = /^<(a?):([^:>]+):(\d+)>$/.exec(emoji);
+  return match
+    ? { name: match[2]!, id: match[3]!, animated: match[1] === "a" }
+    : null;
+}
+
+/**
+ * Recover an emoji's kind from its spelling alone. This is the one inference
+ * the design permits, reserved for a value that carries the string and no
+ * typed fields: a persisted row or a replayed retry payload. A value that
+ * declares its kind never reaches this; `reactionEmojiIdentity` makes that
+ * choice for every reader.
+ *
+ * A mention form is unambiguous. Past that the two remaining kinds are told
+ * apart by whether the string is a name at all: a channel's shortcode is
+ * ASCII word characters, optionally carrying Slack's `::skin-tone-N`
+ * suffix, and anything else is the character itself.
+ */
+export function classifyReactionEmojiSpelling(
+  emoji: string,
+): ReactionEmojiIdentity {
+  const custom = parseDiscordEmojiMention(emoji);
+  if (custom) {
+    // The plain `<:name:id>` form says nothing about animation: the
+    // normalizer spells every custom emoji that way and reports animation
+    // in the typed field instead, so a spelling without the `a` marker is
+    // "unrecorded", not "not animated". Only the `<a:` form asserts it.
+    return {
+      emojiKind: "custom",
+      emojiName: custom.name,
+      emojiId: custom.id,
+      ...(custom.animated ? { emojiAnimated: true } : {}),
+    };
+  }
+  return /^[\w+-]+(::skin-tone-[2-6])?$/.test(emoji)
+    ? { emojiKind: "shortcode", emojiName: emoji }
+    : { emojiKind: "unicode", emojiName: emoji };
+}
+
+/**
+ * The typed identity of a reaction's emoji: the fields it declares when it
+ * declares a kind, otherwise the kind recovered from its spelling. Every
+ * reader that must know what an emoji is goes through this, so the wire
+ * contract and the web agree on when the spelling is consulted.
+ */
+export function reactionEmojiIdentity(
+  reaction: { emoji: string } & ReactionEmojiFields,
+): ReactionEmojiIdentity {
+  return reaction.emojiKind !== undefined && reaction.emojiName !== undefined
+    ? {
+        ...pickReactionEmojiFields(reaction),
+        emojiKind: reaction.emojiKind,
+        emojiName: reaction.emojiName,
+      }
+    : classifyReactionEmojiSpelling(reaction.emoji);
+}

package/node_modules/@vellumai/service-contracts/src/reactions.ts

@@ -7,11 +7,13 @@
  * is spelled. Modelled on Zulip's `reaction_type`, the one surveyed system
  * that separates the namespace from the name.
  *
- * `shortcode` is a name in a channel's own namespace whose kind the channel
- * does not disclose: Slack sends `+1` for the standard emoji and `blob_wave`
- * for a workspace upload with nothing to tell them apart, and only the
- * workspace token can resolve the second. It is a distinct kind from
- * `unicode`, not a stand-in for an unknown one.
+ * `shortcode` is a name in a channel's own namespace that the channel's
+ * adapter could not place among the standard emoji. Slack sends `+1` and
+ * `blob_wave` alike, as names; its normalizer resolves the standard ones to
+ * `unicode` from Slack's own list, and what remains is a workspace upload
+ * only the workspace can render. It is a distinct kind from `unicode`, not
+ * a stand-in for an unknown one, and nothing past an adapter needs a
+ * channel's naming to read it.
  */
 import { z } from "zod";
 
@@ -39,6 +41,12 @@ export const ReactionEmojiFieldsSchema = z.object({
 });
 export type ReactionEmojiFields = z.infer<typeof ReactionEmojiFieldsSchema>;
 
+/** The typed fields with the kind and name known. */
+export type ReactionEmojiIdentity = ReactionEmojiFields & {
+  emojiKind: ReactionEmojiKind;
+  emojiName: string;
+};
+
 /**
  * The typed emoji fields a source actually carries, with undefined ones
  * omitted: an absent key and a present-but-undefined one serialize alike, but the
@@ -58,3 +66,75 @@ export function pickReactionEmojiFields(
       : {}),
   };
 }
+
+/**
+ * Parse Discord's custom-emoji mention form. The form travels the wire as a
+ * reaction's spelling, so more than one package reads it: the daemon rebuilds
+ * a REST path from it when the assistant reacts, and a row carrying only the
+ * spelling recovers its kind from it. One parser, so the two cannot disagree
+ * about what counts as one.
+ *
+ * `animated` reports whether the spelling carries the `a` marker. Discord's
+ * normalizer never writes that marker, so it is read only from spellings that
+ * arrive from elsewhere: a row written by another producer, or a value the
+ * model hands back as it received it.
+ */
+export function parseDiscordEmojiMention(
+  emoji: string,
+): { name: string; id: string; animated: boolean } | null {
+  const match = /^<(a?):([^:>]+):(\d+)>$/.exec(emoji);
+  return match
+    ? { name: match[2]!, id: match[3]!, animated: match[1] === "a" }
+    : null;
+}
+
+/**
+ * Recover an emoji's kind from its spelling alone. This is the one inference
+ * the design permits, reserved for a value that carries the string and no
+ * typed fields: a persisted row or a replayed retry payload. A value that
+ * declares its kind never reaches this; `reactionEmojiIdentity` makes that
+ * choice for every reader.
+ *
+ * A mention form is unambiguous. Past that the two remaining kinds are told
+ * apart by whether the string is a name at all: a channel's shortcode is
+ * ASCII word characters, optionally carrying Slack's `::skin-tone-N`
+ * suffix, and anything else is the character itself.
+ */
+export function classifyReactionEmojiSpelling(
+  emoji: string,
+): ReactionEmojiIdentity {
+  const custom = parseDiscordEmojiMention(emoji);
+  if (custom) {
+    // The plain `<:name:id>` form says nothing about animation: the
+    // normalizer spells every custom emoji that way and reports animation
+    // in the typed field instead, so a spelling without the `a` marker is
+    // "unrecorded", not "not animated". Only the `<a:` form asserts it.
+    return {
+      emojiKind: "custom",
+      emojiName: custom.name,
+      emojiId: custom.id,
+      ...(custom.animated ? { emojiAnimated: true } : {}),
+    };
+  }
+  return /^[\w+-]+(::skin-tone-[2-6])?$/.test(emoji)
+    ? { emojiKind: "shortcode", emojiName: emoji }
+    : { emojiKind: "unicode", emojiName: emoji };
+}
+
+/**
+ * The typed identity of a reaction's emoji: the fields it declares when it
+ * declares a kind, otherwise the kind recovered from its spelling. Every
+ * reader that must know what an emoji is goes through this, so the wire
+ * contract and the web agree on when the spelling is consulted.
+ */
+export function reactionEmojiIdentity(
+  reaction: { emoji: string } & ReactionEmojiFields,
+): ReactionEmojiIdentity {
+  return reaction.emojiKind !== undefined && reaction.emojiName !== undefined
+    ? {
+        ...pickReactionEmojiFields(reaction),
+        emojiKind: reaction.emojiKind,
+        emojiName: reaction.emojiName,
+      }
+    : classifyReactionEmojiSpelling(reaction.emoji);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vellumai/cli",
-  "version": "0.11.11-staging.1",
+  "version": "0.11.11-staging.2",
   "description": "CLI tools for vellum-assistant",
   "type": "module",
   "exports": {