@crossworks/client-types 0.230.43

package/src/journey-format.ts

@@ -0,0 +1,260 @@
+/**
+ * Pure presentation helpers for the Journey view (Activity → Reaction). No DB
+ * imports, so client components can pull these in. Server data fetching lives
+ * in ./journey.ts. The job here: turn a raw trace (kind + source + node type)
+ * into a human-readable "what you did" line + an icon key + a pipeline
+ * category, so the feed reads like a story rather than a log.
+ */
+
+export type ActionCategory = 'content' | 'dialog' | 'automation';
+
+export type ActionIconKey =
+  | 'chat'
+  | 'pdf'
+  | 'doc'
+  | 'image'
+  | 'file'
+  | 'email'
+  | 'note'
+  | 'event'
+  | 'task'
+  | 'telegram'
+  | 'tool'
+  | 'automation'
+  | 'secret';
+
+export type ActionPresentation = {
+  /** Human "what happened" line, e.g. "Email ingested". */
+  label: string;
+  /** Which of the two reaction pipelines this fed. */
+  category: ActionCategory;
+  iconKey: ActionIconKey;
+};
+
+/** Friendly source label for the chip under an action. */
+export function sourceLabel(source: string | null): string {
+  switch (source) {
+    case 'assistant_upload':
+      return 'chat upload';
+    case 'assistant':
+      return 'chat';
+    case 'telegram':
+      return 'telegram';
+    case 'telegram_upload':
+      return 'telegram upload';
+    case 'file_upload':
+      return 'files';
+    case 'file_create':
+      return 'files';
+    case 'file_edit':
+      return 'files';
+    case 'note_create':
+      return 'notes';
+    case 'agent_tool':
+      return 'agent';
+    case 'extractor':
+      return 'pipeline';
+    default:
+      return source || 'system';
+  }
+}
+
+function iconForNode(nodeType: string | null, mime: string | null): ActionIconKey {
+  switch (nodeType) {
+    case 'note':
+      return 'note';
+    case 'email':
+    case 'email_thread':
+      return 'email';
+    case 'task':
+      return 'task';
+    case 'event':
+      return 'event';
+    case 'secret':
+      return 'secret';
+    case 'telegram_message':
+      return 'telegram';
+    case 'file': {
+      const m = (mime ?? '').toLowerCase();
+      if (m.includes('pdf')) return 'pdf';
+      if (m.startsWith('image/')) return 'image';
+      if (
+        m.includes('word') ||
+        m.includes('officedocument') ||
+        m.includes('spreadsheet') ||
+        m.includes('excel') ||
+        m.includes('csv')
+      )
+        return 'doc';
+      return 'file';
+    }
+    default:
+      return 'file';
+  }
+}
+
+function contentLabel(nodeType: string | null, mime: string | null, source: string | null): string {
+  // Prefer the explicit human action when we recorded one.
+  switch (source) {
+    case 'assistant_upload':
+      return 'Uploaded in chat';
+    case 'telegram_upload':
+      return 'Sent media via Telegram';
+    case 'file_upload':
+      return 'Uploaded a file';
+    case 'file_create':
+      return 'Created a file';
+    case 'file_edit':
+      return 'Edited a file';
+    case 'note_create':
+      return 'Wrote a note';
+    case 'agent_tool':
+      return 'Agent created content';
+    default:
+      break;
+  }
+  // Otherwise derive from what the node turned out to be.
+  switch (nodeType) {
+    case 'email':
+    case 'email_thread':
+      return 'Email ingested';
+    case 'note':
+      return 'Note added';
+    case 'event':
+      return 'Event created';
+    case 'task':
+      return 'Task created';
+    case 'secret':
+      return 'Secret stored';
+    case 'file': {
+      const m = (mime ?? '').toLowerCase();
+      if (m.includes('pdf')) return 'PDF ingested';
+      if (m.startsWith('image/')) return 'Image ingested';
+      return 'File added';
+    }
+    default:
+      return 'Content added';
+  }
+}
+
+export function deriveAction(t: {
+  kind: string;
+  nodeType: string | null;
+  mime: string | null;
+  source: string | null;
+}): ActionPresentation {
+  // Conversation messages are dialog, even though the extractor (a content-
+  // pipeline worker) fires on their node. The transcript/text lives in the
+  // conversation store (L2 recent_turns) and flows through the dialog pipeline;
+  // the node is a shadow that the content index deliberately ignores. Labelling
+  // it "content" would mis-file chatter — and most such nodes skip anyway.
+  if (t.nodeType === 'telegram_message') {
+    return { label: 'Telegram message', category: 'dialog', iconKey: 'telegram' };
+  }
+  switch (t.kind) {
+    case 'responder_turn':
+      return { label: 'Conversation turn', category: 'dialog', iconKey: 'chat' };
+    case 'summarizer_run':
+      return {
+        label: 'Rolled up conversation digests',
+        category: 'automation',
+        iconKey: 'automation',
+      };
+    case 'reflector_run':
+      return {
+        label: 'Updated persona from conversation',
+        category: 'automation',
+        iconKey: 'automation',
+      };
+    case 'heartbeat_fire':
+      return { label: 'Scheduled automation fired', category: 'automation', iconKey: 'automation' };
+    default:
+      // extractor_run / content_ingest / photo_ingest / manual → content pipeline
+      return {
+        label: contentLabel(t.nodeType, t.mime, t.source),
+        category: 'content',
+        iconKey: iconForNode(t.nodeType, t.mime),
+      };
+  }
+}
+
+/** Where each pipeline lands, for the legend/reference panel. */
+export const PIPELINE_LEGEND: {
+  category: ActionCategory;
+  title: string;
+  flow: string;
+  blurb: string;
+}[] = [
+  {
+    category: 'content',
+    title: 'Content pipeline',
+    flow: 'L6 store → L5 index → L4 facts → graph',
+    blurb:
+      'Anything you add as knowledge — files, PDFs, images, notes, emails — is stored, summarised + embedded into the searchable index, mined for durable facts, and linked into the entity graph.',
+  },
+  {
+    category: 'dialog',
+    title: 'Dialog pipeline',
+    flow: 'L2 recent turns → L3 digests → L1 persona',
+    blurb:
+      'Conversation lands as recent turns, gets rolled up into digests by the summarizer, and shapes the agent’s persona via the reflector.',
+  },
+  {
+    category: 'automation',
+    title: 'Automation',
+    flow: 'timers + heartbeats',
+    blurb:
+      'Background work the brain does on its own schedule — digest roll-ups, persona reflection, and heartbeat-triggered actions.',
+  },
+];
+
+// ── Journey view DTOs (moved from server/web/lib/journey.ts) ─────────────────
+import type { TraceDetail } from './traces-format';
+
+export type LandedLayers = {
+  /** L6 content_store — the node itself. */
+  node: { id: string; type: string; title: string } | null;
+  /** L5 content_index — the searchable catalogue entry. */
+  index: {
+    summary: string | null;
+    hasEmbedding: boolean;
+    hasText: boolean;
+    tags: string[];
+  } | null;
+  /** L4 profile — durable facts mined from this node (currently-valid only). */
+  facts: { content: string; kind: string; entityName: string | null }[];
+  /** Graph — entities mentioned in this node. */
+  mentions: { name: string; kind: string }[];
+  /** Graph — relations this node drew between entities (subject→object). */
+  relations: { subject: string; relation: string; object: string }[];
+};
+
+export type ActivityItem = ActionPresentation & {
+  traceId: string;
+  kind: string;
+  status: string;
+  startedAt: string;
+  durationMs: number | null;
+  costMicroUsd: number;
+  stepCount: number;
+  /** Node title (or recorded filename) for the subject of the action. */
+  title: string | null;
+  subjectKind: string | null;
+  subjectId: string | null;
+  /** Outcome — what entered the brain. Facts mined + entities linked +
+   *  relations drawn from this action's node (0 for non-content / dialog
+   *  actions). */
+  factCount: number;
+  mentionCount: number;
+  relationCount: number;
+};
+
+export type JourneyDetail = TraceDetail & { landed: LandedLayers | null };
+
+/** Live snapshot for the always-on Activity surfaces: what's running right now,
+ *  what recently succeeded, and what failed. */
+export type LiveActivity = {
+  active: ActivityItem[];
+  recent: ActivityItem[];
+  failures: ActivityItem[];
+};

