@dofy/native-emoji-motion 0.0.0-stage → 0.1.0

package/src/presets.js

@@ -0,0 +1,103 @@
+// Motions transform the entire native glyph. Keyframes deliberately begin and end at rest.
+export const motions = {
+  glide: { keyframes: [{ transform: 'translate(0, 0) rotate(0deg)' }, { transform: 'translate(-12%, 8%) rotate(-9deg)', offset: .25 }, { transform: 'translate(12%, -22%) rotate(9deg)', offset: .6 }, { transform: 'translate(0, 0) rotate(0deg)' }], options: { duration: 1050, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  ride: { keyframes: [{ transform: 'translateY(0) rotate(0deg)' }, { transform: 'translateY(-15%) rotate(-6deg)', offset: .24 }, { transform: 'translateY(0) rotate(4deg)', offset: .48 }, { transform: 'translateY(-9%) rotate(-4deg)', offset: .68 }, { transform: 'translateY(0) rotate(0deg)' }], options: { duration: 950, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 80%' },
+  wave: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(18deg)' }, { transform: 'rotate(-12deg)' }, { transform: 'rotate(16deg)' }, { transform: 'rotate(-7deg)' }, { transform: 'rotate(0deg)' }], options: { duration: 850, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '70% 75%' },
+  bounce: { keyframes: [{ transform: 'translateY(0) scale(1)' }, { transform: 'translateY(-22%) scale(1.07,.94)', offset: .38 }, { transform: 'translateY(0) scale(.93,1.07)', offset: .72 }, { transform: 'translateY(0) scale(1)' }], options: { duration: 650, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 85%' },
+  pulse: { keyframes: [{ transform: 'scale(1)' }, { transform: 'scale(1.25)', offset: .28 }, { transform: 'scale(.96)', offset: .5 }, { transform: 'scale(1.16)', offset: .68 }, { transform: 'scale(1)' }], options: { duration: 750, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  wobble: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(-13deg)' }, { transform: 'rotate(10deg)' }, { transform: 'rotate(-6deg)' }, { transform: 'rotate(3deg)' }, { transform: 'rotate(0deg)' }], options: { duration: 700, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 80%' },
+  spin: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(360deg)' }], options: { duration: 800, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  launch: { keyframes: [{ transform: 'translate(0,0) rotate(0deg)' }, { transform: 'translate(-5%,5%) rotate(-8deg)', offset: .22 }, { transform: 'translate(18%,-22%) rotate(8deg)', offset: .55 }, { transform: 'translate(0,0) rotate(0deg)' }], options: { duration: 900, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  search: { keyframes: [{ transform: 'translate(0,0) rotate(0deg)' }, { transform: 'translate(-12%,-8%) rotate(-12deg)' }, { transform: 'translate(12%,6%) rotate(12deg)' }, { transform: 'translate(0,0) rotate(0deg)' }], options: { duration: 850, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '65% 65%' },
+  swing: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(18deg)' }, { transform: 'rotate(-15deg)' }, { transform: 'rotate(9deg)' }, { transform: 'rotate(-4deg)' }, { transform: 'rotate(0deg)' }], options: { duration: 850, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 10%' },
+  float: { keyframes: [{ transform: 'translateY(0) rotate(0deg)' }, { transform: 'translateY(-18%) rotate(-8deg)', offset: .4 }, { transform: 'translateY(-10%) rotate(6deg)', offset: .7 }, { transform: 'translateY(0) rotate(0deg)' }], options: { duration: 1000, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  shake: { keyframes: [{ transform: 'translateX(0)' }, { transform: 'translateX(-10%) rotate(-8deg)' }, { transform: 'translateX(10%) rotate(8deg)' }, { transform: 'translateX(-6%) rotate(-5deg)' }, { transform: 'translateX(4%) rotate(3deg)' }, { transform: 'translateX(0)' }], options: { duration: 650, easing: 'cubic-bezier(.22,1,.36,1)' } }
+};
+
+// Groups describe semantic families; emoji entries may override the group's motion.
+export const groups = {
+  gestures: { label: 'Gestures', motion: 'wave', description: 'Hands with a friendly wave.' },
+  faces: { label: 'Faces', motion: 'bounce', description: 'Expressions with a little bounce.' },
+  hearts: { label: 'Hearts', motion: 'pulse', description: 'A soft double heartbeat.' },
+  objects: { label: 'Objects', motion: 'wobble', description: 'Everyday things, gently brought to life.' },
+  nature: { label: 'Nature', motion: 'float', description: 'A light, drifting movement.' },
+  travel: { label: 'Travel', motion: 'launch', description: 'Things ready to take off.' },
+  symbols: { label: 'Symbols', motion: 'spin', description: 'A small turn for signs and shapes.' },
+  people: { label: 'People', motion: 'bounce', description: 'People and activities.' },
+  food: { label: 'Food', motion: 'bounce', description: 'Food and drink.' },
+  activities: { label: 'Activities', motion: 'bounce', description: 'Sports, arts and celebrations.' },
+  flags: { label: 'Flags', motion: 'float', description: 'A gentle flag motion.' },
+  other: { label: 'Other', motion: 'bounce', description: 'A gentle fallback.' }
+};
+
+// Explicit mappings avoid guessing at modifier placement in complex sequences.
+const skinTones = glyph => Object.fromEntries(['light', 'medium-light', 'medium', 'medium-dark', 'dark'].map((tone, index) => [tone, glyph + String.fromCodePoint(0x1f3fb + index)]));
+// Variants are explicit: unrelated sequences are never silently normalized.
+export const emoji = {
+  '👋': { group: 'gestures', name: 'Waving hand', skinTones: skinTones('👋') },
+  '👍': { group: 'gestures', name: 'Thumbs up', motion: 'bounce', skinTones: skinTones('👍') },
+  '👏': { group: 'gestures', name: 'Clapping hands', motion: 'shake', skinTones: skinTones('👏') },
+  '👎': { group: 'gestures', name: 'Thumbs down', motion: 'wobble', skinTones: skinTones('👎') },
+  '✋': { group: 'gestures', name: 'Raised hand', skinTones: skinTones('✋') },
+  '🖐️': { group: 'gestures', name: 'Hand with fingers splayed', skinTones: skinTones('🖐') },
+  '🤚': { group: 'gestures', name: 'Raised back of hand', skinTones: skinTones('🤚') },
+  '🤘': { group: 'gestures', name: 'Sign of the horns', motion: 'bounce', skinTones: skinTones('🤘') },
+  '🤙': { group: 'gestures', name: 'Call me hand', motion: 'wobble', skinTones: skinTones('🤙') },
+  '👌': { group: 'gestures', name: 'OK hand', motion: 'pulse', skinTones: skinTones('👌') },
+  '🤞': { group: 'gestures', name: 'Crossed fingers', motion: 'wobble', skinTones: skinTones('🤞') },
+  '🫶': { group: 'gestures', name: 'Heart hands', motion: 'pulse', skinTones: skinTones('🫶') },
+  '🙌': { group: 'gestures', name: 'Raising hands', motion: 'bounce', skinTones: skinTones('🙌') },
+  '🙏': { group: 'gestures', name: 'Folded hands', motion: 'bounce', skinTones: skinTones('🙏') },
+  '💪': { group: 'gestures', name: 'Flexed biceps', motion: 'pulse', skinTones: skinTones('💪') },
+  '👆': { group: 'gestures', name: 'Pointing up', motion: 'bounce', skinTones: skinTones('👆') },
+  '👇': { group: 'gestures', name: 'Pointing down', motion: 'bounce', skinTones: skinTones('👇') },
+  '👉': { group: 'gestures', name: 'Pointing right', motion: 'wobble', skinTones: skinTones('👉') },
+  '😊': { group: 'faces', name: 'Smiling face' }, '😂': { group: 'faces', name: 'Tears of joy', motion: 'shake' }, '🥳': { group: 'faces', name: 'Party face', motion: 'wobble' },
+  '😍': { group: 'faces', name: 'Smiling face with heart eyes', motion: 'pulse' }, '😉': { group: 'faces', name: 'Winking face', motion: 'wobble' }, '😎': { group: 'faces', name: 'Sunglasses face', motion: 'wobble' }, '🤔': { group: 'faces', name: 'Thinking face', motion: 'wobble' }, '😴': { group: 'faces', name: 'Sleeping face', motion: 'float' }, '😭': { group: 'faces', name: 'Loudly crying face', motion: 'shake' },
+  '❤️': { group: 'hearts', name: 'Red heart', variants: ['❤'] }, '💛': { group: 'hearts', name: 'Yellow heart' }, '💖': { group: 'hearts', name: 'Sparkling heart' },
+  '💚': { group: 'hearts', name: 'Green heart' }, '💙': { group: 'hearts', name: 'Blue heart' }, '💜': { group: 'hearts', name: 'Purple heart' }, '💔': { group: 'hearts', name: 'Broken heart', motion: 'shake' },
+  '🔍': { group: 'objects', name: 'Magnifying glass', motion: 'search' }, '🔔': { group: 'objects', name: 'Bell', motion: 'swing', decoration: 'sound' }, '🎁': { group: 'objects', name: 'Gift', motion: 'shake' }, '📡': { group: 'objects', name: 'Satellite antenna', motion: 'wobble', decoration: 'signal' }, '⏱️': { group: 'objects', name: 'Stopwatch', motion: 'swing', variants: ['⏱'] },
+  '💡': { group: 'objects', name: 'Light bulb', motion: 'pulse' }, '📷': { group: 'objects', name: 'Camera', motion: 'bounce' }, '🔑': { group: 'objects', name: 'Key', motion: 'wobble' }, '📌': { group: 'objects', name: 'Pushpin', motion: 'bounce' }, '📦': { group: 'objects', name: 'Package', motion: 'shake' }, '🧭': { group: 'objects', name: 'Compass', motion: 'spin' },
+  '🌸': { group: 'nature', name: 'Blossom' }, '🍃': { group: 'nature', name: 'Leaves' }, '☀️': { group: 'nature', name: 'Sun', motion: 'spin', variants: ['☀'] },
+  '🌻': { group: 'nature', name: 'Sunflower', motion: 'swing' }, '🌈': { group: 'nature', name: 'Rainbow', motion: 'float' }, '🌙': { group: 'nature', name: 'Crescent moon', motion: 'float' }, '⭐': { group: 'nature', name: 'Star', motion: 'pulse', decoration: 'sparkle' }, '🔥': { group: 'nature', name: 'Fire', motion: 'wobble' }, '🌊': { group: 'nature', name: 'Water wave', motion: 'float' },
+  '🚀': { group: 'travel', name: 'Rocket' }, '✈️': { group: 'travel', name: 'Airplane', motion: 'glide', variants: ['✈'] }, '🚲': { group: 'travel', name: 'Bicycle', motion: 'ride' },
+  '🚗': { group: 'travel', name: 'Car', motion: 'ride' }, '🚂': { group: 'travel', name: 'Locomotive', motion: 'ride' }, '🛸': { group: 'travel', name: 'Flying saucer', motion: 'float' }, '🚢': { group: 'travel', name: 'Ship', motion: 'wobble' },
+  '✨': { group: 'symbols', name: 'Sparkles', motion: 'pulse', decoration: 'sparkle' }, '⚙️': { group: 'symbols', name: 'Gear', variants: ['⚙'] }, '🎯': { group: 'symbols', name: 'Target', motion: 'bounce' }, '🎵': { group: 'symbols', name: 'Musical note', motion: 'swing', decoration: 'sound' }, '💤': { group: 'symbols', name: 'Sleeping symbol', motion: 'float' }, '💥': { group: 'symbols', name: 'Collision', motion: 'pulse' }, '❗': { group: 'symbols', name: 'Exclamation mark', motion: 'bounce' }, '❓': { group: 'symbols', name: 'Question mark', motion: 'wobble' }, '✅': { group: 'symbols', name: 'Check mark', motion: 'bounce' }
+};
+
+// Declarative SVG layers never alter the native glyph. Anchors are relative to
+// the consumer's glyph container and may be overridden for a particular font.
+const signalShape = { viewBox: '0 0 100 100', elements: [{ tag: 'circle', attrs: { cx: '50', cy: '50', r: '29', fill: 'none', stroke: '#7c8ee8', 'stroke-width': '2.5' } }] };
+const notesShape = { viewBox: '0 0 100 100', elements: [
+  { tag: 'path', attrs: { d: 'M24 37c-7 3-7 8-3 10s9-1 9-5V23l12-3v15c-7 3-7 8-3 10s9-1 9-5V12l-24 6z', fill: '#b780c8' } },
+  { tag: 'path', attrs: { d: 'M75 67c-5 2-5 6-2 7s7-1 7-4V54l8-2v12c-5 2-5 6-2 7s7-1 7-4V46l-18 5z', fill: '#dc8f72' } }
+] };
+const sparkleShape = { viewBox: '0 0 100 100', elements: [
+  { tag: 'path', attrs: { d: 'M18 9c1.5 9 3 10.5 12 12-9 1.5-10.5 3-12 12-1.5-9-3-10.5-12-12 9-1.5 10.5-3 12-12z', fill: '#e0a63e' } },
+  { tag: 'path', attrs: { d: 'M80 58c1 6 2 7 8 8-6 1-7 2-8 8-1-6-2-7-8-8 6-1 7-2 8-8z', fill: '#d787ad' } }
+] };
+const centered = { width: '160%', height: '160%', overflow: 'visible' };
+export const decorations = {
+  signal: {
+    anchor: { x: '50%', y: '50%' },
+    layers: [0, 180, 360].map(delay => ({
+      svg: signalShape, style: centered,
+      keyframes: [{ opacity: .75, transform: 'translate(-50%, -50%) scale(.55)' }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.2)' }],
+      options: { duration: 700, delay, easing: 'cubic-bezier(.22,1,.36,1)', fill: 'backwards' }
+    }))
+  },
+  sound: {
+    anchor: { x: '50%', y: '50%' },
+    layers: [{ svg: notesShape, style: centered,
+      keyframes: [{ opacity: 0, transform: 'translate(-50%, -45%) scale(.75)' }, { opacity: .9, transform: 'translate(-50%, -55%) scale(1)', offset: .35 }, { opacity: 0, transform: 'translate(-50%, -70%) scale(1.1)' }],
+      options: { duration: 900, easing: 'cubic-bezier(.22,1,.36,1)' }
+    }]
+  },
+  sparkle: {
+    anchor: { x: '50%', y: '50%' },
+    layers: [{ svg: sparkleShape, style: centered,
+      keyframes: [{ opacity: 0, transform: 'translate(-50%, -50%) scale(.6) rotate(-15deg)' }, { opacity: 1, transform: 'translate(-50%, -50%) scale(1)', offset: .42 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.2) rotate(10deg)' }],
+      options: { duration: 850, easing: 'cubic-bezier(.22,1,.36,1)' }
+    }]
+  }
+};

package/src/react-core.js

@@ -0,0 +1,20 @@
+'use client';
+import { createElement, useEffect, useRef } from 'react';
+
+const defaultEvents = ['pointerenter', 'focus', 'click'];
+/** A native emoji with optional motion and decorations. */
+export function createEmojiMotionComponent(emojiMotion) {
+  return function EmojiMotion({ emoji, skinTone, registry = emojiMotion, decoration = true, events = defaultEvents, triggerRef, display = 'inline', label, className, style, ...attributes }) {
+  const wrapper = useRef(null);
+  const glyph = useRef(null);
+  const visual = useRef(null);
+  const result = registry.resolve(emoji, { skinTone });
+  useEffect(() => {
+    if (!wrapper.current || !glyph.current) return;
+    return registry.bind(glyph.current, emoji, { trigger: triggerRef?.current ?? wrapper.current, events, skinTone, ...(decoration ? { decoration: { container: visual.current } } : {}) });
+  }, [registry, emoji, skinTone, decoration, events, triggerRef]);
+  return createElement('span', { ...attributes, className, ref: wrapper, role: 'img', 'aria-label': label ?? result?.name ?? emoji, tabIndex: attributes.tabIndex ?? (triggerRef ? -1 : 0), style: { ...style, display: display === 'block' ? 'block' : 'inline-block' } },
+    createElement('span', { ref: visual, style: { display: 'inline-block', position: 'relative' } },
+      createElement('span', { ref: glyph, 'aria-hidden': 'true', style: { display: 'inline-block' } }, result?.glyph ?? emoji)));
+}
+}

package/src/react-lite.js

@@ -0,0 +1,4 @@
+'use client';
+import { emojiMotion } from './lite.js';
+import { createEmojiMotionComponent } from './react-core.js';
+export const EmojiMotion = createEmojiMotionComponent(emojiMotion);

package/src/react.d.ts

@@ -0,0 +1,14 @@
+import type { CSSProperties, HTMLAttributes, ReactElement, RefObject } from 'react';
+import type { EmojiMotion as Registry, SkinTone } from './index.js';
+export interface EmojiMotionProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'children'> {
+  emoji: string;
+  skinTone?: SkinTone;
+  registry?: Registry;
+  decoration?: boolean;
+  display?: 'inline' | 'block';
+  events?: string[];
+  label?: string;
+  triggerRef?: RefObject<HTMLElement | null>;
+  style?: CSSProperties;
+}
+export declare function EmojiMotion(props: EmojiMotionProps): ReactElement;

package/src/react.js

@@ -0,0 +1,4 @@
+'use client';
+import { emojiMotion } from './index.js';
+import { createEmojiMotionComponent } from './react-core.js';
+export const EmojiMotion = createEmojiMotionComponent(emojiMotion);

package/src/registry.js

@@ -0,0 +1,142 @@
+import { motions as defaultMotions, groups as defaultGroups, emoji as defaultEmoji, decorations as defaultDecorations } from './presets.js';
+
+const toneNames = ['default', 'light', 'medium-light', 'medium', 'medium-dark', 'dark'];
+function validateTone(tone) { if (!toneNames.includes(tone)) throw new Error(`Unknown skin tone "${tone}"`); }
+function defaultClassification(info) {
+  const group = info.unicodeGroup; const sub = info.unicodeSubgroup;
+  if (group === 'Smileys & Emotion') return { group: sub === 'heart' ? 'hearts' : 'faces' };
+  if (group === 'People & Body') return { group: sub.startsWith('hand') ? 'gestures' : 'people', ...(sub.startsWith('hand') && sub !== 'hand-fingers-open' ? { motion: 'wobble' } : {}) };
+  if (group === 'Animals & Nature') return { group: 'nature', ...(sub.startsWith('animal-') ? { motion: 'bounce' } : {}) };
+  if (group === 'Food & Drink') return { group: 'food' };
+  if (group === 'Travel & Places') return { group: 'travel', motion: sub === 'transport-ground' ? 'ride' : sub === 'transport-air' ? 'glide' : sub === 'transport-water' ? 'wobble' : 'float' };
+  if (group === 'Activities') return { group: 'activities' };
+  if (group === 'Objects') return { group: 'objects' };
+  if (group === 'Symbols') return { group: 'symbols', motion: 'pulse' };
+  if (group === 'Flags') return { group: 'flags' };
+  return { group: 'other' };
+}
+
+/** Build a registry with an optional classifier. User definitions always win. */
+export function createRegistry(config = {}, classifier) {
+  const useDefaults = config.defaults !== false;
+  const motions = { ...(useDefaults ? defaultMotions : {}), ...config.motions };
+  const decorations = { ...(useDefaults ? defaultDecorations : {}), ...config.decorations };
+  const groups = { ...(useDefaults ? defaultGroups : {}), ...config.groups };
+  const builtin = useDefaults ? defaultEmoji : {};
+  const user = config.emoji ?? {};
+  const entries = { ...builtin, ...user };
+  if (config.autoDetect === true && !classifier) throw new Error('Automatic classification is not included in the lite entry');
+  const autoDetect = (config.autoDetect ?? useDefaults) && Boolean(classifier);
+  const rules = config.classifications ?? {};
+  let defaultSkinTone = config.defaultSkinTone ?? 'default'; validateTone(defaultSkinTone);
+  function makeAliases(definitions) {
+    const result = new Map();
+    for (const [glyph, entry] of Object.entries(definitions)) {
+      if (!groups[entry.group]) throw new Error(`Unknown group "${entry.group}" for ${glyph}`);
+      const name = entry.motion ?? groups[entry.group].motion;
+      if (!motions[name]) throw new Error(`Unknown motion "${name}" for ${glyph}`);
+      if (entry.decoration && !decorations[entry.decoration]) throw new Error(`Unknown decoration "${entry.decoration}" for ${glyph}`);
+      for (const tone of Object.keys(entry.skinTones ?? {})) { validateTone(tone); if (tone === 'default') throw new Error('Use the canonical glyph for the default skin tone'); }
+      for (const alias of [...(entry.variants ?? []), ...Object.values(entry.skinTones ?? {})]) {
+        if (Object.hasOwn(definitions, alias) || result.has(alias)) throw new Error(`Duplicate emoji variant: ${alias}`);
+        result.set(alias, glyph);
+      }
+    }
+    return result;
+  }
+  const builtinAliases = makeAliases(builtin); const userAliases = makeAliases(user);
+  for (const [id, group] of Object.entries(groups)) if (!motions[group.motion]) throw new Error(`Unknown motion "${group.motion}" for group ${id}`);
+  for (const rule of [...Object.values(rules.groups ?? {}), ...Object.values(rules.subgroups ?? {}), ...(rules.fallback ? [rules.fallback] : [])]) {
+    if (!groups[rule.group]) throw new Error(`Unknown classification group "${rule.group}"`);
+    if (rule.motion && !motions[rule.motion]) throw new Error(`Unknown classification motion "${rule.motion}"`);
+  }
+  const active = new WeakMap();
+  function resolve(glyph, options = {}) {
+    if (typeof glyph !== 'string') return undefined;
+    if (options.skinTone !== undefined) validateTone(options.skinTone);
+    const info = autoDetect ? classifier.lookup(glyph) : undefined;
+    const desiredTone = options.skinTone ?? info?.tone ?? defaultSkinTone;
+    const requestedVariant = info && !info.multiTone && desiredTone !== 'default' ? info.skinTones[desiredTone] : undefined;
+    const candidates = [requestedVariant, glyph, userAliases.get(requestedVariant), userAliases.get(glyph), info?.canonical, builtinAliases.get(glyph)].filter(Boolean);
+    let canonical = candidates.find(key => Object.hasOwn(user, key));
+    let source = canonical ? 'user' : undefined;
+    const userRule = info && (rules.subgroups?.[info.unicodeSubgroup] ?? rules.groups?.[info.unicodeGroup]);
+    // A custom emoji wins first, followed by custom classification rules.
+    if (!canonical && !userRule) { canonical = candidates.find(key => Object.hasOwn(builtin, key)); if (canonical) source = 'preset'; }
+    let entry;
+    let autoRule;
+    if (canonical) entry = source === 'user' ? user[canonical] : builtin[canonical];
+    else if (info) {
+      canonical = info.canonical; source = userRule ? 'user-classification' : 'unicode';
+      autoRule = userRule ?? defaultClassification(info);
+      // A user-defined group overrides the default automatic motion too.
+      if (!userRule && config.groups?.[autoRule.group]) autoRule = { group: autoRule.group };
+      entry = { group: autoRule.group, name: info.name, motion: autoRule.motion };
+    } else if (autoDetect && classifier.looksLikeEmoji(glyph)) {
+      canonical = glyph; source = 'fallback'; autoRule = rules.fallback ?? { group: 'other' };
+      entry = { group: autoRule.group, name: 'Emoji', motion: autoRule.motion };
+    } else return undefined;
+    const group = groups[entry.group];
+    if (!group) throw new Error(`Unknown classification group "${entry.group}"`);
+    // An explicitly supplied group default outranks handcrafted preset motions.
+    // A user-defined emoji or classification remains more specific.
+    const motionId = source === 'preset' && Object.hasOwn(config.groups ?? {}, entry.group) ? group.motion : entry.motion ?? group.motion;
+    if (!motions[motionId]) throw new Error(`Unknown classification motion "${motionId}"`);
+    const mappedTones = entry.skinTones ?? info?.skinTones;
+    const explicitTone = entry.skinTones ? Object.entries(entry.skinTones).find(([, variant]) => variant === glyph)?.[0] : info?.tone;
+    const skinTone = options.skinTone ?? explicitTone ?? defaultSkinTone;
+    let renderedGlyph = glyph;
+    // Mixed-tone sequences are retained: no single requested tone can safely rewrite them.
+    if (mappedTones && !info?.multiTone) {
+      if (skinTone !== 'default') renderedGlyph = mappedTones[skinTone] ?? glyph;
+      else if (explicitTone) renderedGlyph = canonical;
+    }
+    return { ...entry, glyph: renderedGlyph, canonical, skinTone, groupId: entry.group, group, motionId, motion: motions[motionId], decorationPreset: entry.decoration ? decorations[entry.decoration] : undefined, source, ...(info ? { unicodeGroup: info.unicodeGroup, unicodeSubgroup: info.unicodeSubgroup } : {}) };
+  }
+  function play(element, glyph, options = {}) {
+    const result = resolve(glyph, { skinTone: options.skinTone });
+    if (!result || typeof element?.animate !== 'function') return null;
+    if (!options.ignoreReducedMotion && typeof globalThis.matchMedia === 'function' && globalThis.matchMedia('(prefers-reduced-motion: reduce)').matches) return null;
+    active.get(element)?.dispose();
+    const { motion } = result;
+    // transformOrigin belongs in keyframes so it never mutates the host element's styles.
+    const keyframes = motion.keyframes.map(frame => motion.origin ? { ...frame, transformOrigin: motion.origin } : { ...frame });
+    const animation = element.animate(keyframes, { ...motion.options, ...options.animation });
+    let decorationRoot;
+    const decorationAnimations = [];
+    const decorationOptions = options.decoration;
+    const preset = result.decorationPreset;
+    if (decorationOptions && preset) {
+      const { container, anchor = preset.anchor, flipX = false, rotate = 0 } = decorationOptions;
+      decorationRoot = container.ownerDocument.createElement('span');
+      decorationRoot.setAttribute('aria-hidden', 'true');
+      Object.assign(decorationRoot.style, { position: 'absolute', pointerEvents: 'none', left: anchor.x, top: anchor.y, width: '100%', height: '100%', transform: `scaleX(${flipX ? -1 : 1}) rotate(${rotate}deg)` });
+      container.appendChild(decorationRoot);
+      for (const layer of preset.layers) {
+        const node = layer.svg ? container.ownerDocument.createElementNS('http://www.w3.org/2000/svg', 'svg') : container.ownerDocument.createElement('span');
+        if (layer.svg) {
+          node.setAttribute('viewBox', layer.svg.viewBox);
+          for (const shape of layer.svg.elements) {
+            const child = container.ownerDocument.createElementNS('http://www.w3.org/2000/svg', shape.tag);
+            for (const [key, value] of Object.entries(shape.attrs)) child.setAttribute(key, value);
+            node.appendChild(child);
+          }
+        }
+        Object.assign(node.style, { position: 'absolute', left: '0', top: '0', opacity: '0', ...layer.style });
+        decorationRoot.appendChild(node);
+        decorationAnimations.push(node.animate(layer.keyframes, layer.options));
+      }
+      Promise.allSettled(decorationAnimations.map(item => item.finished)).then(() => decorationRoot.remove());
+    }
+    active.set(element, { dispose() { animation.cancel(); decorationAnimations.forEach(item => item.cancel()); decorationRoot?.remove(); } });
+    return animation;
+  }
+  function bind(element, glyph, options = {}) {
+    const trigger = options.trigger ?? element;
+    const events = options.events ?? ['pointerenter', 'focus'];
+    const handler = () => play(element, glyph, options);
+    for (const event of events) trigger.addEventListener(event, handler);
+    return () => { for (const event of events) trigger.removeEventListener(event, handler); active.get(element)?.dispose(); active.delete(element); };
+  }
+  return { resolve, play, bind, setDefaultSkinTone(tone) { validateTone(tone); defaultSkinTone = tone; }, getDefaultSkinTone: () => defaultSkinTone, list: () => Object.keys(entries), groups: () => Object.entries(groups).map(([id, group]) => ({ id, ...group })) };
+}

package/src/svelte-core.js

@@ -0,0 +1,15 @@
+
+/** Svelte action. Apply it to a span dedicated to the emoji. */
+export function createAnimateEmoji(emojiMotion) {
+ return function animateEmoji(node, initial) {
+  let dispose = () => {};
+  function update(options) {
+    dispose();
+    const { emoji, skinTone, registry = emojiMotion, trigger = node, decoration = false, events = ['pointerenter', 'focus', 'click'] } = options;
+    node.textContent = registry.resolve(emoji, { skinTone })?.glyph ?? emoji;
+    dispose = registry.bind(node, emoji, { trigger, events, skinTone, ...(decoration && node.parentElement ? { decoration: { container: node.parentElement } } : {}) });
+  }
+  update(initial);
+  return { update, destroy() { dispose(); } };
+}
+}

package/src/svelte-lite.js

@@ -0,0 +1,3 @@
+import { emojiMotion } from './lite.js';
+import { createAnimateEmoji } from './svelte-core.js';
+export const animateEmoji = createAnimateEmoji(emojiMotion);

package/src/svelte.d.ts

@@ -0,0 +1,3 @@
+import type { EmojiMotion as Registry, SkinTone } from './index.js';
+export interface AnimateEmojiOptions { emoji: string; skinTone?: SkinTone; registry?: Registry; trigger?: EventTarget; decoration?: boolean; events?: string[] }
+export declare function animateEmoji(node: HTMLElement, options: AnimateEmojiOptions): { update(options: AnimateEmojiOptions): void; destroy(): void };

package/src/svelte.js

@@ -0,0 +1,3 @@
+import { emojiMotion } from './index.js';
+import { createAnimateEmoji } from './svelte-core.js';
+export const animateEmoji = createAnimateEmoji(emojiMotion);