Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

38.8 KB
Raw Blame
/**
 * Shared formatting utilities for the client
 * These functions are used across multiple pages and components
 */

/**
 * Format a timestamp as a relative time string
 * @param {string|Date} timestamp - ISO timestamp or Date object
 * @returns {string} Formatted relative time (e.g., "Just now", "5m ago", "2h ago")
 */
export function formatTime(timestamp) {
  if (timestamp == null || timestamp === '') return 'Unknown';
  const date = new Date(timestamp);
  if (isNaN(date.getTime())) return 'Invalid date';
  const now = new Date();
  const diff = now - date;

  if (diff < 60000) return 'Just now';
  if (diff < 3600000) return `${Math.floor(diff / 60000)}m ago`;
  if (diff < 86400000) return `${Math.floor(diff / 3600000)}h ago`;
  return formatDateNumeric(date);
}

const DATE_ONLY_RE = /^\d{4}-\d{2}-\d{2}$/;

/**
 * Format a Date as a browser-local YYYY-MM-DD calendar key.
 * Unlike `toISOString()`, this preserves the user's local day near UTC boundaries.
 * @param {Date} date
 * @returns {string}
 */
export function localDateKey(date = new Date()) {
  const year = date.getFullYear();
  const month = String(date.getMonth() + 1).padStart(2, '0');
  const day = String(date.getDate()).padStart(2, '0');
  return `${year}-${month}-${day}`;
}

/**
 * Shift a YYYY-MM-DD calendar key by whole days without local-time/DST drift.
 * @param {string} dateKey
 * @param {number} days
 * @returns {string}
 */
export function shiftISODate(dateKey, days) {
  const [year, month, day] = dateKey.split('-').map(Number);
  const shifted = new Date(Date.UTC(year, month - 1, day + days));
  return shifted.toISOString().slice(0, 10);
}

/**
 * Coerce a Date / ISO timestamp / epoch ms into a Date for display.
 *
 * A bare calendar date ("2026-03-05") is parsed by `new Date(...)` as UTC
 * midnight, which renders as the PREVIOUS day everywhere west of Greenwich.
 * Anchor it at LOCAL midnight instead — exactly what the call sites used to
 * do by hand with `new Date(value + 'T00:00:00')`.
 * @param {string|number|Date|null|undefined} value
 * @returns {Date} A Date (possibly Invalid — callers validate)
 */
function toDisplayDate(value) {
  if (value instanceof Date) return value;
  if (typeof value === 'string' && DATE_ONLY_RE.test(value)) return new Date(`${value}T00:00:00`);
  return new Date(value);
}

/**
 * Render `value` through `toLocaleDateString`/`toLocaleTimeString` with the
 * given options, returning `fallback` for missing or unparseable input so a
 * blank record never renders the literal string "Invalid Date".
 * @param {'date'|'time'} kind
 * @param {string|number|Date|null|undefined} value
 * @param {Intl.DateTimeFormatOptions|undefined} options
 * @param {string} fallback
 * @returns {string}
 */
function localized(kind, value, options, fallback) {
  if (value == null || value === '') return fallback;
  const date = toDisplayDate(value);
  if (Number.isNaN(date.getTime())) return fallback;
  return kind === 'date'
    ? date.toLocaleDateString([], options)
    : date.toLocaleTimeString([], options);
}

/**
 * Format a timestamp as a localized time-of-day string (e.g., "1:30 PM")
 * @param {string|Date} dateStr - ISO timestamp or Date object
 * @param {object} [options]
 * @param {string} [options.timeZone] - Render in a specific IANA timezone
 * @returns {string} Formatted time of day, or '' for missing/invalid input
 */
export function formatTimeOfDay(dateStr, { timeZone } = {}) {
  return localized('time', dateStr, { hour: 'numeric', minute: '2-digit', ...(timeZone ? { timeZone } : {}) }, '');
}

/**
 * Format a timestamp as a localized time-of-day string WITH seconds
 * (e.g., "1:30:45 PM") — the shape log/queue rows want, where the second
 * matters for ordering. Pair with `formatTimeOfDay` when seconds are noise
 * and `formatClockTime` when the zero-padded 24h-capable clock shape is wanted.
 * @param {string|number|Date|null} value - ISO timestamp, epoch ms, or Date
 * @param {string} [fallback=''] - Rendered for missing/invalid input
 * @returns {string} Formatted time of day with seconds
 */
export function formatTimeOfDaySeconds(value, fallback = '') {
  return localized('time', value, undefined, fallback);
}

/**
 * Format a date as a localized date string (e.g., "March 5, 2026")
 * @param {string|Date} dateStr - ISO timestamp or Date object
 * @returns {string|null} Formatted date, or null for missing input
 */
export function formatDate(dateStr) {
  if (!dateStr) return null;
  return localized('date', dateStr, { month: 'long', day: 'numeric', year: 'numeric' }, null);
}

/**
 * Format a date in the browser's short numeric locale form (e.g., "3/5/2026").
 * This is the canonical home for what used to be a bare
 * `new Date(x).toLocaleDateString()` scattered across components — compact
 * list/table cells where a spelled-out month would not fit.
 * @param {string|number|Date|null} value - ISO timestamp, `YYYY-MM-DD`, epoch ms, or Date
 * @param {string} [fallback=''] - Rendered for missing/invalid input
 * @returns {string} Formatted numeric date
 */