package/src/lib/event-time.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it } from 'vitest';
+import {
+  approachProgress,
+  buildIcsHref,
+  countdownParts,
+  dayGroup,
+  eventProgress,
+  eventState,
+  formatRelativeShort,
+} from './event-time';
+
+const DAY = 86_400_000;
+const HOUR = 3_600_000;
+const MIN = 60_000;
+const NOW = Date.UTC(2026, 4, 25, 12, 0, 0); // 2026-05-25 12:00 UTC
+const iso = (ms: number) => new Date(ms).toISOString();
+
+describe('eventState', () => {
+  it('classifies upcoming / in_progress / past', () => {
+    expect(eventState(iso(NOW + HOUR), null, NOW)).toBe('upcoming');
+    expect(eventState(iso(NOW - HOUR), iso(NOW + HOUR), NOW)).toBe('in_progress');
+    expect(eventState(iso(NOW - 2 * HOUR), iso(NOW - HOUR), NOW)).toBe('past');
+  });
+  it('treats a no-end event as a point in time', () => {
+    expect(eventState(iso(NOW), null, NOW)).toBe('in_progress'); // exact instant
+    expect(eventState(iso(NOW - 1), null, NOW)).toBe('past');
+  });
+});
+
+describe('countdownParts', () => {
+  it('splits remaining time into d/h/m/s', () => {
+    const p = countdownParts(iso(NOW + DAY + 2 * HOUR + 3 * MIN + 4000), NOW);
+    expect(p).toMatchObject({ days: 1, hours: 2, minutes: 3, seconds: 4 });
+  });
+  it('clamps the past to zero', () => {
+    expect(countdownParts(iso(NOW - HOUR), NOW)).toMatchObject({ days: 0, hours: 0, total: 0 });
+  });
+});
+
+describe('formatRelativeShort', () => {
+  it('formats future + past at the right unit', () => {
+    expect(formatRelativeShort(iso(NOW + 3 * DAY), NOW)).toBe('in 3d');
+    expect(formatRelativeShort(iso(NOW + 5 * HOUR), NOW)).toBe('in 5h');
+    expect(formatRelativeShort(iso(NOW - 5 * HOUR), NOW)).toBe('5h ago');
+    expect(formatRelativeShort(iso(NOW + 30_000), NOW)).toBe('now');
+  });
+});
+
+describe('eventProgress', () => {
+  it('is the fraction through a timed event', () => {
+    expect(eventProgress(iso(NOW - HOUR), iso(NOW + HOUR), NOW)).toBeCloseTo(0.5);
+    expect(eventProgress(iso(NOW), null, NOW)).toBe(0); // no end
+  });
+});
+
+describe('approachProgress', () => {
+  it('fills from 0 (≥horizon away) to 1 (at start)', () => {
+    expect(approachProgress(iso(NOW + 7 * DAY), NOW)).toBe(0);
+    expect(approachProgress(iso(NOW + 3.5 * DAY), NOW)).toBeCloseTo(0.5);
+    expect(approachProgress(iso(NOW), NOW)).toBe(1);
+  });
+});
+
+describe('dayGroup (UTC)', () => {
+  const g = (ms: number) => dayGroup(iso(ms), NOW, 'UTC');
+  it('buckets by day boundary', () => {
+    expect(g(NOW + 6 * HOUR)).toBe('today');
+    expect(g(NOW + DAY)).toBe('tomorrow');
+    expect(g(NOW + 3 * DAY)).toBe('this_week');
+    expect(g(NOW + 10 * DAY)).toBe('later');
+    expect(g(NOW - DAY)).toBe('past');
+  });
+});
+
+describe('buildIcsHref', () => {
+  it('builds a calendar data URL, or null without a start', () => {
+    const href = buildIcsHref({ title: 'Standup', startsAt: iso(NOW), location: 'Zoom' });
+    expect(href).toMatch(/^data:text\/calendar/);
+    const decoded = decodeURIComponent(href!);
+    expect(decoded).toContain('BEGIN:VEVENT');
+    expect(decoded).toContain('SUMMARY:Standup');
+    expect(decoded).toContain('LOCATION:Zoom');
+    expect(buildIcsHref({ title: 'x', startsAt: null })).toBeNull();
+  });
+});

