termcard 0.0.0-stage → 0.2.0

package/src/i18n/locales/tr.js

@@ -0,0 +1,39 @@
+export default {
+  'meta.name': 'Türkçe',
+  'label.website': 'Web',
+  'label.email': 'E-posta',
+  'label.phone': 'Telefon',
+  'action.contact': 'İletişime geç',
+  'hint.contact': 'E-posta istemcinizde yeni bir ileti taslağı açar.',
+  'action.save': 'Rehbere ekle',
+  'hint.save': 'Kişi kartını (vCard) cihazınızın rehberine aktarır.',
+  'action.website': 'Web sitesini ziyaret et',
+  'hint.website': '{host} adresini tarayıcıda açar.',
+  'action.link': '{label} profilini görüntüle',
+  'hint.link': '{host} adresini tarayıcıda açar.',
+  'action.copyEmail': 'E-posta adresini kopyala',
+  'hint.copyEmail': 'Adresi panoya kopyalar.',
+  'action.copyPhone': 'Telefon numarasını kopyala',
+  'hint.copyPhone': 'Numarayı panoya kopyalar.',
+  'action.language': 'Dil',
+  'hint.language': 'Kartı başka bir dilde gösterir.',
+  'action.back': 'Geri',
+  'hint.back': 'Ana menüye döner.',
+  'action.exit': 'Çıkış',
+  'hint.exit': 'Kartı kapatır.',
+  'status.contact': 'E-posta taslağı açıldı.',
+  'status.contactFailed': 'E-posta istemcisi açılamadı — {value}',
+  'status.save': 'Kişi kartı açıldı.',
+  'status.saveFailed': 'Kişi kartı kaydedildi: {value}',
+  'status.saveError': 'Kişi kartı oluşturulamadı.',
+  'status.browser': 'Tarayıcıda açıldı.',
+  'status.browserFailed': 'Tarayıcı açılamadı — {value}',
+  'status.copied': 'Panoya kopyalandı.',
+  'status.copyFailed': 'Panoya erişilemedi — {value}',
+  'status.language': 'Dil değiştirildi.',
+  'keys.navigate': 'gezin',
+  'keys.select': 'seç',
+  'keys.quit': 'çıkış',
+  'keys.back': 'geri',
+  'mail.subject': 'Merhaba',
+};

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * termcard — public API.
+ *
+ *   import { start } from 'termcard';
+ *   start(new URL('../card.config.json', import.meta.url));
+ */
+
+export { start, run } from './run.js';
+export { loadConfig } from './config/load.js';
+export { normalizeConfig, ConfigError, isEmail, urlProblem, TEXT_LIMIT, DESCRIPTION_LIMIT, ICON_SETS } from './config/schema.js';
+export { templates, DEFAULT_TEMPLATE } from './config/templates.js';
+export { themes, THEME_DESCRIPTIONS, DEFAULT_THEME } from './config/themes.js';
+export { BUILT_IN_LANGUAGES, detectLanguage, languageName } from './i18n/index.js';
+export { layoutCard, layoutHeader } from './render/card.js';
+export { toAnsi, toPlain, toHtml } from './render/format.js';
+export { colorDepth } from './render/color.js';
+export { createVCard } from './vcard.js';
+export { buildCard, UnsafeOutputError } from './build/index.js';
+export { slugify } from './text.js';

package/src/render/borders.js