export function formatDateNumeric(value, fallback = '') {
  return localized('date', value, undefined, fallback);
}

/**
 * Format a date as month + day only (e.g., "Mar 5"). For dense HUD/badge
 * chrome and week ranges where the year is implied by context.
 * @param {string|number|Date|null} value
 * @param {string} [fallback=''] - Rendered for missing/invalid input
 * @returns {string}
 */
export function formatMonthDay(value, fallback = '') {
  return localized('date', value, { month: 'short', day: 'numeric' }, fallback);
}

/**
 * Format a date as month + year (e.g., "March 2026") — calendar month headers.
 * @param {string|number|Date|null} value
 * @param {string} [fallback=''] - Rendered for missing/invalid input
 * @returns {string}
 */
export function formatMonthYear(value, fallback = '') {
  return localized('date', value, { month: 'long', year: 'numeric' }, fallback);
}

/**
 * Format an abbreviated weekday plus time-of-day (e.g., "Mon, 7:00 AM") — a
 * week-scale schedule timeline, where the day matters but the date does not.
 * @param {string|number|Date|null} value
 * @param {object} [options]
 * @param {string} [options.timeZone] - Render in a specific IANA timezone
 * @returns {string} Formatted weekday + time, or '' for missing/invalid input
 */
export function formatWeekdayTime(value, { timeZone } = {}) {
  if (value == null || value === '') return '';
  const date = toDisplayDate(value);
  if (Number.isNaN(date.getTime())) return '';
  return date.toLocaleString([], { weekday: 'short', hour: 'numeric', minute: '2-digit', ...(timeZone ? { timeZone } : {}) });
}

/**
 * Format a date as an abbreviated weekday only (e.g., "Mon") — calendar
 * column headers and timeline axis ticks.
 * @param {string|number|Date|null} value
 * @param {object} [options]
 * @param {string} [options.timeZone] - Render the weekday in a specific IANA timezone
 * @returns {string} Abbreviated weekday, or '' for missing/invalid input
 */
export function formatWeekdayShort(value, { timeZone } = {}) {
  return localized('date', value, { weekday: 'short', ...(timeZone ? { timeZone } : {}) }, '');
}

/**
 * Format a weekday-led date with a short month (e.g., "Monday, Mar 5", or
 * "Mon, Mar 5, 2026" with `{ weekday: 'short', year: true }`). Distinct from
 * `formatDateFull` (long month, always with year).
 * @param {string|number|Date|null} value
 * @param {object} [options]
 * @param {'long'|'short'} [options.weekday='long'] - Weekday width
 * @param {boolean} [options.year=false] - Append the year
 * @param {string} [options.fallback=''] - Rendered for missing/invalid input
 * @returns {string}
 */
export function formatWeekdayDate(value, { weekday = 'long', year = false, fallback = '' } = {}) {
  return localized('date', value, { weekday, month: 'short', day: 'numeric', ...(year ? { year: 'numeric' } : {}) }, fallback);
}

/**
 * Format a date with full detail including weekday (e.g., "Saturday, March 5, 2026")
 * @param {string|number|Date|null} value - Date object, ISO timestamp, or `YYYY-MM-DD`
 * @returns {string} Formatted date string, or '' for missing/invalid input
 */
export function formatDateFull(value) {
  return localized('date', value, { weekday: 'long', month: 'long', day: 'numeric', year: 'numeric' }, '');
}

/**
 * Format a Date as a clock time string with seconds (e.g., "02:30:45 PM")
 * @param {string|number|Date|null} date - Date object, ISO timestamp, or epoch ms
 * @param {object} [options]
 * @param {string} [options.timeZone] - Render in a specific IANA timezone
 *   (e.g. the server's configured user timezone) instead of the browser's
 * @param {boolean} [options.seconds=true] - Include seconds ("02:30:45 PM" vs "02:30 PM")
 * @param {boolean} [options.hour12] - Force 12h/24h; omit to follow the locale
 * @returns {string} Formatted clock time, or '' for missing/invalid input
 */
export function formatClockTime(date, { timeZone, seconds = true, hour12 } = {}) {
  return localized('time', date, {
    hour: '2-digit',
    minute: '2-digit',
    ...(seconds ? { second: '2-digit' } : {}),
    ...(timeZone ? { timeZone } : {}),
    ...(hour12 === undefined ? {} : { hour12 }),
  }, '');
}

const HOUR_MERIDIEM = {
  long: [' AM', ' PM'],
  compact: ['AM', 'PM'],
  tiny: ['a', 'p'],
  lower: ['am', 'pm'],
};

/**
 * Format a bare hour-of-day number (0-23) as a 12-hour clock label.
 * The canonical home for what five components each hand-rolled, which is why
 * the same 3pm used to render as "3 PM", "3PM", "3p" and "3pm" on four screens.
 * One helper with a `style` option rather than four helpers: every caller wants
 * the same noon/midnight arithmetic and differs only in separator and case.
 * @param {number|string|null} hour - Hour of day, 0-23 (numeric strings accepted)
 * @param {object} [options]
 * @param {'long'|'compact'|'tiny'|'lower'} [options.style='long'] - `3 PM` / `3PM` / `3p` / `3pm`
 * @param {string} [options.fallback='—'] - Rendered for missing/non-numeric input
 * @returns {string} Formatted hour, or the fallback
 */
