@karmaniverous/jeeves-server 3.0.0-0

package/dist/src/services/plantuml.js

@@ -0,0 +1,145 @@
+/**
+ * PlantUML rendering with fallback pipeline:
+ * 1. Local Java jar (if configured) — supports !include directives
+ * 2. Configured PlantUML servers (in order)
+ * 3. Public community server (always last resort)
+ */
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import plantumlEncoder from 'plantuml-encoder';
+import { getConfig } from '../config/index.js';
+/**
+ * Try rendering via local PlantUML jar.
+ * Output goes to a temp directory to avoid writing in the source tree.
+ * Returns the output buffer, or null on failure.
+ */
+function renderViaJar(filePath, format) {
+    const { plantuml } = getConfig();
+    if (!plantuml.jarPath)
+        return null;
+    const dir = path.dirname(filePath);
+    const ext = path.extname(filePath);
+    const base = path.basename(filePath, ext);
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'puml-'));
+    const outFile = path.join(tmpDir, `${base}.${format}`);
+    try {
+        const java = plantuml.javaPath ?? 'java';
+        // UNSECURE profile allows remote !include directives (e.g. AWS PuML from GitHub)
+        execSync(`"${java}" -DPLANTUML_SECURITY_PROFILE=UNSECURE -jar "${plantuml.jarPath}" -t${format} -o "${tmpDir}" "${filePath}"`, { timeout: 60_000, stdio: 'pipe', cwd: dir });
+        if (!fs.existsSync(outFile))
+            return null;
+        const buffer = fs.readFileSync(outFile);
+        return buffer;
+    }
+    catch (err) {
+        // PlantUML may produce output even on non-zero exit (e.g. partial render with warnings).
+        // Check for output before giving up.
+        if (fs.existsSync(outFile)) {
+            console.warn('[PlantUML jar] render completed with warnings');
+            if (err && typeof err === 'object' && 'stderr' in err) {
+                console.warn('[PlantUML jar] stderr:', String(err.stderr));
+            }
+            return fs.readFileSync(outFile);
+        }
+        console.error('[PlantUML jar] render failed:', err.message);
+        if (err && typeof err === 'object' && 'stderr' in err) {
+            console.error('[PlantUML jar] stderr:', String(err.stderr));
+        }
+        return null;
+    }
+    finally {
+        // Clean up temp dir
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Try rendering via a PlantUML server endpoint.
+ * Returns the output buffer, or null on failure.
+ */
+async function renderViaServer(source, format, serverUrl) {
+    try {
+        const encoded = plantumlEncoder.encode(source);
+        const url = `${serverUrl.replace(/\/+$/, '')}/${format}/${encoded}`;
+        const resp = await fetch(url, { signal: AbortSignal.timeout(15_000) });
+        if (!resp.ok)
+            return null;
+        return Buffer.from(await resp.arrayBuffer());
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Render a PlantUML file with the full fallback pipeline.
+ * Returns \{ buffer, method \} or null if all methods fail.
+ */
+export async function renderPlantUml(filePath, format = 'svg') {
+    // 1. Try local jar (supports includes)
+    const jarResult = renderViaJar(filePath, format);
+    if (jarResult)
+        return { buffer: jarResult, method: 'jar' };
+    // 2. Try configured servers in order
+    const { plantuml } = getConfig();
+    const source = fs.readFileSync(filePath, 'utf8');
+    for (const server of plantuml.servers) {
+        const serverResult = await renderViaServer(source, format, server);
+        if (serverResult)
+            return { buffer: serverResult, method: server };
+    }
+    return null;
+}
+/**
+ * Render PlantUML source string to SVG.
+ * Writes to a temp file, renders via the full pipeline, cleans up.
+ */
+export async function renderPlantUmlFromSource(source) {
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'puml-src-'));
+    const inFile = path.join(tmpDir, 'diagram.puml');
+    try {
+        fs.writeFileSync(inFile, source, 'utf8');
+        return await renderPlantUmlSvg(inFile);
+    }
+    finally {
+        try {
+            fs.rmSync(tmpDir, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+/**
+ * Render PlantUML to SVG string (convenience for file API).
+ */
+export async function renderPlantUmlSvg(filePath) {
+    const result = await renderPlantUml(filePath, 'svg');
+    if (!result)
+        return null;
+    return result.buffer.toString('utf8');
+}
+/**
+ * Render PlantUML to buffer for export.
+ */
+export async function renderPlantUmlToBuffer(filePath, format) {
+    const result = await renderPlantUml(filePath, format);
+    return result?.buffer ?? null;
+}
+/**
+ * Get all export formats supported by PlantUML.
+ */
+export function getPlantUmlFormats() {
+    // PlantUML jar supports all these; server supports svg/png/txt
+    const { plantuml } = getConfig();
+    if (plantuml.jarPath) {
+        return ['svg', 'png', 'pdf', 'eps'];
+    }
+    // Server-only: limited formats
+    return ['svg', 'png'];
+}

package/dist/src/services/puppeteer.js

@@ -0,0 +1,156 @@
+/**
+ * Puppeteer browser management and page preparation utilities.
+ * Shared by PDF and DOCX export paths.
+ */
+import puppeteer from 'puppeteer-core';
+import { getConfig } from '../config/index.js';
+/**
+ * Launch Puppeteer browser with configured Chrome path.
+ */
+export async function launchBrowser() {
+    const { chromePath } = getConfig();
+    return await puppeteer.launch({
+        executablePath: chromePath,
+        headless: true,
+        args: ['--no-sandbox', '--disable-setuid-sandbox'],
+    });
+}
+/** Print CSS — hides chrome, normalizes layout for clean export. */
+const PRINT_CSS = `
+  /* Hide chrome — works for both legacy server-rendered and SPA */
+  .header, .header-actions, .panzoom-container, .panzoom-hint,
+  header, nav, .toc-sidebar, [class*="sticky"], [class*="fixed"] { display: none !important; }
+  .toc { position: static !important; height: auto !important; page-break-after: always; }
+  .toc-spacer { display: none !important; }
+  .layout { display: block !important; }
+  body { background: #fff !important; font-size: 10pt !important; line-height: 1.5 !important; color: #000 !important; }
+  /* SPA layout: remove scroll containers so body grows to full content height */
+  html, body, #root { height: auto !important; overflow: visible !important; }
+  main, [class*="overflow-y"] { overflow: visible !important; height: auto !important; }
+  /* SPA article.prose */
+  article.prose { max-width: none !important; border: none !important; padding: 0 !important; }
+  .content, article.prose { font-size: 10pt !important; }
+  /* Hide tab bar and other SPA controls */
+  [role="tablist"], button { display: none !important; }
+  main { padding-top: 0 !important; }
+  /* Inline SVG Panzoom & Embedded Diagrams: strip container chrome, show SVGs cleanly */
+  .inline-svg-panzoom, .embedded-diagram-panzoom, .embedded-diagram-rendered { 
+    position: static !important; 
+    background: white !important; 
+    border: none !important; 
+    overflow: visible !important;
+    cursor: default !important;
+    padding: 0 !important;
+    margin: 1em 0 !important;
+  }
+  .inline-svg-panzoom button, .embedded-diagram-panzoom button { display: none !important; }
+  .inline-svg-panzoom .text-xs, .embedded-diagram-panzoom .text-xs { display: none !important; }
+  .inline-svg-panzoom svg, .embedded-diagram-panzoom svg, .embedded-diagram-rendered svg {
+    max-width: 190mm !important;
+    max-height: 250mm !important;
+    width: auto !important;
+    height: auto !important;
+    display: block !important;
+    page-break-inside: avoid !important;
+  }
+  h1 { font-size: 18pt !important; }
+  h2 { font-size: 14pt !important; }
+  h3 { font-size: 12pt !important; }
+  h4, h5, h6 { font-size: 10pt !important; }
+  code { font-size: 9pt !important; }
+  pre { font-size: 8pt !important; background: #f5f5f5 !important; border: 1px solid #e0e0e0 !important; border-radius: 4px !important; padding: 8px !important; overflow-wrap: break-word !important; white-space: pre-wrap !important; }
+  pre code { font-size: 8pt !important; }
+  table { font-size: 10pt !important; }
+  a.anchor { display: none !important; }
+  img, svg, .svg-container, .zoomable-svg { 
+    max-width: 190mm !important; 
+    max-height: 250mm !important; 
+    width: auto !important; 
+    height: auto !important;
+    display: block !important;
+    page-break-inside: avoid !important; 
+  }
+  img { object-fit: contain !important; }
+`;
+/**
+ * Add print styles to a Puppeteer page.
+ */
+export async function addPrintStyles(page) {
+    await page.addStyleTag({ content: PRINT_CSS });
+}
+/**
+ * Wait for SPA content to fully render, including async SVG fetches.
+ */
+export async function waitForSpaContent(page) {
+    await page
+        .waitForSelector('article.prose', { timeout: 15_000 })
+        .catch(() => { });
+    await page
+        .waitForFunction(() => {
+        const containers = document.querySelectorAll('.inline-svg-panzoom');
+        if (containers.length === 0)
+            return true;
+        return Array.from(containers).every((c) => !c.textContent.includes('Loading SVG'));
+    }, { timeout: 15_000 })
+        .catch(() => { });
+    // Wait for CM6 code blocks to mount
+    await page
+        .waitForFunction(() => {
+        const article = document.querySelector('article.prose');
+        if (!article)
+            return true;
+        // If there are no code blocks, or CM6 has signaled ready
+        const codeBlocks = article.querySelectorAll('.cm6-embedded-code');
+        if (codeBlocks.length === 0)
+            return true;
+        return article.getAttribute('data-cm6-ready') === 'true';
+    }, { timeout: 15_000 })
+        .catch(() => { });
+    await new Promise((r) => setTimeout(r, 1000));
+}
+/** SVG container selectors used across export paths. */
+export const SVG_CONTAINER_SELECTORS = '.svg-container, .zoomable-svg, .inline-svg-panzoom, .embedded-diagram-panzoom, .embedded-diagram-rendered';
+/**
+ * Capture each SVG in a page as a high-quality PNG screenshot.
+ * Returns array of \{ index, dataUrl, width, height \}.
+ */
+export async function captureSvgsAsPng(browser, page) {
+    const svgContents = await page.evaluate((selectors) => {
+        const containers = document.querySelectorAll(selectors);
+        return Array.from(containers).map((container, i) => {
+            const svg = container.querySelector('svg');
+            return { index: i, svgHtml: svg ? svg.outerHTML : null };
+        });
+    }, SVG_CONTAINER_SELECTORS);
+    const results = [];
+    for (const { index, svgHtml } of svgContents) {
+        if (!svgHtml)
+            continue;
+        const svgPage = await browser.newPage();
+        await svgPage.setViewport({
+            width: 1200,
+            height: 2000,
+            deviceScaleFactor: 2,
+        });
+        await svgPage.setContent(`<!DOCTYPE html>
+<html><head><style>
+  body { margin: 0; padding: 0; background: #fff; }
+  svg { width: 1152px; height: auto; display: block; }
+</style></head><body>${svgHtml}</body></html>`, { waitUntil: 'networkidle0' });
+        const svgHandle = await svgPage.$('svg');
+        if (svgHandle) {
+            const screenshot = await svgHandle.screenshot({ type: 'png' });
+            const box = await svgHandle.boundingBox();
+            if (box && box.width > 0 && box.height > 0) {
+                results.push({
+                    index,
+                    dataUrl: `data:image/png;base64,${Buffer.from(screenshot).toString('base64')}`,
+                    width: Math.ceil(box.width),
+                    height: Math.ceil(box.height),
+                });
+            }
+        }
+        await svgPage.close();
+    }
+    return results;
+}

package/dist/src/util/breadcrumbs.js

@@ -0,0 +1,22 @@
+/**
+ * Breadcrumb filtering utilities.
+ */
+/**
+ * Filter breadcrumbs for outsiders:
+ * - File shares: no breadcrumbs (the page stands alone)
+ * - Directory shares: trim to the share root (matchedPath)
+ */
+export function filterBreadcrumbsForOutsider(breadcrumbs, isInsider, matchedPath, isDirectoryView) {
+    if (isInsider)
+        return breadcrumbs;
+    if (!isDirectoryView)
+        return breadcrumbs.length > 0 ? [breadcrumbs[breadcrumbs.length - 1]] : [];
+    // For directory views, trim breadcrumbs to the matched (shared) path root
+    if (matchedPath) {
+        const normalizedMatch = matchedPath.replace(/^\/+|\/+$/g, '').toLowerCase();
+        const matchIdx = breadcrumbs.findIndex((b) => b.path.replace(/^\/+|\/+$/g, '').toLowerCase() === normalizedMatch);
+        if (matchIdx >= 0)
+            return breadcrumbs.slice(matchIdx);
+    }
+    return breadcrumbs;
+}

package/dist/src/util/crypto.js

@@ -0,0 +1,56 @@
+/**
+ * Cryptographic utilities for key computation and verification
+ */
+import crypto from 'node:crypto';
+/**
+ * Compute path-specific key: HMAC-SHA256(apiKey, normalizedPath)
+ */
+export function computePathKey(apiKey, urlPath) {
+    const normalized = urlPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+    const hash = crypto
+        .createHmac('sha256', apiKey)
+        .update(normalized)
+        .digest('hex');
+    return hash.substring(0, 32);
+}
+/**
+ * Compute insider key: HMAC-SHA256(apiKey, "insider")
+ * Works for any path, grants full navigation
+ */
+export function computeInsiderKey(apiKey) {
+    const hash = crypto
+        .createHmac('sha256', apiKey)
+        .update('insider')
+        .digest('hex');
+    return hash.substring(0, 32);
+}
+/**
+ * Compute outsider key with expiry: HMAC-SHA256(apiKey, path + "|" + expiry)
+ */
+export function computeOutsiderKeyWithExpiry(apiKey, urlPath, expiry) {
+    const normalized = urlPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+    const data = `${normalized}|${String(expiry)}`;
+    const hash = crypto.createHmac('sha256', apiKey).update(data).digest('hex');
+    return hash.substring(0, 32);
+}
+/**
+ * Compute deep share key: HMAC-SHA256(seed, path + "|" + d + "|" + dirs + "|" + stack + "|" + exp)
+ * Used for share links with depth \> 0 or dirs enabled.
+ */
+export function computeDeepShareKey(seed, urlPath, params) {
+    const normalized = urlPath.toLowerCase().replace(/^\/+|\/+$/g, '');
+    const data = `${normalized}|${String(params.depth)}|${params.dirs ? '1' : '0'}|${params.stack}|${params.exp ?? ''}`;
+    const hash = crypto.createHmac('sha256', seed).update(data).digest('hex');
+    return hash.substring(0, 32);
+}
+/**
+ * Timing-safe string comparison
+ */
+export function timingSafeEqual(a, b) {
+    try {
+        return crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/util/crypto.test.js

@@ -0,0 +1,99 @@
+/**
+ * Tests for cryptographic utilities
+ */
+import { describe, expect, it } from 'vitest';
+import { computeInsiderKey, computeOutsiderKeyWithExpiry, computePathKey, timingSafeEqual, } from './crypto.js';
+describe('crypto utilities', () => {
+    const testApiKey = 'test-api-key-12345';
+    describe('computePathKey', () => {
+        it('should compute a 32-character hex key', () => {
+            const key = computePathKey(testApiKey, '/foo/bar');
+            expect(key).toMatch(/^[a-f0-9]{32}$/);
+        });
+        it('should normalize paths (case-insensitive)', () => {
+            const key1 = computePathKey(testApiKey, '/Foo/Bar');
+            const key2 = computePathKey(testApiKey, '/foo/bar');
+            expect(key1).toBe(key2);
+        });
+        it('should normalize paths (trim slashes)', () => {
+            const key1 = computePathKey(testApiKey, '/foo/bar/');
+            const key2 = computePathKey(testApiKey, 'foo/bar');
+            expect(key1).toBe(key2);
+        });
+        it('should produce different keys for different paths', () => {
+            const key1 = computePathKey(testApiKey, '/foo/bar');
+            const key2 = computePathKey(testApiKey, '/baz/qux');
+            expect(key1).not.toBe(key2);
+        });
+        it('should produce different keys for different API keys', () => {
+            const key1 = computePathKey('api-key-1', '/foo/bar');
+            const key2 = computePathKey('api-key-2', '/foo/bar');
+            expect(key1).not.toBe(key2);
+        });
+    });
+    describe('computeInsiderKey', () => {
+        it('should compute a 32-character hex key', () => {
+            const key = computeInsiderKey(testApiKey);
+            expect(key).toMatch(/^[a-f0-9]{32}$/);
+        });
+        it('should be deterministic (same API key = same insider key)', () => {
+            const key1 = computeInsiderKey(testApiKey);
+            const key2 = computeInsiderKey(testApiKey);
+            expect(key1).toBe(key2);
+        });
+        it('should produce different keys for different API keys', () => {
+            const key1 = computeInsiderKey('api-key-1');
+            const key2 = computeInsiderKey('api-key-2');
+            expect(key1).not.toBe(key2);
+        });
+    });
+    describe('computeOutsiderKeyWithExpiry', () => {
+        it('should compute a 32-character hex key', () => {
+            const expiry = Date.now() + 3600000;
+            const key = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry);
+            expect(key).toMatch(/^[a-f0-9]{32}$/);
+        });
+        it('should normalize paths (case-insensitive)', () => {
+            const expiry = Date.now() + 3600000;
+            const key1 = computeOutsiderKeyWithExpiry(testApiKey, '/Foo/Bar', expiry);
+            const key2 = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry);
+            expect(key1).toBe(key2);
+        });
+        it('should produce different keys for different expiries', () => {
+            const expiry1 = Date.now() + 3600000;
+            const expiry2 = Date.now() + 7200000;
+            const key1 = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry1);
+            const key2 = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry2);
+            expect(key1).not.toBe(key2);
+        });
+        it('should accept string expiry', () => {
+            const expiry = String(Date.now() + 3600000);
+            const key = computeOutsiderKeyWithExpiry(testApiKey, '/foo/bar', expiry);
+            expect(key).toMatch(/^[a-f0-9]{32}$/);
+        });
+    });
+    describe('timingSafeEqual', () => {
+        it('should return true for equal strings', () => {
+            const a = 'abc123';
+            const b = 'abc123';
+            expect(timingSafeEqual(a, b)).toBe(true);
+        });
+        it('should return false for different strings', () => {
+            const a = 'abc123';
+            const b = 'def456';
+            expect(timingSafeEqual(a, b)).toBe(false);
+        });
+        it('should return false for strings of different lengths', () => {
+            const a = 'abc';
+            const b = 'abcdef';
+            expect(timingSafeEqual(a, b)).toBe(false);
+        });
+        it('should return false for empty strings vs non-empty', () => {
+            expect(timingSafeEqual('', 'abc')).toBe(false);
+            expect(timingSafeEqual('abc', '')).toBe(false);
+        });
+        it('should return true for empty strings', () => {
+            expect(timingSafeEqual('', '')).toBe(true);
+        });
+    });
+});

package/dist/src/util/fileDetection.js

@@ -0,0 +1,66 @@
+/**
+ * File type detection and content-type mapping
+ */
+import mime from 'mime-types';
+/**
+ * Override map for extensions where mime-types returns an incorrect or
+ * unhelpful result for our use case.
+ */
+const OVERRIDES = {
+    '.mmd': 'text/plain; charset=utf-8',
+    '.puml': 'text/plain; charset=utf-8',
+    '.plantuml': 'text/plain; charset=utf-8',
+    '.pu': 'text/plain; charset=utf-8',
+    '.log': 'text/plain; charset=utf-8',
+    '.jsonl': 'text/plain; charset=utf-8',
+};
+/**
+ * Detect if a buffer looks like text (no null bytes in first 8KB)
+ */
+export function looksLikeText(buffer) {
+    const checkSize = Math.min(buffer.length, 8192);
+    for (let i = 0; i < checkSize; i++) {
+        if (buffer[i] === 0)
+            return false;
+    }
+    return true;
+}
+/**
+ * Get content type for a file extension (with leading dot, e.g. '.md')
+ */
+export function getContentType(ext) {
+    const dotExt = ext.startsWith('.') ? ext : `.${ext}`;
+    if (OVERRIDES[dotExt.toLowerCase()])
+        return OVERRIDES[dotExt.toLowerCase()];
+    // mime-types expects extension without the dot
+    return mime.contentType(dotExt.slice(1)) || 'application/octet-stream';
+}
+/**
+ * Standard content-type map for diagram export formats.
+ */
+export const DIAGRAM_CONTENT_TYPES = {
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    pdf: 'application/pdf',
+    eps: 'application/postscript',
+    txt: 'text/plain; charset=utf-8',
+    latex: 'application/x-latex',
+};
+/**
+ * Map file extensions to highlight.js language identifiers.
+ */
+/**
+ * Check if a content type should be displayed inline
+ */
+export function isInlineType(contentType) {
+    const inlineTypes = [
+        'image/',
+        'video/',
+        'audio/',
+        'text/',
+        'application/pdf',
+        'application/json',
+        'application/xml',
+    ];
+    return inlineTypes.some((type) => contentType.startsWith(type));
+}

package/dist/src/util/fileDetection.test.js

@@ -0,0 +1,89 @@
+/**
+ * Tests for file detection utilities
+ */
+import { describe, expect, it } from 'vitest';
+import { getContentType, isInlineType, looksLikeText, } from './fileDetection.js';
+describe('file detection', () => {
+    describe('looksLikeText', () => {
+        it('should return true for plain text', () => {
+            const buffer = Buffer.from('Hello, world!', 'utf8');
+            expect(looksLikeText(buffer)).toBe(true);
+        });
+        it('should return true for text with newlines', () => {
+            const buffer = Buffer.from('Line 1\nLine 2\nLine 3', 'utf8');
+            expect(looksLikeText(buffer)).toBe(true);
+        });
+        it('should return false for binary data with null bytes', () => {
+            const buffer = Buffer.from([0x48, 0x65, 0x00, 0x6c, 0x6c, 0x6f]); // He\0llo
+            expect(looksLikeText(buffer)).toBe(false);
+        });
+        it('should return false for binary data at start', () => {
+            const buffer = Buffer.from([0x00, 0x01, 0x02, 0x03]);
+            expect(looksLikeText(buffer)).toBe(false);
+        });
+        it('should only check first 8KB', () => {
+            // Create 10KB buffer with null byte at position 9000
+            const buffer = Buffer.alloc(10240);
+            buffer.fill('A'.charCodeAt(0), 0, 9000);
+            buffer[9000] = 0;
+            buffer.fill('A'.charCodeAt(0), 9001);
+            // Should return true because null byte is beyond 8KB
+            expect(looksLikeText(buffer)).toBe(true);
+        });
+        it('should handle empty buffer', () => {
+            const buffer = Buffer.alloc(0);
+            expect(looksLikeText(buffer)).toBe(true);
+        });
+    });
+    describe('getContentType', () => {
+        it('should return correct type for text files', () => {
+            expect(getContentType('.txt')).toBe('text/plain; charset=utf-8');
+            expect(getContentType('.json')).toBe('application/json; charset=utf-8');
+            expect(getContentType('.html')).toBe('text/html; charset=utf-8');
+        });
+        it('should return correct type for images', () => {
+            expect(getContentType('.png')).toBe('image/png');
+            expect(getContentType('.jpg')).toBe('image/jpeg');
+            expect(getContentType('.svg')).toBe('image/svg+xml');
+        });
+        it('should return correct type for documents', () => {
+            expect(getContentType('.pdf')).toBe('application/pdf');
+            expect(getContentType('.docx')).toBe('application/vnd.openxmlformats-officedocument.wordprocessingml.document');
+        });
+        it('should be case-insensitive', () => {
+            expect(getContentType('.PDF')).toBe('application/pdf');
+            expect(getContentType('.TxT')).toBe('text/plain; charset=utf-8');
+        });
+        it('should return octet-stream for unknown extensions', () => {
+            expect(getContentType('.unknown')).toBe('application/octet-stream');
+            expect(getContentType('.xyz123')).toBe('application/octet-stream');
+        });
+    });
+    describe('isInlineType', () => {
+        it('should return true for text types', () => {
+            expect(isInlineType('text/plain; charset=utf-8')).toBe(true);
+            expect(isInlineType('text/html')).toBe(true);
+        });
+        it('should return true for images', () => {
+            expect(isInlineType('image/png')).toBe(true);
+            expect(isInlineType('image/jpeg')).toBe(true);
+        });
+        it('should return true for video/audio', () => {
+            expect(isInlineType('video/mp4')).toBe(true);
+            expect(isInlineType('audio/mpeg')).toBe(true);
+        });
+        it('should return true for JSON and PDF', () => {
+            expect(isInlineType('application/json; charset=utf-8')).toBe(true);
+            expect(isInlineType('application/pdf')).toBe(true);
+            expect(isInlineType('application/xml')).toBe(true);
+        });
+        it('should return false for archives', () => {
+            expect(isInlineType('application/zip')).toBe(false);
+            expect(isInlineType('application/x-tar')).toBe(false);
+        });
+        it('should return false for executables', () => {
+            expect(isInlineType('application/octet-stream')).toBe(false);
+            expect(isInlineType('application/x-msdownload')).toBe(false);
+        });
+    });
+});

package/dist/src/util/formatters.js

@@ -0,0 +1,43 @@
+/**
+ * Formatting utilities for dates, file sizes, etc.
+ */
+/**
+ * Format file size in human-readable format
+ */
+export function formatSize(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const units = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(1024));
+    const value = bytes / Math.pow(1024, i);
+    const decimals = i > 0 ? 1 : 0;
+    return `${value.toFixed(decimals)} ${units[i]}`;
+}
+/**
+ * Format ISO timestamp as relative time (e.g., "2h ago")
+ */
+export function formatRelativeTime(isoTimestamp) {
+    if (!isoTimestamp)
+        return null;
+    const then = new Date(isoTimestamp).getTime();
+    const now = Date.now();
+    const diffMs = now - then;
+    if (diffMs < 0)
+        return null;
+    const mins = Math.floor(diffMs / 60000);
+    const hours = Math.floor(mins / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${String(days)}d ago`;
+    if (hours > 0)
+        return `${String(hours)}h ago`;
+    if (mins > 0)
+        return `${String(mins)}m ago`;
+    return 'just now';
+}
+/**
+ * Get current ISO timestamp
+ */
+export function nowIso() {
+    return new Date().toISOString();
+}