@dofy/native-emoji-motion 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.5.0 — 2026-11-13
+
+- Add reviewed motion families for fruit, animal faces, clouds, celestial bodies and writing tools.
+- Add judges, pilots and singers with their official skin tone variants.
+- Add five reusable motions and optional sparkles for fruit.
+
+## 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.

package/README.ja.md

@@ -0,0 +1,44 @@
+<h1 align="center">👋</h1>
+
+<h1 align="center">Emoji Motion</h1>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.zh-TW.md">繁體中文</a> · <a href="./README.ja.md">日本語</a></p>
+
+<p align="center"><strong>いつもの絵文字に、もう少し気持ちを。 ✨</strong></p>
+
+<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>
+
+端末のネイティブ絵文字に小さく表情豊かなアニメーションを追加します。React、Vue、Svelte、Web Component に対応し、肌の色、任意の SVG エフェクト、カスタムモーション、Unicode による自動分類を利用できます。[ライブデモ](https://emoji-motion.phpz.org/)でお試しください。
+
+## 📊 コレクションの概要
+
+| バージョン 0.5.0 | 数 | 内容 |
+| --- | ---: | --- |
+| 個別のプリセット | 177 | 個別に設定された基本絵文字 |
+| 確認済みモーションファミリー | 16 | さらに 123 種類の基本絵文字に対応 |
+| カテゴリ | 10 | コレクションの分類 |
+| 再利用可能なモーション | 42 | プリセットとファミリーで共有 |
+| SVG エフェクト付き絵文字 | 67 | 基本絵文字の数 |
+| 認識できる Unicode シーケンス | 5,235 | 肌の色などのバリエーションを含む Unicode Emoji 18.0 |
+
+肌の色などのバリエーションは追加の Unicode シーケンスとして数えます。プリセットや確認済みファミリーに一致しない絵文字には、分類に基づくフォールバックを適用します。
+
+## 📦 はじめに
+
+```sh
+npm install @dofy/native-emoji-motion
+```
+
+```jsx
+import { EmojiMotion } from '@dofy/native-emoji-motion/react';
+
+<p>Hello <EmojiMotion emoji="👋" skinTone="medium" /></p>
+```
+
+React、Vue、Svelte コンポーネントまたは Web Component を使用できます。`enhance()` で既存のテキストにもモーションを追加できます。設定、パラメーター、肌の色、カスタマイズの詳細は[ドキュメント](https://emoji-motion.phpz.org/docs/)をご覧ください。
+
+> 0.3.0 からアップグレードする場合：0.4.0 では `display` プロパティを削除しました。ブロック要素または CSS でレイアウトを調整してください。
+
+## 📄 ライセンス
+
+[MIT](./LICENSE)。Unicode データには [Unicode License](./UNICODE-LICENSE.txt) が適用されます。

package/README.md

@@ -1,256 +1,56 @@
-# Emoji Motion
+<h1 align="center">👋</h1>
 
-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"><a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.zh-TW.md">繁體中文</a> · <a href="./README.ja.md">日本語</a></p>
 
-The current repository and demo contain **177 handcrafted emoji presets** and **5 reviewed motion families** with **24 additional base emoji**, across **10 categories**. They use **32 reusable motions**; **44 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">
+  <strong>Give your emoji a little more feeling. ✨</strong><br />
+  Small, expressive animations for the native emoji you already use.
+</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.3.0.
+<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>
 
-## Try the demo
+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/).
 
-[Explore the live demo](https://emoji-motion.phpz.org/) or run it locally:
+- 🎨 **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.
 
-```sh
-npm run dev
-```
+## 📊 Collection at a glance
+
+| In version 0.5.0 | Count | What it covers |
+| --- | ---: | --- |
+| Handcrafted presets | 177 | Individually configured base emoji |
+| Reviewed motion families | 16 | 123 additional base emoji sharing reviewed motions |
+| Categories | 10 | Groups used to organize the collection |
+| Reusable motions | 42 | Motions shared by presets and families |
+| Emoji with optional SVG effects | 67 | 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/README.zh-CN.md

@@ -0,0 +1,44 @@
+<h1 align="center">👋</h1>
+
+<h1 align="center">Emoji Motion</h1>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.zh-TW.md">繁體中文</a> · <a href="./README.ja.md">日本語</a></p>
+
+<p align="center"><strong>让你的 emoji 多一点情绪。 ✨</strong></p>
+
+<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>
+
+为设备上的原生 emoji 添加小巧、富有表现力的动画，支持 React、Vue、Svelte 和 Web Component。支持肤色、可选 SVG 装饰、自定义动作与 Unicode 自动分类。前往 [在线演示](https://emoji-motion.phpz.org/) 体验。
+
+## 📊 项目概览
+
+| 0.5.0 版本 | 数量 | 说明 |
+| --- | ---: | --- |
+| 单独定制预设 | 177 | 逐个配置的基础 emoji |
+| 已审核动作家族 | 16 | 另外覆盖 123 个基础 emoji |
+| 类别 | 10 | 用于组织内容的分组 |
+| 可复用动作 | 42 | 预设和家族共享 |
+| 带可选 SVG 效果的 emoji | 67 | 基础 emoji 数量 |
+| 可识别 Unicode 序列 | 5,235 | Unicode Emoji 18.0，包含肤色等变体 |
+
+肤色及其他变体按额外 Unicode 序列计数；没有预设或已审核家族匹配的已识别 emoji 使用分类兜底动作。
+
+## 📦 快速开始
+
+```sh
+npm install @dofy/native-emoji-motion
+```
+
+```jsx
+import { EmojiMotion } from '@dofy/native-emoji-motion/react';
+
+<p>Hello <EmojiMotion emoji="👋" skinTone="medium" /></p>
+```
+
+可使用 React、Vue、Svelte 组件或 Web Component，也可通过 `enhance()` 为现有文本添加动效。完整接入、参数、肤色与自定义说明请参阅[帮助文档](https://emoji-motion.phpz.org/docs/)。
+
+> 从 0.3.0 升级？0.4.0 移除了 `display` 参数，请使用块级容器或 CSS 控制布局。
+
+## 📄 许可证
+
+[MIT](./LICENSE)。Unicode 数据适用 [Unicode License](./UNICODE-LICENSE.txt)。

package/README.zh-TW.md

@@ -0,0 +1,44 @@
+<h1 align="center">👋</h1>
+
+<h1 align="center">Emoji Motion</h1>
+
+<p align="center"><a href="./README.md">English</a> · <a href="./README.zh-CN.md">简体中文</a> · <a href="./README.zh-TW.md">繁體中文</a> · <a href="./README.ja.md">日本語</a></p>
+
+<p align="center"><strong>讓你的 emoji 多一點情緒。 ✨</strong></p>
+
+<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>
+
+為裝置上的原生 emoji 加入小巧、富有表現力的動畫，支援 React、Vue、Svelte 和 Web Component。支援膚色、可選 SVG 裝飾、自訂動作與 Unicode 自動分類。前往[線上展示](https://emoji-motion.phpz.org/)體驗。
+
+## 📊 專案概覽
+
+| 0.5.0 版本 | 數量 | 說明 |
+| --- | ---: | --- |
+| 個別訂製預設 | 177 | 逐一設定的基礎 emoji |
+| 已審核動作家族 | 16 | 另外涵蓋 123 個基礎 emoji |
+| 類別 | 10 | 用來組織內容的分組 |
+| 可重複使用動作 | 42 | 預設和家族共用 |
+| 帶可選 SVG 效果的 emoji | 67 | 基礎 emoji 數量 |
+| 可辨識 Unicode 序列 | 5,235 | Unicode Emoji 18.0，包含膚色等變體 |
+
+膚色和其他變體按額外 Unicode 序列計數；沒有預設或已審核家族匹配的已辨識 emoji 使用分類備援動作。
+
+## 📦 快速開始
+
+```sh
+npm install @dofy/native-emoji-motion
+```
+
+```jsx
+import { EmojiMotion } from '@dofy/native-emoji-motion/react';
+
+<p>Hello <EmojiMotion emoji="👋" skinTone="medium" /></p>
+```
+
+可使用 React、Vue、Svelte 元件或 Web Component，也可透過 `enhance()` 為現有文字加入動效。完整接入、參數、膚色與自訂說明請參閱[說明文件](https://emoji-motion.phpz.org/docs/)。
+
+> 從 0.3.0 升級？0.4.0 移除了 `display` 參數，請使用區塊容器或 CSS 控制版面配置。
+
+## 📄 授權
+
+[MIT](./LICENSE)。Unicode 資料適用 [Unicode License](./UNICODE-LICENSE.txt)。

package/assets/logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <text x="50" y="78" text-anchor="middle" font-size="78" font-family="Apple Color Emoji, Segoe UI Emoji, Noto Color Emoji, sans-serif">👋</text>
+</svg>

package/package.json

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

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

@@ -51,7 +51,17 @@ export const motions = {
   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)' } }
+  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%' },
+  fruitBounce: createSpringMotion({ height: 10, rebounds: 1, duration: 850 }),
+  curiousTilt: { keyframes: [{ transform: 'rotate(0deg) translateY(0)' }, { transform: 'rotate(-7deg) translateY(-3%)', offset: .3 }, { transform: 'rotate(7deg) translateY(-3%)', offset: .62 }, { transform: 'rotate(0deg) translateY(0)' }], options: { duration: 1100, easing: curve }, origin: '50% 85%' },
+  cloudDrift: { keyframes: [{ transform: 'translate(0, 0)' }, { transform: 'translate(-5%, -4%)', offset: .35 }, { transform: 'translate(5%, -4%)', offset: .7 }, { transform: 'translate(0, 0)' }], options: { duration: 1400, easing: curve } },
+  orbitFloat: { keyframes: [{ transform: 'translateY(0) scale(1)' }, { transform: 'translateY(-9%) scale(1.04)', offset: .45 }, { transform: 'translateY(0) scale(1)' }], options: { duration: 1200, easing: curve } },
+  writingTilt: { keyframes: [{ transform: 'rotate(0deg)' }, { transform: 'rotate(-5deg)', offset: .3 }, { transform: 'rotate(5deg)', offset: .65 }, { transform: 'rotate(0deg)' }], options: { duration: 1000, easing: curve }, origin: '50% 65%' },
+  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.
@@ -75,13 +85,34 @@ 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 = {
+  fruit: { label: 'Fruit', group: 'food', motion: 'fruitBounce', members: ['🍊', '🍋', '🍐', '🍑', '🍇', '🫐', '🍒', '🥝', '🍍', '🥭'], decoration: 'sparkle' },
+  animalFaces: { label: 'Animal faces', group: 'nature', motion: 'curiousTilt', members: ['🐶', '🦊', '🐹', '🦝', '🐨', '🐯', '🐭', '🐻‍❄️'] },
+  clouds: { label: 'Clouds', group: 'nature', motion: 'cloudDrift', members: ['🌤️', '⛅', '🌥️', '🌦️', '🌫️'], aliases: { '🌤': '🌤️', '🌥': '🌥️', '🌦': '🌦️', '🌫': '🌫️' } },
+  celestial: { label: 'Celestial bodies', group: 'nature', motion: 'orbitFloat', members: ['🌛', '🌜', '🌝', '🪐', '🌍', '🌎', '🌏', '🌚'] },
+  writingTools: { label: 'Writing tools', group: 'objects', motion: 'writingTilt', members: ['✏️', '🖊️', '🖋️', '🖌️', '🖍️'], aliases: { '✏': '✏️', '🖊': '🖊️', '🖋': '🖋️', '🖌': '🖌️', '🖍': '🖍️' } },
   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 = {
@@ -193,6 +224,11 @@ 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)' }

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;