release: v2.2.11

Fix VersionCheck crash: move VersionCheck and Toaster inside BrowserRouter
VersionCheck and Toaster were rendering outside the BrowserRouter in App.tsx, so the <Link> in the version update toast had no Router context. Moved both into AppRouter.tsx inside BrowserRouter. Also truncate changelog excerpt to 60 chars with ellipsis for cleaner toast display.
2026-04-02 03:05:10 -05:00 · 2026-04-02 03:01:32 -05:00 · 2026-04-02 02:48:34 -05:00 · 2026-04-02 02:40:44 -05:00 · 2026-04-02 02:39:40 -05:00 · 2026-04-02 02:37:13 -05:00
278 changed files with 23073 additions and 7205 deletions
@@ -26,19 +26,37 @@ test:
  script:
    - npm run test

-pages:
+deploy-nsite:
  stage: deploy
-  timeout: 5 minutes
+  timeout: 10 minutes
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: never
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+  variables:
+    NSYTE_VERSION: "v0.24.1"
  script:
+    # Build the web app
+    - npm ci
    - npm run build
-    - rm -rf public
-    - mv dist public
-  artifacts:
-    paths:
-      - public
-  only:
-    variables:
-      - $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+    - cp dist/index.html dist/404.html
+
+    # Download nsyte binary
+    - curl -fsSL "https://github.com/sandwichfarm/nsyte/releases/download/${NSYTE_VERSION}/nsyte-linux" -o /usr/local/bin/nsyte
+    - chmod +x /usr/local/bin/nsyte
+
+    # Deploy to nsite via nsyte using the nbunksec credential
+    - >-
+      nsyte deploy ./dist
+      -i
+      --sec "$NSITE_NBUNKSEC"
+      --name ditto
+      --relays "wss://relay.ditto.pub,wss://relay.nsite.lol,wss://relay.dreamith.to,wss://relay.primal.net"
+      --servers "https://blossom.primal.net,https://blossom.ditto.pub,https://blossom.dreamith.to"
+      --fallback "/index.html"
+      --publish-server-list
+      --use-fallback-relays
+      --use-fallback-servers

 build-apk:
  stage: build
@@ -198,4 +216,4 @@ publish-zapstore:
    - VERSION="${CI_COMMIT_TAG#v}"
    - sed -i "2i release_source:\ ./${APK_PATH}" zapstore.yaml
    - sed -i "2i version:\ ${VERSION}" zapstore.yaml
-    - zsp publish -y --skip-metadata --skip-preview zapstore.yaml
+    - zsp publish --quiet --skip-metadata --skip-preview zapstore.yaml
@@ -294,14 +294,16 @@ When adding support for a new Nostr event kind to the application, the kind must
   - `WELL_KNOWN_KIND_LABELS` in `src/components/ExternalContentHeader.tsx` -- used in addressable event preview headers
   - The icon fallback in `AddressableEventPreview` in the same file

-6. **Inline embeds / quote posts** -- events can be quoted inline via `nostr:nevent1...` or `nostr:naddr1...` URIs in note content. Both `EmbeddedNote` and `EmbeddedNaddr` render a compact card (author + title/content preview) for all kinds automatically — no per-kind registration needed. The same components are reused by CommentContext hover cards and the reply composer.
+6. **Embedded note cards** (`src/components/EmbeddedNote.tsx`, `src/components/EmbeddedNaddr.tsx`) -- these are the small preview cards shown inside quote posts, reply context indicators, and CommentContext hover cards. They are **separate components** from `NoteCard` and render a minimal card (author + title/content preview + attachment indicators). Basic rendering works for all kinds automatically, but kinds whose media lives in tags rather than in the `content` field (e.g. kind 20 photos via `imeta` tags) may need attachment indicator logic added to `EmbeddedNoteCard`.
+
+   > **Note**: Do not confuse these with the `compact` prop on `NoteCard`. The `compact` prop simply hides action buttons on a full `NoteCard`; `EmbeddedNote`/`EmbeddedNaddr` are entirely different components with their own rendering logic.

 7. **Reply composer** (`src/components/ReplyComposeModal.tsx`):
   - The `EmbeddedPost` component delegates to the shared `EmbeddedNote`/`EmbeddedNaddr` components — no per-kind registration needed

 #### Why so many places?

-These are genuinely different UI contexts (feed cards, detail pages, inline embeds, reply previews, comment context labels) with different rendering requirements. However, several of them maintain independent kind-to-label maps that could theoretically be unified. When in doubt, search the codebase for an existing kind number like `30617` to find all the registration points.
+These are genuinely different UI contexts (feed cards, detail pages, embedded note cards, reply previews, comment context labels) with different rendering requirements. However, several of them maintain independent kind-to-label maps that could theoretically be unified. When in doubt, search the codebase for an existing kind number like `30617` to find all the registration points.

 ### NIP.md

@@ -693,6 +695,27 @@ export function MyComponent() {

 The `useCurrentUser` hook should be used to ensure that the user is logged in before they are able to publish Nostr events.

+### Mutating Replaceable Events (CRITICAL)
+
+Replaceable (kind 10000-19999) and addressable (kind 30000-39999) events require a read-modify-write cycle: fetch the current event, modify its tags, then publish a new version. **Never read from TanStack Query cache before mutating** -- the cache can be stale from another device or a rapid prior operation, and republishing stale data silently drops the user's data.
+
+Use `fetchFreshEvent()` from `src/lib/fetchFreshEvent.ts` inside every mutation:
+
+```typescript
+import { fetchFreshEvent } from '@/lib/fetchFreshEvent';
+
+// Inside a mutation function:
+const freshEvent = await fetchFreshEvent(nostr, {
+  kinds: [10003],
+  authors: [user.pubkey],
+});
+const currentTags = freshEvent?.tags ?? [];
+// ...modify tags...
+await publishEvent({ kind: 10003, content: freshEvent?.content ?? '', tags: newTags });
+```
+
+This applies to all list-type hooks (bookmarks, pins, interests, follow sets, badges, etc.). See `useFollowActions` and `useMuteList` for complete examples.
+
 ### Nostr Login

 To enable login with Nostr, simply use the `LoginArea` component already included in this project.
@@ -954,6 +977,16 @@ const defaultConfig: AppConfig = {

 The app uses NIP-65 compatible relay management with automatic sync when users log in. Local storage persists user preferences and relay configurations.

+### Adding a New AppConfig Value
+
+Adding a new configuration field requires updates in **three places**. Missing any of them will cause build failures or runtime issues.
+
+1. **TypeScript interface** (`src/contexts/AppContext.ts`): Add the field to the `AppConfig` interface with a JSDoc comment.
+
+2. **Zod schema** (`src/lib/schemas.ts`): Add the same field to `AppConfigSchema`. The `DittoConfigSchema` (used to validate the build-time `ditto.json` file) is derived from `AppConfigSchema` with `.strict()` mode, so any field present in `ditto.json` but missing from the Zod schema will cause a build error.
+
+3. **Default value** (`src/contexts/AppContext.ts`): If the field is required (not optional), add a default value in `defaultConfig`. Optional fields (`?` in the interface, `.optional()` in Zod) can be omitted from the default.
+
 ### Relay Management

 The project includes a complete NIP-65 relay management system:
@@ -1315,7 +1348,7 @@ After adding or removing plugins, run `npx cap sync` to update the native projec
 The project uses GitLab CI (`.gitlab-ci.yml`) with the following stages:

 1. **test** - Runs `npm run test` on every commit (skipped for tags)
-2. **deploy** - Builds and deploys to GitLab Pages (default branch only)
+2. **deploy** - Builds and deploys to nsite via nsyte (`deploy-nsite` job, default branch only)
 3. **build** - Builds a signed release APK (`build-apk` job, tags only)
 4. **release** - Creates a GitLab Release with the APK artifact (tags only)
 5. **publish** - Publishes the APK to Zapstore (`publish-zapstore` job, tags only)
@@ -1355,19 +1388,69 @@ NIP-46 bunker signing requires two keys: the **user's key** (held by Amber) and
 The `publish-zapstore` job restores the client key from `ZAPSTORE_CLIENT_KEY` into `~/.config/zsp/bunker-keys/<bunker-pubkey>.key` before running `zsp`, so the bunker recognizes the CI runner as an already-authorized client.

 **Initial setup (one-time):**
-1. Generate a client key: `nak key generate` (save the hex output)
-2. Store it as `ZAPSTORE_CLIENT_KEY` in GitLab CI/CD variables
-3. Get a bunker URL from Amber (with `secret` param for first connection)
-4. Authorize the client key locally using `nak`:
-   ```bash
-   export NOSTR_CLIENT_KEY="<the hex client key>"
-   nak event --sec "bunker://<pubkey>?relay=...&secret=<secret>" -c "test"
-   ```
-5. Approve the connection on Amber when prompted
-6. Store the bunker URL **without the `secret` param** as `ZAPSTORE_BUNKER_URL` in GitLab CI/CD variables (the secret is single-use and no longer needed after authorization)
+
+Run the NIP-46 client-initiated auth script:
+
+```bash
+node scripts/nip46-auth.mjs
+```
+
+This generates a `nostrconnect://` URI. Import/paste it into Amber and approve the connection. The script will then output the `bunker://` URI and client key hex, and write the client key to `~/.config/zsp/bunker-keys/`. Update the GitLab CI/CD variables with the printed values.
+
+The script accepts options:
+- `--relay <url>` -- relay for NIP-46 communication (default: `wss://relay.ditto.pub`)
+- `--name <name>` -- app name shown to the signer (default: `Ditto`)
+- `--timeout <sec>` -- how long to wait for approval (default: 300)

 **Key points:**
- The `secret` in bunker URLs is **single-use** -- it is consumed on first connection and cannot be reused
- The `ZAPSTORE_CLIENT_KEY` must be authorized locally first by connecting to the bunker with a fresh secret and approving on Amber
 - After authorization, the bunker recognizes the client key and no secret or manual approval is needed for CI runs
- If the client key is rotated, the authorization step must be repeated with a new bunker URL secret
+- If the client key is rotated, run the script again and update the GitLab CI/CD variables
+
+### nsite Publishing
+
+The project automatically deploys the web app to [nsite](https://nsite.run) on every push to the default branch using [nsyte](https://github.com/sandwichfarm/nsyte). The `deploy-nsite` CI job builds the Vite app and uploads the `dist/` directory to Blossom servers, publishing site manifest events to Nostr relays.
+
+nsyte uses a NIP-46 bunker credential called `nbunksec` -- a bech32-encoded string that bundles the bunker pubkey, client secret key, and relay info into a single self-contained token. This is passed to nsyte via `--sec`.
+
+**GitLab CI/CD Variables** (Settings > CI/CD > Variables):
+
+| Variable | Description | Protected | Masked | Raw |
+|---|---|---|---|---|
+| `NSITE_NBUNKSEC` | nbunksec credential from `nsyte ci`. Must start with `nbunksec1`. | Yes | Yes | Yes |
+
+#### Initial Setup (one-time)
+
+1. Install nsyte locally:
+   ```bash
+   curl -fsSL https://nsyte.run/get/install.sh | bash
+   ```
+
+2. Generate the CI credential:
+   ```bash
+   nsyte ci
+   ```
+   This will guide you through connecting a NIP-46 bunker (e.g. Amber) and output an `nbunksec1...` string. The credential is shown only once.
+
+3. Add the `nbunksec1...` value as the `NSITE_NBUNKSEC` variable in GitLab CI/CD settings (Settings > CI/CD > Variables). Mark it as **Protected** and **Masked**.
+
+#### Configured Relays and Servers
+
+The deploy job publishes to these relays:
+- `wss://relay.ditto.pub`
+- `wss://relay.nsite.lol`
+- `wss://relay.dreamith.to`
+- `wss://relay.primal.net`
+
+And uploads blobs to these Blossom servers:
+- `https://blossom.primal.net`
+- `https://blossom.ditto.pub`
+- `https://blossom.dreamith.to`
+
+The `--use-fallback-relays` and `--use-fallback-servers` flags also include nsyte's built-in defaults for broader coverage. The `--fallback "/index.html"` flag enables SPA client-side routing.
+
+#### Credential Rotation
+
+To rotate the nsite credential:
+1. Revoke the old bunker connection in your signer app
+2. Run `nsyte ci` again to generate a new `nbunksec1...` string
+3. Update the `NSITE_NBUNKSEC` variable in GitLab CI/CD settings
@@ -1,5 +1,145 @@
 # Changelog

+## [2.2.11] - 2026-04-02
+
+### Fixed
+- Fix crash caused by the "What's new" toast firing outside the router
+
+## [2.2.10] - 2026-04-02
+
+### Added
+- App cards for Nostr apps (NIP-89) now display in feeds and detail pages with hero images, icons, supported kinds, and quick-launch buttons
+- "What's new" toast appears after an app update with a changelog preview and link to the full changelog
+
+### Changed
+- Changelog page redesigned with a hero section for the latest release, collapsible older entries, and category icons inline with each item
+
+### Fixed
+- Compose box now fully resets to its collapsed state after posting, including poll options and media trays
+
+## [2.2.9] - 2026-04-01
+
+### Added
+- Emoji pack creator and editor with drag-and-drop image upload, auto-generated identifiers, and description field
+- Blobbi companions now appear in feeds and post detail pages
+
+### Changed
+- Blobbi shop redesigned with a tile layout and instant buy -- no more categories or accessory tabs
+- Emoji packs without any valid emojis are now hidden from feeds
+- Custom emoji shortcode collisions across packs are automatically resolved with pack-prefixed names
+
+## [2.2.8] - 2026-04-01
+
+### Added
+- Full threaded reply trees on post detail pages with collapsible deep branches and "Show X more replies" for sibling threads
+- Broadcast button in the Event JSON dialog to re-publish any event to your relays
+
+### Changed
+- My Badges tab overhauled with drag-and-drop reordering, a scrollable list, and a showcase-style carousel for pending badges
+- Encrypted letter envelopes now show the mailing side first (sender and recipient), then flip to reveal the wax seal
+- Blobbi companions are more expressive -- richer status reactions, sleeping visuals, and body effects like dirt and hunger cues
+
+### Fixed
+- Notification dot not clearing after marking notifications as read
+- Followers/following modal staying open after navigating to a profile
+
+## [2.2.7] - 2026-03-31
+
+### Fixed
+- Nushu script in encrypted letters now renders correctly on Android and iOS
+
+## [2.2.6] - 2026-03-31
+
+### Added
+- Encrypted letters now appear as interactive 3D envelopes with Nushu script -- flip and open them to reveal the secret writing inside
+- Zap receipts and profile metadata events now render in feeds and detail pages
+- Remote signer callback page for NIP-46 login flows (Amber, Primal)
+
+### Changed
+- Post action buttons extracted into a reusable PostActionBar component
+- Badge detail page streamlined with unified tab bar
+
+### Fixed
+- Hashtags now support accented and Unicode characters
+- Letter compose opens correctly from notifications and the letters page
+- Letter font picker loads fonts so each option previews in the correct typeface
+- Zap comment positioned inside the right column instead of floating with offset
+- Safe-area padding on pinned SubHeaderBar only applies when scrolled to top
+
+## [2.2.5] - 2026-03-30
+
+### Fixed
+- Crash when dragging profile tabs to reorder them
+
+## [2.2.4] - 2026-03-30
+
+### Changed
+- Profiles now have an emoji reaction button instead of a zap button -- express yourself with any emoji or custom emoji right on someone's profile
+- Zap moved to the profile overflow menu so it's still one tap away
+
+### Fixed
+- Crash on the notifications page caused by malformed badge award tags
+- Deleting a badge now also deletes all awards you issued for it
+- Custom emoji reactions missing their image tag no longer render as broken shortcodes
+- Deletion requests for addressable events now include both `e` and `a` tags for broader relay compatibility
+- Profile reactions no longer collapse into a single grouped notification
+- Oversized reaction emoji in comment context headers
+
+## [2.2.3] - 2026-03-30
+
+### Added
+- Letters now have an overflow menu, reply button, and a grid layout for browsing
+- Independent feed toggles for comments and generic reposts in content settings
+- Sidebar items are now visible to logged-out users so newcomers can explore everything
+
+### Changed
+- Compose textarea expands smoothly as you type instead of snapping to a new height
+- Blobbi stickers auto-shrink near card edges and clip cleanly at rounded boundaries
+
+### Fixed
+- Feed gaps when replies are disabled no longer cause missing posts
+- Avatar shape no longer flashes on load
+- Top bar arc no longer flickers during navigation transitions
+- Letter drawing-only sends, sticker drag bounds, and theme event preservation
+- Notification rendering for badges and letters
+- Duplicate React keys in content settings
+- Layout rendering warning when switching views
+
+## [2.2.2] - 2026-03-29
+
+### Added
+- Dedicated photo upload flow for sharing photos as NIP-68 kind 20 events
+- Pull-to-refresh on all feed pages
+- 3D tilt effect on badge images -- hover over badges to see them pop
+- Multi-select badge awarding with indicators for already-sent badges
+- Badge list recovery dialog for restoring kind 10008 profile badge lists
+- Compact badge row preview in embedded profile badges events
+- Custom emoji usage tracking so your most-used custom emojis appear in the quick-react bar
+- Release notes now included in Zapstore publishing
+- Changelog link in the app footer
+
+### Changed
+- "Vines" renamed to "Divines" everywhere in the app
+- Custom emojis appear first in the emoji picker, right after recent
+- Threaded comment view now shows the parent event as a NoteCard with kind action headers
+
+### Fixed
+- Delete post dialog no longer freezes the feed on desktop
+- Amber login on Android now properly retries when returning from the background
+- Key downloads on Android save to the correct location
+- Custom emoji SVGs render correctly in the emoji-mart picker
+- Double-tap reactions now properly show the emoji on the post
+- Emoji shortcode autocomplete text and highlight colors
+- Profile skeleton no longer flickers for brand-new users with no metadata
+- Addressable event routing now works correctly for replaceable events (kind 10000-19999)
+- Badge notifications are now clickable
+- Custom profile tab form no longer retains fields from a previously edited tab
+- Double line under profile tabs in edit mode
+- Inconsistent use of "geocache" vs "treasures" terminology
+- Search page "N new posts" pill no longer shows unfiltered count
+- Stale-cache overwrites in replaceable event mutations
+- Click-through on delete confirmation and note menu items
+
 ## [2.2.1] - 2026-03-28

 ### Fixed
@@ -17,7 +157,7 @@
 - Blobbi companion that follows you around the app, tracks your cursor, blinks, expresses emotions, and reacts to what you're doing
 - Blobbi shop and inventory system with items that affect your pet's stats
 - Daily missions with reroll, care streaks, and stage-based rewards
- Immersive full-screen vines experience on both mobile and desktop with floating controls
+- Immersive full-screen divines experience on both mobile and desktop with floating controls
 - NIP-11 relay information panel on the network settings page
 - Link preview cards now display inside quoted posts instead of raw URLs
 - Nsec paste guard warns you before accidentally pasting private keys outside the login field
@@ -2,12 +2,31 @@

 ## Event Kinds Overview

+### Ditto Kinds
+
 | Kind  | Name                 | Description                                           |
 |-------|----------------------|-------------------------------------------------------|
 | 36767 | Theme Definition     | Shareable, named custom UI theme                      |
 | 16767 | Active Profile Theme | The user's currently active theme (one per user)      |
 | 16769 | Profile Tabs         | The user's custom profile page tabs (one per user)    |
-| 8211  | Encrypted Letter     | Encrypted personal letter with visual stationery      |
+
+### Community Kinds
+
+These event kinds were created by community contributors and are supported by Ditto. Full specifications are maintained by their respective authors.
+
+| Kind  | Name                   | Description                                                      | Spec                                                                                      |
+|-------|------------------------|------------------------------------------------------------------|-------------------------------------------------------------------------------------------|
+| 3367  | Color Moment           | Color palette post expressing a mood                             | [NIP](https://gitlab.com/chad.curtis/espy/-/blob/main/NIP.md)                            |
+| 4223  | Weather Reading        | Sensor readings from a weather station                           | [Draft NIP](https://github.com/nostr-protocol/nips/pull/2163)                            |
+| 7516  | Found Log              | Log entry recording a user finding a geocache                    | [NIP-GC](https://gitlab.com/chad.curtis/treasures/-/blob/main/NIP-GC.md)                 |
+| 8211  | Encrypted Letter       | Encrypted personal letter with visual stationery                 | [NIP](https://gitlab.com/chad.curtis/lief/-/blob/main/NIP.md)                            |
+| 11125 | Blobbonaut Profile     | Owner profile with coins, achievements, and inventory            | [NIP-BB](https://github.com/Danidfra/nostr-pet/blob/production/NIP.md)                   |
+| 14919 | Blobbi Interaction     | Individual pet interaction (feed, play, clean, etc.)             | [NIP-BB](https://github.com/Danidfra/nostr-pet/blob/production/NIP.md)                   |
+| 14920 | Blobbi Breeding        | Breeding event between two adult Blobbis                         | [NIP-BB](https://github.com/Danidfra/nostr-pet/blob/production/NIP.md)                   |
+| 14921 | Blobbi Record          | Immutable lifecycle record (birth, evolution, adoption)          | [NIP-BB](https://github.com/Danidfra/nostr-pet/blob/production/NIP.md)                   |
+| 16158 | Weather Station        | Weather station metadata (location, sensors, connectivity)       | [Draft NIP](https://github.com/nostr-protocol/nips/pull/2163)                            |
+| 31124 | Blobbi Pet State       | Current state of a virtual Blobbi pet (addressable)              | [NIP-BB](https://github.com/Danidfra/nostr-pet/blob/production/NIP.md)                   |
+| 37516 | Geocache               | Geocache listing for real-world treasure hunting                 | [NIP-GC](https://gitlab.com/chad.curtis/treasures/-/blob/main/NIP-GC.md)                 |

 ---

@@ -294,3 +313,51 @@ The `shape` field is added to the JSON content of a kind 0 event alongside stand
 - The `shape` field is purely cosmetic and has no protocol-level significance.
 - Clients MAY choose not to support this extension, in which case avatars render as circles as usual.

+---
+
+## Community NIP Specifications
+
+The following specifications are maintained by their respective authors. Ditto implements these kinds but does not own the specs. See each link for the full event structure, tags, and client behavior.
+
+### Color Moments (Kind 3367)
+
+**Author:** Chad Curtis
+**Spec:** https://gitlab.com/chad.curtis/espy/-/blob/main/NIP.md
+**App:** https://espy.you
+
+Color palette posts capturing 3-6 colors from a beautiful moment, optionally accompanied by an emoji and layout preference. Supports horizontal, vertical, grid, star, checkerboard, and diagonal stripe layouts. A form of pre-verbal visual communication through color and emotion.
+
+### Geocaching (Kinds 37516, 7516)
+
+**Author:** Chad Curtis
+**Spec:** https://gitlab.com/chad.curtis/treasures/-/blob/main/NIP-GC.md
+**App:** https://treasures.to
+
+NIP-GC defines geocaching on Nostr. Kind 37516 (addressable) is a geocache listing with location (geohash), difficulty/terrain scores, size, and type. Kind 7516 is a found log recording a successful visit. The spec also covers comment logs (kind 1111 via NIP-22), verified finds with cryptographic proof (kind 7517), and cache retirement.
+
+### Personal Letters (Kind 8211)
+
+**Author:** Chad Curtis
+**Spec:** https://gitlab.com/chad.curtis/lief/-/blob/main/NIP.md
+**App:** https://lief.to
+
+NIP-44 encrypted personal letters with visual stationery, hand-drawn stickers, decorative frames, and custom fonts. Letters render as 5:4 landscape postcards. The privacy model is intentionally postcard-like: sender/recipient metadata is visible, content is encrypted.
+
+### Weather Station (Kinds 4223, 16158)
+
+**Author:** Sam Thomson
+**Spec:** https://github.com/nostr-protocol/nips/pull/2163
+**App:** https://weather.shakespeare.wtf
+**Firmware:** https://github.com/samthomson/weather-station
+
+Kind 16158 (replaceable) describes a weather station's configuration: name, geohash location, elevation, power source, connectivity, and sensor inventory. Kind 4223 (regular) carries individual sensor readings as 3-parameter tags `[sensor_type, value, model]`, enabling historical queries and cross-station comparison. Each station has its own keypair.
+
+### Blobbi Virtual Pet (Kinds 31124, 14919, 14920, 14921, 11125)
+
+**Author:** Danifra
+**Spec:** https://github.com/Danidfra/nostr-pet/blob/production/NIP.md
+**App:** https://nostr-pet.vercel.app
+**See also:** [Blobbi tag schema](docs/blobbi/blobbi-tag-schema.md) (Ditto-specific integration details)
+
+NIP-BB defines a virtual pet lifecycle on Nostr. Kind 31124 (addressable) holds the current pet state across three stages (egg, baby, adult) with stats, appearance, and personality traits. Kind 14919 logs individual interactions, kind 14920 records breeding events, kind 14921 stores immutable lifecycle records, and kind 11125 (replaceable) holds the owner's profile with coins, achievements, and inventory.
+
@@ -13,7 +13,7 @@ Made by [Soapbox](https://soapbox.pub).
 ## Features

 - **Theming** -- 9 built-in theme presets, 19 CSS token properties for full customization, and the ability to publish and share themes as Nostr events
- **Infinite Content Types** -- Text notes, articles, short-form videos (Vines), live streams, polls, follow packs, color moments, magic decks, geocaching, and Webxdc mini-apps
+- **Infinite Content Types** -- Text notes, articles, short-form videos (Divines), live streams, polls, follow packs, color moments, magic decks, geocaching, and Webxdc mini-apps
 - **Lightning Payments** -- Zap posts and profiles with sats via Nostr Wallet Connect (NWC) or WebLN
 - **Private Messaging** -- End-to-end encrypted DMs (NIP-04 and NIP-17)
 - **Comments** -- Comment on anything: posts, URLs, profiles, hashtags, books, and more (NIP-22)
@@ -14,7 +14,7 @@ android {
        minSdkVersion rootProject.ext.minSdkVersion
        targetSdkVersion rootProject.ext.targetSdkVersion
        versionCode 1
-        versionName "2.2.1"
+        versionName "2.2.11"
        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
        aaptOptions {
             // Files and dirs to omit from the packaged assets dir, modified to accommodate modern web apps.
@@ -35,8 +35,9 @@ android {
    buildTypes {
        release {
            signingConfig signingConfigs.release
-            minifyEnabled false
-            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
+            minifyEnabled true
+            shrinkResources true
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
        }
    }
 }
@@ -5,12 +5,19 @@
 # For more details, see
 #   http://developer.android.com/guide/developing/tools/proguard.html

-# If your project uses WebView with JS, uncomment the following
-# and specify the fully qualified class name to the JavaScript interface
-# class:
-#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
-#   public *;
-#}
+# Keep Capacitor classes (WebView JS bridge)
+-keep class com.getcapacitor.** { *; }
+-keep class pub.ditto.app.** { *; }
+
+# Keep WebView JS interfaces
+-keepclassmembers class * {
+    @android.webkit.JavascriptInterface <methods>;
+}
+
+# Keep OkHttp (used by Capacitor)
+-dontwarn okhttp3.**
+-dontwarn okio.**
+-keep class okhttp3.** { *; }

 # Uncomment this to preserve the line number information for
 # debugging stack traces.
@@ -60,7 +60,7 @@ const builtinThemes = {
 };
 ```

-Self-hosters can override these at build time via `ditto.json` (injected through `__DITTO_CONFIG__` in `vite.config.ts`), or at runtime via the `ThemesConfig` in `AppConfig.themes`.
+Self-hosters can override these at build time via `ditto.json` (injected through `import.meta.env.DITTO_CONFIG` in `vite.config.ts`), or at runtime via the `ThemesConfig` in `AppConfig.themes`.

 ### ThemeConfig

@@ -127,7 +127,6 @@ User preferences and computed flags.

 | Tag | Required | Stages | Persistent | Source | Format | Default | Description |
 |-----|----------|--------|------------|--------|--------|---------|-------------|
-| `visible_to_others` | No | egg, baby, adult | Yes | user | `true\|false` | true | Public visibility |
 | `breeding_ready` | No | egg, baby, adult | Yes | computed | `true\|false` | false | Breeding eligibility |

 ### 10. Evolution Tags
@@ -192,7 +191,7 @@ These tags are from legacy versions and MUST be removed when republishing events
 - All visual tags (colors, pattern, size)
 - All personality tags (if present)
 - All progression tags (`experience`, `care_streak`)
- All social tags (`visible_to_others`, `breeding_ready`)
+- All social tags (`breeding_ready`)
 - All extension tags (`theme`, `crossover_app`)

 ### Evolve (baby → adult)
@@ -303,7 +303,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 2.2.1;
+				MARKETING_VERSION = 2.2.11;
 				OTHER_SWIFT_FLAGS = "$(inherited) \"-D\" \"COCOAPODS\" \"-DDEBUG\"";
 				PRODUCT_BUNDLE_IDENTIFIER = pub.ditto.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
@@ -325,7 +325,7 @@
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 2.2.1;
+				MARKETING_VERSION = 2.2.11;
 				PRODUCT_BUNDLE_IDENTIFIER = pub.ditto.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "";
@@ -47,5 +47,9 @@
 	</array>
 	<key>UIViewControllerBasedStatusBarAppearance</key>
 	<true/>
+	<key>NSPhotoLibraryUsageDescription</key>
+	<string>Ditto needs access to your photo library to upload images to your posts and profile.</string>
+	<key>NSMicrophoneUsageDescription</key>
+	<string>Ditto needs access to your microphone to record voice messages.</string>
 </dict>
 </plist>
@@ -0,0 +1,72 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>NSPrivacyCollectedDataTypes</key>
+    <array>
+        <!-- Crash / performance data via Sentry/GlitchTip -->
+        <dict>
+            <key>NSPrivacyCollectedDataType</key>
+            <string>NSPrivacyCollectedDataTypeCrashData</string>
+            <key>NSPrivacyCollectedDataTypeLinked</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypeTracking</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypePurposes</key>
+            <array>
+                <string>NSPrivacyCollectedDataTypePurposeAppFunctionality</string>
+            </array>
+        </dict>
+        <!-- Performance / analytics data via Plausible -->
+        <dict>
+            <key>NSPrivacyCollectedDataType</key>
+            <string>NSPrivacyCollectedDataTypePerformanceData</string>
+            <key>NSPrivacyCollectedDataTypeLinked</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypeTracking</key>
+            <false/>
+            <key>NSPrivacyCollectedDataTypePurposes</key>
+            <array>
+                <string>NSPrivacyCollectedDataTypePurposeAnalytics</string>
+            </array>
+        </dict>
+    </array>
+    <key>NSPrivacyTracking</key>
+    <false/>
+    <key>NSPrivacyTrackingDomains</key>
+    <array/>
+    <key>NSPrivacyAccessedAPITypes</key>
+    <array>
+        <!-- UserDefaults — used by Capacitor/WKWebView for localStorage -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategoryUserDefaults</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <!-- CA92.1: Access info from same app -->
+                <string>CA92.1</string>
+            </array>
+        </dict>
+        <!-- File timestamp APIs — used by @capacitor/filesystem -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategoryFileTimestamp</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <!-- C617.1: Access file timestamps inside app container -->
+                <string>C617.1</string>
+            </array>
+        </dict>
+        <!-- Disk space APIs — used by WKWebView / file operations -->
+        <dict>
+            <key>NSPrivacyAccessedAPIType</key>
+            <string>NSPrivacyAccessedAPICategoryDiskSpace</string>
+            <key>NSPrivacyAccessedAPITypeReasons</key>
+            <array>
+                <!-- E174.1: Check available disk space before writing -->
+                <string>E174.1</string>
+            </array>
+        </dict>
+    </array>
+</dict>
+</plist>
@@ -1,12 +1,12 @@
 {
  "name": "ditto",
-  "version": "2.1.1",
+  "version": "2.2.10",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "ditto",
-      "version": "2.1.1",
+      "version": "2.2.10",
      "dependencies": {
        "@capacitor/app": "^8.0.0",
        "@capacitor/core": "^8.1.0",
@@ -38,6 +38,7 @@
        "@fontsource/courier-prime": "^5.2.8",
        "@fontsource/creepster": "^5.2.7",
        "@fontsource/luckiest-guy": "^5.2.8",
+        "@fontsource/noto-sans-nushu": "^5.2.6",
        "@fontsource/pacifico": "^5.2.7",
        "@fontsource/permanent-marker": "^5.2.7",
        "@fontsource/pirata-one": "^5.2.8",
@@ -989,6 +990,15 @@
        "url": "https://github.com/sponsors/ayuhito"
      }
    },
+    "node_modules/@fontsource/noto-sans-nushu": {
+      "version": "5.2.6",
+      "resolved": "https://registry.npmjs.org/@fontsource/noto-sans-nushu/-/noto-sans-nushu-5.2.6.tgz",
+      "integrity": "sha512-YZswFaWI+EspK69GAg0o53WPXsaYu89dhbjwMYvIFVaRTSYKfcLSdTVCksPQ4ClyXpbWEAmsP+MxRlYlV4kM5g==",
+      "license": "OFL-1.1",
+      "funding": {
+        "url": "https://github.com/sponsors/ayuhito"
+      }
+    },
    "node_modules/@fontsource/pacifico": {
      "version": "5.2.7",
      "resolved": "https://registry.npmjs.org/@fontsource/pacifico/-/pacifico-5.2.7.tgz",
@@ -6044,9 +6054,9 @@
      "license": "unlicense"
    },
    "node_modules/@xmldom/xmldom": {
-      "version": "0.8.11",
-      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.11.tgz",
-      "integrity": "sha512-cQzWCtO6C8TQiYl1ruKNn2U6Ao4o4WBBcbL61yJl84x+j5sOWWFU9X7DpND8XZG3daDppSsigMdfAIl2upQBRw==",
+      "version": "0.8.12",
+      "resolved": "https://registry.npmjs.org/@xmldom/xmldom/-/xmldom-0.8.12.tgz",
+      "integrity": "sha512-9k/gHF6n/pAi/9tqr3m3aqkuiNosYTurLLUtc7xQ9sxB/wm7WPygCv8GYa6mS0fLJEHhqMC1ATYhz++U/lRHqg==",
      "dev": true,
      "license": "MIT",
      "engines": {
@@ -1,7 +1,7 @@
 {
  "name": "ditto",
  "private": true,
-  "version": "2.2.1",
+  "version": "2.2.11",
  "type": "module",
  "scripts": {
    "dev": "npm i --silent && vite",
@@ -44,6 +44,7 @@
    "@fontsource/courier-prime": "^5.2.8",
    "@fontsource/creepster": "^5.2.7",
    "@fontsource/luckiest-guy": "^5.2.8",
+    "@fontsource/noto-sans-nushu": "^5.2.6",
    "@fontsource/pacifico": "^5.2.7",
    "@fontsource/permanent-marker": "^5.2.7",
    "@fontsource/pirata-one": "^5.2.8",
@@ -1,5 +1,145 @@
 # Changelog

+## [2.2.11] - 2026-04-02
+
+### Fixed
+- Fix crash caused by the "What's new" toast firing outside the router
+
+## [2.2.10] - 2026-04-02
+
+### Added
+- App cards for Nostr apps (NIP-89) now display in feeds and detail pages with hero images, icons, supported kinds, and quick-launch buttons
+- "What's new" toast appears after an app update with a changelog preview and link to the full changelog
+
+### Changed
+- Changelog page redesigned with a hero section for the latest release, collapsible older entries, and category icons inline with each item
+
+### Fixed
+- Compose box now fully resets to its collapsed state after posting, including poll options and media trays
+
+## [2.2.9] - 2026-04-01
+
+### Added
+- Emoji pack creator and editor with drag-and-drop image upload, auto-generated identifiers, and description field
+- Blobbi companions now appear in feeds and post detail pages
+
+### Changed
+- Blobbi shop redesigned with a tile layout and instant buy -- no more categories or accessory tabs
+- Emoji packs without any valid emojis are now hidden from feeds
+- Custom emoji shortcode collisions across packs are automatically resolved with pack-prefixed names
+
+## [2.2.8] - 2026-04-01
+
+### Added
+- Full threaded reply trees on post detail pages with collapsible deep branches and "Show X more replies" for sibling threads
+- Broadcast button in the Event JSON dialog to re-publish any event to your relays
+
+### Changed
+- My Badges tab overhauled with drag-and-drop reordering, a scrollable list, and a showcase-style carousel for pending badges
+- Encrypted letter envelopes now show the mailing side first (sender and recipient), then flip to reveal the wax seal
+- Blobbi companions are more expressive -- richer status reactions, sleeping visuals, and body effects like dirt and hunger cues
+
+### Fixed
+- Notification dot not clearing after marking notifications as read
+- Followers/following modal staying open after navigating to a profile
+
+## [2.2.7] - 2026-03-31
+
+### Fixed
+- Nushu script in encrypted letters now renders correctly on Android and iOS
+
+## [2.2.6] - 2026-03-31
+
+### Added
+- Encrypted letters now appear as interactive 3D envelopes with Nushu script -- flip and open them to reveal the secret writing inside
+- Zap receipts and profile metadata events now render in feeds and detail pages
+- Remote signer callback page for NIP-46 login flows (Amber, Primal)
+
+### Changed
+- Post action buttons extracted into a reusable PostActionBar component
+- Badge detail page streamlined with unified tab bar
+
+### Fixed
+- Hashtags now support accented and Unicode characters
+- Letter compose opens correctly from notifications and the letters page
+- Letter font picker loads fonts so each option previews in the correct typeface
+- Zap comment positioned inside the right column instead of floating with offset
+- Safe-area padding on pinned SubHeaderBar only applies when scrolled to top
+
+## [2.2.5] - 2026-03-30
+
+### Fixed
+- Crash when dragging profile tabs to reorder them
+
+## [2.2.4] - 2026-03-30
+
+### Changed
+- Profiles now have an emoji reaction button instead of a zap button -- express yourself with any emoji or custom emoji right on someone's profile
+- Zap moved to the profile overflow menu so it's still one tap away
+
+### Fixed
+- Crash on the notifications page caused by malformed badge award tags
+- Deleting a badge now also deletes all awards you issued for it
+- Custom emoji reactions missing their image tag no longer render as broken shortcodes
+- Deletion requests for addressable events now include both `e` and `a` tags for broader relay compatibility
+- Profile reactions no longer collapse into a single grouped notification
+- Oversized reaction emoji in comment context headers
+
+## [2.2.3] - 2026-03-30
+
+### Added
+- Letters now have an overflow menu, reply button, and a grid layout for browsing
+- Independent feed toggles for comments and generic reposts in content settings
+- Sidebar items are now visible to logged-out users so newcomers can explore everything
+
+### Changed
+- Compose textarea expands smoothly as you type instead of snapping to a new height
+- Blobbi stickers auto-shrink near card edges and clip cleanly at rounded boundaries
+
+### Fixed
+- Feed gaps when replies are disabled no longer cause missing posts
+- Avatar shape no longer flashes on load
+- Top bar arc no longer flickers during navigation transitions
+- Letter drawing-only sends, sticker drag bounds, and theme event preservation
+- Notification rendering for badges and letters
+- Duplicate React keys in content settings
+- Layout rendering warning when switching views
+
+## [2.2.2] - 2026-03-29
+
+### Added
+- Dedicated photo upload flow for sharing photos as NIP-68 kind 20 events
+- Pull-to-refresh on all feed pages
+- 3D tilt effect on badge images -- hover over badges to see them pop
+- Multi-select badge awarding with indicators for already-sent badges
+- Badge list recovery dialog for restoring kind 10008 profile badge lists
+- Compact badge row preview in embedded profile badges events
+- Custom emoji usage tracking so your most-used custom emojis appear in the quick-react bar
+- Release notes now included in Zapstore publishing
+- Changelog link in the app footer
+
+### Changed
+- "Vines" renamed to "Divines" everywhere in the app
+- Custom emojis appear first in the emoji picker, right after recent
+- Threaded comment view now shows the parent event as a NoteCard with kind action headers
+
+### Fixed
+- Delete post dialog no longer freezes the feed on desktop
+- Amber login on Android now properly retries when returning from the background
+- Key downloads on Android save to the correct location
+- Custom emoji SVGs render correctly in the emoji-mart picker
+- Double-tap reactions now properly show the emoji on the post
+- Emoji shortcode autocomplete text and highlight colors
+- Profile skeleton no longer flickers for brand-new users with no metadata
+- Addressable event routing now works correctly for replaceable events (kind 10000-19999)
+- Badge notifications are now clickable
+- Custom profile tab form no longer retains fields from a previously edited tab
+- Double line under profile tabs in edit mode
+- Inconsistent use of "geocache" vs "treasures" terminology
+- Search page "N new posts" pill no longer shows unfiltered count
+- Stale-cache overwrites in replaceable event mutations
+- Click-through on delete confirmation and note menu items
+
 ## [2.2.1] - 2026-03-28

 ### Fixed
@@ -17,7 +157,7 @@
 - Blobbi companion that follows you around the app, tracks your cursor, blinks, expresses emotions, and reacts to what you're doing
 - Blobbi shop and inventory system with items that affect your pet's stats
 - Daily missions with reroll, care streaks, and stage-based rewards
- Immersive full-screen vines experience on both mobile and desktop with floating controls
+- Immersive full-screen divines experience on both mobile and desktop with floating controls
 - NIP-11 relay information panel on the network settings page
 - Link preview cards now display inside quoted posts instead of raw URLs
 - Nsec paste guard warns you before accidentally pasting private keys outside the login field
@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+
+/**
+ * NIP-46 Client-Initiated Auth Script
+ *
+ * Generates an ephemeral client keypair and a `nostrconnect://` URI.
+ * Import the URI into a remote signer app (e.g. Amber) to authorize
+ * the client key. Once authorized, the script outputs:
+ *
+ *   - bunker:// URI (for ZAPSTORE_BUNKER_URL)
+ *   - client secret key hex (for ZAPSTORE_CLIENT_KEY)
+ *
+ * It also writes the client key to ~/.config/zsp/bunker-keys/<bunkerPubkey>.key
+ * so that `zsp` can use it immediately.
+ *
+ * Usage:
+ *   node scripts/nip46-auth.mjs [--relay wss://relay.example.com] [--name MyApp] [--timeout 300]
+ */
+
+import { NPool, NRelay1, NConnectSigner, NSecSigner } from '@nostrify/nostrify';
+import { generateSecretKey, getPublicKey, nip19 } from 'nostr-tools';
+import { bytesToHex } from '@noble/hashes/utils';
+import QRCode from 'qrcode';
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+// ---------------------------------------------------------------------------
+// CLI args
+// ---------------------------------------------------------------------------
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const result = {
+    relays: [],
+    name: 'Ditto',
+    timeout: 300, // seconds
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    switch (args[i]) {
+      case '--relay':
+        result.relays.push(args[++i]);
+        break;
+      case '--name':
+        result.name = args[++i];
+        break;
+      case '--timeout':
+        result.timeout = parseInt(args[++i], 10);
+        break;
+      case '--help':
+      case '-h':
+        console.log(`Usage: node scripts/nip46-auth.mjs [options]
+
+Options:
+  --relay <url>    Relay URL for NIP-46 communication (repeatable)
+                   Default: wss://relay.ditto.pub
+  --name <name>    Application name shown to the signer
+                   Default: Ditto
+  --timeout <sec>  How long to wait for signer approval (seconds)
+                   Default: 300 (5 minutes)
+  --help, -h       Show this help message
+`);
+        process.exit(0);
+    }
+  }
+
+  if (result.relays.length === 0) {
+    result.relays.push('wss://relay.ditto.pub');
+  }
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const opts = parseArgs();
+
+  // 1. Generate ephemeral client keypair
+  const clientSecretKey = generateSecretKey();
+  const clientPubkey = getPublicKey(clientSecretKey);
+  const clientHex = bytesToHex(clientSecretKey);
+
+  console.log('');
+  console.log('=== NIP-46 Client-Initiated Auth ===');
+  console.log('');
+  console.log(`Client pubkey: ${clientPubkey}`);
+  console.log(`Relay(s):      ${opts.relays.join(', ')}`);
+  console.log(`Timeout:       ${opts.timeout}s`);
+  console.log('');
+
+  // 2. Generate random secret
+  const randomBytes = new Uint8Array(4);
+  crypto.getRandomValues(randomBytes);
+  const secret = Array.from(randomBytes)
+    .map((b) => b.toString(16).padStart(2, '0'))
+    .join('');
+
+  // 3. Build nostrconnect:// URI
+  const searchParams = new URLSearchParams();
+  for (const relay of opts.relays) {
+    searchParams.append('relay', relay);
+  }
+  searchParams.set('secret', secret);
+  searchParams.set('name', opts.name);
+
+  const nostrConnectURI = `nostrconnect://${clientPubkey}?${searchParams.toString()}`;
+
+  console.log('Scan this QR code with your signer app (e.g. Amber):');
+  console.log('');
+  console.log(await QRCode.toString(nostrConnectURI, { type: 'terminal', small: true }));
+  console.log('Or import this URI manually:');
+  console.log('');
+  console.log(`  ${nostrConnectURI}`);
+  console.log('');
+  console.log('Waiting for signer to approve the connection...');
+  console.log('');
+
+  // 4. Set up relay pool
+  const pool = new NPool({
+    open: (url) => new NRelay1(url),
+    reqRouter: async (filters) => new Map(opts.relays.map((r) => [r, filters])),
+    eventRouter: async () => opts.relays,
+  });
+
+  const clientSigner = new NSecSigner(clientSecretKey);
+  const relayGroup = pool.group(opts.relays);
+
+  // 5. Subscribe and wait for the signer's response
+  const signal = AbortSignal.timeout(opts.timeout * 1000);
+
+  const sub = relayGroup.req(
+    [{ kinds: [24133], '#p': [clientPubkey], limit: 1 }],
+    { signal },
+  );
+
+  let bunkerPubkey;
+  let userPubkey;
+
+  try {
+    for await (const msg of sub) {
+      if (msg[0] === 'CLOSED') {
+        throw new Error('Relay closed the subscription before signer responded');
+      }
+      if (msg[0] === 'EVENT') {
+        const event = msg[2];
+
+        let decrypted;
+        try {
+          decrypted = await clientSigner.nip44.decrypt(event.pubkey, event.content);
+        } catch {
+          // Could not decrypt -- not for us, skip
+          continue;
+        }
+
+        let response;
+        try {
+          response = JSON.parse(decrypted);
+        } catch {
+          continue;
+        }
+
+        if (response.result !== secret && response.result !== 'ack') {
+          continue;
+        }
+
+        bunkerPubkey = event.pubkey;
+
+        console.log(`Signer responded! Bunker pubkey: ${bunkerPubkey}`);
+        console.log('');
+
+        // 6. Get user pubkey via the now-established connection
+        const signer = new NConnectSigner({
+          relay: relayGroup,
+          pubkey: bunkerPubkey,
+          signer: clientSigner,
+          timeout: 60_000,
+        });
+
+        console.log('Requesting user public key...');
+        userPubkey = await signer.getPublicKey();
+        console.log(`User pubkey:   ${userPubkey}`);
+        console.log('');
+
+        break;
+      }
+    }
+  } catch (err) {
+    if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+      console.error(`Timed out after ${opts.timeout}s waiting for signer approval.`);
+      console.error('Make sure you imported the nostrconnect:// URI into your signer app.');
+      process.exit(1);
+    }
+    throw err;
+  }
+
+  if (!bunkerPubkey || !userPubkey) {
+    console.error('Failed to establish connection with remote signer.');
+    process.exit(1);
+  }
+
+  // 7. Build bunker:// URI (for CI)
+  const bunkerParams = new URLSearchParams();
+  for (const relay of opts.relays) {
+    bunkerParams.append('relay', relay);
+  }
+  const bunkerURI = `bunker://${bunkerPubkey}?${bunkerParams.toString()}`;
+
+  // 8. Write client key to zsp config
+  const zspDir = path.join(os.homedir(), '.config', 'zsp', 'bunker-keys');
+  const zspKeyFile = path.join(zspDir, `${bunkerPubkey}.key`);
+
+  fs.mkdirSync(zspDir, { recursive: true });
+  fs.writeFileSync(zspKeyFile, clientHex + '\n', { mode: 0o600 });
+
+  // 9. Print results
+  console.log('=== Connection Established ===');
+  console.log('');
+  console.log('Bunker URI (ZAPSTORE_BUNKER_URL):');
+  console.log(`  ${bunkerURI}`);
+  console.log('');
+  console.log('Client secret key hex (ZAPSTORE_CLIENT_KEY):');
+  console.log(`  ${clientHex}`);
+  console.log('');
+  console.log(`User pubkey:   ${userPubkey}`);
+  console.log(`User npub:     ${nip19.npubEncode(userPubkey)}`);
+  console.log('');
+  console.log(`zsp client key written to: ${zspKeyFile}`);
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Update ZAPSTORE_BUNKER_URL in GitLab CI/CD variables');
+  console.log('  2. Update ZAPSTORE_CLIENT_KEY in GitLab CI/CD variables');
+  console.log('');
+
+  // Clean up
+  pool.close();
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Fatal error:', err.message);
+  process.exit(1);
+});
@@ -16,17 +16,19 @@ import NostrProvider from "@/components/NostrProvider";
 import { NostrSync } from "@/components/NostrSync";
 import { PlausibleProvider } from "@/components/PlausibleProvider";
 import { SentryProvider } from "@/components/SentryProvider";
-import { Toaster } from "@/components/ui/toaster";
+
+
 import { TooltipProvider } from "@/components/ui/tooltip";
 import { useNsecPasteGuard } from "@/hooks/useNsecPasteGuard";
 import type { AppConfig } from "@/contexts/AppContext";
 import { NWCProvider } from "@/contexts/NWCContext";
 import { PROTOCOL_MODE } from "@/lib/dmConstants";
+import { DittoConfigSchema, type DittoConfig } from "@/lib/schemas";
 import { EmotionDevProvider } from "@/blobbi/dev/EmotionDevContext";
 import AppRouter from "./AppRouter";

 const dmConfig: DMConfig = {
-  enabled: true,
+  enabled: false,
  protocolMode: PROTOCOL_MODE.NIP04_OR_NIP17,
 };

@@ -59,7 +61,9 @@ const hardcodedConfig: AppConfig = {
  },
  feedSettings: {
    feedIncludePosts: true,
+    feedIncludeComments: true,
    feedIncludeReposts: true,
+    feedIncludeGenericReposts: true,
    feedIncludeArticles: true,
    showArticles: true,
    showEvents: true,
@@ -112,17 +116,17 @@ const hardcodedConfig: AppConfig = {
    feedIncludeBadgeDefinitions: true,
    feedIncludeProfileBadges: true,
    feedIncludeVanish: true,
+    feedIncludeBlobbi: true,
    followsFeedShowReplies: true,
  },
  sidebarOrder: [
    "feed",
    "notifications",
    "search",
-    "bookmarks",
-    "profile",
-    "photos",
-    "videos",
    "themes",
+    "letters",
+    "badges",
+    "blobbi",
    "theme",
    "settings",
    "help",
@@ -146,15 +150,30 @@ const hardcodedConfig: AppConfig = {
  imageQuality: 'compressed',
 };

+/**
+ * Parse and validate build-time ditto.json overrides from the env string.
+ * Returns an empty object when no config file was provided or validation fails.
+ */
+function parseDittoConfig(): DittoConfig {
+  try {
+    const json = JSON.parse(import.meta.env.DITTO_CONFIG);
+    if (!json) return {};
+    return DittoConfigSchema.parse(json);
+  } catch {
+    return {};
+  }
+}
+
 /**
 * Merge hardcoded defaults with build-time ditto.json overrides.
+ * Deep-merges feedSettings so a partial override doesn't erase defaults.
 * Precedence (handled by AppProvider): user localStorage > build-time > hardcoded.
 */
+const dittoConfig = parseDittoConfig();
 const defaultConfig: AppConfig = {
  ...hardcodedConfig,
-  ...(typeof __DITTO_CONFIG__ !== "undefined" && __DITTO_CONFIG__
-    ? __DITTO_CONFIG__
-    : {}),
+  ...dittoConfig,
+  feedSettings: { ...hardcodedConfig.feedSettings, ...dittoConfig.feedSettings },
 };

 export function App() {
@@ -182,11 +201,11 @@ export function App() {
                <NostrProvider>
                  <NostrSync />
                  <NativeNotifications />
+
                    <NWCProvider>
                    <DMProvider config={dmConfig}>
                      <EmotionDevProvider>
                        <TooltipProvider>
-                          <Toaster />
                          <InitialSyncGate>
                            <AppRouter />
                          </InitialSyncGate>
@@ -6,8 +6,10 @@ import { MinimizedAudioBar } from "@/components/MinimizedAudioBar";
 import { AudioPlayerProvider } from "@/contexts/AudioPlayerContext";
 import { BlobbiActionsProvider } from "@/blobbi/companion/interaction/BlobbiActionsProvider";
 import { sidebarItemIcon } from "@/lib/sidebarItems";
+import { Toaster } from "./components/ui/toaster";
 import { MainLayout } from "./components/MainLayout";
 import { ScrollToTop } from "./components/ScrollToTop";
+import { VersionCheck } from "./components/VersionCheck";
 import { useCurrentUser } from "./hooks/useCurrentUser";
 import { useProfileUrl } from "./hooks/useProfileUrl";
 import { getExtraKindDef } from "./lib/extraKinds";
@@ -22,6 +24,9 @@ const BlobbiCompanionLayer = lazy(() => import("@/blobbi/companion").then(m => (
 // Lazy-loaded compose modal (pulls in emoji-mart ~620K)
 const ReplyComposeModal = lazy(() => import("@/components/ReplyComposeModal").then(m => ({ default: m.ReplyComposeModal })));

+// Lazy-loaded emoji pack dialog
+const EmojiPackDialog = lazy(() => import("@/components/EmojiPackDialog").then(m => ({ default: m.EmojiPackDialog })));
+
 // HomePage eagerly imported all page components; now lazy-loaded
 const HomePage = lazy(() => import("./pages/HomePage").then(m => ({ default: m.HomePage })));

@@ -45,6 +50,7 @@ const GeotagPage = lazy(() => import("./pages/GeotagPage").then(m => ({ default:
 const HashtagPage = lazy(() => import("./pages/HashtagPage").then(m => ({ default: m.HashtagPage })));
 const HelpPage = lazy(() => import("./pages/HelpPage").then(m => ({ default: m.HelpPage })));
 const KindFeedPage = lazy(() => import("./pages/KindFeedPage").then(m => ({ default: m.KindFeedPage })));
+const LetterComposePage = lazy(() => import("./pages/LetterComposePage").then(m => ({ default: m.LetterComposePage })));
 const LetterPreferencesPage = lazy(() => import("./pages/LetterPreferencesPage").then(m => ({ default: m.LetterPreferencesPage })));
 const LettersPage = lazy(() => import("./pages/LettersPage").then(m => ({ default: m.LettersPage })));
 const MagicSettingsPage = lazy(() => import("./pages/MagicSettingsPage").then(m => ({ default: m.MagicSettingsPage })));
@@ -70,6 +76,7 @@ const WalletSettingsPage = lazy(() => import("./pages/WalletSettingsPage").then(
 const WebxdcFeedPage = lazy(() => import("./pages/WebxdcFeedPage").then(m => ({ default: m.WebxdcFeedPage })));
 const WikipediaPage = lazy(() => import("./pages/WikipediaPage").then(m => ({ default: m.WikipediaPage })));
 const WorldPage = lazy(() => import("./pages/WorldPage").then(m => ({ default: m.WorldPage })));
+const RemoteLoginSuccessPage = lazy(() => import("./pages/RemoteLoginSuccessPage").then(m => ({ default: m.RemoteLoginSuccessPage })));

 const pollsDef = getExtraKindDef("polls")!;
 const colorsDef = getExtraKindDef("colors")!;
@@ -99,6 +106,26 @@ function PollsFeedPage() {
  );
 }

+/** Emoji feed page with a FAB that opens the emoji pack creation dialog. */
+function EmojiFeedPage() {
+  const [composeOpen, setComposeOpen] = useState(false);
+  return (
+    <>
+      <KindFeedPage
+        kind={emojisDef.kind}
+        title={emojisDef.label}
+        icon={sidebarItemIcon("emojis", "size-5")}
+        onFabClick={() => setComposeOpen(true)}
+      />
+      {composeOpen && (
+        <Suspense fallback={null}>
+          <EmojiPackDialog open={composeOpen} onOpenChange={setComposeOpen} />
+        </Suspense>
+      )}
+    </>
+  );
+}
+
 /** Redirects /profile to the user's canonical profile URL (nip05 or npub). */
 function ProfileRedirect() {
  const { user, metadata } = useCurrentUser();
@@ -111,6 +138,8 @@ export function AppRouter() {
  return (
    <AudioPlayerProvider>
      <BrowserRouter>
+        <Toaster />
+        <VersionCheck />
        <MinimizedAudioBar />
        <AudioNavigationGuard />
        <DeepLinkHandler />
@@ -202,16 +231,7 @@ export function AppRouter() {
                />
              }
            />
-            <Route
-              path="/emojis"
-              element={
-                <KindFeedPage
-                  kind={emojisDef.kind}
-                  title={emojisDef.label}
-                  icon={sidebarItemIcon("emojis", "size-5")}
-                />
-              }
-            />
+            <Route path="/emojis" element={<EmojiFeedPage />} />
            <Route
              path="/development"
              element={
@@ -237,6 +257,7 @@ export function AppRouter() {
            <Route path="/bluesky" element={<BlueskyPage />} />
            <Route path="/wikipedia" element={<WikipediaPage />} />
            <Route path="/letters" element={<LettersPage />} />
+            <Route path="/letters/compose" element={<LetterComposePage />} />
            <Route path="/settings/letters" element={<LetterPreferencesPage />} />
            <Route path="/help" element={<HelpPage />} />
            <Route path="/privacy" element={<PrivacyPolicyPage />} />
@@ -249,6 +270,8 @@ export function AppRouter() {
            />
            <Route path="/i/*" element={<ExternalContentPage />} />

+            {/* Callback target for remote signers (e.g. Amber, Primal) after NIP-46 approval */}
+            <Route path="/remoteloginsuccess" element={<RemoteLoginSuccessPage />} />
            {/* NIP-19 route for npub1, note1, naddr1, nevent1, nprofile1 */}
            <Route path="/:nip19" element={<NIP19Page />} />
            {/* ADD ALL CUSTOM ROUTES ABOVE THE CATCH-ALL "*" ROUTE */}
@@ -15,7 +15,7 @@ import { Button } from '@/components/ui/button';
 import { Badge } from '@/components/ui/badge';
 import { Input } from '@/components/ui/input';

-import type { BlobbiCompanion, BlobbonautProfile } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile } from '@/blobbi/core/lib/blobbi';
 import { cn } from '@/lib/utils';

 import {
@@ -11,7 +11,7 @@ import {
 } from '@/components/ui/dialog';
 import { Button } from '@/components/ui/button';

-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';
 import type { InventoryAction, DirectAction } from '../lib/blobbi-action-utils';

 interface BlobbiActionsModalProps {
@@ -27,7 +27,7 @@ import {
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
 import { useState } from 'react';

-import type { BlobbiCompanion, BlobbonautProfile } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile } from '@/blobbi/core/lib/blobbi';
 import type { NostrEvent } from '@nostrify/nostrify';
 import type { HatchTasksResult } from '../hooks/useHatchTasks';
 import type { EvolveTasksResult } from '../hooks/useEvolveTasks';
@@ -7,6 +7,7 @@

 import { ExternalLink, Check, Loader2, ChevronRight } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
+import { openUrl } from '@/lib/downloadFile';

 import { Button } from '@/components/ui/button';
 import { Progress } from '@/components/ui/progress';
@@ -48,7 +49,7 @@ function TaskRow({ task, onOpenPostModal }: TaskRowProps) {
        navigate(task.actionTarget);
        break;
      case 'external_link':
-        window.open(task.actionTarget, '_blank', 'noopener,noreferrer');
+        openUrl(task.actionTarget);
        break;
      case 'open_modal':
        if (task.actionTarget === 'blobbi_post') {
@@ -9,14 +9,14 @@ import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover
 import { cn } from '@/lib/utils';

 import { useAudioPlayback } from '../hooks/useAudioPlayback';
-import type { AudioSource } from './PlayMusicModal';
+import type { SelectedTrack } from './PlayMusicModal';

 // Re-export for external use
-export type { AudioSource as MusicTrackSource } from './PlayMusicModal';
+export type { SelectedTrack } from './PlayMusicModal';

 interface InlineMusicPlayerProps {
-  /** The selected track source */
-  source: AudioSource;
+  /** The selected track */
+  selection: SelectedTrack;
  /** Called when user wants to change the track */
  onChangeTrack: () => void;
  /** Called when user closes the player */
@@ -34,7 +34,7 @@ interface InlineMusicPlayerProps {
 // ─── Component ────────────────────────────────────────────────────────────────

 export function InlineMusicPlayer({
-  source,
+  selection,
  onChangeTrack,
  onClose,
  onPlaybackStart,
@@ -64,20 +64,20 @@ export function InlineMusicPlayer({
  // that requires explicit user action (play button) to restart
  useEffect(() => {
    if (isPublished && playbackState === 'idle') {
-      load(source.url, true);
+      load(selection.url, true);
      onPlaybackStart?.();
    }
-  }, [isPublished, playbackState, source.url, load, onPlaybackStart]);
+  }, [isPublished, playbackState, selection.url, load, onPlaybackStart]);
  
  // Force reload when source URL changes while already playing/paused
  useEffect(() => {
    // Only trigger reload if we're in an active playback state with a different URL
    if (isPublished && (playbackState === 'playing' || playbackState === 'paused')) {
      // The load function will check if URL changed and reload if needed
-      load(source.url, true);
+      load(selection.url, true);
    }
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- Only react to source.url changes
-  }, [source.url]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- Only react to selection.url changes
+  }, [selection.url]);
  
  // Notify on playback state changes
  useEffect(() => {
@@ -99,20 +99,15 @@ export function InlineMusicPlayer({
  // Handle play/pause toggle
  const handleToggle = useCallback(async () => {
    if (playbackState === 'idle' || playbackState === 'stopped') {
-      load(source.url, true);
+      load(selection.url, true);
    } else {
      await toggle();
    }
-  }, [playbackState, source.url, load, toggle]);
+  }, [playbackState, selection.url, load, toggle]);
  
-  // Track title
-  const trackTitle = source.type === 'builtin' 
-    ? source.track?.title ?? 'Unknown Track'
-    : source.file?.name ?? 'Uploaded Track';
-  
-  const trackArtist = source.type === 'builtin'
-    ? source.track?.artist
-    : undefined;
+  // Track info
+  const trackTitle = selection.track.title;
+  const trackArtist = selection.track.artist;
  
  const isLoading = playbackState === 'loading' || isPublishing;
  const hasError = playbackState === 'error';
@@ -1,7 +1,7 @@
 // src/blobbi/actions/components/PlayMusicModal.tsx

 import { useState, useRef, useCallback, useEffect } from 'react';
-import { Music, Upload, Play, Pause, Check, Loader2, Volume2, X, AlertCircle } from 'lucide-react';
+import { Music, Play, Pause, Check, Loader2, Volume2, AlertCircle } from 'lucide-react';

 import {
  Dialog,
@@ -10,30 +10,29 @@ import {
  DialogTitle,
 } from '@/components/ui/dialog';
 import { Button } from '@/components/ui/button';
-import { Badge } from '@/components/ui/badge';
-import { Tabs, TabsContent, TabsList, TabsTrigger } from '@/components/ui/tabs';
 import { cn } from '@/lib/utils';

 import {
-  getAllBuiltInTracks,
+  getAllTracks,
  formatTrackDuration,
-  type BuiltInTrack,
-} from '../lib/blobbi-builtin-tracks';
+  type BlobbiTrack,
+} from '../lib/blobbi-track-catalog';

 // ─── Types ────────────────────────────────────────────────────────────────────

 /**
- * Audio source for the music player
+ * Selected track for the music player
 */
-export type AudioSource = 
-  | { type: 'builtin'; track: BuiltInTrack; url: string }
-  | { type: 'uploaded'; file: File; url: string };
+export interface SelectedTrack {
+  track: BlobbiTrack;
+  url: string;
+}

 interface PlayMusicModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
-  /** Called with the selected audio source when user confirms */
-  onConfirm: (source: AudioSource) => void;
+  /** Called with the selected track when user confirms */
+  onConfirm: (selection: SelectedTrack) => void;
  isLoading: boolean;
 }

@@ -45,102 +44,53 @@ export function PlayMusicModal({
  onConfirm,
  isLoading,
 }: PlayMusicModalProps) {
-  const [selectedSource, setSelectedSource] = useState<AudioSource | null>(null);
+  const [selectedTrack, setSelectedTrack] = useState<SelectedTrack | null>(null);
  const [isPlaying, setIsPlaying] = useState(false);
-  const [uploadError, setUploadError] = useState<string | null>(null);
-  const [builtInError, setBuiltInError] = useState<string | null>(null);
+  const [error, setError] = useState<string | null>(null);
  const audioRef = useRef<HTMLAudioElement | null>(null);
-  const fileInputRef = useRef<HTMLInputElement>(null);
  
-  const builtInTracks = getAllBuiltInTracks();
+  // Track the current audio source URL to detect changes
+  const currentAudioUrlRef = useRef<string | null>(null);
  
-  // Cleanup audio on unmount or modal close
+  const tracks = getAllTracks();
+  
+  // Cleanup audio on unmount
  useEffect(() => {
    return () => {
      if (audioRef.current) {
        audioRef.current.pause();
        audioRef.current = null;
      }
-      // Revoke object URL if it was an uploaded file
-      if (selectedSource?.type === 'uploaded') {
-        URL.revokeObjectURL(selectedSource.url);
-      }
    };
-  }, [selectedSource]);
+  }, []);
  
  // Reset state when modal opens
  useEffect(() => {
    if (open) {
-      setSelectedSource(null);
+      setSelectedTrack(null);
      setIsPlaying(false);
-      setUploadError(null);
-      setBuiltInError(null);
+      setError(null);
      currentAudioUrlRef.current = null;
    }
  }, [open]);
  
-  // Handle selecting a built-in track
-  const handleSelectBuiltIn = useCallback((track: BuiltInTrack) => {
+  // Handle selecting a track
+  const handleSelectTrack = useCallback((track: BlobbiTrack) => {
    // Stop current playback
    if (audioRef.current) {
      audioRef.current.pause();
      setIsPlaying(false);
    }
    
-    // Revoke previous URL if uploaded
-    if (selectedSource?.type === 'uploaded') {
-      URL.revokeObjectURL(selectedSource.url);
-    }
-    
-    setSelectedSource({ type: 'builtin', track, url: track.path });
-    setBuiltInError(null);
-  }, [selectedSource]);
-  
-  // Handle file upload
-  const handleFileUpload = useCallback((e: React.ChangeEvent<HTMLInputElement>) => {
-    const file = e.target.files?.[0];
-    if (!file) return;
-    
-    // Validate file type
-    const validTypes = ['audio/mpeg', 'audio/mp3', 'audio/wav', 'audio/ogg', 'audio/m4a', 'audio/mp4'];
-    if (!validTypes.includes(file.type) && !file.name.match(/\.(mp3|wav|ogg|m4a)$/i)) {
-      setUploadError('Please upload an MP3, WAV, OGG, or M4A file.');
-      return;
-    }
-    
-    // Validate file size (max 10MB)
-    const maxSize = 10 * 1024 * 1024;
-    if (file.size > maxSize) {
-      setUploadError('File is too large. Maximum size is 10MB.');
-      return;
-    }
-    
-    // Stop current playback
-    if (audioRef.current) {
-      audioRef.current.pause();
-      setIsPlaying(false);
-    }
-    
-    // Revoke previous URL if uploaded
-    if (selectedSource?.type === 'uploaded') {
-      URL.revokeObjectURL(selectedSource.url);
-    }
-    
-    const url = URL.createObjectURL(file);
-    setSelectedSource({ type: 'uploaded', file, url });
-    setUploadError(null);
-  }, [selectedSource]);
-  
-  // Track the current audio source URL to detect changes
-  const currentAudioUrlRef = useRef<string | null>(null);
+    setSelectedTrack({ track, url: track.url });
+    setError(null);
+  }, []);
  
  // Handle play/pause preview
  const handleTogglePlay = useCallback(() => {
-    if (!selectedSource) return;
+    if (!selectedTrack) return;
    
-    const audioUrl = selectedSource.type === 'builtin' 
-      ? selectedSource.track.path 
-      : selectedSource.url;
+    const audioUrl = selectedTrack.url;
    
    // Check if we need to create a new Audio instance (source changed or first time)
    const needsNewAudio = !audioRef.current || currentAudioUrlRef.current !== audioUrl;
@@ -159,9 +109,7 @@ export function PlayMusicModal({
      
      audioRef.current.onended = () => setIsPlaying(false);
      audioRef.current.onerror = () => {
-        if (selectedSource.type === 'builtin') {
-          setBuiltInError('This track is not available yet. Try uploading your own music!');
-        }
+        setError('Failed to load this track. Please try another one.');
        setIsPlaying(false);
      };
    }
@@ -173,26 +121,24 @@ export function PlayMusicModal({
    } else {
      // Start playback (either new source or resuming)
      audioRef.current?.play().catch(() => {
-        if (selectedSource.type === 'builtin') {
-          setBuiltInError('This track is not available yet. Try uploading your own music!');
-        }
+        setError('Failed to play this track. Please try another one.');
        setIsPlaying(false);
      });
      setIsPlaying(true);
    }
-  }, [selectedSource, isPlaying]);
+  }, [selectedTrack, isPlaying]);
  
  // Handle confirm
  const handleConfirm = useCallback(() => {
-    if (!selectedSource) return;
+    if (!selectedTrack) return;
    
    // Stop playback
    if (audioRef.current) {
      audioRef.current.pause();
      setIsPlaying(false);
    }
-    onConfirm(selectedSource);
-  }, [selectedSource, onConfirm]);
+    onConfirm(selectedTrack);
+  }, [selectedTrack, onConfirm]);
  
  // Handle close
  const handleClose = useCallback((isOpen: boolean) => {
@@ -202,12 +148,6 @@ export function PlayMusicModal({
    }
    onOpenChange(isOpen);
  }, [onOpenChange]);
-  
-  const selectedName = selectedSource?.type === 'builtin' 
-    ? selectedSource.track.title 
-    : selectedSource?.type === 'uploaded'
-    ? selectedSource.file.name
-    : null;

  return (
    <Dialog open={open} onOpenChange={handleClose}>
@@ -227,116 +167,32 @@ export function PlayMusicModal({
          </div>
        </DialogHeader>

-        {/* Content */}
+        {/* Content - Track List */}
        <div className="flex-1 overflow-y-auto px-6 py-4">
-          <Tabs defaultValue="builtin" className="w-full">
-            <TabsList className="grid w-full grid-cols-2">
-              <TabsTrigger value="builtin">Built-in</TabsTrigger>
-              <TabsTrigger 
-                value="upload" 
-                disabled
-                className="gap-1.5 data-[disabled]:opacity-50 data-[disabled]:cursor-not-allowed"
-              >
-                Upload
-                <Badge variant="secondary" className="text-[10px] px-1 py-0 h-4 font-normal">
-                  Soon
-                </Badge>
-              </TabsTrigger>
-            </TabsList>
-            
-            {/* Built-in Tracks Tab */}
-            <TabsContent value="builtin" className="mt-4">
-              <div className="grid gap-2">
-                {builtInTracks.map((track) => (
-                  <TrackRow
-                    key={track.id}
-                    track={track}
-                    isSelected={selectedSource?.type === 'builtin' && selectedSource.track.id === track.id}
-                    onSelect={() => handleSelectBuiltIn(track)}
-                  />
-                ))}
+          <div className="grid gap-2">
+            {tracks.map((track) => (
+              <TrackRow
+                key={track.id}
+                track={track}
+                isSelected={selectedTrack?.track.id === track.id}
+                onSelect={() => handleSelectTrack(track)}
+              />
+            ))}
+          </div>
+          {error && (
+            <div className="mt-4 p-3 rounded-lg bg-amber-500/10 border border-amber-500/30">
+              <div className="flex items-start gap-2">
+                <AlertCircle className="size-4 text-amber-500 mt-0.5 shrink-0" />
+                <p className="text-sm text-amber-600 dark:text-amber-400">{error}</p>
              </div>
-              {builtInError && (
-                <div className="mt-4 p-3 rounded-lg bg-amber-500/10 border border-amber-500/30">
-                  <div className="flex items-start gap-2">
-                    <AlertCircle className="size-4 text-amber-500 mt-0.5 shrink-0" />
-                    <p className="text-sm text-amber-600 dark:text-amber-400">{builtInError}</p>
-                  </div>
-                </div>
-              )}
-            </TabsContent>
-            
-            {/* Upload Tab */}
-            <TabsContent value="upload" className="mt-4">
-              <div className="space-y-4">
-                {/* Upload Area */}
-                <button
-                  type="button"
-                  onClick={() => fileInputRef.current?.click()}
-                  className={cn(
-                    "w-full p-8 rounded-xl border-2 border-dashed transition-colors",
-                    "hover:border-primary/50 hover:bg-primary/5",
-                    "flex flex-col items-center justify-center gap-3",
-                    selectedSource?.type === 'uploaded' 
-                      ? "border-primary/30 bg-primary/5" 
-                      : "border-border"
-                  )}
-                >
-                  <div className="size-12 rounded-full bg-muted flex items-center justify-center">
-                    <Upload className="size-6 text-muted-foreground" />
-                  </div>
-                  <div className="text-center">
-                    <p className="font-medium">Upload Audio File</p>
-                    <p className="text-sm text-muted-foreground">
-                      MP3, WAV, OGG, M4A (max 10MB)
-                    </p>
-                  </div>
-                </button>
-                
-                <input
-                  ref={fileInputRef}
-                  type="file"
-                  accept="audio/*"
-                  onChange={handleFileUpload}
-                  className="hidden"
-                />
-                
-                {/* Upload Error */}
-                {uploadError && (
-                  <div className="p-3 rounded-lg bg-destructive/10 border border-destructive/30">
-                    <div className="flex items-start gap-2">
-                      <X className="size-4 text-destructive mt-0.5 shrink-0" />
-                      <p className="text-sm text-destructive">{uploadError}</p>
-                    </div>
-                  </div>
-                )}
-                
-                {/* Uploaded File Display */}
-                {selectedSource?.type === 'uploaded' && (
-                  <div className="p-4 rounded-xl border bg-card/60">
-                    <div className="flex items-center gap-3">
-                      <div className="size-10 rounded-lg bg-primary/10 flex items-center justify-center">
-                        <Music className="size-5 text-primary" />
-                      </div>
-                      <div className="flex-1 min-w-0">
-                        <p className="font-medium truncate">{selectedSource.file.name}</p>
-                        <p className="text-sm text-muted-foreground">
-                          {(selectedSource.file.size / 1024 / 1024).toFixed(2)} MB
-                        </p>
-                      </div>
-                      <Check className="size-5 text-primary shrink-0" />
-                    </div>
-                  </div>
-                )}
-              </div>
-            </TabsContent>
-          </Tabs>
+            </div>
+          )}
        </div>

        {/* Footer */}
        <div className="px-6 py-4 border-t bg-muted/30">
          {/* Preview Controls */}
-          {selectedSource && (
+          {selectedTrack && (
            <div className="mb-4 p-3 rounded-lg bg-card border">
              <div className="flex items-center gap-3">
                <Button
@@ -352,7 +208,7 @@ export function PlayMusicModal({
                  )}
                </Button>
                <div className="flex-1 min-w-0">
-                  <p className="font-medium truncate text-sm">{selectedName}</p>
+                  <p className="font-medium truncate text-sm">{selectedTrack.track.title}</p>
                  <p className="text-xs text-muted-foreground">
                    {isPlaying ? 'Now playing...' : 'Click to preview'}
                  </p>
@@ -376,7 +232,7 @@ export function PlayMusicModal({
            </Button>
            <Button
              onClick={handleConfirm}
-              disabled={!selectedSource || isLoading}
+              disabled={!selectedTrack || isLoading}
              className="flex-1"
            >
              {isLoading ? (
@@ -401,7 +257,7 @@ export function PlayMusicModal({
 // ─── Track Row Component ──────────────────────────────────────────────────────

 interface TrackRowProps {
-  track: BuiltInTrack;
+  track: BlobbiTrack;
  isSelected: boolean;
  onSelect: () => void;
 }
@@ -22,7 +22,7 @@ import {
  AlertDialogTitle,
 } from '@/components/ui/alert-dialog';

-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';

 // ─── Types ────────────────────────────────────────────────────────────────────

@@ -26,7 +26,7 @@ import {
  AlertDialogTitle,
 } from '@/components/ui/alert-dialog';

-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';
 import type { StartIncubationMode } from '../hooks/useBlobbiIncubation';

 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -8,6 +8,7 @@

 import { ExternalLink, Check, Loader2, ChevronRight, AlertCircle } from 'lucide-react';
 import { useNavigate } from 'react-router-dom';
+import { openUrl } from '@/lib/downloadFile';

 import { Button } from '@/components/ui/button';
 import { Progress } from '@/components/ui/progress';
@@ -62,7 +63,7 @@ function TaskRow({ task, onOpenPostModal }: TaskRowProps) {
        navigate(task.actionTarget);
        break;
      case 'external_link':
-        window.open(task.actionTarget, '_blank', 'noopener,noreferrer');
+        openUrl(task.actionTarget);
        break;
      case 'open_modal':
        if (task.actionTarget === 'blobbi_post') {
@@ -17,7 +17,7 @@
 */

 import { useMemo } from 'react';
-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';
 import type { HatchTask, HatchTasksResult } from './useHatchTasks';
 import type { EvolveTasksResult } from './useEvolveTasks';
 import { HATCH_REQUIRED_INTERACTIONS } from './useHatchTasks';
@@ -23,8 +23,8 @@ import type { NostrEvent } from '@nostrify/nostrify';
 import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';

-import type { BlobbiCompanion } from '@/lib/blobbi';
-import { KIND_BLOBBI_STATE, updateBlobbiTags } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';
+import { KIND_BLOBBI_STATE, updateBlobbiTags } from '@/blobbi/core/lib/blobbi';

 import { getStreakTagUpdates, calculateStreakUpdate, type StreakUpdateResult } from '../lib/blobbi-streak';

@@ -6,12 +6,12 @@ import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBI_STATE,
  updateBlobbiTags,
-} from '@/lib/blobbi';
-import { applyBlobbiDecay } from '@/lib/blobbi-decay';
+} from '@/blobbi/core/lib/blobbi';
+import { applyBlobbiDecay } from '@/blobbi/core/lib/blobbi-decay';
 import {
  clampStat,
  applyStat,
@@ -22,6 +22,7 @@ import {
 import { trackMultipleDailyMissionActions } from '../lib/daily-mission-tracker';
 import type { DailyMissionAction } from '../lib/daily-missions';
 import { getStreakTagUpdates } from '../lib/blobbi-streak';
+import { calculateActionXP, applyXPGain, formatXPGain } from '../lib/blobbi-xp';
 import { HATCH_REQUIRED_INTERACTIONS } from './useHatchTasks';
 import { EVOLVE_REQUIRED_INTERACTIONS } from './useEvolveTasks';

@@ -50,6 +51,8 @@ export interface DirectActionRequest {
 export interface DirectActionResult {
  action: DirectAction;
  happinessChange: number;
+  xpGained: number;
+  newXP: number;
 }

 /**
@@ -129,6 +132,9 @@ export function useBlobbiDirectAction({
      const happinessDelta = DIRECT_ACTION_HAPPINESS_EFFECTS[action];
      const newHappiness = applyStat(statsAfterDecay.happiness, happinessDelta);
      
+      // Track if happiness actually changed
+      const happinessChanged = newHappiness !== statsAfterDecay.happiness;
+      
      // Build stats update
      const isEgg = canonical.companion.stage === 'egg';
      const statsUpdate: Record<string, string> = {
@@ -161,9 +167,16 @@ export function useBlobbiDirectAction({
      // Get streak updates (will only update if needed based on day)
      const streakUpdates = getStreakTagUpdates(canonical.companion) ?? {};
      
+      // ─── Apply XP Gain (ONLY if happiness actually changed) ───
+      // Direct actions modify happiness. Only grant XP if happiness actually increased.
+      const xpGained = happinessChanged ? calculateActionXP(action) : 0;
+      const currentXP = canonical.companion.experience ?? 0;
+      const newXP = applyXPGain(currentXP, xpGained);
+      
      const blobbiTags = updateBlobbiTags(updatedTags, {
        ...statsUpdate,
        ...streakUpdates,
+        experience: newXP.toString(),
        last_interaction: nowStr,
        last_decay_at: nowStr,
      });
@@ -185,13 +198,16 @@ export function useBlobbiDirectAction({
      return {
        action,
        happinessChange: happinessDelta,
+        xpGained,
+        newXP,
      };
    },
-    onSuccess: ({ action, happinessChange }) => {
+    onSuccess: ({ action, happinessChange, xpGained }) => {
      const actionMeta = DIRECT_ACTION_METADATA[action];
+      const xpText = formatXPGain(xpGained);
      toast({
        title: `${actionMeta.label} complete!`,
-        description: `Your Blobbi's happiness increased by ${happinessChange}!`,
+        description: `Your Blobbi's happiness increased by ${happinessChange}! ${xpText}`,
      });

      // Track daily mission progress
@@ -21,12 +21,12 @@ import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

-import type { BlobbiCompanion, BlobbonautProfile } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBI_STATE,
  updateBlobbiTags,
-} from '@/lib/blobbi';
-import { applyBlobbiDecay } from '@/lib/blobbi-decay';
+} from '@/blobbi/core/lib/blobbi';
+import { applyBlobbiDecay } from '@/blobbi/core/lib/blobbi-decay';

 // ─── Types ────────────────────────────────────────────────────────────────────

@@ -62,7 +62,7 @@ export interface UseStartIncubationParams {
    allTags: string[][];
    wasMigrated: boolean;
    profileAllTags: string[][];
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
  } | null>;
  /** Update companion event in local cache */
  updateCompanionEvent: (event: NostrEvent) => void;
@@ -325,7 +325,7 @@ export interface UseStopIncubationParams {
    allTags: string[][];
    wasMigrated: boolean;
    profileAllTags: string[][];
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
  } | null>;
  /** Update companion event in local cache */
  updateCompanionEvent: (event: NostrEvent) => void;
@@ -476,7 +476,7 @@ export interface UseStartEvolutionParams {
    allTags: string[][];
    wasMigrated: boolean;
    profileAllTags: string[][];
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
  } | null>;
  /** Update companion event in local cache */
  updateCompanionEvent: (event: NostrEvent) => void;
@@ -627,7 +627,7 @@ export interface UseStopEvolutionParams {
    allTags: string[][];
    wasMigrated: boolean;
    profileAllTags: string[][];
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
  } | null>;
  /** Update companion event in local cache */
  updateCompanionEvent: (event: NostrEvent) => void;
@@ -780,7 +780,7 @@ export interface UseSyncTaskCompletionsParams {
    allTags: string[][];
    wasMigrated: boolean;
    profileAllTags: string[][];
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
  } | null>;
  /** Update companion event in local cache */
  updateCompanionEvent: (event: NostrEvent) => void;
@@ -19,14 +19,14 @@ import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

-import type { BlobbiCompanion, BlobbonautProfile, BlobbiStage } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile, BlobbiStage } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBI_STATE,
+  STAT_MAX,
  updateBlobbiTags,
-  DEFAULT_EGG_STATS,
-} from '@/lib/blobbi';
-import { applyBlobbiDecay } from '@/lib/blobbi-decay';
-import { validateAndRepairBlobbiTags } from '@/lib/blobbi-tag-schema';
+} from '@/blobbi/core/lib/blobbi';
+import { applyBlobbiDecay } from '@/blobbi/core/lib/blobbi-decay';
+import { validateAndRepairBlobbiTags } from '@/blobbi/core/lib/blobbi-tag-schema';
 import { getStreakTagUpdates } from '../lib/blobbi-streak';

 // ─── Content Helpers ──────────────────────────────────────────────────────────
@@ -56,7 +56,7 @@ export interface CanonicalActionResult {
  /** Latest profile tags after migration */
  profileAllTags: string[][];
  /** Latest profile storage after migration */
-  profileStorage: import('@/lib/blobbi').StorageItem[];
+  profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
 }

 /**
@@ -157,14 +157,13 @@ export function useBlobbiHatch({
      });

      // ─── Calculate Baby Stats ───
-      // Baby inherits the decayed health from the egg
-      // Other stats start fresh at 100 for the new life stage
+      // All stats reset to 100 when hatching — the baby starts fresh
      const babyStats = {
-        hunger: DEFAULT_EGG_STATS.hunger,      // Start full
-        happiness: DEFAULT_EGG_STATS.happiness, // Start happy
-        health: decayResult.stats.health,       // Inherit from egg
-        hygiene: DEFAULT_EGG_STATS.hygiene,    // Start clean
-        energy: DEFAULT_EGG_STATS.energy,      // Start energized
+        hunger: STAT_MAX,
+        happiness: STAT_MAX,
+        health: STAT_MAX,
+        hygiene: STAT_MAX,
+        energy: STAT_MAX,
      };

      // ─── Build Updated Tags ───
@@ -6,15 +6,15 @@ import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

-import type { BlobbiCompanion, BlobbonautProfile, BlobbiStats } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile, BlobbiStats } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBI_STATE,
  KIND_BLOBBONAUT_PROFILE,
  updateBlobbiTags,
  updateBlobbonautTags,
  createStorageTags,
-} from '@/lib/blobbi';
-import { applyBlobbiDecay } from '@/lib/blobbi-decay';
+} from '@/blobbi/core/lib/blobbi';
+import { applyBlobbiDecay } from '@/blobbi/core/lib/blobbi-decay';
 import { getShopItemById } from '@/blobbi/shop/lib/blobbi-shop-items';
 import {
  applyItemEffects,
@@ -32,6 +32,7 @@ import {
 import { trackMultipleDailyMissionActions } from '../lib/daily-mission-tracker';
 import type { DailyMissionAction } from '../lib/daily-missions';
 import { getStreakTagUpdates } from '../lib/blobbi-streak';
+import { calculateInventoryActionXP, applyXPGain, formatXPGain } from '../lib/blobbi-xp';
 import { HATCH_REQUIRED_INTERACTIONS } from './useHatchTasks';
 import { EVOLVE_REQUIRED_INTERACTIONS } from './useEvolveTasks';

@@ -52,7 +53,10 @@ export interface UseItemResult {
  itemName: string;
  action: InventoryAction;
  quantity: number;
+  effectiveItemCount: number; // How many items actually changed stats (may be less than quantity due to caps)
  statsChanged: Record<string, number>;
+  xpGained: number;
+  newXP: number;
 }

 /**
@@ -70,7 +74,7 @@ export interface UseBlobbiUseInventoryItemParams {
    /** Latest profile tags after migration (use instead of profile.allTags) */
    profileAllTags: string[][];
    /** Latest profile storage after migration (use instead of profile.storage) */
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
  } | null>;
  /** Update companion event in local cache */
  updateCompanionEvent: (event: NostrEvent) => void;
@@ -186,14 +190,49 @@ export function useBlobbiUseInventoryItem({
      // Start with decayed stats as the base
      const statsAfterDecay = decayResult.stats;
      
+      // ─── Validate Play Energy Requirements ───
+      // For play actions, validate the Blobbi has enough energy AFTER decay
+      if (action === 'play') {
+        const energyCost = Math.abs(shopItem.effect.energy ?? 0);
+        const currentEnergy = statsAfterDecay.energy;
+        
+        if (energyCost > 0 && currentEnergy < energyCost) {
+          throw new Error(
+            `Your Blobbi needs at least ${energyCost} energy to play with this toy (current: ${currentEnergy})`
+          );
+        }
+        
+        // Also check if playing would have any effect at all
+        // If happiness is maxed AND we can't spend energy, playing is pointless
+        const happinessGain = shopItem.effect.happiness ?? 0;
+        const currentHappiness = statsAfterDecay.happiness;
+        const wouldGainHappiness = happinessGain > 0 && currentHappiness < 100;
+        const wouldSpendEnergy = energyCost > 0 && currentEnergy >= energyCost;
+        
+        if (!wouldGainHappiness && !wouldSpendEnergy) {
+          throw new Error(
+            'Playing would have no effect - your Blobbi is already at maximum happiness and has no energy to spend'
+          );
+        }
+      }
+      
      // ─── Apply Item Effects ───
      // Apply effects multiple times (once per quantity) to simulate using items in sequence.
      // This ensures proper clamping at each step, e.g., using 5 health items when at 90 health
      // won't give more than 100 health total.
+      // 
+      // CRITICAL: Track the number of items that actually produced INTENDED stat changes for XP.
+      // XP counting is action-aware - only count positive intended effects, NOT negative side effects:
+      // - feed: count when hunger/energy/health/happiness INCREASE (NOT when hygiene decreases)
+      // - clean: count when hygiene or happiness INCREASES
+      // - medicine: count when health/energy/happiness INCREASE (NOT negative side effects)
+      // - play: EXCEPTION - count when happiness increases OR energy decreases (both are intended effects)
+      //
      // Use canonical companion stage for egg checks
      const isEggCompanion = canonical.companion.stage === 'egg';
      const statsUpdate: Record<string, string> = {};
      const statsChanged: Record<string, number> = {};
+      let effectiveItemCount = 0; // Number of items that produced intended effects

      if (isEggCompanion && action === 'medicine') {
        // Egg medicine handling:
@@ -203,9 +242,15 @@ export function useBlobbiUseInventoryItem({
        
        const healthDelta = shopItem.effect.health ?? 0;
        // Apply health effect N times in sequence with clamping at each step
+        // Only count items that actually INCREASED health (positive effect only)
        let currentHealth = statsAfterDecay.health ?? 0;
        for (let i = 0; i < quantity; i++) {
+          const prevHealth = currentHealth;
          currentHealth = applyStat(currentHealth, healthDelta);
+          // Only count as effective if health increased (not just changed)
+          if (healthDelta > 0 && currentHealth > prevHealth) {
+            effectiveItemCount++;
+          }
        }
        
        statsUpdate.health = currentHealth.toString();
@@ -228,11 +273,20 @@ export function useBlobbiUseInventoryItem({
        const happinessDelta = shopItem.effect.happiness ?? 0;
        
        // Apply effects N times in sequence
+        // Only count items that INCREASED hygiene or happiness (positive effects only)
        let currentHygiene = statsAfterDecay.hygiene ?? 0;
        let currentHappiness = statsAfterDecay.happiness ?? 0;
        for (let i = 0; i < quantity; i++) {
+          const prevHygiene = currentHygiene;
+          const prevHappiness = currentHappiness;
          currentHygiene = applyStat(currentHygiene, hygieneDelta);
          currentHappiness = applyStat(currentHappiness, happinessDelta);
+          // Count as effective if hygiene OR happiness increased (positive effects only)
+          const hygieneIncreased = hygieneDelta > 0 && currentHygiene > prevHygiene;
+          const happinessIncreased = happinessDelta > 0 && currentHappiness > prevHappiness;
+          if (hygieneIncreased || happinessIncreased) {
+            effectiveItemCount++;
+          }
        }
        
        statsUpdate.hygiene = currentHygiene.toString();
@@ -252,9 +306,49 @@ export function useBlobbiUseInventoryItem({
      } else {
        // Normal stats application for baby/adult
        // Apply item effects N times in sequence ON TOP of decayed stats
+        // Use action-aware effectiveness checking for XP calculation
        let currentStats: Partial<BlobbiStats> = { ...statsAfterDecay };
+        const effect = shopItem.effect;
+        
        for (let i = 0; i < quantity; i++) {
-          currentStats = applyItemEffects(currentStats, shopItem.effect);
+          const prevStats = { ...currentStats };
+          currentStats = applyItemEffects(currentStats, effect);
+          
+          // Action-aware effectiveness check:
+          // Only count INTENDED positive effects, not negative side effects
+          let isEffective = false;
+          
+          if (action === 'feed') {
+            // Feed: count when hunger/energy/health/happiness INCREASE
+            // Do NOT count hygiene decrease (that's a side effect)
+            const hungerIncreased = (effect.hunger ?? 0) > 0 && (currentStats.hunger ?? 0) > (prevStats.hunger ?? 0);
+            const energyIncreased = (effect.energy ?? 0) > 0 && (currentStats.energy ?? 0) > (prevStats.energy ?? 0);
+            const healthIncreased = (effect.health ?? 0) > 0 && (currentStats.health ?? 0) > (prevStats.health ?? 0);
+            const happinessIncreased = (effect.happiness ?? 0) > 0 && (currentStats.happiness ?? 0) > (prevStats.happiness ?? 0);
+            isEffective = hungerIncreased || energyIncreased || healthIncreased || happinessIncreased;
+          } else if (action === 'clean') {
+            // Clean: count when hygiene or happiness INCREASES
+            const hygieneIncreased = (effect.hygiene ?? 0) > 0 && (currentStats.hygiene ?? 0) > (prevStats.hygiene ?? 0);
+            const happinessIncreased = (effect.happiness ?? 0) > 0 && (currentStats.happiness ?? 0) > (prevStats.happiness ?? 0);
+            isEffective = hygieneIncreased || happinessIncreased;
+          } else if (action === 'medicine') {
+            // Medicine: count when health/energy/happiness INCREASE
+            // Do NOT count negative side effects (like happiness decrease on Super Medicine)
+            const healthIncreased = (effect.health ?? 0) > 0 && (currentStats.health ?? 0) > (prevStats.health ?? 0);
+            const energyIncreased = (effect.energy ?? 0) > 0 && (currentStats.energy ?? 0) > (prevStats.energy ?? 0);
+            const happinessIncreased = (effect.happiness ?? 0) > 0 && (currentStats.happiness ?? 0) > (prevStats.happiness ?? 0);
+            isEffective = healthIncreased || energyIncreased || happinessIncreased;
+          } else if (action === 'play') {
+            // Play: EXCEPTION - both happiness increase AND energy decrease are intended effects
+            // Playing naturally consumes energy, so energy decrease counts as valid
+            const happinessIncreased = (effect.happiness ?? 0) > 0 && (currentStats.happiness ?? 0) > (prevStats.happiness ?? 0);
+            const energyDecreased = (effect.energy ?? 0) < 0 && (currentStats.energy ?? 0) < (prevStats.energy ?? 0);
+            isEffective = happinessIncreased || energyDecreased;
+          }
+          
+          if (isEffective) {
+            effectiveItemCount++;
+          }
        }

        statsUpdate.hunger = clampStat(currentStats.hunger).toString();
@@ -288,9 +382,18 @@ export function useBlobbiUseInventoryItem({
      // Get streak updates (will only update if needed based on day)
      const streakUpdates = getStreakTagUpdates(canonical.companion) ?? {};
      
+      // ─── Apply XP Gain (Based on effective item count) ───
+      // Only grant XP for items that actually changed stats.
+      // If user used 100 food items but hunger capped at item #4, only 4 items were effective.
+      // This prevents XP farming by mass-using items after stats are already maxed.
+      const xpGained = effectiveItemCount > 0 ? calculateInventoryActionXP(action, effectiveItemCount) : 0;
+      const currentXP = canonical.companion.experience ?? 0;
+      const newXP = applyXPGain(currentXP, xpGained);
+      
      const blobbiTags = updateBlobbiTags(updatedTags, {
        ...statsUpdate,
        ...streakUpdates,
+        experience: newXP.toString(),
        last_interaction: nowStr,
        last_decay_at: nowStr,
      });
@@ -330,15 +433,19 @@ export function useBlobbiUseInventoryItem({
        itemName: shopItem.name,
        action,
        quantity,
+        effectiveItemCount, // How many items actually changed stats
        statsChanged,
+        xpGained,
+        newXP,
      };
    },
-    onSuccess: ({ itemName, action, quantity }) => {
+    onSuccess: ({ itemName, action, quantity, xpGained }) => {
      const actionMeta = ACTION_METADATA[action];
      const quantityText = quantity > 1 ? ` (x${quantity})` : '';
+      const xpText = formatXPGain(xpGained);
      toast({
        title: `${actionMeta.label} successful!`,
-        description: `Used ${itemName}${quantityText} on your Blobbi.`,
+        description: `Used ${itemName}${quantityText} on your Blobbi. ${xpText}`,
      });

      // Track daily mission progress
@@ -14,11 +14,11 @@ import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

-import type { BlobbonautProfile } from '@/lib/blobbi';
+import type { BlobbonautProfile } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBONAUT_PROFILE,
  updateBlobbonautTags,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';
 import {
  type DailyMissionsState,
  getTodayDateString,
@@ -15,7 +15,7 @@ import { useNostr } from '@nostrify/react';
 import type { NostrEvent, NostrFilter } from '@nostrify/nostrify';

 import { useCurrentUser } from '@/hooks/useCurrentUser';
-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';

 import {
  KIND_THEME_DEFINITION,
@@ -5,10 +5,11 @@
 * 
 * CRITICAL ARCHITECTURE:
 * - PERSISTENT TASKS: Based on Nostr events, can be cached in tags
- * - DYNAMIC TASKS: Based on current stats, NEVER stored in tags
 * 
 * Tags are only cache for persistent tasks. Source of truth = Nostr events.
 * All persistent tasks are computed dynamically from events with created_at >= state_started_at.
+ * 
+ * Note: Egg stats no longer decay, so there are no dynamic tasks for hatching.
 */

 import { useQuery } from '@tanstack/react-query';
@@ -16,7 +17,7 @@ import { useNostr } from '@nostrify/react';
 import type { NostrEvent, NostrFilter } from '@nostrify/nostrify';

 import { useCurrentUser } from '@/hooks/useCurrentUser';
-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';

 // ─── Constants ────────────────────────────────────────────────────────────────

@@ -38,9 +39,6 @@ export const BLOBBI_POST_REQUIRED_HASHTAGS = ['blobbi', 'ditto', 'nostr'];
 /** Prefix text for Blobbi hatch post */
 export const BLOBBI_POST_PREFIX = 'Hello Nostr! Posting to hatch';

-/** Stat threshold for hatch dynamic task (health, hygiene, happiness >= 70) */
-export const HATCH_STAT_THRESHOLD = 70;
-
 // Legacy export for backwards compatibility
 export const REQUIRED_INTERACTIONS = HATCH_REQUIRED_INTERACTIONS;

@@ -158,8 +156,8 @@ export const isValidBlobbiPost = isValidHatchPost;
 * 3. Create Post (kind 1) - ≥1 valid Blobbi hatch post after start
 * 4. Interactions - 7 total (tracked via companion.tasks cache)
 * 
- * DYNAMIC TASK (stat-based, NEVER cached):
- * 5. Maintain Stats - health >= 70, hygiene >= 70, happiness >= 70
+ * Note: Egg stats no longer decay, so the "maintain stats" dynamic task
+ * has been removed. The baby/adult evolve equivalent is still in useEvolveTasks.
 * 
 * @param companion - The Blobbi companion (must be incubating)
 * @param interactionCount - Current interaction count from companion tasks cache
@@ -323,32 +321,6 @@ export function useHatchTasks(
    // No action - just interact with Blobbi
  });
  
-  // ─── Compute DYNAMIC Task (stat-based, NEVER cached) ───
-  // 6. Maintain Stats - health >= 70, hygiene >= 70, happiness >= 70
-  const stats = companion?.stats ?? {};
-  const health = stats.health ?? 0;
-  const hygiene = stats.hygiene ?? 0;
-  const happiness = stats.happiness ?? 0;
-  
-  const statsOk = 
-    health >= HATCH_STAT_THRESHOLD &&
-    hygiene >= HATCH_STAT_THRESHOLD &&
-    happiness >= HATCH_STAT_THRESHOLD;
-  
-  // Calculate minimum stat for progress display
-  const minStat = Math.min(health, hygiene, happiness);
-  
-  tasks.push({
-    id: 'maintain_stats',
-    name: 'Keep Egg Healthy',
-    description: `Keep health, hygiene & happiness above ${HATCH_STAT_THRESHOLD}`,
-    current: statsOk ? HATCH_STAT_THRESHOLD : minStat,
-    required: HATCH_STAT_THRESHOLD,
-    completed: statsOk,
-    type: 'dynamic', // CRITICAL: Never persist this task
-    // No action - just care for your Blobbi
-  });
-  
  // ─── Compute Completion States ───
  const persistentTasks = tasks.filter(t => t.type === 'persistent');
  const dynamicTasks = tasks.filter(t => t.type === 'dynamic');
@@ -13,7 +13,6 @@ export { BlobbiPostModal } from './components/BlobbiPostModal';
 export { StartIncubationDialog } from './components/StartIncubationDialog';
 export { StartEvolutionDialog } from './components/StartEvolutionDialog';
 export { BlobbiMissionsModal } from './components/BlobbiMissionsModal';
-export type { AudioSource } from './components/PlayMusicModal';

 // Hooks
 export { useBlobbiUseInventoryItem } from './hooks/useBlobbiUseInventoryItem';
@@ -61,7 +60,6 @@ export {
  KIND_THEME_DEFINITION,
  KIND_COLOR_MOMENT,
  HATCH_REQUIRED_INTERACTIONS,
-  HATCH_STAT_THRESHOLD,
  REQUIRED_INTERACTIONS, // Legacy export
  BLOBBI_POST_PREFIX,
  BLOBBI_POST_REQUIRED_HASHTAGS,
@@ -88,14 +86,14 @@ export type { DirectActionRequest, DirectActionResult, UseBlobbiDirectActionPara
 export { useAudioPlayback } from './hooks/useAudioPlayback';
 export type { PlaybackState, PlaybackError, UseAudioPlaybackOptions, UseAudioPlaybackReturn } from './hooks/useAudioPlayback';

-// Built-in tracks
+// Track catalog
 export { 
-  BLOBBI_BUILTIN_TRACKS,
-  getAllBuiltInTracks,
-  getBuiltInTrackById,
+  BLOBBI_TRACK_CATALOG,
+  getAllTracks,
+  getTrackById,
  formatTrackDuration,
-  type BuiltInTrack,
-} from './lib/blobbi-builtin-tracks';
+  type BlobbiTrack,
+} from './lib/blobbi-track-catalog';

 // Activity state
 export {
@@ -108,11 +106,11 @@ export {
  type SingActivityState,
  type NoActivityState,
  type BlobbiReactionState,
-  type MusicTrackSource,
+  type SelectedTrack,
 } from './lib/blobbi-activity-state';

 // Re-export stat bounds from canonical source
-export { STAT_MIN, STAT_MAX } from '@/lib/blobbi';
+export { STAT_MIN, STAT_MAX } from '@/blobbi/core/lib/blobbi';

 // Utilities
 export {
@@ -1,6 +1,6 @@
 // src/blobbi/actions/lib/blobbi-action-utils.ts

-import { STAT_MIN, STAT_MAX, type BlobbiCompanion, type BlobbiStats, type StorageItem } from '@/lib/blobbi';
+import { STAT_MIN, STAT_MAX, type BlobbiCompanion, type BlobbiStats, type StorageItem } from '@/blobbi/core/lib/blobbi';
 import type { ItemEffect, ShopItemCategory } from '@/blobbi/shop/types/shop.types';
 import { getShopItemById } from '@/blobbi/shop/lib/blobbi-shop-items';

@@ -217,11 +217,6 @@ export function canUseItemForStage(
    return { canUse: true };
  }

-  // Accessories are disabled
-  if (shopItem.type === 'accessory') {
-    return { canUse: false, reason: 'Accessories are not usable yet' };
-  }
-
  return { canUse: true };
 }

@@ -1,6 +1,6 @@
 // src/blobbi/actions/lib/blobbi-activity-state.ts

-import type { AudioSource } from '../components/PlayMusicModal';
+import type { SelectedTrack } from '../components/PlayMusicModal';

 /**
 * Types of inline activities that can be displayed in BlobbiPage
@@ -8,14 +8,14 @@ import type { AudioSource } from '../components/PlayMusicModal';
 export type InlineActivityType = 'none' | 'music' | 'sing';

 // Re-export for convenience
-export type { AudioSource as MusicTrackSource } from '../components/PlayMusicModal';
+export type { SelectedTrack } from '../components/PlayMusicModal';

 /**
 * State for the music inline activity
 */
 export interface MusicActivityState {
  type: 'music';
-  source: AudioSource;
+  selection: SelectedTrack;
  isPublished: boolean;
 }

@@ -54,10 +54,10 @@ export type BlobbiReactionState =
 /**
 * Helper to create a music activity state
 */
-export function createMusicActivity(source: AudioSource): MusicActivityState {
+export function createMusicActivity(selection: SelectedTrack): MusicActivityState {
  return {
    type: 'music',
-    source,
+    selection,
    isPublished: false,
  };
 }
@@ -1,121 +0,0 @@
-// src/blobbi/actions/lib/blobbi-builtin-tracks.ts
-
-/**
- * Built-in music tracks for the Blobbi "Play Music" action.
- * 
- * ## Asset Location
- * 
- * Audio files live in: `public/blobbi/audio/`
- * 
- * In Vite, files in `public/` are served at root paths, so:
- * - `public/blobbi/audio/foo.mp3` → accessible at `/blobbi/audio/foo.mp3`
- * 
- * ## Adding New Tracks
- * 
- * 1. Place the MP3 file in `public/blobbi/audio/`
- * 2. Add a new entry to `BLOBBI_BUILTIN_TRACKS` below
- * 3. Set `path` to `/blobbi/audio/<filename>.mp3`
- * 4. Get the duration: `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 <file>`
- * 
- * ## Supported Formats
- * 
- * MP3 is recommended for maximum browser compatibility.
- * WAV, OGG, and M4A may work but are browser-dependent.
- */
-
-export interface BuiltInTrack {
-  /** Unique identifier for the track (used in state/events) */
-  id: string;
-  /** Display title shown in the UI */
-  title: string;
-  /** Artist or source attribution */
-  artist: string;
-  /** Path to audio file (relative to public directory root) */
-  path: string;
-  /** Duration in seconds (for display, get via ffprobe) */
-  durationSeconds: number;
-  /** Optional cover art path (relative to public directory root) */
-  coverArt?: string;
-  /** Optional tags for categorization/filtering */
-  tags?: string[];
-}
-
-/**
- * Built-in track catalog for Blobbi music player.
- * 
- * All tracks are royalty-free/Creative Commons licensed.
- * Audio files located at: public/blobbi/audio/
- */
-export const BLOBBI_BUILTIN_TRACKS: BuiltInTrack[] = [
-  {
-    id: 'nap_in_the_meadow',
-    title: 'Nap in the Meadow',
-    artist: 'Chilltape FM',
-    path: '/blobbi/audio/chilltapefm-nap-in-the-meadow.mp3',
-    durationSeconds: 240, // 4:00
-    tags: ['relaxing', 'nature'],
-  },
-  {
-    id: 'happy_kids',
-    title: 'Happy Kids',
-    artist: 'Dmitrii Kolesnikov',
-    path: '/blobbi/audio/happy-kids.mp3',
-    durationSeconds: 129, // 2:09
-    tags: ['upbeat', 'fun'],
-  },
-  {
-    id: 'soft_piano',
-    title: 'Soft Piano',
-    artist: 'Dmitrii Kolesnikov',
-    path: '/blobbi/audio/soft-piano.mp3',
-    durationSeconds: 124, // 2:04
-    tags: ['calming', 'sleep'],
-  },
-  {
-    id: 'epic_sacred_light',
-    title: 'Epic Sacred Light',
-    artist: 'Ura Megis',
-    path: '/blobbi/audio/epic-sacred-light.mp3',
-    durationSeconds: 223, // 3:43
-    tags: ['energetic', 'adventure'],
-  },
-  {
-    id: 'split_memmories',
-    title: 'Split Memmories',
-    artist: 'ido berg',
-    path: '/blobbi/audio/split-memmories.mp3',
-    durationSeconds: 153, // 2:33
-    tags: ['ambient', 'relaxing'],
-  },
-  {
-    id: 'minhas_mensagens',
-    title: 'Minhas Mensagens',
-    artist: 'PReis',
-    path: '/blobbi/audio/minhas-mensagens-preis.mp3',
-    durationSeconds: 248, // 4:08
-    tags: ['ambient', 'relaxing'],
-  },
-];
-
-/**
- * Get a built-in track by ID
- */
-export function getBuiltInTrackById(id: string): BuiltInTrack | undefined {
-  return BLOBBI_BUILTIN_TRACKS.find(track => track.id === id);
-}
-
-/**
- * Get all built-in tracks
- */
-export function getAllBuiltInTracks(): BuiltInTrack[] {
-  return BLOBBI_BUILTIN_TRACKS;
-}
-
-/**
- * Format duration in seconds to MM:SS string
- */
-export function formatTrackDuration(seconds: number): string {
-  const mins = Math.floor(seconds / 60);
-  const secs = Math.floor(seconds % 60);
-  return `${mins}:${secs.toString().padStart(2, '0')}`;
-}
@@ -21,7 +21,7 @@ import {
  getLocalDayString,
  getDaysDifference,
  type BlobbiCompanion,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';

 // ─── Types ────────────────────────────────────────────────────────────────────

@@ -0,0 +1,118 @@
+// src/blobbi/actions/lib/blobbi-track-catalog.ts
+
+/**
+ * Blobbi Track Catalog
+ * 
+ * Music tracks for the Blobbi "Play Music" action.
+ * All tracks are hosted on remote Blossom servers and streamed on-demand.
+ * 
+ * ## Adding New Tracks
+ * 
+ * 1. Convert the audio file to M4A (AAC-LC):
+ *    `ffmpeg -i input.m4a -c:a aac -b:a 64k -ar 48000 output.m4a`
+ * 2. Upload the M4A file to a Blossom server
+ * 3. Add a new entry to `BLOBBI_TRACK_CATALOG` below
+ * 4. Set `url` to the full Blossom URL
+ * 5. Get the duration: `ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 <file>`
+ * 
+ * ## Supported Formats
+ * 
+ * M4A (AAC-LC) is required for iOS/Safari compatibility and small file size.
+ */
+
+export interface BlobbiTrack {
+  /** Unique identifier for the track (used in state/events) */
+  id: string;
+  /** Display title shown in the UI */
+  title: string;
+  /** Artist or source attribution */
+  artist: string;
+  /** Full URL to the remote audio file (Blossom server) */
+  url: string;
+  /** Duration in seconds (for display, get via ffprobe) */
+  durationSeconds: number;
+  /** Optional cover art URL */
+  coverArt?: string;
+  /** Optional tags for categorization/filtering */
+  tags?: string[];
+}
+
+/**
+ * Blobbi track catalog.
+ * 
+ * All tracks are royalty-free/Creative Commons licensed.
+ * Audio files hosted on remote Blossom servers.
+ */
+export const BLOBBI_TRACK_CATALOG: BlobbiTrack[] = [
+  {
+    id: 'nap_in_the_meadow',
+    title: 'Nap in the Meadow',
+    artist: 'Chilltape FM',
+    url: 'https://blossom.ditto.pub/6be1c95e879187f83af2a661ccac2bd96196f7bc334af44529ede6270b2811fc.m4a',
+    durationSeconds: 240, // 4:00
+    tags: ['relaxing', 'nature'],
+  },
+  {
+    id: 'happy_kids',
+    title: 'Happy Kids',
+    artist: 'Dmitrii Kolesnikov',
+    url: 'https://blossom.ditto.pub/94d49abd178aa8afb14737a55e0a7143f6b337f618d74858d011232bb2db845d.m4a',
+    durationSeconds: 129, // 2:09
+    tags: ['upbeat', 'fun'],
+  },
+  {
+    id: 'soft_piano',
+    title: 'Soft Piano',
+    artist: 'Dmitrii Kolesnikov',
+    url: 'https://blossom.ditto.pub/5367242d3dc555c77f5c637fd153df1166708a24c5a4c222bb4dcaeabf740743.m4a',
+    durationSeconds: 124, // 2:04
+    tags: ['calming', 'sleep'],
+  },
+  {
+    id: 'epic_sacred_light',
+    title: 'Epic Sacred Light',
+    artist: 'Ura Megis',
+    url: 'https://blossom.dreamith.to/c22953791d686605958165fd44a84cd7d9fd3d4423ebf786e47891ed3a82c6db.m4a',
+    durationSeconds: 223, // 3:43
+    tags: ['energetic', 'adventure'],
+  },
+  {
+    id: 'split_memories',
+    title: 'Split Memories',
+    artist: 'ido berg',
+    url: 'https://blossom.ditto.pub/57ba2e2122a732449880ae531d4bfac9a580bc19693c7dda735afbfa336b35fe.m4a',
+    durationSeconds: 153, // 2:33
+    tags: ['ambient', 'relaxing'],
+  },
+  {
+    id: 'minhas_mensagens',
+    title: 'Minhas Mensagens',
+    artist: 'PReis',
+    url: 'https://blossom.ditto.pub/0945064dc8f946f3392be23629b166e72090cafca7cca865a20b5395dd83ff46.m4a',
+    durationSeconds: 248, // 4:08
+    tags: ['ambient', 'relaxing'],
+  },
+];
+
+/**
+ * Get a track by ID from the catalog
+ */
+export function getTrackById(id: string): BlobbiTrack | undefined {
+  return BLOBBI_TRACK_CATALOG.find(track => track.id === id);
+}
+
+/**
+ * Get all tracks from the catalog
+ */
+export function getAllTracks(): BlobbiTrack[] {
+  return BLOBBI_TRACK_CATALOG;
+}
+
+/**
+ * Format duration in seconds to MM:SS string
+ */
+export function formatTrackDuration(seconds: number): string {
+  const mins = Math.floor(seconds / 60);
+  const secs = Math.floor(seconds % 60);
+  return `${mins}:${secs.toString().padStart(2, '0')}`;
+}
@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+
+import {
+  calculateActionXP,
+  calculateInventoryActionXP,
+  applyXPGain,
+  getXPGainSummary,
+  formatXPGain,
+  getXPGainMessage,
+  ACTION_XP,
+  INVENTORY_ACTION_XP,
+  DIRECT_ACTION_XP,
+} from './blobbi-xp';
+
+describe('calculateActionXP', () => {
+  it('returns the correct XP for each inventory action', () => {
+    expect(calculateActionXP('feed')).toBe(5);
+    expect(calculateActionXP('play')).toBe(8);
+    expect(calculateActionXP('clean')).toBe(6);
+    expect(calculateActionXP('medicine')).toBe(10);
+  });
+
+  it('returns the correct XP for each direct action', () => {
+    expect(calculateActionXP('play_music')).toBe(7);
+    expect(calculateActionXP('sing')).toBe(9);
+  });
+
+  it('returns 0 for an unknown action', () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect(calculateActionXP('unknown' as any)).toBe(0);
+  });
+});
+
+describe('calculateInventoryActionXP', () => {
+  it('returns base XP for quantity 1', () => {
+    expect(calculateInventoryActionXP('feed', 1)).toBe(5);
+    expect(calculateInventoryActionXP('medicine', 1)).toBe(10);
+  });
+
+  it('multiplies XP by quantity', () => {
+    expect(calculateInventoryActionXP('feed', 3)).toBe(15);
+    expect(calculateInventoryActionXP('play', 5)).toBe(40);
+  });
+
+  it('defaults to quantity 1 when not specified', () => {
+    expect(calculateInventoryActionXP('clean')).toBe(6);
+  });
+
+  it('returns 0 for quantity less than 1', () => {
+    expect(calculateInventoryActionXP('feed', 0)).toBe(0);
+    expect(calculateInventoryActionXP('feed', -1)).toBe(0);
+  });
+});
+
+describe('applyXPGain', () => {
+  it('adds XP to a current value', () => {
+    expect(applyXPGain(100, 25)).toBe(125);
+  });
+
+  it('treats undefined current XP as 0', () => {
+    expect(applyXPGain(undefined, 10)).toBe(10);
+  });
+
+  it('never returns a negative value', () => {
+    expect(applyXPGain(5, -20)).toBe(0);
+    expect(applyXPGain(0, -1)).toBe(0);
+  });
+
+  it('handles zero XP gain', () => {
+    expect(applyXPGain(50, 0)).toBe(50);
+  });
+});
+
+describe('getXPGainSummary', () => {
+  it('returns the correct xpGained and quantity', () => {
+    const result = getXPGainSummary('feed', 3);
+    expect(result).toEqual({ xpGained: 15, quantity: 3 });
+  });
+
+  it('defaults quantity to 1', () => {
+    const result = getXPGainSummary('sing');
+    expect(result).toEqual({ xpGained: 9, quantity: 1 });
+  });
+});
+
+describe('formatXPGain', () => {
+  it('formats positive XP as "+N XP"', () => {
+    expect(formatXPGain(15)).toBe('+15 XP');
+    expect(formatXPGain(1)).toBe('+1 XP');
+  });
+
+  it('returns empty string for zero or negative XP', () => {
+    expect(formatXPGain(0)).toBe('');
+    expect(formatXPGain(-5)).toBe('');
+  });
+});
+
+describe('getXPGainMessage', () => {
+  it('formats a message with action and XP earned', () => {
+    expect(getXPGainMessage('feed', 5)).toBe('+5 XP earned!');
+  });
+
+  it('includes total when provided', () => {
+    expect(getXPGainMessage('feed', 5, 105)).toBe('+5 XP earned! Total: 105 XP');
+  });
+
+  it('returns empty string for zero or negative XP', () => {
+    expect(getXPGainMessage('feed', 0)).toBe('');
+    expect(getXPGainMessage('feed', -1)).toBe('');
+  });
+});
+
+describe('XP constants', () => {
+  it('ACTION_XP contains all inventory and direct actions', () => {
+    for (const action of Object.keys(INVENTORY_ACTION_XP)) {
+      expect(ACTION_XP).toHaveProperty(action);
+      expect(ACTION_XP[action as keyof typeof ACTION_XP]).toBe(
+        INVENTORY_ACTION_XP[action as keyof typeof INVENTORY_ACTION_XP],
+      );
+    }
+    for (const action of Object.keys(DIRECT_ACTION_XP)) {
+      expect(ACTION_XP).toHaveProperty(action);
+      expect(ACTION_XP[action as keyof typeof ACTION_XP]).toBe(
+        DIRECT_ACTION_XP[action as keyof typeof DIRECT_ACTION_XP],
+      );
+    }
+  });
+
+  it('all XP values are positive integers', () => {
+    for (const xp of Object.values(ACTION_XP)) {
+      expect(xp).toBeGreaterThan(0);
+      expect(Number.isInteger(xp)).toBe(true);
+    }
+  });
+});
@@ -0,0 +1,138 @@
+/**
+ * Blobbi XP (Experience Points) System
+ * 
+ * This module defines XP values for all Blobbi care actions and provides
+ * utilities for calculating and applying XP gains.
+ * 
+ * Design Philosophy:
+ * - Different actions award different XP to reflect their complexity/value
+ * - XP values are balanced to encourage variety in care activities
+ * - Direct actions (sing, play_music) give moderate XP as they're free
+ * - Inventory actions (feed, play, clean, medicine) give varied XP based on resource cost
+ * - XP accumulates across all life stages and never resets
+ */
+
+import type { BlobbiAction, InventoryAction, DirectAction } from './blobbi-action-utils';
+
+// ─── XP Values by Action ──────────────────────────────────────────────────────
+
+/**
+ * Base XP values for inventory actions (feed, play, clean, medicine).
+ * These actions consume items from the player's storage.
+ */
+export const INVENTORY_ACTION_XP: Record<InventoryAction, number> = {
+  feed: 5,      // Feeding is common and essential - moderate XP
+  play: 8,      // Playing toys provides good interaction - higher XP
+  clean: 6,     // Hygiene maintenance is important - moderate-high XP
+  medicine: 10, // Medicine is costly and critical - highest inventory XP
+};
+
+/**
+ * Base XP values for direct actions (play_music, sing).
+ * These actions don't consume items - they're free activities.
+ */
+export const DIRECT_ACTION_XP: Record<DirectAction, number> = {
+  play_music: 7,  // Playing music is engaging - good XP
+  sing: 9,        // Singing requires more user effort - higher XP
+};
+
+/**
+ * Combined XP lookup for all action types.
+ * Use this for a unified XP calculation interface.
+ */
+export const ACTION_XP: Record<BlobbiAction, number> = {
+  ...INVENTORY_ACTION_XP,
+  ...DIRECT_ACTION_XP,
+};
+
+// ─── XP Calculation Utilities ─────────────────────────────────────────────────
+
+/**
+ * Calculate XP gain for a single action.
+ * 
+ * @param action - The action performed
+ * @returns XP points earned
+ */
+export function calculateActionXP(action: BlobbiAction): number {
+  return ACTION_XP[action] ?? 0;
+}
+
+/**
+ * Calculate total XP gain for using multiple items.
+ * Each item use counts as a separate action for XP purposes.
+ * 
+ * @param action - The action performed
+ * @param quantity - Number of items used (defaults to 1)
+ * @returns Total XP points earned
+ */
+export function calculateInventoryActionXP(action: InventoryAction, quantity: number = 1): number {
+  if (quantity < 1) return 0;
+  const baseXP = INVENTORY_ACTION_XP[action] ?? 0;
+  return baseXP * quantity;
+}
+
+/**
+ * Apply XP gain to current experience value.
+ * 
+ * @param currentXP - Current experience points (undefined = 0)
+ * @param xpGain - XP points to add
+ * @returns New total XP (never negative)
+ */
+export function applyXPGain(currentXP: number | undefined, xpGain: number): number {
+  const current = currentXP ?? 0;
+  const newXP = current + xpGain;
+  return Math.max(0, newXP);
+}
+
+/**
+ * Get XP gain summary for displaying to the user.
+ * 
+ * @param action - The action performed
+ * @param quantity - Number of times the action was performed (for inventory actions)
+ * @returns Object with xpGained and total quantity
+ */
+export function getXPGainSummary(
+  action: BlobbiAction,
+  quantity: number = 1
+): { xpGained: number; quantity: number } {
+  const baseXP = ACTION_XP[action] ?? 0;
+  const xpGained = baseXP * quantity;
+  return { xpGained, quantity };
+}
+
+// ─── XP Display Utilities ─────────────────────────────────────────────────────
+
+/**
+ * Format XP gain for display in toasts/notifications.
+ * 
+ * @param xpGained - Amount of XP gained
+ * @returns Formatted string like "+15 XP"
+ */
+export function formatXPGain(xpGained: number): string {
+  if (xpGained <= 0) return '';
+  return `+${xpGained} XP`;
+}
+
+/**
+ * Get a descriptive message about XP gain.
+ * 
+ * @param action - The action that earned XP
+ * @param xpGained - Amount of XP gained
+ * @param newTotal - New total XP (optional, for "You now have X XP" message)
+ * @returns Formatted message for user feedback
+ */
+export function getXPGainMessage(
+  action: BlobbiAction,
+  xpGained: number,
+  newTotal?: number
+): string {
+  if (xpGained <= 0) return '';
+  
+  const xpText = formatXPGain(xpGained);
+  
+  if (newTotal !== undefined) {
+    return `${xpText} earned! Total: ${newTotal} XP`;
+  }
+  
+  return `${xpText} earned!`;
+}
@@ -1,58 +1,19 @@
 /**
 * Adult Blobbi SVG Customizer
- * 
+ *
 * Handles applying colors and customizations to adult SVG content.
 * Each adult form has different gradient IDs that need color mapping.
- * 
+ *
 * IMPORTANT: Gradients must be preserved for 3D shading effects.
 * We replace gradient colors, not the gradient structure.
+ *
+ * Uses shared utilities from blobbi/ui/lib/svg for common operations.
 */

-import type { Blobbi } from '@/types/blobbi';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
+import { lightenColor, darkenColor, uniquifySvgIds, ensureSvgFillsContainer } from '@/blobbi/ui/lib/svg';
 import type { AdultForm, AdultSvgCustomization } from '../types/adult.types';

-// ─── Color Utilities ──────────────────────────────────────────────────────────
-
-/**
- * Lighten a hex color by a percentage
- */
-function lightenColor(color: string, percent: number): string {
-  if (color.startsWith('#')) {
-    const num = parseInt(color.slice(1), 16);
-    const amt = Math.round(2.55 * percent);
-    const R = (num >> 16) + amt;
-    const G = (num >> 8 & 0x00FF) + amt;
-    const B = (num & 0x0000FF) + amt;
-    return '#' + (
-      0x1000000 +
-      (R < 255 ? (R < 1 ? 0 : R) : 255) * 0x10000 +
-      (G < 255 ? (G < 1 ? 0 : G) : 255) * 0x100 +
-      (B < 255 ? (B < 1 ? 0 : B) : 255)
-    ).toString(16).slice(1).toUpperCase();
-  }
-  return color;
-}
-
-/**
- * Darken a hex color by a percentage
- */
-function darkenColor(color: string, percent: number): string {
-  if (color.startsWith('#')) {
-    const num = parseInt(color.slice(1), 16);
-    const amt = Math.round(2.55 * percent);
-    const R = (num >> 16) - amt;
-    const G = (num >> 8 & 0x00FF) - amt;
-    const B = (num & 0x0000FF) - amt;
-    return '#' + (
-      0x1000000 +
-      (R < 255 ? (R < 1 ? 0 : R) : 255) * 0x10000 +
-      (G < 255 ? (G < 1 ? 0 : G) : 255) * 0x100 +
-      (B < 255 ? (B < 1 ? 0 : B) : 255)
-    ).toString(16).slice(1).toUpperCase();
-  }
-  return color;
-}
-
 // ─── Gradient Builders ────────────────────────────────────────────────────────

 /**
@@ -610,77 +571,6 @@ export function customizeAdultSvg(
  return modifiedSvg;
 }

-/**
- * Ensure SVG has width/height attributes so it fills its container
- */
-function ensureSvgFillsContainer(svgText: string): string {
-  if (/\swidth=/.test(svgText) && /\sheight=/.test(svgText)) {
-    return svgText;
-  }
-
-  return svgText.replace(
-    /<svg([^>]*)>/,
-    '<svg$1 width="100%" height="100%">'
-  );
-}
-
-/**
- * Make all SVG definition IDs unique by prefixing with an instance ID.
- * This prevents gradient ID collisions when multiple Blobbis are rendered on the same page.
- * 
- * Updates both:
- * - Definition IDs: id="gradientName" → id="prefix_gradientName"
- * - References: url(#gradientName) → url(#prefix_gradientName)
- */
-function uniquifySvgIds(svgText: string, instanceId: string): string {
-  // Generate a unique prefix from the full instance ID
-  // Sanitize to only allow valid SVG ID characters (letters, numbers, underscore, hyphen)
-  // Note: instanceId format is "blobbi-{pubkeyPrefix12}-{petId10}" so we need the full ID
-  // to distinguish between Blobbis owned by the same user
-  const prefix = `b_${instanceId.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
-  
-  // Find all IDs defined in the SVG (in defs, gradients, clipPaths, etc.)
-  const idPattern = /\bid=["']([^"']+)["']/g;
-  const ids = new Set<string>();
-  let match;
-  
-  while ((match = idPattern.exec(svgText)) !== null) {
-    ids.add(match[1]);
-  }
-  
-  // Replace each ID and its references
-  let modified = svgText;
-  for (const id of ids) {
-    const prefixedId = `${prefix}_${id}`;
-    
-    // Replace the ID definition
-    modified = modified.replace(
-      new RegExp(`\\bid=["']${id}["']`, 'g'),
-      `id="${prefixedId}"`
-    );
-    
-    // Replace url() references
-    modified = modified.replace(
-      new RegExp(`url\\(#${id}\\)`, 'g'),
-      `url(#${prefixedId})`
-    );
-    
-    // Replace xlink:href references (older SVG format)
-    modified = modified.replace(
-      new RegExp(`xlink:href=["']#${id}["']`, 'g'),
-      `xlink:href="#${prefixedId}"`
-    );
-    
-    // Replace href references (newer SVG format)
-    modified = modified.replace(
-      new RegExp(`\\bhref=["']#${id}["']`, 'g'),
-      `href="#${prefixedId}"`
-    );
-  }
-  
-  return modified;
-}
-
 /**
 * Fallback: Apply generic body gradient for forms without specific customizer
 */
@@ -5,7 +5,7 @@
 * Each adult form has its own folder with base and sleeping variants.
 */

-import type { Blobbi } from '@/types/blobbi';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
 import { 
  type AdultForm, 
  type AdultSvgResolverOptions,
@@ -4,7 +4,7 @@
 * Type definitions for adult stage visuals and customization
 */

-import type { Blobbi } from '@/types/blobbi';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';

 /**
 * All available adult evolution forms.
@@ -1,35 +1,14 @@
 /**
 * Baby Blobbi SVG Customizer
- * 
- * Handles applying colors and customizations to baby SVG content
+ *
+ * Handles applying colors and customizations to baby SVG content.
+ * Uses shared utilities from blobbi/ui/lib/svg for common operations.
 */

-import { Blobbi } from '@/types/blobbi';
+import { Blobbi } from '@/blobbi/core/types/blobbi';
+import { lightenColor, uniquifySvgIds, ensureSvgFillsContainer } from '@/blobbi/ui/lib/svg';
 import { BabySvgCustomization } from '../types/baby.types';

-/**
- * Lighten a color by a percentage
- */
-function lightenColor(color: string, percent: number): string {
-  // Handle hex colors
-  if (color.startsWith('#')) {
-    const num = parseInt(color.slice(1), 16);
-    const amt = Math.round(2.55 * percent);
-    const R = (num >> 16) + amt;
-    const G = (num >> 8 & 0x00FF) + amt;
-    const B = (num & 0x0000FF) + amt;
-    return '#' + (
-      0x1000000 +
-      (R < 255 ? (R < 1 ? 0 : R) : 255) * 0x10000 +
-      (G < 255 ? (G < 1 ? 0 : G) : 255) * 0x100 +
-      (B < 255 ? (B < 1 ? 0 : B) : 255)
-    ).toString(16).slice(1).toUpperCase();
-  }
-  
-  // Return as-is for non-hex colors (rgb, etc.)
-  return color;
-}
-
 /**
 * Apply color customizations to baby SVG
 * 
@@ -78,79 +57,6 @@ export function customizeBabySvg(
  return modifiedSvg;
 }

-/**
- * Ensure SVG has width/height attributes so it fills its container
- */
-function ensureSvgFillsContainer(svgText: string): string {
-  // Check if width and height are already set
-  if (/\swidth=/.test(svgText) && /\sheight=/.test(svgText)) {
-    return svgText;
-  }
-
-  // Add width="100%" height="100%" to the SVG tag
-  return svgText.replace(
-    /<svg([^>]*)>/,
-    '<svg$1 width="100%" height="100%">'
-  );
-}
-
-/**
- * Make all SVG definition IDs unique by prefixing with an instance ID.
- * This prevents gradient ID collisions when multiple Blobbis are rendered on the same page.
- * 
- * Updates both:
- * - Definition IDs: id="gradientName" → id="prefix_gradientName"
- * - References: url(#gradientName) → url(#prefix_gradientName)
- */
-function uniquifySvgIds(svgText: string, instanceId: string): string {
-  // Generate a unique prefix from the full instance ID
-  // Sanitize to only allow valid SVG ID characters (letters, numbers, underscore, hyphen)
-  // Note: instanceId format is "blobbi-{pubkeyPrefix12}-{petId10}" so we need the full ID
-  // to distinguish between Blobbis owned by the same user
-  const prefix = `b_${instanceId.replace(/[^a-zA-Z0-9_-]/g, '_')}`;
-  
-  // Find all IDs defined in the SVG (in defs, gradients, clipPaths, etc.)
-  const idPattern = /\bid=["']([^"']+)["']/g;
-  const ids = new Set<string>();
-  let match;
-  
-  while ((match = idPattern.exec(svgText)) !== null) {
-    ids.add(match[1]);
-  }
-  
-  // Replace each ID and its references
-  let modified = svgText;
-  for (const id of ids) {
-    const prefixedId = `${prefix}_${id}`;
-    
-    // Replace the ID definition
-    modified = modified.replace(
-      new RegExp(`\\bid=["']${id}["']`, 'g'),
-      `id="${prefixedId}"`
-    );
-    
-    // Replace url() references
-    modified = modified.replace(
-      new RegExp(`url\\(#${id}\\)`, 'g'),
-      `url(#${prefixedId})`
-    );
-    
-    // Replace xlink:href references (older SVG format)
-    modified = modified.replace(
-      new RegExp(`xlink:href=["']#${id}["']`, 'g'),
-      `xlink:href="#${prefixedId}"`
-    );
-    
-    // Replace href references (newer SVG format)
-    modified = modified.replace(
-      new RegExp(`\\bhref=["']#${id}["']`, 'g'),
-      `href="#${prefixedId}"`
-    );
-  }
-  
-  return modified;
-}
-
 /**
 * Apply body gradient customization
 */
@@ -4,7 +4,7 @@
 * Handles loading and resolving baby stage SVG assets
 */

-import { Blobbi } from '@/types/blobbi';
+import { Blobbi } from '@/blobbi/core/types/blobbi';
 import { BabyVariant, BabySvgResolverOptions } from '../types/baby.types';
 import { BABY_BASE_SVG, BABY_SLEEPING_SVG } from './baby-svg-data';

@@ -4,7 +4,7 @@
 * Type definitions for baby stage visuals and customization
 */

-import { Blobbi } from '@/types/blobbi';
+import { Blobbi } from '@/blobbi/core/types/blobbi';

 /**
 * Baby visual variant types
@@ -19,6 +19,7 @@ import type {
  Position,
  EntryState,
 } from '../types/companion.types';
+import type { RefObject } from 'react';
 import { DEFAULT_COMPANION_CONFIG } from '../core/companionConfig';
 import { 
  calculateFloatAnimation,
@@ -28,6 +29,9 @@ import {
 } from '../utils/animation';
 import { BlobbiCompanionVisual } from './BlobbiCompanionVisual';
 import { useClickDetection } from '../interaction';
+import type { BlobbiEmotion } from '@/blobbi/ui/lib/emotion-types';
+import type { BlobbiVisualRecipe } from '@/blobbi/ui/lib/recipe';
+import type { BodyEffectsSpec } from '@/blobbi/ui/lib/bodyEffects';

 interface BlobbiCompanionProps {
  /** Companion data */
@@ -36,8 +40,8 @@ interface BlobbiCompanionProps {
  state: CompanionState;
  /** Current motion state */
  motion: CompanionMotion;
-  /** Eye offset for gaze */
-  eyeOffset: EyeOffset;
+  /** Ref-based eye offset for imperative gaze control (avoids per-frame rerenders) */
+  eyeOffsetRef: RefObject<EyeOffset>;
  /** Whether entry animation is playing */
  isEntering: boolean;
  /** Entry animation progress (0-1) */
@@ -58,6 +62,17 @@ interface BlobbiCompanionProps {
  onEndDrag: () => void;
  /** Click callback (when interaction is a click, not a drag) */
  onClick?: () => void;
+  /** Pre-resolved visual recipe. Takes precedence over `emotion`. */
+  recipe?: BlobbiVisualRecipe;
+  /** Label for the recipe (CSS class names). */
+  recipeLabel?: string;
+  /** Named emotion preset (convenience). Ignored when `recipe` is provided. */
+  emotion?: BlobbiEmotion;
+  /**
+   * Body-level visual effects — for manual/external use only.
+   * Status-reaction body effects are already folded into the recipe.
+   */
+  bodyEffects?: BodyEffectsSpec;
  /** Callback to report rendered position (including animations) */
  onPositionUpdate?: (position: Position) => void;
  /** Debug mode - disables animations and shows visual debug aids */
@@ -68,7 +83,7 @@ export function BlobbiCompanion({
  companion,
  state,
  motion,
-  eyeOffset,
+  eyeOffsetRef,
  isEntering,
  entryProgress: _entryProgress,
  entryState,
@@ -79,13 +94,17 @@ export function BlobbiCompanion({
  onUpdateDrag,
  onEndDrag,
  onClick,
+  recipe,
+  recipeLabel,
+  emotion,
+  bodyEffects,
  onPositionUpdate,
  debugMode = false,
 }: BlobbiCompanionProps) {
  const config = DEFAULT_COMPANION_CONFIG;
  const containerRef = useRef<HTMLDivElement>(null);
  const [animationTime, setAnimationTime] = useState(0);
-  
+
  // Click detection - distinguishes click from drag
  const clickDetection = useClickDetection({
    onClick,
@@ -174,8 +193,9 @@ export function BlobbiCompanion({
  }
  
  // Calculate floating animation offset (gentle sway/float)
-  // Skip during entry animation, dragging, or debug mode
-  const floatOffset = (!useEntryPosition && !motion.isDragging && !debugMode)
+  // Skip during entry animation, dragging, debug mode, or sleeping
+  const isSleeping = companion.state === 'sleeping';
+  const floatOffset = (!useEntryPosition && !motion.isDragging && !debugMode && !isSleeping)
    ? calculateFloatAnimation(animationTime, state === 'walking')
    : { x: 0, y: 0, rotation: 0 };
  
@@ -209,12 +229,15 @@ export function BlobbiCompanion({
    : undefined;
  
  // Drag handlers with click detection
+  // Uses pointer events only (handles mouse, touch, and pen natively)
  const handlePointerDown = useCallback((e: React.PointerEvent) => {
-    e.preventDefault();
    e.stopPropagation();
    
-    // Capture pointer for tracking outside element
-    (e.target as HTMLElement).setPointerCapture(e.pointerId);
+    // Capture pointer on the container (not e.target which may be a child)
+    // for reliable tracking across element boundaries during drag
+    if (containerRef.current) {
+      containerRef.current.setPointerCapture(e.pointerId);
+    }
    
    // Start click detection tracking
    clickDetection.handlePointerDown({ x: e.clientX, y: e.clientY });
@@ -235,7 +258,9 @@ export function BlobbiCompanion({
  }, [clickDetection, motion.isDragging, config.size, onUpdateDrag]);
  
  const handlePointerUp = useCallback((e: React.PointerEvent) => {
-    (e.target as HTMLElement).releasePointerCapture(e.pointerId);
+    if (containerRef.current) {
+      containerRef.current.releasePointerCapture(e.pointerId);
+    }
    
    // Finalize click detection - will call onClick if it was a click
    clickDetection.handlePointerUp();
@@ -246,42 +271,6 @@ export function BlobbiCompanion({
    }
  }, [clickDetection, motion.isDragging, onEndDrag]);
  
-  // Touch handlers for mobile (with click detection)
-  const handleTouchStart = useCallback((e: React.TouchEvent) => {
-    e.preventDefault();
-    if (e.touches.length === 0) return;
-    
-    const touch = e.touches[0];
-    clickDetection.handlePointerDown({ x: touch.clientX, y: touch.clientY });
-  }, [clickDetection]);
-  
-  const handleTouchMove = useCallback((e: React.TouchEvent) => {
-    if (e.touches.length === 0) return;
-    
-    const touch = e.touches[0];
-    const position = { x: touch.clientX, y: touch.clientY };
-    
-    // Check if movement exceeds click threshold (starts drag)
-    const isDrag = clickDetection.handlePointerMove(position);
-    
-    // If dragging, update position
-    if (motion.isDragging || isDrag) {
-      const newX = touch.clientX - config.size / 2;
-      const newY = touch.clientY - config.size / 2;
-      onUpdateDrag({ x: newX, y: newY });
-    }
-  }, [clickDetection, motion.isDragging, config.size, onUpdateDrag]);
-  
-  const handleTouchEnd = useCallback(() => {
-    // Finalize click detection
-    clickDetection.handlePointerUp();
-    
-    // Always end drag state
-    if (motion.isDragging) {
-      onEndDrag();
-    }
-  }, [clickDetection, motion.isDragging, onEndDrag]);
-  
  return (
    <div
      ref={containerRef}
@@ -302,20 +291,21 @@ export function BlobbiCompanion({
      onPointerMove={handlePointerMove}
      onPointerUp={handlePointerUp}
      onPointerCancel={handlePointerUp}
-      onTouchStart={handleTouchStart}
-      onTouchMove={handleTouchMove}
-      onTouchEnd={handleTouchEnd}
    >
      <BlobbiCompanionVisual
        companion={companion}
        size={config.size}
-        eyeOffset={eyeOffset}
+        eyeOffsetRef={eyeOffsetRef}
        direction={isEntering ? 'right' : motion.direction}
        isDragging={motion.isDragging}
        isWalking={state === 'walking'}
        floatOffset={floatOffset}
        isOnGround={isOnGround}
        distanceFromGround={distanceFromGround}
+        recipe={recipe}
+        recipeLabel={recipeLabel}
+        emotion={emotion}
+        bodyEffects={bodyEffects}
        debugMode={debugMode}
      />
    </div>
@@ -1,26 +1,31 @@
 /**
- * BlobbiCompanionLayer
- * 
- * Global layer component that renders the companion above all other content.
- * This should be placed at the root level of the app.
- * 
- * Entry animations are VERTICAL based on sidebar navigation direction:
- * - Navigating DOWN the sidebar: Blobbi falls from the top of the screen
- * - Navigating UP the sidebar: Blobbi rises from the bottom with inspection
- * 
- * Interaction features:
- * - Click/tap on Blobbi opens action menu
- * - Action menu shows available actions in a radial layout
- * - Selecting an action shows available items as floating bubbles
+ * BlobbiCompanionLayer — Global orchestration layer for the companion.
+ *
+ * This component is the top-level coordinator. It is NOT a visual component.
+ * It wires together:
+ *   - Companion runtime (position, motion, gaze, entry animations)
+ *   - Status reaction system (stats → visual recipe)
+ *   - Action menu and hanging items interaction
+ *   - Item use with temporary emotion overrides
+ *
+ * Visual rendering is delegated entirely to:
+ *   BlobbiCompanion → BlobbiCompanionVisual → MemoizedBlobbiVisual → Visual → SvgRenderer
+ *
+ * This file should be placed at the app root level (renders a fixed overlay).
 */

-import { useCallback, useState } from 'react';
+import { useCallback, useState, useMemo } from 'react';

 import { useBlobbiCompanion } from '../hooks/useBlobbiCompanion';
 import { useCompanionItemReaction } from '../hooks/useCompanionItemReaction';
+import { useActionEmotionOverride } from '../hooks/useActionEmotionOverride';
 import { BlobbiCompanion } from './BlobbiCompanion';
+import { DebugGroundOverlay } from './DebugGroundOverlay';
 import { DEFAULT_COMPANION_CONFIG } from '../core/companionConfig';
 import { calculateGroundY } from '../utils/movement';
+import { useStatusReaction } from '@/blobbi/ui/hooks/useStatusReaction';
+import { buildSleepingRecipe } from '@/blobbi/ui/lib/recipe';
+import type { ActionType } from '@/blobbi/ui/lib/status-reactions';
 import {
  useCompanionActionMenu,
  useBlobbiActions,
@@ -30,30 +35,19 @@ import {
  type CompanionItem,
  type ItemLandedData,
 } from '../interaction';
+import { useBlobbiSleepToggle } from '../interaction/useBlobbiSleepToggle';
 import type { Position } from '../types/companion.types';

-// DEBUG MODE - Set to true to debug ground contact
+/** Set to true to show debug ground-contact lines. */
 const DEBUG_GROUND_CONTACT = false;

-/**
- * Global companion layer.
- * 
- * Renders the companion if:
- * - User is logged in
- * - User has set a current_companion in their profile
- * - The companion data is loaded
- * 
- * Entry animations are vertical:
- * - Falls from top when navigating DOWN the sidebar
- * - Rises from bottom (with inspection) when navigating UP the sidebar
- */
 export function BlobbiCompanionLayer() {
  const {
    companion,
    isVisible,
    state,
    motion,
-    eyeOffset,
+    eyeOffsetRef,
    isEntering,
    entryProgress,
    entryState,
@@ -65,19 +59,20 @@ export function BlobbiCompanionLayer() {
    endDrag,
    triggerAttention,
  } = useBlobbiCompanion();
-  
+
  const config = DEFAULT_COMPANION_CONFIG;
-  
-  // Track the actual rendered position of the companion
-  // This accounts for entry animations, float offset, etc.
+
+  // ── Rendered position tracking ─────────────────────────────────────────────
+  // Tracks the actual visual position (including entry/float offsets) so
+  // the action menu and hanging items can position relative to Blobbi.
  const [renderedPosition, setRenderedPosition] = useState<Position>(motion.position);
-  
-  // Handle position updates from BlobbiCompanion
+
  const handlePositionUpdate = useCallback((position: Position) => {
    setRenderedPosition(position);
  }, []);
-  
-  // Callback for glancing at items (when Blobbi doesn't need them)
+
+  // ── Item reaction ──────────────────────────────────────────────────────────
+
  const handleGlanceAtItem = useCallback((position: Position) => {
    triggerAttention(position, {
      duration: 800,
@@ -86,39 +81,31 @@ export function BlobbiCompanionLayer() {
      isGlance: true,
    });
  }, [triggerAttention]);
-  
-  // Callback for walking to items (when Blobbi needs them)
-  // For now, we just glance more intensely - full walking behavior 
-  // would require deeper integration with the state machine
+
  const handleWalkToItem = useCallback((position: Position) => {
-    // TODO: Implement actual walking behavior via useBlobbiCompanionState
-    // For now, trigger a longer attention to simulate interest
    triggerAttention(position, {
      duration: 1500,
      priority: 'normal',
      source: 'item-landed:need',
-      isGlance: false, // Use longer cooldown for "interested" attention
+      isGlance: false,
    });
  }, [triggerAttention]);
-  
-  // Item reaction hook - determines if Blobbi needs items and how to react
+
  const { reactToItemLanding } = useCompanionItemReaction({
    isActive: isVisible && !isEntering,
    onGlance: handleGlanceAtItem,
    onWalkTo: handleWalkToItem,
  });
-  
-  // Handle when an item finishes falling and lands on the ground
+
  const handleItemLanded = useCallback((data: ItemLandedData) => {
    if (import.meta.env.DEV) {
      console.log('[CompanionLayer] Item landed:', data.item.name, 'at', { x: data.x, y: data.y });
    }
-    
-    // React to the item landing based on Blobbi's needs
    reactToItemLanding(data.item.category, { x: data.x, y: data.y });
  }, [reactToItemLanding]);
-  
-  // Action menu state
+
+  // ── Action menu ────────────────────────────────────────────────────────────
+
  const {
    menuState,
    availableActions,
@@ -130,57 +117,56 @@ export function BlobbiCompanionLayer() {
    isActive: isVisible,
    stage: companion?.stage,
    onItemClick: (item) => {
-      // Item was clicked in the hanging menu - this releases it
-      console.log('[CompanionLayer] Item released:', item);
+      if (import.meta.env.DEV) {
+        console.log('[CompanionLayer] Item released:', item);
+      }
    },
  });
-  
-  // Get Blobbi actions from context
-  // This now works even when BlobbiPage is not mounted (uses built-in fallback)
-  const { 
-    useItem: contextUseItem, 
-    canUseItems, 
-    isItemOnCooldown 
+
+  const {
+    useItem: contextUseItem,
+    canUseItems,
+    isItemOnCooldown,
  } = useBlobbiActions();
-  
-  /**
-   * Handle item use - called when item contacts Blobbi or is clicked.
-   * Uses the BlobbiActionsContext to perform the actual item use.
-   * Returns success/failure to control whether item is removed from screen.
-   * 
-   * Now works from any page (not just /blobbi) thanks to the built-in
-   * fallback in BlobbiActionsContext.
-   */
+
+  // Standalone sleep/wake toggle — works without BlobbiPage mounted
+  const { toggleSleep } = useBlobbiSleepToggle();
+
+  // ── Item use with emotion override ─────────────────────────────────────────
+
+  const { actionOverride, triggerOverride } = useActionEmotionOverride();
+
  const handleItemUse = useCallback(async (item: CompanionItem): Promise<{ success: boolean; error?: string }> => {
-    // Resolve the action from the item category
    const action = CATEGORY_TO_ACTION[item.category];
-    
+
    if (!action) {
      if (import.meta.env.DEV) {
        console.warn('[CompanionLayer] No action for item category:', item.category);
      }
      return { success: false, error: `Cannot use ${item.category} items` };
    }
-    
+
    if (!canUseItems) {
      if (import.meta.env.DEV) {
        console.warn('[CompanionLayer] Cannot use items - no companion selected');
      }
      return { success: false, error: 'No companion selected' };
    }
-    
+
+    // Trigger the temporary emotion override for visual feedback
+    triggerOverride(action as ActionType);
+
    if (import.meta.env.DEV) {
      console.log('[CompanionLayer] Using item:', item.name, 'with action:', action);
    }
-    
+
    try {
      const result = await contextUseItem(item.id, action, 1);
-      
+
      if (result.success) {
        if (import.meta.env.DEV) {
          console.log('[CompanionLayer] Item used successfully:', item.name, result.statsChanged);
        }
-        // Close the menu after successful use
        closeMenu();
        return { success: true };
      } else {
@@ -196,154 +182,130 @@ export function BlobbiCompanionLayer() {
      }
      return { success: false, error: errorMessage };
    }
-  }, [canUseItems, contextUseItem, closeMenu]);
-  
-  // Handle companion click
+  }, [canUseItems, contextUseItem, closeMenu, triggerOverride]);
+
+  // ── Companion click ────────────────────────────────────────────────────────
+
+  // ── Sleep action (direct, not item-based) ───────────────────────────────────
+
+  const handleSleepAction = useCallback(async () => {
+    closeMenu();
+    try {
+      await toggleSleep();
+    } catch (error) {
+      if (import.meta.env.DEV) {
+        console.error('[CompanionLayer] Sleep toggle failed:', error);
+      }
+    }
+  }, [toggleSleep, closeMenu]);
+
+  /** Intercept action selection: sleep is a direct action, others go through item flow. */
+  const handleActionClick = useCallback((action: Parameters<typeof selectAction>[0]) => {
+    if (action === 'sleep') {
+      handleSleepAction();
+    } else {
+      selectAction(action);
+    }
+  }, [handleSleepAction, selectAction]);
+
  const handleCompanionClick = useCallback(() => {
-    // Don't open menu during entry animation
    if (isEntering) return;
-    
    toggleMenu();
  }, [isEntering, toggleMenu]);
-  
-  // Handle click outside menu
+
  const handleClickOutside = useCallback(() => {
    closeMenu();
  }, [closeMenu]);
-  
-  // Don't render anything if not visible
+
+  // ── Status reaction ────────────────────────────────────────────────────────
+  // Resolves companion stats into a visual recipe (sleepy, hungry, dirty, etc.).
+  // The actionOverride from useActionEmotionOverride temporarily overrides
+  // the recipe when an item is used (e.g., feeding → happy face for 1.5s).
+  //
+  // Status reaction stays ENABLED during sleep so body effects (dirty) and
+  // extras (food icon) still resolve. The sleeping recipe overlay is applied
+  // on top to override the face while preserving compatible body effects.
+
+  const isSleeping = companion?.state === 'sleeping';
+  const companionStats = useMemo(() => companion?.stats ?? {
+    hunger: 100, happiness: 100, health: 100, hygiene: 100, energy: 100,
+  }, [companion?.stats]);
+
+  const { recipe: statusRecipe, recipeLabel: statusRecipeLabel } = useStatusReaction({
+    stats: companionStats,
+    enabled: isVisible && companion?.stage !== 'egg',
+    actionOverride: isSleeping ? null : actionOverride,
+  });
+
+  // When sleeping, overlay the sleeping face on top of the status recipe.
+  // This keeps body effects (dirty, stink) and food icon while overriding
+  // eyes, mouth, and eyebrows with sleeping visuals.
+  const companionRecipe = isSleeping
+    ? buildSleepingRecipe(statusRecipe)
+    : statusRecipe;
+  const companionRecipeLabel = isSleeping ? 'sleeping' : statusRecipeLabel;
+
+  // ── Early return ───────────────────────────────────────────────────────────
+
  if (!isVisible || !companion) {
    return null;
  }
-  
-  // Companion props
-  const companionProps = {
-    companion,
-    state,
-    motion,
-    eyeOffset,
-    isEntering,
-    entryProgress,
-    entryState,
-    wasResolvedFromStuck,
-    groundPosition,
-    viewport,
-    onStartDrag: startDrag,
-    onUpdateDrag: updateDrag,
-    onEndDrag: endDrag,
-    onClick: handleCompanionClick,
-    onPositionUpdate: handlePositionUpdate,
-  };
-  
-  // Calculate ground position for debug line
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+
  const debugGroundY = calculateGroundY(viewport.height, config.size, config);
-  
+
  return (
-    <div 
+    <div
      className="fixed inset-0 pointer-events-none"
      style={{ zIndex: 9999 }}
      aria-hidden="true"
    >
-      {/* DEBUG: Visible ground line */}
      {DEBUG_GROUND_CONTACT && (
-        <>
-          {/* Ground line where Blobbi's CONTAINER bottom should be */}
-          <div 
-            style={{
-              position: 'fixed',
-              left: 0,
-              right: 0,
-              top: debugGroundY + config.size, // Container bottom
-              height: 2,
-              backgroundColor: 'red',
-              zIndex: 10002,
-            }}
-          />
-          {/* Label for the ground line */}
-          <div
-            style={{
-              position: 'fixed',
-              right: 10,
-              top: debugGroundY + config.size + 4,
-              color: 'red',
-              fontSize: 12,
-              fontWeight: 'bold',
-              zIndex: 10002,
-              backgroundColor: 'white',
-              padding: '2px 4px',
-            }}
-          >
-            Container bottom (groundY + size = {Math.round(debugGroundY + config.size)}px)
-          </div>
-          {/* Another line showing the actual viewport bottom minus padding */}
-          <div 
-            style={{
-              position: 'fixed',
-              left: 0,
-              right: 0,
-              top: viewport.height - config.padding.bottom,
-              height: 2,
-              backgroundColor: 'blue',
-              zIndex: 10002,
-            }}
-          />
-          <div
-            style={{
-              position: 'fixed',
-              right: 10,
-              top: viewport.height - config.padding.bottom + 4,
-              color: 'blue',
-              fontSize: 12,
-              fontWeight: 'bold',
-              zIndex: 10002,
-              backgroundColor: 'white',
-              padding: '2px 4px',
-            }}
-          >
-            Viewport - padding = {viewport.height - config.padding.bottom}px (Target ground)
-          </div>
-          {/* Entry type indicator */}
-          {isEntering && (
-            <div
-              style={{
-                position: 'fixed',
-                left: 10,
-                top: 10,
-                color: entryState.entryType === 'fall' ? 'orange' : 'green',
-                fontSize: 14,
-                fontWeight: 'bold',
-                zIndex: 10002,
-                backgroundColor: 'white',
-                padding: '4px 8px',
-                borderRadius: 4,
-              }}
-            >
-              Entry: {entryState.entryType.toUpperCase()} | Phase: {entryState.phase}
-            </div>
-          )}
-        </>
+        <DebugGroundOverlay
+          groundY={debugGroundY}
+          size={config.size}
+          viewportHeight={viewport.height}
+          paddingBottom={config.padding.bottom}
+          isEntering={isEntering}
+          entryState={entryState}
+        />
      )}
-      
-      {/* Companion */}
+
      <div className="pointer-events-auto">
-        <BlobbiCompanion 
-          {...companionProps}
+        <BlobbiCompanion
+          companion={companion}
+          state={state}
+          motion={motion}
+          eyeOffsetRef={eyeOffsetRef}
+          isEntering={isEntering}
+          entryProgress={entryProgress}
+          entryState={entryState}
+          wasResolvedFromStuck={wasResolvedFromStuck}
+          groundPosition={groundPosition}
+          viewport={viewport}
+          onStartDrag={startDrag}
+          onUpdateDrag={updateDrag}
+          onEndDrag={endDrag}
+          onClick={handleCompanionClick}
+          recipe={companionRecipe}
+          recipeLabel={companionRecipeLabel}
+          onPositionUpdate={handlePositionUpdate}
          debugMode={DEBUG_GROUND_CONTACT}
        />
      </div>
-      
-      {/* Action Menu - radial buttons around Blobbi */}
+
      <CompanionActionMenu
        isOpen={menuState.isOpen}
        companionPosition={renderedPosition}
        companionSize={config.size}
        actions={availableActions}
        selectedAction={menuState.selectedAction}
-        onActionClick={selectAction}
+        onActionClick={handleActionClick}
        onClickOutside={handleClickOutside}
+        isSleeping={isSleeping}
      />
-      
-      {/* Hanging Items - items displayed as hanging elements from top */}
+
      <HangingItems
        isVisible={menuState.isOpen && menuState.selectedAction !== null}
        selectedAction={menuState.selectedAction}
@@ -1,197 +1,210 @@
 /**
 * BlobbiCompanionVisual
- * 
+ *
 * Visual component for rendering the companion Blobbi.
- * Supports external eye offset control for custom gaze behavior.
+ *
+ * Architecture:
+ * - Outer shell: handles per-frame updates (float, shadow, drag state) — rerenders freely
+ * - Float wrapper: owns translateY alignment + JS float offset (inline transform)
+ * - Sway wrapper: owns CSS rotation animation only (animate-blobbi-sway)
+ *   Kept separate from float wrapper so CSS @keyframes don't override the
+ *   inline translateY, which would make Blobbi float above the ground.
+ * - Inner MemoizedBlobbiVisual: renders the actual SVG — only rerenders when visual inputs change
+ * - Eye gaze is driven imperatively via ref (no React rerenders for gaze)
 */

-import { useMemo, useRef } from 'react';
+import { useMemo, memo, type RefObject } from 'react';

 import { BlobbiBabyVisual } from '@/blobbi/ui/BlobbiBabyVisual';
 import { BlobbiAdultVisual } from '@/blobbi/ui/BlobbiAdultVisual';
+import { companionDataToBlobbi } from '@/blobbi/ui/lib/adapters';
 import { useEffectiveEmotion } from '@/blobbi/dev/EmotionDevContext';
+import type { BlobbiEmotion } from '@/blobbi/ui/lib/emotion-types';
+import type { BlobbiVisualRecipe } from '@/blobbi/ui/lib/recipe';
+import type { BodyEffectsSpec } from '@/blobbi/ui/lib/bodyEffects';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
 import { cn } from '@/lib/utils';
 import type { CompanionData, EyeOffset, CompanionDirection } from '../types/companion.types';
-import type { Blobbi } from '@/types/blobbi';
+
+// ─── Props ────────────────────────────────────────────────────────────────────

 interface BlobbiCompanionVisualProps {
-  /** Companion data */
  companion: CompanionData;
-  /** Size in pixels */
  size: number;
-  /** Eye offset for gaze direction */
-  eyeOffset: EyeOffset;
-  /** Facing direction (used for gaze, not for flipping) */
+  eyeOffsetRef: RefObject<EyeOffset>;
  direction: CompanionDirection;
-  /** Whether the companion is being dragged */
  isDragging: boolean;
-  /** Whether the companion is walking */
  isWalking: boolean;
-  /** Floating animation offset for gentle sway */
  floatOffset?: { x: number; y: number; rotation: number };
-  /** Whether Blobbi is on or near the ground (affects shadow visibility) */
  isOnGround?: boolean;
-  /** Distance from ground in pixels (for shadow fade, 0 = on ground) */
  distanceFromGround?: number;
-  /** Additional class names */
+  recipe?: BlobbiVisualRecipe;
+  recipeLabel?: string;
+  emotion?: BlobbiEmotion;
+  bodyEffects?: BodyEffectsSpec;
  className?: string;
-  /** Debug mode - shows visual boundaries */
  debugMode?: boolean;
 }

-/**
- * Convert CompanionData to the Blobbi type for rendering.
- */
-function toBlobiForVisual(companion: CompanionData): Blobbi {
-  return {
-    id: companion.d,
-    name: companion.name,
-    lifeStage: companion.stage,
-    state: 'active',
-    isSleeping: false,
-    stats: {
-      hunger: 100,
-      happiness: 100,
-      health: 100,
-      hygiene: 100,
-      energy: companion.energy,
-    },
-    baseColor: companion.visualTraits.baseColor,
-    secondaryColor: companion.visualTraits.secondaryColor,
-    eyeColor: companion.visualTraits.eyeColor,
-    pattern: companion.visualTraits.pattern,
-    specialMark: companion.visualTraits.specialMark,
-    size: companion.visualTraits.size,
-    seed: companion.seed ?? '',
-    tags: [],
-    // Include adult form info for proper rendering
-    adult: companion.adultType ? { evolutionForm: companion.adultType } : undefined,
-  };
+// ─── Memoized Inner Visual ────────────────────────────────────────────────────
+//
+// STABILITY CONTRACT:
+// This component is the boundary that protects the SVG DOM subtree from the
+// companion rerender storm (~60 renders/s from motion/float RAF loops).
+// It renders BlobbiAdultVisual / BlobbiBabyVisual with renderMode="companion".
+//
+// It MUST only rerender when actual visual content changes:
+//   blobbi, recipe, recipeLabel, emotion, bodyEffects, stage
+//
+// It MUST NOT receive or depend on per-frame values:
+//   eyeOffset value, floatOffset, isDragging, isWalking, position, animationTime
+//
+// The eyeOffsetRef is a stable React ref — its identity never changes,
+// so it is safe to pass without triggering rerenders.
+
+interface MemoizedBlobbiVisualProps {
+  stage: 'baby' | 'adult';
+  blobbi: Blobbi;
+  eyeOffsetRef: RefObject<EyeOffset>;
+  recipe?: BlobbiVisualRecipe;
+  recipeLabel?: string;
+  emotion: BlobbiEmotion;
+  bodyEffects?: BodyEffectsSpec;
 }

+const MemoizedBlobbiVisual = memo(function MemoizedBlobbiVisual({
+  stage,
+  blobbi,
+  eyeOffsetRef,
+  recipe,
+  recipeLabel,
+  emotion,
+  bodyEffects,
+}: MemoizedBlobbiVisualProps) {
+  if (stage === 'baby') {
+    return (
+      <BlobbiBabyVisual
+        blobbi={blobbi}
+        renderMode="companion"
+        lookMode="forward"
+        externalEyeOffsetRef={eyeOffsetRef}
+        recipe={recipe}
+        recipeLabel={recipeLabel}
+        emotion={emotion}
+        bodyEffects={bodyEffects}
+        className="size-full"
+      />
+    );
+  }
+
+  return (
+    <BlobbiAdultVisual
+      blobbi={blobbi}
+      renderMode="companion"
+      lookMode="forward"
+      externalEyeOffsetRef={eyeOffsetRef}
+      recipe={recipe}
+      recipeLabel={recipeLabel}
+      emotion={emotion}
+      bodyEffects={bodyEffects}
+      className="size-full"
+    />
+  );
+}, (prev, next) => {
+  return (
+    prev.stage === next.stage &&
+    prev.blobbi === next.blobbi &&
+    prev.recipe === next.recipe &&
+    prev.recipeLabel === next.recipeLabel &&
+    prev.emotion === next.emotion &&
+    prev.bodyEffects === next.bodyEffects
+  );
+});
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
 export function BlobbiCompanionVisual({
  companion,
  size,
-  eyeOffset,
+  eyeOffsetRef,
  direction,
  isDragging,
  isWalking,
  floatOffset = { x: 0, y: 0, rotation: 0 },
  isOnGround = true,
  distanceFromGround = 0,
+  recipe: recipeProp,
+  recipeLabel: recipeLabelProp,
+  emotion: emotionProp,
+  bodyEffects: bodyEffectsProp,
  className,
  debugMode = false,
 }: BlobbiCompanionVisualProps) {
-  const containerRef = useRef<HTMLDivElement>(null);
-  
-  const blobbi = useMemo(() => toBlobiForVisual(companion), [companion]);
-  
-  // DEV ONLY: Get effective emotion from dev context
-  const effectiveEmotion = useEffectiveEmotion();
-  
-  // Eye offset is now passed directly to the visual components via externalEyeOffset prop
-  // This is more reliable than DOM manipulation which can be overwritten by useBlobbiEyes
-  
-  // Build transform for floating animation
-  // No flipping based on direction - Blobbi always faces the same way
+  const blobbi = useMemo(() => companionDataToBlobbi(companion), [companion]);
+
+  // DEV ONLY: Get effective emotion from dev context (overrides production emotions)
+  const devEmotion = useEffectiveEmotion();
+  const hasDevOverride = devEmotion !== 'neutral';
+
+  const effectiveRecipe = hasDevOverride ? undefined : recipeProp;
+  const effectiveRecipeLabel = hasDevOverride ? undefined : recipeLabelProp;
+  const effectiveEmotion = hasDevOverride ? devEmotion : (emotionProp ?? 'neutral');
+  const effectiveBodyEffects = hasDevOverride ? undefined : bodyEffectsProp;
+
+  // Float transform
  const blobbiTransform = useMemo(() => {
    const transforms: string[] = [];
-    
    if (floatOffset.x !== 0 || floatOffset.y !== 0) {
      transforms.push(`translate(${floatOffset.x}px, ${floatOffset.y}px)`);
    }
    if (floatOffset.rotation !== 0) {
      transforms.push(`rotate(${floatOffset.rotation}deg)`);
    }
-    
    return transforms.length > 0 ? transforms.join(' ') : undefined;
  }, [floatOffset]);
-  
-  // Determine reaction state
-  const reaction = isDragging ? 'happy' : isWalking ? 'idle' : 'idle';
-  
-  // Shadow visibility and appearance based on ground proximity
-  // Shadow should only appear when Blobbi is on or very near the ground
-  const SHADOW_FADE_DISTANCE = 30; // Shadow fully fades at this distance from ground
+
+  // Reaction state for CSS animations on the OUTER wrapper
+  // When sleeping, always idle — no swaying/happy animation
+  const isSleeping = companion.state === 'sleeping';
+  const reaction = isSleeping ? 'idle' : isDragging ? 'happy' : isWalking ? 'swaying' : 'idle';
+
+  // ── Shadow ─────────────────────────────────────────────────────────────────
+  const SHADOW_FADE_DISTANCE = 30;
  const SHADOW_MAX_OPACITY = 0.35;
-  
-  // Calculate shadow visibility based on actual ground distance, not just float offset
+
  const showShadow = isOnGround && !isDragging && distanceFromGround < SHADOW_FADE_DISTANCE;
-  
-  // Shadow fades as Blobbi gets farther from ground
-  // Also factor in the float animation offset for subtle breathing effect
  const floatHeight = Math.abs(floatOffset.y);
  const groundFadeRatio = Math.max(0, 1 - distanceFromGround / SHADOW_FADE_DISTANCE);
-  const floatFadeRatio = Math.max(0.85, 1 - floatHeight * 0.02); // Subtle fade during float
+  const floatFadeRatio = Math.max(0.85, 1 - floatHeight * 0.02);
  const shadowOpacity = SHADOW_MAX_OPACITY * groundFadeRatio * floatFadeRatio;
-  const shadowScale = 0.9 + 0.1 * groundFadeRatio * floatFadeRatio; // Slightly smaller when lifting
-  
-  // Suppress unused variable warning for direction (kept for API compatibility)
+  const shadowScale = 0.9 + 0.1 * groundFadeRatio * floatFadeRatio;
+
+  // direction is accepted for API completeness but not currently used for rendering
+  // (Blobbi does not flip based on facing direction). Suppress unused warning.
  void direction;
-  
+
  return (
-    <div 
-      ref={containerRef}
+    <div
      className={cn('relative', className)}
      style={{ width: size, height: size }}
    >
-      {/* DEBUG: Container and alignment markers */}
+      {/* Debug alignment markers */}
      {debugMode && (
        <>
-          {/* Container outline - lime */}
-          <div
-            className="absolute inset-0 pointer-events-none"
-            style={{
-              border: '2px solid lime',
-              boxSizing: 'border-box',
-            }}
-          />
-          {/* 88% line from top (where SVG body bottom should be before shift) - yellow */}
-          <div
-            className="absolute pointer-events-none"
-            style={{
-              top: `${size * 0.88}px`,
-              left: 0,
-              right: 0,
-              height: 2,
-              backgroundColor: 'yellow',
-            }}
-          />
-          {/* 100% line (container bottom where body should touch after shift) - cyan */}
-          <div
-            className="absolute pointer-events-none"
-            style={{
-              bottom: 0,
-              left: 0,
-              right: 0,
-              height: 2,
-              backgroundColor: 'cyan',
-            }}
-          />
-          {/* Label showing the expected shift */}
-          <div
-            className="absolute pointer-events-none"
-            style={{
-              top: 2,
-              left: 2,
-              fontSize: 8,
-              color: 'white',
-              backgroundColor: 'black',
-              padding: '1px 2px',
-            }}
-          >
+          <div className="absolute inset-0 pointer-events-none" style={{ border: '2px solid lime', boxSizing: 'border-box' }} />
+          <div className="absolute pointer-events-none" style={{ top: `${size * 0.88}px`, left: 0, right: 0, height: 2, backgroundColor: 'yellow' }} />
+          <div className="absolute pointer-events-none" style={{ bottom: 0, left: 0, right: 0, height: 2, backgroundColor: 'cyan' }} />
+          <div className="absolute pointer-events-none" style={{ top: 2, left: 2, fontSize: 8, color: 'white', backgroundColor: 'black', padding: '1px 2px' }}>
            shift: {size * 0.12}px
          </div>
        </>
      )}
-      
-      {/* Floor shadow - only visible when Blobbi is on/near the ground */}
-      {/* Hidden during: dragging, entry animations, falling, or when far from ground */}
+
+      {/* Floor shadow */}
      {!debugMode && showShadow && shadowOpacity > 0.01 && (
        <div
          className="absolute pointer-events-none"
          style={{
-            // Position shadow well below Blobbi to feel like it's on the floor
            bottom: -20,
            left: '50%',
            width: size * 0.5,
@@ -200,53 +213,53 @@ export function BlobbiCompanionVisual({
            background: `radial-gradient(ellipse at center, rgba(0,0,0,${shadowOpacity}) 0%, rgba(0,0,0,${shadowOpacity * 0.5}) 40%, transparent 70%)`,
            borderRadius: '50%',
            filter: 'blur(4px)',
-            opacity: groundFadeRatio, // Additional opacity control for smooth fade
+            opacity: groundFadeRatio,
            transition: 'opacity 0.15s ease-out, transform 0.1s ease-out',
          }}
        />
      )}
-      
-      {/* Blobbi visual with floating transform */}
-      {/* 
-        The Blobbi SVG has empty space: 15% at top (body starts at y=15), 12% at bottom (body ends at y=88).
-        To align the visible body bottom with the container bottom, we shift down by 12% of container size.
-        This is applied BEFORE the float transform so the ground position is correct.
+
+      {/*
+        Float wrapper — owns translateY alignment + JS float offset.
+        This is a separate element from the sway wrapper below so that
+        the CSS animation on the sway wrapper does not override the
+        inline transform here. (CSS @keyframes replace the entire
+        `transform` property while active, which would drop the
+        translateY alignment shift and cause Blobbi to float above
+        the ground during walking.)
      */}
      <div
        className="size-full"
        style={{
-          // First apply the SVG alignment correction, then the float animation
-          // The 12% shift pushes the SVG down so its visible body bottom aligns with container bottom
          transform: [
-            `translateY(${size * 0.12}px)`,  // SVG body alignment correction
-            blobbiTransform,                  // Float animation (if any)
+            `translateY(${size * 0.12}px)`,
+            blobbiTransform,
          ].filter(Boolean).join(' ') || undefined,
          transformOrigin: 'center bottom',
          transition: isDragging ? 'none' : 'transform 0.05s ease-out',
-          // DEBUG: Show the shifted wrapper
          ...(debugMode ? { outline: '2px dashed magenta' } : {}),
        }}
      >
-        {companion.stage === 'baby' && (
-          <BlobbiBabyVisual
-            blobbi={blobbi}
-            reaction={reaction}
-            lookMode="forward"
-            externalEyeOffset={eyeOffset}
-            emotion={effectiveEmotion}
-            className="size-full"
-          />
-        )}
-        {companion.stage === 'adult' && (
-          <BlobbiAdultVisual
-            blobbi={blobbi}
-            reaction={reaction}
-            lookMode="forward"
-            externalEyeOffset={eyeOffset}
-            emotion={effectiveEmotion}
-            className="size-full"
-          />
-        )}
+        {/* Sway wrapper — CSS rotation only, no positioning transforms */}
+        <div
+          className={cn(
+            'size-full',
+            (reaction === 'swaying' || reaction === 'happy') && 'animate-blobbi-sway',
+          )}
+          style={{ transformOrigin: 'center bottom' }}
+        >
+          {(companion.stage === 'baby' || companion.stage === 'adult') && (
+            <MemoizedBlobbiVisual
+              stage={companion.stage}
+              blobbi={blobbi}
+              eyeOffsetRef={eyeOffsetRef}
+              recipe={effectiveRecipe}
+              recipeLabel={effectiveRecipeLabel}
+              emotion={effectiveEmotion}
+              bodyEffects={effectiveBodyEffects}
+            />
+          )}
+        </div>
      </div>
    </div>
  );
@@ -0,0 +1,108 @@
+/**
+ * DebugGroundOverlay — Debug-only visual overlay for ground contact debugging.
+ *
+ * Shows horizontal lines indicating:
+ *   - Container bottom (where Blobbi's container ends)
+ *   - Viewport bottom minus padding (target ground position)
+ *   - Entry animation type and phase (during entry)
+ *
+ * Enabled by setting DEBUG_GROUND_CONTACT = true in BlobbiCompanionLayer.
+ */
+
+import type { EntryState } from '../types/companion.types';
+
+interface DebugGroundOverlayProps {
+  groundY: number;
+  size: number;
+  viewportHeight: number;
+  paddingBottom: number;
+  isEntering: boolean;
+  entryState: EntryState;
+}
+
+export function DebugGroundOverlay({
+  groundY,
+  size,
+  viewportHeight,
+  paddingBottom,
+  isEntering,
+  entryState,
+}: DebugGroundOverlayProps) {
+  return (
+    <>
+      {/* Ground line where Blobbi's CONTAINER bottom should be */}
+      <div
+        style={{
+          position: 'fixed',
+          left: 0,
+          right: 0,
+          top: groundY + size,
+          height: 2,
+          backgroundColor: 'red',
+          zIndex: 10002,
+        }}
+      />
+      <div
+        style={{
+          position: 'fixed',
+          right: 10,
+          top: groundY + size + 4,
+          color: 'red',
+          fontSize: 12,
+          fontWeight: 'bold',
+          zIndex: 10002,
+          backgroundColor: 'white',
+          padding: '2px 4px',
+        }}
+      >
+        Container bottom (groundY + size = {Math.round(groundY + size)}px)
+      </div>
+      {/* Viewport bottom minus padding */}
+      <div
+        style={{
+          position: 'fixed',
+          left: 0,
+          right: 0,
+          top: viewportHeight - paddingBottom,
+          height: 2,
+          backgroundColor: 'blue',
+          zIndex: 10002,
+        }}
+      />
+      <div
+        style={{
+          position: 'fixed',
+          right: 10,
+          top: viewportHeight - paddingBottom + 4,
+          color: 'blue',
+          fontSize: 12,
+          fontWeight: 'bold',
+          zIndex: 10002,
+          backgroundColor: 'white',
+          padding: '2px 4px',
+        }}
+      >
+        Viewport - padding = {viewportHeight - paddingBottom}px (Target ground)
+      </div>
+      {/* Entry type indicator */}
+      {isEntering && (
+        <div
+          style={{
+            position: 'fixed',
+            left: 10,
+            top: 10,
+            color: entryState.entryType === 'fall' ? 'orange' : 'green',
+            fontSize: 14,
+            fontWeight: 'bold',
+            zIndex: 10002,
+            backgroundColor: 'white',
+            padding: '4px 8px',
+            borderRadius: 4,
+          }}
+        >
+          Entry: {entryState.entryType.toUpperCase()} | Phase: {entryState.phase}
+        </div>
+      )}
+    </>
+  );
+}
@@ -0,0 +1,43 @@
+/**
+ * useActionEmotionOverride — Temporary emotion override when using items.
+ *
+ * When an item is used on the companion (e.g., feeding → happy), this hook
+ * provides a short-lived emotion override that takes precedence over the
+ * status reaction system. The override automatically clears after 1.5s.
+ *
+ * Used by BlobbiCompanionLayer to wrap item-use handlers with emotion feedback.
+ */
+
+import { useState, useCallback, useRef } from 'react';
+
+import { getActionEmotion, type ActionType } from '@/blobbi/ui/lib/status-reactions';
+import type { BlobbiEmotion } from '@/blobbi/ui/lib/emotions';
+
+/** Duration of the action emotion override in milliseconds. */
+const ACTION_OVERRIDE_DURATION_MS = 1500;
+
+interface UseActionEmotionOverrideResult {
+  /** Current override emotion, or null if none active. Passed to useStatusReaction. */
+  actionOverride: BlobbiEmotion | null;
+  /** Trigger an override for the given action type. */
+  triggerOverride: (action: ActionType) => void;
+}
+
+export function useActionEmotionOverride(): UseActionEmotionOverrideResult {
+  const [actionOverride, setActionOverride] = useState<BlobbiEmotion | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const triggerOverride = useCallback((action: ActionType) => {
+    // Clear any existing timer
+    if (timerRef.current) {
+      clearTimeout(timerRef.current);
+    }
+    setActionOverride(getActionEmotion(action));
+    timerRef.current = setTimeout(() => {
+      setActionOverride(null);
+      timerRef.current = null;
+    }, ACTION_OVERRIDE_DURATION_MS);
+  }, []);
+
+  return { actionOverride, triggerOverride };
+}
@@ -12,7 +12,6 @@ import type {
  CompanionData,
  CompanionState,
  CompanionMotion,
-  GazeState,
  EyeOffset,
  Position,
  MovementBounds,
@@ -20,8 +19,17 @@ import type {
  EntryType,
  InspectionDirection,
 } from '../types/companion.types';
+
+/** Default motion state used before motion hook initializes */
+const DEFAULT_MOTION: CompanionMotion = {
+  position: { x: 0, y: 0 },
+  velocity: { x: 0, y: 0 },
+  direction: 'right',
+  isGrounded: true,
+  isDragging: false,
+};
 import { DEFAULT_COMPANION_CONFIG } from '../core/companionConfig';
-import { calculateMovementBounds, calculateGroundY, calculateRestingPosition } from '../utils/movement';
+import { calculateMovementBounds, calculateGroundY } from '../utils/movement';
 import { useBlobbiCompanionData } from './useBlobbiCompanionData';
 import { useBlobbiCompanionState } from './useBlobbiCompanionState';
 import { useBlobbiCompanionMotion } from './useBlobbiCompanionMotion';
@@ -50,10 +58,8 @@ interface UseBlobbiCompanionResult {
  state: CompanionState;
  /** Current motion state */
  motion: CompanionMotion;
-  /** Current gaze state */
-  gaze: GazeState;
-  /** Smoothed eye offset for rendering */
-  eyeOffset: EyeOffset;
+  /** Ref-based eye offset for imperative gaze control (no rerenders) */
+  eyeOffsetRef: React.RefObject<EyeOffset>;
  /** Whether entry animation is playing */
  isEntering: boolean;
  /** Entry animation progress (0-1) - legacy, use entryState for detailed control */
@@ -128,10 +134,14 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
    y: groundY,
  }), [viewport.width, config.size, groundY]);
  
-  const restingPosition = useMemo(() =>
-    calculateRestingPosition(viewport.width, viewport.height, config.size, config),
-    [viewport.width, viewport.height, config]
-  );
+  // Shared motion ref - motion hook writes, state hook reads
+  // This solves the bidirectional dependency: state needs motion position,
+  // motion needs state/targetX. By using a ref, state can read current motion
+  // without creating a circular hook dependency.
+  const motionRef = useRef<CompanionMotion>({
+    ...DEFAULT_MOTION,
+    position: groundPosition,
+  });
  
  // Fetch companion data
  const { companion, isLoading } = useBlobbiCompanionData();
@@ -200,7 +210,11 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
    }, config.attention.postRouteDelay);
  }, [findMainContentPosition, triggerAttention, config.attention.postRouteDuration, config.attention.postRouteDelay]);
  
+  // Determine if companion is sleeping
+  const companionSleeping = companion?.state === 'sleeping';
+
  // State management
+  // Pass the shared motionRef so state can read live motion values
  const {
    state,
    direction,
@@ -210,19 +224,15 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
    onReachedTarget,
  } = useBlobbiCompanionState({
    isActive: isVisible,
-    motion: { 
-      position: restingPosition, 
-      velocity: { x: 0, y: 0 }, 
-      direction: 'right', 
-      isGrounded: true, 
-      isDragging: false 
-    },
+    motionRef,
    bounds,
    attentionTarget: currentAttention,
+    isSleeping: companionSleeping,
  });
  
  // Motion management
  // After entry completes, motion continues from groundPosition (where entry ended)
+  // Pass sharedMotionRef so state hook can read live motion values
  const {
    motion,
    startDrag,
@@ -237,6 +247,7 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
    targetX,
    energy: companion?.energy ?? 50,
    onReachedTarget,
+    sharedMotionRef: motionRef,
  });
  
  // Entry animation management (handles route changes and companion changes)
@@ -292,7 +303,7 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
  }, [entryJustCompleted, wasResolvedFromStuck, setPosition, groundPosition, acknowledgeCompletion]);
  
  // Gaze management - passes entry inspection direction for eye control during entry
-  const { gaze, eyeOffset } = useBlobbiCompanionGaze({
+  const { eyeOffsetRef } = useBlobbiCompanionGaze({
    state: isEntering ? 'idle' : state,
    direction: isEntering ? 'right' : direction,
    companionPosition: motion.position,
@@ -310,8 +321,7 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
    isVisible: shouldBeVisible,
    state: isEntering ? 'idle' : state,
    motion,
-    gaze,
-    eyeOffset,
+    eyeOffsetRef,
    isEntering,
    entryProgress: entryState.progress,
    entryState,
@@ -4,22 +4,18 @@
 * Fetches the current companion data from the user's Blobbonaut profile.
 * This is the data layer - it handles fetching and provides companion data.
 * 
- * IMPORTANT: This hook uses useBlobbonautProfile to ensure reactivity.
- * When the profile is updated (e.g., companion selected/removed), this hook
- * automatically receives the update via the shared query cache.
+ * IMPORTANT: This hook shares the same query cache as BlobbiPage via
+ * useBlobbisCollection. This ensures:
+ * - Immediate reactivity when stats change (optimistic updates)
+ * - Projected decay is applied for accurate visual reactions
+ * - No duplicate queries or stale cache issues
 */

 import { useMemo } from 'react';
-import { useNostr } from '@nostrify/react';
-import { useQuery } from '@tanstack/react-query';

-import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useBlobbonautProfile } from '@/hooks/useBlobbonautProfile';
-import {
-  KIND_BLOBBI_STATE,
-  isValidBlobbiEvent,
-  parseBlobbiEvent,
-} from '@/lib/blobbi';
+import { useBlobbisCollection } from '@/blobbi/core/hooks/useBlobbisCollection';
+import { useProjectedBlobbiState } from '@/blobbi/core/hooks/useProjectedBlobbiState';
 import type { CompanionData } from '../types/companion.types';

 interface UseBlobbiCompanionDataResult {
@@ -36,79 +32,83 @@ interface UseBlobbiCompanionDataResult {
 * 
 * Flow:
 * 1. Use useBlobbonautProfile to get the profile (shared query, reactive)
- * 2. Read the currentCompanion from the profile
- * 3. If it exists, fetch the corresponding kind 31124 (Blobbi State) event
- * 4. Return the minimal data needed for rendering
+ * 2. Build a dList containing just the currentCompanion
+ * 3. Use useBlobbisCollection (shared with BlobbiPage) to get the companion
+ * 4. Apply projected decay for accurate UI reactions
+ * 5. Return the companion data with projected stats
 * 
 * Reactivity:
- * - Uses the same query cache as useBlobbonautProfile
- * - When profile is updated via updateProfileEvent(), this hook reacts immediately
- * - No duplicate queries or stale cache issues
+ * - Uses the same query cache as BlobbiPage (blobbi-collection)
+ * - When Blobbi state is updated, optimistic updates flow through immediately
+ * - Projected decay recalculates every 60 seconds
+ * - No separate query or stale cache issues
 */
 export function useBlobbiCompanionData(): UseBlobbiCompanionDataResult {
-  const { nostr } = useNostr();
-  const { user } = useCurrentUser();
-  
  // Use the shared profile hook - this ensures reactivity when profile changes
  const { profile, isLoading: profileLoading } = useBlobbonautProfile();
  
  // Extract current companion d-tag from the reactive profile
  const currentCompanionD = profile?.currentCompanion;
  
-  // Fetch the Blobbi state if we have a current companion
-  const blobbiQuery = useQuery({
-    queryKey: ['companion-blobbi', user?.pubkey, currentCompanionD],
-    queryFn: async ({ signal }) => {
-      if (!user?.pubkey || !currentCompanionD) return null;
-      
-      const events = await nostr.query([{
-        kinds: [KIND_BLOBBI_STATE],
-        authors: [user.pubkey],
-        '#d': [currentCompanionD],
-      }], { signal });
-      
-      // Get the latest valid event
-      const validEvents = events
-        .filter(isValidBlobbiEvent)
-        .sort((a, b) => b.created_at - a.created_at);
-      
-      if (validEvents.length === 0) return null;
-      
-      return parseBlobbiEvent(validEvents[0]);
-    },
-    enabled: !!user?.pubkey && !!currentCompanionD,
-    staleTime: 60_000, // 1 minute
-    gcTime: 5 * 60_000, // 5 minutes
-  });
+  // Build dList containing just the current companion (if set)
+  // This allows us to use the shared collection query cache
+  const dList = useMemo(() => {
+    if (!currentCompanionD) return undefined;
+    return [currentCompanionD];
+  }, [currentCompanionD]);
  
-  // Transform to CompanionData
+  // Use the shared collection query - same cache as BlobbiPage
+  // This ensures we get optimistic updates immediately
+  const {
+    companionsByD,
+    isLoading: collectionLoading,
+  } = useBlobbisCollection(dList);
+  
+  // Get the BlobbiCompanion from the collection
+  const blobbi = currentCompanionD ? companionsByD[currentCompanionD] ?? null : null;
+  
+  // Apply projected decay for accurate visual reactions
+  // This recalculates every 60 seconds while mounted
+  const projectedState = useProjectedBlobbiState(blobbi);
+  
+  // Transform to CompanionData with projected stats
  // When currentCompanionD becomes null/undefined, companion becomes null
  const companion = useMemo((): CompanionData | null => {
    // If no current companion is set in profile, return null immediately
    // This ensures removal is reactive
    if (!currentCompanionD) return null;
    
-    const blobbi = blobbiQuery.data;
    if (!blobbi) return null;
    
    // Only baby and adult can be companions
    if (blobbi.stage === 'egg') return null;
    
+    // Use projected stats if available, otherwise fall back to base stats
+    const stats = projectedState?.stats ?? blobbi.stats;
+    
    return {
      d: blobbi.d,
      name: blobbi.name,
      stage: blobbi.stage,
      visualTraits: blobbi.visualTraits,
-      energy: blobbi.stats.energy ?? 100,
+      energy: stats.energy ?? 100,
+      stats: {
+        hunger: stats.hunger ?? 100,
+        happiness: stats.happiness ?? 100,
+        health: stats.health ?? 100,
+        hygiene: stats.hygiene ?? 100,
+        energy: stats.energy ?? 100,
+      },
+      state: blobbi.state,
      // Include adult form info for proper rendering
      adultType: blobbi.adultType,
      seed: blobbi.seed,
    };
-  }, [currentCompanionD, blobbiQuery.data]);
+  }, [currentCompanionD, blobbi, projectedState?.stats]);
  
  return {
    companion,
-    isLoading: profileLoading || (!!currentCompanionD && blobbiQuery.isLoading),
-    error: blobbiQuery.error ?? null,
+    isLoading: profileLoading || (!!currentCompanionD && collectionLoading),
+    error: null,
  };
 }
@@ -49,10 +49,8 @@ interface UseBlobbiCompanionGazeOptions {
 }

 interface UseBlobbiCompanionGazeResult {
-  /** Current gaze state */
-  gaze: GazeState;
-  /** Smoothed eye offset for rendering */
-  eyeOffset: EyeOffset;
+  /** Ref-based eye offset for imperative gaze control (no rerenders) */
+  eyeOffsetRef: React.RefObject<EyeOffset>;
 }

 /**
@@ -94,8 +92,11 @@ export function useBlobbiCompanionGaze({
  attentionPosition,
  entryInspectionDirection,
 }: UseBlobbiCompanionGazeOptions): UseBlobbiCompanionGazeResult {
-  const [gaze, setGaze] = useState<GazeState>(createInitialGaze);
-  const [eyeOffset, setEyeOffset] = useState<EyeOffset>({ x: 0, y: 0 });
+  const [, setGaze] = useState<GazeState>(createInitialGaze);
+  // Eye offset is driven imperatively via ref — no React state needed.
+  // The RAF loop writes to eyeOffsetRef; useExternalEyeOffset reads from it.
+  /** Ref-based eye offset for imperative consumers (avoids per-frame React rerenders) */
+  const eyeOffsetRef = useRef<EyeOffset>({ x: 0, y: 0 });
  const [mousePosition, setMousePosition] = useState<Position | null>(null);
  
  // Use refs for values that shouldn't trigger re-renders
@@ -109,8 +110,25 @@ export function useBlobbiCompanionGaze({
  const mouseFollowTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  const mouseFollowCheckTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
  
+  // Refs for frequently changing values used in animation loop
+  // This prevents RAF effect from being torn down on every position change
+  const directionRef = useRef(direction);
+  const companionPositionRef = useRef(companionPosition);
+  const companionSizeRef = useRef(companionSize);
+  const mousePositionRef = useRef(mousePosition);
+  const observationTargetRef = useRef(observationTarget);
+  const attentionPositionRef = useRef(attentionPosition);
+  
  const config = DEFAULT_COMPANION_CONFIG;
  
+  // Keep refs updated with latest values
+  useEffect(() => { directionRef.current = direction; }, [direction]);
+  useEffect(() => { companionPositionRef.current = companionPosition; }, [companionPosition]);
+  useEffect(() => { companionSizeRef.current = companionSize; }, [companionSize]);
+  useEffect(() => { mousePositionRef.current = mousePosition; }, [mousePosition]);
+  useEffect(() => { observationTargetRef.current = observationTarget; }, [observationTarget]);
+  useEffect(() => { attentionPositionRef.current = attentionPosition; }, [attentionPosition]);
+  
  // Clear all timers helper
  const clearAllTimers = useCallback(() => {
    if (randomGazeTimerRef.current) {
@@ -275,6 +293,9 @@ export function useBlobbiCompanionGaze({
  }, [isActive, state, observationTarget, attentionPosition, entryInspectionDirection, config.gaze.randomInterval, config.gaze.mouseFollowCooldown, config.gaze.mouseFollowChance, config.gaze.mouseFollowDuration, clearAllTimers]);
  
  // Animation loop for smooth eye movement
+  // IMPORTANT: This effect only depends on isActive to start/stop the loop.
+  // All other values are read from refs to prevent loop recreation on every
+  // position change (which caused jitter and stuck eyes after entry).
  useEffect(() => {
    if (!isActive) {
      if (animationRef.current) {
@@ -285,6 +306,14 @@ export function useBlobbiCompanionGaze({
    }
    
    const animate = () => {
+      // Read current values from refs (not closure captures)
+      const currentPosition = companionPositionRef.current;
+      const currentSize = companionSizeRef.current;
+      const currentDirection = directionRef.current;
+      const currentMouse = mousePositionRef.current;
+      const currentObservation = observationTargetRef.current;
+      const currentAttention = attentionPositionRef.current;
+      
      // Calculate target offset based on current gaze mode
      let targetOffset: EyeOffset;
      
@@ -294,19 +323,19 @@ export function useBlobbiCompanionGaze({
        // During entry inspection - use the pre-set target offset from inspection direction
        // This is set by the main effect when entryInspectionDirection changes
        targetOffset = targetOffsetRef.current;
-      } else if (currentMode === 'attend-ui' && attentionPosition) {
+      } else if (currentMode === 'attend-ui' && currentAttention) {
        // Look at UI element that appeared - calculate offset to that position
-        targetOffset = calculateEyeOffset(companionPosition, attentionPosition, companionSize);
-      } else if (currentMode === 'observe-target' && observationTarget) {
+        targetOffset = calculateEyeOffset(currentPosition, currentAttention, currentSize);
+      } else if (currentMode === 'observe-target' && currentObservation) {
        // Look at observation target - calculate offset to that position
-        targetOffset = calculateEyeOffset(companionPosition, observationTarget, companionSize);
-      } else if (currentMode === 'follow-mouse' && mousePosition) {
+        targetOffset = calculateEyeOffset(currentPosition, currentObservation, currentSize);
+      } else if (currentMode === 'follow-mouse' && currentMouse) {
        // Follow mouse cursor
-        targetOffset = calculateEyeOffset(companionPosition, mousePosition, companionSize);
+        targetOffset = calculateEyeOffset(currentPosition, currentMouse, currentSize);
      } else if (currentMode === 'forward') {
        // Look in movement direction - STRONGER offset for clear visual feedback
        targetOffset = {
-          x: direction === 'right' ? 0.85 : -0.85,
+          x: currentDirection === 'right' ? 0.85 : -0.85,
          y: 0.15, // Slightly down, looking at path ahead
        };
      } else {
@@ -329,10 +358,13 @@ export function useBlobbiCompanionGaze({
                         : currentMode === 'forward' ? 0.12 
                         : 0.06;
      
-      setEyeOffset(prev => ({
-        x: smoothLerp(prev.x, targetOffset.x, smoothFactor),
-        y: smoothLerp(prev.y, targetOffset.y, smoothFactor),
-      }));
+      // Update the ref imperatively (no React rerender) — companion visual reads from this
+      const prevOffset = eyeOffsetRef.current;
+      const newOffset = {
+        x: smoothLerp(prevOffset.x, targetOffset.x, smoothFactor),
+        y: smoothLerp(prevOffset.y, targetOffset.y, smoothFactor),
+      };
+      eyeOffsetRef.current = newOffset;
      
      animationRef.current = requestAnimationFrame(animate);
    };
@@ -345,10 +377,9 @@ export function useBlobbiCompanionGaze({
        animationRef.current = null;
      }
    };
-  }, [isActive, direction, companionPosition, mousePosition, companionSize, observationTarget, attentionPosition, entryInspectionDirection]);
+  }, [isActive]); // ONLY depend on isActive - all other values read from refs
  
  return {
-    gaze,
-    eyeOffset,
+    eyeOffsetRef,
  };
 }
@@ -5,7 +5,7 @@
 * This includes walking, gravity, and drag behavior.
 */

-import { useState, useCallback, useRef, useEffect } from 'react';
+import { useState, useCallback, useRef, useEffect, type MutableRefObject } from 'react';

 import type {
  CompanionState,
@@ -37,6 +37,12 @@ interface UseBlobbiCompanionMotionOptions {
  energy: number;
  /** Callback when target is reached */
  onReachedTarget: () => void;
+  /**
+   * Shared ref to sync motion state with state hook.
+   * This allows the state hook to read live motion values without
+   * creating a circular dependency.
+   */
+  sharedMotionRef?: MutableRefObject<CompanionMotion>;
 }

 interface UseBlobbiCompanionMotionResult {
@@ -63,6 +69,7 @@ export function useBlobbiCompanionMotion({
  targetX,
  energy,
  onReachedTarget,
+  sharedMotionRef,
 }: UseBlobbiCompanionMotionOptions): UseBlobbiCompanionMotionResult {
  const [motion, setMotion] = useState<CompanionMotion>(() => 
    createInitialMotion(initialX, groundY)
@@ -72,6 +79,13 @@ export function useBlobbiCompanionMotion({
  const lastTimeRef = useRef<number>(0);
  const config = DEFAULT_COMPANION_CONFIG;
  
+  // Sync motion to shared ref so state hook can read it
+  useEffect(() => {
+    if (sharedMotionRef) {
+      sharedMotionRef.current = motion;
+    }
+  }, [motion, sharedMotionRef]);
+  
  // Animation loop
  useEffect(() => {
    const animate = (time: number) => {
@@ -5,7 +5,7 @@
 * This is the state layer - it handles state transitions and timing.
 */

-import { useState, useEffect, useCallback, useRef } from 'react';
+import { useState, useEffect, useCallback, useRef, type MutableRefObject } from 'react';

 import type {
  CompanionState,
@@ -21,14 +21,20 @@ import { DEFAULT_COMPANION_CONFIG, randomDuration } from '../core/companionConfi
 interface UseBlobbiCompanionStateOptions {
  /** Whether the companion is active and should be making decisions */
  isActive: boolean;
-  /** Current motion state (used for position/dragging checks) */
-  motion: CompanionMotion;
+  /** 
+   * Ref to current motion state (shared with motion hook).
+   * Using a ref allows state to read live motion values without
+   * creating a circular dependency between state and motion hooks.
+   */
+  motionRef: MutableRefObject<CompanionMotion>;
  /** Movement bounds */
  bounds: MovementBounds;
  /** Whether to force walking on first activation (after entry) */
  forceInitialWalk?: boolean;
  /** Current attention target (from UI attention system) */
  attentionTarget?: AttentionTarget | null;
+  /** Whether the companion is sleeping (freezes all decisions/movement) */
+  isSleeping?: boolean;
 }

 interface UseBlobbiCompanionStateResult {
@@ -51,10 +57,11 @@ interface UseBlobbiCompanionStateResult {
 */
 export function useBlobbiCompanionState({
  isActive,
-  motion,
+  motionRef,
  bounds,
  forceInitialWalk = true,
  attentionTarget,
+  isSleeping = false,
 }: UseBlobbiCompanionStateOptions): UseBlobbiCompanionStateResult {
  const [state, setState] = useState<CompanionState>('idle');
  const [direction, setDirection] = useState<CompanionDirection>('right');
@@ -67,14 +74,11 @@ export function useBlobbiCompanionState({
  
  const timerRef = useRef<number | null>(null);
  const hasHadInitialWalk = useRef(false);
-  const motionRef = useRef(motion);
  const lastObservationTimeRef = useRef<number>(0);
  const config = DEFAULT_COMPANION_CONFIG;
  
-  // Keep motion ref updated
-  useEffect(() => {
-    motionRef.current = motion;
-  }, [motion]);
+  // motionRef is now passed in from the orchestrator and shared with motion hook
+  // No need for local ref or sync effect - just read directly from motionRef.current
  
  // Clear timer on cleanup
  useEffect(() => {
@@ -136,7 +140,7 @@ export function useBlobbiCompanionState({
  
  // Make a decision about what to do next
  const makeDecision = useCallback(() => {
-    if (!isActive || motionRef.current.isDragging) {
+    if (!isActive || isSleeping || motionRef.current.isDragging) {
      return;
    }
    
@@ -172,7 +176,7 @@ export function useBlobbiCompanionState({
    // Schedule next decision
    const duration = transition.duration ?? randomDuration(config.idleTime);
    timerRef.current = window.setTimeout(makeDecision, duration);
-  }, [isActive, bounds, state, config, startObservation]);
+  }, [isActive, isSleeping, bounds, state, config, startObservation]);
  
  // Handle reaching target
  const onReachedTarget = useCallback(() => {
@@ -207,9 +211,22 @@ export function useBlobbiCompanionState({
    }
  }, [makeDecision, observationTarget, config.observation.lookDuration]);
  
-  // Start decision loop when active
+  // Force idle when sleeping - stop all movement/decisions immediately
  useEffect(() => {
-    if (isActive && !motionRef.current.isDragging) {
+    if (isSleeping) {
+      if (timerRef.current) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+      setState('idle');
+      setTargetX(null);
+      setObservationTarget(null);
+    }
+  }, [isSleeping]);
+
+  // Start decision loop when active (and not sleeping)
+  useEffect(() => {
+    if (isActive && !isSleeping && !motionRef.current.isDragging) {
      // Clear any existing timer
      if (timerRef.current) {
        clearTimeout(timerRef.current);
@@ -238,19 +255,33 @@ export function useBlobbiCompanionState({
        clearTimeout(timerRef.current);
      }
    };
-  }, [isActive, forceInitialWalk, startInitialWalk, makeDecision]);
+  }, [isActive, isSleeping, forceInitialWalk, startInitialWalk, makeDecision]);
  
  // Pause decisions while dragging
+  // We poll isDragging via interval since motionRef changes don't trigger re-renders
  useEffect(() => {
-    if (motion.isDragging) {
-      if (timerRef.current) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
+    if (!isActive) return;
+    
+    let wasDragging = false;
+    
+    const checkDragging = () => {
+      const isDragging = motionRef.current.isDragging;
+      if (isDragging && !wasDragging) {
+        // Started dragging
+        if (timerRef.current) {
+          clearTimeout(timerRef.current);
+          timerRef.current = null;
+        }
+        setState('idle');
+        setTargetX(null);
      }
-      setState('idle');
-      setTargetX(null);
-    }
-  }, [motion.isDragging]);
+      wasDragging = isDragging;
+    };
+    
+    // Check frequently for drag state changes
+    const interval = setInterval(checkDragging, 100);
+    return () => clearInterval(interval);
+  }, [isActive, motionRef]);
  
  // Handle attention targets - interrupt current behavior when UI elements appear
  useEffect(() => {
@@ -24,7 +24,7 @@ import {
  isValidBlobbiEvent,
  parseBlobbiEvent,
  type BlobbiStats,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';
 import { checkItemCategoryNeed, type NeedCheckResult } from '../interaction/needDetection';
 import type { ShopItemCategory } from '@/blobbi/shop/types/shop.types';
 import type { Position } from '../types/companion.types';
@@ -100,7 +100,6 @@ export function BlobbiActionsProvider({ children }: BlobbiActionsProviderProps)
  const registerRef = useRef<UseItemFunction | null>(null);
  const canUseItemsRegisteredRef = useRef<boolean>(false);
  const isUsingItemRegisteredRef = useRef<boolean>(false);
-
  // Subscribers for manual notification
  const subscribersRef = useRef<Set<() => void>>(new Set());

@@ -35,6 +35,8 @@ interface CompanionActionMenuProps {
  onActionClick: (action: CompanionMenuAction) => void;
  /** Callback for clicking outside the menu */
  onClickOutside?: () => void;
+  /** Whether Blobbi is currently sleeping (affects sleep button label) */
+  isSleeping?: boolean;
 }

 // Layout configuration
@@ -90,6 +92,7 @@ export function CompanionActionMenu({
  selectedAction,
  onActionClick,
  onClickOutside,
+  isSleeping = false,
 }: CompanionActionMenuProps) {
  if (!isOpen) return null;
  
@@ -122,6 +125,11 @@ export function CompanionActionMenu({
        const isSelected = selectedAction === action.id;
        const delay = index * MENU_CONFIG.staggerDelay;
        
+        // Sleep action toggles label/emoji based on sleeping state
+        const isSleepAction = action.id === 'sleep';
+        const displayEmoji = isSleepAction && isSleeping ? '\u2600\uFE0F' : action.emoji;
+        const displayLabel = isSleepAction && isSleeping ? 'Wake up' : action.label;
+        
        return (
          <button
            key={action.id}
@@ -155,15 +163,15 @@ export function CompanionActionMenu({
              e.stopPropagation();
              onActionClick(action.id);
            }}
-            title={action.label}
-            aria-label={action.label}
+            title={displayLabel}
+            aria-label={displayLabel}
          >
            <span 
              className="text-xl select-none"
              role="img"
              aria-hidden="true"
            >
-              {action.emoji}
+              {displayEmoji}
            </span>
          </button>
        );
@@ -10,7 +10,7 @@
 * - Returns both boolean need and priority level for potential future use
 */

-import type { BlobbiStats } from '@/lib/blobbi';
+import type { BlobbiStats } from '@/blobbi/core/lib/blobbi';
 import type { ShopItemCategory } from '@/blobbi/shop/types/shop.types';

 // ─── Need Thresholds ──────────────────────────────────────────────────────────
@@ -66,7 +66,6 @@ const CATEGORY_TO_PRIMARY_STAT: Record<ShopItemCategory, (keyof BlobbiStats)[]>
  toy: ['happiness'],
  hygiene: ['hygiene'],
  medicine: ['health'],
-  accessory: [], // Accessories don't address needs
 };

 // ─── Need Detection Functions ─────────────────────────────────────────────────
@@ -27,7 +27,7 @@ import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

 import type { NostrEvent } from '@nostrify/nostrify';
-import type { BlobbiCompanion, BlobbonautProfile, BlobbiStats } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile, BlobbiStats } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBI_STATE,
  KIND_BLOBBONAUT_PROFILE,
@@ -36,8 +36,8 @@ import {
  createStorageTags,
  parseBlobbiEvent,
  isValidBlobbiEvent,
-} from '@/lib/blobbi';
-import { applyBlobbiDecay } from '@/lib/blobbi-decay';
+} from '@/blobbi/core/lib/blobbi';
+import { applyBlobbiDecay } from '@/blobbi/core/lib/blobbi-decay';
 import { getShopItemById } from '@/blobbi/shop/lib/blobbi-shop-items';
 import {
  applyItemEffects,
@@ -188,14 +188,45 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
    return parseBlobbiEvent(validEvents[0]) ?? null;
  }, [nostr, user?.pubkey, profile?.currentCompanion, options.companion]);
  
-  // Update companion in query cache
-  const updateCompanionInCache = useCallback((_event: NostrEvent) => {
+  // Update companion in query cache - optimistic update for immediate UI refresh
+  const updateCompanionInCache = useCallback((event: NostrEvent) => {
    if (!user?.pubkey || !profile?.currentCompanion) return;
    
-    // Invalidate and update the companion query
-    queryClient.invalidateQueries({ 
-      queryKey: ['companion-blobbi', user.pubkey, profile.currentCompanion] 
-    });
+    // Parse the new event to get the updated companion
+    const parsed = parseBlobbiEvent(event);
+    if (!parsed) {
+      // Fallback to invalidation if parsing fails
+      queryClient.invalidateQueries({ 
+        queryKey: ['blobbi-collection', user.pubkey] 
+      });
+      return;
+    }
+    
+    // Optimistically update the blobbi-collection cache
+    // This ensures the companion layer sees the update immediately
+    queryClient.setQueryData<{ companionsByD: Record<string, BlobbiCompanion>; companions: BlobbiCompanion[] } | undefined>(
+      // Use partial key match - React Query will find any matching query
+      ['blobbi-collection', user.pubkey],
+      (prev) => {
+        if (!prev) return prev;
+        
+        // Update the specific companion in the record
+        const newCompanionsByD = {
+          ...prev.companionsByD,
+          [parsed.d]: parsed,
+        };
+        
+        // Rebuild companions array from the record
+        const newCompanions = Object.values(newCompanionsByD);
+        
+        return {
+          companionsByD: newCompanionsByD,
+          companions: newCompanions,
+        };
+      },
+    );
+    
+    // Also invalidate to trigger background refetch (ensures consistency)
    queryClient.invalidateQueries({ 
      queryKey: ['blobbi-collection', user.pubkey] 
    });
@@ -0,0 +1,187 @@
+/**
+ * useBlobbiSleepToggle — Standalone sleep/wake toggle for the companion.
+ *
+ * This hook mirrors the essential logic of BlobbiPage's `handleRest` but
+ * works independently — it fetches fresh event data from relays, publishes
+ * the state change, and updates the TanStack Query cache directly.
+ *
+ * This eliminates the dependency on BlobbiPage being mounted. The companion
+ * sleep button works on any page.
+ */
+
+import { useCallback, useRef } from 'react';
+import { useNostr } from '@nostrify/react';
+import { useQueryClient } from '@tanstack/react-query';
+
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+import { useBlobbonautProfile } from '@/hooks/useBlobbonautProfile';
+import { useNostrPublish } from '@/hooks/useNostrPublish';
+import { toast } from '@/hooks/useToast';
+
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';
+import {
+  KIND_BLOBBI_STATE,
+  updateBlobbiTags,
+  parseBlobbiEvent,
+  isValidBlobbiEvent,
+} from '@/blobbi/core/lib/blobbi';
+import { applyBlobbiDecay } from '@/blobbi/core/lib/blobbi-decay';
+import { getStreakTagUpdates } from '@/blobbi/actions/lib/blobbi-streak';
+import { trackDailyMissionProgress } from '@/blobbi/actions/lib/daily-mission-tracker';
+
+export interface UseBlobbiSleepToggleResult {
+  /** Toggle sleep/wake state. Resolves when published. */
+  toggleSleep: () => Promise<void>;
+  /** Whether a toggle is currently in progress. */
+  isPending: boolean;
+}
+
+export function useBlobbiSleepToggle(): UseBlobbiSleepToggleResult {
+  const { nostr } = useNostr();
+  const { user } = useCurrentUser();
+  const { mutateAsync: publishEvent } = useNostrPublish();
+  const queryClient = useQueryClient();
+  const { profile } = useBlobbonautProfile();
+
+  // Track pending state via ref to avoid re-renders.
+  // We only use this for the guard (no duplicate calls), not for rendering.
+  const pendingRef = useRef(false);
+
+  /** Fetch the latest companion event directly from relays. */
+  const fetchFreshCompanion = useCallback(async (
+    pubkey: string,
+    dTag: string,
+  ): Promise<BlobbiCompanion | null> => {
+    const events = await nostr.query([{
+      kinds: [KIND_BLOBBI_STATE],
+      authors: [pubkey],
+      '#d': [dTag],
+    }]);
+
+    const validEvents = events
+      .filter(isValidBlobbiEvent)
+      .sort((a, b) => b.created_at - a.created_at);
+
+    if (validEvents.length === 0) return null;
+    return parseBlobbiEvent(validEvents[0]) ?? null;
+  }, [nostr]);
+
+  /** Optimistically update the TanStack cache so the companion reacts immediately. */
+  const updateCache = useCallback((event: import('@nostrify/nostrify').NostrEvent, pubkey: string) => {
+    const parsed = parseBlobbiEvent(event);
+    if (!parsed) {
+      queryClient.invalidateQueries({ queryKey: ['blobbi-collection', pubkey] });
+      return;
+    }
+
+    // Optimistically update ALL blobbi-collection queries for this user.
+    // The cache key is ['blobbi-collection', pubkey, dListArray], so we use
+    // partial matching to find all entries regardless of dList shape.
+    type CollectionData = { companionsByD: Record<string, BlobbiCompanion>; companions: BlobbiCompanion[] };
+    const matchingQueries = queryClient.getQueriesData<CollectionData>({
+      queryKey: ['blobbi-collection', pubkey],
+    });
+
+    for (const [queryKey, data] of matchingQueries) {
+      if (!data) continue;
+      const newCompanionsByD = { ...data.companionsByD, [parsed.d]: parsed };
+      queryClient.setQueryData<CollectionData>(queryKey, {
+        companionsByD: newCompanionsByD,
+        companions: Object.values(newCompanionsByD),
+      });
+    }
+
+    // Also invalidate for background refetch to ensure eventual consistency
+    queryClient.invalidateQueries({ queryKey: ['blobbi-collection', pubkey] });
+  }, [queryClient]);
+
+  const toggleSleep = useCallback(async () => {
+    if (pendingRef.current) return;
+    if (!user?.pubkey || !profile?.currentCompanion) {
+      if (import.meta.env.DEV) {
+        console.warn('[SleepToggle] No user or no current companion');
+      }
+      return;
+    }
+
+    pendingRef.current = true;
+
+    try {
+      // Fetch the freshest event from relays (read-modify-write)
+      const companion = await fetchFreshCompanion(user.pubkey, profile.currentCompanion);
+      if (!companion) {
+        toast({
+          title: 'Cannot change state',
+          description: 'Companion not found. Please try again.',
+          variant: 'destructive',
+        });
+        return;
+      }
+
+      const isCurrentlySleeping = companion.state === 'sleeping';
+      const newState = isCurrentlySleeping ? 'active' : 'sleeping';
+
+      // Apply accumulated decay before the state change
+      const now = Math.floor(Date.now() / 1000);
+      const decayResult = applyBlobbiDecay({
+        stage: companion.stage,
+        state: companion.state,
+        stats: companion.stats,
+        lastDecayAt: companion.lastDecayAt,
+        now,
+      });
+
+      const nowStr = now.toString();
+
+      // Streak updates (putting to sleep/waking counts as care activity)
+      const streakUpdates = getStreakTagUpdates(companion) ?? {};
+
+      const newTags = updateBlobbiTags(companion.allTags, {
+        state: newState,
+        hunger: decayResult.stats.hunger.toString(),
+        happiness: decayResult.stats.happiness.toString(),
+        health: decayResult.stats.health.toString(),
+        hygiene: decayResult.stats.hygiene.toString(),
+        energy: decayResult.stats.energy.toString(),
+        ...streakUpdates,
+        last_interaction: nowStr,
+        last_decay_at: nowStr,
+      });
+
+      const event = await publishEvent({
+        kind: KIND_BLOBBI_STATE,
+        content: companion.event.content,
+        tags: newTags,
+      });
+
+      // Optimistic cache update + background invalidation
+      updateCache(event, user.pubkey);
+
+      toast({
+        title: isCurrentlySleeping ? 'Woke up!' : 'Resting...',
+        description: isCurrentlySleeping
+          ? 'Your Blobbi is now awake and active!'
+          : 'Your Blobbi is taking a rest.',
+      });
+
+      // Track daily mission progress (only when putting to sleep)
+      if (!isCurrentlySleeping) {
+        trackDailyMissionProgress('sleep', 1, user.pubkey);
+      }
+    } catch (error) {
+      console.error('[SleepToggle] Failed:', error);
+      toast({
+        title: 'Failed to update',
+        description: error instanceof Error ? error.message : 'Unknown error',
+        variant: 'destructive',
+      });
+    } finally {
+      pendingRef.current = false;
+    }
+  }, [user?.pubkey, profile?.currentCompanion, fetchFreshCompanion, publishEvent, updateCache]);
+
+  return {
+    toggleSleep,
+    isPending: false, // ref-based, so always false for render — prevents unnecessary re-renders
+  };
+}
@@ -19,7 +19,7 @@ import { useLocation } from 'react-router-dom';

 import { useBlobbonautProfile } from '@/hooks/useBlobbonautProfile';
 import { getShopItemById } from '@/blobbi/shop/lib/blobbi-shop-items';
-import type { StorageItem } from '@/lib/blobbi';
+import type { StorageItem } from '@/blobbi/core/lib/blobbi';
 import { canUseItemForStage } from '@/blobbi/actions/lib/blobbi-action-utils';

 import type {
@@ -82,7 +82,6 @@ export const CATEGORY_TO_ACTION: Record<ShopItemCategory, InventoryAction | null
  toy: 'play',
  medicine: 'medicine',
  hygiene: 'clean',
-  accessory: null, // Accessories are cosmetic, not usable
 };

 /**
@@ -5,7 +5,8 @@
 * decoupled from app-specific concerns.
 */

-import type { BlobbiVisualTraits } from '@/lib/blobbi';
+import type { BlobbiVisualTraits, BlobbiStats } from '@/blobbi/core/lib/blobbi';
+import type { BlobbiState } from '@/blobbi/core/types/blobbi';

 // ─── Companion State Machine ──────────────────────────────────────────────────

@@ -176,6 +177,10 @@ export interface CompanionData {
  visualTraits: BlobbiVisualTraits;
  /** Current energy level (0-100) - affects walking speed */
  energy: number;
+  /** Current stats for status-based visual reactions */
+  stats: BlobbiStats;
+  /** Current companion state (e.g., 'sleeping') */
+  state?: BlobbiState;
  /** Adult evolution form type (e.g., 'catti', 'pupp', 'buni') - only for adults */
  adultType?: string;
  /** Deterministic seed for deriving traits */
@@ -318,8 +323,6 @@ export interface CompanionContextValue {
  state: CompanionState;
  /** Current motion state */
  motion: CompanionMotion;
-  /** Current gaze state */
-  gaze: GazeState;
  /** Start dragging the companion */
  startDrag: () => void;
  /** Update drag position */
@@ -44,13 +44,12 @@ export function calculateFloatAnimation(time: number, isMoving: boolean): FloatO
    // Multiple frequencies create a bouncy, charming walk
    const t = time / 1000; // Convert to seconds for easier frequency tuning
    
-    // Primary bob - quick rhythmic bounce (about 2 bounces per second)
-    const primaryBob = Math.sin(t * 12) * 3;
-    // Secondary bob - slower wave that adds variation
-    const secondaryBob = Math.sin(t * 5 + 0.5) * 1.5;
-    // Slight lift during walk - don't stay on ground
-    const baseLift = -2;
-    const yOffset = baseLift + primaryBob * 0.5 + secondaryBob * 0.3;
+    // Vertical bob oscillates symmetrically around zero so Blobbi's base
+    // stays anchored to the ground line. The original baseLift = -2 was
+    // removed because it biased the offset permanently upward.
+    const primaryBob = Math.sin(t * 12) * 2;     // Reduced from *3: less vertical energy
+    const secondaryBob = Math.sin(t * 5 + 0.5) * 1;
+    const yOffset = primaryBob * 0.4 + secondaryBob * 0.25;
    
    // Horizontal sway - playful side-to-side motion
    const primarySway = Math.sin(t * 6) * 2;
@@ -0,0 +1,299 @@
+import { useCallback } from 'react';
+import type { NostrEvent } from '@nostrify/nostrify';
+
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+import { useNostrPublish } from '@/hooks/useNostrPublish';
+import { toast } from '@/hooks/useToast';
+
+import {
+  KIND_BLOBBI_STATE,
+  KIND_BLOBBONAUT_PROFILE,
+  buildMigrationTags,
+  generatePetId10,
+  getCanonicalBlobbiD,
+  migratePetInHas,
+  updateBlobbonautTags,
+  parseBlobbiEvent,
+  parseStorageTags,
+  type BlobbiCompanion,
+  type BlobbonautProfile,
+  type StorageItem,
+} from '../lib/blobbi';
+
+/**
+ * Result of a successful migration.
+ */
+export interface MigrationResult {
+  /** The new canonical d-tag */
+  canonicalD: string;
+  /** The published canonical Blobbi event */
+  event: NostrEvent;
+  /** The parsed canonical BlobbiCompanion */
+  companion: BlobbiCompanion;
+  /** The updated profile event */
+  profileEvent: NostrEvent;
+  /** The updated profile tags (canonical has, current_companion, etc.) */
+  profileTags: string[][];
+  /** The profile storage (unchanged during migration, but fresh from migrated profile) */
+  profileStorage: StorageItem[];
+}
+
+/**
+ * Options for the migration helper.
+ */
+export interface EnsureCanonicalOptions {
+  /** The companion to check/migrate */
+  companion: BlobbiCompanion;
+  /** The user's profile */
+  profile: BlobbonautProfile;
+  /** Callback to update the profile event in query cache */
+  updateProfileEvent: (event: NostrEvent) => void;
+  /** Callback to update the companion event in query cache */
+  updateCompanionEvent: (event: NostrEvent) => void;
+  /** Callback to update localStorage selection if it was pointing to legacy d */
+  updateStoredSelectedD?: (newD: string) => void;
+  /** Callback to invalidate companion query */
+  invalidateCompanion?: () => void;
+  /** Callback to invalidate profile query */
+  invalidateProfile?: () => void;
+}
+
+/**
+ * Result of ensureCanonicalBlobbiBeforeAction.
+ */
+export interface EnsureCanonicalResult {
+  /** Whether the companion was migrated */
+  wasMigrated: boolean;
+  /** The canonical companion (either the original or the migrated one) */
+  companion: BlobbiCompanion;
+  /** The canonical event tags to use for the action */
+  allTags: string[][];
+  /** The event content to use */
+  content: string;
+  /** 
+   * The latest profile tags to use for profile updates.
+   * IMPORTANT: Always use these instead of profile.allTags from hook closure
+   * to avoid restoring stale/legacy values after migration.
+   */
+  profileAllTags: string[][];
+  /**
+   * The latest profile storage to use.
+   * Use this as the base for storage modifications.
+   */
+  profileStorage: StorageItem[];
+}
+
+/**
+ * Hook providing centralized migration logic for Blobbi companions.
+ * 
+ * This hook should be used by all action handlers to ensure legacy Blobbis
+ * are automatically migrated before any interaction.
+ * 
+ * Usage:
+ * ```ts
+ * const { ensureCanonicalBlobbiBeforeAction } = useBlobbiMigration();
+ * 
+ * const handleFeed = async () => {
+ *   const result = await ensureCanonicalBlobbiBeforeAction({
+ *     companion,
+ *     profile,
+ *     updateProfileEvent,
+ *     updateCompanionEvent,
+ *     updateStoredSelectedD: setStoredSelectedD,
+ *   });
+ *   
+ *   if (!result) return; // Migration failed
+ *   
+ *   // Continue with the action using result.companion and result.allTags
+ *   const newTags = updateBlobbiTags(result.allTags, { ... });
+ *   // ... publish event
+ * };
+ * ```
+ */
+export function useBlobbiMigration() {
+  const { user } = useCurrentUser();
+  const { mutateAsync: publishEvent } = useNostrPublish();
+  
+  /**
+   * Migrate a legacy Blobbi to canonical format.
+   * 
+   * This function:
+   * 1. Generates a canonical d-tag
+   * 2. Ensures a seed exists (generates one if missing)
+   * 3. Preserves name, stage, stats, state, timestamps
+   * 4. Publishes a canonical 31124 event
+   * 5. Updates the Blobbonaut profile (kind 11125)
+   * 6. Updates local state (query cache, localStorage)
+   */
+  const migrateLegacyBlobbi = useCallback(async (
+    options: EnsureCanonicalOptions
+  ): Promise<MigrationResult | null> => {
+    const {
+      companion,
+      profile,
+      updateProfileEvent,
+      updateCompanionEvent,
+      updateStoredSelectedD,
+      invalidateCompanion,
+      invalidateProfile,
+    } = options;
+    
+    if (!user?.pubkey) {
+      console.error('[Blobbi Migration] No user pubkey');
+      return null;
+    }
+    
+    console.log('[Blobbi Migration] Starting migration for:', companion.d);
+    
+    try {
+      // Generate new canonical d-tag
+      const newPetId = generatePetId10();
+      const canonicalD = getCanonicalBlobbiD(user.pubkey, newPetId);
+      
+      // Build migration tags (preserves name, stage, stats, generates seed if missing)
+      const migrationTags = buildMigrationTags(companion.event, newPetId, user.pubkey);
+      
+      console.log('[Blobbi Migration] Publishing canonical event with d:', canonicalD);
+      
+      // Publish the canonical Blobbi state
+      const canonicalEvent = await publishEvent({
+        kind: KIND_BLOBBI_STATE,
+        content: companion.event.content || `${companion.name} is a ${companion.stage} Blobbi.`,
+        tags: migrationTags,
+      });
+      
+      // Parse the new event to get the canonical companion
+      const canonicalCompanion = parseBlobbiEvent(canonicalEvent);
+      if (!canonicalCompanion) {
+        throw new Error('Failed to parse migrated event');
+      }
+      
+      // Update profile: replace legacy d with canonical d in has[], update current_companion
+      const updatedHas = migratePetInHas(profile.has, companion.d, canonicalD);
+      const shouldUpdateCurrentCompanion = profile.currentCompanion === companion.d;
+      
+      const profileUpdates: Record<string, string | string[]> = {
+        has: updatedHas,
+      };
+      
+      if (shouldUpdateCurrentCompanion) {
+        profileUpdates.current_companion = canonicalD;
+      }
+      
+      const profileTags = updateBlobbonautTags(profile.allTags, profileUpdates);
+      
+      console.log('[Blobbi Migration] Publishing updated profile');
+      
+      const profileEvent = await publishEvent({
+        kind: KIND_BLOBBONAUT_PROFILE,
+        content: '',
+        tags: profileTags,
+      });
+      
+      // Update query caches
+      updateProfileEvent(profileEvent);
+      updateCompanionEvent(canonicalEvent);
+      
+      // Update localStorage selection if it was pointing to legacy d
+      if (updateStoredSelectedD) {
+        console.log('[Blobbi Migration] Updating localStorage selection:', canonicalD);
+        updateStoredSelectedD(canonicalD);
+      }
+      
+      // Invalidate queries to refetch fresh data
+      invalidateCompanion?.();
+      invalidateProfile?.();
+      
+      toast({
+        title: 'Pet upgraded!',
+        description: `${companion.name} has been migrated to the new format.`,
+      });
+      
+      console.log('[Blobbi Migration] Migration complete:', {
+        legacyD: companion.d,
+        canonicalD,
+      });
+      
+      // Parse storage from the migrated profile tags
+      // Storage itself doesn't change during migration, but we need fresh tags
+      const migratedStorage = parseStorageTags(profileTags);
+      
+      return {
+        canonicalD,
+        event: canonicalEvent,
+        companion: canonicalCompanion,
+        profileEvent,
+        profileTags,
+        profileStorage: migratedStorage,
+      };
+    } catch (error) {
+      console.error('[Blobbi Migration] Migration failed:', error);
+      toast({
+        title: 'Migration failed',
+        description: error instanceof Error ? error.message : 'Unknown error',
+        variant: 'destructive',
+      });
+      return null;
+    }
+  }, [user?.pubkey, publishEvent]);
+  
+  /**
+   * Ensure a Blobbi is in canonical format before performing an action.
+   * 
+   * If the companion is legacy, it will be migrated first.
+   * Returns the canonical companion to use for the action.
+   * 
+   * Flow:
+   * 1. Check if Blobbi is legacy
+   * 2. If legacy: migrate Blobbi
+   * 3. Return the resolved canonical Blobbi
+   * 
+   * All interaction handlers should call this before publishing events.
+   */
+  const ensureCanonicalBlobbiBeforeAction = useCallback(async (
+    options: EnsureCanonicalOptions
+  ): Promise<EnsureCanonicalResult | null> => {
+    const { companion, profile } = options;
+    
+    // Check if the companion needs migration
+    if (companion.isLegacy) {
+      console.log('[Blobbi Migration] Legacy companion detected, migrating before action');
+      
+      const migrationResult = await migrateLegacyBlobbi(options);
+      
+      if (!migrationResult) {
+        // Migration failed, cannot proceed with action
+        return null;
+      }
+      
+      // Return the canonical companion AND migrated profile context
+      // CRITICAL: Consumers must use profileAllTags instead of profile.allTags
+      // to avoid restoring stale/legacy values
+      return {
+        wasMigrated: true,
+        companion: migrationResult.companion,
+        allTags: migrationResult.event.tags,
+        content: migrationResult.event.content,
+        profileAllTags: migrationResult.profileTags,
+        profileStorage: migrationResult.profileStorage,
+      };
+    }
+    
+    // Companion is already canonical, return profile as-is
+    return {
+      wasMigrated: false,
+      companion,
+      allTags: companion.allTags,
+      content: companion.event.content,
+      profileAllTags: profile.allTags,
+      profileStorage: profile.storage,
+    };
+  }, [migrateLegacyBlobbi]);
+  
+  return {
+    /** Migrate a legacy Blobbi to canonical format */
+    migrateLegacyBlobbi,
+    /** Ensure a Blobbi is canonical before an action, migrating if necessary */
+    ensureCanonicalBlobbiBeforeAction,
+  };
+}
@@ -0,0 +1,198 @@
+import { useCallback, useMemo } from 'react';
+import { useNostr } from '@nostrify/react';
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import type { NostrEvent } from '@nostrify/nostrify';
+
+import { useCurrentUser } from '@/hooks/useCurrentUser';
+import {
+  KIND_BLOBBI_STATE,
+  isValidBlobbiEvent,
+  parseBlobbiEvent,
+  type BlobbiCompanion,
+} from '../lib/blobbi';
+
+/** Maximum number of d-tags per query chunk to avoid relay issues */
+const CHUNK_SIZE = 20;
+
+/**
+ * Split an array into chunks of a given size.
+ */
+function chunkArray<T>(array: T[], size: number): T[][] {
+  const chunks: T[][] = [];
+  for (let i = 0; i < array.length; i += size) {
+    chunks.push(array.slice(i, i + size));
+  }
+  return chunks;
+}
+
+/**
+ * Hook to fetch ALL Blobbi companions (Kind 31124) owned by the logged-in user.
+ * 
+ * Features:
+ * - Fetches ALL pets by d-tag list (no limit: 1)
+ * - Chunks large d-lists into multiple queries for relay compatibility
+ * - Keeps only the newest event per d-tag
+ * - Returns both a lookup record and array of companions
+ * - Provides invalidation and optimistic update helpers
+ */
+export function useBlobbisCollection(dList: string[] | undefined) {
+  const { nostr } = useNostr();
+  const { user } = useCurrentUser();
+  const queryClient = useQueryClient();
+  
+  // Create a stable query key based on sorted d-tags
+  const sortedDList = useMemo(() => {
+    if (!dList || dList.length === 0) return null;
+    return [...dList].sort();
+  }, [dList]);
+  
+  const queryKeyDTags = sortedDList?.join(',') ?? '';
+  
+  // Main query to fetch all companions from relays
+  const query = useQuery({
+    queryKey: ['blobbi-collection', user?.pubkey, queryKeyDTags],
+    queryFn: async ({ signal }) => {
+      if (!user?.pubkey || !sortedDList || sortedDList.length === 0) {
+        console.log('[useBlobbisCollection] No pubkey or empty dList, returning empty');
+        return { companionsByD: {}, companions: [] };
+      }
+      
+      // Log the dList we're about to query
+      console.log('[Blobbi] dList:', sortedDList);
+      
+      // Chunk the d-list for relay compatibility
+      const chunks = chunkArray(sortedDList, CHUNK_SIZE);
+      console.log('[useBlobbisCollection] Splitting into', chunks.length, 'chunk(s)');
+      
+      // Query all chunks in parallel
+      const allEvents: NostrEvent[] = [];
+      
+      for (const chunk of chunks) {
+        const filter = {
+          kinds: [KIND_BLOBBI_STATE],
+          authors: [user.pubkey],
+          '#d': chunk,
+          // IMPORTANT: No limit - fetch ALL pets matching the d-tags
+        };
+        
+        // Log the filter immediately before query
+        console.log('[Blobbi] 31124 query filter:', JSON.stringify(filter, null, 2));
+        
+        const events = await nostr.query([filter], { signal });
+        allEvents.push(...events);
+        
+        console.log('[useBlobbisCollection] Chunk returned', events.length, 'events');
+      }
+      
+      console.log('[useBlobbisCollection] Total events received:', allEvents.length);
+      
+      // Filter to valid events
+      const validEvents = allEvents.filter(isValidBlobbiEvent);
+      
+      console.log('[useBlobbisCollection] Valid events:', validEvents.length);
+      
+      // Group events by d-tag and keep only the newest per d
+      const eventsByD = new Map<string, NostrEvent>();
+      
+      for (const event of validEvents) {
+        const dTag = event.tags.find(([name]) => name === 'd')?.[1];
+        if (!dTag) continue;
+        
+        const existing = eventsByD.get(dTag);
+        if (!existing || event.created_at > existing.created_at) {
+          eventsByD.set(dTag, event);
+        }
+      }
+      
+      // Parse all events into BlobbiCompanion objects
+      const companionsByD: Record<string, BlobbiCompanion> = {};
+      const companions: BlobbiCompanion[] = [];
+      
+      for (const [dTag, event] of eventsByD) {
+        const parsed = parseBlobbiEvent(event);
+        if (parsed) {
+          companionsByD[dTag] = parsed;
+          companions.push(parsed);
+        }
+      }
+      
+      console.log('[useBlobbisCollection] Parsed companions:', {
+        count: companions.length,
+        dTags: Object.keys(companionsByD),
+      });
+      
+      return { companionsByD, companions };
+    },
+    enabled: !!user?.pubkey && !!sortedDList && sortedDList.length > 0,
+    staleTime: 30_000, // 30 seconds
+    gcTime: 5 * 60 * 1000, // 5 minutes
+    refetchOnWindowFocus: false,
+    refetchOnReconnect: true,
+    retry: 3,
+    retryDelay: (attemptIndex) => Math.min(1000 * 2 ** attemptIndex, 30000),
+  });
+  
+  // Helper to invalidate and refetch after publishing
+  const invalidate = useCallback(() => {
+    if (user?.pubkey && queryKeyDTags) {
+      queryClient.invalidateQueries({
+        queryKey: ['blobbi-collection', user.pubkey, queryKeyDTags],
+      });
+    }
+  }, [queryClient, user?.pubkey, queryKeyDTags]);
+  
+  // Update a single companion event in the query cache (optimistic update)
+  const updateCompanionEvent = useCallback((event: NostrEvent) => {
+    const parsed = parseBlobbiEvent(event);
+    if (!parsed || !user?.pubkey) return;
+    
+    queryClient.setQueryData<{ companionsByD: Record<string, BlobbiCompanion>; companions: BlobbiCompanion[] }>(
+      ['blobbi-collection', user.pubkey, queryKeyDTags],
+      (prev) => {
+        if (!prev) {
+          return {
+            companionsByD: { [parsed.d]: parsed },
+            companions: [parsed],
+          };
+        }
+        
+        // Update the specific companion in the record
+        const newCompanionsByD = {
+          ...prev.companionsByD,
+          [parsed.d]: parsed,
+        };
+        
+        // Rebuild companions array from the record
+        const newCompanions = Object.values(newCompanionsByD);
+        
+        return {
+          companionsByD: newCompanionsByD,
+          companions: newCompanions,
+        };
+      }
+    );
+  }, [queryClient, user?.pubkey, queryKeyDTags]);
+  
+  // Memoize return values for stability
+  const companionsByD = query.data?.companionsByD ?? {};
+  const companions = query.data?.companions ?? [];
+  
+  return {
+    /** Record of companions keyed by d-tag */
+    companionsByD,
+    /** Array of all companions (newest per d-tag) */
+    companions,
+    /** True only when query is loading and no data available */
+    isLoading: query.isLoading,
+    /** True when actively fetching */
+    isFetching: query.isFetching,
+    /** True when data is stale */
+    isStale: query.isStale,
+    /** Query error if any */
+    error: query.error,
+    /** Invalidate and refetch the collection */
+    invalidate,
+    /** Optimistically update a single companion in the cache */
+    updateCompanionEvent,
+  };
+}
@@ -0,0 +1,122 @@
+/**
+ * Hook for projecting Blobbi decay state in the UI.
+ * 
+ * This hook provides a local projection of decay without publishing events.
+ * It recalculates every 60 seconds while the component is mounted.
+ * 
+ * The projected state is for UI display only. Actual mutations must
+ * recalculate from the persisted state before publishing.
+ * 
+ * @see docs/blobbi/decay-system.md
+ */
+
+import { useState, useEffect, useMemo } from 'react';
+
+import type { BlobbiCompanion, BlobbiStats } from '../lib/blobbi';
+import { applyBlobbiDecay, getVisibleStatsWithValues, type DecayResult } from '@/blobbi/core/lib/blobbi-decay';
+
+/** UI refresh interval in milliseconds (60 seconds) */
+const UI_REFRESH_INTERVAL_MS = 60_000;
+
+/**
+ * Projected Blobbi state for UI display.
+ */
+export interface ProjectedBlobbiState {
+  /** Stats after applying projected decay */
+  stats: BlobbiStats;
+  /** Visible stats for the current stage with status indicators */
+  visibleStats: Array<{
+    stat: keyof BlobbiStats;
+    value: number;
+    status: 'critical' | 'warning' | 'normal';
+  }>;
+  /** Time elapsed since last decay (seconds) */
+  elapsedSeconds: number;
+  /** Timestamp of the projection calculation */
+  projectedAt: number;
+  /** Whether this is a fresh projection (recalculated this render) */
+  isFresh: boolean;
+}
+
+/**
+ * Hook to get a projected Blobbi state with decay applied.
+ * 
+ * Features:
+ * - Immediately calculates projected state on mount/companion change
+ * - Recalculates every 60 seconds while mounted
+ * - Pure calculation - does not publish any events
+ * - Returns both full stats and stage-appropriate visible stats
+ * 
+ * @param companion - The persisted Blobbi companion (source of truth)
+ * @returns Projected state with decay applied, or null if no companion
+ */
+export function useProjectedBlobbiState(
+  companion: BlobbiCompanion | null
+): ProjectedBlobbiState | null {
+  // Track when we last recalculated
+  const [refreshTick, setRefreshTick] = useState(0);
+  
+  // Set up 60-second refresh interval
+  useEffect(() => {
+    if (!companion) return;
+    
+    const interval = setInterval(() => {
+      setRefreshTick(t => t + 1);
+    }, UI_REFRESH_INTERVAL_MS);
+    
+    return () => clearInterval(interval);
+  }, [companion]);
+  
+  // Calculate projected state
+  const projectedState = useMemo((): ProjectedBlobbiState | null => {
+    if (!companion) return null;
+    
+    const now = Math.floor(Date.now() / 1000);
+    
+    // Apply decay from persisted state
+    const decayResult: DecayResult = applyBlobbiDecay({
+      stage: companion.stage,
+      state: companion.state,
+      stats: companion.stats,
+      lastDecayAt: companion.lastDecayAt,
+      now,
+    });
+    
+    // Get visible stats for the stage
+    const visibleStats = getVisibleStatsWithValues(companion.stage, decayResult.stats);
+    
+    return {
+      stats: decayResult.stats,
+      visibleStats,
+      elapsedSeconds: decayResult.elapsedSeconds,
+      projectedAt: now,
+      isFresh: true,
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- refreshTick triggers recalculation
+  }, [companion, refreshTick]);
+  
+  return projectedState;
+}
+
+/**
+ * Calculate projected decay for a companion at a specific timestamp.
+ * 
+ * This is a utility function for use outside of React components,
+ * such as in mutation handlers before publishing.
+ * 
+ * @param companion - The persisted Blobbi companion
+ * @param now - Unix timestamp to calculate decay to (defaults to current time)
+ * @returns Decay result with updated stats
+ */
+export function calculateProjectedDecay(
+  companion: BlobbiCompanion,
+  now?: number
+): DecayResult {
+  return applyBlobbiDecay({
+    stage: companion.stage,
+    state: companion.state,
+    stats: companion.stats,
+    lastDecayAt: companion.lastDecayAt,
+    now: now ?? Math.floor(Date.now() / 1000),
+  });
+}
@@ -0,0 +1,517 @@
+/**
+ * Blobbi Decay System
+ * 
+ * This module implements the continuous proportional decay system for Blobbi stats.
+ * 
+ * Key principles:
+ * - Pure, deterministic calculation based on elapsed time
+ * - Floored stat changes before application
+ * - Stats clamped to 0-100 range
+ * - Stage-specific decay rates and health modifiers
+ * - Persisted state is the source of truth
+ * 
+ * @see docs/blobbi/decay-system.md for full documentation
+ */
+
+import type { BlobbiStage, BlobbiState, BlobbiStats } from './blobbi';
+import { STAT_MIN, STAT_MAX } from './blobbi';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * Result of applying decay to a Blobbi.
+ * Contains updated stats and metadata about the calculation.
+ */
+export interface DecayResult {
+  /** Updated stats after decay (clamped to 0-100) */
+  stats: BlobbiStats;
+  /** Elapsed time in seconds that was used for decay calculation */
+  elapsedSeconds: number;
+  /** The timestamp that should be set as the new last_decay_at */
+  newDecayTimestamp: number;
+}
+
+/**
+ * Input parameters for decay calculation.
+ * Uses the persisted Blobbi state as source of truth.
+ */
+export interface DecayInput {
+  /** Current life stage */
+  stage: BlobbiStage;
+  /** Current activity state (awake/sleeping) */
+  state: BlobbiState;
+  /** Current stats from persisted state */
+  stats: Partial<BlobbiStats>;
+  /** Unix timestamp of last decay application */
+  lastDecayAt: number | undefined;
+  /** Current unix timestamp (defaults to now) */
+  now?: number;
+}
+
+// ─── Constants: Decay Rates ───────────────────────────────────────────────────
+
+/**
+ * Baby stage decay rates (per hour).
+ * 
+ * Design goal: Needs attention every 3-5 hours.
+ */
+const BABY_DECAY = {
+  hunger: -7.0,
+  happiness: -4.0,
+  hygiene: -5.0,
+  energy: {
+    awake: -8.0,
+    sleeping: 6.0,  // Regeneration
+  },
+  health: {
+    base: -0.75,
+    hungerBelow70: -0.75,
+    hungerBelow40: -1.25,
+    hygieneBelow70: -0.75,
+    hygieneBelow40: -1.25,
+    energyBelow50: -0.5,
+    energyBelow25: -1.0,
+    happinessBelow50: -0.5,
+    happinessBelow25: -1.0,
+    // Regeneration when all stats are >= 80
+    regenThreshold: 80,
+    regenRate: 1.5,
+  },
+} as const;
+
+/**
+ * Adult stage decay rates (per hour).
+ * 
+ * Design goal: Needs attention every 5-7 hours.
+ */
+const ADULT_DECAY = {
+  hunger: -4.5,
+  happiness: -2.5,
+  hygiene: -3.5,
+  energy: {
+    awake: -5.0,
+    sleeping: 5.0,  // Regeneration
+  },
+  health: {
+    base: -0.4,
+    hungerBelow60: -0.5,
+    hungerBelow30: -1.0,
+    hygieneBelow60: -0.5,
+    hygieneBelow30: -1.0,
+    energyBelow40: -0.4,
+    energyBelow20: -0.8,
+    happinessBelow40: -0.4,
+    happinessBelow20: -0.8,
+    // Regeneration when all stats are >= 80
+    regenThreshold: 80,
+    regenRate: 1.0,
+  },
+} as const;
+
+// ─── Constants: Warning Thresholds ────────────────────────────────────────────
+
+/**
+ * Warning thresholds by stage.
+ * Warning = stat below this value indicates the Blobbi needs attention.
+ */
+export const WARNING_THRESHOLDS = {
+  egg: {
+    hygiene: 75,
+    health: 75,
+    happiness: 75,
+  },
+  baby: {
+    hunger: 65,
+    happiness: 65,
+    hygiene: 65,
+    energy: 65,
+    health: 65,
+  },
+  adult: {
+    hunger: 60,
+    happiness: 60,
+    hygiene: 60,
+    energy: 60,
+    health: 60,
+  },
+} as const;
+
+/**
+ * Critical thresholds by stage.
+ * Critical = stat below this value indicates urgent attention needed.
+ */
+export const CRITICAL_THRESHOLDS = {
+  egg: {
+    hygiene: 45,
+    health: 45,
+    happiness: 45,
+  },
+  baby: {
+    hunger: 35,
+    happiness: 35,
+    hygiene: 35,
+    energy: 25,
+    health: 35,
+  },
+  adult: {
+    hunger: 30,
+    happiness: 30,
+    hygiene: 30,
+    energy: 20,
+    health: 30,
+  },
+} as const;
+
+// ─── Helper Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Clamp a value to the STAT_MIN-STAT_MAX range (1-100).
+ * Stats can never reach true zero - minimum is always 1.
+ */
+function clamp(value: number): number {
+  return Math.max(STAT_MIN, Math.min(STAT_MAX, value));
+}
+
+/**
+ * Get stat value with fallback to 100 (full).
+ */
+function getStat(stats: Partial<BlobbiStats>, key: keyof BlobbiStats): number {
+  return stats[key] ?? 100;
+}
+
+/**
+ * Convert hours to the elapsed time unit for calculation.
+ * @param hours - Elapsed hours
+ * @returns Rate multiplier for the elapsed time
+ */
+function hoursFromSeconds(seconds: number): number {
+  return seconds / 3600;
+}
+
+/**
+ * Round a stat delta toward zero (truncate fractional part).
+ * 
+ * CRITICAL: We use Math.trunc() instead of Math.floor() because:
+ * - Math.floor(-0.5) = -1 (rounds down, applying decay even with tiny elapsed time)
+ * - Math.trunc(-0.5) = 0 (rounds toward zero, no decay applied)
+ * 
+ * This prevents the bug where any action within seconds of the last action
+ * would still apply -1 decay even though insufficient time passed.
+ * 
+ * @param delta - Calculated stat change (can be positive or negative)
+ * @returns Integer delta to apply
+ */
+function roundDelta(delta: number): number {
+  return Math.trunc(delta);
+}
+
+// ─── Stage-Specific Decay Calculators ─────────────────────────────────────────
+
+/**
+ * Calculate egg stage decay.
+ * 
+ * Eggs only decay hygiene, health, and happiness.
+ * Hunger and energy are fixed at 100.
+ */
+function calculateEggDecay(
+  stats: Partial<BlobbiStats>,
+  _elapsedHours: number
+): BlobbiStats {
+  // Eggs do not decay — all stats remain fixed until hatching.
+  return {
+    hunger: 100,
+    energy: 100,
+    hygiene: getStat(stats, 'hygiene'),
+    health: getStat(stats, 'health'),
+    happiness: getStat(stats, 'happiness'),
+  };
+}
+
+/**
+ * Calculate baby stage decay.
+ */
+function calculateBabyDecay(
+  stats: Partial<BlobbiStats>,
+  state: BlobbiState,
+  elapsedHours: number
+): BlobbiStats {
+  const isSleeping = state === 'sleeping';
+  
+  // Get current values
+  let hunger = getStat(stats, 'hunger');
+  let happiness = getStat(stats, 'happiness');
+  let hygiene = getStat(stats, 'hygiene');
+  let energy = getStat(stats, 'energy');
+  let health = getStat(stats, 'health');
+  
+  // Calculate basic stat decay/regen
+  const hungerDelta = BABY_DECAY.hunger * elapsedHours;
+  const happinessDelta = BABY_DECAY.happiness * elapsedHours;
+  const hygieneDelta = BABY_DECAY.hygiene * elapsedHours;
+  const energyDelta = (isSleeping ? BABY_DECAY.energy.sleeping : BABY_DECAY.energy.awake) * elapsedHours;
+  
+  // Apply basic deltas
+  hunger = clamp(hunger + roundDelta(hungerDelta));
+  happiness = clamp(happiness + roundDelta(happinessDelta));
+  hygiene = clamp(hygiene + roundDelta(hygieneDelta));
+  energy = clamp(energy + roundDelta(energyDelta));
+  
+  // Calculate health (complex conditional decay + possible regen)
+  let healthDelta = BABY_DECAY.health.base * elapsedHours;
+  
+  // Hunger penalties
+  if (hunger < 70) healthDelta += BABY_DECAY.health.hungerBelow70 * elapsedHours;
+  if (hunger < 40) healthDelta += BABY_DECAY.health.hungerBelow40 * elapsedHours;
+  
+  // Hygiene penalties
+  if (hygiene < 70) healthDelta += BABY_DECAY.health.hygieneBelow70 * elapsedHours;
+  if (hygiene < 40) healthDelta += BABY_DECAY.health.hygieneBelow40 * elapsedHours;
+  
+  // Energy penalties
+  if (energy < 50) healthDelta += BABY_DECAY.health.energyBelow50 * elapsedHours;
+  if (energy < 25) healthDelta += BABY_DECAY.health.energyBelow25 * elapsedHours;
+  
+  // Happiness penalties
+  if (happiness < 50) healthDelta += BABY_DECAY.health.happinessBelow50 * elapsedHours;
+  if (happiness < 25) healthDelta += BABY_DECAY.health.happinessBelow25 * elapsedHours;
+  
+  // Health regeneration (all stats >= 80)
+  const threshold = BABY_DECAY.health.regenThreshold;
+  if (hunger >= threshold && happiness >= threshold && hygiene >= threshold && energy >= threshold) {
+    healthDelta += BABY_DECAY.health.regenRate * elapsedHours;
+  }
+  
+  health = clamp(health + roundDelta(healthDelta));
+  
+  return { hunger, happiness, hygiene, energy, health };
+}
+
+/**
+ * Calculate adult stage decay.
+ */
+function calculateAdultDecay(
+  stats: Partial<BlobbiStats>,
+  state: BlobbiState,
+  elapsedHours: number
+): BlobbiStats {
+  const isSleeping = state === 'sleeping';
+  
+  // Get current values
+  let hunger = getStat(stats, 'hunger');
+  let happiness = getStat(stats, 'happiness');
+  let hygiene = getStat(stats, 'hygiene');
+  let energy = getStat(stats, 'energy');
+  let health = getStat(stats, 'health');
+  
+  // Calculate basic stat decay/regen
+  const hungerDelta = ADULT_DECAY.hunger * elapsedHours;
+  const happinessDelta = ADULT_DECAY.happiness * elapsedHours;
+  const hygieneDelta = ADULT_DECAY.hygiene * elapsedHours;
+  const energyDelta = (isSleeping ? ADULT_DECAY.energy.sleeping : ADULT_DECAY.energy.awake) * elapsedHours;
+  
+  // Apply basic deltas
+  hunger = clamp(hunger + roundDelta(hungerDelta));
+  happiness = clamp(happiness + roundDelta(happinessDelta));
+  hygiene = clamp(hygiene + roundDelta(hygieneDelta));
+  energy = clamp(energy + roundDelta(energyDelta));
+  
+  // Calculate health (complex conditional decay + possible regen)
+  let healthDelta = ADULT_DECAY.health.base * elapsedHours;
+  
+  // Hunger penalties
+  if (hunger < 60) healthDelta += ADULT_DECAY.health.hungerBelow60 * elapsedHours;
+  if (hunger < 30) healthDelta += ADULT_DECAY.health.hungerBelow30 * elapsedHours;
+  
+  // Hygiene penalties
+  if (hygiene < 60) healthDelta += ADULT_DECAY.health.hygieneBelow60 * elapsedHours;
+  if (hygiene < 30) healthDelta += ADULT_DECAY.health.hygieneBelow30 * elapsedHours;
+  
+  // Energy penalties
+  if (energy < 40) healthDelta += ADULT_DECAY.health.energyBelow40 * elapsedHours;
+  if (energy < 20) healthDelta += ADULT_DECAY.health.energyBelow20 * elapsedHours;
+  
+  // Happiness penalties
+  if (happiness < 40) healthDelta += ADULT_DECAY.health.happinessBelow40 * elapsedHours;
+  if (happiness < 20) healthDelta += ADULT_DECAY.health.happinessBelow20 * elapsedHours;
+  
+  // Health regeneration (all stats >= 80)
+  const threshold = ADULT_DECAY.health.regenThreshold;
+  if (hunger >= threshold && happiness >= threshold && hygiene >= threshold && energy >= threshold) {
+    healthDelta += ADULT_DECAY.health.regenRate * elapsedHours;
+  }
+  
+  health = clamp(health + roundDelta(healthDelta));
+  
+  return { hunger, happiness, hygiene, energy, health };
+}
+
+// ─── Main Decay Function ──────────────────────────────────────────────────────
+
+/**
+ * Apply decay to a Blobbi based on elapsed time since last decay.
+ * 
+ * This is a pure, deterministic function that:
+ * 1. Calculates elapsed time from lastDecayAt to now
+ * 2. Applies stage-specific decay rates
+ * 3. Truncates all stat deltas toward zero before application (prevents micro-decay from tiny elapsed times)
+ * 4. Clamps final stats to 1-100 range
+ * 5. Returns updated stats without side effects
+ * 
+ * @param input - Decay input parameters from persisted state
+ * @returns DecayResult with updated stats and new decay timestamp
+ */
+export function applyBlobbiDecay(input: DecayInput): DecayResult {
+  const now = input.now ?? Math.floor(Date.now() / 1000);
+  const lastDecayAt = input.lastDecayAt ?? now;
+  
+  // Calculate elapsed time
+  const elapsedSeconds = Math.max(0, now - lastDecayAt);
+  const elapsedHours = hoursFromSeconds(elapsedSeconds);
+  
+  // If no time has passed, return current stats unchanged
+  if (elapsedSeconds === 0) {
+    return {
+      stats: {
+        hunger: getStat(input.stats, 'hunger'),
+        happiness: getStat(input.stats, 'happiness'),
+        health: getStat(input.stats, 'health'),
+        hygiene: getStat(input.stats, 'hygiene'),
+        energy: getStat(input.stats, 'energy'),
+      },
+      elapsedSeconds: 0,
+      newDecayTimestamp: now,
+    };
+  }
+  
+  // Apply stage-specific decay
+  let newStats: BlobbiStats;
+  switch (input.stage) {
+    case 'egg':
+      newStats = calculateEggDecay(input.stats, elapsedHours);
+      break;
+    case 'baby':
+      newStats = calculateBabyDecay(input.stats, input.state, elapsedHours);
+      break;
+    case 'adult':
+      newStats = calculateAdultDecay(input.stats, input.state, elapsedHours);
+      break;
+    default:
+      // Fallback to adult decay for unknown stages
+      newStats = calculateAdultDecay(input.stats, input.state, elapsedHours);
+  }
+  
+  return {
+    stats: newStats,
+    elapsedSeconds,
+    newDecayTimestamp: now,
+  };
+}
+
+// ─── Threshold Checkers ───────────────────────────────────────────────────────
+
+/**
+ * Check if a stat is at warning level for the given stage.
+ */
+export function isStatAtWarning(
+  stage: BlobbiStage,
+  stat: keyof BlobbiStats,
+  value: number
+): boolean {
+  const thresholds = WARNING_THRESHOLDS[stage];
+  const threshold = (thresholds as Record<string, number>)[stat];
+  if (threshold === undefined) return false;
+  return value < threshold;
+}
+
+/**
+ * Check if a stat is at critical level for the given stage.
+ */
+export function isStatAtCritical(
+  stage: BlobbiStage,
+  stat: keyof BlobbiStats,
+  value: number
+): boolean {
+  const thresholds = CRITICAL_THRESHOLDS[stage];
+  const threshold = (thresholds as Record<string, number>)[stat];
+  if (threshold === undefined) return false;
+  return value < threshold;
+}
+
+/**
+ * Get the status level for a stat.
+ * @returns 'critical' | 'warning' | 'normal'
+ */
+export function getStatStatus(
+  stage: BlobbiStage,
+  stat: keyof BlobbiStats,
+  value: number
+): 'critical' | 'warning' | 'normal' {
+  if (isStatAtCritical(stage, stat, value)) return 'critical';
+  if (isStatAtWarning(stage, stat, value)) return 'warning';
+  return 'normal';
+}
+
+/**
+ * Get all stats that are at warning or critical level.
+ */
+export function getStatsNeedingAttention(
+  stage: BlobbiStage,
+  stats: Partial<BlobbiStats>
+): Array<{ stat: keyof BlobbiStats; value: number; status: 'warning' | 'critical' }> {
+  const results: Array<{ stat: keyof BlobbiStats; value: number; status: 'warning' | 'critical' }> = [];
+  
+  const statKeys: (keyof BlobbiStats)[] = ['hunger', 'happiness', 'health', 'hygiene', 'energy'];
+  
+  // For eggs, only check relevant stats
+  const relevantStats = stage === 'egg' 
+    ? ['health', 'hygiene', 'happiness'] as (keyof BlobbiStats)[]
+    : statKeys;
+  
+  for (const stat of relevantStats) {
+    const value = stats[stat] ?? 100;
+    const status = getStatStatus(stage, stat, value);
+    if (status !== 'normal') {
+      results.push({ stat, value, status });
+    }
+  }
+  
+  return results;
+}
+
+// ─── Visible Stats Helper ─────────────────────────────────────────────────────
+
+/**
+ * Visibility threshold: stats at or above this value are hidden in the UI.
+ * Only stats below this threshold are displayed.
+ */
+export const STAT_VISIBILITY_THRESHOLD = 70;
+
+/**
+ * Get the stats that should be visible for a given stage.
+ * Eggs only show health, hygiene, happiness.
+ * Baby/adult show all stats.
+ */
+export function getVisibleStats(stage: BlobbiStage): (keyof BlobbiStats)[] {
+  if (stage === 'egg') {
+    return ['health', 'hygiene', 'happiness'];
+  }
+  return ['hunger', 'happiness', 'health', 'hygiene', 'energy'];
+}
+
+/**
+ * Get visible stats with their values for display.
+ * Stats at or above STAT_VISIBILITY_THRESHOLD are filtered out.
+ */
+export function getVisibleStatsWithValues(
+  stage: BlobbiStage,
+  stats: Partial<BlobbiStats>
+): Array<{ stat: keyof BlobbiStats; value: number; status: 'critical' | 'warning' | 'normal' }> {
+  const visibleStats = getVisibleStats(stage);
+  return visibleStats
+    .map(stat => ({
+      stat,
+      value: stats[stat] ?? 100,
+      status: getStatStatus(stage, stat, stats[stat] ?? 100),
+    }))
+    .filter(entry => entry.value < STAT_VISIBILITY_THRESHOLD);
+}
@@ -0,0 +1,156 @@
+/**
+ * Blobbi → EggGraphic Adapter
+ * 
+ * This module provides a translation layer between the Blobbi domain model
+ * and the portable EggGraphic visual module.
+ * 
+ * PURPOSE:
+ * - Keep the game/domain visual model decoupled from EggGraphic internals
+ * - Provide explicit mappings between vocabularies
+ * - Act as the single translation boundary for visual rendering
+ * 
+ * USAGE:
+ * ```ts
+ * const eggVisual = toEggGraphicVisualBlobbi(companion);
+ * // Pass eggVisual to EggGraphic component
+ * ```
+ */
+
+import type { EggVisualBlobbi } from '@/blobbi/egg';
+import {
+  type BlobbiCompanion,
+  type BlobbiPattern,
+  type BlobbiSpecialMark,
+  type BlobbiStage,
+  getTagValue,
+} from './blobbi';
+
+// ─── Egg Module Types (derived from EggVisualBlobbi) ──────────────────────────
+
+/** Life stage values accepted by EggGraphic */
+type EggLifeStage = NonNullable<EggVisualBlobbi['lifeStage']>;
+
+/** Pattern values accepted by EggGraphic */
+type EggPattern = NonNullable<EggVisualBlobbi['pattern']>;
+
+/** Special mark values accepted by EggGraphic */
+type EggSpecialMark = NonNullable<EggVisualBlobbi['specialMark']>;
+
+/** Theme variant values accepted by EggGraphic */
+type EggThemeVariant = NonNullable<EggVisualBlobbi['themeVariant']>;
+
+// ─── Mapping Tables ───────────────────────────────────────────────────────────
+
+/**
+ * Maps Blobbi pattern values to EggGraphic pattern values.
+ * Explicit mapping allows vocabularies to diverge in the future.
+ */
+const PATTERN_MAP: Record<BlobbiPattern, EggPattern> = {
+  'solid': 'solid',
+  'spotted': 'spotted',
+  'striped': 'striped',
+  'gradient': 'gradient',
+};
+
+/**
+ * Maps Blobbi special mark values to EggGraphic special mark values.
+ */
+const SPECIAL_MARK_MAP: Record<BlobbiSpecialMark, EggSpecialMark> = {
+  'none': 'none',
+  'star': 'star',
+  'heart': 'heart',
+  'sparkle': 'sparkle',
+  'blush': 'blush',
+};
+
+/**
+ * Maps Blobbi stage values to EggGraphic life stage values.
+ */
+const LIFE_STAGE_MAP: Record<BlobbiStage, EggLifeStage> = {
+  'egg': 'egg',
+  'baby': 'baby',
+  'adult': 'adult',
+};
+
+// ─── Fallback Values ──────────────────────────────────────────────────────────
+
+const DEFAULT_PATTERN: EggPattern = 'solid';
+const DEFAULT_SPECIAL_MARK: EggSpecialMark = 'none';
+const DEFAULT_LIFE_STAGE: EggLifeStage = 'egg';
+const DEFAULT_THEME_VARIANT: EggThemeVariant = 'default';
+
+// ─── Helper Functions ─────────────────────────────────────────────────────────
+
+/**
+ * Extract crossover app identifier from companion tags.
+ */
+function extractCrossoverApp(allTags: string[][]): string | undefined {
+  return getTagValue(allTags, 'crossover_app');
+}
+
+// ─── Main Adapter Function ────────────────────────────────────────────────────
+
+/**
+ * Convert a BlobbiCompanion to EggVisualBlobbi for rendering.
+ * 
+ * This is the TRANSLATION BOUNDARY between the Blobbi domain model
+ * and the EggGraphic visual module.
+ * 
+ * The adapter:
+ * - Maps vocabulary values through explicit mapping tables
+ * - Passes through full tags for EggGraphic metadata lookups
+ * - Provides safe fallbacks for any missing/invalid data
+ * - Does NOT leak app-specific assumptions into EggGraphic
+ * 
+ * @param companion - The parsed BlobbiCompanion from parseBlobbiEvent
+ * @param themeVariant - Optional theme variant override
+ * @returns Visual data compatible with EggVisualBlobbi
+ */
+export function toEggGraphicVisualBlobbi(
+  companion: BlobbiCompanion,
+  themeVariant: EggThemeVariant = DEFAULT_THEME_VARIANT
+): EggVisualBlobbi {
+  const { visualTraits, stage, allTags } = companion;
+  
+  return {
+    // Colors pass through directly (already CSS hex values)
+    baseColor: visualTraits.baseColor,
+    secondaryColor: visualTraits.secondaryColor,
+    
+    // Mapped through explicit tables with fallbacks
+    pattern: PATTERN_MAP[visualTraits.pattern] ?? DEFAULT_PATTERN,
+    specialMark: SPECIAL_MARK_MAP[visualTraits.specialMark] ?? DEFAULT_SPECIAL_MARK,
+    lifeStage: LIFE_STAGE_MAP[stage] ?? DEFAULT_LIFE_STAGE,
+    
+    // Theme variant
+    themeVariant,
+    
+    // Pass through full tags for EggGraphic metadata lookups
+    tags: allTags,
+    
+    // Extracted convenience values
+    crossoverApp: extractCrossoverApp(allTags),
+    
+    // NOTE: We intentionally do NOT pass companion.name as title here.
+    // The EggGraphic 'title' field is for special designations (e.g., "Divine"),
+    // not the pet's name. The pet name is displayed separately by the parent component.
+  };
+}
+
+/**
+ * Check if two EggVisualBlobbi configurations are visually equivalent.
+ * Useful for memoization and avoiding unnecessary re-renders.
+ */
+export function areEggGraphicVisualsEqual(
+  a: EggVisualBlobbi,
+  b: EggVisualBlobbi
+): boolean {
+  return (
+    a.baseColor === b.baseColor &&
+    a.secondaryColor === b.secondaryColor &&
+    a.pattern === b.pattern &&
+    a.specialMark === b.specialMark &&
+    a.lifeStage === b.lifeStage &&
+    a.themeVariant === b.themeVariant
+  );
+}
@@ -0,0 +1,242 @@
+// src/types/blobbi.ts
+
+/**
+ * Minimal, clean Blobbi domain types for the new project.
+ *
+ * Goal:
+ * - keep the model small and portable
+ * - support egg / baby / adult rendering
+ * - support sleep state
+ * - support visual customization
+ * - avoid dragging old project complexity into the new app
+ */
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Core lifecycle / state
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export type BlobbiLifeStage = 'egg' | 'baby' | 'adult';
+export type BlobbiState = 'active' | 'sleeping' | 'hibernating' | 'incubating' | 'evolving';
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Visual traits
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export type BlobbiPattern = 'solid' | 'spotted' | 'striped' | 'gradient';
+export type BlobbiSpecialMark = 'none' | 'star' | 'heart' | 'sparkle' | 'blush';
+export type BlobbiSize = 'small' | 'medium' | 'large';
+
+export interface BlobbiVisualTraits {
+  /**
+   * Main body/base color.
+   * Example: "#8B5CF6"
+   */
+  baseColor?: string;
+
+  /**
+   * Secondary/accent color, usually used in gradients or details.
+   */
+  secondaryColor?: string;
+
+  /**
+   * Eye / pupil color.
+   */
+  eyeColor?: string;
+
+  /**
+   * Optional pattern used by egg or future visual systems.
+   */
+  pattern?: BlobbiPattern;
+
+  /**
+   * Optional visual mark.
+   */
+  specialMark?: BlobbiSpecialMark;
+
+  /**
+   * Optional size hint for rendering.
+   */
+  size?: BlobbiSize;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Basic stats
+ * Keep only what is useful right now for UI and simple interactions.
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export interface BlobbiStats {
+  hunger: number;
+  happiness: number;
+  health: number;
+  hygiene: number;
+  energy: number;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Stage-specific fields
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export interface BlobbiEggData {
+  incubationTime?: number;
+  incubationProgress?: number;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface BlobbiBabyData {
+  // Reserved for future baby-specific fields
+}
+
+export interface BlobbiAdultData {
+  evolutionForm?: string;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Main Blobbi entity
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export interface Blobbi extends BlobbiVisualTraits {
+  /**
+   * Stable unique identifier.
+   */
+  id: string;
+
+  /**
+   * Display name.
+   */
+  name: string;
+
+  /**
+   * Current lifecycle stage.
+   */
+  lifeStage: BlobbiLifeStage;
+
+  /**
+   * Current activity state.
+   */
+  state: BlobbiState;
+
+  /**
+   * Optional convenience boolean for UI code that still expects this.
+   * Prefer using `state === "sleeping"` in new code.
+   */
+  isSleeping?: boolean;
+
+  /**
+   * Basic gameplay / care stats.
+   */
+  stats: BlobbiStats;
+
+  /**
+   * Ownership / identity metadata.
+   */
+  ownerPubkey?: string;
+  seed?: string;
+
+  /**
+   * Timestamps.
+   * Keep them simple for now; decide later whether the project will
+   * standardize on seconds or milliseconds everywhere.
+   */
+  createdAt?: number;
+  birthTime?: number;
+  hatchTime?: number;
+  lastInteraction?: number;
+
+  /**
+   * Progression.
+   */
+  experience?: number;
+  generation?: number;
+  careStreak?: number;
+
+  crossoverApp?: string | null;
+  themeVariant?: string;
+
+  /**
+   * Optional raw tags for Nostr-backed or metadata-driven rendering.
+   */
+  tags?: string[][];
+
+  /**
+   * Optional stage-specific buckets.
+   * This keeps the root model clean while leaving room to grow.
+   */
+  egg?: BlobbiEggData;
+  baby?: BlobbiBabyData;
+  adult?: BlobbiAdultData;
+}
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Defaults / helpers
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export const DEFAULT_BLOBBI_STATS: BlobbiStats = {
+  hunger: 100,
+  happiness: 100,
+  health: 100,
+  hygiene: 100,
+  energy: 100,
+};
+
+export const DEFAULT_BLOBBI_STATE: BlobbiState = 'active';
+export const DEFAULT_BLOBBI_LIFE_STAGE: BlobbiLifeStage = 'egg';
+
+export function createDefaultBlobbi(overrides: Partial<Blobbi> = {}): Blobbi {
+  const state = overrides.state ?? DEFAULT_BLOBBI_STATE;
+
+  return {
+    id: overrides.id ?? 'blobbi-1',
+    name: overrides.name ?? 'Blobbi',
+    lifeStage: overrides.lifeStage ?? DEFAULT_BLOBBI_LIFE_STAGE,
+    state,
+    isSleeping: overrides.isSleeping ?? state === 'sleeping',
+    stats: overrides.stats ?? { ...DEFAULT_BLOBBI_STATS },
+
+    baseColor: overrides.baseColor,
+    secondaryColor: overrides.secondaryColor,
+    eyeColor: overrides.eyeColor,
+    pattern: overrides.pattern,
+    specialMark: overrides.specialMark,
+    size: overrides.size,
+
+    ownerPubkey: overrides.ownerPubkey,
+    seed: overrides.seed,
+
+    createdAt: overrides.createdAt,
+    birthTime: overrides.birthTime,
+    hatchTime: overrides.hatchTime,
+    lastInteraction: overrides.lastInteraction,
+
+    experience: overrides.experience ?? 0,
+    generation: overrides.generation ?? 1,
+    careStreak: overrides.careStreak ?? 0,
+
+    crossoverApp: overrides.crossoverApp ?? null,
+    themeVariant: overrides.themeVariant,
+    tags: overrides.tags ?? [],
+
+    egg: overrides.egg,
+    baby: overrides.baby,
+    adult: overrides.adult,
+  };
+}
+
+/* ────────────────────────────────────────────────────────────────────────── *
+ * Type guards
+ * ────────────────────────────────────────────────────────────────────────── */
+
+export function isEggBlobbi(blobbi: Blobbi): boolean {
+  return blobbi.lifeStage === 'egg';
+}
+
+export function isBabyBlobbi(blobbi: Blobbi): boolean {
+  return blobbi.lifeStage === 'baby';
+}
+
+export function isAdultBlobbi(blobbi: Blobbi): boolean {
+  return blobbi.lifeStage === 'adult';
+}
+
+export function isBlobbiSleeping(blobbi: Blobbi): boolean {
+  return blobbi.state === 'sleeping' || blobbi.isSleeping === true;
+}
@@ -22,7 +22,7 @@ import { Switch } from '@/components/ui/switch';
 import { Input } from '@/components/ui/input';
 import { cn } from '@/lib/utils';

-import type { BlobbiCompanion, BlobbiStage, BlobbiState, BlobbiStats } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbiStage, BlobbiState, BlobbiStats } from '@/blobbi/core/lib/blobbi';
 import { ADULT_FORMS } from '@/blobbi/adult-blobbi/types/adult.types';

 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -58,8 +58,6 @@ export interface BlobbiDevUpdates {
  breedingReady?: boolean;
  /** Generation number */
  generation?: number;
-  /** Visibility to others */
-  visibleToOthers?: boolean;
 }

 // ─── Stat Presets ─────────────────────────────────────────────────────────────
@@ -189,7 +187,6 @@ export function BlobbiDevEditor({
  const [careStreak, setCareStreak] = useState(companion.careStreak ?? 0);
  const [breedingReady, setBreedingReady] = useState(companion.breedingReady);
  const [generation, setGeneration] = useState(companion.generation ?? 1);
-  const [visibleToOthers, setVisibleToOthers] = useState(companion.visibleToOthers);

  // Reset state when companion changes or modal opens
  const resetToCompanion = useCallback(() => {
@@ -207,7 +204,6 @@ export function BlobbiDevEditor({
    setCareStreak(companion.careStreak ?? 0);
    setBreedingReady(companion.breedingReady);
    setGeneration(companion.generation ?? 1);
-    setVisibleToOthers(companion.visibleToOthers);
  }, [companion]);

  // Check if there are any changes
@@ -224,10 +220,9 @@ export function BlobbiDevEditor({
      experience !== (companion.experience ?? 0) ||
      careStreak !== (companion.careStreak ?? 0) ||
      breedingReady !== companion.breedingReady ||
-      generation !== (companion.generation ?? 1) ||
-      visibleToOthers !== companion.visibleToOthers
+      generation !== (companion.generation ?? 1)
    );
-  }, [stage, state, adultType, stats, experience, careStreak, breedingReady, generation, visibleToOthers, companion]);
+  }, [stage, state, adultType, stats, experience, careStreak, breedingReady, generation, companion]);

  // Apply preset
  const applyPreset = useCallback((preset: StatPreset) => {
@@ -270,11 +265,10 @@ export function BlobbiDevEditor({
    if (careStreak !== (companion.careStreak ?? 0)) updates.careStreak = careStreak;
    if (breedingReady !== companion.breedingReady) updates.breedingReady = breedingReady;
    if (generation !== (companion.generation ?? 1)) updates.generation = generation;
-    if (visibleToOthers !== companion.visibleToOthers) updates.visibleToOthers = visibleToOthers;

    await onApply(updates);
    onClose();
-  }, [stage, state, adultType, stats, experience, careStreak, breedingReady, generation, visibleToOthers, companion, onApply, onClose]);
+  }, [stage, state, adultType, stats, experience, careStreak, breedingReady, generation, companion, onApply, onClose]);

  // Handle close
  const handleClose = useCallback(() => {
@@ -533,13 +527,6 @@ export function BlobbiDevEditor({
                  onCheckedChange={setBreedingReady}
                />
              </div>
-              <div className="flex items-center justify-between">
-                <Label className="text-sm">Visible to Others</Label>
-                <Switch
-                  checked={visibleToOthers}
-                  onCheckedChange={setVisibleToOthers}
-                />
-              </div>
            </div>
          </div>
        </div>
@@ -32,6 +32,8 @@ interface BlobbiEmotionPanelProps {
 const EMOTIONS: Array<{ value: BlobbiEmotion; label: string; emoji: string }> = [
  { value: 'neutral', label: 'Default', emoji: '😊' },
  { value: 'sad', label: 'Sad', emoji: '😢' },
+  { value: 'boring', label: 'Boring', emoji: '😑' },
+  { value: 'dirty', label: 'Dirty', emoji: '💩' },
  { value: 'happy', label: 'Extra Happy', emoji: '😄' },
  { value: 'angry', label: 'Angry', emoji: '😠' },
  { value: 'surprised', label: 'Surprised', emoji: '😲' },
@@ -14,8 +14,8 @@ import { useCurrentUser } from '@/hooks/useCurrentUser';
 import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

-import type { BlobbiCompanion, BlobbiStage } from '@/lib/blobbi';
-import { KIND_BLOBBI_STATE, updateBlobbiTags, getLocalDayString } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbiStage } from '@/blobbi/core/lib/blobbi';
+import { KIND_BLOBBI_STATE, updateBlobbiTags, getLocalDayString } from '@/blobbi/core/lib/blobbi';
 import type { BlobbiDevUpdates } from './BlobbiDevEditor';

 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -140,10 +140,6 @@ export function useBlobbiDevUpdate({
        tagUpdates.generation = updates.generation.toString();
        changedFields.push('generation');
      }
-      if (updates.visibleToOthers !== undefined) {
-        tagUpdates.visible = updates.visibleToOthers ? 'true' : 'false';
-        changedFields.push('visible');
-      }

      // Always update last_interaction and last_decay_at
      tagUpdates.last_interaction = now.toString();
@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useState, useCallback } from 'react';
 import type { EggVisualBlobbi } from '../types/egg.types';
 import { isValidBaseColor, isValidSecondaryColor } from '../lib/blobbi-egg-validation';
 import { SpecialMarkRenderer, SpecialMarkFallback } from './SpecialMarkRenderer';
@@ -12,6 +12,19 @@ import { cn } from '../lib/cn';
 */
 export type EggReactionState = 'idle' | 'listening' | 'swaying' | 'singing' | 'happy';

+/**
+ * Status effects for egg-stage visual feedback.
+ * These are simpler than adult/baby expressions since eggs don't have faces.
+ */
+export interface EggStatusEffects {
+  /** Dirty state: shows sweat droplet and dust underneath */
+  dirty?: boolean;
+  /** Health state: shows floating dizzy spirals around egg */
+  sick?: boolean;
+  /** Happy state: shows subtle sparkles around egg */
+  happy?: boolean;
+}
+
 interface EggGraphicProps {
  blobbi?: EggVisualBlobbi; // Visual blobbi object for visual properties
  sizeVariant?: 'tiny' | 'small' | 'medium' | 'large'; // Internal scaling only, NOT layout size
@@ -21,6 +34,42 @@ interface EggGraphicProps {
  cracking?: boolean;
  warmth?: number; // 0-100, affects the glow (fallback if no blobbi)
  forceInlineSvg?: boolean; // New prop to guarantee inline SVG
+  /** Status effects for egg-stage visual feedback */
+  statusEffects?: EggStatusEffects;
+}
+
+/**
+ * Create a spiral path for sick/dizzy effects.
+ * Generates a true Archimedean spiral that starts from center and winds outward.
+ * Based on the spiral algorithm from eyes/effects.ts.
+ * 
+ * @param cx - Center X coordinate
+ * @param cy - Center Y coordinate  
+ * @param radius - Outer radius of the spiral
+ * @param clockwise - If true, winds clockwise; if false, winds counter-clockwise (default: true)
+ */
+function createEggSpiralPath(cx: number, cy: number, radius: number, clockwise: boolean = true): string {
+  const points: string[] = [];
+  const turns = 2; // Number of complete rotations
+  const steps = 40; // Smoothness of the spiral
+  
+  // Direction multiplier: 1 for clockwise, -1 for counter-clockwise
+  const direction = clockwise ? 1 : -1;
+
+  for (let i = 0; i <= steps; i++) {
+    const angle = direction * (i / steps) * turns * 2 * Math.PI;
+    const r = (i / steps) * radius;
+    const x = cx + r * Math.cos(angle);
+    const y = cy + r * Math.sin(angle);
+
+    if (i === 0) {
+      points.push(`M ${x.toFixed(2)} ${y.toFixed(2)}`);
+    } else {
+      points.push(`L ${x.toFixed(2)} ${y.toFixed(2)}`);
+    }
+  }
+
+  return points.join(' ');
 }

 // Legacy fallback function for special marks (kept for compatibility)
@@ -64,6 +113,7 @@ export const EggGraphic: React.FC<EggGraphicProps> = ({
  cracking = false,
  warmth = 50,
  forceInlineSvg: _forceInlineSvg = false,
+  statusEffects,
 }) => {
  // sizeVariant controls ONLY internal scaling/details, NOT layout dimensions
  // Parent container controls actual rendered width/height via slot
@@ -98,6 +148,18 @@ export const EggGraphic: React.FC<EggGraphicProps> = ({

  const scale = fillScale[sizeVariant] || fillScale.medium;

+  // Tap-to-wiggle interaction state
+  const [isTapWiggling, setIsTapWiggling] = useState(false);
+
+  const handleEggClick = useCallback(() => {
+    if (isTapWiggling || cracking) return; // Don't re-trigger during animation or cracking
+    setIsTapWiggling(true);
+  }, [isTapWiggling, cracking]);
+
+  const handleWiggleEnd = useCallback(() => {
+    setIsTapWiggling(false);
+  }, []);
+
  // Divine color constants
  const DIVINE_PRIMARY_GREEN = '#55C4A2';
  const _DIVINE_HIGHLIGHT_GREEN = '#7AD9B9';
@@ -393,11 +455,17 @@ export const EggGraphic: React.FC<EggGraphicProps> = ({

        {/* Main egg shape - uses percentage-based sizing */}
        <div
+          onClick={handleEggClick}
+          onAnimationEnd={(e) => {
+            if (e.animationName === 'egg-tap-wiggle') handleWiggleEnd();
+          }}
          className={cn(
-            'relative transition-all duration-500 z-10',
-            // Reaction-based animations (music/sing)
-            (reaction === 'listening' || reaction === 'swaying' || reaction === 'happy') && 'animate-egg-sway',
-            reaction === 'singing' && 'animate-egg-bounce',
+            'relative transition-all duration-500 z-10 cursor-pointer',
+            // Tap wiggle (highest priority after cracking)
+            isTapWiggling && !cracking && 'animate-egg-tap-wiggle',
+            // Reaction-based animations (music/sing) - only when not tap-wiggling
+            !isTapWiggling && (reaction === 'listening' || reaction === 'swaying' || reaction === 'happy') && 'animate-egg-sway',
+            !isTapWiggling && reaction === 'singing' && 'animate-egg-bounce',
            // Warmth effect only when animated AND warm
            animated && actualWarmth > 60 && 'animate-egg-warmth',
            // Cracking overrides other animations
@@ -657,6 +725,440 @@ export const EggGraphic: React.FC<EggGraphicProps> = ({
            />
          </>
        )}
+
+        {/* ── Status Effects ─────────────────────────────────────────────── */}
+
+        {/* Dirty effect: sweat droplet + dust at lower shell edges
+            Placement rules for egg:
+            - Sweat droplet stays at upper-left (outside egg, not on face)
+            - Dust particles only at lower outer shell edges
+            - Avoid center-front placement entirely
+        */}
+        {statusEffects?.dirty && (
+          <>
+            {/* Sweat droplet - upper left outside egg shell */}
+            <div
+              className="absolute animate-egg-sweat-drop"
+              style={{
+                top: '15%',
+                left: '5%',
+                width: '0.6em',
+                height: '0.9em',
+                background: 'linear-gradient(180deg, rgba(147, 197, 253, 0.9) 0%, rgba(59, 130, 246, 0.7) 100%)',
+                borderRadius: '50% 50% 50% 50% / 30% 30% 70% 70%',
+                zIndex: 20,
+              }}
+            />
+            {/* Dust particles underneath (back layer) - at lower edges */}
+            <div
+              className="absolute animate-egg-dust"
+              style={{
+                bottom: '-5%',
+                left: '20%',
+                width: '60%',
+                height: '0.4em',
+                display: 'flex',
+                justifyContent: 'space-between',
+                zIndex: 5,
+              }}
+            >
+              {/* Left edge particle */}
+              <div
+                style={{
+                  width: '0.3em',
+                  height: '0.3em',
+                  background: 'rgba(87, 83, 78, 0.7)',
+                  borderRadius: '50%',
+                }}
+                className="animate-egg-dust-particle"
+              />
+              {/* Right edge particle */}
+              <div
+                style={{
+                  width: '0.28em',
+                  height: '0.28em',
+                  background: 'rgba(87, 83, 78, 0.65)',
+                  borderRadius: '50%',
+                  animationDelay: '0.4s',
+                }}
+                className="animate-egg-dust-particle"
+              />
+            </div>
+            {/* Front-layer dust - at lower-left and lower-right edges
+                More visible than back layer, stronger colors */}
+            {/* Lower-left edge particle - larger, more visible */}
+            <div
+              className="absolute animate-egg-dust-particle"
+              style={{
+                bottom: '12%',
+                left: '6%',
+                width: '0.28em',
+                height: '0.28em',
+                background: 'rgba(63, 63, 70, 0.8)',
+                borderRadius: '50%',
+                zIndex: 25,
+                animationDelay: '0.1s',
+              }}
+            />
+            {/* Lower-right edge particle */}
+            <div
+              className="absolute animate-egg-dust-particle"
+              style={{
+                bottom: '15%',
+                right: '5%',
+                width: '0.25em',
+                height: '0.25em',
+                background: 'rgba(63, 63, 70, 0.75)',
+                borderRadius: '50%',
+                zIndex: 25,
+                animationDelay: '0.5s',
+              }}
+            />
+            {/* Very bottom left particle */}
+            <div
+              className="absolute animate-egg-dust-particle"
+              style={{
+                bottom: '5%',
+                left: '18%',
+                width: '0.22em',
+                height: '0.22em',
+                background: 'rgba(68, 64, 60, 0.7)',
+                borderRadius: '50%',
+                zIndex: 25,
+                animationDelay: '0.8s',
+              }}
+            />
+            {/* Very bottom right particle */}
+            <div
+              className="absolute animate-egg-dust-particle"
+              style={{
+                bottom: '3%',
+                right: '20%',
+                width: '0.2em',
+                height: '0.2em',
+                background: 'rgba(68, 64, 60, 0.65)',
+                borderRadius: '50%',
+                zIndex: 25,
+                animationDelay: '1.1s',
+              }}
+            />
+          </>
+        )}
+
+        {/* Sick effect: layered dizzy spirals around and across egg
+            Creates a magical/dizzy atmosphere with multiple spiral layers:
+            - Outer spirals: floating around the egg shell
+            - Inner spirals: across the egg body itself
+            - Mixed colors: gray (primary) + white (accents)
+            - Varying sizes, speeds, and rotation directions
+            All use true Archimedean spiral paths matching Blobbi dizzy eyes
+        */}
+        {statusEffects?.sick && (
+          <>
+            {/* ═══ OUTER SPIRALS (floating around egg) ═══ */}
+            
+            {/* Outer 1 - top left, large, gray, COUNTER-CLOCKWISE path */}
+            <svg
+              className="absolute"
+              style={{
+                top: '0%',
+                left: '-5%',
+                width: '1.1em',
+                height: '1.1em',
+                zIndex: 20,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 8, false)}
+                  stroke="#4b5563"
+                  strokeWidth="1.5"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.65"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="0 10 10"
+                  to="360 10 10"
+                  dur="2.5s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+            
+            {/* Outer 2 - right side, medium, gray, CLOCKWISE path */}
+            <svg
+              className="absolute"
+              style={{
+                top: '25%',
+                right: '-6%',
+                width: '0.95em',
+                height: '0.95em',
+                zIndex: 20,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 8, true)}
+                  stroke="#6b7280"
+                  strokeWidth="1.4"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.6"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="360 10 10"
+                  to="0 10 10"
+                  dur="2s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+            
+            {/* Outer 3 - bottom left, small, white accent, COUNTER-CLOCKWISE path */}
+            <svg
+              className="absolute"
+              style={{
+                bottom: '15%',
+                left: '-4%',
+                width: '0.7em',
+                height: '0.7em',
+                zIndex: 20,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 8, false)}
+                  stroke="white"
+                  strokeWidth="1.3"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.5"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="360 10 10"
+                  to="0 10 10"
+                  dur="3s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+            
+            {/* Outer 4 - bottom right, tiny, gray, CLOCKWISE path */}
+            <svg
+              className="absolute"
+              style={{
+                bottom: '8%',
+                right: '-3%',
+                width: '0.6em',
+                height: '0.6em',
+                zIndex: 20,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 8, true)}
+                  stroke="#9ca3af"
+                  strokeWidth="1.2"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.5"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="0 10 10"
+                  to="360 10 10"
+                  dur="3.5s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+            
+            {/* ═══ INNER SPIRALS (across egg body) ═══ */}
+            
+            {/* Inner 1 - upper egg, small, white, COUNTER-CLOCKWISE path */}
+            <svg
+              className="absolute"
+              style={{
+                top: '18%',
+                left: '22%',
+                width: '0.55em',
+                height: '0.55em',
+                zIndex: 15,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 7, false)}
+                  stroke="white"
+                  strokeWidth="1.2"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.4"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="0 10 10"
+                  to="360 10 10"
+                  dur="4s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+            
+            {/* Inner 2 - mid-right egg, tiny, gray, CLOCKWISE path */}
+            <svg
+              className="absolute"
+              style={{
+                top: '40%',
+                right: '18%',
+                width: '0.5em',
+                height: '0.5em',
+                zIndex: 15,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 7, true)}
+                  stroke="#6b7280"
+                  strokeWidth="1.1"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.35"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="360 10 10"
+                  to="0 10 10"
+                  dur="3s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+            
+            {/* Inner 3 - lower-center egg, small, white accent */}
+            <svg
+              className="absolute"
+              style={{
+                bottom: '28%',
+                left: '35%',
+                width: '0.45em',
+                height: '0.45em',
+                zIndex: 15,
+                overflow: 'visible',
+              }}
+              viewBox="0 0 20 20"
+            >
+              <g>
+                <path
+                  d={createEggSpiralPath(10, 10, 7, false)}
+                  stroke="white"
+                  strokeWidth="1"
+                  fill="none"
+                  strokeLinecap="round"
+                  opacity="0.35"
+                />
+                <animateTransform
+                  attributeName="transform"
+                  type="rotate"
+                  from="0 10 10"
+                  to="360 10 10"
+                  dur="3.5s"
+                  repeatCount="indefinite"
+                />
+              </g>
+            </svg>
+          </>
+        )}
+
+        {/* Happy effect: subtle sparkles around egg */}
+        {statusEffects?.happy && (
+          <>
+            {/* Sparkle 1 - top */}
+            <div
+              className="absolute animate-egg-sparkle"
+              style={{
+                top: '5%',
+                left: '45%',
+                width: '0.5em',
+                height: '0.5em',
+                zIndex: 20,
+              }}
+            >
+              <svg viewBox="0 0 20 20" className="w-full h-full">
+                <path
+                  d="M10 0 L10 20 M0 10 L20 10 M3 3 L17 17 M17 3 L3 17"
+                  stroke="rgba(251, 191, 36, 0.8)"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </div>
+            {/* Sparkle 2 - right */}
+            <div
+              className="absolute animate-egg-sparkle"
+              style={{
+                top: '25%',
+                right: '0%',
+                width: '0.4em',
+                height: '0.4em',
+                zIndex: 20,
+                animationDelay: '0.4s',
+              }}
+            >
+              <svg viewBox="0 0 20 20" className="w-full h-full">
+                <path
+                  d="M10 0 L10 20 M0 10 L20 10"
+                  stroke="rgba(251, 191, 36, 0.7)"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </div>
+            {/* Sparkle 3 - left */}
+            <div
+              className="absolute animate-egg-sparkle"
+              style={{
+                top: '40%',
+                left: '0%',
+                width: '0.35em',
+                height: '0.35em',
+                zIndex: 20,
+                animationDelay: '0.8s',
+              }}
+            >
+              <svg viewBox="0 0 20 20" className="w-full h-full">
+                <path
+                  d="M10 0 L10 20 M0 10 L20 10"
+                  stroke="rgba(251, 191, 36, 0.6)"
+                  strokeWidth="2"
+                  strokeLinecap="round"
+                />
+              </svg>
+            </div>
+          </>
+        )}
      </div>
    </div>
  );
@@ -12,7 +12,7 @@
 import './styles/egg-animations.css';

 // Components
-export { EggGraphic, type EggReactionState } from './components/EggGraphic';
+export { EggGraphic, type EggReactionState, type EggStatusEffects } from './components/EggGraphic';
 export { SpecialMarkRenderer, SpecialMarkFallback } from './components/SpecialMarkRenderer';

 // Hooks
@@ -82,6 +82,118 @@
  animation: egg-crack-shake 0.5s ease-in-out infinite;
 }

+/* Tap interaction: rock side-to-side and hop */
+@keyframes egg-tap-wiggle {
+  0% {
+    transform: translateY(0) rotate(0deg);
+  }
+  15% {
+    transform: translateY(-2px) rotate(-6deg);
+  }
+  30% {
+    transform: translateY(-6px) rotate(5deg);
+  }
+  45% {
+    transform: translateY(-3px) rotate(-4deg);
+  }
+  60% {
+    transform: translateY(-1px) rotate(3deg);
+  }
+  75% {
+    transform: translateY(0) rotate(-1.5deg);
+  }
+  90% {
+    transform: translateY(0) rotate(0.5deg);
+  }
+  100% {
+    transform: translateY(0) rotate(0deg);
+  }
+}
+
+.animate-egg-tap-wiggle {
+  animation: egg-tap-wiggle 0.6s cubic-bezier(0.34, 1.56, 0.64, 1) forwards;
+}
+
+/* ==========================================
+   Egg Status Effect Animations
+   ========================================== */
+
+/* Sweat droplet - slides down and fades */
+@keyframes egg-sweat-drop {
+  0% {
+    opacity: 0;
+    transform: translateY(-2px);
+  }
+  20% {
+    opacity: 1;
+    transform: translateY(0);
+  }
+  80% {
+    opacity: 1;
+    transform: translateY(4px);
+  }
+  100% {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+}
+
+.animate-egg-sweat-drop {
+  animation: egg-sweat-drop 2s ease-in-out infinite;
+}
+
+/* Dust particles - gentle float up */
+@keyframes egg-dust-particle {
+  0%, 100% {
+    opacity: 0.3;
+    transform: translateY(0);
+  }
+  50% {
+    opacity: 0.6;
+    transform: translateY(-3px);
+  }
+}
+
+.animate-egg-dust-particle {
+  animation: egg-dust-particle 2s ease-in-out infinite;
+}
+
+/* Dizzy spirals - rotate and float */
+@keyframes egg-spiral {
+  0% {
+    opacity: 0.4;
+    transform: rotate(0deg) translateY(0);
+  }
+  50% {
+    opacity: 0.8;
+    transform: rotate(180deg) translateY(-4px);
+  }
+  100% {
+    opacity: 0.4;
+    transform: rotate(360deg) translateY(0);
+  }
+}
+
+.animate-egg-spiral {
+  animation: egg-spiral 3s ease-in-out infinite;
+}
+
+/* Happy sparkles - twinkle effect */
+@keyframes egg-sparkle {
+  0%, 100% {
+    opacity: 0.3;
+    transform: scale(0.8);
+  }
+  50% {
+    opacity: 1;
+    transform: scale(1.2);
+  }
+}
+
+.animate-egg-sparkle {
+  animation: egg-sparkle 1.5s ease-in-out infinite;
+}
+
 /* ==========================================
   Special Mark Animations
   ========================================== */
@@ -234,7 +346,12 @@
  .animate-egg-sway,
  .animate-egg-bounce,
  .animate-egg-warmth,
-  .animate-egg-crack {
+  .animate-egg-crack,
+  .animate-egg-tap-wiggle,
+  .animate-egg-sweat-drop,
+  .animate-egg-dust-particle,
+  .animate-egg-spiral,
+  .animate-egg-sparkle {
    animation: none !important;
  }
 }
@@ -16,7 +16,7 @@ import {
  DialogFooter,
 } from '@/components/ui/dialog';
 import { BlobbiStageVisual } from '@/blobbi/ui/BlobbiStageVisual';
-import { BLOBBI_ADOPTION_COST } from '@/lib/blobbi';
+import { BLOBBI_ADOPTION_COST } from '@/blobbi/core/lib/blobbi';
 import { formatCompactNumber } from '@/lib/utils';

 import type { BlobbiEggPreview } from '../lib/blobbi-preview';
@@ -19,7 +19,7 @@ import { cn, formatCompactNumber } from '@/lib/utils';
 import {
  BLOBBI_PREVIEW_REROLL_COST,
  BLOBBI_ADOPTION_COST,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';

 import type { BlobbiEggPreview } from '../lib/blobbi-preview';
 import { previewToBlobbiCompanion } from '../lib/blobbi-preview';
@@ -26,7 +26,7 @@ import { BlobbiEggPreviewCard } from './BlobbiEggPreviewCard';
 import { BlobbiAdoptionConfirmDialog } from './BlobbiAdoptionConfirmDialog';
 import { Loader2 } from 'lucide-react';

-import type { BlobbonautProfile } from '@/lib/blobbi';
+import type { BlobbonautProfile } from '@/blobbi/core/lib/blobbi';

 interface BlobbiOnboardingFlowProps {
  /** Current profile (null if doesn't exist) */
@@ -31,7 +31,7 @@ import {
  buildBlobbonautTags,
  updateBlobbonautTags,
  type BlobbonautProfile,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';

 import {
  generateEggPreview,
@@ -16,7 +16,7 @@ import {
  getLocalDayString,
  type BlobbiVisualTraits,
  type BlobbiStats,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';

 // ─── Types ────────────────────────────────────────────────────────────────────

@@ -135,7 +135,6 @@ export function previewToEventTags(preview: BlobbiEggPreview): string[][] {
    ['stage', preview.stage],
    ['state', preview.state],
    ['seed', preview.seed],
-    ['visible_to_others', 'true'],
    ['generation', '1'],
    ['breeding_ready', 'false'],
    ['experience', '0'],
@@ -181,7 +180,6 @@ export function previewToBlobbiCompanion(preview: BlobbiEggPreview) {
    isLegacy: false,
    lastInteraction: preview.createdAt,
    lastDecayAt: preview.createdAt,
-    visibleToOthers: true,
    generation: 1,
    breedingReady: false,
    experience: 0,
@@ -18,7 +18,7 @@ import {
  TooltipTrigger,
 } from '@/components/ui/tooltip';

-import type { BlobbiCompanion, BlobbonautProfile } from '@/lib/blobbi';
+import type { BlobbiCompanion, BlobbonautProfile } from '@/blobbi/core/lib/blobbi';
 import type { ShopItem } from '../types/shop.types';
 import { getShopItemById } from '../lib/blobbi-shop-items';
 import { canUseItemForStage } from '@/blobbi/actions/lib/blobbi-action-utils';
@@ -45,20 +45,25 @@ interface ResolvedInventoryItem extends ShopItem {
  reason?: string;
 }

-export function BlobbiInventoryModal({
-  open,
-  onOpenChange,
+// ── Shared inventory content (used by both standalone modal and unified shop modal) ──
+
+interface BlobbiInventoryContentProps {
+  profile: BlobbonautProfile | null;
+  companion: BlobbiCompanion | null;
+  onUseItem?: (itemId: string, quantity: number) => void;
+  isUsingItem?: boolean;
+}
+
+export function BlobbiInventoryContent({
  profile,
  companion,
  onUseItem,
  isUsingItem = false,
-}: BlobbiInventoryModalProps) {
-  // State for use confirmation dialog
+}: BlobbiInventoryContentProps) {
  const [selectedItem, setSelectedItem] = useState<ResolvedInventoryItem | null>(null);
  const [quantity, setQuantity] = useState(1);
  const [showUseDialog, setShowUseDialog] = useState(false);

-  // Resolve storage items with their metadata and usability from the shop catalog
  const inventoryItems = useMemo((): ResolvedInventoryItem[] => {
    if (!profile) return [];
    const stage = companion?.stage ?? 'egg';
@@ -68,7 +73,6 @@ export function BlobbiInventoryModal({
      const item = getShopItemById(storageItem.itemId);
      if (!item) continue;

-      // Check if item can be used for current stage
      const usability = canUseItemForStage(storageItem.itemId, stage);

      result.push({
@@ -84,7 +88,6 @@ export function BlobbiInventoryModal({

  const isEmpty = inventoryItems.length === 0;

-  // Handlers for use dialog
  const handleSelectItem = (item: ResolvedInventoryItem) => {
    if (!item.canUse || isUsingItem) return;
    setSelectedItem(item);
@@ -95,7 +98,6 @@ export function BlobbiInventoryModal({
  const handleConfirmUse = () => {
    if (!selectedItem || !onUseItem || isUsingItem) return;
    onUseItem(selectedItem.itemId, quantity);
-    // Reset state
    setShowUseDialog(false);
    setSelectedItem(null);
    setQuantity(1);
@@ -109,7 +111,6 @@ export function BlobbiInventoryModal({
    }
  };

-  // Quantity controls
  const maxQuantity = selectedItem?.quantity ?? 1;
  const handleIncrease = () => setQuantity(q => Math.min(q + 1, maxQuantity));
  const handleDecrease = () => setQuantity(q => Math.max(q - 1, 1));
@@ -123,142 +124,117 @@ export function BlobbiInventoryModal({
  };

  return (
-    <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="max-w-2xl w-[calc(100%-2rem)] max-h-[85vh] flex flex-col p-0 gap-0 [&>button:last-child]:hidden">
-        {/* Header - Sticky */}
-        <DialogHeader className="sticky top-0 z-10 bg-background px-4 sm:px-6 pt-4 sm:pt-6 pb-3 sm:pb-4 border-b">
-          <div className="flex items-start justify-between gap-3">
-            <div className="flex items-center gap-3 min-w-0">
-              <div className="size-9 sm:size-10 rounded-xl bg-gradient-to-br from-blue-500/20 to-indigo-500/20 flex items-center justify-center shrink-0">
-                <Package className="size-4 sm:size-5 text-primary" />
-              </div>
-              <div className="min-w-0">
-                <DialogTitle className="text-xl sm:text-2xl">Inventory</DialogTitle>
-                <p className="text-xs sm:text-sm text-muted-foreground">
-                  {isEmpty ? 'No items yet' : `${inventoryItems.length} ${inventoryItems.length === 1 ? 'item' : 'items'}`}
-                </p>
-              </div>
+    <>
+      <div className="px-4 sm:px-6 py-3 sm:py-4">
+        {isEmpty ? (
+          <div className="flex flex-col items-center justify-center py-16 text-center">
+            <div className="size-20 rounded-3xl bg-muted/50 flex items-center justify-center mb-4">
+              <Package className="size-10 text-muted-foreground" />
            </div>
-            <DialogClose className="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 shrink-0">
-              <X className="size-5" />
-              <span className="sr-only">Close</span>
-            </DialogClose>
+            <h3 className="text-lg font-semibold mb-2">No Items Yet</h3>
+            <p className="text-sm text-muted-foreground max-w-sm">
+              Visit the Shop tab to purchase items for your Blobbi. Items you buy will appear here.
+            </p>
          </div>
-        </DialogHeader>
-
-        {/* Content - Scrollable */}
-        <div className="flex-1 min-h-0 overflow-y-auto px-4 sm:px-6 py-3 sm:py-4">
-          {isEmpty ? (
-            <div className="flex flex-col items-center justify-center py-16 text-center">
-              <div className="size-20 rounded-3xl bg-muted/50 flex items-center justify-center mb-4">
-                <Package className="size-10 text-muted-foreground" />
-              </div>
-              <h3 className="text-lg font-semibold mb-2">No Items Yet</h3>
-              <p className="text-sm text-muted-foreground max-w-sm">
-                Visit the shop to purchase items for your Blobbi. Items you buy will appear here.
-              </p>
-            </div>
-          ) : (
-            <div className="grid gap-2 sm:gap-3">
-              {inventoryItems.map(item => (
-                <div
-                  key={item.itemId}
-                  className={cn(
-                    "flex flex-col sm:flex-row sm:items-center gap-2 sm:gap-4 p-3 sm:p-4 rounded-xl border bg-card/60 backdrop-blur-sm transition-colors",
-                    item.canUse ? "hover:border-primary/30" : "opacity-70"
-                  )}
-                >
-                  {/* Top row on mobile: Icon + Name/Type + Quantity + Button */}
-                  <div className="flex items-center gap-3 sm:contents">
-                    {/* Item Icon */}
-                    <div className="relative shrink-0">
-                      <div className="absolute inset-0 bg-gradient-to-br from-primary/20 to-primary/5 rounded-full blur-xl" />
-                      <div className={cn(
-                        "relative size-10 sm:size-14 rounded-full bg-gradient-to-br from-primary/10 to-primary/5 flex items-center justify-center text-2xl sm:text-3xl",
-                        !item.canUse && "grayscale"
-                      )}>
-                        {item.icon}
-                      </div>
+        ) : (
+          <div className="grid gap-2 sm:gap-3">
+            {inventoryItems.map(item => (
+              <div
+                key={item.itemId}
+                className={cn(
+                  "flex flex-col sm:flex-row sm:items-center gap-2 sm:gap-4 p-3 sm:p-4 rounded-xl border bg-card/60 backdrop-blur-sm transition-colors",
+                  item.canUse ? "hover:border-primary/30" : "opacity-70"
+                )}
+              >
+                {/* Top row on mobile: Icon + Name/Type + Quantity + Button */}
+                <div className="flex items-center gap-3 sm:contents">
+                  {/* Item Icon */}
+                  <div className="relative shrink-0">
+                    <div className="absolute inset-0 bg-gradient-to-br from-primary/20 to-primary/5 rounded-full blur-xl" />
+                    <div className={cn(
+                      "relative size-10 sm:size-14 rounded-full bg-gradient-to-br from-primary/10 to-primary/5 flex items-center justify-center text-2xl sm:text-3xl",
+                      !item.canUse && "grayscale"
+                    )}>
+                      {item.icon}
                    </div>
-
-                    {/* Item Info - Name and Type */}
-                    <div className="flex-1 min-w-0">
-                      <div className="flex items-center gap-2 mb-0.5 sm:mb-1">
-                        <h3 className="font-semibold text-sm sm:text-base truncate">{item.name}</h3>
-                        <Badge variant="secondary" className="text-xs capitalize shrink-0 hidden sm:inline-flex">
-                          {item.type}
-                        </Badge>
-                      </div>
-                      {/* Effect preview - desktop only inline */}
-                      <div className="hidden sm:block">
-                        <ItemEffectDisplay effect={item.effect} variant="inline" />
-                      </div>
-                      {/* Show blocked reason - desktop only inline */}
-                      {!item.canUse && item.reason && (
-                        <p className="hidden sm:block text-xs text-amber-600 dark:text-amber-400 mt-1">
-                          {item.reason}
-                        </p>
-                      )}
-                    </div>
-
-                    {/* Quantity Badge */}
-                    <Badge className="bg-gradient-to-r from-blue-500 to-indigo-500 text-white border-0 px-2 py-0.5 shrink-0 text-xs">
-                      ×{item.quantity}
-                    </Badge>
-
-                    {/* Use Button */}
-                    {onUseItem && (
-                      item.canUse ? (
-                        <Button
-                          size="sm"
-                          onClick={() => handleSelectItem(item)}
-                          disabled={isUsingItem}
-                          className="shrink-0"
-                        >
-                          Use
-                        </Button>
-                      ) : (
-                        <Tooltip>
-                          <TooltipTrigger asChild>
-                            <span>
-                              <Button
-                                size="sm"
-                                disabled
-                                className="shrink-0"
-                              >
-                                Use
-                              </Button>
-                            </span>
-                          </TooltipTrigger>
-                          <TooltipContent>
-                            <p>{item.reason || 'Cannot use this item'}</p>
-                          </TooltipContent>
-                        </Tooltip>
-                      )
-                    )}
                  </div>

-                  {/* Mobile only: Effect preview and blocked reason below */}
-                  <div className="sm:hidden pl-13 space-y-1">
-                    <div className="flex items-center gap-2">
-                      <Badge variant="secondary" className="text-xs capitalize">
+                  {/* Item Info - Name and Type */}
+                  <div className="flex-1 min-w-0">
+                    <div className="flex items-center gap-2 mb-0.5 sm:mb-1">
+                      <h3 className="font-semibold text-sm sm:text-base truncate">{item.name}</h3>
+                      <Badge variant="secondary" className="text-xs capitalize shrink-0 hidden sm:inline-flex">
                        {item.type}
                      </Badge>
+                    </div>
+                    {/* Effect preview - desktop only inline */}
+                    <div className="hidden sm:block">
                      <ItemEffectDisplay effect={item.effect} variant="inline" />
                    </div>
-                    {/* Show blocked reason on mobile */}
+                    {/* Show blocked reason - desktop only inline */}
                    {!item.canUse && item.reason && (
-                      <p className="text-xs text-amber-600 dark:text-amber-400">
+                      <p className="hidden sm:block text-xs text-amber-600 dark:text-amber-400 mt-1">
                        {item.reason}
                      </p>
                    )}
                  </div>
+
+                  {/* Quantity Badge */}
+                  <Badge className="bg-gradient-to-r from-blue-500 to-indigo-500 text-white border-0 px-2 py-0.5 shrink-0 text-xs">
+                    ×{item.quantity}
+                  </Badge>
+
+                  {/* Use Button */}
+                  {onUseItem && (
+                    item.canUse ? (
+                      <Button
+                        size="sm"
+                        onClick={() => handleSelectItem(item)}
+                        disabled={isUsingItem}
+                        className="shrink-0"
+                      >
+                        Use
+                      </Button>
+                    ) : (
+                      <Tooltip>
+                        <TooltipTrigger asChild>
+                          <span>
+                            <Button
+                              size="sm"
+                              disabled
+                              className="shrink-0"
+                            >
+                              Use
+                            </Button>
+                          </span>
+                        </TooltipTrigger>
+                        <TooltipContent>
+                          <p>{item.reason || 'Cannot use this item'}</p>
+                        </TooltipContent>
+                      </Tooltip>
+                    )
+                  )}
                </div>
-              ))}
-            </div>
-          )}
-        </div>
-      </DialogContent>
+
+                {/* Mobile only: Effect preview and blocked reason below */}
+                <div className="sm:hidden pl-13 space-y-1">
+                  <div className="flex items-center gap-2">
+                    <Badge variant="secondary" className="text-xs capitalize">
+                      {item.type}
+                    </Badge>
+                    <ItemEffectDisplay effect={item.effect} variant="inline" />
+                  </div>
+                  {!item.canUse && item.reason && (
+                    <p className="text-xs text-amber-600 dark:text-amber-400">
+                      {item.reason}
+                    </p>
+                  )}
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>

      {/* Use Item Confirmation Dialog */}
      {selectedItem && companion && (
@@ -276,6 +252,49 @@ export function BlobbiInventoryModal({
          isUsing={isUsingItem}
        />
      )}
+    </>
+  );
+}
+
+// ── Standalone Inventory Modal (kept for backwards compatibility) ──
+
+export function BlobbiInventoryModal({
+  open,
+  onOpenChange,
+  profile,
+  companion,
+  onUseItem,
+  isUsingItem = false,
+}: BlobbiInventoryModalProps) {
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent className="max-w-2xl w-[calc(100%-2rem)] max-h-[85vh] flex flex-col p-0 gap-0 [&>button:last-child]:hidden">
+        {/* Header - Sticky */}
+        <DialogHeader className="sticky top-0 z-10 bg-background px-4 sm:px-6 pt-4 sm:pt-6 pb-3 sm:pb-4 border-b">
+          <div className="flex items-start justify-between gap-3">
+            <div className="flex items-center gap-3 min-w-0">
+              <div className="size-9 sm:size-10 rounded-xl bg-gradient-to-br from-blue-500/20 to-indigo-500/20 flex items-center justify-center shrink-0">
+                <Package className="size-4 sm:size-5 text-primary" />
+              </div>
+              <DialogTitle className="text-xl sm:text-2xl">Inventory</DialogTitle>
+            </div>
+            <DialogClose className="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2 shrink-0">
+              <X className="size-5" />
+              <span className="sr-only">Close</span>
+            </DialogClose>
+          </div>
+        </DialogHeader>
+
+        {/* Content - Scrollable */}
+        <div className="flex-1 min-h-0 overflow-y-auto">
+          <BlobbiInventoryContent
+            profile={profile}
+            companion={companion}
+            onUseItem={onUseItem}
+            isUsingItem={isUsingItem}
+          />
+        </div>
+      </DialogContent>
    </Dialog>
  );
 }
@@ -309,15 +328,12 @@ function InventoryUseConfirmDialog({
  onConfirm,
  isUsing,
 }: InventoryUseConfirmDialogProps) {
-  // Calculate total effect for the selected quantity by simulating sequential application
-  // This matches the actual behavior when items are used (clamping at each step)
  const totalEffect = useMemo(() => {
    if (!item.effect) return null;
    
    const statKeys = ['hunger', 'happiness', 'energy', 'hygiene', 'health'] as const;
    const currentStats = { ...companion.stats };
    
-    // Apply effects N times in sequence with clamping at each step
    for (let i = 0; i < quantity; i++) {
      for (const stat of statKeys) {
        const delta = item.effect[stat];
@@ -327,7 +343,6 @@ function InventoryUseConfirmDialog({
      }
    }
    
-    // Calculate actual deltas (may be less than effect * quantity due to clamping)
    const result: Record<string, number> = {};
    for (const stat of statKeys) {
      const delta = (currentStats[stat] ?? 0) - (companion.stats[stat] ?? 0);
@@ -12,7 +12,6 @@ import {
 import { Input } from '@/components/ui/input';

 import type { ShopItem } from '../types/shop.types';
-import { ItemEffectDisplay } from './ItemEffectDisplay';
 import { formatCompactNumber } from '@/lib/utils';

 interface BlobbiPurchaseDialogProps {
@@ -150,13 +149,6 @@ export function BlobbiPurchaseDialog({
            )}
          </div>

-          {/* Effects Summary */}
-          {item.effect && Object.keys(item.effect).length > 0 && (
-            <div className="p-4 rounded-lg bg-gradient-to-r from-emerald-500/10 to-green-500/10 border border-emerald-500/20">
-              <h4 className="text-sm font-medium mb-2">Effects per item</h4>
-              <ItemEffectDisplay effect={item.effect} variant="grid" />
-            </div>
-          )}
        </div>

        <DialogFooter>
@@ -1,178 +1,364 @@
-import { useState } from 'react';
-import { ShoppingBag, Utensils, Gamepad2, Heart, Droplets, Palette, X } from 'lucide-react';
+import { useState, useMemo } from 'react';
+import { ShoppingBag, Package, Loader2, X } from 'lucide-react';

 import {
  Dialog,
  DialogContent,
-  DialogHeader,
-  DialogTitle,
  DialogClose,
 } from '@/components/ui/dialog';
 import { Badge } from '@/components/ui/badge';
+import { Button } from '@/components/ui/button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@/components/ui/tooltip';

-import { BlobbiShopItemRow } from './BlobbiShopItemRow';
-import { BlobbiPurchaseDialog } from './BlobbiPurchaseDialog';
-
-import type { ShopItem, ShopItemCategory } from '../types/shop.types';
-import type { BlobbonautProfile } from '@/lib/blobbi';
-import { getShopItemsByType } from '../lib/blobbi-shop-items';
+import type { ShopItem } from '../types/shop.types';
+import type { BlobbiCompanion, BlobbonautProfile } from '@/blobbi/core/lib/blobbi';
+import { getLiveShopItems, getShopItemById } from '../lib/blobbi-shop-items';
 import { useBlobbiPurchaseItem } from '../hooks/useBlobbiPurchaseItem';
+import { canUseItemForStage } from '@/blobbi/actions/lib/blobbi-action-utils';
 import { cn, formatCompactNumber } from '@/lib/utils';

+type TopTab = 'items' | 'shop';
+
+/** Resolved inventory item with shop metadata and usability info */
+interface ResolvedInventoryItem extends ShopItem {
+  itemId: string;
+  quantity: number;
+  canUse: boolean;
+  reason?: string;
+}
+
 interface BlobbiShopModalProps {
  open: boolean;
  onOpenChange: (open: boolean) => void;
  profile: BlobbonautProfile | null;
+  /** Initial tab to open on. Defaults to "items". */
+  initialTab?: TopTab;
+  // ── Inventory props (passed through) ──
+  companion: BlobbiCompanion | null;
+  onUseItem?: (itemId: string, quantity: number) => void;
+  isUsingItem?: boolean;
 }

-const CATEGORIES: Array<{
-  type: ShopItemCategory;
-  label: string;
-  icon: React.ReactNode;
-}> = [
-  { type: 'food', label: 'Food', icon: <Utensils className="size-4" /> },
-  { type: 'toy', label: 'Toys', icon: <Gamepad2 className="size-4" /> },
-  { type: 'medicine', label: 'Medicine', icon: <Heart className="size-4" /> },
-  { type: 'hygiene', label: 'Hygiene', icon: <Droplets className="size-4" /> },
-  { type: 'accessory', label: 'Accessories', icon: <Palette className="size-4" /> },
-];
-
-export function BlobbiShopModal({ open, onOpenChange, profile }: BlobbiShopModalProps) {
-  const [activeCategory, setActiveCategory] = useState<ShopItemCategory>('food');
-  const [selectedItem, setSelectedItem] = useState<ShopItem | null>(null);
-  const [showPurchaseDialog, setShowPurchaseDialog] = useState(false);
+export function BlobbiShopModal({
+  open,
+  onOpenChange,
+  profile,
+  initialTab = 'items',
+  companion,
+  onUseItem,
+  isUsingItem,
+}: BlobbiShopModalProps) {
+  const [topTab, setTopTab] = useState<TopTab>(initialTab);

  const { mutate: purchaseItem, isPending: isPurchasing } = useBlobbiPurchaseItem(profile);
+  const [purchasingItemId, setPurchasingItemId] = useState<string | null>(null);

  const availableCoins = profile?.coins ?? 0;
-  const items = getShopItemsByType(activeCategory);
+  const allItems = getLiveShopItems();

-  const handlePurchaseClick = (item: ShopItem) => {
-    setSelectedItem(item);
-    setShowPurchaseDialog(true);
+  // Reset to initialTab when modal re-opens
+  const handleOpenChange = (isOpen: boolean) => {
+    if (isOpen) {
+      setTopTab(initialTab);
+    }
+    onOpenChange(isOpen);
  };

-  const handlePurchase = (quantity: number) => {
-    if (!selectedItem) return;
-
+  // Instant purchase — one tap = one item
+  const handleBuyItem = (item: ShopItem) => {
+    if (isPurchasing || availableCoins < item.price) return;
+    setPurchasingItemId(item.id);
    purchaseItem(
-      {
-        itemId: selectedItem.id,
-        price: selectedItem.price,
-        quantity,
-      },
-      {
-        onSuccess: () => {
-          setShowPurchaseDialog(false);
-          setSelectedItem(null);
-        },
-      }
+      { itemId: item.id, price: item.price, quantity: 1 },
+      { onSettled: () => setPurchasingItemId(null) },
    );
  };

+  const effectivePurchasingId = isPurchasing ? purchasingItemId : null;
+
+  // ── Inventory items resolution ──
+  const inventoryItems = useMemo((): ResolvedInventoryItem[] => {
+    if (!profile) return [];
+    const stage = companion?.stage ?? 'egg';
+
+    const result: ResolvedInventoryItem[] = [];
+    for (const storageItem of profile.storage) {
+      const item = getShopItemById(storageItem.itemId);
+      if (!item) continue;
+
+      const usability = canUseItemForStage(storageItem.itemId, stage);
+
+      result.push({
+        ...item,
+        itemId: storageItem.itemId,
+        quantity: storageItem.quantity,
+        canUse: usability.canUse,
+        reason: usability.reason,
+      });
+    }
+    return result;
+  }, [profile, companion?.stage]);
+
+  // ── Inventory use item handler ──
+  const [usingItemId, setUsingItemId] = useState<string | null>(null);
+
+  const handleUseItem = (item: ResolvedInventoryItem) => {
+    if (!item.canUse || isUsingItem || !onUseItem) return;
+    setUsingItemId(item.itemId);
+    onUseItem(item.itemId, 1);
+  };
+
+  // Clear usingItemId when isUsingItem goes false
+  const effectiveUsingItemId = isUsingItem ? usingItemId : null;
+
+  const inventoryEmpty = inventoryItems.length === 0;
+
  return (
    <>
-      <Dialog open={open} onOpenChange={onOpenChange}>
-        <DialogContent className="max-w-2xl w-[calc(100%-2rem)] max-h-[85vh] flex flex-col p-0 gap-0 [&>button:last-child]:hidden">
-          {/* Header - Sticky */}
-          <DialogHeader className="sticky top-0 z-10 bg-background px-4 sm:px-6 pt-4 sm:pt-6 pb-3 sm:pb-4 border-b">
-            <div className="flex items-start justify-between gap-2">
-              <div className="flex items-center gap-2 sm:gap-3 min-w-0">
-                <div className="size-9 sm:size-10 rounded-xl bg-gradient-to-br from-purple-500/20 to-pink-500/20 flex items-center justify-center shrink-0">
-                  <ShoppingBag className="size-4 sm:size-5 text-primary" />
-                </div>
-                <DialogTitle className="text-xl sm:text-2xl truncate">Blobbi Shop</DialogTitle>
-              </div>
-              <div className="flex items-center gap-2 shrink-0">
-                <Badge className="bg-gradient-to-r from-yellow-500 to-amber-500 text-white border-0 text-sm sm:text-base px-3 sm:px-4 py-1">
-                  {formatCompactNumber(availableCoins)} coins
+      <Dialog open={open} onOpenChange={handleOpenChange}>
+        <DialogContent className="max-w-md w-[calc(100%-2rem)] max-h-[80vh] flex flex-col p-0 gap-0 overflow-hidden rounded-2xl [&>button:last-child]:hidden">
+
+          {/* Tab Bar (replaces header) */}
+          <div className="flex items-center border-b bg-muted/30">
+            {/* Tabs */}
+            <button
+              onClick={() => setTopTab('items')}
+              className={cn(
+                'flex-1 flex items-center justify-center gap-2 px-4 py-3.5 text-sm font-medium transition-colors relative',
+                topTab === 'items'
+                  ? 'text-foreground'
+                  : 'text-muted-foreground hover:text-foreground/70'
+              )}
+            >
+              <Package className="size-4" />
+              Items
+              {!inventoryEmpty && (
+                <Badge variant="secondary" className="text-[10px] px-1.5 py-0 h-4 min-w-4">
+                  {inventoryItems.reduce((sum, i) => sum + i.quantity, 0)}
                </Badge>
-                <DialogClose className="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none focus:ring-2 focus:ring-ring focus:ring-offset-2">
-                  <X className="size-5" />
-                  <span className="sr-only">Close</span>
-                </DialogClose>
-              </div>
-            </div>
-          </DialogHeader>
+              )}
+              {topTab === 'items' && (
+                <span className="absolute bottom-0 inset-x-4 h-0.5 bg-primary rounded-full" />
+              )}
+            </button>
+            <button
+              onClick={() => setTopTab('shop')}
+              className={cn(
+                'flex-1 flex items-center justify-center gap-2 px-4 py-3.5 text-sm font-medium transition-colors relative',
+                topTab === 'shop'
+                  ? 'text-foreground'
+                  : 'text-muted-foreground hover:text-foreground/70'
+              )}
+            >
+              <ShoppingBag className="size-4" />
+              Shop
+              {topTab === 'shop' && (
+                <span className="absolute bottom-0 inset-x-4 h-0.5 bg-primary rounded-full" />
+              )}
+            </button>

-          {/* Category Tabs - Part of sticky header area */}
-          <div className="sticky top-[60px] sm:top-[72px] z-10 bg-background px-4 sm:px-6 pt-3 sm:pt-4 pb-2 border-b">
-            <div className="flex gap-1.5 sm:gap-2 overflow-x-auto pb-1 -mx-1 px-1">
-              {CATEGORIES.map(category => {
-                const isActive = activeCategory === category.type;
-                const itemCount = getShopItemsByType(category.type).length;
-
-                  return (
-                    <button
-                      key={category.type}
-                      onClick={() => setActiveCategory(category.type)}
-                      className={cn(
-                        'flex items-center gap-1.5 sm:gap-2 px-2.5 sm:px-4 py-1.5 sm:py-2 rounded-lg transition-all whitespace-nowrap',
-                        'border text-sm sm:text-base',
-                        isActive
-                          ? 'bg-primary text-primary-foreground border-primary'
-                          : 'bg-muted/50 text-muted-foreground border-transparent hover:bg-muted'
-                      )}
-                    >
-                      {category.icon}
-                      <span className="font-medium hidden xs:inline">{category.label}</span>
-                      <Badge variant="secondary" className="ml-0.5 sm:ml-1 text-xs">
-                        {itemCount}
-                      </Badge>
-                    </button>
-                  );
-              })}
+            {/* Coin badge + Close */}
+            <div className="flex items-center gap-1.5 pr-3 pl-2">
+              <Badge className="bg-gradient-to-r from-yellow-500 to-amber-500 text-white border-0 text-xs px-2 py-0.5">
+                <span className="mr-1">🪙</span>{formatCompactNumber(availableCoins)}
+              </Badge>
+              <DialogClose className="rounded-full p-1 opacity-60 hover:opacity-100 transition-opacity">
+                <X className="size-4" />
+                <span className="sr-only">Close</span>
+              </DialogClose>
            </div>
          </div>

-          {/* Scrollable Content Area */}
+          {/* Scrollable Content */}
          <div className="flex-1 min-h-0 overflow-y-auto">
-            {/* Accessories Coming Soon Banner */}
-            {activeCategory === 'accessory' && (
-              <div className="mx-4 sm:mx-6 mt-3 sm:mt-4 p-4 sm:p-6 rounded-xl bg-gradient-to-br from-primary/10 to-primary/5 border border-primary/20">
-                <div className="flex items-start gap-3 sm:gap-4">
-                  <div className="size-12 sm:size-16 rounded-xl sm:rounded-2xl bg-gradient-to-br from-primary/20 to-primary/10 flex items-center justify-center text-2xl sm:text-3xl relative shrink-0">
-                    🎨
-                    <div className="absolute -top-1 -right-1 text-base sm:text-xl">✨</div>
-                  </div>
-                  <div className="flex-1 min-w-0">
-                    <h3 className="text-base sm:text-lg font-semibold mb-1">Accessories Coming Soon!</h3>
-                    <p className="text-xs sm:text-sm text-muted-foreground">
-                      Get ready to customize your Blobbi's appearance with amazing accessories and cosmetic items.
-                    </p>
-                  </div>
-                </div>
-              </div>
+            {topTab === 'shop' ? (
+              <ShopGrid
+                items={allItems}
+                availableCoins={availableCoins}
+                onBuy={handleBuyItem}
+                purchasingItemId={effectivePurchasingId}
+              />
+            ) : (
+              <ItemsGrid
+                items={inventoryItems}
+                onUseItem={handleUseItem}
+                isUsingItem={isUsingItem}
+                usingItemId={effectiveUsingItemId}
+                onGoToShop={() => setTopTab('shop')}
+              />
            )}
-
-            {/* Items List */}
-            <div className="px-4 sm:px-6 py-3 sm:py-4">
-              <div className="space-y-2">
-                {items.map(item => (
-                  <BlobbiShopItemRow
-                    key={item.id}
-                    item={item}
-                    availableCoins={availableCoins}
-                    onPurchaseClick={handlePurchaseClick}
-                  />
-                ))}
-              </div>
-            </div>
          </div>
        </DialogContent>
      </Dialog>
-
-      {/* Purchase Dialog */}
-      {selectedItem && (
-        <BlobbiPurchaseDialog
-          open={showPurchaseDialog}
-          onOpenChange={setShowPurchaseDialog}
-          item={selectedItem}
-          availableCoins={availableCoins}
-          onPurchase={handlePurchase}
-          isPurchasing={isPurchasing}
-        />
-      )}
    </>
  );
 }
+
+// ─── Shop Grid (tile layout, all items, cost in button) ───────────────────────
+
+interface ShopGridProps {
+  items: ShopItem[];
+  availableCoins: number;
+  onBuy: (item: ShopItem) => void;
+  purchasingItemId: string | null;
+}
+
+function ShopGrid({ items, availableCoins, onBuy, purchasingItemId }: ShopGridProps) {
+  return (
+    <div className="p-3">
+      <div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
+        {items.map(item => {
+          const isDisabled = item.status === 'disabled';
+          const isAffordable = !isDisabled && availableCoins >= item.price;
+          const isBuying = purchasingItemId === item.id;
+
+          return (
+            <div
+              key={item.id}
+              className={cn(
+                'flex flex-col items-center gap-1.5 p-3 rounded-xl border transition-all text-center',
+                'bg-card/60 backdrop-blur-sm',
+                isDisabled && 'opacity-50',
+                !isDisabled && !isAffordable && 'opacity-70',
+              )}
+            >
+              {/* Icon */}
+              <div className="text-3xl leading-none mt-1">{item.icon}</div>
+
+              {/* Name */}
+              <span className="text-xs font-medium truncate w-full">{item.name}</span>
+
+              {/* Buy button with integrated cost */}
+              <button
+                onClick={() => onBuy(item)}
+                disabled={isDisabled || !isAffordable || !!purchasingItemId}
+                className={cn(
+                  'w-full rounded-lg px-2 py-1.5 text-xs font-medium transition-colors',
+                  isDisabled
+                    ? 'bg-muted text-muted-foreground cursor-not-allowed'
+                    : isAffordable
+                      ? 'bg-gradient-to-r from-purple-500 to-pink-500 text-white hover:from-purple-600 hover:to-pink-600 active:scale-95 transition-transform'
+                      : 'bg-muted text-muted-foreground cursor-not-allowed'
+                )}
+              >
+                {isDisabled ? (
+                  'Soon'
+                ) : isBuying ? (
+                  <span className="flex items-center justify-center">
+                    <Loader2 className="size-3 animate-spin" />
+                  </span>
+                ) : (
+                  <span className="flex items-center justify-center gap-1">
+                    <span>🪙</span> {formatCompactNumber(item.price)}
+                  </span>
+                )}
+              </button>
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
+
+// ─── Items Grid (inventory, tile layout) ──────────────────────────────────────
+
+interface ItemsGridProps {
+  items: ResolvedInventoryItem[];
+  onUseItem: (item: ResolvedInventoryItem) => void;
+  isUsingItem?: boolean;
+  usingItemId: string | null;
+  onGoToShop: () => void;
+}
+
+function ItemsGrid({ items, onUseItem, isUsingItem, usingItemId, onGoToShop }: ItemsGridProps) {
+  if (items.length === 0) {
+    return (
+      <div className="flex flex-col items-center justify-center py-16 px-6 text-center">
+        <div className="size-16 rounded-2xl bg-muted/50 flex items-center justify-center mb-4">
+          <Package className="size-8 text-muted-foreground/60" />
+        </div>
+        <p className="text-sm text-muted-foreground mb-4">
+          No items yet. Visit the shop to stock up!
+        </p>
+        <Button variant="outline" size="sm" onClick={onGoToShop} className="gap-2">
+          <ShoppingBag className="size-3.5" />
+          Browse Shop
+        </Button>
+      </div>
+    );
+  }
+
+  return (
+    <div className="p-3">
+      <div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
+        {items.map(item => {
+          const isThisUsing = isUsingItem && usingItemId === item.itemId;
+
+          return (
+            <div
+              key={item.itemId}
+              className={cn(
+                'flex flex-col items-center gap-1.5 p-3 rounded-xl border transition-all text-center relative',
+                'bg-card/60 backdrop-blur-sm',
+                item.canUse ? 'hover:border-primary/40 hover:bg-accent/40' : 'opacity-60',
+              )}
+            >
+              {/* Quantity badge */}
+              <Badge
+                className="absolute top-1.5 right-1.5 text-[10px] px-1.5 py-0 h-4 min-w-4 bg-gradient-to-r from-blue-500 to-indigo-500 text-white border-0"
+              >
+                {item.quantity}
+              </Badge>
+
+              {/* Icon */}
+              <div className={cn('text-3xl leading-none mt-1', !item.canUse && 'grayscale')}>{item.icon}</div>
+
+              {/* Name */}
+              <span className="text-xs font-medium truncate w-full">{item.name}</span>
+
+              {/* Use button */}
+              {item.canUse ? (
+                <Button
+                  size="sm"
+                  variant="outline"
+                  className="w-full h-7 text-xs"
+                  onClick={() => onUseItem(item)}
+                  disabled={isUsingItem}
+                >
+                  {isThisUsing ? (
+                    <Loader2 className="size-3 animate-spin" />
+                  ) : (
+                    'Use'
+                  )}
+                </Button>
+              ) : (
+                <Tooltip>
+                  <TooltipTrigger asChild>
+                    <span className="w-full">
+                      <Button
+                        size="sm"
+                        variant="outline"
+                        className="w-full h-7 text-xs"
+                        disabled
+                      >
+                        Use
+                      </Button>
+                    </span>
+                  </TooltipTrigger>
+                  <TooltipContent>
+                    <p>{item.reason || 'Cannot use this item'}</p>
+                  </TooltipContent>
+                </Tooltip>
+              )}
+            </div>
+          );
+        })}
+      </div>
+    </div>
+  );
+}
@@ -5,12 +5,12 @@ import { useNostrPublish } from '@/hooks/useNostrPublish';
 import { toast } from '@/hooks/useToast';

 import type { PurchaseRequest } from '../types/shop.types';
-import type { BlobbonautProfile, StorageItem } from '@/lib/blobbi';
+import type { BlobbonautProfile, StorageItem } from '@/blobbi/core/lib/blobbi';
 import {
  KIND_BLOBBONAUT_PROFILE,
  updateBlobbonautTags,
  createStorageTags,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';
 import { getShopItemById } from '../lib/blobbi-shop-items';

 /**
@@ -177,39 +177,6 @@ export const BLOBBI_SHOP_ITEMS: ShopItem[] = [
    status: 'live',
  },

-  // ─── Accessory Items (Disabled) ─────────────────────────────────────────────
-  {
-    id: 'acc_hat',
-    name: 'Party Hat',
-    type: 'accessory',
-    price: 75,
-    icon: '🎩',
-    status: 'disabled',
-  },
-  {
-    id: 'acc_glasses',
-    name: 'Cool Glasses',
-    type: 'accessory',
-    price: 60,
-    icon: '🕶️',
-    status: 'disabled',
-  },
-  {
-    id: 'acc_bow',
-    name: 'Bow Tie',
-    type: 'accessory',
-    price: 50,
-    icon: '🎀',
-    status: 'disabled',
-  },
-  {
-    id: 'acc_crown',
-    name: 'Crown',
-    type: 'accessory',
-    price: 100,
-    icon: '👑',
-    status: 'disabled',
-  },
 ];

 /**
@@ -237,7 +204,7 @@ export function getLiveShopItems(): ShopItem[] {
 * Get all shop item categories with their counts
 */
 export function getShopCategories(): Array<{ type: ShopItemCategory; count: number; label: string }> {
-  const categories: ShopItemCategory[] = ['food', 'toy', 'medicine', 'hygiene', 'accessory'];
+  const categories: ShopItemCategory[] = ['food', 'toy', 'medicine', 'hygiene'];
  
  return categories.map(type => ({
    type,
@@ -7,8 +7,7 @@ export type ShopItemCategory =
  | 'food' 
  | 'toy' 
  | 'medicine' 
-  | 'hygiene' 
-  | 'accessory';
+  | 'hygiene';

 /**
 * Stat effects that items can apply to Blobbi
@@ -0,0 +1,104 @@
+/**
+ * BlobbiAdultSvgRenderer — Pure SVG rendering component for adult Blobbi.
+ *
+ * This component is the leaf node of the visual pipeline. It:
+ *   1. Resolves the base SVG for the adult form
+ *   2. Customizes colors and unique IDs
+ *   3. Adds eye animation infrastructure (blink clip-paths, gaze groups)
+ *   4. Applies visual recipe or emotion preset
+ *   5. Applies manual body effects (when no recipe is provided)
+ *   6. Sanitizes the SVG
+ *   7. Renders via dangerouslySetInnerHTML
+ *
+ * It does NOT know about:
+ *   - Eye tracking hooks (useBlobbiEyes / useExternalEyeOffset)
+ *   - Render mode (page vs companion)
+ *   - Reaction CSS classes (sway / bounce)
+ *   - Companion runtime (drag, float, position)
+ *
+ * This separation ensures that the SVG DOM node stays mounted and stable
+ * as long as the visual inputs don't change. SMIL and CSS animations
+ * inside the SVG continue running across parent rerenders.
+ */
+
+import { useMemo } from 'react';
+
+import { resolveAdultSvgWithForm, customizeAdultSvgFromBlobbi } from '@/blobbi/adult-blobbi';
+import { sanitizeBlobbiSvg } from '@/lib/sanitizeBlobbiSvg';
+
+import { addEyeAnimation } from './lib/eye-animation';
+import { resolveVisualRecipe, applyVisualRecipe, type BlobbiVisualRecipe } from './lib/recipe';
+import type { BlobbiEmotion } from './lib/emotion-types';
+import { applyBodyEffects, type BodyEffectsSpec } from './lib/bodyEffects';
+import { debugBlobbi } from './lib/debug';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
+
+export interface BlobbiAdultSvgRendererProps {
+  /** The Blobbi data */
+  blobbi: Blobbi;
+  /** Whether the Blobbi is sleeping */
+  isSleeping: boolean;
+  /** Pre-resolved visual recipe. Takes precedence over `emotion`. */
+  recipe?: BlobbiVisualRecipe;
+  /** Label for the recipe (used in CSS class names). */
+  recipeLabel?: string;
+  /** Named emotion preset. Ignored when `recipe` is provided. Default: 'neutral' */
+  emotion?: BlobbiEmotion;
+  /** Body-level visual effects (manual/external use only — not from status reaction). */
+  bodyEffects?: BodyEffectsSpec;
+  /** Additional CSS classes for the container */
+  className?: string;
+}
+
+/**
+ * Pure SVG renderer for adult Blobbi.
+ *
+ * IMPORTANT: This component must remain a pure rendering leaf. It must NOT:
+ * - Run eye-tracking hooks (those belong in the Visual wrapper)
+ * - Know about render modes or companion runtime
+ * - Apply reaction CSS classes (those belong on an outer wrapper)
+ *
+ * The parent Visual wrapper owns the DOM query boundary (containerRef)
+ * that eye hooks use to find SVG elements via querySelector.
+ */
+export function BlobbiAdultSvgRenderer({
+  blobbi,
+  isSleeping: _isSleeping,
+  recipe: recipeProp,
+  recipeLabel,
+  emotion = 'neutral',
+  bodyEffects,
+  className,
+}: BlobbiAdultSvgRendererProps) {
+  const customizedSvg = useMemo(() => {
+    debugBlobbi('svg-rebuild', 'adult customizedSvg rebuild');
+
+    // Always use the base (awake) SVG — sleeping is a recipe overlay, not an asset swap
+    const { form, svg } = resolveAdultSvgWithForm(blobbi, { isSleeping: false });
+    const colorizedSvg = customizeAdultSvgFromBlobbi(svg, form, blobbi, false);
+
+    let animatedSvg = addEyeAnimation(colorizedSvg, { baseColor: blobbi.baseColor, instanceId: blobbi.id });
+
+    if (recipeProp) {
+      animatedSvg = applyVisualRecipe(animatedSvg, recipeProp, recipeLabel ?? 'status', 'adult', form, blobbi.id);
+    } else if (emotion !== 'neutral') {
+      const resolved = resolveVisualRecipe(emotion);
+      animatedSvg = applyVisualRecipe(animatedSvg, resolved, emotion, 'adult', form, blobbi.id);
+    }
+
+    if (bodyEffects && !recipeProp) {
+      animatedSvg = applyBodyEffects(animatedSvg, { ...bodyEffects, idPrefix: bodyEffects.idPrefix ?? blobbi.id });
+    }
+
+    return animatedSvg;
+  }, [blobbi, recipeProp, recipeLabel, emotion, bodyEffects]);
+
+  const safeSvg = useMemo(() => sanitizeBlobbiSvg(customizedSvg), [customizedSvg]);
+
+  return (
+    <div
+      className={className}
+      dangerouslySetInnerHTML={{ __html: safeSvg }}
+    />
+  );
+}
@@ -1,162 +1,134 @@
 /**
- * BlobbiAdultVisual - Reusable component for rendering Blobbi adults
+ * BlobbiAdultVisual — Visual wrapper for rendering Blobbi adults.
 *
- * Uses the adult-blobbi module for SVG resolution and customization.
- * Handles awake vs sleeping states automatically.
- * Supports multiple adult evolution forms.
- * Eyes always track the mouse cursor in real-time.
+ * Responsibilities:
+ *   - Owns the container ref for eye hooks to query SVG DOM
+ *   - Runs useBlobbiEyes (blink RAF loop, optional mouse tracking)
+ *   - Runs useExternalEyeOffset (companion gaze RAF loop)
+ *   - Applies reaction CSS classes (sway/bounce) in page mode
+ *   - Delegates SVG rendering to BlobbiAdultSvgRenderer
+ *
+ * The SVG renderer is a separate component so the dangerouslySetInnerHTML
+ * node stays mounted even when wrapper-level props change (reaction,
+ * className toggles, etc.).
+ *
+ * Render modes:
+ *   - 'page' (default): Mouse tracking enabled, reaction classes applied here.
+ *   - 'companion': Mouse tracking disabled (gaze via ref), reaction classes
+ *     suppressed (applied by outer companion wrapper instead).
 */

-import { useMemo, useRef, useEffect } from 'react';
+import { useRef, type RefObject } from 'react';

-import { resolveAdultSvgWithForm, customizeAdultSvgFromBlobbi } from '@/blobbi/adult-blobbi';
 import { cn } from '@/lib/utils';

-import { addEyeAnimation } from './lib/eye-animation';
-import { applyEmotion, type BlobbiEmotion } from './lib/emotions';
 import { useBlobbiEyes, type BlobbiLookMode } from './lib/useBlobbiEyes';
-import type { Blobbi } from '@/types/blobbi';
-import { isBlobbiSleeping } from '@/types/blobbi';
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/**
- * Reaction states for adult Blobbi animations
- */
-export type AdultReactionState = 'idle' | 'listening' | 'swaying' | 'singing' | 'happy';
-
-/**
- * External eye offset for companion control
- * Values range from -1 to 1, converted to pixel movement internally
- */
-export interface ExternalEyeOffset {
-  x: number;
-  y: number;
-}
+import { useExternalEyeOffset } from './lib/useExternalEyeOffset';
+import type { ExternalEyeOffset, BlobbiReactionState, BlobbiRenderMode } from './lib/types';
+import type { BlobbiVisualRecipe } from './lib/recipe';
+import type { BlobbiEmotion } from './lib/emotion-types';
+import type { BodyEffectsSpec } from './lib/bodyEffects';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
+import { isBlobbiSleeping } from '@/blobbi/core/types/blobbi';
+import { BlobbiAdultSvgRenderer } from './BlobbiAdultSvgRenderer';

 export interface BlobbiAdultVisualProps {
  /** The Blobbi data */
  blobbi: Blobbi;
  /** Reaction state for music/sing animations */
-  reaction?: AdultReactionState;
+  reaction?: BlobbiReactionState;
  /** Controls eye tracking behavior (default: 'follow-pointer') */
  lookMode?: BlobbiLookMode;
  /** Disable blinking animation (for photo/export mode) */
  disableBlink?: boolean;
-  /** 
-   * External eye offset from companion system.
-   * When provided, bypasses internal mouse tracking and uses this offset directly.
-   * Values should be -1 to 1, will be converted to pixel movement.
-   */
+  /** External eye offset (value-based — causes rerenders). */
  externalEyeOffset?: ExternalEyeOffset;
-  /** 
-   * Emotional state to display.
-   * Adds visual overlays like eyebrows, modified mouth, and tears.
-   * Default: 'neutral' (no modifications)
-   */
+  /** Ref-based external eye offset (imperative — no rerenders). Preferred for companion mode. */
+  externalEyeOffsetRef?: RefObject<ExternalEyeOffset>;
+  /** Render mode. Default: 'page'. */
+  renderMode?: BlobbiRenderMode;
+  /** Pre-resolved visual recipe. Takes precedence over `emotion`. */
+  recipe?: BlobbiVisualRecipe;
+  /** Label for the recipe (used in CSS class names). */
+  recipeLabel?: string;
+  /** Named emotion preset. Ignored when `recipe` is provided. Default: 'neutral' */
  emotion?: BlobbiEmotion;
+  /** Body-level visual effects (manual/external use only). */
+  bodyEffects?: BodyEffectsSpec;
  /** Additional CSS classes for the container */
  className?: string;
 }

-// ─── Component ────────────────────────────────────────────────────────────────
-
-/**
- * Renders an adult Blobbi using inline SVG.
- *
- * - Resolves the correct form from blobbi data (evolutionForm or seed-derived)
- * - Selects the correct SVG variant (awake or sleeping) based on state
- * - Applies color customization from Blobbi traits
- * - Eyes always track the mouse cursor (instant, real-time)
- * - Renders safely using dangerouslySetInnerHTML
- */
-export function BlobbiAdultVisual({ blobbi, reaction = 'idle', lookMode = 'follow-pointer', disableBlink = false, externalEyeOffset, emotion = 'neutral', className }: BlobbiAdultVisualProps) {
+export function BlobbiAdultVisual({
+  blobbi,
+  reaction = 'idle',
+  lookMode = 'follow-pointer',
+  disableBlink = false,
+  externalEyeOffset,
+  externalEyeOffsetRef,
+  renderMode = 'page',
+  recipe,
+  recipeLabel,
+  emotion = 'neutral',
+  bodyEffects,
+  className,
+}: BlobbiAdultVisualProps) {
  const isSleeping = isBlobbiSleeping(blobbi);
+
+  // This ref is the DOM query boundary for eye hooks. useBlobbiEyes and
+  // useExternalEyeOffset use querySelector on this element to find SVG
+  // eye elements rendered by the child SvgRenderer.
  const containerRef = useRef<HTMLDivElement>(null);

-  // Disable reactions when sleeping
+  const isCompanion = renderMode === 'companion';
+
  const effectiveReaction = isSleeping ? 'idle' : reaction;

-  // Eye animation hook - handles DOM manipulation internally
-  // When externalEyeOffset is provided, we disable tracking but keep blinking
+  // ── Eye hooks ──────────────────────────────────────────────────────────────
+
  useBlobbiEyes(containerRef, {
    isSleeping,
-    maxMovement: 2.5, // Slightly more movement for larger adult form
+    maxMovement: 2.5,
    lookMode,
    disableBlink,
-    disableTracking: !!externalEyeOffset, // External system controls eye position
+    disableTracking: isCompanion,
  });

-  // External eye offset control - applies offset directly when provided
-  // This bypasses useBlobbiEyes and gives companion full control
-  useEffect(() => {
-    if (!externalEyeOffset || !containerRef.current || isSleeping) return;
+  useExternalEyeOffset({
+    containerRef,
+    externalEyeOffset,
+    externalEyeOffsetRef,
+    isSleeping,
+    variant: 'adult',
+  });

-    const eyeElements = containerRef.current.querySelectorAll<SVGGElement>('.blobbi-eye-left, .blobbi-eye-right');
-    if (eyeElements.length === 0) return;
-
-    // Convert -1 to 1 offset to pixel movement
-    // Increased max movement for more visible eye tracking (4.5px horizontal for adults)
-    const maxMovementX = 4.5;
-    const x = externalEyeOffset.x * maxMovementX;
-    
-    // Asymmetric vertical movement:
-    // - Upward (negative y): stronger movement (1.0x) for clear "looking up" effect
-    // - Downward (positive y): reduced movement (0.6x) to avoid looking too droopy
-    // Y offset: -1 = looking up, +1 = looking down
-    const maxMovementYUp = 4.5;  // Full range for looking up
-    const maxMovementYDown = 2.7; // Reduced range for looking down (0.6x)
-    const y = externalEyeOffset.y < 0 
-      ? externalEyeOffset.y * maxMovementYUp    // Looking up: full range
-      : externalEyeOffset.y * maxMovementYDown; // Looking down: reduced range
-
-    eyeElements.forEach(el => {
-      el.setAttribute('transform', `translate(${x} ${y})`);
-    });
-  }, [externalEyeOffset, isSleeping]);
-
-  // Memoize the customized SVG to avoid unnecessary processing
-  const customizedSvg = useMemo(() => {
-    // Get form and base SVG
-    const { form, svg } = resolveAdultSvgWithForm(blobbi, { isSleeping });
-
-    // Apply color customization
-    const colorizedSvg = customizeAdultSvgFromBlobbi(svg, form, blobbi, isSleeping);
-
-    // Add eye animation wrappers when awake (eyes are closed when sleeping)
-    if (!isSleeping) {
-      // Pass base color for eyelid generation
-      let animatedSvg = addEyeAnimation(colorizedSvg, { baseColor: blobbi.baseColor, instanceId: blobbi.id });
-      
-      // Apply emotion overlays (eyebrows, sad mouth, tears, etc.)
-      // Pass form for form-specific adjustments (e.g., owli/froggi eyebrow positioning)
-      if (emotion !== 'neutral') {
-        animatedSvg = applyEmotion(animatedSvg, emotion, 'adult', form);
-      }
-      
-      return animatedSvg;
-    }
-
-    return colorizedSvg;
-  }, [blobbi, isSleeping, emotion]);
+  // ── Render ─────────────────────────────────────────────────────────────────
+  // In companion mode, reaction classes are applied by an outer wrapper to
+  // keep the dangerouslySetInnerHTML div className-stable.

  return (
    <div
      ref={containerRef}
      className={cn(
        'relative flex items-center justify-center',
-        // Reduced opacity when sleeping for visual feedback
-        isSleeping && 'opacity-70',
-        // Reaction animations for adult
-        (effectiveReaction === 'listening' ||
+        // No opacity change for sleeping — sleeping is a recipe overlay, not a visual dim
+        !isCompanion && (effectiveReaction === 'listening' ||
          effectiveReaction === 'swaying' ||
          effectiveReaction === 'happy') &&
          'animate-blobbi-sway',
-        effectiveReaction === 'singing' && 'animate-blobbi-bounce',
-        className
+        !isCompanion && effectiveReaction === 'singing' && 'animate-blobbi-bounce',
+        className,
      )}
-      // Safe: SVG content comes from our own trusted module
-      dangerouslySetInnerHTML={{ __html: customizedSvg }}
-    />
+    >
+      <BlobbiAdultSvgRenderer
+        blobbi={blobbi}
+        isSleeping={isSleeping}
+        recipe={recipe}
+        recipeLabel={recipeLabel}
+        emotion={emotion}
+        bodyEffects={bodyEffects}
+        className="size-full"
+      />
+    </div>
  );
 }
@@ -0,0 +1,100 @@
+/**
+ * BlobbiBabySvgRenderer — Pure SVG rendering component for baby Blobbi.
+ *
+ * This component is the leaf node of the visual pipeline. It:
+ *   1. Resolves the base SVG for the baby
+ *   2. Customizes colors and unique IDs
+ *   3. Adds eye animation infrastructure (blink clip-paths, gaze groups)
+ *   4. Applies visual recipe or emotion preset
+ *   5. Applies manual body effects (when no recipe is provided)
+ *   6. Sanitizes the SVG
+ *   7. Renders via dangerouslySetInnerHTML
+ *
+ * It does NOT know about:
+ *   - Eye tracking hooks (useBlobbiEyes / useExternalEyeOffset)
+ *   - Render mode (page vs companion)
+ *   - Reaction CSS classes (sway / bounce)
+ *   - Companion runtime (drag, float, position)
+ */
+
+import { useMemo } from 'react';
+
+import { resolveBabySvg, customizeBabySvgFromBlobbi } from '@/blobbi/baby-blobbi';
+import { sanitizeBlobbiSvg } from '@/lib/sanitizeBlobbiSvg';
+
+import { addEyeAnimation } from './lib/eye-animation';
+import { resolveVisualRecipe, applyVisualRecipe, type BlobbiVisualRecipe } from './lib/recipe';
+import type { BlobbiEmotion } from './lib/emotion-types';
+import { applyBodyEffects, type BodyEffectsSpec } from './lib/bodyEffects';
+import { debugBlobbi } from './lib/debug';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
+
+export interface BlobbiBabySvgRendererProps {
+  /** The Blobbi data */
+  blobbi: Blobbi;
+  /** Whether the Blobbi is sleeping */
+  isSleeping: boolean;
+  /** Pre-resolved visual recipe. Takes precedence over `emotion`. */
+  recipe?: BlobbiVisualRecipe;
+  /** Label for the recipe (used in CSS class names). */
+  recipeLabel?: string;
+  /** Named emotion preset. Ignored when `recipe` is provided. Default: 'neutral' */
+  emotion?: BlobbiEmotion;
+  /** Body-level visual effects (manual/external use only — not from status reaction). */
+  bodyEffects?: BodyEffectsSpec;
+  /** Additional CSS classes for the container */
+  className?: string;
+}
+
+/**
+ * Pure SVG renderer for baby Blobbi.
+ *
+ * IMPORTANT: This component must remain a pure rendering leaf. It must NOT:
+ * - Run eye-tracking hooks (those belong in the Visual wrapper)
+ * - Know about render modes or companion runtime
+ * - Apply reaction CSS classes (those belong on an outer wrapper)
+ *
+ * The parent Visual wrapper owns the DOM query boundary (containerRef)
+ * that eye hooks use to find SVG elements via querySelector.
+ */
+export function BlobbiBabySvgRenderer({
+  blobbi,
+  isSleeping: _isSleeping,
+  recipe: recipeProp,
+  recipeLabel,
+  emotion = 'neutral',
+  bodyEffects,
+  className,
+}: BlobbiBabySvgRendererProps) {
+  const customizedSvg = useMemo(() => {
+    debugBlobbi('svg-rebuild', 'baby customizedSvg rebuild');
+
+    // Always use the base (awake) SVG — sleeping is a recipe overlay, not an asset swap
+    const baseSvg = resolveBabySvg(blobbi, { isSleeping: false });
+    const colorizedSvg = customizeBabySvgFromBlobbi(baseSvg, blobbi, false);
+
+    let animatedSvg = addEyeAnimation(colorizedSvg, { baseColor: blobbi.baseColor, instanceId: blobbi.id });
+
+    if (recipeProp) {
+      animatedSvg = applyVisualRecipe(animatedSvg, recipeProp, recipeLabel ?? 'status', 'baby', undefined, blobbi.id);
+    } else if (emotion !== 'neutral') {
+      const resolved = resolveVisualRecipe(emotion);
+      animatedSvg = applyVisualRecipe(animatedSvg, resolved, emotion, 'baby', undefined, blobbi.id);
+    }
+
+    if (bodyEffects && !recipeProp) {
+      animatedSvg = applyBodyEffects(animatedSvg, { ...bodyEffects, idPrefix: bodyEffects.idPrefix ?? blobbi.id });
+    }
+
+    return animatedSvg;
+  }, [blobbi, recipeProp, recipeLabel, emotion, bodyEffects]);
+
+  const safeSvg = useMemo(() => sanitizeBlobbiSvg(customizedSvg), [customizedSvg]);
+
+  return (
+    <div
+      className={className}
+      dangerouslySetInnerHTML={{ __html: safeSvg }}
+    />
+  );
+}
@@ -1,156 +1,120 @@
 /**
- * BlobbiBabyVisual - Reusable component for rendering Blobbi babies
+ * BlobbiBabyVisual — Visual wrapper for rendering Blobbi babies.
 *
- * Uses the baby-blobbi module for SVG resolution and customization.
- * Handles awake vs sleeping states automatically.
- * Eyes always track the mouse cursor in real-time.
+ * Responsibilities:
+ *   - Owns the container ref for eye hooks to query SVG DOM
+ *   - Runs useBlobbiEyes (blink RAF loop, optional mouse tracking)
+ *   - Runs useExternalEyeOffset (companion gaze RAF loop)
+ *   - Applies reaction CSS classes (sway/bounce) in page mode
+ *   - Delegates SVG rendering to BlobbiBabySvgRenderer
+ *
+ * Render modes:
+ *   - 'page' (default): Mouse tracking enabled, reaction classes applied here.
+ *   - 'companion': Mouse tracking disabled (gaze via ref), reaction classes
+ *     suppressed (applied by outer companion wrapper instead).
 */

-import { useMemo, useRef, useEffect } from 'react';
+import { useRef, type RefObject } from 'react';

-import { resolveBabySvg, customizeBabySvgFromBlobbi } from '@/blobbi/baby-blobbi';
-import { addEyeAnimation } from './lib/eye-animation';
-import { applyEmotion, type BlobbiEmotion } from './lib/emotions';
-import { useBlobbiEyes, type BlobbiLookMode } from './lib/useBlobbiEyes';
 import { cn } from '@/lib/utils';
-import type { Blobbi } from '@/types/blobbi';
-import { isBlobbiSleeping } from '@/types/blobbi';

-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/**
- * Reaction states for baby Blobbi animations
- */
-export type BabyReactionState = 'idle' | 'listening' | 'swaying' | 'singing' | 'happy';
-
-/**
- * External eye offset for companion control
- * Values range from -1 to 1, converted to pixel movement internally
- */
-export interface ExternalEyeOffset {
-  x: number;
-  y: number;
-}
+import { useBlobbiEyes, type BlobbiLookMode } from './lib/useBlobbiEyes';
+import { useExternalEyeOffset } from './lib/useExternalEyeOffset';
+import type { ExternalEyeOffset, BlobbiReactionState, BlobbiRenderMode } from './lib/types';
+import type { BlobbiVisualRecipe } from './lib/recipe';
+import type { BlobbiEmotion } from './lib/emotion-types';
+import type { BodyEffectsSpec } from './lib/bodyEffects';
+import type { Blobbi } from '@/blobbi/core/types/blobbi';
+import { isBlobbiSleeping } from '@/blobbi/core/types/blobbi';
+import { BlobbiBabySvgRenderer } from './BlobbiBabySvgRenderer';

 export interface BlobbiBabyVisualProps {
-  /** The Blobbi data */
  blobbi: Blobbi;
-  /** Reaction state for music/sing animations */
-  reaction?: BabyReactionState;
-  /** Controls eye tracking behavior (default: 'follow-pointer') */
+  reaction?: BlobbiReactionState;
  lookMode?: BlobbiLookMode;
-  /** Disable blinking animation (for photo/export mode) */
  disableBlink?: boolean;
-  /** 
-   * External eye offset from companion system.
-   * When provided, bypasses internal mouse tracking and uses this offset directly.
-   * Values should be -1 to 1, will be converted to pixel movement.
-   */
  externalEyeOffset?: ExternalEyeOffset;
-  /** 
-   * Emotional state to display.
-   * Adds visual overlays like eyebrows, modified mouth, and tears.
-   * Default: 'neutral' (no modifications)
-   */
+  /** Ref-based external eye offset (imperative — no rerenders). Preferred for companion mode. */
+  externalEyeOffsetRef?: RefObject<ExternalEyeOffset>;
+  /** Render mode. Default: 'page'. */
+  renderMode?: BlobbiRenderMode;
+  /** Pre-resolved visual recipe. Takes precedence over `emotion`. */
+  recipe?: BlobbiVisualRecipe;
+  /** Label for the recipe (CSS class names). */
+  recipeLabel?: string;
+  /** Named emotion preset. Ignored when `recipe` is provided. */
  emotion?: BlobbiEmotion;
-  /** Additional CSS classes for the container */
+  /** Body-level visual effects — for manual/external use only. */
+  bodyEffects?: BodyEffectsSpec;
  className?: string;
 }

-// ─── Component ────────────────────────────────────────────────────────────────
-
-/**
- * Renders a baby Blobbi using inline SVG.
- *
- * - Resolves the correct SVG (awake or sleeping) based on state
- * - Applies color customization from Blobbi traits
- * - Eyes always track the mouse cursor (instant, real-time)
- * - Renders safely using dangerouslySetInnerHTML
- */
-export function BlobbiBabyVisual({ blobbi, reaction = 'idle', lookMode = 'follow-pointer', disableBlink = false, externalEyeOffset, emotion = 'neutral', className }: BlobbiBabyVisualProps) {
+export function BlobbiBabyVisual({
+  blobbi,
+  reaction = 'idle',
+  lookMode = 'follow-pointer',
+  disableBlink = false,
+  externalEyeOffset,
+  externalEyeOffsetRef,
+  renderMode = 'page',
+  recipe,
+  recipeLabel,
+  emotion = 'neutral',
+  bodyEffects,
+  className,
+}: BlobbiBabyVisualProps) {
  const isSleeping = isBlobbiSleeping(blobbi);
+
+  // DOM query boundary for eye hooks. See BlobbiAdultVisual for details.
  const containerRef = useRef<HTMLDivElement>(null);

-  // Disable reactions when sleeping
+  const isCompanion = renderMode === 'companion';
+
  const effectiveReaction = isSleeping ? 'idle' : reaction;

-  // Eye animation hook - handles DOM manipulation internally
-  // When externalEyeOffset is provided, we disable tracking but keep blinking
+  // ── Eye hooks ──────────────────────────────────────────────────────────────
+
  useBlobbiEyes(containerRef, {
    isSleeping,
    maxMovement: 2,
    lookMode,
    disableBlink,
-    disableTracking: !!externalEyeOffset, // External system controls eye position
+    disableTracking: isCompanion,
  });

-  // External eye offset control - applies offset directly when provided
-  // This bypasses useBlobbiEyes and gives companion full control
-  useEffect(() => {
-    if (!externalEyeOffset || !containerRef.current || isSleeping) return;
+  useExternalEyeOffset({
+    containerRef,
+    externalEyeOffset,
+    externalEyeOffsetRef,
+    isSleeping,
+    variant: 'baby',
+  });

-    const eyeElements = containerRef.current.querySelectorAll<SVGGElement>('.blobbi-eye-left, .blobbi-eye-right');
-    if (eyeElements.length === 0) return;
-
-    // Convert -1 to 1 offset to pixel movement
-    // Increased max movement for more visible eye tracking (4px horizontal)
-    const maxMovementX = 4;
-    const x = externalEyeOffset.x * maxMovementX;
-    
-    // Asymmetric vertical movement:
-    // - Upward (negative y): stronger movement (1.0x) for clear "looking up" effect
-    // - Downward (positive y): reduced movement (0.6x) to avoid looking too droopy
-    // Y offset: -1 = looking up, +1 = looking down
-    const maxMovementYUp = 4;    // Full range for looking up
-    const maxMovementYDown = 2.4; // Reduced range for looking down (0.6x)
-    const y = externalEyeOffset.y < 0 
-      ? externalEyeOffset.y * maxMovementYUp    // Looking up: full range
-      : externalEyeOffset.y * maxMovementYDown; // Looking down: reduced range
-
-    eyeElements.forEach(el => {
-      el.setAttribute('transform', `translate(${x} ${y})`);
-    });
-  }, [externalEyeOffset, isSleeping]);
-
-  // Memoize the customized SVG to avoid unnecessary processing
-  const customizedSvg = useMemo(() => {
-    const baseSvg = resolveBabySvg(blobbi, { isSleeping });
-    const colorizedSvg = customizeBabySvgFromBlobbi(baseSvg, blobbi, isSleeping);
-
-    // Add eye animation wrappers (only when not sleeping)
-    if (!isSleeping) {
-      // Pass base color for eyelid generation
-      let animatedSvg = addEyeAnimation(colorizedSvg, { baseColor: blobbi.baseColor, instanceId: blobbi.id });
-      
-      // Apply emotion overlays (eyebrows, sad mouth, tears, etc.)
-      // Pass 'baby' variant for baby-specific adjustments (e.g., eyebrow positioning)
-      if (emotion !== 'neutral') {
-        animatedSvg = applyEmotion(animatedSvg, emotion, 'baby');
-      }
-      
-      return animatedSvg;
-    }
-
-    return colorizedSvg;
-  }, [blobbi, isSleeping, emotion]);
+  // ── Render ─────────────────────────────────────────────────────────────────

  return (
    <div
      ref={containerRef}
      className={cn(
        'relative flex items-center justify-center',
-        // Reduced opacity when sleeping for visual feedback
-        isSleeping && 'opacity-70',
-        // Reaction animations for baby
-        (effectiveReaction === 'listening' ||
+        // No opacity change for sleeping — sleeping is a recipe overlay, not a visual dim
+        !isCompanion && (effectiveReaction === 'listening' ||
          effectiveReaction === 'swaying' ||
          effectiveReaction === 'happy') &&
          'animate-blobbi-sway',
-        effectiveReaction === 'singing' && 'animate-blobbi-bounce',
-        className
+        !isCompanion && effectiveReaction === 'singing' && 'animate-blobbi-bounce',
+        className,
      )}
-      // Safe: SVG content comes from our own trusted module
-      dangerouslySetInnerHTML={{ __html: customizedSvg }}
-    />
+    >
+      <BlobbiBabySvgRenderer
+        blobbi={blobbi}
+        isSleeping={isSleeping}
+        recipe={recipe}
+        recipeLabel={recipeLabel}
+        emotion={emotion}
+        bodyEffects={bodyEffects}
+        className="size-full"
+      />
+    </div>
  );
 }
@@ -13,17 +13,17 @@

 import { useMemo } from 'react';

-import { EggGraphic, type EggReactionState } from '@/blobbi/egg';
-import { toEggGraphicVisualBlobbi } from '@/lib/blobbi-egg-adapter';
+import { EggGraphic, type EggReactionState, type EggStatusEffects } from '@/blobbi/egg';
+import { toEggGraphicVisualBlobbi } from '@/blobbi/core/lib/blobbi-egg-adapter';
 import { cn } from '@/lib/utils';
-import type { BlobbiCompanion } from '@/lib/blobbi';
+import type { BlobbiCompanion } from '@/blobbi/core/lib/blobbi';

 // ─── Types ────────────────────────────────────────────────────────────────────

 export type BlobbiEggSize = 'sm' | 'md' | 'lg';

 // Re-export for convenience
-export type { EggReactionState } from '@/blobbi/egg';
+export type { EggReactionState, EggStatusEffects } from '@/blobbi/egg';

 export interface BlobbiEggVisualProps {
  /** The Blobbi companion data from parseBlobbiEvent */
@@ -34,6 +34,8 @@ export interface BlobbiEggVisualProps {
  animated?: boolean;
  /** Reaction state for music/sing animations */
  reaction?: EggReactionState;
+  /** Status effects for egg visual feedback (dirty, sick, happy) */
+  statusEffects?: EggStatusEffects;
  /** Additional CSS classes for the container */
  className?: string;
 }
@@ -67,6 +69,7 @@ export function BlobbiEggVisual({
  size = 'md',
  animated = false,
  reaction = 'idle',
+  statusEffects,
  className,
 }: BlobbiEggVisualProps) {
  // Memoize adapter output to avoid unnecessary re-renders
@@ -99,6 +102,7 @@ export function BlobbiEggVisual({
        sizeVariant={config.sizeVariant}
        animated={animated && !isSleeping}
        reaction={effectiveReaction}
+        statusEffects={isSleeping ? undefined : statusEffects}
      />
    </div>
  );
--- a/Show More
+++ b/Show More