@mycadet/cli 0.0.1 → 0.12.6-dev.202610072225.d7acd73

package/node_modules/@mycadet/local-mode/node_modules/@mycadet/avatar-manifest/src/__tests__/read.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { AVATAR_SIDECAR_MAX_BYTES, readWorkspaceAvatar } from "../read.js";
+
+const traits = { bodyShape: "round", eyeStyle: "dot", color: "#abc" };
+
+describe("readWorkspaceAvatar", () => {
+  let workspaceDir: string;
+  let avatarDir: string;
+
+  const write = (name: string, contents: string): void => {
+    mkdirSync(avatarDir, { recursive: true });
+    writeFileSync(join(avatarDir, name), contents);
+  };
+
+  beforeEach(() => {
+    workspaceDir = mkdtempSync(join(tmpdir(), "avatar-manifest-"));
+    avatarDir = join(workspaceDir, "data", "avatar");
+  });
+
+  afterEach(() => {
+    rmSync(workspaceDir, { recursive: true, force: true });
+  });
+
+  test("missing avatar dir yields none", () => {
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({ kind: "none" });
+  });
+
+  test("manifest character returns its traits", () => {
+    write("avatar.json", JSON.stringify({ kind: "character", traits }));
+    write("avatar-image.png", "png");
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({
+      kind: "character",
+      traits,
+    });
+  });
+
+  test("image resolves to the PNG path", () => {
+    write("avatar-image.png", "png");
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({
+      kind: "image",
+      imagePath: join(avatarDir, "avatar-image.png"),
+    });
+  });
+
+  test("corrupt manifest falls back to the traits sidecar", () => {
+    write("avatar.json", "{ not json");
+    write("character-traits.json", JSON.stringify(traits));
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({
+      kind: "character",
+      traits,
+    });
+  });
+
+  test("oversized sidecars are treated as absent", () => {
+    const padded = JSON.stringify({
+      kind: "character",
+      traits,
+      pad: "x".repeat(AVATAR_SIDECAR_MAX_BYTES),
+    });
+    write("avatar.json", padded);
+    write("character-traits.json", JSON.stringify({ ...traits, pad: padded }));
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({ kind: "none" });
+  });
+
+  test("a sidecar at the cap still reads", () => {
+    const body = JSON.stringify({ kind: "character", traits, pad: "" });
+    write(
+      "avatar.json",
+      body.replace(
+        '"pad":""',
+        `"pad":"${"x".repeat(AVATAR_SIDECAR_MAX_BYTES - body.length)}"`,
+      ),
+    );
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({
+      kind: "character",
+      traits,
+    });
+  });
+
+  test("a symlinked avatar dir is treated as absent", () => {
+    const foreign = mkdtempSync(join(tmpdir(), "foreign-avatar-"));
+    writeFileSync(
+      join(foreign, "character-traits.json"),
+      JSON.stringify({
+        bodyShape: "blob",
+        eyeStyle: "curious",
+        color: "green",
+      }),
+    );
+    mkdirSync(join(workspaceDir, "data"), { recursive: true });
+    symlinkSync(foreign, avatarDir);
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({ kind: "none" });
+    rmSync(foreign, { recursive: true, force: true });
+  });
+
+  test("symlinked sidecars are treated as absent", () => {
+    const outside = join(workspaceDir, "outside.json");
+    writeFileSync(outside, JSON.stringify({ kind: "character", traits }));
+    mkdirSync(avatarDir, { recursive: true });
+    symlinkSync(outside, join(avatarDir, "avatar.json"));
+    symlinkSync(outside, join(avatarDir, "character-traits.json"));
+    expect(readWorkspaceAvatar(workspaceDir)).toEqual({ kind: "none" });
+  });
+});

package/node_modules/@mycadet/local-mode/node_modules/@mycadet/avatar-manifest/src/accent.ts