package/src/lib/event-time.ts

@@ -0,0 +1,152 @@
+/**
+ * Pure time helpers for the events surface — countdowns, relative labels, the
+ * approach-ring + in-progress fractions, day grouping, and an .ics builder.
+ * Pure (no React, no DOM) so they're unit-testable and reusable on the server
+ * (share presenter) and client (live detail). All take `now` (ms) explicitly so
+ * the live components can drive them off a ticking clock and tests are
+ * deterministic.
+ */
+
+const MIN = 60_000;
+const HOUR = 3_600_000;
+const DAY = 86_400_000;
+
+export type EventState = 'upcoming' | 'in_progress' | 'past';
+
+/** Where an event sits relative to `now`. An event with no end is treated as a
+ *  point in time (in_progress only at the exact instant, then past). */
+export function eventState(startsAt: string, endsAt: string | null, now: number): EventState {
+  const start = new Date(startsAt).getTime();
+  const end = endsAt ? new Date(endsAt).getTime() : start;
+  if (now < start) return 'upcoming';
+  if (now <= end) return 'in_progress';
+  return 'past';
+}
+
+export type CountdownParts = {
+  days: number;
+  hours: number;
+  minutes: number;
+  seconds: number;
+  total: number; // remaining ms (clamped ≥ 0)
+};
+
+/** Break the time until `targetIso` into d/h/m/s (clamped at zero). */
+export function countdownParts(targetIso: string, now: number): CountdownParts {
+  const total = Math.max(0, new Date(targetIso).getTime() - now);
+  let ms = total;
+  const days = Math.floor(ms / DAY);
+  ms -= days * DAY;
+  const hours = Math.floor(ms / HOUR);
+  ms -= hours * HOUR;
+  const minutes = Math.floor(ms / MIN);
+  ms -= minutes * MIN;
+  const seconds = Math.floor(ms / 1000);
+  return { days, hours, minutes, seconds, total };
+}
+
+/** Compact relative label for list cards: "in 3d", "in 5h", "in 12m", "now",
+ *  "5m ago", "2d ago". Minute-resolution (the list ticks per minute). */
+export function formatRelativeShort(iso: string, now: number): string {
+  const diff = new Date(iso).getTime() - now;
+  const abs = Math.abs(diff);
+  if (abs < MIN) return 'now';
+  const unit = abs >= DAY ? 'd' : abs >= HOUR ? 'h' : 'm';
+  const n =
+    abs >= DAY
+      ? Math.round(abs / DAY)
+      : abs >= HOUR
+        ? Math.round(abs / HOUR)
+        : Math.round(abs / MIN);
+  return diff > 0 ? `in ${n}${unit}` : `${n}${unit} ago`;
+}
+
+/** Fraction (0..1) through an event with a known end — for the in-progress bar. */
+export function eventProgress(startsAt: string, endsAt: string | null, now: number): number {
+  if (!endsAt) return 0;
+  const s = new Date(startsAt).getTime();
+  const e = new Date(endsAt).getTime();
+  if (e <= s) return 0;
+  return Math.min(1, Math.max(0, (now - s) / (e - s)));
+}
+
+/** Ring fill (0..1) for an upcoming event: empty until `horizonMs` before start,
+ *  then fills smoothly to full at start. Default horizon: 7 days. */
+export function approachProgress(startsAt: string, now: number, horizonMs = 7 * DAY): number {
+  const remaining = new Date(startsAt).getTime() - now;
+  if (remaining <= 0) return 1;
+  if (remaining >= horizonMs) return 0;
+  return 1 - remaining / horizonMs;
+}
+
+export type DayGroup = 'today' | 'tomorrow' | 'this_week' | 'later' | 'past';
+
+/** Bucket an event by its start, in the given IANA timezone, relative to `now`.
+ *  Day boundaries are computed in `tz` so "today" matches the user's wall clock. */
+export function dayGroup(startsAt: string, now: number, tz: string): DayGroup {
+  const start = new Date(startsAt).getTime();
+  const startDay = dayIndex(start, tz);
+  const nowDay = dayIndex(now, tz);
+  const delta = startDay - nowDay;
+  if (delta < 0) return 'past';
+  if (delta === 0) return 'today';
+  if (delta === 1) return 'tomorrow';
+  if (delta <= 7) return 'this_week';
+  return 'later';
+}
+
+/** Integer day number (since epoch) for an instant, in `tz`. */
+function dayIndex(ms: number, tz: string): number {
+  // en-CA → YYYY-MM-DD; Date.UTC of those parts gives a tz-independent day count.
+  const [y, m, d] = new Intl.DateTimeFormat('en-CA', {
+    timeZone: tz,
+    year: 'numeric',
+    month: '2-digit',
+    day: '2-digit',
+  })
+    .format(new Date(ms))
+    .split('-')
+    .map(Number);
+  return Math.floor(Date.UTC(y!, m! - 1, d!) / DAY);
+}
+
+/** RFC5545 UTC stamp: 20260524T143000Z. */
+function icsStamp(iso: string): string {
+  return new Date(iso)
+    .toISOString()
+    .replace(/[-:]/g, '')
+    .replace(/\.\d{3}/, '');
+}
+function icsEscape(s: string): string {
+  return s.replace(/\\/g, '\\\\').replace(/;/g, '\\;').replace(/,/g, '\\,').replace(/\n/g, '\\n');
+}
+
+export type IcsInput = {
+  title: string;
+  body?: string;
+  startsAt: string | null;
+  endsAt?: string | null;
+  location?: string | null;
+};
+
+/** Build an `.ics` data URL so the event can be added to any calendar. Null if
+ *  there's no start. Shared by the events detail + the public share presenter. */
+export function buildIcsHref(e: IcsInput): string | null {
+  if (!e.startsAt) return null;
+  const lines = [
+    'BEGIN:VCALENDAR',
+    'VERSION:2.0',
+    'PRODID:-//Mantle//Events//EN',
+    'BEGIN:VEVENT',
+    `UID:${icsStamp(e.startsAt)}-${Math.random().toString(36).slice(2)}@mantle`,
+    `DTSTAMP:${icsStamp(new Date().toISOString())}`,
+    `DTSTART:${icsStamp(e.startsAt)}`,
+    ...(e.endsAt ? [`DTEND:${icsStamp(e.endsAt)}`] : []),
+    `SUMMARY:${icsEscape(e.title)}`,
+    ...(e.location ? [`LOCATION:${icsEscape(e.location)}`] : []),
+    ...(e.body ? [`DESCRIPTION:${icsEscape(e.body)}`] : []),
+    'END:VEVENT',
+    'END:VCALENDAR',
+  ];
+  return `data:text/calendar;charset=utf-8,${encodeURIComponent(lines.join('\r\n'))}`;
+}