export function formatHourOfDay(hour, { style = 'long', fallback = '—' } = {}) {
  if (hour === null || hour === undefined || hour === '') return fallback;
  const h = Number(hour);
  if (!Number.isFinite(h)) return fallback;
  const [am, pm] = HOUR_MERIDIEM[style] || HOUR_MERIDIEM.long;
  const hr = h % 12 === 0 ? 12 : h % 12;
  return `${hr}${h < 12 ? am : pm}`;
}

/**
 * Format a duration in milliseconds as a human-readable string
 * @param {number} ms - Duration in milliseconds
 * @returns {string|null} Formatted duration (e.g., "500ms", "1.5s", "2.0m")
 */
export function formatRuntime(ms) {
  if (!ms) return null;
  if (ms < 1000) return `${ms}ms`;
  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
  return `${(ms / 60000).toFixed(1)}m`;
}

/**
 * Format a timestamp as relative time (e.g., "just now", "5m ago", "2d ago")
 * Handles null/missing values with configurable fallback.
 * @param {string|Date|null} dateStr - ISO timestamp, Date object, or null
 * @param {string} fallback - Text to show for null/missing dates (default: 'never')
 * @returns {string} Relative time string
 */
export function timeAgo(dateStr, fallback = 'never') {
  if (!dateStr) return fallback;
  const time = new Date(dateStr).getTime();
  if (!Number.isFinite(time)) return fallback; // Invalid Date → fallback, not "NaNy ago"
  const seconds = Math.floor((Date.now() - time) / 1000);
  if (seconds < 0) return 'just now';
  if (seconds < 60) return seconds < 10 ? 'just now' : `${seconds}s ago`;
  const mins = Math.floor(seconds / 60);
  if (mins < 60) return `${mins}m ago`;
  const hrs = Math.floor(mins / 60);
  if (hrs < 24) return `${hrs}h ago`;
  const days = Math.floor(hrs / 24);
  if (days < 30) return `${days}d ago`;
  if (days < 365) return `${Math.floor(days / 30)}mo ago`;
  return `${Math.floor(days / 365)}y ago`;
}

/**
 * Age in whole DAYS — "today", "1 day ago", "412 days ago".
 *
 * Distinct from `timeAgo`, which collapses anything past a month into "3mo ago"
 * / "2y ago". Model-download lists want the day count itself: it is the number
 * that says how current a checkpoint is, and a bucket label hides the difference
 * between a 40-day-old release and a 400-day-old one.
 * @param {string|number|Date|null} value - ISO timestamp, epoch ms, or Date
 * @param {string} fallback - Text for null/missing/unparseable values
 * @returns {string} Day-count label
 */
export function formatAgeDays(value, fallback = '') {
  if (value === null || value === undefined || value === '') return fallback;
  // toDisplayDate, not `new Date`: a bare "2026-03-05" parses as UTC midnight and
  // would read a day older than it is everywhere west of Greenwich.
  const time = toDisplayDate(value).getTime();
  if (!Number.isFinite(time)) return fallback;
  const days = Math.floor((Date.now() - time) / 86400000);
  // <= 0 covers a clock skew ahead of the publish date — never "-1 days ago".
  if (days <= 0) return 'today';
  return `${GROUPED_INTEGER.format(days)} day${days === 1 ? '' : 's'} ago`;
}

/**
 * Format a future timestamp as a relative "in X" string, mirroring timeAgo's
 * bucket thresholds. Returns `fallback` for null/missing or past dates (use
 * timeAgo for past-relative display). Example outputs: "in 5s", "in 3m",
 * "in 2h", "in 4d".
 * @param {string|Date|null} dateStr - ISO timestamp or Date object
 * @param {string} fallback - Text to show for null/missing/past dates (default: 'now')
 * @returns {string} Future-relative time string
 */
export function timeUntil(dateStr, fallback = 'now') {
  if (!dateStr) return fallback;
  const time = new Date(dateStr).getTime();
  if (!Number.isFinite(time)) return fallback;
  const seconds = Math.floor((time - Date.now()) / 1000);
  if (seconds <= 0) return fallback;
  if (seconds < 60) return `in ${seconds}s`;
  const mins = Math.floor(seconds / 60);
  if (mins < 60) return `in ${mins}m`;
  const hrs = Math.floor(mins / 60);
  if (hrs < 24) return `in ${hrs}h`;
  const days = Math.floor(hrs / 24);
  if (days < 30) return `in ${days}d`;
  if (days < 365) return `in ${Math.floor(days / 30)}mo`;
  return `in ${Math.floor(days / 365)}y`;
}

/**
 * Compact decimal count: 950 → "950", 1200 → "1.2K", 3400000 → "3.4M".
 * @param {number} n - Count to abbreviate
 * @returns {string} Abbreviated count
 */
export function formatCompactCount(n) {
  if (!Number.isFinite(n)) return '0';
  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
  if (n >= 1_000) return `${(n / 1_000).toFixed(1)}K`;
  return String(n);
}