@@ -0,0 +1,150 @@
+/**
+ * The avatar accent: the one colour every surface that tints itself to the
+ * assistant paints with.
+ *
+ * A character avatar's accent is its palette colour. An uploaded image has no
+ * colour as data, so one is read out of its pixels here. Pure pixel math with
+ * no decoder: the daemon feeds it a raster decoded by sharp and the web feeds
+ * it a canvas, and because both go through this one function they cannot
+ * disagree about what colour an image is.
+ */
+
+/** `#rrggbb` only: the one form CSS, the native hex parsers, and the colour picker all agree on. */
+const ACCENT_HEX_PATTERN = /^#[0-9a-f]{6}$/i;
+
+/** Whether `value` is a `#rrggbb` string. */
+export function isAvatarAccentHex(value: unknown): value is string {
+  return typeof value === "string" && ACCENT_HEX_PATTERN.test(value);
+}
+
+/**
+ * Canonical form of an accent hex (`#rrggbb`, lowercase), or null when the
+ * input is not one. Surrounding whitespace is tolerated because the value can
+ * arrive from a text field.
+ */
+export function normalizeAvatarAccentHex(value: unknown): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+  const trimmed = value.trim();
+  return ACCENT_HEX_PATTERN.test(trimmed) ? trimmed.toLowerCase() : null;
+}
+
+/** Pixels below this alpha are skipped: a cutout's transparent ground is not its colour. */
+const MIN_ALPHA = 128;
+
+/** Hue is bucketed this finely, so a gradient of one hue lands in one bin. */
+const HUE_BINS = 24;
+/** Chromatic bins are split by lightness this many ways, so a colour and its shadow stay apart. */
+const LIGHT_BANDS = 3;
+/** Below this saturation a pixel is counted as gray, bucketed by lightness alone. */
+const GRAY_SATURATION = 0.15;
+/** Gray bins by lightness. */
+const GRAY_BANDS = 5;
+
+interface Bin {
+  count: number;
+  r: number;
+  g: number;
+  b: number;
+  s: number;
+  l: number;
+}
+
+function rgbToHsl(
+  r: number,
+  g: number,
+  b: number,
+): { h: number; s: number; l: number } {
+  const rn = r / 255;
+  const gn = g / 255;
+  const bn = b / 255;
+  const max = Math.max(rn, gn, bn);
+  const min = Math.min(rn, gn, bn);
+  const l = (max + min) / 2;
+  const d = max - min;
+  if (d === 0) {
+    return { h: 0, s: 0, l };
+  }
+  const s = d / (1 - Math.abs(2 * l - 1));
+  let h: number;
+  if (max === rn) {
+    h = ((gn - bn) / d) % 6;
+  } else if (max === gn) {
+    h = (bn - rn) / d + 2;
+  } else {
+    h = (rn - gn) / d + 4;
+  }
+  h /= 6;
+  return { h: h < 0 ? h + 1 : h, s, l };
+}
+
+function toHex(r: number, g: number, b: number): string {
+  const ch = (v: number) => Math.max(0, Math.min(255, Math.round(v)));
+  return `#${((1 << 24) | (ch(r) << 16) | (ch(g) << 8) | ch(b)).toString(16).slice(1)}`;
+}
+
+/**
+ * How much a bin's colour deserves to be the accent, per pixel in it.
+ *
+ * Population alone picks the background: most uploads are a subject on white
+ * or black. Saturation and mid lightness weight the bin instead, so a red mark
+ * on a white ground reads as red while an all-gray photo still reads as gray,
+ * because with nothing colourful to beat, the gray bin's small weight wins.
+ */
+function salience(s: number, l: number): number {
+  return (0.1 + 0.9 * s) * Math.max(0.1, 1 - Math.abs(l - 0.5) * 1.6);
+}
+
+/**
+ * The most prevalent accent colour in a block of RGBA pixels, as `#rrggbb`, or
+ * null when no pixel is opaque enough to count.
+ *
+ * Pixels are bucketed by hue and lightness (grays by lightness alone), each
+ * bucket is scored by population times how much it looks like an accent
+ * (saturated, mid-toned), and the winner's mean colour is the answer. The
+ * mean rather than the bucket centre, so a brand's exact orange comes back
+ * as that orange and not the nearest of twenty-four hues.
+ */
+export function dominantAccentHex(pixels: ArrayLike<number>): string | null {
+  const bins = new Map<number, Bin>();
+  for (let i = 0; i + 3 < pixels.length; i += 4) {
+    if (pixels[i + 3]! < MIN_ALPHA) {
+      continue;
+    }
+    const r = pixels[i]!;
+    const g = pixels[i + 1]!;
+    const b = pixels[i + 2]!;
+    const { h, s, l } = rgbToHsl(r, g, b);
+    const key =
+      s < GRAY_SATURATION
+        ? -1 - Math.min(GRAY_BANDS - 1, Math.floor(l * GRAY_BANDS))
+        : Math.min(HUE_BINS - 1, Math.floor(h * HUE_BINS)) * LIGHT_BANDS +
+          Math.min(LIGHT_BANDS - 1, Math.floor(l * LIGHT_BANDS));
+    let bin = bins.get(key);
+    if (!bin) {
+      bin = { count: 0, r: 0, g: 0, b: 0, s: 0, l: 0 };
+      bins.set(key, bin);
+    }
+    bin.count += 1;
+    bin.r += r;
+    bin.g += g;
+    bin.b += b;
+    bin.s += s;
+    bin.l += l;
+  }
+
+  let best: Bin | null = null;
+  let bestScore = -1;
+  for (const bin of bins.values()) {
+    const score = bin.count * salience(bin.s / bin.count, bin.l / bin.count);
+    if (score > bestScore) {
+      best = bin;
+      bestScore = score;
+    }
+  }
+  if (!best) {
+    return null;
+  }
+  return toHex(best.r / best.count, best.g / best.count, best.b / best.count);
+}