package/src/lib/format-bytes.ts

@@ -0,0 +1,50 @@
+/**
+ * Pure, dependency-free byte/percent formatters. Safe to import from both
+ * server and client components (no DB / Node-only deps), mirroring
+ * `traces-format.ts`.
+ */
+
+/** Human-readable bytes, e.g. 1234567 → "1.2 MB". */
+export function formatBytes(n: number | null | undefined): string {
+  if (n == null || !Number.isFinite(n)) return '—';
+  if (n < 1024) return `${n} B`;
+  const units = ['KB', 'MB', 'GB', 'TB', 'PB'];
+  let v = n / 1024;
+  let i = 0;
+  while (v >= 1024 && i < units.length - 1) {
+    v /= 1024;
+    i++;
+  }
+  return `${v.toFixed(v >= 100 ? 0 : 1)} ${units[i]}`;
+}
+
+/** A 0..1 ratio (or 0..100 already-percent) → "12%". Pass `already=true`
+ *  when the input is already a 0..100 percentage. */
+export function formatPct(value: number | null | undefined, already = false): string {
+  if (value == null || !Number.isFinite(value)) return '—';
+  const pct = already ? value : value * 100;
+  return `${pct.toFixed(pct >= 10 || pct === 0 ? 0 : 1)}%`;
+}
+
+/** Compact integer with thousands separators, e.g. 12345 → "12,345".
+ *  Pins the `en-US` locale so server (Node) and client (browser) render the
+ *  SAME separator — a bare `toLocaleString()` formats per the runtime's locale,
+ *  which differs between Node and the browser (e.g. "1 931" vs "1,931") and
+ *  causes a React hydration mismatch. */
+export function formatCount(n: number | null | undefined): string {
+  if (n == null || !Number.isFinite(n)) return '—';
+  return n.toLocaleString('en-US');
+}
+
+/** Seconds → "3d 4h", "5h 12m", "8m", "42s". For uptime display. */
+export function formatUptime(seconds: number | null | undefined): string {
+  if (seconds == null || !Number.isFinite(seconds)) return '—';
+  const s = Math.floor(seconds);
+  const d = Math.floor(s / 86400);
+  const h = Math.floor((s % 86400) / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  if (d > 0) return `${d}d ${h}h`;
+  if (h > 0) return `${h}h ${m}m`;
+  if (m > 0) return `${m}m`;
+  return `${s}s`;
+}

package/src/lib/format-datetime.ts

@@ -0,0 +1,88 @@
+/**
+ * Deterministic date/time formatting for React components that render
+ * on BOTH the server (Node) and the client (browser).
+ *
+ * `Date.prototype.toLocaleString()` without arguments returns different
+ * strings on the two sides — Node uses the OS locale, the browser uses
+ * the user's preference. That diverges the SSR HTML from the hydrated
+ * tree and triggers a React hydration mismatch warning. Symptom: a
+ * red error in dev about "server rendered text didn't match the
+ * client", and the affected subtree gets regenerated on the client.
+ *
+ * Fix: pin the locale on every call. We use 'en-GB' across the app —
+ * the user is in South Africa, en-GB matches local conventions
+ * (DD/MM/YYYY, 24-hour time) and renders identically wherever Node
+ * runs. If we ever localise the UI properly, swap this for an i18n
+ * provider read from a cookie that's shared between SSR + client.
+ *
+ * Three formats covered:
+ *   - formatDateTime: '19/05/2026, 10:38:41'  — full timestamp
+ *   - formatDate:     '19/05/2026'             — date only
+ *   - formatTime:     '10:38:41'               — time only
+ *
+ * All three accept Date | string | number | null | undefined and return
+ * 'never' for missing values so callers don't have to do the null check.
+ */
+
+const LOCALE = 'en-GB';
+
+const DATETIME_OPTS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hour12: false,
+};
+
+const DATE_OPTS: Intl.DateTimeFormatOptions = {
+  year: 'numeric',
+  month: '2-digit',
+  day: '2-digit',
+};
+
+const TIME_OPTS: Intl.DateTimeFormatOptions = {
+  hour: '2-digit',
+  minute: '2-digit',
+  second: '2-digit',
+  hour12: false,
+};
+
+type Input = Date | string | number | null | undefined;
+
+function toDate(input: Input): Date | null {
+  if (input == null) return null;
+  if (input instanceof Date) return Number.isNaN(input.getTime()) ? null : input;
+  const d = new Date(input);
+  return Number.isNaN(d.getTime()) ? null : d;
+}
+
+export function formatDateTime(input: Input, missing = 'never'): string {
+  const d = toDate(input);
+  if (!d) return missing;
+  return new Intl.DateTimeFormat(LOCALE, DATETIME_OPTS).format(d);
+}
+
+export function formatDate(input: Input, missing = 'never'): string {
+  const d = toDate(input);
+  if (!d) return missing;
+  return new Intl.DateTimeFormat(LOCALE, DATE_OPTS).format(d);
+}
+
+export function formatTime(input: Input, missing = 'never'): string {
+  const d = toDate(input);
+  if (!d) return missing;
+  return new Intl.DateTimeFormat(LOCALE, TIME_OPTS).format(d);
+}
+
+/**
+ * `YYYY-MM-DD` in the viewer's LOCAL timezone (defaults to now). Use this to
+ * compare against day-bucketed date strings — `new Date().toISOString().slice(0,10)`
+ * is UTC, so it highlights the wrong day for a viewer whose local date differs
+ * from UTC (e.g. evening in the Americas, or already-tomorrow in APAC).
+ */
+export function localDay(date: Date = new Date()): string {
+  const p = (n: number) => String(n).padStart(2, '0');
+  return `${date.getFullYear()}-${p(date.getMonth() + 1)}-${p(date.getDate())}`;
+}

