@dofy/native-emoji-motion 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 0.4.0 — 2026-11-13
+
+- **Breaking:** Remove the component `display` prop and web component attribute. Components use normal inline layout; use a block container or CSS for placement.
+- Add `enhance()` to animate emoji in existing text and observe dynamic content.
+- Expand reviewed motion families and improve the demo.
+
+## 0.3.0 — 2026-11-13
+
+- Add lighting and sparkle effects for light sources, reflective objects, and celebrations.
+- Expand the handcrafted collection to 177 emoji, including 44 with optional SVG effects.
+- Refine motions for amusement rides, dice, compass, sunflower, candle, and hourglass.
+- Add reusable 3D carousel and object flip motions.
+
 ## 0.2.0 — 2026-11-13
 
 - Expand the handcrafted collection to 161 emoji and add five reviewed motion families.

package/README.md

@@ -1,256 +1,56 @@
-# Emoji Motion
+<p align="center">
+  <img src="./assets/logo.svg" width="104" height="104" alt="Emoji Motion logo" />
+</p>
 
-Small, expressive animations for native emoji. A framework independent library with Unicode based automatic classification, reusable motion presets and explicit per emoji overrides.
+<h1 align="center">Emoji Motion</h1>
 
-## Collection at a glance
+<p align="center">
+  <strong>Give your emoji a little more feeling. ✨</strong><br />
+  Small, expressive animations for the native emoji you already use.
+</p>
 
-The current repository and demo contain **161 handcrafted emoji presets** and **5 reviewed motion families** with **24 additional base emoji**, across **10 categories**. They use **27 reusable motions**; **24 base emoji** have optional SVG effects. Skin tones and other variants are additional sequences, and similar emoji may share the same motion.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@dofy/native-emoji-motion"><img src="https://img.shields.io/npm/v/%40dofy%2Fnative-emoji-motion?label=npm" alt="npm version" /></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="MIT license" /></a>
+  <a href="https://www.npmjs.com/package/@dofy/native-emoji-motion"><img src="https://img.shields.io/node/v/%40dofy%2Fnative-emoji-motion" alt="Node.js version" /></a>
+</p>
 
-The default entry also recognizes **5,235 Unicode Emoji 18.0 sequences**, including qualified forms and variants, and applies a category based fallback when there is no handcrafted preset or reviewed family match. These collection counts describe version 0.2.0.
+Bring 👋, ❤️, 📡 and more to life in React, Vue, Svelte or plain HTML. Emoji Motion animates your system's native emoji, with reusable motions, optional decorative effects and room for your own ideas. Explore the collection and try any emoji in the [live demo](https://emoji-motion.phpz.org/).
 
-## Try the demo
+- 🎨 **Native and adaptable:** keep the platform's emoji style, with skin tone support and optional SVG effects.
+- 🧩 **Easy to use:** drop a component into a sentence or use it as a block.
+- 🛠️ **Made to extend:** customize individual emoji, motion families and classification rules.
+- 🌍 **Ready for more:** Unicode-based automatic classification provides a fallback for recognized emoji.
 