@@ -0,0 +1,7 @@
+export const borders = {
+  rounded: { tl: '╭', tr: '╮', bl: '╰', br: '╯', h: '─', v: '│' },
+  square: { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' },
+  double: { tl: '╔', tr: '╗', bl: '╚', br: '╝', h: '═', v: '║' },
+  heavy: { tl: '┏', tr: '┓', bl: '┗', br: '┛', h: '━', v: '┃' },
+  none: null,
+};

package/src/render/card.js

@@ -0,0 +1,122 @@
+/**
+ * Card layout. Produces format-independent lines of segments:
+ *   { text, role?, href?, frame? }
+ * `role` maps to a theme color, `frame` marks border/padding that the HTML
+ * renderer replaces with CSS. Formatters live in ./format.js.
+ */
+
+import { displayWidth, localize, stripProtocol, upper, wrap } from '../text.js';
+import { createTranslator } from '../i18n/index.js';
+import { borders } from './borders.js';
+import { iconFor } from './icons.js';
+import { templates } from '../config/templates.js';
+
+const INDENT = '  ';
+const seg = (text, role, href) => ({ text, role, href });
+const frame = (text, role) => ({ text, role, frame: true });
+const widthOf = (segments) => segments.reduce((n, s) => n + displayWidth(s.text), 0);
+
+function nameLines(name, { nameStyle, splitName }, lang) {
+  const words = name.split(/\s+/);
+  const parts = splitName && words.length > 1 ? [words.slice(0, -1).join(' '), words.at(-1)] : [name];
+  return parts.map((part) => {
+    if (nameStyle === 'spaced') return [...upper(part, lang)].join(' ');
+    if (nameStyle === 'uppercase') return upper(part, lang);
+    return part;
+  });
+}
+
+/** The contact rows the card shows, in the configured order. */
+export function contactRows(config, t, iconSet = config.icons) {
+  const rows = {
+    website: config.website && { label: t('label.website'), value: stripProtocol(config.website), href: config.website, icon: iconFor(iconSet, 'website') },
+    email: config.email && { label: t('label.email'), value: config.email, href: `mailto:${config.email}`, icon: iconFor(iconSet, 'email') },
+    phone: config.phone && { label: t('label.phone'), value: config.phone, href: `tel:${config.phone.replace(/[^\d+]/g, '')}`, icon: iconFor(iconSet, 'phone') },
+  };
+  for (const link of config.links) {
+    rows[link.id] = { label: link.label, value: stripProtocol(link.url), href: link.url, icon: iconFor(iconSet, 'link', link) };
+  }
+  return config.card.fields.filter((f) => f !== 'location').map((f) => rows[f]).filter(Boolean);
+}
+
+/** Width that the description wraps to: the card's inner width, or a comfortable default. */
+const descriptionWidth = (card, box) => (typeof card.width === 'number' && box ? card.width - 2 - card.padding * 2 : 46);
+
+/** Options for `layoutCard`: { iconSet } overrides config.icons (the web page uses this). */
+/** One-line header shown above the menu when the card itself is turned off. */
+export function layoutHeader(config, lang) {
+  const text = (value) => localize(value, lang);
+  const first = [seg(config.name, 'name')];
+  if (config.tagline) first.push(seg('  ·  ', 'faint'), seg(text(config.tagline), 'accent'));
+  const lines = [first];
+  if (config.title) lines.push([seg(text(config.title), 'muted')]);
+  if (config.description) for (const line of wrap(text(config.description), 60)) lines.push([seg(line, 'muted')]);
+  return lines.map((line) => [frame(INDENT), ...line]);
+}
+
+export function layoutCard(config, lang, { iconSet = config.icons } = {}) {
+  // With "card": false the card is still printed where no menu can be shown (pipes, --card).
+  const card = config.card.enabled ? config.card : { ...config.card, ...templates.minimal };
+  const t = createTranslator(lang, config.strings);
+  const text = (value) => localize(value, lang);
+  const relaxed = card.spacing === 'relaxed';
+
+  // Content sections; blank lines are inserted between them.
+  const sections = [];
+  const head = nameLines(config.name, card, lang).map((n) => [seg(n, 'name')]);
+  if (config.title) head.push([seg(text(config.title), 'muted')]);
+
+  const brand = [];
+  if (config.tagline) brand.push([seg(text(config.tagline), 'accent')]);
+  if (card.accentRule) brand.push([seg('───', 'accent')]);
+  if (config.description) {
+    for (const line of wrap(text(config.description), descriptionWidth(card, borders[card.border]))) brand.push([seg(line, 'muted')]);
+  }
+
+  if (relaxed) sections.push(head, brand);
+  else sections.push([...head, ...brand]);
+
+  const rows = contactRows(config, t, iconSet);
+  const labelWidth = Math.max(0, ...rows.map((r) => displayWidth(r.label))) + 2;
+  const iconWidth = Math.max(0, ...rows.map((r) => displayWidth(r.icon)), displayWidth(iconFor(iconSet, 'location')));
+  const icon = (glyph) => (iconWidth ? [seg(glyph + ' '.repeat(iconWidth - displayWidth(glyph) + 1), 'accent')] : []);
+  sections.push(
+    rows.map((r) => [
+      ...icon(r.icon),
+      ...(card.labels ? [seg(r.label + ' '.repeat(labelWidth - displayWidth(r.label)), 'muted')] : []),
+      seg(r.value, 'text', r.href),
+    ]),
+  );
+
+  const location =
+    card.fields.includes('location') && config.location ? [...icon(iconFor(iconSet, 'location')), seg(text(config.location), 'muted')] : null;
+  const body = sections.filter((s) => s.length).flatMap((s, i) => (i ? [[], ...s] : s));
+  if (location) body.push([], { right: card.locationAlign === 'right', segments: location });
+
+  // Normalize to { segments, right } and compute the inner width.
+  const content = body.map((l) => (Array.isArray(l) ? { segments: l, right: false } : l));
+  const pad = card.padding;
+  const box = borders[card.border];
+  const contentWidth = Math.max(...content.map((l) => widthOf(l.segments)));
+  const innerWidth = Math.max(contentWidth + pad * 2, card.width === 'auto' || !box ? 0 : card.width - 2);
+  const usable = innerWidth - pad * 2;
+
+  const place = ({ segments, right }) => {
+    const fill = seg(' '.repeat(Math.max(0, usable - widthOf(segments))));
+    return right ? [fill, ...segments] : [...segments, fill];
+  };
+
+  if (!box) {
+    return content.map((l) => [frame(INDENT), ...(l.right ? place(l) : l.segments)]);
+  }
+
+  const row = (segments) => [frame(INDENT), frame(box.v, 'faint'), frame(' '.repeat(pad)), ...segments, frame(' '.repeat(pad)), frame(box.v, 'faint')];
+  const blank = row([seg(' '.repeat(usable))]);
+  return [
+    [frame(INDENT), frame(box.tl + box.h.repeat(innerWidth) + box.tr, 'faint')],
+    ...(relaxed ? [blank] : []),
+    ...content.map((l) => row(place(l))),
+    ...(relaxed ? [blank] : []),
+    [frame(INDENT), frame(box.bl + box.h.repeat(innerWidth) + box.br, 'faint')],
+  ];
+}

package/src/render/color.js

@@ -0,0 +1,40 @@
+/** Terminal color support detection and hex → ANSI conversion. */
+
+const CUBE = [0, 95, 135, 175, 215, 255];
+
+const hexToRgb = (hex) => [1, 3, 5].map((i) => parseInt(hex.slice(i, i + 2), 16));
+const distance = (a, b) => a.reduce((sum, v, i) => sum + (v - b[i]) ** 2, 0);
+
+/** Closest xterm-256 palette index for a hex color (6×6×6 cube or grayscale ramp). */
+export function hexTo256(hex) {
+  const rgb = hexToRgb(hex);
+  const nearest = (v) => CUBE.reduce((best, level, i) => (Math.abs(level - v) < Math.abs(CUBE[best] - v) ? i : best), 0);
+  const [r, g, b] = rgb.map(nearest);
+  const cubeIndex = 16 + 36 * r + 6 * g + b;
+  const cubeRgb = [CUBE[r], CUBE[g], CUBE[b]];
+
+  const avg = (rgb[0] + rgb[1] + rgb[2]) / 3;
+  const grayStep = Math.max(0, Math.min(23, Math.round((avg - 8) / 10)));
+  const grayRgb = Array(3).fill(8 + grayStep * 10);
+
+  return distance(rgb, grayRgb) < distance(rgb, cubeRgb) ? 232 + grayStep : cubeIndex;
+}
+
+/**
+ * Color depth for a stream: 0 (none), 256, or 16777216 (truecolor).
+ * Honors the NO_COLOR (https://no-color.org) and FORCE_COLOR conventions.
+ */
+export function colorDepth(stream, env = {}) {
+  if ('NO_COLOR' in env && env.NO_COLOR !== '') return 0;
+  if (env.FORCE_COLOR === '0' || env.FORCE_COLOR === 'false') return 0;
+  const forced = env.FORCE_COLOR !== undefined;
+  if (!forced && (!stream?.isTTY || env.TERM === 'dumb')) return 0;
+  if (/^(truecolor|24bit)$/i.test(env.COLORTERM ?? '')) return 16777216;
+  return 256;
+}
+
+/** SGR parameters for a foreground hex color at the given depth. */
+export function foreground(hex, depth) {
+  if (depth >= 16777216) return `38;2;${hexToRgb(hex).join(';')}`;
+  return `38;5;${hexTo256(hex)}`;
+}

package/src/render/format.js

@@ -0,0 +1,46 @@
+/** Turns laid-out card lines into terminal (ANSI), plain text or HTML output. */
+
+import { foreground } from './color.js';
+
+const ROLE_COLOR = { name: 'text', text: 'text', muted: 'muted', faint: 'faint', accent: 'accent' };
+
+/** Returns a function that paints text in a theme role, or leaves it plain at depth 0. */
+export function createPainter(theme, depth) {
+  return (role, text) => {
+    if (!depth || !role) return text;
+    const color = theme[ROLE_COLOR[role] ?? 'text'];
+    const codes = [
+      ...(role === 'name' || role === 'strong' ? ['1'] : []),
+      ...(color && color !== 'default' ? [foreground(color, depth)] : []),
+    ];
+    return codes.length ? `\x1b[${codes.join(';')}m${text}\x1b[0m` : text;
+  };
+}
+
+export function toAnsi(lines, theme, depth = 256) {
+  const paint = createPainter(theme, depth);
+  return lines.map((line) => line.map((s) => paint(s.role, s.text)).join('').trimEnd()).join('\n');
+}
+
+export const toPlain = (lines) => lines.map((line) => line.map((s) => s.text).join('').trimEnd()).join('\n');
+
+export const escapeHtml = (text) =>
+  String(text).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c]);
+
+/** HTML for the web page. Frame segments are dropped — CSS draws the border. */
+export function toHtml(lines) {
+  const content = lines.map((line) => line.filter((s) => !s.frame)).filter((line, i, all) => line.length || (i > 0 && i < all.length - 1));
+  return content
+    .map((line) =>
+      line
+        .map((s) => {
+          const inner = s.role ? `<span class="${s.role}">${escapeHtml(s.text)}</span>` : escapeHtml(s.text);
+          if (!s.href) return inner;
+          const external = /^https?:/.test(s.href) ? ' target="_blank" rel="noopener noreferrer"' : '';
+          return `<a href="${escapeHtml(s.href)}"${external}>${inner}</a>`;
+        })
+        .join('')
+        .trimEnd(),
+    )
+    .join('\n');
+}