/**
 * `formatCompactCount` for a count that may legitimately be absent: renders an
 * em-dash instead of "0", so "no data" and "measured zero" read differently on
 * a stat tile. `formatCompactCount` itself can't take this on — a real 0 must
 * still render as "0".
 * @param {number|null|undefined} n
 * @returns {string}
 */
export function formatCompactCountOrDash(n) {
  return n == null ? '—' : formatCompactCount(n);
}

// Grouping is pinned to en-US rather than the browser locale. The UI is
// English-only, and `$` is a US currency mark — rendering "$4.610,09" next to
// English copy reads as a typo, not as localization. Counts use the same
// separator so a total and its cost line up — `formatAgeDays` above formats its
// day count through the same instance for that reason. The date/time DISPLAY
// helpers keep the browser locale on purpose: a rendered date carries no
// currency anchor, so there is nothing for its separators to contradict.
const GROUPED_INTEGER = new Intl.NumberFormat('en-US', { maximumFractionDigits: 0 });
const USD_CENTS = new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: 2 });
const USD_COMPACT = new Intl.NumberFormat('en-US', { notation: 'compact', maximumFractionDigits: 1 });

/**
 * Thousands-separated count for a number the user is meant to read exactly:
 * 2762 → "2,762". Use this for a total, a record count, or a token count —
 * anywhere `formatCompactCount`'s "2.8K" would lose the precision that is the
 * point of showing the number at all.
 * @param {number|string|null|undefined} n
 * @param {object} [options]
 * @param {number} [options.maximumFractionDigits=0] - Optional precision for scores and other fractional values
 * @param {string} [options.fallback='—'] - Rendered when the value is missing/unparseable
 * @returns {string} e.g. "2,762"
 */
export function formatCount(n, { fallback = '—', maximumFractionDigits = 0 } = {}) {
  const precision = Number.isInteger(maximumFractionDigits) ? Math.max(0, Math.min(8, maximumFractionDigits)) : 0;
  const value = roundForDisplay(n, precision);
  if (precision && value !== null) return new Intl.NumberFormat('en-US', { maximumFractionDigits: precision }).format(value + 0);
  // `+ 0` folds the -0 that a negative fraction rounds to (-0.4 → -0), which
  // Intl would render as the nonsense "-0".
  return value === null ? fallback : GROUPED_INTEGER.format(value + 0);
}

/**
 * Round a number to `decimals` places and drop trailing zeros
 * (170.35000000000002 → 170.4, 170.0 → 170). Returns null for
 * non-finite input so callers can render their own fallback.
 * @param {number|string|null|undefined} value
 * @param {number} decimals
 * @returns {number|null}
 */
function roundForDisplay(value, decimals) {
  // `Number(null)`, `Number('')`, `Number('   ')` and `Number(false)` are all 0,
  // which would render a missing measurement as a real "0 lbs" — accept only a
  // number or a non-blank numeric string before coercing.
  const isNumeric = typeof value === 'number'
    || (typeof value === 'string' && value.trim() !== '');
  if (!isNumeric) return null;
  const n = Number(value);
  if (!Number.isFinite(n)) return null;
  return parseFloat(n.toFixed(decimals));
}

/**
 * One-line readout of a mastered render's measured audio (#10249).
 * @param {{integratedLufs:number, truePeakDb:number, masteredFrom?:{integratedLufs:number}}|null|undefined} loudness
 * @returns {string} e.g. "-14.1 LUFS, peak -1.6 dB (was -27.3 LUFS)", or '' when unmeasured
 */
export function formatLoudness(loudness) {
  const lufs = roundForDisplay(loudness?.integratedLufs, 1);
  const peak = roundForDisplay(loudness?.truePeakDb, 1);
  if (lufs == null || peak == null) return '';
  const was = roundForDisplay(loudness.masteredFrom?.integratedLufs, 1);
  return `${lufs} LUFS, peak ${peak} dB${was == null ? '' : ` (was ${was} LUFS)`}`;
}

/**
 * Format a body weight for display. Unit-converted weights arrive as raw
 * binary floats (e.g. 170.35000000000002), which read as false precision and
 * blow out a tile's line — round to one decimal by default and suffix the unit.
 * @param {number|string|null|undefined} value - Weight in `unit`
 * @param {object} [options]
 * @param {string} [options.unit='lbs'] - Unit suffix
 * @param {number} [options.decimals=1] - Decimal places to keep
 * @param {string} [options.fallback='—'] - Rendered when the value is missing/invalid
 * @returns {string} e.g. "170.4 lbs"
 */
export function formatWeight(value, { unit = 'lbs', decimals = 1, fallback = '—' } = {}) {
  const n = roundForDisplay(value, decimals);
  if (n === null) return fallback;
  return unit ? `${n} ${unit}` : `${n}`;
}

/**
 * Format a percentage for display, rounding away float noise the same way
 * `formatWeight` does (18.400000000000002 → "18.4%").
 * @param {number|string|null|undefined} value - Percentage (already 0–100)
 * @param {object} [options]
 * @param {number} [options.decimals=1] - Decimal places to keep
 * @param {string} [options.fallback='—'] - Rendered when the value is missing/invalid
 * @returns {string} e.g. "18.4%"
 */
export function formatPercent(value, { decimals = 1, fallback = '—' } = {}) {
  const n = roundForDisplay(value, decimals);
  if (n === null) return fallback;
  return `${n}%`;
}

