@limeade-labs/sparkui-icons 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Limeade Labs, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# sparkui-icons
+
+Emoji → Lucide icon replacement library for SparkUI. Replaces 208 emoji characters with inline Lucide SVG icons in a single regex pass.
+
+## Installation
+
+```bash
+npm install @limeade-labs/sparkui-icons
+```
+
+## Usage
+
+```js
+const { replace, lookup, has } = require('@limeade-labs/sparkui-icons');
+
+// Replace emojis in HTML strings
+const html = '<h1>⚡ Dashboard</h1><p>📊 Stats and 🔥 Performance</p>';
+const result = replace(html);
+// Emojis are replaced with inline Lucide SVGs
+
+// Look up a single emoji
+const entry = lookup('⚡');
+// { name: 'zap', svg: '<svg class="lucide lucide-zap" ...' }
+
+// Check if an emoji is mapped
+has('⚡');  // true
+has('🦄');  // false
+```
+
+## API
+
+### `replace(html, options?)`
+
+Replace mapped emojis with inline SVGs.
+
+**Options:**
+| Option | Default | Description |
+|--------|---------|-------------|
+| `size` | `20` | Icon size in pixels |
+| `class` | `'sparkui-icon'` | CSS class for icons |
+| `preserveEmoji` | `true` | Keep emoji as `aria-label` for accessibility |
+| `strokeWidth` | `2` | SVG stroke width |
+| `variant` | `'outline'` | Rendering style: `'outline'`, `'filled'`, or `'duotone'` |
+| `color` | — | Color for filled variant |
+| `fillColor` | — | Fill color for duotone variant |
+| `strokeColor` | — | Stroke color for duotone variant |
+| `fillOpacity` | `0.35` | Fill opacity for duotone variant |
+| `colorMap` | — | Per-emoji color overrides (import from `colors.js`) |
+
+**Protected regions:** Content inside `<code>`, `<pre>`, `<textarea>`, and elements with `data-sparkui-no-replace` is never modified.
+
+**Skin tones:** Automatically stripped before lookup (👍🏻 → 👍).
+
+### `lookup(emoji)` → `{ name, svg } | undefined`
+### `has(emoji)` → `boolean`
+### `entries()` → `Iterator<[emoji, { name, svg }]>`
+### `size()` → `number`
+
+## Performance
+
+- < 2ms for realistic 50KB pages (~100 emojis)
+- Pre-compiled regex and pre-built replacement strings
+- Zero runtime file I/O
+- Protected region detection via fast pre-check
+
+## Colored Circles
+
+Circle emojis (🔴 🟢 🟡 🔵 ⚪ 🟠) are mapped to the Lucide `circle` icon with color-specific CSS classes:
+
+```css
+.sparkui-icon.sparkui-red    { color: #ef4444; }
+.sparkui-icon.sparkui-green  { color: #22c55e; }
+.sparkui-icon.sparkui-yellow { color: #eab308; }
+.sparkui-icon.sparkui-blue   { color: #3b82f6; }
+.sparkui-icon.sparkui-white  { color: #e5e7eb; }
+.sparkui-icon.sparkui-orange { color: #f97316; }
+```
+
+## Icon Mapping
+
+208 emojis mapped across categories: Navigation, Sections, Actions, Status, Health, Food, Finance, Travel, Education, Entertainment, Weather, Communication, and Misc.
+
+### Build Notes
+- 🪣 → `paint-bucket` (lucide-static doesn't have `bucket`)
+- ✅/❌ map to `circle-check`/`circle-x` (status versions, not `check-circle`/`x-circle`)
+- Some emojis share icon names (🌮/🍴 → `utensils`, 🔧/🛠️ → `wrench`, etc.)
+
+## License
+
+MIT

package/client.js

@@ -0,0 +1,50 @@
+/**
+ * sparkui-icons client-side module
+ * MutationObserver for dynamic content replacement
+ */
+(function () {
+  'use strict';
+
+  if (typeof window === 'undefined' || typeof MutationObserver === 'undefined') return;
+
+  // Will be injected by SparkUI server or loaded separately
+  const sparkuiIcons = window.sparkuiIcons;
+  if (!sparkuiIcons) {
+    console.warn('[sparkui-icons] window.sparkuiIcons not found. Load the library first.');
+    return;
+  }
+
+  const observer = new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType !== 1) continue; // Element nodes only
+        if (node.closest('[data-sparkui-no-replace]')) continue;
+        if (['CODE', 'PRE', 'TEXTAREA'].includes(node.tagName)) continue;
+
+        // Replace emojis in the new node's HTML
+        const original = node.innerHTML;
+        const replaced = sparkuiIcons.replace(original);
+        if (replaced !== original) {
+          node.innerHTML = replaced;
+        }
+      }
+    }
+  });
+
+  // Start observing when DOM is ready
+  function init() {
+    observer.observe(document.body, {
+      childList: true,
+      subtree: true,
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', init);
+  } else {
+    init();
+  }
+
+  // Expose for manual control
+  window.sparkuiIconsObserver = observer;
+})();