package/node_modules/@mycadet/local-mode/node_modules/@mycadet/avatar-manifest/src/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @mycadet/avatar-manifest: the single source of truth for the on-disk
+ * avatar layout of an assistant workspace (`<workspace>/data/avatar`) and
+ * how its files resolve to an avatar.
+ *
+ * The daemon owns the files (it writes the manifest and sidecars); hosts
+ * such as the desktop app read them directly so a sleeping assistant still
+ * has an avatar in the chooser. Both go through the parsing and legacy
+ * derivation here so they cannot disagree. Leaf package: node builtins only.
+ */
+export {
+  AVATAR_IMAGE_FILENAME,
+  AVATAR_MANIFEST_FILENAME,
+  AVATAR_TRAITS_FILENAME,
+  resolveAvatarDir,
+} from "./layout.js";
+export {
+  dominantAccentHex,
+  isAvatarAccentHex,
+  normalizeAvatarAccentHex,
+} from "./accent.js";
+export {
+  deriveAvatarFromLegacyFiles,
+  parseAvatarManifest,
+} from "./manifest.js";
+export type {
+  AvatarAccent,
+  AvatarAccentSource,
+  AvatarImageMeta,
+  AvatarKind,
+  AvatarSource,
+  AvatarState,
+  CharacterTraits,
+} from "./manifest.js";
+export { readWorkspaceAvatar } from "./read.js";
+export type { WorkspaceAvatar } from "./read.js";

package/node_modules/@mycadet/local-mode/node_modules/@mycadet/avatar-manifest/src/layout.ts

@@ -0,0 +1,18 @@
+import { join } from "node:path";
+
+/** Path segments of the avatar directory below the workspace directory. */
+const AVATAR_DIR_SEGMENTS: readonly string[] = ["data", "avatar"];
+
+/** Avatar state manifest. */
+export const AVATAR_MANIFEST_FILENAME = "avatar.json";
+
+/** Legacy sidecar holding the persisted character traits. */
+export const AVATAR_TRAITS_FILENAME = "character-traits.json";
+
+/** The avatar PNG (uploaded, or rendered from the character traits). */
+export const AVATAR_IMAGE_FILENAME = "avatar-image.png";
+
+/** The avatar directory for a workspace (`<workspace>/data/avatar`). */
+export function resolveAvatarDir(workspaceDir: string): string {
+  return join(workspaceDir, ...AVATAR_DIR_SEGMENTS);
+}

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