package/src/lib/safe-download.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { safeDownloadHeaders } from './safe-download';
+
+describe('safeDownloadHeaders', () => {
+  it('serves SVG inline as image/svg+xml so <img> embeds render', () => {
+    const h = safeDownloadHeaders('image/svg+xml', 'logo.svg');
+    expect(h['content-type']).toBe('image/svg+xml');
+    expect(h['content-disposition']).toMatch(/^inline;/);
+    expect(h['x-content-type-options']).toBe('nosniff');
+  });
+
+  it('sandboxes SVG with a scriptless CSP (no script execution on direct nav)', () => {
+    const h = safeDownloadHeaders('image/svg+xml', 'logo.svg');
+    const csp = h['content-security-policy'] ?? '';
+    expect(csp).toContain('sandbox');
+    expect(csp).not.toContain('allow-scripts');
+    expect(csp).toContain("default-src 'none'");
+  });
+
+  it('handles SVG mime parameters and casing', () => {
+    const h = safeDownloadHeaders('IMAGE/SVG+XML; charset=utf-8', 'logo.svg');
+    expect(h['content-type']).toBe('image/svg+xml');
+    expect(h['content-disposition']).toMatch(/^inline;/);
+    expect(h['content-security-policy']).toContain('sandbox');
+  });
+
+  it('forces HTML to an attachment', () => {
+    const h = safeDownloadHeaders('text/html', 'page.html');
+    expect(h['content-type']).toBe('application/octet-stream');
+    expect(h['content-disposition']).toMatch(/^attachment;/);
+  });
+
+  it('renders a PNG inline with its real type', () => {
+    const h = safeDownloadHeaders('image/png', 'pic.png');
+    expect(h['content-type']).toBe('image/png');
+    expect(h['content-disposition']).toMatch(/^inline;/);
+    expect(h['x-content-type-options']).toBe('nosniff');
+  });
+
+  it('ignores parameters on the mime type and is case-insensitive', () => {
+    expect(safeDownloadHeaders('IMAGE/PNG; charset=binary', 'p.png')['content-type']).toBe(
+      'image/png',
+    );
+  });
+
+  it('percent-encodes the filename so it cannot inject header content', () => {
+    const h = safeDownloadHeaders('application/pdf', 'a"; evil\r\nx: y.pdf');
+    expect(h['content-disposition']).not.toContain('"');
+    expect(h['content-disposition']).not.toContain('\r');
+    expect(h['content-disposition']).not.toContain('\n');
+    expect(h['content-disposition']).toContain("filename*=UTF-8''");
+  });
+
+  it('treats empty/unknown types as non-inline downloads', () => {
+    expect(safeDownloadHeaders('', 'x')['content-disposition']).toMatch(/^attachment;/);
+    expect(safeDownloadHeaders(null, 'x')['content-type']).toBe('application/octet-stream');
+  });
+});