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

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.2.0 — 2026-11-13
+
+- Expand the handcrafted collection to 161 emoji and add five reviewed motion families.
+- Add configurable spring and sway motion builders and composable SVG decorations.
+- Support custom families with explicit variant aliases and user-defined priority.
+- Improve the demo with family previews, persistent preferences and clearer examples.
+
+## 0.1.0 — 2026-11-13
+
+Initial public release.
+
+- Animate native emoji using handcrafted presets or automatic Unicode 18.0 classification.
+- Customize emoji, group and classification motions with user-defined rules taking priority.
+- Support skin tone variants, optional SVG decorations and reduced-motion preferences.
+- Provide components for React, Vue and Svelte, plus a framework-independent web component.
+- Offer preset-only lite entry points and TypeScript declarations.

package/LICENSE

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

package/README.md

@@ -1,3 +1,256 @@
-# Temporary Holding Version
+# Emoji Motion
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Small, expressive animations for native emoji. A framework independent library with Unicode based automatic classification, reusable motion presets and explicit per emoji overrides.
+
+## Collection at a glance
+
+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.
+
+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.
+
+## Try the demo
+
+[Explore the live demo](https://emoji-motion.phpz.org/) or run it locally:
+
+```sh
+npm run dev
+```
+
+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.
+
+## Installation
+
+```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
+
+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.
+
+## Development and release
+
+`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.

package/UNICODE-LICENSE.txt

@@ -0,0 +1,39 @@
+UNICODE LICENSE V3
+
+COPYRIGHT AND PERMISSION NOTICE
+
+Copyright © 1991-2026 Unicode, Inc.
+
+NOTICE TO USER: Carefully read the following legal agreement. BY
+DOWNLOADING, INSTALLING, COPYING OR OTHERWISE USING DATA FILES, AND/OR
+SOFTWARE, YOU UNEQUIVOCALLY ACCEPT, AND AGREE TO BE BOUND BY, ALL OF THE
+TERMS AND CONDITIONS OF THIS AGREEMENT. IF YOU DO NOT AGREE, DO NOT
+DOWNLOAD, INSTALL, COPY, DISTRIBUTE OR USE THE DATA FILES OR SOFTWARE.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of data files and any associated documentation (the "Data Files") or
+software and any associated documentation (the "Software") to deal in the
+Data Files or Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, and/or sell
+copies of the Data Files or Software, and to permit persons to whom the
+Data Files or Software are furnished to do so, provided that either (a)
+this copyright and permission notice appear with all copies of the Data
+Files or Software, or (b) this copyright and permission notice appear in
+associated Documentation.
+
+THE DATA FILES AND SOFTWARE ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT OF
+THIRD PARTY RIGHTS.
+
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR HOLDERS INCLUDED IN THIS NOTICE
+BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL INDIRECT OR CONSEQUENTIAL DAMAGES,
+OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
+WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
+ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THE DATA
+FILES OR SOFTWARE.
+
+Except as contained in this notice, the name of a copyright holder shall
+not be used in advertising or otherwise to promote the sale, use or other
+dealings in these Data Files or Software without prior written
+authorization of the copyright holder.

package/package.json

@@ -1,6 +1,130 @@
 {
   "name": "@dofy/native-emoji-motion",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Expressive, extensible animations for native emoji with optional SVG effects",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "default": "./src/index.js"
+    },
+    "./react": {
+      "types": "./src/react.d.ts",
+      "import": "./src/react.js"
+    },
+    "./vue": {
+      "types": "./src/vue.d.ts",
+      "import": "./src/vue.js"
+    },
+    "./svelte": {
+      "types": "./src/svelte.d.ts",
+      "import": "./src/svelte.js"
+    },
+    "./element": {
+      "types": "./src/element.d.ts",
+      "import": "./src/element.js"
+    },
+    "./svelte/EmojiMotion.svelte": {
+      "types": "./src/EmojiMotion.svelte.d.ts",
+      "svelte": "./src/EmojiMotion.svelte",
+      "default": "./src/EmojiMotion.svelte"
+    },
+    "./lite": {
+      "types": "./src/lite.d.ts",
+      "import": "./src/lite.js",
+      "default": "./src/lite.js"
+    },
+    "./react/lite": {
+      "types": "./src/react.d.ts",
+      "import": "./src/react-lite.js"
+    },
+    "./vue/lite": {
+      "types": "./src/vue.d.ts",
+      "import": "./src/vue-lite.js"
+    },
+    "./svelte/lite": {
+      "types": "./src/svelte.d.ts",
+      "import": "./src/svelte-lite.js"
+    },
+    "./svelte/EmojiMotionLite.svelte": {
+      "types": "./src/EmojiMotion.svelte.d.ts",
+      "svelte": "./src/EmojiMotionLite.svelte",
+      "default": "./src/EmojiMotionLite.svelte"
+    },
+    "./element/lite": {
+      "types": "./src/element.d.ts",
+      "import": "./src/element-lite.js"
+    }
+  },
+  "types": "./src/index.d.ts",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "UNICODE-LICENSE.txt",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "dev": "node demo/server.js",
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run",
+    "build:demo": "node scripts/build-demo.js",
+    "prepublishOnly": "npm test && npm run test:types",
+    "test:types": "tsc --noEmit --strict --skipLibCheck false --module nodenext --moduleResolution nodenext --target es2022 type-tests/consumer.mts",
+    "generate:unicode": "node scripts/generate-unicode.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "keywords": [
+    "emoji",
+    "emoji-animation",
+    "animation",
+    "web-animations",
+    "svg",
+    "skin-tone",
+    "zero-dependencies"
+  ],
+  "sideEffects": [
+    "./src/element.js",
+    "./src/element-lite.js"
+  ],
+  "homepage": "https://emoji-motion.phpz.org",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dofy/emoji-motion.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dofy/emoji-motion/issues"
+  },
+  "devDependencies": {
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "^26.1.0",
+    "prismjs": "^1.30.0",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "svelte": "^5.57.3",
+    "svelte4": "npm:svelte@^4.2.20",
+    "typescript": "~5.9.3",
+    "vue": "^3.5.45"
+  },
+  "peerDependencies": {
+    "react": "^18.2.0 || ^19.0.0",
+    "svelte": "^4.0.0 || ^5.0.0",
+    "vue": "^3.3.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    }
+  }
+}