@@ -0,0 +1,208 @@
+import { isAvatarAccentHex } from "./accent.js";
+
+export type AvatarKind = "character" | "image" | "none";
+export type AvatarSource = "builder" | "upload" | "ai";
+
+export interface CharacterTraits {
+  bodyShape: string;
+  eyeStyle: string;
+  color: string;
+}
+
+export interface AvatarImageMeta {
+  updatedAt: string;
+  etag: string;
+}
+
+/**
+ * Where an accent came from. `palette`: a character's chosen colour.
+ * `derived`: read out of an uploaded image's pixels. `custom`: set by the
+ * user over an image. Only the last is worth offering a reset from.
+ */
+export type AvatarAccentSource = "palette" | "derived" | "custom";
+
+/** The colour every avatar-tinted surface paints with, as `#rrggbb`. */
+export interface AvatarAccent {
+  hex: string;
+  source: AvatarAccentSource;
+}
+
+/** The persisted manifest (`avatar.json`). */
+export interface AvatarState {
+  kind: AvatarKind;
+  traits: CharacterTraits | null;
+  source: AvatarSource | null;
+  image: AvatarImageMeta | null;
+  /** Null for `none`, and for an image whose colour could not be read. */
+  accent: AvatarAccent | null;
+}
+
+const AVATAR_KINDS: ReadonlySet<string> = new Set<AvatarKind>([
+  "character",
+  "image",
+  "none",
+]);
+
+const AVATAR_SOURCES: ReadonlySet<string> = new Set<AvatarSource>([
+  "builder",
+  "upload",
+  "ai",
+]);
+
+const AVATAR_ACCENT_SOURCES: ReadonlySet<string> = new Set<AvatarAccentSource>([
+  "palette",
+  "derived",
+  "custom",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object";
+}
+
+/** Longest string any manifest field may carry (trait ids, etags, timestamps). */
+export const AVATAR_FIELD_MAX_LENGTH = 256;
+
+function isBoundedString(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    value.length > 0 &&
+    value.length <= AVATAR_FIELD_MAX_LENGTH
+  );
+}
+
+/** Narrows an unknown value to valid CharacterTraits (presence and length only). */
+function isValidCharacterTraits(value: unknown): value is CharacterTraits {
+  return (
+    isRecord(value) &&
+    isBoundedString(value.bodyShape) &&
+    isBoundedString(value.eyeStyle) &&
+    isBoundedString(value.color)
+  );
+}
+
+/** Narrows an unknown value to valid AvatarImageMeta (presence and length only). */
+function isValidAvatarImageMeta(value: unknown): value is AvatarImageMeta {
+  return (
+    isRecord(value) &&
+    isBoundedString(value.updatedAt) &&
+    isBoundedString(value.etag)
+  );
+}
+
+/**
+ * An accent is optional on the wire and in the file: manifests written before
+ * accents existed carry none, and an unreadable image has none. Anything not
+ * a well-formed accent normalizes to null rather than failing the manifest.
+ */
+function parseAvatarAccent(value: unknown): AvatarAccent | null {
+  if (
+    !isRecord(value) ||
+    !isAvatarAccentHex(value.hex) ||
+    typeof value.source !== "string" ||
+    !AVATAR_ACCENT_SOURCES.has(value.source)
+  ) {
+    return null;
+  }
+  return { hex: value.hex, source: value.source as AvatarAccentSource };
+}
+
+/**
+ * Validates a parsed `avatar.json`. Returns `null` for a non-object, an
+ * invalid or missing `kind`, or a valid `kind` whose per-kind payload is
+ * missing or malformed, so callers fall back to legacy derivation instead
+ * of surfacing an avatar with null traits/image. An unknown `source` and any
+ * payload irrelevant to the kind normalize to `null` rather than passing
+ * through, so the result always satisfies the wire shape.
+ */
+export function parseAvatarManifest(value: unknown): AvatarState | null {
+  if (!isRecord(value)) {
+    return null;
+  }
+  if (typeof value.kind !== "string" || !AVATAR_KINDS.has(value.kind)) {
+    return null;
+  }
+  const kind = value.kind as AvatarKind;
+  const source =
+    typeof value.source === "string" && AVATAR_SOURCES.has(value.source)
+      ? (value.source as AvatarSource)
+      : null;
+  if (kind === "character") {
+    if (!isValidCharacterTraits(value.traits)) {
+      return null;
+    }
+    return {
+      kind,
+      traits: value.traits,
+      source,
+      image: null,
+      accent: parseAvatarAccent(value.accent),
+    };
+  }
+  if (kind === "image") {
+    if (!isValidAvatarImageMeta(value.image)) {
+      return null;
+    }
+    return {
+      kind,
+      traits: null,
+      source,
+      image: value.image,
+      accent: parseAvatarAccent(value.accent),
+    };
+  }
+  return { kind, traits: null, source, image: null, accent: null };
+}
+
+type LegacyAvatarDerivation =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image" }
+  | { kind: "none" };
+
+/**
+ * Derives the avatar from the legacy sidecar files when there is no usable
+ * manifest. Traits-first: valid traits win even when the PNG also exists,
+ * because the builder writes the rendered PNG after the traits file, so
+ * mtimes cannot tell a built character from an uploaded image.
+ */
+export function deriveAvatarFromLegacyFiles(input: {
+  traitsJson: unknown;
+  hasImage: boolean;
+}): LegacyAvatarDerivation {
+  if (isValidCharacterTraits(input.traitsJson)) {
+    return { kind: "character", traits: input.traitsJson };
+  }
+  return input.hasImage ? { kind: "image" } : { kind: "none" };
+}
+
+type ResolvedAvatar =
+  | { kind: "character"; traits: CharacterTraits }
+  | { kind: "image"; image: AvatarImageMeta | null }
+  | { kind: "none" };
+
+/**
+ * Resolves the avatar from the parsed avatar files: the manifest when it is
+ * valid, otherwise the legacy derivation. `image` carries the manifest's
+ * metadata when the manifest decided, and is null for a legacy PNG.
+ */
+export function resolveAvatarFromFiles(input: {
+  manifestJson: unknown;
+  traitsJson: unknown;
+  hasImage: boolean;
+}): ResolvedAvatar {
+  const manifest = parseAvatarManifest(input.manifestJson);
+  if (manifest) {
+    switch (manifest.kind) {
+      case "character":
+        return {
+          kind: "character",
+          traits: manifest.traits as CharacterTraits,
+        };
+      case "image":
+        return { kind: "image", image: manifest.image };
+      case "none":
+        return { kind: "none" };
+    }
+  }
+  const legacy = deriveAvatarFromLegacyFiles(input);
+  return legacy.kind === "image" ? { kind: "image", image: null } : legacy;
+}

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