package/src/render/icons.js

@@ -0,0 +1,40 @@
+/**
+ * Icon sets for card rows and menu entries.
+ *
+ * - symbols: plain Unicode symbols that every terminal font has (default choice when icons are on)
+ * - emoji:   colorful, two columns wide; looks best on macOS and modern terminals
+ * - nerd:    brand icons; requires a Nerd Font (https://www.nerdfonts.com) in the visitor's
+ *            terminal, so it suits developer audiences. Web output falls back to symbols.
+ */
+
+const sets = {
+  symbols: {
+    website: '⌂', email: '✉', phone: '☎', location: '◎', link: '↗',
+    save: '+', language: '⇄', exit: '×',
+  },
+  emoji: {
+    website: '🌐', email: '📧', phone: '📞', location: '📍', link: '🔗',
+    save: '📇', language: '💬', exit: '👋',
+  },
+  nerd: {
+    website: '', email: '', phone: '', location: '', link: '',
+    save: '', language: '', exit: '',
+    github: '', gitlab: '', linkedin: '', x: '', instagram: '',
+    facebook: '', youtube: '', behance: '', dribbble: '', medium: '',
+    stackoverflow: '', codepen: '', npm: '',
+  },
+};
+
+/**
+ * Returns the icon for a key ("email", "website", …) or a link, or '' when icons are off.
+ * A link's own `icon` always wins.
+ */
+export function iconFor(set, key, link) {
+  if (link?.icon) return link.icon;
+  if (!sets[set]) return '';
+  if (link) return sets[set][link.service] ?? sets[set].link;
+  return sets[set][key] ?? '';
+}
+
+/** Icon set to use in HTML: Nerd Font glyphs are not available on the web. */
+export const webIconSet = (set) => (set === 'nerd' ? 'symbols' : set);