package/colors.js

@@ -0,0 +1,302 @@
+// Semantic color map for sparkui-icons duotone mode
+// Each emoji gets a "natural" fill color for its duotone variant
+'use strict';
+
+// Tailwind color palette
+const RED     = '#ef4444';
+const ORANGE  = '#f97316';
+const AMBER   = '#f59e0b';
+const YELLOW  = '#eab308';
+const GREEN   = '#10b981';
+const TEAL    = '#14b8a6';
+const BLUE    = '#3b82f6';
+const INDIGO  = '#6366f1';
+const PURPLE  = '#8b5cf6';
+const PINK    = '#ec4899';
+const SLATE   = '#64748b';
+const WHITE   = '#ffffff';
+
+function c(fill) { return { fill, stroke: WHITE }; }
+
+module.exports = {
+  // ── Navigation & UI ──
+  '⚡': c(AMBER),
+  '🔥': c(ORANGE),
+  '✅': c(GREEN),
+  '❌': c(RED),
+  '⚠️': c(YELLOW),
+  '💡': c(AMBER),
+  '🔔': c(AMBER),
+  '⭐': c(AMBER),
+  '🎯': c(RED),
+  '📌': c(RED),
+  '🔍': c(BLUE),
+  '➡️': c(BLUE),
+  '⬅️': c(BLUE),
+  '⬆️': c(GREEN),
+  '⬇️': c(RED),
+  '🔗': c(BLUE),
+  '📎': c(SLATE),
+  'ℹ️': c(BLUE),
+  '❓': c(BLUE),
+  '❗': c(RED),
+  '🚀': c(ORANGE),
+  '💬': c(BLUE),
+  '📢': c(ORANGE),
+  '🏷️': c(BLUE),
+  '🔖': c(AMBER),
+
+  // ── Sections ──
+  '🏠': c(BLUE),
+  '👤': c(BLUE),
+  '👥': c(BLUE),
+  '⚙️': c(SLATE),
+  '📊': c(BLUE),
+  '📈': c(GREEN),
+  '📉': c(RED),
+  '💰': c(GREEN),
+  '🛒': c(GREEN),
+  '📱': c(BLUE),
+  '💻': c(BLUE),
+  '🔒': c(INDIGO),
+  '🔓': c(INDIGO),
+  '🛡️': c(PURPLE),
+  '📧': c(BLUE),
+  '📞': c(GREEN),
+  '🌐': c(BLUE),
+  '🗂️': c(AMBER),
+  '📁': c(AMBER),
+  '📄': c(BLUE),
+  '🖼️': c(PURPLE),
+  '🎨': c(PURPLE),
+  '🧩': c(PURPLE),
+  '📋': c(BLUE),
+  '🗓️': c(BLUE),
+
+  // ── Actions ──
+  '➕': c(GREEN),
+  '➖': c(RED),
+  '✏️': c(AMBER),
+  '🗑️': c(RED),
+  '📤': c(BLUE),
+  '📥': c(BLUE),
+  '🔄': c(BLUE),
+  '▶️': c(GREEN),
+  '⏸️': c(AMBER),
+  '⏹️': c(RED),
+  '⏭️': c(BLUE),
+  '⏮️': c(BLUE),
+  '🔊': c(BLUE),
+  '🔇': c(SLATE),
+  '📷': c(BLUE),
+  '🖨️': c(SLATE),
+  '💾': c(BLUE),
+  '↩️': c(SLATE),
+  '↪️': c(SLATE),
+  '📝': c(AMBER),
+  '🔀': c(BLUE),
+  '🔁': c(BLUE),
+  '✂️': c(SLATE),
+  '📑': c(BLUE),
+  '🔽': c(SLATE),
+
+  // ── Status ──
+  '⏳': c(AMBER),
+  '⏰': c(RED),
+  '🔴': c(RED),
+  '🟢': c(GREEN),
+  '🟡': c(YELLOW),
+  '🔵': c(BLUE),
+  '⚪': c(SLATE),
+  '🟠': c(ORANGE),
+  '✔️': c(GREEN),
+  '❎': c(RED),
+  '🆕': c(GREEN),
+  '🔜': c(BLUE),
+  '📶': c(GREEN),
+  '🔋': c(GREEN),
+  '💤': c(INDIGO),
+  '🏁': c(SLATE),
+  '📍': c(RED),
+  '📅': c(BLUE),
+  '📆': c(BLUE),
+  '🕐': c(BLUE),
+  '🕑': c(BLUE),
+  '🕒': c(BLUE),
+  '🕓': c(BLUE),
+  '🕔': c(BLUE),
+  '🕕': c(BLUE),
+  '🕖': c(BLUE),
+  '🕗': c(BLUE),
+  '🕘': c(BLUE),
+  '🕙': c(BLUE),
+  '🕚': c(BLUE),
+  '🕛': c(BLUE),
+
+  // ── Health ──
+  '🏋️': c(ORANGE),
+  '💪': c(ORANGE),
+  '🏃': c(ORANGE),
+  '🏃\u200D♂️': c(ORANGE),
+  '❤️': c(RED),
+  '💓': c(RED),
+  '🩺': c(RED),
+  '💊': c(RED),
+  '🏥': c(RED),
+  '🧘': c(GREEN),
+  '🍎': c(RED),
+  '🥗': c(GREEN),
+  '⚖️': c(BLUE),
+  '🩸': c(RED),
+  '🌡️': c(RED),
+  '😴': c(INDIGO),
+
+  // ── Food ──
+  '🍳': c(AMBER),
+  '🍕': c(ORANGE),
+  '☕': c(AMBER),
+  '🍺': c(AMBER),
+  '🍷': c(PURPLE),
+  '🥤': c(TEAL),
+  '🧁': c(PINK),
+  '🍔': c(ORANGE),
+  '🌮': c(ORANGE),
+  '🥩': c(RED),
+  '🍴': c(SLATE),
+  '🛎️': c(AMBER),
+  '📖': c(BLUE),
+  '⏲️': c(BLUE),
+  '🔪': c(SLATE),
+  '🍽️': c(SLATE),
+  '🥑': c(GREEN),
+  '🌾': c(AMBER),
+  '💧': c(TEAL),
+  '🧈': c(AMBER),
+  '🥓': c(RED),
+  '🧀': c(AMBER),
+  '🥚': c(AMBER),
+  '🍗': c(ORANGE),
+  '🥦': c(GREEN),
+  '🫒': c(GREEN),
+  '🧅': c(AMBER),
+  '🍜': c(ORANGE),
+  '🍲': c(ORANGE),
+  '🫐': c(INDIGO),
+  '🍫': c(AMBER),
+  '🍩': c(PINK),
+  '🍪': c(AMBER),
+
+  // ── Finance ──
+  '💳': c(BLUE),
+  '🏦': c(BLUE),
+  '💵': c(GREEN),
+  '🧾': c(SLATE),
+  '💹': c(GREEN),
+  '🏢': c(BLUE),
+  '👔': c(BLUE),
+  '📃': c(BLUE),
+  '🤝': c(BLUE),
+  '📐': c(SLATE),
+  '💎': c(PURPLE),
+  '🪙': c(AMBER),
+  '📦': c(AMBER),
+  '💸': c(GREEN),
+
+  // ── Travel ──
+  '✈️': c(BLUE),
+  '🚗': c(BLUE),
+  '🚕': c(AMBER),
+  '🚌': c(AMBER),
+  '🚂': c(SLATE),
+  '🚢': c(BLUE),
+  '🏨': c(BLUE),
+  '🗺️': c(GREEN),
+  '🧭': c(RED),
+  '⛽': c(ORANGE),
+  '🅿️': c(BLUE),
+  '🛫': c(BLUE),
+  '🛬': c(BLUE),
+  '🚲': c(GREEN),
+  '🏖️': c(AMBER),
+
+  // ── Education ──
+  '📚': c(BLUE),
+  '🎓': c(INDIGO),
+  '✍️': c(BLUE),
+  '🔬': c(INDIGO),
+  '🧪': c(GREEN),
+  '🌍': c(GREEN),
+  '🧮': c(SLATE),
+
+  // ── Entertainment ──
+  '🎮': c(PURPLE),
+  '🎵': c(PINK),
+  '🎬': c(SLATE),
+  '📺': c(BLUE),
+  '🎙️': c(SLATE),
+  '🎧': c(PURPLE),
+  '📻': c(SLATE),
+  '🎭': c(PURPLE),
+  '📸': c(BLUE),
+  '🎤': c(SLATE),
+  '🎪': c(ORANGE),
+  '🎲': c(PURPLE),
+  '🃏': c(INDIGO),
+  '🏆': c(AMBER),
+
+  // ── Weather ──
+  '☀️': c(AMBER),
+  '🌙': c(INDIGO),
+  '⛅': c(BLUE),
+  '🌧️': c(BLUE),
+  '❄️': c(TEAL),
+  '🌊': c(TEAL),
+  '🌪️': c(SLATE),
+  '⛈️': c(SLATE),
+  '🌈': c(PURPLE),
+  '🌲': c(GREEN),
+
+  // ── Communication ──
+  '💌': c(PINK),
+  '📩': c(BLUE),
+  '📨': c(BLUE),
+  '🗣️': c(BLUE),
+  '👁️': c(BLUE),
+  '🤖': c(BLUE),
+  '👋': c(AMBER),
+  '🙏': c(PINK),
+  '👍': c(GREEN),
+  '👎': c(RED),
+  '🔕': c(SLATE),
+  '📣': c(ORANGE),
+  '🗨️': c(BLUE),
+
+  // ── Expressions & Social ──
+  '🎉': c(AMBER),
+  '👏': c(AMBER),
+  '🙌': c(AMBER),
+  '😊': c(AMBER),
+  '😃': c(AMBER),
+  '😄': c(AMBER),
+  '🤔': c(PURPLE),
+
+  // ── Misc ──
+  '🎁': c(PINK),
+  '🧲': c(RED),
+  '🔧': c(SLATE),
+  '🔨': c(SLATE),
+  '⚒️': c(SLATE),
+  '🛠️': c(SLATE),
+  '🗝️': c(AMBER),
+  '🔑': c(AMBER),
+  '🧰': c(ORANGE),
+  '🪣': c(BLUE),
+  '🧹': c(SLATE),
+  '🔌': c(SLATE),
+  '🧬': c(GREEN),
+  '♻️': c(GREEN),
+  '⏱️': { fill: '#3b82f6', stroke: '#ffffff' },
+  '⏱': { fill: '#3b82f6', stroke: '#ffffff' },
+  '⌛': { fill: '#f59e0b', stroke: '#ffffff' },
+  '⌚': { fill: '#3b82f6', stroke: '#ffffff' },
+};