@@ -0,0 +1,143 @@
+/**
+ * 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";
+import type { AvatarKind } from "./manifest.js";
+
+/** Output edge in pixels: large enough for an iOS notification thumbnail. */
+export const NOTIFICATION_AVATAR_SIZE = 256;
+
+/** Free disc on each side of a character avatar, as a fraction of the edge. */
+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 = 2;
+
+/** 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.
+ * Custom images fill the disc; character avatars retain space around their
+ * silhouette.
+ */
+export function notificationAvatarGeometry(
+  kind: Exclude<AvatarKind, "none">,
+  size: number = NOTIFICATION_AVATAR_SIZE,
+): { radius: number; offset: number; inner: number } {
+  const offset = kind === "character" ? size * NOTIFICATION_AVATAR_INSET : 0;
+  return { radius: size / 2, offset, inner: size - 2 * offset };
+}
+
+export interface NotificationAvatarSvgOptions {
+  kind: Exclude<AvatarKind, "none">;
+  /** 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
+ * filling it for custom images or inset for character avatars.
+ *
+ * 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({
+  kind,
+  innerPngBase64,
+  innerMediaType = "image/png",
+  accentHex,
+  size = NOTIFICATION_AVATAR_SIZE,
+}: NotificationAvatarSvgOptions): string {
+  const { radius, offset, inner } = notificationAvatarGeometry(kind, 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>`
+  );
+}