package/src/run.js

@@ -0,0 +1,80 @@
+/** Entry point used by every generated card package: `npx <name>`. */
+
+import { parseArgs } from 'node:util';
+import { loadConfig } from './config/load.js';
+import { ConfigError } from './config/schema.js';
+import { detectLanguage, createTranslator } from './i18n/index.js';
+import { layoutCard } from './render/card.js';
+import { toAnsi } from './render/format.js';
+import { colorDepth } from './render/color.js';
+import { createVCard } from './vcard.js';
+import { runInteractive } from './tui/app.js';
+import { buildMenu } from './tui/actions.js';
+
+const HELP = `Usage: npx <card> [options]
+
+Options:
+  --lang <code>   Show the card in a specific language
+  --card          Print the card without the interactive menu
+  --vcard         Print the contact card in vCard format
+  --json          Print the card details as JSON
+  --no-color      Disable colors
+  -h, --help      Show this help`;
+
+/** Public, display-only view of the config (what the card already shows). */
+const publicProfile = (config) => {
+  const { name, title, tagline, description, organization, email, phone, website, location, links } = config;
+  return JSON.parse(JSON.stringify({ name, title, tagline, description, organization, email, phone, website, location, links }));
+};
+
+/**
+ * Runs a card from a normalized config.
+ * @returns {Promise<number>} process exit code
+ */
+export async function run(config, { argv = process.argv.slice(2), env = process.env, stdin = process.stdin, stdout = process.stdout, stderr = process.stderr } = {}) {
+  let flags;
+  try {
+    ({ values: flags } = parseArgs({
+      args: argv,
+      options: {
+        lang: { type: 'string' },
+        card: { type: 'boolean' },
+        vcard: { type: 'boolean' },
+        json: { type: 'boolean' },
+        'no-color': { type: 'boolean' },
+        help: { type: 'boolean', short: 'h' },
+      },
+      strict: true,
+    }));
+  } catch (error) {
+    stderr.write(`${error.message}\n\n${HELP}\n`);
+    return 2;
+  }
+
+  if (flags.help) return stdout.write(`${HELP}\n`), 0;
+  const lang = detectLanguage(config.language, { flag: flags.lang, env });
+  if (flags.json) return stdout.write(`${JSON.stringify(publicProfile(config), null, 2)}\n`), 0;
+  if (flags.vcard) return stdout.write(createVCard(config, lang)), 0;
+
+  const depth = flags['no-color'] ? 0 : colorDepth(stdout, env);
+  const hasMenu = config.menu.enabled && buildMenu(config, lang, createTranslator(lang, config.strings)).length > 0;
+  const interactive = hasMenu && !flags.card && stdin.isTTY && stdout.isTTY && typeof stdin.setRawMode === 'function';
+  if (!interactive) {
+    stdout.write(`\n${toAnsi(layoutCard(config, lang), config.theme, depth)}\n\n`);
+    return 0;
+  }
+  await runInteractive(config, { lang, depth, stdin, stdout });
+  return 0;
+}
+
+/** Loads a JSON config file and runs it; prints readable errors instead of stack traces. */
+export async function start(configFile, options = {}) {
+  const stderr = options.stderr ?? process.stderr;
+  try {
+    process.exitCode = await run(loadConfig(configFile), options);
+  } catch (error) {
+    if (!(error instanceof ConfigError)) throw error;
+    stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/system.js

@@ -0,0 +1,73 @@
+/**
+ * The only module that touches the operating system.
+ * Commands are spawned without a shell and with fixed argument lists, so no
+ * value from a config can be interpreted as a shell command.
+ */
+
+import { spawn } from 'node:child_process';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+
+const SAFE_URL = /^(https?:\/\/|mailto:|tel:)/i;
+// Openers normally exit within milliseconds; one still running after this is treated as success.
+const OPENER_GRACE_MS = 1500;
+
+function openerFor(platform) {
+  if (platform === 'darwin') return ['open', []];
+  if (platform === 'win32') return ['rundll32', ['url.dll,FileProtocolHandler']];
+  return ['xdg-open', []];
+}
+
+/** Opens a URL (http, https, mailto, tel) or an absolute file path with the default app. */
+export function openExternal(target, platform = process.platform) {
+  if (!SAFE_URL.test(target) && !isAbsolute(target)) return Promise.resolve(false);
+  const [command, args] = openerFor(platform);
+  return new Promise((resolve) => {
+    const child = spawn(command, [...args, target], { stdio: 'ignore', detached: true, shell: false });
+    const timer = setTimeout(() => {
+      child.unref();
+      resolve(true);
+    }, OPENER_GRACE_MS);
+    timer.unref();
+    child.once('error', () => {
+      clearTimeout(timer);
+      resolve(false);
+    });
+    child.once('exit', (code) => {
+      clearTimeout(timer);
+      resolve(code === 0);
+    });
+  });
+}
+
+function clipboardTools(platform) {
+  if (platform === 'darwin') return [['pbcopy', []]];
+  if (platform === 'win32') return [['clip', []]];
+  return [['wl-copy', []], ['xclip', ['-selection', 'clipboard']], ['xsel', ['--clipboard', '--input']]];
+}
+
+/** Copies text using the platform clipboard tool. Resolves false if none is available. */
+export function copyToClipboard(text, platform = process.platform) {
+  const tools = clipboardTools(platform);
+  return new Promise((resolve) => {
+    const attempt = (i) => {
+      if (i >= tools.length) return resolve(false);
+      const [command, args] = tools[i];
+      const child = spawn(command, args, { stdio: ['pipe', 'ignore', 'ignore'], shell: false });
+      child.once('error', () => attempt(i + 1));
+      child.once('close', (code) => (code === 0 ? resolve(true) : attempt(i + 1)));
+      child.stdin.on('error', () => {});
+      child.stdin.end(text);
+    };
+    attempt(0);
+  });
+}
+
+/** Writes a file into a fresh private temp directory (mode 0600) and returns its path. */
+export function writeTempFile(name, content) {
+  const dir = mkdtempSync(join(tmpdir(), 'termcard-'));
+  const file = join(dir, name);
+  writeFileSync(file, content, { mode: 0o600 });
+  return file;
+}

package/src/text.js

@@ -0,0 +1,113 @@
+/**
+ * Text helpers shared by every renderer.
+ * All user-provided strings pass through `sanitize` before they reach a terminal or HTML.
+ */
+
+// C0/C1 control characters (incl. ESC) and bidirectional override characters.
+// Removing them prevents terminal escape injection and text-direction spoofing.
+const UNSAFE = /[\u0000-\u001f\u007f-\u009f‪-‮⁦-⁩]/g;
+
+export const sanitize = (value) => String(value).replace(UNSAFE, '').trim();
+
+const isZeroWidth = (cp) =>
+  (cp >= 0x0300 && cp <= 0x036f) || // combining diacritics
+  (cp >= 0x200b && cp <= 0x200f) || // zero-width space/joiners
+  (cp >= 0xfe00 && cp <= 0xfe0f); // variation selectors
+
+// Symbols below U+1F300 that terminals draw two columns wide (emoji presentation).
+const WIDE_SYMBOLS = [
+  [0x231a, 0x231b], [0x23e9, 0x23ec], [0x23f0, 0x23f0], [0x23f3, 0x23f3], [0x25fd, 0x25fe],
+  [0x2614, 0x2615], [0x2648, 0x2653], [0x267f, 0x267f], [0x2693, 0x2693], [0x26a1, 0x26a1],
+  [0x26aa, 0x26ab], [0x26bd, 0x26be], [0x26c4, 0x26c5], [0x26ce, 0x26ce], [0x26d4, 0x26d4],
+  [0x26ea, 0x26ea], [0x26f2, 0x26f3], [0x26f5, 0x26f5], [0x26fa, 0x26fa], [0x26fd, 0x26fd],
+  [0x2705, 0x2705], [0x270a, 0x270b], [0x2728, 0x2728], [0x274c, 0x274c], [0x274e, 0x274e],
+  [0x2753, 0x2755], [0x2757, 0x2757], [0x2795, 0x2797], [0x27b0, 0x27b0], [0x27bf, 0x27bf],
+  [0x2b1b, 0x2b1c], [0x2b50, 0x2b50], [0x2b55, 0x2b55],
+];
+
+const isWide = (cp) =>
+  WIDE_SYMBOLS.some(([from, to]) => cp >= from && cp <= to) ||
+  (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+  (cp >= 0x2e80 && cp <= 0xa4cf && cp !== 0x303f) || // CJK … Yi
+  (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+  (cp >= 0xf900 && cp <= 0xfaff) || // CJK compatibility ideographs
+  (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compatibility forms
+  (cp >= 0xff00 && cp <= 0xff60) || // fullwidth forms
+  (cp >= 0xffe0 && cp <= 0xffe6) ||
+  (cp >= 0x1f300 && cp <= 0x1faff) || // emoji & pictographs
+  (cp >= 0x20000 && cp <= 0x3fffd); // CJK extensions
+
+/** Number of terminal columns a string occupies (no escape sequences expected). */
+export function displayWidth(text) {
+  let width = 0;
+  for (const char of text) {
+    const cp = char.codePointAt(0);
+    if (isZeroWidth(cp)) continue;
+    width += isWide(cp) ? 2 : 1;
+  }
+  return width;
+}
+
+/** Replaces `{key}` placeholders. Unknown keys are left untouched. */
+export const format = (template, values = {}) =>
+  template.replace(/\{(\w+)\}/g, (match, key) => (key in values ? String(values[key]) : match));
+
+/**
+ * A localized value is either a plain string or an object keyed by language code.
+ * Falls back to the given fallback language, then to the first available entry.
+ */
+export function localize(value, lang, fallback = 'en') {
+  if (value == null) return '';
+  if (typeof value === 'string') return value;
+  return value[lang] ?? value[fallback] ?? Object.values(value)[0] ?? '';
+}
+
+/** Locale-aware uppercase that keeps Turkish dotted/dotless i correct. */
+export const upper = (text, lang) => text.toLocaleUpperCase(lang === 'tr' || lang === 'az' ? 'tr-TR' : undefined);
+
+export const stripProtocol = (url) => url.replace(/^https?:\/\/(www\.)?/, '').replace(/\/$/, '');
+
+const TRANSLITERATE = { ı: 'i', ß: 'ss', ø: 'o', æ: 'ae', œ: 'oe', ł: 'l', đ: 'd', þ: 'th' };
+
+/** "Ahmet Erkan Paşahan" → "ahmet-erkan-pasahan" (lowercase ASCII, dashes). */
+export function slugify(text) {
+  return text
+    .toLowerCase()
+    .replace(/[ıßøæœłđþ]/g, (ch) => TRANSLITERATE[ch])
+    .normalize('NFKD')
+    .replace(/[\u0300-\u036f]/g, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 50);
+}
+
+/** Removes ANSI SGR sequences (used to measure already-painted lines). */
+export const stripAnsi = (text) => text.replace(/\x1b\[[0-9;]*m/g, '');
+
+/** Word-wraps text to lines of at most `width` columns; overlong words are split. */
+export function wrap(text, width) {
+  const lines = [];
+  let line = '';
+  for (const word of text.split(/\s+/).filter(Boolean)) {
+    let rest = word;
+    while (displayWidth(rest) > width) {
+      let head = '';
+      for (const ch of rest) {
+        if (displayWidth(head + ch) > width) break;
+        head += ch;
+      }
+      if (line) lines.push(line);
+      lines.push(head);
+      line = '';
+      rest = rest.slice(head.length);
+    }
+    const candidate = line ? `${line} ${rest}` : rest;
+    if (displayWidth(candidate) <= width) line = candidate;
+    else {
+      lines.push(line);
+      line = rest;
+    }
+  }
+  if (line) lines.push(line);
+  return lines;
+}