-[Explore the live demo](https://emoji-motion.phpz.org/) or run it locally:
+## 📊 Collection at a glance
 
-```sh
-npm run dev
-```
+| In version 0.4.0 | Count | What it covers |
+| --- | ---: | --- |
+| Handcrafted presets | 177 | Individually configured base emoji |
+| Reviewed motion families | 11 | 78 additional base emoji sharing reviewed motions |
+| Categories | 10 | Groups used to organize the collection |
+| Reusable motions | 37 | Motions shared by presets and families |
+| Emoji with optional SVG effects | 57 | Base emoji with decorative effects |
+| Recognized Unicode sequences | 5,235 | Unicode Emoji 18.0 sequences, including skin tones and other variants |
 
-Open http://127.0.0.1:4173. Hover, focus or tap a card; use the filters to explore the groups. The demo imports the same public entry point as an application. Use **Try any emoji** to preview automatic classification. The gallery starts with a curated selection from across the groups. Choose **All presets** for the handcrafted list, **Motion families** for reviewed family members, **With effects** for decorative SVG layers, or select a semantic group. Choose a framework and display mode, then select an emoji to copy its component. The examples show how to place an emoji in a sentence or on its own line.
+Skin tones and other variants count as additional Unicode sequences. Similar emoji may share a motion. Recognized emoji without a preset or reviewed family receive a category-based fallback.
 
-## Installation
+## 📦 Get started
 
 ```sh
 npm install @dofy/native-emoji-motion
 ```
 
-The package is ESM and uses the browser Web Animations API. React, Vue and Svelte are optional peers: install the framework used by your application.
-
-## Components
-
-Use an emoji directly as a component. `display` is `inline` by default and can be set to `block`; all components animate on hover, focus and click and use built in SVG effects when available. Use these imports in a bundled app. React, Vue and Svelte are optional peers, so the core stays framework independent.
-
 ```jsx
 import { EmojiMotion } from '@dofy/native-emoji-motion/react';
 
 <p>Hello <EmojiMotion emoji="👋" skinTone="medium" /></p>
-<EmojiMotion emoji="📡" display="block" />
-```
-
-```vue
-<script setup>
-import { EmojiMotion } from '@dofy/native-emoji-motion/vue';
-</script>
-<template>
-  <p>Hello <EmojiMotion emoji="👋" skin-tone="medium" /></p>
-  <EmojiMotion emoji="📡" display="block" />
-</template>
-```
-
-```svelte
-<script>
-  import EmojiMotion from '@dofy/native-emoji-motion/svelte/EmojiMotion.svelte';
-</script>
-<p>Hello <EmojiMotion emoji="👋" skinTone="medium" /></p>
-<EmojiMotion emoji="📡" display="block" />
-```
-
-For plain HTML or other frameworks, import `@dofy/native-emoji-motion/element` once in a bundled entry module, then use `<emoji-motion emoji="👋" display="block"></emoji-motion>`. The web component can be used with Angular or any other framework that supports custom elements. It registers itself when the module is imported. Its attributes include `emoji`, `skin-tone`, `display`, `label` and `decoration="false"`; assign the `registry` property to use a custom registry.
-
-React, Vue and Svelte components accept `emoji`, `skinTone`, `display`, `decoration`, `label`, `events`, and a custom `registry`. For a custom interaction target, React accepts `triggerRef` and Vue/Svelte accept `trigger`. Components clean up their listeners when updated or unmounted. A global skin tone set on a registry is read when a component renders; to update an already mounted component, update its `skinTone` prop or cause a framework rerender.
-
-Components do not set a mouse cursor: the emoji follows its surrounding context. Set `cursor: pointer` on a button or other control when the emoji is part of an action.
-
-## Low level API
-
-Import the package in an ESM application:
-
-```js
-import { emojiMotion } from '@dofy/native-emoji-motion';
-
-// Keep the emoji in its own inline-block element. The card can be the trigger.
-const dispose = emojiMotion.bind(emojiElement, '👋', { trigger: card });
-// When the component is removed:
-dispose();
-```
-
-Or play once manually: `emojiMotion.play(emojiElement, '❤️')`. `resolve(glyph)` returns the entry, group and selected motion, or `undefined` when the input cannot be recognized. `list()` returns canonical entries; `groups()` lists groups. `bind` listens to `pointerenter` and `focus` by default. Pass `events: ['click']` or any DOM event names to change this. Make the trigger keyboard accessible; a `<button>` is a good default. The element being animated should have `display: inline-block`, and should be dedicated to the emoji because Web Animations controls its transform.
-
-Motion is skipped when the user prefers reduced motion. `play` returns `null` for unknown emoji, reduced motion, or an element without Web Animations support; otherwise it returns the browser's `Animation`. A repeated play cancels the previous one on the same element. `ignoreReducedMotion` is an explicit opt out and should only be used with the user's consent.
-
-## Automatic classification
-
-The default entry recognizes emoji using data generated from Unicode Emoji 18.0, including fully qualified, minimally qualified, and unqualified sequences. A known emoji is classified by its Unicode group and subgroup and receives a conservative reusable motion; existing handcrafted presets retain their special animations and optional decorations. Exact Unicode sequences, including flags and ZWJ sequences, are used rather than guessing category from a code point range. `resolve()` exposes `source`, `unicodeGroup` and `unicodeSubgroup` where available:
-
-```js
-import { emojiMotion } from '@dofy/native-emoji-motion';
-
-emojiMotion.resolve('🐶'); // source: 'unicode', subgroup: 'animal-mammal', motion: 'bounce'
-emojiMotion.resolve('👩🏽‍🚀').glyph; // 👩🏽‍🚀
-emojiMotion.resolve('📡').source; // 'preset', including its signal decoration
-emojiMotion.resolve('hello'); // undefined
-```
-
-The precedence is: **user emoji and aliases → user subgroup or group classification rule → user group default → handcrafted preset → generated Unicode classification → conservative fallback**. User emoji entries always take precedence over user classification rules. Within user classifications, subgroup rules take precedence over group rules. An explicitly supplied group default overrides handcrafted and automatic motions for that group; a more specific user emoji or classification rule can override it. User-defined motions replace built in motions with the same ID. User classification rules also override matching handcrafted presets.
-
-```js
-import { createEmojiMotion } from '@dofy/native-emoji-motion';
-
-const custom = createEmojiMotion({
-  classifications: {
-    groups: { 'Animals & Nature': { group: 'nature', motion: 'float' } },
-    subgroups: { 'animal-bird': { group: 'nature', motion: 'swing' } },
-    fallback: { group: 'other', motion: 'bounce' },
-  },
-  emoji: { '🐶': { group: 'hearts', name: 'My dog', motion: 'pulse' } },
-});
-// 🐶 uses pulse, 🐦 uses swing, and other animals use float.
-```
-
-A generated Unicode name and subgroup are used for uncustomized emoji. `list()` remains the small set of handcrafted and explicitly added entries; it is not a list of the entire Unicode dataset. Generated classifications do not automatically create SVG decorations. Unknown sequences newer than the pinned dataset receive a generic fallback only if the JavaScript engine recognizes them as emoji; otherwise they remain unrecognized. Detection does not guarantee that the system font can render the glyph. Standalone components and arbitrary text are not treated as emoji.
-
-The `defaults: false` setting disables both built in presets and automatic classification unless `autoDetect: true` is explicitly supplied; with no built in groups or motions, the caller must define the groups and motions used by its rules. Set `autoDetect: false` to disable automatic classification while keeping built in presets.
-
-## Smaller preset only entry
-
-Use the lite entry to omit the Unicode classifier and its data. Unknown emoji do not automatically animate; user-defined entries and handcrafted presets still work. The matching framework entries also omit Unicode data:
-
-```js
-import { createEmojiMotion } from '@dofy/native-emoji-motion/lite';
-import { EmojiMotion as ReactEmoji } from '@dofy/native-emoji-motion/react/lite';
-import { EmojiMotion as VueEmoji } from '@dofy/native-emoji-motion/vue/lite';
-import '@dofy/native-emoji-motion/element/lite';
-// Svelte: import EmojiMotion from '@dofy/native-emoji-motion/svelte/EmojiMotionLite.svelte';
-```
-
-Import either the full or lite web component entry on a page, not both: both register the same `emoji-motion` tag and the first registration wins. To keep a framework bundle small, use its lite entry rather than passing a lite registry to a full component entry, which still imports the full classifier.
-
-Unicode data is generated with `npm run generate:unicode` from a version-pinned, checksum-verified official file. The data is covered by [UNICODE-LICENSE.txt](./UNICODE-LICENSE.txt).
-
-## Skin tone
-
-A registry can specify a default and change it later. `resolve` returns the glyph to render; animation never changes your element's text automatically.
-
-```js
-import { createEmojiMotion } from '@dofy/native-emoji-motion';
-
-const motion = createEmojiMotion({ defaultSkinTone: 'medium' });
-motion.resolve('👋').glyph; // 👋🏽
-motion.resolve('👋', { skinTone: 'dark' }).glyph; // 👋🏿
-motion.setDefaultSkinTone('light');
-motion.resolve('👋').glyph; // 👋🏻
-```
-
-The available values are `default`, `light`, `medium-light`, `medium`, `medium-dark` and `dark`. Explicitly supplied skin tone variants retain their tone unless a per-call override is supplied. Automatic skin tones are applied only where an official single-tone variant is unambiguous; mixed-tone sequences stay unchanged rather than being rewritten. Emoji without a skin tone mapping stay unchanged. When adding custom emoji, supply `skinTones` as an explicit map from the tone names to complete Unicode sequences, including any joiners; the library does not guess modifier placement. If the default tone changes, update rendered text by resolving again.
-
-## Extend
-
-An isolated registry combines built ins and your definitions; existing IDs can be replaced. Set `defaults: false` to use only your own definitions. Emoji variants are explicit rather than guessed, so skin tone and multi code point sequences remain under your control.
-
-```js
-import { createEmojiMotion } from '@dofy/native-emoji-motion';
-
-const motion = createEmojiMotion({
-  motions: {
-    wiggle: {
-      keyframes: [
-        { transform: 'rotate(0deg)' },
-        { transform: 'rotate(12deg)' },
-        { transform: 'rotate(0deg)' },
-      ],
-      options: { duration: 600, easing: 'ease-out' },
-      origin: '50% 80%',
-    },
-  },
-  groups: { creatures: { label: 'Creatures', motion: 'wiggle' } },
-  emoji: { '🐙': { name: 'Octopus', group: 'creatures' } },
-});
-motion.bind(emojiElement, '🐙', { trigger: card });
-```
-
-Groups select a default motion; an emoji entry can override it with `motion`, and `variants` lists exact alternate sequences that inherit its settings. References and duplicate variants are validated when a registry is created. Definitions are ordinary JavaScript objects; do not mutate exported built in data. Create a new registry to change configuration. API types are included.
-
-### Motion families
-
-Families apply a shared motion to explicitly reviewed members. Built in families cover balls, plants, drinks, flying animals and people in poses. They do not assume every emoji in a Unicode subgroup moves alike. `resolve()` reports `source: 'family'` and `familyId` for family matches; `list()` remains the handcrafted emoji list, while `families()` returns family definitions.
-
-Use the configurable spring and sway builders to create reusable motions. A family can adjust Web Animations timing with `animation`, and combine named SVG effects with `decorations`:
-
-```js
-import { createEmojiMotion, createSpringMotion } from '@dofy/native-emoji-motion';
-
-const motion = createEmojiMotion({
-  motions: { smallBounce: createSpringMotion({ height: 14, rebounds: 2, duration: 900 }) },
-  families: {
-    snacks: {
-      label: 'Snacks', group: 'food', motion: 'smallBounce',
-      members: ['🍪', '🍩'],
-      animation: { duration: 800 },
-      decorations: ['impact', 'sparkle'],
-    },
-  },
-});
-```
-
-Pass `motion` as the component's `registry` property to use this configuration. `createSwayMotion({ angle, duration, origin })` provides a direction neutral sway. Effects remain optional and require a decoration container when using the low level API. Each effect keeps its own anchor unless the caller explicitly overrides it.
-
-Custom emoji definitions take priority, followed by custom Unicode classifications and custom families. Built in single emoji presets precede built in families; remaining emoji use automatic classification. A custom group default overrides built in presets and families, while an explicitly defined custom family keeps its chosen motion. A custom family with the same ID replaces the built in family. Unicode variants and unambiguous skin tones are resolved by the full entry; for the lite entry, supply explicit `aliases: { '🧎🏽': '🧎' }` mappings when a family needs variants. Mixed tone sequences are never guessed or rewritten.
-
-## Optional decorative effects
-
-Emoji can also reference a decoration preset. The built in 📡 example adds a neutral signal halo around the whole glyph; 🔔 and 🎵 add notes, and ✨ adds sparkles. Decorations are opt in and render inside a container you provide. Make the container `position: relative` and size it to the glyph. Effects do not change the emoji itself.
-
-```html
-<button id="antenna"><span class="emoji-box"><span id="dish">📡</span></span></button>
-<style>.emoji-box { position: relative; display: inline-block } #dish { display: inline-block }</style>
-```
-
-```js
-emojiMotion.bind(document.querySelector('#dish'), '📡', {
-  trigger: document.querySelector('#antenna'),
-  decoration: {
-    container: document.querySelector('.emoji-box'),
-    // Optional: adjust for the font actually used by your application.
-    anchor: { x: '50%', y: '50%' },
-    flipX: false,
-    rotate: 0,
-  },
-});
-```
-
-`anchor` is relative to the container. `flipX` and `rotate` affect the decoration, never the glyph. For asymmetric effects, select explicit settings for the actual font or environment you support; OS detection alone cannot reliably determine the font or its direction. The default signal effect is centered rather than tied to a specific antenna position. When no decoration container is supplied, only the emoji moves. Decoration layers are removed after playback, on replay and on cleanup; reduced motion skips both.
-
-Add custom `decorations` in `createEmojiMotion`: each named preset has an `anchor` and `layers`, each with CSS `style`, Web Animations `keyframes` and `options`. Optionally provide `svg: { viewBox, elements }`, where each element has a `tag` and `attrs`; without `svg`, a styled span is used. Reference its name using the emoji entry's `decoration` field. Layer styles are trusted application code, and the library does not bundle images or fonts.
-
-For example, this adds an SVG sparkle to a custom group:
-
-```js
-const custom = createEmojiMotion({
-  decorations: {
-    star: {
-      anchor: { x: '50%', y: '50%' },
-      layers: [{
-        svg: { viewBox: '0 0 100 100', elements: [
-          { tag: 'circle', attrs: { cx: '50', cy: '20', r: '5', fill: 'gold' } },
-        ] },
-        style: { width: '160%', height: '160%' },
-        keyframes: [
-          { opacity: 1, transform: 'translate(-50%, -50%) scale(.6)' },
-          { opacity: 0, transform: 'translate(-50%, -50%) scale(1.2)' },
-        ],
-        options: { duration: 700 },
-      }],
-    },
-  },
-  emoji: { '🌟': { name: 'Glowing star', group: 'symbols', decoration: 'star' } },
-});
-custom.bind(emojiElement, '🌟', { trigger: card, decoration: { container: emojiBox } });
 ```
 
-## Platform boundaries
+Use components with React, Vue, Svelte or the Web Component, or add motion to existing text with the `enhance()` API. See the [documentation](https://emoji-motion.phpz.org/docs/) for setup, framework examples, skin tones, customization and API details.
 
-The library animates the entire native glyph, not individual parts. Rendering, supported emoji, sizes and font fallback vary by operating system, browser and installed fonts. Unsupported sequences may appear as missing glyphs or multiple characters. This library deliberately ships no emoji images or fonts and does not replace unsupported glyphs. Test the target browser, OS and font combinations for your product. Keyframes use relative transforms, but the visual pivot can still vary between fonts.
+> Upgrading from 0.3.0? The `display` prop was removed in 0.4.0. Use a block container or CSS to control layout.
 
-## Development and release
+## 📄 License
 
-`npm test` runs the registry and lifecycle tests; `npm run build:demo` creates the isolated static site in `dist/`; `npm run pack:check` previews package contents. The core uses ESM and the browser Web Animations API; it does not require a framework. See [RELEASE.md](https://github.com/dofy/emoji-motion/blob/main/RELEASE.md) for the release checklist.
+[MIT](./LICENSE). Unicode data is covered by the [Unicode License](./UNICODE-LICENSE.txt).

package/assets/logo.svg

@@ -0,0 +1,8 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 96 96" role="img" aria-label="Emoji Motion logo">
+  <circle cx="48" cy="48" r="46" fill="#302d29"/>
+  <circle cx="43" cy="49" r="23" fill="#efe6f6"/>
+  <circle cx="35" cy="44" r="2.6" fill="#302d29"/>
+  <circle cx="51" cy="44" r="2.6" fill="#302d29"/>
+  <path d="M34 55c3.2 4.2 6.3 6 9 6s5.8-1.8 9-6" fill="none" stroke="#302d29" stroke-width="3.5" stroke-linecap="round"/>
+  <path d="M71 31c3 2.4 5 5.4 6 9M73 48c0 3.2-.5 5.7-1.5 8" fill="none" stroke="#ef956d" stroke-width="4" stroke-linecap="round"/>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dofy/native-emoji-motion",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Expressive, extensible animations for native emoji with optional SVG effects",
   "type": "module",
   "exports": {
@@ -60,6 +60,7 @@
   "types": "./src/index.d.ts",
   "files": [
     "src",
+    "assets/logo.svg",
     "README.md",
     "LICENSE",
     "UNICODE-LICENSE.txt",

package/src/EmojiMotion.svelte

@@ -5,7 +5,6 @@
   export let skinTone = undefined;
   export let registry = emojiMotion;
   export let decoration = true;
-  export let display = 'inline';
   export let trigger = undefined;
   export let label = undefined;
   export let events = ['pointerenter', 'focus', 'click'];
@@ -13,8 +12,8 @@
   $: resolved = registry.resolve(emoji, { skinTone });
 </script>
 
-<span bind:this={wrapper} role="img" aria-label={label ?? resolved?.name ?? emoji}
-  tabindex={trigger ? -1 : 0} style:display={display === 'block' ? 'block' : 'inline-block'}>
+<span bind:this={wrapper} data-emoji-motion="component" role="img" aria-label={label ?? resolved?.name ?? emoji}
+  tabindex={trigger ? -1 : 0}>
   <span style="display: inline-block; position: relative">
     <span aria-hidden="true" style="display: inline-block"
       use:animateEmoji={{ emoji, skinTone, registry, trigger: trigger ?? wrapper, decoration, events }}>{resolved?.glyph ?? emoji}</span>

package/src/EmojiMotion.svelte.d.ts

@@ -5,7 +5,6 @@ export interface EmojiMotionProps {
   skinTone?: SkinTone;
   registry?: Registry;
   decoration?: boolean;
-  display?: 'inline' | 'block';
   trigger?: EventTarget;
   label?: string;
   events?: string[];

package/src/EmojiMotionLite.svelte

@@ -5,7 +5,6 @@
   export let skinTone = undefined;
   export let registry = emojiMotion;
   export let decoration = true;
-  export let display = 'inline';
   export let trigger = undefined;
   export let label = undefined;
   export let events = ['pointerenter', 'focus', 'click'];
@@ -13,8 +12,8 @@
   $: resolved = registry.resolve(emoji, { skinTone });
 </script>
 
-<span bind:this={wrapper} role="img" aria-label={label ?? resolved?.name ?? emoji}
-  tabindex={trigger ? -1 : 0} style:display={display === 'block' ? 'block' : 'inline-block'}>
+<span bind:this={wrapper} data-emoji-motion="component" role="img" aria-label={label ?? resolved?.name ?? emoji}
+  tabindex={trigger ? -1 : 0}>
   <span style="display: inline-block; position: relative">
     <span aria-hidden="true" style="display: inline-block"
       use:animateEmoji={{ emoji, skinTone, registry, trigger: trigger ?? wrapper, decoration, events }}>{resolved?.glyph ?? emoji}</span>

package/src/element-core.js

@@ -2,7 +2,7 @@ const BaseElement = globalThis.HTMLElement ?? class {};
 /** Framework-independent web component. Import this module to register <emoji-motion>. */
 export function createEmojiMotionElement(emojiMotion) {
  return class EmojiMotionElement extends BaseElement {
-  static observedAttributes = ['emoji', 'skin-tone', 'display', 'decoration', 'label'];
+  static observedAttributes = ['emoji', 'skin-tone', 'decoration', 'label'];
   #registry = emojiMotion;
   #dispose = () => {};
   get registry() { return this.#registry; }
@@ -15,7 +15,6 @@ export function createEmojiMotionElement(emojiMotion) {
     const emoji = this.getAttribute('emoji') ?? '';
     const skinTone = this.getAttribute('skin-tone') ?? undefined;
     const result = this.#registry.resolve(emoji, { skinTone });
-    this.style.display = this.getAttribute('display') === 'block' ? 'block' : 'inline-block';
     this.setAttribute('role', 'img');
     this.setAttribute('aria-label', this.getAttribute('label') ?? result?.name ?? emoji);
     if (!this.hasAttribute('tabindex')) this.tabIndex = 0;

package/src/enhance.js

@@ -0,0 +1,95 @@
+const excluded = 'script, style, noscript, template, textarea, input, select, option, pre, code, kbd, samp, svg, math, [contenteditable]:not([contenteditable="false"]), [data-emoji-motion], [data-emoji-motion-ignore], emoji-motion';
+const fallbackPattern = /(?:[\u{1F1E6}-\u{1F1FF}]{2}|[#*0-9]\uFE0F?\u20E3|\p{Extended_Pictographic}[\uFE0E\uFE0F]?(?:\p{Emoji_Modifier})?(?:[\u{E0020}-\u{E007E}]+\u{E007F})?(?:\u200D\p{Extended_Pictographic}[\uFE0E\uFE0F]?(?:\p{Emoji_Modifier})?)*)/gu;
+
+// Do not split a ZWJ sequence, flag, keycap, or skin tone into separate glyphs.
+function segments(text, segmenter) {
+  if (segmenter) {
+    return Array.from(segmenter.segment(text), part => ({ glyph: part.segment, index: part.index }));
+  }
+  return Array.from(text.matchAll(fallbackPattern), match => ({ glyph: match[0], index: match.index }));
+}
+
+export function enhance(registry, options = {}) {
+  const doc = globalThis.document;
+  if (!doc) throw new Error('enhance() requires a browser document');
+  const root = typeof options.root === 'string' ? doc.querySelector(options.root) : (options.root ?? doc.body);
+  if (!root || ![1, 9, 11].includes(root.nodeType)) throw new Error('enhance() root must match an element or be a DOM container');
+  const exclusion = options.exclude ? `${excluded}, ${options.exclude}` : excluded;
+  // Validate selectors before doing any DOM work.
+  doc.createElement('span').matches(exclusion);
+  const segmenter = typeof Intl.Segmenter === 'function' ? new Intl.Segmenter(undefined, { granularity: 'grapheme' }) : null;
+  const owned = new Map();
+  let closed = false;
+  let enabled = false;
+  const isExcluded = node => {
+    const parent = node.nodeType === 1 ? node : node.parentElement;
+    return Boolean(parent?.closest(exclusion));
+  };
+  function transform(node) {
+    if (!node.parentNode || isExcluded(node)) return;
+    const text = node.data;
+    const hits = segments(text, segmenter).filter(({ glyph }) => registry.resolve(glyph));
+    if (!hits.length) return;
+    const fragment = node.ownerDocument.createDocumentFragment();
+    let cursor = 0;
+    for (const { glyph, index } of hits) {
+      if (index > cursor) fragment.append(node.ownerDocument.createTextNode(text.slice(cursor, index)));
+      const wrapper = node.ownerDocument.createElement('span');
+      wrapper.setAttribute('data-emoji-motion', 'enhanced');
+      Object.assign(wrapper.style, { display: 'inline-block', position: 'relative' });
+      const inner = node.ownerDocument.createElement('span');
+      inner.style.display = 'inline-block';
+      inner.textContent = glyph;
+      wrapper.append(inner);
+      const dispose = registry.bind(inner, glyph, { events: options.events ?? ['pointerenter', 'focus', 'click'], ...(options.decoration ? { decoration: { container: wrapper } } : {}) });
+      owned.set(wrapper, dispose);
+      fragment.append(wrapper);
+      cursor = index + glyph.length;
+    }
+    if (cursor < text.length) fragment.append(node.ownerDocument.createTextNode(text.slice(cursor)));
+    node.replaceWith(fragment);
+  }
+  function scan(container) {
+    if (isExcluded(container)) return;
+    if (container.nodeType === 3) { transform(container); return; }
+    const walker = container.ownerDocument.createTreeWalker(container, 4);
+    const nodes = [];
+    while (walker.nextNode()) if (!isExcluded(walker.currentNode)) nodes.push(walker.currentNode);
+    for (const node of nodes) transform(node);
+  }
+  const Observer = root.ownerDocument?.defaultView?.MutationObserver ?? doc.defaultView?.MutationObserver;
+  const observer = options.observe === false || !Observer ? null : new Observer(records => {
+    if (!enabled || closed) return;
+    const candidates = new Set();
+    for (const record of records) {
+      if (record.type === 'characterData') candidates.add(record.target);
+      else for (const node of record.addedNodes) if ([1, 3, 11].includes(node.nodeType)) candidates.add(node);
+    }
+    for (const node of candidates) if (root.contains(node)) scan(node);
+    // Discard bindings for removed content without touching nodes the application moved.
+    for (const [wrapper, dispose] of owned) if (!root.contains(wrapper)) { dispose(); wrapper.removeAttribute('data-emoji-motion'); owned.delete(wrapper); }
+  });
+  function disable() {
+    if (closed || !enabled) return;
+    enabled = false;
+    observer?.disconnect();
+    for (const [wrapper, dispose] of owned) {
+      dispose();
+      if (wrapper.parentNode && root.contains(wrapper)) wrapper.replaceWith(wrapper.ownerDocument.createTextNode(wrapper.textContent));
+    }
+    owned.clear();
+  }
+  function enable() {
+    if (closed) throw new Error('Cannot enable a cleaned up enhancer');
+    if (enabled) return;
+    enabled = true;
+    scan(root.nodeType === 9 ? root.documentElement : root);
+    observer?.observe(root, { childList: true, subtree: true, characterData: true });
+  }
+  if (options.enabled !== false) enable();
+  return { enable, disable, cleanup() {
+    if (closed) return;
+    disable();
+    closed = true;
+  } };
+}

package/src/index.d.ts

@@ -12,7 +12,9 @@ export interface Config { defaults?: boolean; autoDetect?: boolean; classificati
 export interface PlayOptions { ignoreReducedMotion?: boolean; skinTone?: SkinTone; animation?: KeyframeAnimationOptions; decoration?: { container: HTMLElement; anchor?: Anchor; flipX?: boolean; rotate?: number } }
 export interface BindOptions extends PlayOptions { trigger?: EventTarget; events?: string[] }
 export interface Resolution extends Omit<EmojiEntry, 'group' | 'motion'> { glyph: string; canonical: string; skinTone: SkinTone; groupId: string; group: Group; motionId: string; motion: Motion; decorationPreset?: Decoration; decorationPresets: Decoration[]; familyId?: string; animation?: KeyframeAnimationOptions; source: 'user' | 'user-classification' | 'preset' | 'family' | 'unicode' | 'fallback'; unicodeGroup?: string; unicodeSubgroup?: string }
-export interface EmojiMotion { resolve(glyph: string, options?: { skinTone?: SkinTone }): Resolution | undefined; setDefaultSkinTone(tone: SkinTone): void; getDefaultSkinTone(): SkinTone; play(element: Element, glyph: string, options?: PlayOptions): Animation | null; bind(element: Element, glyph: string, options?: BindOptions): () => void; list(): string[]; groups(): (Group & { id: string })[]; families(): (MotionFamily & { id: string })[] }
+export interface EnhanceOptions { root?: string | Element | Document | DocumentFragment; exclude?: string; enabled?: boolean; observe?: boolean; decoration?: boolean; events?: string[] }
+export interface EmojiEnhancer { enable(): void; disable(): void; cleanup(): void }
+export interface EmojiMotion { enhance(options?: EnhanceOptions): EmojiEnhancer; resolve(glyph: string, options?: { skinTone?: SkinTone }): Resolution | undefined; setDefaultSkinTone(tone: SkinTone): void; getDefaultSkinTone(): SkinTone; play(element: Element, glyph: string, options?: PlayOptions): Animation | null; bind(element: Element, glyph: string, options?: BindOptions): () => void; list(): string[]; groups(): (Group & { id: string })[]; families(): (MotionFamily & { id: string })[] }
 export declare function createEmojiMotion(config?: Config): EmojiMotion;
 export declare const motions: Record<string, Motion>;
 export declare const groups: Record<string, Group>;

package/src/lite.d.ts

@@ -1,2 +1,2 @@
 export { createEmojiMotion, emojiMotion, motions, groups, emoji, decorations, families, createSpringMotion, createSwayMotion } from './index.js';
-export type { Motion, MotionFamily, Group, Anchor, SvgShape, DecorationLayer, Decoration, SkinTone, EmojiEntry, Config, ClassificationRule, PlayOptions, BindOptions, Resolution, EmojiMotion } from './index.js';
+export type { Motion, MotionFamily, Group, Anchor, SvgShape, DecorationLayer, Decoration, SkinTone, EmojiEntry, Config, ClassificationRule, PlayOptions, BindOptions, EnhanceOptions, EmojiEnhancer, Resolution, EmojiMotion } from './index.js';

package/src/presets.js

@@ -46,7 +46,17 @@ export const motions = {
   leafSway: createSwayMotion(),
   hoverFlight: { keyframes: [{ transform: 'translateY(0) rotate(0deg)' }, { transform: 'translateY(-15%) rotate(-6deg)', offset: .3 }, { transform: 'translateY(-9%) rotate(6deg)', offset: .6 }, { transform: 'translateY(0) rotate(0deg)' }], options: { duration: 1000, easing: 'cubic-bezier(.22,1,.36,1)' } },
   gentleSip: { keyframes: [{ transform: 'translateY(0) rotate(0deg)' }, { transform: 'translateY(-7%) rotate(-4deg)', offset: .35 }, { transform: 'translateY(-7%) rotate(4deg)', offset: .65 }, { transform: 'translateY(0) rotate(0deg)' }], options: { duration: 1000, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 85%' },
-  pose: { keyframes: [{ transform: 'scale(1) translateY(0)' }, { transform: 'scale(1.04,1.06) translateY(-3%)', offset: .45 }, { transform: 'scale(1) translateY(0)' }], options: { duration: 1100, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 90%' }
+  pose: { keyframes: [{ transform: 'scale(1) translateY(0)' }, { transform: 'scale(1.04,1.06) translateY(-3%)', offset: .45 }, { transform: 'scale(1) translateY(0)' }], options: { duration: 1100, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 90%' },
+  carousel: { keyframes: [{ transform: 'perspective(500px) rotateY(0deg) translateY(0)' }, { transform: 'perspective(500px) rotateY(-35deg) translateY(-8%)', offset: .3 }, { transform: 'perspective(500px) rotateY(35deg) translateY(-4%)', offset: .65 }, { transform: 'perspective(500px) rotateY(0deg) translateY(0)' }], options: { duration: 1200, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 85%' },
+  flipHorizontal: { keyframes: [{ transform: 'perspective(500px) rotateY(0deg)' }, { transform: 'perspective(500px) rotateY(180deg)', offset: .5 }, { transform: 'perspective(500px) rotateY(360deg)' }], options: { duration: 1000, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  flipVertical: { keyframes: [{ transform: 'perspective(500px) rotateX(0deg)' }, { transform: 'perspective(500px) rotateX(180deg)', offset: .5 }, { transform: 'perspective(500px) rotateX(360deg)' }], options: { duration: 1000, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  steady: { keyframes: [{ transform: 'scale(1)' }, { transform: 'scale(1.025)', offset: .5 }, { transform: 'scale(1)' }], options: { duration: 1100, easing: 'cubic-bezier(.22,1,.36,1)' }, origin: '50% 100%' },
+  hourglassTurn: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(180deg)', offset: .4 }, { transform: 'rotate(180deg)', offset: .6 }, { transform: 'rotate(0deg)' }], options: { duration: 1300, easing: 'cubic-bezier(.22,1,.36,1)' } },
+  underwater: { keyframes: [{ transform: 'translateY(0) rotate(0deg)' }, { transform: 'translateY(-9%) rotate(-4deg)', offset: .35 }, { transform: 'translateY(3%) rotate(4deg)', offset: .7 }, { transform: 'translateY(0) rotate(0deg)' }], options: { duration: 1200, easing: curve } },
+  pastryBounce: createSpringMotion({ height: 12, rebounds: 1, duration: 850 }),
+  railRide: { keyframes: [{ transform: 'translateY(0) rotate(0deg)' }, { transform: 'translateY(-3%) rotate(-2deg)', offset: .25 }, { transform: 'translateY(0) rotate(2deg)', offset: .55 }, { transform: 'translateY(-2%) rotate(-1deg)', offset: .75 }, { transform: 'translateY(0) rotate(0deg)' }], options: { duration: 1000, easing: curve }, origin: '50% 85%' },
+  rhythm: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(-5deg)' }, { transform: 'rotate(5deg)' }, { transform: 'rotate(-3deg)' }, { transform: 'rotate(0deg)' }], options: { duration: 1050, easing: curve }, origin: '50% 80%' },
+  steps: { keyframes: [{ transform: 'translateY(0)' }, { transform: 'translateY(-7%)', offset: .25 }, { transform: 'translateY(0)', offset: .5 }, { transform: 'translateY(-5%)', offset: .75 }, { transform: 'translateY(0)' }], options: { duration: 1000, easing: curve }, origin: '50% 90%' }
 };
 
 // Groups describe semantic families; emoji entries may override the group's motion.
@@ -70,13 +80,29 @@ const skinTones = glyph => Object.fromEntries(['light', 'medium-light', 'medium'
 // A person modifier belongs before the joiner, never at the end of the sequence.
 const personSkinTones = suffix => Object.fromEntries(['light', 'medium-light', 'medium', 'medium-dark', 'dark'].map((tone, index) => [tone, `🧑${String.fromCodePoint(0x1f3fb + index)}‍${suffix}`]));
 const familyToneAliases = glyphs => Object.fromEntries(glyphs.flatMap(glyph => Object.values(skinTones(glyph)).map(variant => [variant, glyph])));
+// These reviewed ZWJ families use explicit suffixes; tests check every sequence against Unicode.
+const rolePeople = ['🧑', '👨', '👩'];
+const roleSuffixes = ['⚕️', '🎓', '🏫', '🌾', '🔧', '🔬', '🚒'];
+const roleMembers = roleSuffixes.flatMap(suffix => rolePeople.map(person => `${person}‍${suffix}`));
+const roleAliases = Object.fromEntries(roleSuffixes.flatMap(suffix => rolePeople.flatMap(person => Object.values(skinTones(person)).map(variant => [`${variant}‍${suffix}`, `${person}‍${suffix}`]))));
+const walkerMembers = ['🚶', '🚶‍♂️', '🚶‍♀️', '🏃‍♂️', '🏃‍♀️'];
+const walkerAliases = Object.fromEntries(walkerMembers.flatMap(glyph => {
+  const [person, suffix = ''] = glyph.split('‍');
+  return Object.values(skinTones(person)).map(variant => [suffix ? `${variant}‍${suffix}` : variant, glyph]);
+}));
 // Members are reviewed explicitly; no entire Unicode subgroup is assumed to move alike.
 export const families = {
   balls: { label: 'Balls', group: 'activities', motion: 'spring', members: ['⚾', '🥎', '🎱', '🎳'], animation: { duration: 900 }, decorations: ['impact', 'sparkle'] },
   plants: { label: 'Plants', group: 'nature', motion: 'leafSway', members: ['🌷', '🌹', '🌺', '🪻', '🌴', '🌿', '🍀'] },
   drinks: { label: 'Drinks', group: 'food', motion: 'gentleSip', members: ['🥤', '🧃', '🧋', '🍹', '🍸'] },
   flying: { label: 'Flying animals', group: 'nature', motion: 'hoverFlight', members: ['🦜', '🦉', '🦅', '🪰', '🦟'] },
-  poses: { label: 'People in poses', group: 'people', motion: 'pose', members: ['🧎', '🧍', '🙇'], aliases: familyToneAliases(['🧎', '🧍', '🙇']) }
+  poses: { label: 'People in poses', group: 'people', motion: 'pose', members: ['🧎', '🧍', '🙇'], aliases: familyToneAliases(['🧎', '🧍', '🙇']) },
+  professionals: { label: 'Professionals', group: 'people', motion: 'pose', members: roleMembers, aliases: roleAliases },
+  walkers: { label: 'Walking and running', group: 'people', motion: 'steps', members: walkerMembers, aliases: walkerAliases },
+  seaLife: { label: 'Sea life', group: 'nature', motion: 'underwater', members: ['🐠', '🐡', '🦈', '🐋', '🐳', '🦭'], decoration: 'bubbles' },
+  bakery: { label: 'Bakery', group: 'food', motion: 'pastryBounce', members: ['🍞', '🥐', '🥖', '🥨', '🥯', '🥞', '🧇'] },
+  rail: { label: 'Rail vehicles', group: 'travel', motion: 'railRide', members: ['🚄', '🚅', '🚆', '🚇', '🚈', '🚊', '🚝', '🚞'] },
+  instruments: { label: 'Instruments', group: 'activities', motion: 'rhythm', members: ['🎹', '🎷', '🎺', '🪕', '🪗', '🎻', '🪈'], decoration: 'sound' }
 };
 // Variants are explicit: unrelated sequences are never silently normalized.
 export const emoji = {
@@ -103,9 +129,9 @@ export const emoji = {
   '❤️': { 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', decoration: 'petals' }, '🍃': { 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: 'objects', name: 'Light bulb', motion: 'breathe', decoration: 'glow' }, '📷': { group: 'objects', name: 'Camera', motion: 'bounce', decoration: 'flash' }, '🔑': { group: 'objects', name: 'Key', motion: 'wobble' }, '📌': { group: 'objects', name: 'Pushpin', motion: 'bounce' }, '📦': { group: 'objects', name: 'Package', motion: 'shake' }, '🧭': { group: 'objects', name: 'Compass', motion: 'wobble' },
+  '🌸': { group: 'nature', name: 'Blossom', decoration: 'petals' }, '🍃': { group: 'nature', name: 'Leaves' }, '☀️': { group: 'nature', name: 'Sun', motion: 'spin', decoration: 'glow', variants: ['☀'] },
+  '🌻': { group: 'nature', name: 'Sunflower', motion: 'leafSway' }, '🌈': { 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', decoration: 'flicker' }, '🌊': { 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' },
@@ -113,7 +139,7 @@ export const emoji = {
   '☕': { group: 'food', name: 'Hot beverage', motion: 'sip', decoration: 'steam' }, '🍵': { group: 'food', name: 'Teacup', motion: 'sip', decoration: 'steam' }, '🍕': { group: 'food', name: 'Pizza', motion: 'bounce' }, '🍦': { group: 'food', name: 'Soft ice cream', motion: 'sway' },
   '🏀': { group: 'activities', name: 'Basketball', motion: 'hop' }, '⚽': { group: 'activities', name: 'Soccer ball', motion: 'hop' }, '🎈': { group: 'activities', name: 'Balloon', motion: 'float' }, '🎉': { group: 'activities', name: 'Party popper', motion: 'bounce', decoration: 'sparkle' },
   '💃': { group: 'people', name: 'Woman dancing', motion: 'twirl', skinTones: skinTones('💃') }, '🕺': { group: 'people', name: 'Man dancing', motion: 'twirl', skinTones: skinTones('🕺') },
-  '⏳': { group: 'objects', name: 'Hourglass', motion: 'flip' }, '⏰': { group: 'objects', name: 'Alarm clock', motion: 'shake' }, '🕯️': { group: 'objects', name: 'Candle', motion: 'sway', variants: ['🕯'] },
+  '⏳': { group: 'objects', name: 'Hourglass', motion: 'hourglassTurn' }, '⏰': { group: 'objects', name: 'Alarm clock', motion: 'shake' }, '🕯️': { group: 'objects', name: 'Candle', motion: 'steady', decoration: 'flicker', variants: ['🕯'] },
 
   // Additional handcrafted entries share motions where their physical action fits.
   '😀': { group: 'faces', name: 'Grinning face', motion: 'bounce' }, '🤣': { group: 'faces', name: 'Rolling on the floor laughing', motion: 'shake' },
@@ -143,9 +169,26 @@ export const emoji = {
   '🧑‍🚀': { group: 'people', name: 'Astronaut', motion: 'float', skinTones: personSkinTones('🚀') }, '🧑‍💻': { group: 'people', name: 'Technologist', motion: 'nod', skinTones: personSkinTones('💻') },
   '📱': { group: 'objects', name: 'Mobile phone', motion: 'shake' }, '📚': { group: 'objects', name: 'Books', motion: 'nod' }, '✉️': { group: 'objects', name: 'Envelope', motion: 'bob', variants: ['✉'] },
   '💌': { group: 'objects', name: 'Love letter', motion: 'bob', decoration: 'sparkle' }, '🔒': { group: 'objects', name: 'Locked', motion: 'wobble' }, '🔓': { group: 'objects', name: 'Unlocked', motion: 'pop' },
-  '🔦': { group: 'objects', name: 'Flashlight', motion: 'nod' }, '🪄': { group: 'objects', name: 'Magic wand', motion: 'twirl', decoration: 'sparkle' }, '🎤': { group: 'objects', name: 'Microphone', motion: 'swing', decoration: 'sound' },
+  '🔦': { group: 'objects', name: 'Flashlight', motion: 'nod', decoration: 'flash' }, '🪄': { group: 'objects', name: 'Magic wand', motion: 'twirl', decoration: 'sparkle' }, '🎤': { group: 'objects', name: 'Microphone', motion: 'swing', decoration: 'sound' },
   '🚌': { group: 'travel', name: 'Bus', motion: 'ride' }, '🚕': { group: 'travel', name: 'Taxi', motion: 'ride' }, '🚁': { group: 'travel', name: 'Helicopter', motion: 'bob' },
-  '🎡': { group: 'travel', name: 'Ferris wheel', motion: 'spin' }, '⛵': { group: 'travel', name: 'Sailboat', motion: 'bob' }, '🎠': { group: 'travel', name: 'Carousel horse', motion: 'hop' }
+  '🎡': { group: 'travel', name: 'Ferris wheel', motion: 'steady' }, '⛵': { group: 'travel', name: 'Sailboat', motion: 'bob' }, '🎠': { group: 'travel', name: 'Carousel horse', motion: 'carousel' },
+  // Direction-neutral lighting for other objects that naturally emit or reflect light.
+  '📸': { group: 'objects', name: 'Camera with flash', motion: 'bounce', decoration: 'flash' },
+  '🪔': { group: 'objects', name: 'Oil lamp', motion: 'sway', decoration: 'flicker' },
+  '🚨': { group: 'objects', name: 'Police car light', motion: 'pulse', decoration: 'alertLight' },
+  '🔅': { group: 'symbols', name: 'Dim button', motion: 'breathe', decoration: 'glow' },
+  '🔆': { group: 'symbols', name: 'Bright button', motion: 'pulse', decoration: 'glow' },
+  '🌞': { group: 'nature', name: 'Sun with face', motion: 'breathe', decoration: 'glow' },
+  '🌟': { group: 'nature', name: 'Glowing star', motion: 'pulse', decoration: 'sparkle' },
+  '⚡': { group: 'nature', name: 'High voltage', motion: 'pop', decoration: 'flash' },
+  '🎆': { group: 'activities', name: 'Fireworks', motion: 'pop', decoration: 'sparkle' },
+  '🎇': { group: 'activities', name: 'Sparkler', motion: 'wobble', decoration: 'sparkle' },
+  '🔮': { group: 'objects', name: 'Crystal ball', motion: 'breathe', decoration: 'sparkle' },
+  '💎': { group: 'objects', name: 'Gem stone', motion: 'pulse', decoration: 'sparkle' },
+  '🪩': { group: 'objects', name: 'Mirror ball', motion: 'spin', decoration: 'sparkle' },
+  '🌠': { group: 'nature', name: 'Shooting star', motion: 'float', decoration: 'sparkle' },
+  '🪙': { group: 'objects', name: 'Coin', motion: 'flipHorizontal' },
+  '🎲': { group: 'activities', name: 'Game die', motion: 'spin' }
 };
 
 // Declarative SVG layers never alter the native glyph. Anchors are relative to
@@ -166,7 +209,32 @@ const steamShape = { viewBox: '0 0 100 100', elements: [
 const rainShape = { viewBox: '0 0 100 100', elements: [
   { tag: 'path', attrs: { d: 'M30 67v6M50 72v6M70 67v6', fill: 'none', stroke: '#7c9fca', 'stroke-width': '3', 'stroke-linecap': 'round' } }
 ] };
+// Symmetric rays sit around the glyph rather than assuming a bulb, lens or flame position.
+const lightShape = color => ({ viewBox: '0 0 100 100', elements: [
+  { tag: 'path', attrs: { d: 'M50 4v9M50 87v9M4 50h9M87 50h9M17 17l6 6M77 77l6 6M83 17l-6 6M23 77l-6 6', fill: 'none', stroke: color, 'stroke-width': '3', 'stroke-linecap': 'round' } }
+] });
 export const decorations = {
+  bubbles: { anchor: { x: '50%', y: '50%' }, layers: [{ svg: { viewBox: '0 0 100 100', elements: [
+    { tag: 'circle', attrs: { cx: '21', cy: '46', r: '3', fill: 'none', stroke: '#7cafd0', 'stroke-width': '2' } },
+    { tag: 'circle', attrs: { cx: '76', cy: '38', r: '4', fill: 'none', stroke: '#7cafd0', 'stroke-width': '2' } },
+    { tag: 'circle', attrs: { cx: '80', cy: '60', r: '2', fill: 'none', stroke: '#7cafd0', 'stroke-width': '2' } }
+  ] }, style: centered, keyframes: [{ opacity: 0, transform: 'translate(-50%, -43%)' }, { opacity: .85, transform: 'translate(-50%, -50%)', offset: .35 }, { opacity: 0, transform: 'translate(-50%, -64%)' }], options: { duration: 1100, easing: curve } }] },
+  alertLight: { anchor: { x: '50%', y: '50%' }, layers: [{ svg: lightShape('#df625e'), style: centered,
+    keyframes: [{ opacity: 0, transform: 'translate(-50%, -50%) scale(.85)' }, { opacity: .9, transform: 'translate(-50%, -50%) scale(1)', offset: .3 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.12)' }],
+    options: { duration: 900, easing: 'cubic-bezier(.22,1,.36,1)' }
+  }] },
+  glow: { anchor: { x: '50%', y: '50%' }, layers: [{ svg: lightShape('#e0a63e'), style: centered,
+    keyframes: [{ opacity: 0, transform: 'translate(-50%, -50%) scale(.85)' }, { opacity: .9, transform: 'translate(-50%, -50%) scale(1)', offset: .35 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.08)' }],
+    options: { duration: 850, easing: 'cubic-bezier(.22,1,.36,1)' }
+  }] },
+  flicker: { anchor: { x: '50%', y: '50%' }, layers: [{ svg: lightShape('#df985c'), style: centered,
+    keyframes: [{ opacity: 0, transform: 'translate(-50%, -50%) scale(.9)' }, { opacity: .7, transform: 'translate(-50%, -50%) scale(1)', offset: .3 }, { opacity: .3, transform: 'translate(-50%, -50%) scale(.95)', offset: .5 }, { opacity: .75, transform: 'translate(-50%, -50%) scale(1.03)', offset: .7 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1)' }],
+    options: { duration: 1100, easing: 'cubic-bezier(.22,1,.36,1)' }
+  }] },
+  flash: { anchor: { x: '50%', y: '50%' }, layers: [{ svg: lightShape('#a5b7df'), style: centered,
+    keyframes: [{ opacity: 0, transform: 'translate(-50%, -50%) scale(.75)' }, { opacity: 1, transform: 'translate(-50%, -50%) scale(1)', offset: .18 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.2)', offset: .52 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.2)' }],
+    options: { duration: 800, easing: 'cubic-bezier(.22,1,.36,1)' }
+  }] },
   impact: { anchor: { x: '50%', y: '50%' }, layers: [{ svg: { viewBox: '0 0 100 100', elements: [{ tag: 'path', attrs: { d: 'M28 75l-5 4M72 75l5 4M50 79v6', fill: 'none', stroke: '#d49b70', 'stroke-width': '3', 'stroke-linecap': 'round' } }] }, style: centered,
     keyframes: [{ opacity: 0, transform: 'translate(-50%, -50%) scale(.8)' }, { opacity: 0, transform: 'translate(-50%, -50%) scale(.8)', offset: .45 }, { opacity: .85, transform: 'translate(-50%, -50%) scale(1)', offset: .65 }, { opacity: 0, transform: 'translate(-50%, -50%) scale(1.1)' }], options: { duration: 900, easing: 'cubic-bezier(.22,1,.36,1)' }
   }] },

package/src/react-core.js

@@ -4,7 +4,7 @@ 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 }) {
+  return function EmojiMotion({ emoji, skinTone, registry = emojiMotion, decoration = true, events = defaultEvents, triggerRef, label, className, style, ...attributes }) {
   const wrapper = useRef(null);
   const glyph = useRef(null);
   const visual = useRef(null);
@@ -13,7 +13,7 @@ export function createEmojiMotionComponent(emojiMotion) {
     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' } },
+  return createElement('span', { ...attributes, className, ref: wrapper, 'data-emoji-motion': 'component', role: 'img', 'aria-label': label ?? result?.name ?? emoji, tabIndex: attributes.tabIndex ?? (triggerRef ? -1 : 0), style },
     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.d.ts

@@ -5,7 +5,6 @@ export interface EmojiMotionProps extends Omit<HTMLAttributes<HTMLSpanElement>,
   skinTone?: SkinTone;
   registry?: Registry;
   decoration?: boolean;
-  display?: 'inline' | 'block';
   events?: string[];
   label?: string;
   triggerRef?: RefObject<HTMLElement | null>;

package/src/registry.js

@@ -1,3 +1,4 @@
+import { enhance } from './enhance.js';
 import { motions as defaultMotions, groups as defaultGroups, emoji as defaultEmoji, decorations as defaultDecorations, families as defaultFamilies } from './presets.js';
 
 const toneNames = ['default', 'light', 'medium-light', 'medium', 'medium-dark', 'dark'];
@@ -179,5 +180,5 @@ export function createRegistry(config = {}, classifier) {
     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 })), families: () => Object.entries({ ...builtinFamilies, ...userFamilies }).map(([id, family]) => ({ ...family, id, members: [...family.members], ...(family.aliases ? { aliases: { ...family.aliases } } : {}), ...(family.decorations ? { decorations: [...family.decorations] } : {}), ...(family.animation ? { animation: { ...family.animation } } : {}) })) };
+  return { resolve, play, bind, enhance(options) { return enhance({ resolve, bind }, options); }, setDefaultSkinTone(tone) { validateTone(tone); defaultSkinTone = tone; }, getDefaultSkinTone: () => defaultSkinTone, list: () => Object.keys(entries), groups: () => Object.entries(groups).map(([id, group]) => ({ id, ...group })), families: () => Object.entries({ ...builtinFamilies, ...userFamilies }).map(([id, family]) => ({ ...family, id, members: [...family.members], ...(family.aliases ? { aliases: { ...family.aliases } } : {}), ...(family.decorations ? { decorations: [...family.decorations] } : {}), ...(family.animation ? { animation: { ...family.animation } } : {}) })) };
 }

package/src/svelte-core.js

@@ -2,6 +2,8 @@
 /** Svelte action. Apply it to a span dedicated to the emoji. */
 export function createAnimateEmoji(emojiMotion) {
  return function animateEmoji(node, initial) {
+  const hadMarker = node.hasAttribute('data-emoji-motion');
+  if (!hadMarker) node.setAttribute('data-emoji-motion', 'action');
   let dispose = () => {};
   function update(options) {
     dispose();
@@ -10,6 +12,6 @@ export function createAnimateEmoji(emojiMotion) {
     dispose = registry.bind(node, emoji, { trigger, events, skinTone, ...(decoration && node.parentElement ? { decoration: { container: node.parentElement } } : {}) });
   }
   update(initial);
-  return { update, destroy() { dispose(); } };
+  return { update, destroy() { dispose(); if (!hadMarker) node.removeAttribute('data-emoji-motion'); } };
 }
 }

package/src/vue-core.js

@@ -7,7 +7,7 @@ export function createEmojiMotionComponent(emojiMotion) {
   inheritAttrs: false,
   props: {
     emoji: { type: String, required: true }, skinTone: String, registry: { type: Object, default: () => emojiMotion },
-    decoration: { type: Boolean, default: true }, display: { type: String, default: 'inline' }, trigger: { type: Object, default: null }, events: { type: Array, default: () => defaultEvents }, label: String
+    decoration: { type: Boolean, default: true }, trigger: { type: Object, default: null }, events: { type: Array, default: () => defaultEvents }, label: String
   },
   setup(props, { attrs }) {
     const wrapper = ref(null); const visual = ref(null); const glyph = ref(null);
@@ -21,7 +21,7 @@ export function createEmojiMotionComponent(emojiMotion) {
     onBeforeUnmount(stop);
     return () => {
       const result = props.registry.resolve(props.emoji, { skinTone: props.skinTone });
-      return h('span', { ...attrs, ref: wrapper, role: 'img', 'aria-label': props.label ?? result?.name ?? props.emoji, tabindex: attrs.tabindex ?? (props.trigger ? -1 : 0), style: [attrs.style, { display: props.display === 'block' ? 'block' : 'inline-block' }] },
+      return h('span', { ...attrs, ref: wrapper, 'data-emoji-motion': 'component', role: 'img', 'aria-label': props.label ?? result?.name ?? props.emoji, tabindex: attrs.tabindex ?? (props.trigger ? -1 : 0) },
         h('span', { ref: visual, style: { display: 'inline-block', position: 'relative' } },
           h('span', { ref: glyph, 'aria-hidden': 'true', style: { display: 'inline-block' } }, result?.glyph ?? props.emoji)));
     };

package/src/vue.d.ts

@@ -5,7 +5,6 @@ export interface EmojiMotionProps {
   skinTone?: SkinTone;
   registry?: Registry;
   decoration?: boolean;
-  display?: 'inline' | 'block';
   events?: string[];
   label?: string;
   trigger?: HTMLElement | null;