package/index.js

@@ -0,0 +1,202 @@
+'use strict';
+
+const { MAP, CIRCLE_COLORS } = require('./map');
+const { EMOJI_REGEX } = require('./regex');
+
+// Skin tone modifier range: U+1F3FB to U+1F3FF
+const SKIN_TONE_RE = /[\u{1F3FB}-\u{1F3FF}]/gu;
+
+// Check if string might contain protected elements (fast pre-check)
+const HAS_PROTECTED_RE = /<(?:code|pre|textarea|script|style|meta)\b|data-sparkui-no-replace/i;
+
+// Protected region regex
+const PROTECTED_RE = /<(code|pre|textarea|script|style)\b[^>]*>[\s\S]*?<\/\1>|<(\w+)\b[^>]*data-sparkui-no-replace[^>]*>[\s\S]*?<\/\2>/gi;
+
+// Pre-build default SVGs (size=20, class=sparkui-icon) for reuse
+const DEFAULT_SVGS = new Map();
+for (const [emoji, entry] of MAP) {
+  const colorClass = CIRCLE_COLORS.get(emoji);
+  const classes = colorClass ? `sparkui-icon ${colorClass}` : 'sparkui-icon';
+
+  let svg = entry.svg
+    .replace(/width="\d+"/, 'width="20"')
+    .replace(/height="\d+"/, 'height="20"');
+
+  if (/class="/.test(svg)) {
+    svg = svg.replace(/class="([^"]*)"/, (_, ex) => `class="${ex} ${classes}"`);
+  } else {
+    svg = svg.replace('<svg ', `<svg class="${classes}" `);
+  }
+
+  DEFAULT_SVGS.set(emoji, svg);
+}
+
+// Pre-build default replacements (outline, no variant)
+const DEFAULT_REPLACEMENTS = new Map();
+for (const [emoji, svg] of DEFAULT_SVGS) {
+  DEFAULT_REPLACEMENTS.set(emoji, `<span role="img" aria-label="${emoji}" class="sparkui-icon-wrap">${svg}</span>`);
+}
+
+// Build a sorted list of emoji keys for scanning (longest first)
+const EMOJI_KEYS = [...MAP.keys()].sort((a, b) => b.length - a.length);
+const MAX_EMOJI_LEN = EMOJI_KEYS[0].length;
+
+// Build a Set of first characters that could start an emoji
+const EMOJI_FIRST_CHARS = new Set();
+for (const key of EMOJI_KEYS) {
+  const cp = key.codePointAt(0);
+  EMOJI_FIRST_CHARS.add(cp);
+}
+
+// Fast scan-and-replace using regex (pre-compiled) with pre-built replacement map
+function fastReplace(str, replacements) {
+  EMOJI_REGEX.lastIndex = 0;
+  return str.replace(EMOJI_REGEX, (match) => {
+    const direct = replacements.get(match);
+    if (direct) return direct;
+    const stripped = match.replace(SKIN_TONE_RE, '');
+    return replacements.get(stripped) || match;
+  });
+}
+
+/**
+ * Build variant wrapper attributes for a single emoji.
+ */
+function buildVariantSpan(emoji, svg, variant, opts) {
+  const colorMap = opts.colorMap;
+  const override = colorMap && colorMap[emoji];
+
+  let wrapClass = 'sparkui-icon-wrap';
+  const styleParts = [];
+
+  if (variant === 'filled') {
+    wrapClass += ' sparkui-filled';
+    const color = (override && (override.fill || override.color)) || opts.color;
+    if (color) styleParts.push(`--si-color:${color}`);
+  } else if (variant === 'duotone') {
+    wrapClass += ' sparkui-duotone';
+    const fill = (override && override.fill) || opts.fillColor;
+    const stroke = (override && override.stroke) || opts.strokeColor;
+    const opacity = (override && override.fillOpacity != null) ? override.fillOpacity : opts.fillOpacity;
+    if (fill) styleParts.push(`--si-fill:${fill}`);
+    if (stroke) styleParts.push(`--si-stroke:${stroke}`);
+    if (opacity != null) styleParts.push(`--si-fill-opacity:${opacity}`);
+  }
+
+  const wrapStyle = styleParts.length ? ` style="${styleParts.join(';')}"` : '';
+  return `<span role="img" aria-label="${emoji}" class="${wrapClass}"${wrapStyle}>${svg}</span>`;
+}
+
+/**
+ * Replace mapped emojis with inline Lucide SVGs in an HTML string.
+ */
+function replace(html, options) {
+  if (!html || typeof html !== 'string') return html;
+
+  const hasVariant = options && (options.variant || options.colorMap || options.color || options.fillColor || options.strokeColor || options.fillOpacity != null);
+
+  const isDefault = !options || (!hasVariant && (
+    (options.size === undefined || options.size === 20) &&
+    (options.class === undefined || options.class === 'sparkui-icon') &&
+    (options.preserveEmoji === undefined || options.preserveEmoji === true) &&
+    (options.strokeWidth === undefined || options.strokeWidth === 2)
+  ));
+
+  let replacements;
+  if (isDefault) {
+    replacements = DEFAULT_REPLACEMENTS;
+  } else {
+    const opts = { size: 20, class: 'sparkui-icon', preserveEmoji: true, strokeWidth: 2, ...options };
+    const variant = opts.variant || 'outline';
+    const isDefaultSvg = opts.size === 20 && opts.class === 'sparkui-icon' && opts.strokeWidth === 2;
+
+    replacements = new Map();
+    for (const [emoji, entry] of MAP) {
+      // Reuse pre-built SVGs when size/class/strokeWidth are defaults
+      let svg;
+      if (isDefaultSvg) {
+        svg = DEFAULT_SVGS.get(emoji);
+      } else {
+        const colorClass = CIRCLE_COLORS.get(emoji);
+        const classes = colorClass ? `${opts.class} ${colorClass}` : opts.class;
+        svg = entry.svg
+          .replace(/width="\d+"/, `width="${opts.size}"`)
+          .replace(/height="\d+"/, `height="${opts.size}"`)
+          .replace(/stroke-width="\d+"/, `stroke-width="${opts.strokeWidth}"`);
+        if (/class="/.test(svg)) {
+          svg = svg.replace(/class="([^"]*)"/, (_, ex) => `class="${ex} ${classes}"`);
+        } else {
+          svg = svg.replace('<svg ', `<svg class="${classes}" `);
+        }
+      }
+
+      if (opts.preserveEmoji) {
+        if (variant === 'outline' && !opts.colorMap) {
+          // Outline with no colorMap — same as default wrapper
+          replacements.set(emoji, `<span role="img" aria-label="${emoji}" class="sparkui-icon-wrap">${svg}</span>`);
+        } else {
+          replacements.set(emoji, buildVariantSpan(emoji, svg, variant, opts));
+        }
+      } else {
+        replacements.set(emoji, svg);
+      }
+    }
+  }
+
+  // Strategy: only replace emojis in text nodes (between HTML tags),
+  // never inside <tag attributes>, <script>, <style>, <code>, <pre>, <textarea>.
+
+  // Step 1: Protect block-level regions (script, style, code, pre, textarea, no-replace)
+  const regions = [];
+  PROTECTED_RE.lastIndex = 0;
+  let workHtml = html.replace(PROTECTED_RE, (match) => {
+    const idx = regions.length;
+    regions.push(match);
+    return `\x00P${idx}\x00`;
+  });
+
+  // Step 2: Split by HTML tags — only replace in text segments, not inside <...>
+  // This prevents replacing emojis inside attribute values (content="...", title="...", etc.)
+  const TAG_RE = /<[^>]*>/g;
+  let result = '';
+  let lastIdx = 0;
+  let tagMatch;
+  TAG_RE.lastIndex = 0;
+  while ((tagMatch = TAG_RE.exec(workHtml)) !== null) {
+    // Text before this tag — safe to replace
+    if (tagMatch.index > lastIdx) {
+      result += fastReplace(workHtml.slice(lastIdx, tagMatch.index), replacements);
+    }
+    // The tag itself — do NOT replace
+    result += tagMatch[0];
+    lastIdx = TAG_RE.lastIndex;
+  }
+  // Remaining text after last tag
+  if (lastIdx < workHtml.length) {
+    result += fastReplace(workHtml.slice(lastIdx), replacements);
+  }
+
+  // Step 3: Restore protected regions
+  return result.replace(/\x00P(\d+)\x00/g, (_, idx) => regions[parseInt(idx)]);
+}
+
+/**
+ * Look up the icon entry for a single emoji.
+ */
+function lookup(emoji) {
+  const stripped = emoji.replace(SKIN_TONE_RE, '');
+  return MAP.get(stripped);
+}
+
+/**
+ * Check if an emoji has a mapped icon.
+ */
+function has(emoji) {
+  const stripped = emoji.replace(SKIN_TONE_RE, '');
+  return MAP.has(stripped);
+}
+
+function entries() { return MAP.entries(); }
+function size() { return MAP.size; }
+
+module.exports = { replace, lookup, has, entries, size, MAP, CIRCLE_COLORS, EMOJI_REGEX };