/**
 * Format a USD amount for display: `$12.34`, `$4,610.09`.
 *
 * `signed` keeps the minus sign OUTSIDE the dollar sign (`-$5.00`), so a
 * negative saving reads as a loss rather than as a strange currency string.
 * `trimWhole` drops the `.00` on a round figure — for a price the user typed
 * ($200/mo), not for a computed total, where aligned cents are the point.
 * Amounts past a thousand are grouped (`$4,610.09`) — an unseparated `$4610.09`
 * is read as the wrong order of magnitude at a glance. `compact` abbreviates
 * (`$9.4K`) for chart axes and labels where width is tight.
 *
 * @param {number} value - Dollar amount (nullish renders as $0.00; a non-nullish
 *   value that fails to parse as a finite number — NaN, a broken calc — renders
 *   `fallback` instead, so a computation failure never masquerades as "$0.00")
 * @param {{ signed?: boolean, trimWhole?: boolean, compact?: boolean, fallback?: string, maximumFractionDigits?: number }} [options]
 * @returns {string} e.g. "$12.34", "-$5.00", "$200"
 */
export function formatUsd(value, { signed = false, trimWhole = false, compact = false, fallback = '—', maximumFractionDigits = 2 } = {}) {
  const n = value === null || value === undefined ? 0 : Number(value);
  if (!Number.isFinite(n)) return fallback;
  // Anything under half a cent renders as zero, and Intl signs it (`-$0.00`)
  // where the old `toFixed(2)` did not. A saving that rounds away to nothing
  // must not read as a loss, so snap it onto a true zero and drop the sign with
  // it — `signed && n < 0` alone would still print the minus.
  const raw = signed ? Math.abs(n) : n;
  const precision = Number.isInteger(maximumFractionDigits) ? Math.max(2, Math.min(8, maximumFractionDigits)) : 2;
  const magnitude = Math.abs(raw) < 0.5 * 10 ** -precision ? 0 : raw;
  const body = compact ? USD_COMPACT.format(magnitude) : trimWhole && Number.isInteger(magnitude)
    ? GROUPED_INTEGER.format(magnitude)
    : precision === 2 ? USD_CENTS.format(magnitude) : new Intl.NumberFormat('en-US', { minimumFractionDigits: 2, maximumFractionDigits: precision }).format(magnitude);
  return `${signed && n < 0 && magnitude !== 0 ? '-' : ''}$${body}`;
}

/**
 * Format bytes as a human-readable string
 * @param {number} bytes - Size in bytes
 * @param {number} decimals - Number of decimal places
 * @returns {string} Formatted size (e.g., "1.5 KB", "2.3 MB", "4.2 TB")
 */