package/src/EmojiMotion.svelte

@@ -0,0 +1,22 @@
+<script>
+  import { animateEmoji } from './svelte.js';
+  import { emojiMotion } from './index.js';
+  export let emoji;
+  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'];
+  let wrapper;
+  $: 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 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>
+  </span>
+</span>

package/src/EmojiMotion.svelte.d.ts

@@ -0,0 +1,13 @@
+import { SvelteComponentTyped } from 'svelte';
+import type { EmojiMotion as Registry, SkinTone } from './index.js';
+export interface EmojiMotionProps {
+  emoji: string;
+  skinTone?: SkinTone;
+  registry?: Registry;
+  decoration?: boolean;
+  display?: 'inline' | 'block';
+  trigger?: EventTarget;
+  label?: string;
+  events?: string[];
+}
+export default class EmojiMotion extends SvelteComponentTyped<EmojiMotionProps> {}

package/src/EmojiMotionLite.svelte

@@ -0,0 +1,22 @@
+<script>
+  import { animateEmoji } from './svelte-lite.js';
+  import { emojiMotion } from './lite.js';
+  export let emoji;
+  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'];
+  let wrapper;
+  $: 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 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>
+  </span>
+</span>

package/src/element-core.js

@@ -0,0 +1,31 @@
+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'];
+  #registry = emojiMotion;
+  #dispose = () => {};
+  get registry() { return this.#registry; }
+  set registry(value) { this.#registry = value ?? emojiMotion; if (this.isConnected) this.#render(); }
+  connectedCallback() { this.#render(); }
+  disconnectedCallback() { this.#dispose(); }
+  attributeChangedCallback() { if (this.isConnected) this.#render(); }
+  #render() {
+    this.#dispose();
+    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;
+    const visual = this.ownerDocument.createElement('span');
+    Object.assign(visual.style, { display: 'inline-block', position: 'relative' });
+    const glyph = this.ownerDocument.createElement('span');
+    Object.assign(glyph.style, { display: 'inline-block' });
+    glyph.setAttribute('aria-hidden', 'true'); glyph.textContent = result?.glyph ?? emoji;
+    visual.append(glyph); this.replaceChildren(visual);
+    this.#dispose = this.#registry.bind(glyph, emoji, { trigger: this, events: ['pointerenter', 'focus', 'click'], skinTone, ...(this.getAttribute('decoration') !== 'false' ? { decoration: { container: visual } } : {}) });
+  }
+};
+}

package/src/element-lite.js

@@ -0,0 +1,7 @@
+import { emojiMotion } from './lite.js';
+import { createEmojiMotionElement } from './element-core.js';
+export const EmojiMotionElement = createEmojiMotionElement(emojiMotion);
+export function defineEmojiMotion() {
+  if (globalThis.customElements && !customElements.get('emoji-motion')) customElements.define('emoji-motion', EmojiMotionElement);
+}
+defineEmojiMotion();

package/src/element.d.ts

@@ -0,0 +1,3 @@
+import type { EmojiMotion } from './index.js';
+export declare class EmojiMotionElement extends HTMLElement { registry: EmojiMotion }
+export declare function defineEmojiMotion(): void;

package/src/element.js

@@ -0,0 +1,7 @@
+import { emojiMotion } from './index.js';
+import { createEmojiMotionElement } from './element-core.js';
+export const EmojiMotionElement = createEmojiMotionElement(emojiMotion);
+export function defineEmojiMotion() {
+  if (globalThis.customElements && !customElements.get('emoji-motion')) customElements.define('emoji-motion', EmojiMotionElement);
+}
+defineEmojiMotion();

package/src/index.d.ts

@@ -0,0 +1,25 @@
+export interface Motion { keyframes: Keyframe[]; options?: KeyframeAnimationOptions; origin?: string }
+export interface Group { label: string; description?: string; motion: string }
+export interface Anchor { x: string; y: string }
+export interface SvgShape { tag: 'path' | 'circle' | 'ellipse' | 'rect' | 'line' | 'polyline' | 'polygon'; attrs: Record<string, string> }
+export interface DecorationLayer { style: Partial<CSSStyleDeclaration>; keyframes: Keyframe[]; options?: KeyframeAnimationOptions; svg?: { viewBox: string; elements: SvgShape[] } }
+export interface Decoration { anchor: Anchor; layers: DecorationLayer[] }
+export type SkinTone = 'default' | 'light' | 'medium-light' | 'medium' | 'medium-dark' | 'dark';
+export interface EmojiEntry { group: string; name: string; motion?: string; decoration?: string; variants?: string[]; skinTones?: Partial<Record<Exclude<SkinTone, 'default'>, string>> }
+export interface ClassificationRule { group: string; motion?: string }
+export interface MotionFamily { label: string; group: string; motion: string; members: string[]; aliases?: Record<string, string>; decoration?: string; decorations?: string[]; animation?: KeyframeAnimationOptions }
+export interface Config { defaults?: boolean; autoDetect?: boolean; classifications?: { groups?: Record<string, ClassificationRule>; subgroups?: Record<string, ClassificationRule>; fallback?: ClassificationRule }; defaultSkinTone?: SkinTone; motions?: Record<string, Motion>; decorations?: Record<string, Decoration>; groups?: Record<string, Group>; emoji?: Record<string, EmojiEntry>; families?: Record<string, MotionFamily> }
+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 declare function createEmojiMotion(config?: Config): EmojiMotion;
+export declare const motions: Record<string, Motion>;
+export declare const groups: Record<string, Group>;
+export declare const emoji: Record<string, EmojiEntry>;
+export declare const emojiMotion: EmojiMotion;
+export declare const decorations: Record<string, Decoration>;
+export declare const families: Record<string, MotionFamily>;
+export declare function createSpringMotion(options?: { height?: number; rebounds?: 0 | 1 | 2; duration?: number }): Motion;
+export declare function createSwayMotion(options?: { angle?: number; duration?: number; origin?: string }): Motion;
+export declare const unicodeVersion: string;

package/src/index.js

@@ -0,0 +1,8 @@
+import { createRegistry } from './registry.js';
+import { lookupUnicode, looksLikeEmoji } from './unicode.js';
+
+const classifier = { lookup: lookupUnicode, looksLikeEmoji };
+export function createEmojiMotion(config = {}) { return createRegistry(config, classifier); }
+export { motions, groups, emoji, decorations, families, createSpringMotion, createSwayMotion } from './presets.js';
+export { unicodeVersion } from './unicode.js';
+export const emojiMotion = createEmojiMotion();

package/src/lite.d.ts

@@ -0,0 +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';

package/src/lite.js

@@ -0,0 +1,5 @@
+import { createRegistry } from './registry.js';
+/** Preset-only entry: does not load Unicode classification data. */
+export function createEmojiMotion(config = {}) { return createRegistry(config); }
+export { motions, groups, emoji, decorations, families, createSpringMotion, createSwayMotion } from './presets.js';
+export const emojiMotion = createEmojiMotion();