export function formatBytes(bytes, decimals = 1) {
  if (!bytes || bytes === 0) return '0 B';

  const k = 1024;
  const sizes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB'];
  // Clamp the unit index so values larger than the largest defined unit
  // still render with a known suffix (e.g. multi-PB import archives) rather
  // than `undefined`.
  const i = Math.min(Math.floor(Math.log(bytes) / Math.log(k)), sizes.length - 1);

  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(decimals))} ${sizes[i]}`;
}

/**
 * Format a model's decimal-GB (10^9 bytes) download footprint as "~29 GB".
 * Returns null for missing/zero/invalid values so callers can omit the label
 * entirely rather than render "~undefined GB". Deliberately decimal, not the
 * binary units `formatBytes` uses: these values come from HuggingFace repo
 * sizes, which are quoted in decimal GB.
 * @param {number|null|undefined} gb
 * @returns {string|null}
 */
export function formatDownloadGb(gb) {
  return typeof gb === 'number' && Number.isFinite(gb) && gb > 0 ? `~${gb} GB` : null;
}

/**
 * Format a model context window (in tokens) compactly, e.g. 32768 → "32K ctx",
 * 131072 → "128K ctx", 1000000 → "1M ctx". Returns null for missing/invalid
 * values so callers can omit the label entirely.
 *
 * Two unit systems, picked per value, because model context windows are quoted
 * in both and neither divisor is right for the other: local runtimes report
 * BINARY windows (131072, 32768 — "128K", "32K"), while cloud vendors quote
 * DECIMAL ones (128000, 1000000 — "128K", "1M"). Dividing a decimal window by
 * 1024 is what rendered a 128,000-token provider as "125K ctx", a number no
 * vendor publishes and which reads as a PortOS-imposed cap rather than the
 * model's own spec. So: a value that divides evenly by 1000 is decimal, and
 * everything else is binary.
 *
 * `suffix` is what follows the number. The default reads as a standalone badge;
 * pass `''` when the surrounding prose already supplies the noun ("up to 32K
 * tokens of context"), so the two spellings stay one implementation instead of
 * a near-copy per caller.
 *
 * @param {number|null|undefined} tokens
 * @param {{ suffix?: string }} [options]
 * @returns {string|null}
 */
export function formatContextLength(tokens, { suffix = ' ctx' } = {}) {
  const n = Number(tokens);
  if (!Number.isFinite(n) || n <= 0) return null;
  const k = n % 1000 === 0 ? 1000 : 1024;
  if (n >= k * k) {
    const m = n / (k * k);
    return `${parseFloat(m.toFixed(m % 1 ? 1 : 0))}M${suffix}`;
  }
  if (n >= k) return `${Math.round(n / k)}K${suffix}`;
  return `${n}${suffix}`;
}

/**
 * Context length with NO unit suffix — `4096` → `"4K"` — for prose that
 * already says "tokens of context" around it.
 *
 * Three surfaces in the Models section had each declared this same one-line
 * alias privately; it lives here, beside `formatContextLength`, so a change to
 * the K/M thresholds reaches all of them.
 */
export function formatContextTokens(tokens) {
  return formatContextLength(tokens, { suffix: '' });
}

/**
 * How fast a measured model generated, as one label: `"58.5 tok/s"`,
 * `"~58.5 tok/s"` for a frame-counted estimate, or `"240 chars/s"` when the
 * runtime reported no token counts at all. `null` when neither was measured.
 *
 * Tokens/s leads because it is the figure people compare local models on, and
 * the two are never shown together — one row carrying both units reads as a
 * contradiction. The `~` is not decoration: PortOS has no tokenizer, so a count
 * derived from counting streamed frames must never be presented as one the
 * daemon's tokenizer produced.
 *
 * @param {{meanTokensPerSecond?: number|null, meanCharsPerSecond?: number|null, tokensEstimated?: boolean|null}} perf
 */
export function throughputLabel(perf) {
  const tokens = perf?.meanTokensPerSecond;
  if (typeof tokens === 'number' && Number.isFinite(tokens)) {
    return `${perf?.tokensEstimated ? '~' : ''}${tokens} tok/s`;
  }
  const chars = perf?.meanCharsPerSecond;
  return typeof chars === 'number' && Number.isFinite(chars) ? `${chars} chars/s` : null;
}

/**
 * Format a number of seconds as MM:SS (e.g. 75 → "01:15"), or H:MM:SS once the
 * total reaches an hour (e.g. 3661 → "1:01:01"). Used for sprint timers and
 * other countdowns. Negative and non-finite values clamp to 0.
 */
export function formatCountdown(seconds) {
  const safe = Number.isFinite(seconds) ? Math.max(0, Math.round(seconds)) : 0;
  const h = Math.floor(safe / 3600);
  const m = Math.floor((safe % 3600) / 60);
  const s = safe % 60;
  const mmss = `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`;
  return h > 0 ? `${h}:${mmss}` : mmss;
}

/**
 * Format a timestamp as a localized date+time string (e.g., "Apr 1, 2026, 1:30 PM")
 * @param {string|Date|null} value - ISO timestamp or Date object
 * @returns {string} Formatted date and time, or 'Unknown time' for invalid input
 */
const _dateTimeFormatter = new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeStyle: 'short' });

export function formatDateTime(value, fallback = 'Unknown time') {
  if (value == null || value === '') return fallback;
  const date = toDisplayDate(value);
  if (Number.isNaN(date.getTime())) return fallback;
  return _dateTimeFormatter.format(date);
}

/**
 * Format a number of seconds as M:SS (e.g. 75 → "1:15"). For coarse durations
 * like a stitched video's runtime or a piano-roll ruler tick. Returns `'—'`
 * for missing/invalid/negative input; a genuine zero renders as `"0:00"` (not
 * `'—'`) so callers can distinguish "unknown" from "zero seconds".
 */
export function formatDurationSec(seconds) {
  if (!Number.isFinite(seconds) || seconds < 0) return '—';
  const m = Math.floor(seconds / 60);
  const s = Math.floor(seconds % 60);
  return `${m}:${String(s).padStart(2, '0')}`;
}

/**
 * Format a number of seconds as M:SS.ss for video-editor timecodes
 * (e.g. 95.42 → "1:35.42"). Negative or non-finite inputs render as "0:00.00".
 */
export function formatTimecode(seconds, digits = 2) {
  if (!Number.isFinite(seconds) || seconds < 0) return `0:00.${'0'.repeat(digits)}`;
  const m = Math.floor(seconds / 60);
  const s = seconds - m * 60;
  return `${m}:${s.toFixed(digits).padStart(3 + digits, '0')}`;
}

/**
 * Format a date with a short month label (e.g., "Mar 5, 2026"). Returns
 * `'—'` for missing/invalid input — pair with `formatDate` (long month, null
 * fallback) depending on the surrounding UI.
 */
export function formatDateShort(value) {
  return localized('date', value, { year: 'numeric', month: 'short', day: 'numeric' }, '—');
}

// Per-call LLM timeout bounds. Client-side mirror of the canonical
// MIN_TIMEOUT / MAX_TIMEOUT in server/lib/aiToolkit/constants.js — the
// client can't import across the server boundary (Vite vs Node, plus the
// aiToolkit directory is kept self-contained per AGENTS.md). The server
// validators (validation.js, stageRunner.js) and aiToolkit's own
// provider/run schemas all import from constants.js; this file is the
// only known mirror. Bumping these here without the server constants —
// or vice versa — would let a value through one validator that the
// other rejects.
export const TIMEOUT_INPUT_MIN_MS = 1000;
export const TIMEOUT_INPUT_MAX_MS = 43_200_000;
export const TIMEOUT_INPUT_STEP_MS = 1000;

/**
 * Parse a raw string from a timeout (ms) input into a stored value.
 * Returns `null` for blank input (caller treats as "clear override") and
 * for anything outside the validated [TIMEOUT_INPUT_MIN_MS,
 * TIMEOUT_INPUT_MAX_MS] integer range — the caller is then responsible for
 * snapping the input back to the persisted value. Clamping here keeps the
 * client from emitting PUTs the server's Zod schema would 400 (e.g. a
 * stray `1` that "looks positive" but is below the 1s floor).
 *
 * Accepts only digit-only strings (`^\d+$`), then parses via `Number(...)`
 * + `Number.isInteger`. The digit-only gate is stricter than `Number(v)`
 * alone — `Number("1e3")` is 1000 and `Number("1000.5")` is 1000.5 — and
 * is mirrored in `stageConfigUpdateSchema`'s preprocess in
 * server/lib/validation.js so client/server reject the same shapes. If
 * you loosen this rule, loosen the server preprocess in lockstep.
 */
export function parseTimeoutMs(raw) {
  if (raw == null) return null;
  const trimmed = String(raw).trim();
  if (trimmed === '') return null;
  // Require an explicit digit-only string so "1e3" / "1.5" / "0x10" can't
  // sneak past Number()'s permissive coercion.
  if (!/^\d+$/.test(trimmed)) return null;
  const ms = Number(trimmed);
  if (!Number.isInteger(ms) || ms < TIMEOUT_INPUT_MIN_MS || ms > TIMEOUT_INPUT_MAX_MS) return null;
  return ms;
}

/**
 * Format a duration in milliseconds as a human-readable string. Buckets down
 * from days so multi-day uptimes read as "2d 3h" rather than an unbounded
 * hours count ("51h 0m").
 * @param {number} ms - Duration in milliseconds
 * @returns {string} Formatted duration (e.g., "45s", "3m 12s", "2h 5m", "2d 3h")
 */
export function formatDurationMs(ms) {
  if (ms == null) return '-';
  const seconds = Math.floor(ms / 1000);
  if (seconds < 60) return `${seconds}s`;
  const minutes = Math.floor(seconds / 60);
  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
  const hours = Math.floor(minutes / 60);
  if (hours < 24) return `${hours}h ${minutes % 60}m`;
  const days = Math.floor(hours / 24);
  return `${days}d ${hours % 24}h`;
}

/**
 * Format a duration in minutes as a human-readable string
 * @param {number|null|undefined} minutes - Duration in minutes; nullish → ''
 * @param {object} [options]
 * @param {boolean} [options.approximate=false] - Prefix the result with `~`
 *   to signal an estimate (e.g., "~1h 30m") for predicted/averaged durations.
 * @returns {string} Formatted duration (e.g., "30m", "1h 30m", "2h", "~2h")
 */
export function formatDurationMin(minutes, options = {}) {
  if (minutes == null) return '';
  const { approximate = false } = options ?? {};
  const prefix = approximate ? '~' : '';
  if (minutes >= 60) {
    const h = Math.floor(minutes / 60);
    const m = minutes % 60;
    return m ? `${prefix}${h}h ${m}m` : `${prefix}${h}h`;
  }
  return `${prefix}${minutes}m`;
}

/**
 * Format a calendar event's date+time, with a distinct all-day rendering.
 * Tuned for the event-detail panel: timed events show a short weekday plus
 * time (e.g. "Sat, Apr 1, 1:30 PM"); all-day events show a full weekday and
 * year (e.g. "Saturday, April 1, 2026"). Kept separate from `formatDateTime`
 * because the weekday-led shape is event-specific.
 * Missing/unparseable input renders '' — the same fallback contract every
 * other helper here follows. (It used to pass the raw `Invalid Date` string
 * through "for migration fidelity"; once the all-day branch started routing
 * through `formatDateFull`'s guard, that left one branch guarded and one not.
 * Both call sites pass a real event time, so nothing visible changes.)
 * @param {string|Date|null} dateStr - ISO timestamp or Date object
 * @param {object} [options]
 * @param {boolean} [options.allDay=false] - Render date-only (all-day event).
 * @returns {string} Formatted event date/time
 */
export function formatEventDateTime(dateStr, options = {}) {
  const { allDay = false } = options ?? {};
  // All-day events render exactly like `formatDateFull` (full weekday + year).
  if (allDay) return formatDateFull(dateStr);
  if (dateStr == null || dateStr === '') return '';
  const date = toDisplayDate(dateStr);
  if (Number.isNaN(date.getTime())) return '';
  return date.toLocaleString([], { weekday: 'short', month: 'short', day: 'numeric', hour: 'numeric', minute: '2-digit' });
}

/**
 * Get app name from app ID by looking up in apps array
 * @param {string|null} appId - The app ID to look up
 * @param {Array<{id: string, name: string}>} apps - Array of app objects
 * @param {string} fallback - Fallback value if app not found
 * @returns {string|null} App name or fallback
 */
export function getAppName(appId, apps, fallback = null) {
  if (!appId) return fallback;
  const app = apps?.find(a => a.id === appId);
  return app?.name || fallback;
}

/**
 * Derive a human-friendly default record name from a gallery-image filename:
 * drop the path + extension, turn `-`/`_` separators into spaces, title-case,
 * and cap at 120 chars (the server-side name limit). Shared by the "image → 3D
 * model" pages (Three.js Models and image-to-3D) so their defaults don't drift.
 * @param {string} filename
 * @param {string} [fallback='Untitled 3D model'] - used when the filename is empty
 * @returns {string}
 */
export function nameFromImageFilename(filename, fallback = 'Untitled 3D model') {
  const base = String(filename || '').split('/').pop().replace(/\.[^.]+$/, '');
  const name = base.replace(/[-_]+/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase()).trim().slice(0, 120);
  return name || fallback;
}

/**
 * Truncate from the MIDDLE so the distinguishing tail of a long string stays
 * readable — the failure mode of CSS `line-clamp`/`text-overflow`, which always
 * eats the end. Use it wherever a list renders many strings that share a long
 * prefix (auto-generated names, dated run labels, deep paths), where clipping
 * the end collapses every row to the same visible text.
 * @param {string} value - Source string (non-strings coerce; nullish → '')
 * @param {number} [max=48] - Maximum length of the RESULT in CODE POINTS, ellipsis included.
 *   A non-finite cap returns the string whole rather than discarding it.
 * @returns {string} `value` when it already fits, else `head…tail`
 */
export function middleTruncate(value, max = 48) {
  const str = value == null ? '' : String(value);
  // A cap that isn't a real number can't middle-truncate anything — return the
  // string untouched. (`Math.max(0, NaN)` is NaN, so a naive slice would
  // silently return '' and swallow the value.)
  if (!Number.isFinite(max)) return str;
  const cap = Math.floor(max);
  // Slice on CODE POINTS, not UTF-16 code units: cutting through a surrogate
  // pair (any emoji / astral character) emits a lone surrogate that renders as
  // the replacement glyph.
  const chars = Array.from(str);
  // A cap that can't fit the ellipsis plus one char on each side has no
  // meaningful middle-truncation; fall back to a plain head slice.
  if (cap < 3) return chars.slice(0, Math.max(0, cap)).join('');
  if (chars.length <= cap) return str;
  const head = Math.ceil((cap - 1) / 2);
  const tail = cap - 1 - head;
  return `${chars.slice(0, head).join('')}…${chars.slice(chars.length - tail).join('')}`;
}

/**
 * Format a cooldown countdown in milliseconds as "M:SS" (e.g., "1:05", "0:09").
 * @param {number} ms - Remaining milliseconds (negative values clamp to 0:00)
 * @returns {string} Minutes:seconds countdown string
 */
export function formatCooldown(ms) {
  const totalSeconds = Math.max(0, Math.ceil(ms / 1000));
  const minutes = Math.floor(totalSeconds / 60);
  const seconds = totalSeconds % 60;
  return `${minutes}:${seconds.toString().padStart(2, '0')}`;
}

/**
 * Parse a human size string ("4.7 GB", "512 MB") to GB.
 * @param {string|null|undefined} sizeStr - Human-readable size string
 * @returns {number|null} Size in GB, or null when unparseable
 */
function parseSizeGb(sizeStr) {
  const match = /([\d.]+)\s*(TB|GB|MB|KB)/i.exec(String(sizeStr || ''));
  if (!match) return null;
  const val = parseFloat(match[1]);
  if (!Number.isFinite(val)) return null;
  return val * ({ TB: 1024, GB: 1, MB: 1 / 1024, KB: 1 / (1024 * 1024) }[match[2].toUpperCase()]);
}

/**
 * Rough RAM/VRAM needed to run a local model: weights + ~20% overhead
 * (KV cache/runtime), rounded up to whole GB with a 1 GB floor.
 * Prefers exact bytes when known, falling back to a human size string.
 * @param {number|null|undefined} sizeBytes - Exact model size in bytes
 * @param {string|null|undefined} sizeStr - Human size string fallback ("4.7 GB")
 * @returns {number|null} Whole GB recommendation, or null when size is unknown
 */
export function recommendedRamGb(sizeBytes, sizeStr) {
  const gb = Number.isFinite(sizeBytes) ? sizeBytes / 1024 ** 3 : parseSizeGb(sizeStr);
  if (!gb || gb <= 0) return null;
  return Math.max(1, Math.ceil(gb * 1.2));
}

/**
 * Clamp a numeric value `n` into the inclusive range `[min, max]`.
 * @param {number} n - Value to clamp
 * @param {number} min - Lower bound
 * @param {number} max - Upper bound
 * @returns {number} Clamped value
 */
export function clamp(n, min, max) {
  return Math.min(max, Math.max(min, n));
}

/**
 * Capitalize the first character of a string, leaving the rest untouched
 * (e.g. "female" → "Female"). Non-strings and empty strings pass through
 * unchanged rather than throwing.
 * @param {string} s
 * @returns {string}
 */
export function capitalize(s) {
  return typeof s === 'string' && s.length ? s[0].toUpperCase() + s.slice(1) : s;
}

/**
 * Short display name for a Claude model id: drops the `claude-` prefix and a
 * trailing 8-digit date stamp only, so `claude-sonnet-5-5` stays "sonnet-5-5"
 * (a bare `-\d+` strip would collapse it to "sonnet-5").
 */
export function shortClaudeModelName(model) {
  return String(model ?? '').replace(/^claude-/, '').replace(/-\d{8}$/, '');
}