release: v2.6.6

Remove resizeOnFullScreen config which caused possiblyResizeChildOfContent()
to corrupt CoordinatorLayout height on Android 16 (API 36). Upgrade plugin
from 8.0.2 to 8.0.3 which adds a SystemBars guard as additional safety.
Platform-gate setAccessoryBarVisible to iOS only (unimplemented on Android).

.agents/skills/lockdown-mode/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: lockdown-mode
+description: Apple Lockdown Mode restrictions and their impact on web APIs inside WKWebView/Safari/WebView. Reference when debugging or building features for lockdown-enabled devices.
+---
+
+# Apple Lockdown Mode
+
+Apple's Lockdown Mode is an opt-in security hardening profile that disables or restricts many web platform APIs inside Safari and WKWebView. Since this app ships inside a Capacitor WKWebView shell, **every restriction that applies to Safari also applies to our app**.
+
+## Platform Availability
+
+Lockdown Mode is available on:
+
+- **iOS 16** or later (iPhone)
+- **iPadOS 16** or later (iPad)
+- **watchOS 10** or later (Apple Watch)
+- **macOS Ventura** or later (Mac)
+
+Additional protections are available starting in iOS 17, iPadOS 17, watchOS 10, and macOS Sonoma.
+
+For full details, see [About Lockdown Mode](https://support.apple.com/en-us/105120) on Apple Support.
+
+## Testing Baseline
+
+This document is based on testing against **iOS 18.7 / Safari 26.4** on an iPhone with Lockdown Mode enabled (April 2026). The web API restrictions documented below apply to Safari and WKWebView across all supported platforms (iOS, iPadOS, and macOS).
+
+## Blocked APIs
+
+These APIs are **completely unavailable** (return `undefined`, `null`, or throw) when Lockdown Mode is active.
+
+| API | Impact | Notes |
+|-----|--------|-------|
+| **IndexedDB** | Critical | `indexedDB` global is missing entirely. Any library that relies on IndexedDB for storage will fail (Dexie, idb, localForage with IndexedDB driver, etc.). |
+| **Service Workers** | High | `navigator.serviceWorker` is absent. No offline caching, no background sync, no push notifications via SW. |
+| **Cache API** | High | `caches` global is absent. Often used alongside Service Workers for offline strategies. |
+| **WebAssembly** | High | `WebAssembly` global is `undefined`. Libraries compiled to WASM (e.g. libsodium-wrappers, secp256k1-wasm, SQLite WASM) will not load. |
+| **Web Locks** | High | `navigator.locks` is absent. Cross-tab coordination patterns that depend on this will break silently. |
+| **WebRTC** | High | `RTCPeerConnection` is absent. No peer-to-peer audio/video/data channels. |
+| **WebGL / WebGL2** | Medium | All canvas `getContext('webgl'*)` calls return `null`. GPU-accelerated rendering, maps (Mapbox GL, deck.gl), and 3D are broken. |
+| **FileReader** | Medium | `FileReader` constructor is absent. Cannot read `Blob`/`File` objects client-side (e.g. image preview before upload). Use the `File` constructor + `URL.createObjectURL()` as a workaround for previews. |
+| **SharedArrayBuffer** | Medium | `SharedArrayBuffer` is `undefined`. May also require COOP/COEP headers on non-lockdown browsers, so this is often already unavailable. |
+| **Speech Synthesis** | Low | `window.speechSynthesis` is absent. Text-to-speech features won't work. |
+| **Notifications API** | Low | `Notification` is absent. Web push permission prompts won't appear. (Capacitor local notifications via the native plugin are unaffected.) |
+| **WebCodecs** | Low | `VideoDecoder` / `VideoEncoder` are absent (`AudioDecoder` remains). Low-level media processing is unavailable. |
+| **Gamepad API** | Low | `navigator.getGamepads` is absent. |
+| **OPFS** | Medium | `navigator.storage.getDirectory` method does not exist. The `navigator.storage` object is present but the Origin Private File System API is stripped. SQLite-over-OPFS and any other OPFS-based storage will fail. |
+| **Web Share API** | Low | `navigator.share` is absent. Use Capacitor's `@capacitor/share` plugin instead -- the native share sheet still works. |
+
+## Available APIs
+
+These APIs **still work** under Lockdown Mode and can be relied on.
+
+| API | Notes |
+|-----|-------|
+| **File constructor** | `new File(...)` works. You can create File/Blob objects. |
+| **FontFace API** | Dynamic font loading via `new FontFace()` succeeds. Remote font fetches may fail with a network error (data URIs rejected). |
+| **JIT compilation** | JavaScript JIT appears active (~110ms for 1M iterations). Performance is not interpreter-level degraded. |
+| **PDF viewer** | `navigator.pdfViewerEnabled` is `true`. Inline `<embed type="application/pdf">` works. |
+| **Cookies** | `navigator.cookieEnabled` is `true`. |
+| **Credential Management** | `navigator.credentials` is available. |
+| **localStorage / sessionStorage** | Standard Web Storage APIs remain functional. |
+
+## Implications for This App
+
+### Storage
+
+- **localStorage works** -- our primary client-side storage (app config, relay lists, etc.) is unaffected.
+- **IndexedDB is gone** -- if any dependency silently uses IndexedDB (e.g. some Nostr caching layers, TanStack Query persisters), it will fail. Ensure all storage paths fall back to localStorage or in-memory.
+- **OPFS is gone** -- `navigator.storage.getDirectory` is stripped (the method doesn't exist, though the `navigator.storage` object itself remains). SQLite-over-OPFS (e.g. wa-sqlite, sql.js with OPFS backend) and any other OPFS-based persistence will not work.
+
+### Cryptography
+
+- **WebAssembly is blocked** -- any WASM-based crypto libraries (secp256k1 compiled to WASM, libsodium WASM builds) will not load. Use pure-JS implementations (e.g. `@noble/secp256k1`, `@noble/hashes`) which are already what nostr-tools uses.
+- **WebCrypto (`crypto.subtle`)** -- not listed as blocked in testing. The SubtleCrypto API should still be available for NIP-44 encryption via the standard Web Crypto path.
+
+### Media & Rendering
+
+- **WebGL is gone** -- map libraries that require WebGL (Mapbox GL JS, Google Maps WebGL renderer) will show blank canvases. Use raster tile alternatives or static map images.
+- **FileReader is gone** -- image/file preview workflows that use `FileReader.readAsDataURL()` need a workaround. Use `URL.createObjectURL(file)` directly for `<img src>` previews instead.
+
+### Communication
+
+- **WebRTC is gone** -- any peer-to-peer features (voice/video calls, WebRTC data channels) are completely unavailable.
+- **Fetch / XMLHttpRequest** -- standard network requests appear unaffected. Relay WebSocket connections should work normally.
+
+### Native Plugin Workarounds
+
+Several blocked web APIs have Capacitor plugin equivalents that bypass WKWebView restrictions entirely:
+
+| Blocked Web API | Capacitor Alternative |
+|---|---|
+| Web Share | `@capacitor/share` (already installed) |
+| Notifications | `@capacitor/local-notifications` (already installed) |
+| File downloads | `@capacitor/filesystem` + share (already implemented in `downloadFile.ts`) |
+
+### Detection
+
+The report used a scoring heuristic (8/12 key APIs blocked = 70%) to detect Lockdown Mode. There is no official API to query Lockdown Mode status. Detection relies on probing for the absence of multiple APIs that are specifically disabled by Lockdown Mode but normally present in Safari.
+
+## Raw Diagnostic Report
+
+For exact error messages, navigator properties, weight scores, and per-API diagnostic output, see [ios-report.txt](ios-report.txt).
+
+## Guidance for Feature Decisions
+
+When building new features, consider:
+
+1. **Always provide pure-JS fallbacks** for any crypto or data-processing library that might ship a WASM build.
+2. **Never depend on IndexedDB or OPFS** as the sole storage mechanism. Both are completely stripped. Always fall back to localStorage or in-memory stores.
+3. **Avoid WebGL-dependent UI** for core functionality. Use it as a progressive enhancement with a CSS/Canvas 2D fallback.
+4. **Use Capacitor plugins** for sharing, notifications, and file operations rather than web APIs -- they work on all native platforms regardless of Lockdown Mode.
+5. **Test on a Lockdown Mode device** when shipping features that touch storage, crypto, or media APIs.

.agents/skills/lockdown-mode/ios-report.txt

@@ -0,0 +1,229 @@
+============================================================
+LOCKDOWN MODE DETECTOR REPORT
+2026-04-06T23:40:58.170Z
+============================================================
+
+VERDICT: Lockdown Mode Likely Active
+8 of 12 key APIs are blocked, consistent with iOS/macOS Lockdown Mode.
+Score: 70% (8/12 key APIs blocked)
+
+============================================================
+API TEST RESULTS (detailed)
+============================================================
+
+------------------------------------------------------------
+[BLOCKED] IndexedDB (weight: 3)
+  Client-side structured storage
+  Result: Can't find variable: indexedDB
+  Diagnostics:
+    uncaught: Can't find variable: indexedDB
+
+------------------------------------------------------------
+[BLOCKED] WebAssembly (weight: 2)
+  Binary instruction execution
+  Result: WebAssembly is undefined
+  Diagnostics:
+    typeof WebAssembly: undefined
+    WebAssembly global does not exist
+
+------------------------------------------------------------
+[BLOCKED] Web Locks API (weight: 3)
+  Cross-tab resource coordination
+  Result: navigator.locks is undefined
+  Diagnostics:
+    typeof navigator.locks: undefined
+    'locks' in navigator: false
+    navigator.locks is falsy
+
+------------------------------------------------------------
+[BLOCKED] Speech Synthesis (weight: 3)
+  Web Speech API (text-to-speech)
+  Result: window.speechSynthesis is undefined
+  Diagnostics:
+    typeof window.speechSynthesis: undefined
+    'speechSynthesis' in window: false
+    typeof SpeechSynthesisUtterance: undefined
+    speechSynthesis is falsy
+
+------------------------------------------------------------
+[BLOCKED] FileReader API (weight: 2)
+  Local file reading interface
+  Result: FileReader is undefined
+  Diagnostics:
+    typeof FileReader: undefined
+    FileReader constructor does not exist
+
+------------------------------------------------------------
+[AVAILABLE] File Constructor (weight: 2)
+  File object creation
+  Result: File created: name=test.txt size=4
+  Diagnostics:
+    typeof File: function
+    calling new File(['test'], 'test.txt', {type:'text/plain'})...
+    succeeded
+    f.name: test.txt
+    f.size: 4
+    f.type: text/plain
+    f instanceof Blob: true
+
+------------------------------------------------------------
+[BLOCKED] WebGL (weight: 2)
+  GPU-accelerated graphics
+  Result: all WebGL contexts returned null
+  Diagnostics:
+    getContext('webgl2'): null
+    getContext('webgl'): null
+    getContext('experimental-webgl'): null
+
+------------------------------------------------------------
+[BLOCKED] WebGL2 (weight: 1)
+  Advanced GPU graphics context
+  Result: getContext('webgl2') returned null
+  Diagnostics:
+    getContext('webgl2'): null
+
+------------------------------------------------------------
+[BLOCKED] Service Worker (weight: 1)
+  Background script registration
+  Result: navigator.serviceWorker not present
+  Diagnostics:
+    'serviceWorker' in navigator: false
+    typeof navigator.serviceWorker: undefined
+
+------------------------------------------------------------
+[BLOCKED] Web Share API (weight: 0)
+  Native sharing interface
+  Result: navigator.share is undefined
+  Diagnostics:
+    typeof navigator.share: undefined
+    typeof navigator.canShare: undefined
+
+------------------------------------------------------------
+[BLOCKED] Gamepad API (weight: 1)
+  Game controller input
+  Result: navigator.getGamepads not present
+  Diagnostics:
+    'getGamepads' in navigator: false
+
+------------------------------------------------------------
+[BLOCKED] WebRTC (weight: 2)
+  Real-time peer communication
+  Result: RTCPeerConnection is undefined
+  Diagnostics:
+    typeof RTCPeerConnection: undefined
+    typeof webkitRTCPeerConnection: undefined
+
+------------------------------------------------------------
+[AVAILABLE] FontFace API (weight: 1)
+  Dynamic font loading
+  Result: status: loaded
+  Diagnostics:
+    typeof FontFace: function
+    new FontFace() succeeded
+    ff.status: unloaded
+    ff.family: test
+    ff.status after load: loaded
+
+------------------------------------------------------------
+[AVAILABLE] Remote Fonts (weight: 2)
+  Loading fonts from network via data URI
+  Result: API works, load rejected:  A network error occurred.
+  Diagnostics:
+    FontFace created with data URI
+    ff.status before load: unloaded
+    caught: DOMException:  A network error occurred.
+
+------------------------------------------------------------
+[AVAILABLE] JIT Compilation (weight: 2)
+  JavaScript JIT optimization heuristic
+  Result: 99.0ms for 1M iterations (JIT likely)
+  Diagnostics:
+    running 1,000,000 iterations of Math.sqrt*Math.sin...
+    elapsed: 99.00ms
+    sum (to prevent dead-code elimination): -681.7597
+    threshold: <150ms suggests JIT active
+    verdict: likely JIT
+
+------------------------------------------------------------
+[BLOCKED] Notifications API (weight: 1)
+  Push notification permission
+  Result: Notification not in window
+  Diagnostics:
+    'Notification' in window: false
+    typeof Notification: undefined
+
+------------------------------------------------------------
+[BLOCKED] WebCodecs (weight: 1)
+  Low-level VideoDecoder API
+  Result: VideoDecoder is undefined
+  Diagnostics:
+    typeof VideoDecoder: undefined
+    typeof VideoEncoder: undefined
+    typeof AudioDecoder: function
+
+------------------------------------------------------------
+[AVAILABLE] PDF Embed (weight: 2)
+  Inline PDF rendering via embed/pdfViewerEnabled
+  Result: pdfViewerEnabled is true
+  Diagnostics:
+    navigator.pdfViewerEnabled: true
+    typeof navigator.pdfViewerEnabled: boolean
+    created and appended <embed type=application/pdf>
+    navigator.mimeTypes['application/pdf']: [object MimeType]
+
+------------------------------------------------------------
+[BLOCKED] SharedArrayBuffer (weight: 1)
+  Shared memory between workers
+  Result: SharedArrayBuffer is undefined
+  Diagnostics:
+    typeof SharedArrayBuffer: undefined
+    requires COOP/COEP headers to be present; may not indicate Lockdown Mode specifically
+
+------------------------------------------------------------
+[BLOCKED] Cache API (weight: 1)
+  Programmatic HTTP cache (CacheStorage)
+  Result: caches not in window
+  Diagnostics:
+    'caches' in window: false
+    typeof caches: undefined
+
+------------------------------------------------------------
+[BLOCKED] OPFS (weight: 2)
+  Origin Private File System (navigator.storage.getDirectory)
+  Result: navigator.storage.getDirectory is not a function
+  Diagnostics:
+    typeof navigator.storage: object
+    typeof navigator.storage.getDirectory: undefined
+    getDirectory method does not exist
+
+============================================================
+NAVIGATOR INFO
+============================================================
+
+  userAgent:             Mozilla/5.0 (iPhone; CPU iPhone OS 18_7 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/26.4 Mobile/15E148 Safari/604.1
+  platform:              iPhone
+  vendor:                Apple Computer, Inc.
+  language:              en-US
+  languages:             en-US
+  cookieEnabled:         true
+  doNotTrack:            null
+  maxTouchPoints:        5
+  hardwareConcurrency:   4
+  deviceMemory:          N/A
+  pdfViewerEnabled:      true
+  webdriver:             false
+  connection:            unavailable
+  mediaDevices:          unavailable
+  storage:               available
+  serviceWorker:         unavailable
+  credentials:           available
+  bluetooth:             unavailable
+  gpu (WebGPU):          unavailable
+  screenWidth:           393
+  screenHeight:          852
+  devicePixelRatio:      3
+  colorDepth:            24
+
+============================================================
+END OF REPORT
+============================================================

.agents/skills/release/SKILL.md

@@ -108,6 +108,7 @@ Prepend a new section to `CHANGELOG.md` directly below the `# Changelog` heading
 - Use present tense ("Add dark mode toggle", not "Added dark mode toggle")
 - Focus on what the user sees/experiences, not internal implementation details
 - Use the current date in YYYY-MM-DD format
+- **Never use Nostr protocol jargon.** NIP numbers (e.g., "NIP-89", "NIP-17"), kind numbers (e.g., "kind 30078"), and other protocol-level references must not appear in the changelog. Describe the feature in plain language from the user's perspective. For example, write "App cards for Nostr apps" instead of "App cards for Nostr apps (NIP-89)". The changelog audience is end users, not protocol developers.
 - **Collapse related work into one entry.** If a feature was added and then fixed/tweaked across multiple commits in the same release, present the finished result as a single "Added" entry. Never list something as "Added" and then also list fixes for that same thing -- the user sees the end product, not the development history.
 - **Omit purely internal changes.** CI fixes, build pipeline tweaks, developer tooling, and infrastructure changes should be omitted from the changelog entirely unless they have a direct, visible impact on the user experience. The changelog is for users, not developers.
 - **Compare the actual code between versions** to understand what really changed, rather than just reading commit messages. Commit messages may over- or under-represent the significance of changes.

.env.example

@@ -2,4 +2,6 @@ VITE_SENTRY_DSN="https://********************************@*****************.exam
 VITE_PLAUSIBLE_DOMAIN="example.tld"
 VITE_PLAUSIBLE_ENDPOINT="https://plausible.example.tld/api/event"
 # Hex pubkey of the nostr-push server (found in nostr-push startup logs as "worker_pubkey")
-VITE_NOSTR_PUSH_PUBKEY=""
+VITE_NOSTR_PUSH_PUBKEY=""
+# Set to "*" to allow any host in the Vite dev server (eg. when proxying through a custom domain)
+# ALLOWED_HOSTS="*"

.gitlab-ci.yml

@@ -26,19 +26,52 @@ 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
+    - 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"
+      --use-fallback-relays
+      --use-fallback-servers
+
+build-web:
+  stage: build
+  timeout: 10 minutes
+  needs: []
+  rules:
+    - if: $CI_COMMIT_TAG
+      when: never
+    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
+  script:
+    - npm ci
+    - npm run build
+    - cp dist/index.html dist/404.html
   artifacts:
     paths:
-      - public
-  only:
-    variables:
-      - $CI_DEFAULT_BRANCH == $CI_COMMIT_REF_NAME
+      - dist/
 
 build-apk:
   stage: build
@@ -112,8 +145,9 @@ build-apk:
     - npx vite build -l error
     - cp dist/index.html dist/404.html
 
-    # Sync web assets to Capacitor Android project
+    # Sync web assets to Capacitor Android project and register local plugins
     - npx cap sync android
+    - node scripts/patch-cap-config.mjs
 
     # Build signed release APK
     - cd android && chmod +x gradlew && ./gradlew assembleRelease bundleRelease && cd ..
@@ -185,6 +219,8 @@ publish-zapstore:
     - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
   variables:
     SIGN_WITH: $ZAPSTORE_BUNKER_URL
+    RELAY_URLS: "wss://relay.zapstore.dev,wss://relay.ditto.pub,wss://relay.dreamith.to,wss://relay.primal.net"
+    BLOSSOM_URL: "https://blossom.ditto.pub"
   script:
     - go install github.com/zapstore/zsp@latest
 
@@ -198,4 +234,33 @@ 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
+
+publish-google-play:
+  stage: publish
+  image: ruby:3.3
+  needs:
+    - build-apk
+  rules:
+    - if: $CI_COMMIT_TAG =~ /^v\d+\.\d+\.\d+$/
+  script:
+    - gem install fastlane --no-document
+
+    # Decode base64-encoded service account JSON to a temp file
+    - echo "$GOOGLE_PLAY_SERVICE_ACCOUNT_JSON" | base64 -d > /tmp/play-service-account.json
+
+    # Upload the AAB to Google Play production track
+    - >-
+      fastlane supply
+      --aab artifacts/Ditto.aab
+      --package_name pub.ditto.app
+      --track production
+      --json_key /tmp/play-service-account.json
+      --skip_upload_metadata
+      --skip_upload_changelogs
+      --skip_upload_images
+      --skip_upload_screenshots
+      --skip_upload_apk
+
+    # Clean up
+    - rm -f /tmp/play-service-account.json

.gitlab/merge_request_templates/Default.md

@@ -0,0 +1,68 @@
+Thanks for contributing to Ditto! Please read [CONTRIBUTING.md](CONTRIBUTING.md) in full before submitting -- it covers everything you need to get your MR accepted.
+
+## Related Issue
+
+<!-- Link the GitLab issue. MRs without a linked issue will not be reviewed. -->
+
+Closes #
+
+## What Changed
+
+<!-- 1-3 sentences: what you changed and why. -->
+
+## Live Preview
+
+<!-- REQUIRED for UI changes. Deploy your branch and paste the URL. -->
+<!-- Example: npx surge dist your-branch.surge.sh -->
+<!-- Write "N/A -- no UI changes" only if this MR has zero visual impact. -->
+
+## Screenshots
+
+<!-- REQUIRED for UI changes. Show before and after. -->
+<!-- Write "N/A -- no UI changes" only if this MR has zero visual impact. -->
+
+**Before:**
+
+
+**After:**
+
+## Philosophy Alignment
+
+<!-- Answer this question for your change: -->
+<!-- "Does this make Ditto more magnetic, more threatening to the status quo, -->
+<!-- and more peaceful to inhabit?" -->
+<!-- See: https://about.ditto.pub/philosophy -->
+<!-- For bug fixes: "Bug fix -- restores intended behavior" is acceptable. -->
+
+## How to Test
+
+<!-- Steps a reviewer can follow to verify this works. -->
+
+1.
+2.
+3.
+
+## Self-Review Checklist
+
+<!-- Complete ALL items. MRs with unchecked boxes will not be reviewed. -->
+<!-- Check a box: replace [ ] with [x] -->
+
+### Process
+
+- [ ] I read `AGENTS.md` before starting
+- [ ] I read the [Ditto Philosophy](https://about.ditto.pub/philosophy)
+- [ ] I used plan/research mode before writing code
+- [ ] I used Claude Opus 4.6 (or equivalent frontier model)
+
+### Self-review
+
+Copy-paste this into your AI tool and fix any findings before submitting:
+
+> Review this diff against the self-review checklist in CONTRIBUTING.md step 8. Read that file first, then check every item. For each finding, state the file, line, and issue.
+
+- [ ] I ran the self-review prompt above and addressed all findings
+
+### Testing
+
+- [ ] I ran `npm run test` locally and it passes
+- [ ] I tested the change manually in the browser

AGENTS.md

@@ -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
 
@@ -407,6 +409,74 @@ Without filtering approvals by the moderator list, anyone could publish kind 455
 
 Author filtering is not needed for public user-generated content where anyone should be able to post (kind 1 notes, reactions, discovery queries, public feeds, etc.).
 
+#### Sanitizing URLs from Event Data
+
+**CRITICAL**: Any URL extracted from Nostr event tags, content, or metadata fields is **untrusted user input**. Malicious URLs can cause harm in many ways beyond `javascript:` XSS — `data:` URIs for resource exhaustion, `http://` URLs leaking user IPs without TLS, relative paths triggering unintended requests to the app's own origin, and more. Reasoning about which rendering context is "safe enough" to skip sanitization is fragile and error-prone.
+
+**Rule: sanitize every event-sourced URL unconditionally**, regardless of where it will be used (`href`, `img src`, `style`, etc.). Use `sanitizeUrl()` from `@/lib/sanitizeUrl`:
+
+```typescript
+import { sanitizeUrl } from '@/lib/sanitizeUrl';
+
+// Single URL — returns the normalised href, or undefined if not valid https
+const url = sanitizeUrl(getTag(event.tags, 'url'));
+if (url) {
+  // safe to use in any context
+}
+
+// Array of URLs — filter out invalid entries
+const links = getAllTags(event.tags, 'r')
+  .map(([, v]) => sanitizeUrl(v))
+  .filter((v): v is string => !!v);
+```
+
+`sanitizeUrl` accepts `string | undefined | null` and returns the normalised `href` string only when the URL parses successfully **and** uses the `https:` protocol. All other inputs (malformed URLs, `javascript:`, `data:`, `http:`, relative paths, etc.) return `undefined`.
+
+**Best practice — sanitize at the parse layer.** When writing a parser function that extracts URLs from event tags (e.g. `parseThemeDefinition`, `parseBadgeDefinition`), apply `sanitizeUrl()` before returning the parsed data. This way every downstream consumer is automatically protected without needing to remember to sanitize at each usage site.
+
+**When sanitization is NOT required:**
+- URLs extracted by regex that already constrains the protocol (e.g. `NoteContent` tokeniser matches only `https?://`)
+- Hardcoded or application-generated URLs (relay configs, internal routes, etc.)
+- URLs displayed as plain text without being placed into any HTML attribute or CSS value
+
+#### Preventing CSS Injection from Event Data
+
+**CRITICAL**: Any value from a Nostr event that is interpolated into a CSS string (inside a `<style>` element or inline `style` attribute) is a CSS injection vector. A malicious value containing `"`, `)`, `}`, or `;` can break out of the CSS context and inject arbitrary rules — for example, overlaying phishing content or hiding UI elements.
+
+**Common CSS injection surfaces:**
+- `background-image: url("${url}")` — a URL with `"); body { display:none }` breaks out
+- `font-family: "${family}"` — a family name with `"; } body { visibility:hidden } .x {` breaks out
+- `@font-face { src: url("${url}") }` — same risk as background URLs
+
+**Mitigation strategy — sanitize at the parse layer:**
+
+1. **URLs in CSS `url()` values**: Pass through `sanitizeUrl()` at parse time. The `URL` constructor normalises the string, percent-encoding characters like `"`, `)`, and `\` that could escape the CSS context. Invalid or non-`https:` URLs are rejected entirely. This is already done for theme event background and font URLs in `src/lib/themeEvent.ts`.
+
+2. **Strings in CSS declarations** (e.g. font family names): Use `sanitizeCssString()` from `src/lib/fontLoader.ts`, which uses an allowlist approach — only Unicode letters, numbers, spaces, hyphens, underscores, apostrophes, and periods are permitted. Everything else is stripped.
+
+```typescript
+// ❌ UNSAFE — raw event data interpolated into CSS
+const bgUrl = getTagValue(event.tags, 'bg');
+style.textContent = `body { background-image: url("${bgUrl}"); }`;
+
+const family = getTagValue(event.tags, 'f');
+style.textContent = `html { font-family: "${family}"; }`;
+
+// ✅ SAFE — URLs validated, strings sanitised
+import { sanitizeUrl } from '@/lib/sanitizeUrl';
+
+const bgUrl = sanitizeUrl(getTagValue(event.tags, 'bg'));
+if (bgUrl) {
+  style.textContent = `body { background-image: url("${bgUrl}"); }`;
+}
+
+// For non-URL strings, allowlist safe characters only
+const safeFamily = family.replace(/[^\p{L}\p{N} _\-'.]/gu, '');
+style.textContent = `html { font-family: "${safeFamily}"; }`;
+```
+
+**Rule of thumb**: Never interpolate untrusted strings into CSS without sanitisation. If it's a URL, use `sanitizeUrl()`. If it's any other string, strip characters that can break out of the CSS string context.
+
 ### The `useNostr` Hook
 
 The `useNostr` hook returns an object containing a `nostr` property, with `.query()` and `.event()` methods for querying and publishing Nostr events respectively.
@@ -693,6 +763,88 @@ 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, and **always pass the fetched event as `prev`** so `useNostrPublish` can preserve `published_at`:
+
+```typescript
+import { fetchFreshEvent } from '@/lib/fetchFreshEvent';
+
+// Inside a mutation function:
+const prev = await fetchFreshEvent(nostr, {
+  kinds: [10003],
+  authors: [user.pubkey],
+});
+const currentTags = prev?.tags ?? [];
+// ...modify tags...
+await publishEvent({
+  kind: 10003,
+  content: prev?.content ?? '',
+  tags: newTags,
+  prev: prev ?? undefined,
+});
+```
+
+This applies to all list-type hooks (bookmarks, pins, interests, follow sets, badges, etc.). See `useFollowActions` and `useMuteList` for complete examples.
+
+#### The `prev` Property on Event Templates
+
+`useNostrPublish` accepts an optional `prev` property on the event template. This is the **previous version** of the event being replaced. The hook uses it to automatically manage the `published_at` tag (NIP-24) for replaceable and addressable events:
+
+- **First publish (no `prev`)**: `published_at` is set equal to `created_at`
+- **Update (`prev` provided)**: `published_at` is preserved from the old event
+- **Old event lacks `published_at`**: nothing is fabricated
+- **Caller already set `published_at` in tags**: left alone
+
+**Convention**: Name the local variable `prev` at the call site (not `freshEvent` or `latestEvent`) so it reads naturally when passed to `publishEvent`:
+
+```typescript
+const prev = await fetchFreshEvent(nostr, { kinds: [3], authors: [user.pubkey] });
+// ...
+await publishEvent({ kind: 3, content: prev?.content ?? '', tags: newTags, prev: prev ?? undefined });
+```
+
+`prev` is stripped from the template before signing — it never appears in the published Nostr event.
+
+### D-Tag Collision Prevention for Addressable Events
+
+Addressable events (kind 30000-39999) are identified by `pubkey + kind + d-tag`. Publishing an event with the same d-tag as an existing one **silently replaces** it. This is by design for intentional updates (edit flows), but dangerous when creating *new* content with user-derived d-tags (slugs from titles, user-entered identifiers, etc.).
+
+#### When to Check for Collisions
+
+**Must check before publishing** when the d-tag is derived from user input (slugified titles, user-entered identifiers, etc.). **No check needed** when the d-tag is a `crypto.randomUUID()`, a canonical format with embedded pubkey prefix, or intentionally the same as an existing event (edit/update flows).
+
+#### Implementation Pattern
+
+Before publishing a **new** addressable event with a user-derived d-tag, query for an existing event with that d-tag. If one exists, block the publish and tell the user to change the identifier.
+
+```typescript
+// Before publishing a new addressable event:
+const slug = slugify(title, { lower: true, strict: true });
+
+const existing = await nostr.query([
+  { kinds: [30023], authors: [user.pubkey], '#d': [slug], limit: 1 },
+]);
+
+if (existing.length > 0) {
+  toast({
+    title: 'Slug already in use',
+    description: 'Change the slug or edit the existing item.',
+    variant: 'destructive',
+  });
+  return;
+}
+
+// Safe to publish
+publishEvent({ kind: 30023, content, tags: [['d', slug], ...otherTags] });
+```
+
+**Skip the check in edit mode** -- when the user explicitly loaded an existing event to update, overwriting is the intended behavior.
+
+Prefer UUID or canonical formats when the d-tag doesn't need to be human-readable. Only use slugified input when the d-tag will appear in URLs or needs to be meaningful to users, and always add a collision check.
+
 ### Nostr Login
 
 To enable login with Nostr, simply use the `LoginArea` component already included in this project.
@@ -954,6 +1106,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:
@@ -1241,6 +1403,10 @@ Run available tools in this priority order:
 
 The validation ensures code quality and catches errors before deployment, regardless of the development environment.
 
+### Contributing Guide
+
+When preparing changes for a merge request, also follow the guidelines in `CONTRIBUTING.md`. It includes a self-review checklist (step 8) that should be run against your diff before committing.
+
 ### Using Git
 
 If git is available in your environment (through a `shell` tool, or other git-specific tools), you should utilize `git log` to understand project history. Use `git status` and `git diff` to check the status of your changes, and if you make a mistake use `git checkout` to restore files.
@@ -1315,10 +1481,10 @@ 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)
+5. **publish** - Publishes the APK to Zapstore (`publish-zapstore` job, tags only) and AAB to Google Play (`publish-google-play` job, tags only)
 
 ### Creating a Release
 
@@ -1328,7 +1494,7 @@ Releases are triggered by pushing a version tag. Use the npm script:
 npm run release
 ```
 
-This creates a tag in the format `v2026.03.14+abc1234` (date + short commit hash) and pushes it to GitLab, which triggers the `build-apk`, `release`, and `publish-zapstore` stages.
+This creates a tag in the format `v2026.03.14+abc1234` (date + short commit hash) and pushes it to GitLab, which triggers the `build-apk`, `release`, `publish-zapstore`, and `publish-google-play` stages.
 
 ### Zapstore Publishing
 
@@ -1355,19 +1521,94 @@ 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
+
+### Google Play Publishing
+
+The project automatically publishes Android AABs (App Bundles) to [Google Play](https://play.google.com/store/apps/details?id=pub.ditto.app) using [fastlane supply](https://docs.fastlane.tools/actions/supply/). The `publish-google-play` CI job runs after a successful AAB build and uploads directly to the production track.
+
+**GitLab CI/CD Variables** (Settings > CI/CD > Variables):
+
+| Variable | Description | Protected | Masked | Raw |
+|---|---|---|---|---|
+| `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` | Full JSON contents of the Google Play API service account key file | Yes | Yes | No |
+
+#### Initial Setup (one-time)
+
+1. Create or reuse a project in the [Google Cloud Console](https://console.cloud.google.com/projectcreate)
+2. Enable the [Google Play Developer API](https://console.developers.google.com/apis/api/androidpublisher.googleapis.com/) for that project
+3. In Google Cloud Console, go to [Service Accounts](https://console.cloud.google.com/iam-admin/serviceaccounts), create a service account, and download a JSON key file for it
+4. In Google Play Console, go to [Users & Permissions](https://play.google.com/console/users-and-permissions), click **Invite new users**, enter the service account email, and grant it permission to manage releases for `pub.ditto.app`
+5. Add the full JSON contents of the key file as the `GOOGLE_PLAY_SERVICE_ACCOUNT_JSON` variable in GitLab CI/CD settings (Settings > CI/CD > Variables). Mark it as **Protected** and **Masked**.
+
+#### Key Points
+
+- The job uploads the signed AAB (not APK) since Google Play requires App Bundles
+- Uploads go directly to the **production** track -- Google's review process still applies before the update reaches users
+- Metadata, screenshots, and changelogs are managed in the Play Console, not via CI (the job uses `--skip_upload_metadata` etc.)
+- The same signing keystore used for Zapstore is used here (`ANDROID_KEYSTORE_BASE64`, `KEYSTORE_PASSWORD`, `KEY_PASSWORD`)

CHANGELOG.md

@@ -1,5 +1,340 @@
 # Changelog
 
+## [2.6.6] - 2026-04-12
+
+### Fixed
+- Emoji and mention autocomplete dropdowns no longer get clipped by the compose box
+- Emoji shortcodes now render as color emoji instead of plain text glyphs
+- Dialogs and input fields on Android are no longer obscured by the virtual keyboard
+- Signing requests on Android are more reliable and no longer silently fail after switching apps
+
+## [2.6.5] - 2026-04-11
+
+### Changed
+- Apps and games load significantly faster on Android with smarter prefetching and server affinity
+- Native loading spinners replace HTML-based ones on iOS and Android for a smoother experience
+
+### Fixed
+- External API requests on Android no longer fail due to hostname restrictions
+- iOS App Store compliance issues resolved
+
+## [2.6.4] - 2026-04-11
+
+### Added
+- iCloud Keychain integration on iOS -- your login credentials are now saved and restored automatically across devices
+
+### Changed
+- Empty feeds show a friendlier state with a discover button to help you find people to follow
+- Signup flow simplified -- cleaner profile step with a single Continue button
+
+### Fixed
+- Avatar fallback now shows the user's initial instead of a question mark
+- Android 16+ devices no longer have content hidden behind system bars
+- Signup dialog background clears properly when switching between light and dark themes
+- Sticky compose button stays anchored to the bottom even on empty feeds
+
+## [2.6.3] - 2026-04-10
+
+### Added
+- Lightning invoices embedded in posts now render as tappable payment cards
+- Blobbi companions in the feed reflect their current condition and projected health
+
+### Changed
+- Profile headers are cleaner -- lightning addresses and verification badges moved out of the way, and website URLs no longer show a trailing slash
+- Login credentials are saved to your browser's built-in password manager for easier sign-in across sessions
+- "Request to Vanish" renamed to "Delete Account" for clarity
+
+### Fixed
+- Badge image uploads now show a recommended 1:1 aspect ratio hint so your badges don't get cropped unexpectedly
+- Security hardening for URLs and styles sourced from the network
+
+## [2.6.2] - 2026-04-08
+
+### Added
+- Share follow packs and follow sets via link -- recipients see an immersive preview with member avatars, a "Follow All" button, and a combined feed from everyone in the pack
+- Curated home feed with a mix of photos, short videos, livestreams, and music -- content types are spaced out so your timeline stays fresh and varied
+- "Write a letter" option on profile menus for a more personal way to reach out
+- Push vs persistent notification delivery option on Android
+
+### Changed
+- Webxdc games and apps always open fullscreen for a more immersive experience
+- Login credentials are now stored in the device's secure keychain on iOS and Android instead of plain local storage
+- Profile fields now appear inline instead of in a separate right sidebar
+- Trending hashtags removed from the logged-out homepage for a cleaner first impression
+
+### Fixed
+- Webxdc and nsites work natively on iOS and Android without relying on browser sandboxing tricks
+- File downloads now save directly to Documents on iOS and Android instead of silently failing
+- Mobile search no longer scrolls the page behind it and properly hides the bottom navigation bar
+- iOS swipe-back navigation works correctly throughout the app
+- Blobbi companions appear reliably on profiles instead of sometimes going missing
+- IndexedDB no longer crashes on devices with Lockdown Mode enabled
+
+## [2.6.1] - 2026-04-06
+
+### Added
+- Manage your interest tabs (hashtags and locations) from the settings page
+- Edit button on custom profile tabs so you can tweak them without recreating from scratch
+- Follow packs and follow sets now show author info and action headers in the feed
+- Posts now show whether they were created or updated, so you can tell when something's been edited
+
+### Changed
+- Webxdc games and apps run in a more secure sandbox with stricter content policies and private subdomains
+- Nsite previews now use the same secure sandbox as webxdc apps
+- Blobbi items work as instant abilities instead of consumable inventory -- no more fiddly quantity pickers
+
+### Fixed
+- Desktop tab bar no longer overflows when you have lots of tabs -- scroll arrows appear automatically
+- Mobile compose box no longer randomly collapses or becomes unclickable
+- Profile avatar and banner lightbox no longer hides behind the right sidebar
+- Infinite scroll on custom profile tab feeds no longer reloads the same content
+- Reaction emoji are now visible on each row in the interactions modal
+- Missing bottom border on collapsed thread expand button restored
+
+## [2.6.0] - 2026-04-05
+
+### Added
+- Follow links and QR codes -- share a link or scannable code that lets anyone follow you with one tap, complete with your themed profile preview and recent posts
+- Immersive Blobbi hatching ceremony -- crack your egg through cinematic stages with shaking animations, a burst of light, sparkles, typewriter dialog, and a naming moment
+
+### Changed
+- Footer links redesigned as compact icon chips for a cleaner look
+- Custom emoji now render crisp at small sizes with pixel-perfect scaling
+
+### Fixed
+- Custom themes now apply correctly when logging in on a new device
+- Settings and preferences sync reliably across devices
+- Mobile sidebar links no longer clip into the safe area
+- Blobbi page background overlay now appears properly on custom themes
+- Blobbi companion state no longer resets unexpectedly from stale cache data
+- Letter compose picker no longer gets hidden behind the top navigation arc
+
+## [2.5.2] - 2026-04-04
+
+### Added
+- See who voted on each poll option -- tap the vote count to open a voters list with avatar stacks and per-option filter tabs
+- Poll votes now appear as activity cards in feeds and on detail pages
+
+### Fixed
+- Threads and replies load more reliably by following relay and author hints when fetching parent events
+
+## [2.5.1] - 2026-04-03
+
+### Fixed
+- Lightbox now reliably appears above all content, not just when opened from photo galleries
+
+## [2.5.0] - 2026-04-03
+
+### Added
+- Run nsites and web apps directly inside Ditto -- hit the "Run" button on any nsite or app card to preview it in an overlay without leaving your feed
+- File uploads in the poll composer -- attach images and media to your polls
+- Blobbi posts now appear in the homepage feed
+
+### Changed
+- Profile media sidebar fills remaining slots with photos from text posts when there aren't enough dedicated media posts
+- App cards now show banner images and improved layout
+
+### Fixed
+- Lightbox no longer appears behind the right sidebar
+- Compose box corners are properly rounded
+- Clicking buttons or links inside a post card no longer accidentally navigates to the post detail page
+
+## [2.4.1] - 2026-04-02
+
+### Added
+- Rich cards for Zapstore app releases and assets -- see download links, version info, platform badges, and hashes right in your feed
+
+### Fixed
+- First-hatch tour now shows for accounts that were onboarded before the tour existed, so no one misses the hatching moment
+
+## [2.4.0] - 2026-04-02
+
+### Added
+- First-hatch tour: a guided experience for hatching your very first Blobbi egg, with progressive crack animations, an inline card flow, and a reveal moment
+- Customizable bottom bar: rearrange or hide any item in the navigation bar to make Ditto feel like yours
+- Mission surface card in the feed that surfaces your active quests at a glance
+
+### Changed
+- Missions redesigned as a quest board with collapsible cards and a lighter aesthetic
+- "Edit Profile" mission now completes when you update any profile field, not just wall-specific edits
+- Media tab on profiles now shows only photos, videos, and other media -- not plain text posts
+- Blobbi onboarding state now syncs to your profile so it follows you across devices
+
+### Fixed
+- Notification dot no longer reappears after you've already marked notifications as read
+- Dialogs no longer fly up when the mobile keyboard opens
+
+## [2.3.1] - 2026-04-02
+
+### Changed
+- Drafts now save instantly to your device and sync to relays in the background, with a cloud sync indicator so you always know the status
+
+### Fixed
+- Dialogs stay visible above the keyboard on mobile instead of getting hidden behind it
+- Editing an existing article no longer incorrectly warns about a duplicate slug
+- Switching between rich text and markdown source mode no longer clears your content
+- Fix crash when editing in markdown source mode
+
+## [2.3.0] - 2026-04-02
+
+### Added
+- In-app article editor with a rich text toolbar, image uploads, auto-saving drafts, and a "My Articles" tab to manage drafts and published articles
+
+### Fixed
+- Custom emoji no longer stretch to fill their container
+- Mobile drawer now closes when tapping footer links like Changelog or Privacy
+- Logged-out users now default to the global tab on content feeds instead of seeing an empty follows tab
+
+## [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 now display in feeds and detail pages with hero images, icons, 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 login flows with Amber, Primal, and other signing apps
+
+### 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
+- 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 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
+- Event links now route correctly for all event types
+- 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
+- New posts no longer cause scroll jumps -- they buffer while you're reading and appear with a tap
+- Mobile header no longer shows double-layered backgrounds on notched devices
+- Pinned tabs stay properly positioned when scrolling on mobile
+- Signer approval toasts no longer fire in rapid succession on unstable connections
+- Toasts are easier to swipe away on mobile
+- Content warnings now blur thumbnails in the media grid
+
 ## [2.2.0] - 2026-03-28
 
 ### Added
@@ -7,11 +342,11 @@
 - 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
-- NIP-11 relay information panel on the network settings page
+- Immersive full-screen divines experience on both mobile and desktop with floating controls
+- 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
-- Remote signer UX improvements for Amber and NIP-46 users on Android
+- Remote signer UX improvements for Amber users on Android
 - Badge awards now trigger push notifications
 - Badges display in profile bio section with a "Give badge" option in the profile menu
 

CONTRIBUTING.md

@@ -0,0 +1,184 @@
+# Contributing to Ditto
+
+We welcome contributions, but we have high standards. Ditto is a carefully designed product with a specific vision, and every merge request must meet that bar. This guide exists to help you succeed.
+
+**Required reading before you start:**
+
+- [Ditto Philosophy](https://about.ditto.pub/philosophy) -- the product vision. Your change must align with it.
+- [Contributing Guide](https://about.ditto.pub/contributing) -- the upstream contribution process.
+- `AGENTS.md` in this repo -- the codebase conventions. Your AI tool should load this file.
+
+## Understanding Ditto
+
+Ditto is a carnival, not a platform. Before contributing, you need to understand what that means.
+
+### The product decision filter
+
+Every change to Ditto should pass this test:
+
+> *Does this make Ditto more magnetic, more threatening to the status quo, and more peaceful to inhabit?*
+
+- **Magnetic** -- Ditto attracts through experience, not ideology. People don't need to understand Nostr to love it. They need to feel something they haven't felt online since the early web. Features should be odd, intriguing, and captivating -- not generic social media clones.
+- **Threatening to the status quo** -- Ditto threatens mainstream platforms when someone opens it and thinks: *"Why can't my platform do this?"* Theming, games, treasure hunts, interoperable micro-apps -- these are things walled gardens can't replicate.
+- **Peaceful to inhabit** -- Ditto displaces argument with creation, conformity with expression, and consumption with participation. No ads, no engagement-optimized algorithms, no outrage incentives.
+
+If a change does all three, it belongs. If it only does one, think harder. If it does none, it doesn't belong here.
+
+### What Ditto is NOT
+
+- A Twitter/X clone with decentralization bolted on
+- A place to replicate features that mainstream platforms already do well
+- A showcase for generic UI components or boilerplate social features
+
+### What Ditto IS
+
+- A convergence point for interoperable Nostr experiences (games, treasure hunts, magic decks, themes, color moments, live streams, and things nobody has imagined yet)
+- A place where profiles feel like worlds, not business cards
+- The most fun you've had on the internet in years
+
+Read the [full philosophy](https://about.ditto.pub/philosophy) for the complete vision.
+
+## What we accept
+
+### Bug fixes
+
+One bug, one merge request. Fix exactly one thing. Don't bundle unrelated changes, don't sneak in refactors, don't "clean up while you're in there." Small, focused MRs get reviewed fast. Large ones sit.
+
+### New features and significant changes
+
+Every feature MR must link to an existing open issue and clearly align with the [Ditto Philosophy](https://about.ditto.pub/philosophy). The philosophy alignment section in the MR template is where you make the case for why your change belongs in Ditto. If you can't articulate that clearly, the change probably doesn't belong.
+
+If you have an idea for a feature that doesn't have an issue yet:
+
+1. Build it as a standalone Nostr app first (see [Contributing Guide](https://about.ditto.pub/contributing)).
+2. Prove it works and get user feedback.
+3. Open an issue to discuss integration.
+
+**Feature MRs that don't link to an issue or don't align with the Ditto Philosophy will be closed.** Our open issues are our internal roadmap -- some require deep product context. If your implementation doesn't match the product vision, it will be closed regardless of code quality.
+
+## Required tools
+
+- **Claude Opus 4.6** (or the latest frontier model) -- not Sonnet, not GPT-4o, not local models. Quality depends on model quality.
+- **An AI coding agent with plan/research mode** -- [OpenCode](https://opencode.ai), [Shakespeare](https://shakespeare.diy), Cursor, or similar.
+- **Node.js 22+** and npm 10.9.4+.
+
+## The contribution workflow
+
+Follow these steps in order. Skipping steps is the most common reason MRs are rejected.
+
+### 1. Ask: does anyone need this?
+
+Before writing a single line of code, answer this honestly. For bug fixes this is straightforward -- someone hit the bug. For features, it requires more thought. Is there evidence of real user demand? Is the underlying technology mature enough? A beautifully written feature for a nonexistent user base is the wrong thing to build. If you can't point to a concrete user need, reconsider.
+
+### 2. Understand the issue
+
+Read the issue thoroughly. If anything is unclear, ask in the issue comments before writing code. Understand not just *what* to change, but *why* -- what problem does this solve for users?
+
+### 3. Read the codebase conventions
+
+Read `AGENTS.md` in the repo root. This is the single source of truth for how code should be written in this project. Your AI tool should load this file automatically. If it doesn't, paste it in or configure your tool to read it.
+
+### 4. Read the philosophy
+
+Read the [Ditto Philosophy](https://about.ditto.pub/philosophy). Ditto is a carnival, not a platform. Your change should feel like it belongs in Ditto -- not like it was transplanted from a generic social media template. Apply the product decision filter above.
+
+### 5. Plan before you code
+
+Start your AI tool in **plan mode** (or research/think mode). Spend the first few prompts:
+
+- Exploring the existing codebase to understand how similar features are implemented
+- Reading the files you'll need to modify
+- Proposing an approach
+
+Do not write code until you have a plan. The most expensive mistake is implementing the wrong approach.
+
+### 6. Implement
+
+Switch to code mode and implement your plan. Use Opus 4.6 or equivalent.
+
+### 7. Run the test suite
+
+```sh
+npm run test
+```
+
+This runs type-checking, linting, unit tests, and a production build. All must pass. Do not submit an MR with a failing test suite.
+
+### 8. Self-review
+
+Run this prompt against your diff (copy the full `git diff` output and paste it to your AI tool along with this prompt):
+
+```
+Review this diff as if you are a senior maintainer of this codebase who has to
+maintain it long-term. For each finding, state the file, line, and issue.
+
+- [ ] Does the diff contain changes that weren't requested? Flag anything out of scope.
+- [ ] Is there dead code, commented-out blocks, or debug artifacts left in?
+- [ ] Are there placeholder comments like "// In a real app..." or "// TODO: implement"?
+- [ ] For every value displayed to a user, can you trace it from source to render without a gap?
+- [ ] Are error, loading, and empty states all handled -- and in the right order?
+- [ ] Does a mutation reflect in the UI without requiring a manual refresh?
+- [ ] Is there a new read/write path that assumes fresh data but could get a stale cache?
+- [ ] For replaceable/addressable Nostr events: is fetchFreshEvent used before mutation?
+- [ ] Does anything new block the critical render path or fire N+1 network requests?
+- [ ] Are Nostr queries efficient (combined kinds, relay-level filtering vs client-side)?
+- [ ] Are user inputs used in queries or rendered as content without sanitization?
+- [ ] Were existing patterns/conventions in AGENTS.md ignored in favor of something novel?
+- [ ] Are secrets, keys, or env-specific values hardcoded?
+- [ ] Does the code use the `any` type anywhere?
+- [ ] Is the code Capacitor-compatible (no `<a download>`, no `window.open()`)?
+- [ ] Are new Nostr event kinds documented in NIP.md with links to relevant specs?
+- [ ] Are there any new images >100KB or other large binary assets that should be hosted externally?
+- [ ] Is there any use of dangerouslySetInnerHTML, eval, innerHTML, or SVG string interpolation?
+- [ ] Is any data from a Nostr event (tags, content, pubkey, URLs) used in a security-sensitive context (href, src, query filter, trust decision) without validation?
+
+Skip anything a linter or type checker would catch. Focus on logic, data flow, and intent.
+
+Then answer: "If you were the people who have to maintain this codebase and deal
+with all long-term issues, what would be your biggest concerns about this
+implementation?"
+```
+
+Address every finding before submitting.
+
+### 9. Deploy a live preview
+
+Deploy your branch so reviewers can test it without pulling your code:
+
+```sh
+npm run build
+npx surge dist your-branch-name.surge.sh
+```
+
+Or use Netlify, Vercel, or any static hosting. Include the live preview URL in your MR description.
+
+### 10. Take screenshots
+
+Capture before and after screenshots of any UI changes. Include them directly in the MR description. If your change has no visual component, state that explicitly.
+
+### 11. Submit
+
+Fill out every field in the MR template. Incomplete MRs will not be reviewed.
+
+## What gets your MR closed without review
+
+- No linked issue
+- Feature MRs with no clear alignment with the [Ditto Philosophy](https://about.ditto.pub/philosophy)
+- Features that fail the product decision filter (not magnetic, not threatening to the status quo, not peaceful)
+- Incomplete MR template (missing checklist, screenshots, or preview URL)
+- Changes that go beyond what was asked for (scope creep)
+- Placeholder code, dead code, or debug artifacts
+- Evidence of low-quality AI generation ("In a real application..." comments, hallucinated APIs, generic template code)
+- Failing test suite
+- No evidence of planning (code-first, think-later approach produces recognizable patterns)
+- Undocumented Nostr event kinds (new kinds must be in NIP.md)
+- Large binary assets committed to git (images >100KB, fonts, videos)
+- Security issues (dangerouslySetInnerHTML, eval, innerHTML, unsanitized user input)
+
+## MR review process
+
+1. The CI pipeline validates your MR description automatically. If it fails, read the error message and fix your MR description.
+2. Maintainers will review your MR when all CI checks pass and the template is complete.
+3. If changes are requested, address them promptly. Stale MRs will be closed.
+
+We appreciate your interest in contributing. These standards exist because reviewing a low-quality MR takes 3x longer than doing the work ourselves. Help us help you by following the process.

NIP.md

@@ -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.
+

README.md

@@ -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)
@@ -138,6 +138,17 @@ src/
 public/           Static assets, icons, manifest
 ```
 
+## Contributing
+
+We welcome contributions but have high standards. Please read the full [Contributing Guide](CONTRIBUTING.md) before submitting a merge request. The short version:
+
+- **Bug fixes**: One bug, one MR. Keep it small and focused.
+- **New features**: Must link to an existing issue and align with the [Ditto Philosophy](https://about.ditto.pub/philosophy).
+- **Required**: Live preview URL, before/after screenshots, completed self-review checklist.
+- **Required tools**: Claude Opus 4.6 (or latest frontier model), an AI coding agent with plan mode.
+
+Read the [Ditto Philosophy](https://about.ditto.pub/philosophy) to understand what Ditto is and isn't.
+
 ## License
 
 [AGPL-3.0](LICENSE)

android/app/build.gradle

@@ -14,7 +14,7 @@ android {
         minSdkVersion rootProject.ext.minSdkVersion
         targetSdkVersion rootProject.ext.targetSdkVersion
         versionCode 1
-        versionName "2.2.0"
+        versionName "2.6.6"
         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'
         }
     }
 }

android/app/capacitor.build.gradle

@@ -11,9 +11,11 @@ apply from: "../capacitor-cordova-android-plugins/cordova.variables.gradle"
 dependencies {
     implementation project(':capacitor-app')
     implementation project(':capacitor-filesystem')
+    implementation project(':capacitor-keyboard')
     implementation project(':capacitor-local-notifications')
     implementation project(':capacitor-share')
-    implementation project(':capacitor-status-bar')
+    implementation project(':capgo-capacitor-autofill-save-password')
+    implementation project(':capacitor-secure-storage-plugin')
 
 }
 

android/app/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.

android/app/src/main/java/pub/ditto/app/DittoNotificationPlugin.java

@@ -1,7 +1,10 @@
 package pub.ditto.app;
 
-import android.content.SharedPreferences;
+import android.app.ForegroundServiceStartNotAllowedException;
 import android.content.Context;
+import android.content.Intent;
+import android.content.SharedPreferences;
+import android.os.Build;
 import android.util.Log;
 
 import com.getcapacitor.Plugin;
@@ -14,6 +17,10 @@ import org.json.JSONArray;
 /**
  * Capacitor plugin that allows the JS layer to configure the native
  * notification polling service with the user's pubkey and relay URLs.
+ *
+ * Supports two notification styles:
+ * - "push" (default): no foreground service, relies on push notifications
+ * - "persistent": starts NotificationRelayService as a foreground service
  */
 @CapacitorPlugin(name = "DittoNotification")
 public class DittoNotificationPlugin extends Plugin {
@@ -24,6 +31,7 @@ public class DittoNotificationPlugin extends Plugin {
     @PluginMethod
     public void configure(PluginCall call) {
         String userPubkey = call.getString("userPubkey");
+        String notificationStyle = call.getString("notificationStyle", "push");
         String relayUrlsRaw = null;
         String enabledKindsRaw = null;
         String authorsRaw = null;
@@ -60,7 +68,8 @@ public class DittoNotificationPlugin extends Plugin {
         if (userPubkey != null && relayUrlsRaw != null) {
             SharedPreferences.Editor editor = prefs.edit()
                     .putString("userPubkey", userPubkey)
-                    .putString("relayUrls", relayUrlsRaw);
+                    .putString("relayUrls", relayUrlsRaw)
+                    .putString("notificationStyle", notificationStyle);
             if (enabledKindsRaw != null) {
                 editor.putString("enabledKinds", enabledKindsRaw);
             }
@@ -70,13 +79,46 @@ public class DittoNotificationPlugin extends Plugin {
                 editor.remove("authors");
             }
             editor.apply();
-            Log.d(TAG, "Configured: pubkey=" + userPubkey.substring(0, 8) + "..., relays=" + relayUrlsRaw + ", kinds=" + enabledKindsRaw + ", authors=" + (authorsRaw != null ? authorsRaw.length() + " chars" : "all"));
+            Log.d(TAG, "Configured: pubkey=" + userPubkey.substring(0, 8) + "..., style=" + notificationStyle + ", relays=" + relayUrlsRaw + ", kinds=" + enabledKindsRaw + ", authors=" + (authorsRaw != null ? authorsRaw.length() + " chars" : "all"));
         } else {
             // Clear config (user logged out)
             prefs.edit().clear().apply();
             Log.d(TAG, "Config cleared (user logged out)");
         }
 
+        // Start or stop the foreground service based on style
+        manageService(notificationStyle, userPubkey != null && relayUrlsRaw != null);
+
         call.resolve();
     }
+
+    /**
+     * Start the foreground service when style is "persistent" and config is valid.
+     * Stop it otherwise.
+     */
+    private void manageService(String style, boolean hasConfig) {
+        Context ctx = getContext();
+        Intent serviceIntent = new Intent(ctx, NotificationRelayService.class);
+
+        if ("persistent".equals(style) && hasConfig) {
+            try {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                    ctx.startForegroundService(serviceIntent);
+                } else {
+                    ctx.startService(serviceIntent);
+                }
+                Log.d(TAG, "Started NotificationRelayService (persistent mode)");
+            } catch (Exception e) {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
+                        && e instanceof ForegroundServiceStartNotAllowedException) {
+                    Log.w(TAG, "Could not start foreground service: " + e.getMessage());
+                } else {
+                    Log.w(TAG, "Failed to start service", e);
+                }
+            }
+        } else {
+            ctx.stopService(serviceIntent);
+            Log.d(TAG, "Stopped NotificationRelayService (push mode or no config)");
+        }
+    }
 }

android/app/src/main/java/pub/ditto/app/MainActivity.java

@@ -1,7 +1,9 @@
 package pub.ditto.app;
 
 import android.app.ForegroundServiceStartNotAllowedException;
+import android.content.Context;
 import android.content.Intent;
+import android.content.SharedPreferences;
 import android.net.Uri;
 import android.os.Build;
 import android.os.Bundle;
@@ -11,32 +13,36 @@ import com.getcapacitor.BridgeActivity;
 
 public class MainActivity extends BridgeActivity {
 
+    private static final String PREFS_NAME = "ditto_notification_config";
+
     @Override
     protected void onCreate(Bundle savedInstanceState) {
-        // Register the native notification config plugin before super.onCreate
+        // Register native plugins before super.onCreate.
         registerPlugin(DittoNotificationPlugin.class);
+        registerPlugin(SandboxPlugin.class);
 
         super.onCreate(savedInstanceState);
 
-        // Start the persistent relay connection service.
-        // On Android 12+ (API 31+) the system may throw
-        // ForegroundServiceStartNotAllowedException if the foreground service
-        // time limit for this type has already been exhausted. We catch it so
-        // the app continues to run normally; the alarm inside the service will
-        // retry at the next scheduled interval.
-        try {
-            Intent serviceIntent = new Intent(this, NotificationRelayService.class);
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-                startForegroundService(serviceIntent);
-            } else {
-                startService(serviceIntent);
-            }
-        } catch (Exception e) {
-            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
-                    && e instanceof ForegroundServiceStartNotAllowedException) {
-                Log.w("MainActivity", "Could not start NotificationRelayService: " + e.getMessage());
-            } else {
-                throw e;
+        // Only start the foreground service if the user has opted into
+        // "persistent" notification style. Default is "push" (no service).
+        SharedPreferences prefs = getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        String style = prefs.getString("notificationStyle", "push");
+
+        if ("persistent".equals(style)) {
+            try {
+                Intent serviceIntent = new Intent(this, NotificationRelayService.class);
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+                    startForegroundService(serviceIntent);
+                } else {
+                    startService(serviceIntent);
+                }
+            } catch (Exception e) {
+                if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S
+                        && e instanceof ForegroundServiceStartNotAllowedException) {
+                    Log.w("MainActivity", "Could not start NotificationRelayService: " + e.getMessage());
+                } else {
+                    throw e;
+                }
             }
         }
 

android/app/src/main/java/pub/ditto/app/SandboxPlugin.java

@@ -0,0 +1,552 @@
+package pub.ditto.app;
+
+import android.graphics.Color;
+import android.graphics.PorterDuff;
+import android.os.Handler;
+import android.os.Looper;
+import android.util.Base64;
+import android.util.Log;
+import android.view.Gravity;
+import android.view.View;
+import android.view.ViewGroup;
+import android.webkit.JavascriptInterface;
+import android.webkit.WebResourceRequest;
+import android.webkit.WebResourceResponse;
+import android.webkit.WebSettings;
+import android.webkit.WebView;
+import android.webkit.WebViewClient;
+import android.widget.FrameLayout;
+import android.widget.ProgressBar;
+import androidx.coordinatorlayout.widget.CoordinatorLayout;
+
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Plugin;
+import com.getcapacitor.PluginCall;
+import com.getcapacitor.PluginMethod;
+import com.getcapacitor.annotation.CapacitorPlugin;
+
+import org.json.JSONException;
+import org.json.JSONObject;
+
+import java.io.ByteArrayInputStream;
+import java.io.InputStream;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.UUID;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.CountDownLatch;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Capacitor plugin that creates isolated Android WebViews for sandboxed content.
+ *
+ * Each sandbox uses shouldInterceptRequest to intercept all requests and forward
+ * them to the JS layer as fetch events — the same protocol iframe.diy uses.
+ * The React code can serve files identically regardless of platform.
+ */
+@CapacitorPlugin(name = "SandboxPlugin")
+public class SandboxPlugin extends Plugin {
+
+    private static final String TAG = "SandboxPlugin";
+    private final Map<String, SandboxInstance> sandboxes = new HashMap<>();
+    private final Handler mainHandler = new Handler(Looper.getMainLooper());
+
+    @PluginMethod
+    public void create(PluginCall call) {
+        String sandboxId = call.getString("id");
+        if (sandboxId == null) {
+            call.reject("Missing required parameter: id");
+            return;
+        }
+
+        JSObject frame = call.getObject("frame");
+        if (frame == null) {
+            call.reject("Missing required parameter: frame");
+            return;
+        }
+
+        int x = frame.optInt("x", 0);
+        int y = frame.optInt("y", 0);
+        int width = frame.optInt("width", 0);
+        int height = frame.optInt("height", 0);
+
+        if (sandboxes.containsKey(sandboxId)) {
+            call.reject("Sandbox already exists: " + sandboxId);
+            return;
+        }
+
+        float density = getActivity().getResources().getDisplayMetrics().density;
+        int pxX = Math.round(x * density);
+        int pxY = Math.round(y * density);
+        int pxWidth = Math.round(width * density);
+        int pxHeight = Math.round(height * density);
+
+        mainHandler.post(() -> {
+            SandboxInstance sandbox = new SandboxInstance(sandboxId, this);
+            sandboxes.put(sandboxId, sandbox);
+
+            // Add the container (WebView + spinner overlay) on top of the
+            // Capacitor WebView. The parent is a CoordinatorLayout — using
+            // the wrong LayoutParams type causes a ClassCastException when
+            // it intercepts touch events.
+            View capWebView = getBridge().getWebView();
+            ViewGroup parent = (ViewGroup) capWebView.getParent();
+            CoordinatorLayout.LayoutParams params = new CoordinatorLayout.LayoutParams(pxWidth, pxHeight);
+            params.leftMargin = pxX;
+            params.topMargin = pxY;
+            parent.addView(sandbox.container, params);
+
+            // The spinner is now visible. Navigation is deferred until the
+            // JS layer calls navigate() — this allows the caller to
+            // pre-fetch blobs while the spinner animates.
+
+            call.resolve();
+        });
+    }
+
+    @PluginMethod
+    public void navigate(PluginCall call) {
+        String sandboxId = call.getString("id");
+        if (sandboxId == null) {
+            call.reject("Missing required parameter: id");
+            return;
+        }
+
+        mainHandler.post(() -> {
+            SandboxInstance sandbox = sandboxes.get(sandboxId);
+            if (sandbox == null) {
+                call.reject("Sandbox not found: " + sandboxId);
+                return;
+            }
+
+            sandbox.webView.loadUrl("https://" + sandboxId + ".sandbox.native/index.html");
+            call.resolve();
+        });
+    }
+
+    @PluginMethod
+    public void updateFrame(PluginCall call) {
+        String sandboxId = call.getString("id");
+        if (sandboxId == null) {
+            call.reject("Missing required parameter: id");
+            return;
+        }
+
+        JSObject frame = call.getObject("frame");
+        if (frame == null) {
+            call.reject("Missing required parameter: frame");
+            return;
+        }
+
+        int x = frame.optInt("x", 0);
+        int y = frame.optInt("y", 0);
+        int width = frame.optInt("width", 0);
+        int height = frame.optInt("height", 0);
+
+        float density = getActivity().getResources().getDisplayMetrics().density;
+        int pxX = Math.round(x * density);
+        int pxY = Math.round(y * density);
+        int pxWidth = Math.round(width * density);
+        int pxHeight = Math.round(height * density);
+
+        mainHandler.post(() -> {
+            SandboxInstance sandbox = sandboxes.get(sandboxId);
+            if (sandbox == null) {
+                call.reject("Sandbox not found: " + sandboxId);
+                return;
+            }
+
+            CoordinatorLayout.LayoutParams params = new CoordinatorLayout.LayoutParams(pxWidth, pxHeight);
+            params.leftMargin = pxX;
+            params.topMargin = pxY;
+            sandbox.container.setLayoutParams(params);
+
+            call.resolve();
+        });
+    }
+
+    @PluginMethod
+    public void respondToFetch(PluginCall call) {
+        String sandboxId = call.getString("id");
+        if (sandboxId == null) {
+            call.reject("Missing required parameter: id");
+            return;
+        }
+        String requestId = call.getString("requestId");
+        if (requestId == null) {
+            call.reject("Missing required parameter: requestId");
+            return;
+        }
+        JSObject response = call.getObject("response");
+        if (response == null) {
+            call.reject("Missing required parameter: response");
+            return;
+        }
+
+        SandboxInstance sandbox = sandboxes.get(sandboxId);
+        if (sandbox == null) {
+            call.reject("Sandbox not found: " + sandboxId);
+            return;
+        }
+
+        int status = response.optInt("status", 200);
+        String statusText = response.optString("statusText", "OK");
+        String bodyBase64 = response.optString("body", null);
+
+        Map<String, String> headers = new HashMap<>();
+        JSONObject headersObj = response.optJSONObject("headers");
+        if (headersObj != null) {
+            for (java.util.Iterator<String> it = headersObj.keys(); it.hasNext(); ) {
+                String key = it.next();
+                headers.put(key, headersObj.optString(key));
+            }
+        }
+
+        sandbox.resolveRequest(requestId, status, statusText, headers, bodyBase64);
+
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void postMessage(PluginCall call) {
+        String sandboxId = call.getString("id");
+        if (sandboxId == null) {
+            call.reject("Missing required parameter: id");
+            return;
+        }
+        JSObject message = call.getObject("message");
+        if (message == null) {
+            call.reject("Missing required parameter: message");
+            return;
+        }
+
+        SandboxInstance sandbox = sandboxes.get(sandboxId);
+        if (sandbox == null) {
+            call.reject("Sandbox not found: " + sandboxId);
+            return;
+        }
+
+        mainHandler.post(() -> sandbox.postMessageToWebView(message.toString()));
+
+        call.resolve();
+    }
+
+    @PluginMethod
+    public void destroy(PluginCall call) {
+        String sandboxId = call.getString("id");
+        if (sandboxId == null) {
+            call.reject("Missing required parameter: id");
+            return;
+        }
+
+        mainHandler.post(() -> {
+            SandboxInstance sandbox = sandboxes.remove(sandboxId);
+            if (sandbox != null) {
+                ViewGroup parent = (ViewGroup) sandbox.container.getParent();
+                if (parent != null) {
+                    parent.removeView(sandbox.container);
+                }
+                sandbox.webView.destroy();
+            }
+            call.resolve();
+        });
+    }
+
+    void emitFetchRequest(String sandboxId, String requestId, JSObject request) {
+        JSObject data = new JSObject();
+        data.put("id", sandboxId);
+        data.put("requestId", requestId);
+        data.put("request", request);
+        notifyListeners("fetch", data);
+    }
+
+    void emitScriptMessage(String sandboxId, JSObject message) {
+        JSObject data = new JSObject();
+        data.put("id", sandboxId);
+        data.put("message", message);
+        notifyListeners("scriptMessage", data);
+    }
+
+    /**
+     * A single sandboxed WebView instance.
+     */
+    private static class SandboxInstance {
+        final String id;
+        /** Wrapper layout that holds the WebView and the loading overlay. */
+        final FrameLayout container;
+        final WebView webView;
+        final SandboxPlugin plugin;
+        private final ConcurrentHashMap<String, PendingRequest> pendingRequests = new ConcurrentHashMap<>();
+        /** Native spinner overlay, shown while the sandbox content loads. */
+        private ProgressBar spinner;
+
+        SandboxInstance(String id, SandboxPlugin plugin) {
+            this.id = id;
+            this.plugin = plugin;
+
+            this.container = new FrameLayout(plugin.getActivity());
+            this.webView = new WebView(plugin.getActivity());
+
+            WebSettings settings = webView.getSettings();
+            settings.setJavaScriptEnabled(true);
+            settings.setDomStorageEnabled(true);
+            settings.setAllowFileAccess(false);
+            settings.setAllowContentAccess(false);
+            settings.setDatabaseEnabled(true);
+
+            webView.setBackgroundColor(Color.parseColor("#14161f"));
+
+            // Add JavaScript interface for script->native communication.
+            webView.addJavascriptInterface(new SandboxBridge(this), "__sandboxNative");
+
+            // Inject the bridge script and intercept requests.
+            webView.setWebViewClient(new SandboxWebViewClient(this));
+
+            // Build the container: WebView fills it, spinner overlays on top.
+            container.addView(webView, new FrameLayout.LayoutParams(
+                    ViewGroup.LayoutParams.MATCH_PARENT,
+                    ViewGroup.LayoutParams.MATCH_PARENT));
+
+            // Native spinner overlay — uses the Android indeterminate
+            // ProgressBar which animates on the render thread, so it keeps
+            // spinning even when the main/IO threads are busy.
+            spinner = new ProgressBar(plugin.getActivity());
+            spinner.setIndeterminate(true);
+            spinner.getIndeterminateDrawable().setColorFilter(
+                    Color.parseColor("#7c5cdc"), PorterDuff.Mode.SRC_IN);
+            FrameLayout.LayoutParams spinnerParams = new FrameLayout.LayoutParams(
+                    dpToPx(plugin, 32), dpToPx(plugin, 32), Gravity.CENTER);
+            container.addView(spinner, spinnerParams);
+
+            // Dark background behind the spinner.
+            View overlay = new View(plugin.getActivity());
+            overlay.setBackgroundColor(Color.parseColor("#14161f"));
+            // Insert the overlay between the WebView (index 0) and spinner (index 1)
+            // so it covers the WebView but sits behind the spinner.
+            container.addView(overlay, 1, new FrameLayout.LayoutParams(
+                    ViewGroup.LayoutParams.MATCH_PARENT,
+                    ViewGroup.LayoutParams.MATCH_PARENT));
+        }
+
+        /** Remove the native loading overlay. Safe to call multiple times. */
+        void hideSpinner() {
+            if (spinner != null) {
+                // Remove spinner and overlay (indices 2 and 1 after WebView at 0).
+                if (container.getChildCount() > 2) container.removeViewAt(2); // spinner
+                if (container.getChildCount() > 1) container.removeViewAt(1); // overlay
+                spinner = null;
+            }
+        }
+
+        private static int dpToPx(SandboxPlugin plugin, int dp) {
+            float density = plugin.getActivity().getResources().getDisplayMetrics().density;
+            return Math.round(dp * density);
+        }
+
+        void postMessageToWebView(String jsonString) {
+            String js = "(function() { " +
+                    "if (window.__sandboxBridge && window.__sandboxBridge.onMessage) { " +
+                    "window.__sandboxBridge.onMessage(" + jsonString + "); " +
+                    "} " +
+                    "})();";
+            webView.evaluateJavascript(js, null);
+        }
+
+        void resolveRequest(String requestId, int status, String statusText,
+                            Map<String, String> headers, String bodyBase64) {
+            PendingRequest pending = pendingRequests.remove(requestId);
+            if (pending == null) return;
+
+            byte[] bodyBytes = null;
+            if (bodyBase64 != null && !bodyBase64.equals("null")) {
+                try {
+                    bodyBytes = Base64.decode(bodyBase64, Base64.DEFAULT);
+                } catch (Exception e) {
+                    Log.w(TAG, "Base64 decode failed for request " + requestId, e);
+                }
+            }
+
+            String contentType = headers.getOrDefault("Content-Type", "application/octet-stream");
+            String encoding = contentType.contains("text/") ? "UTF-8" : null;
+
+            InputStream body = bodyBytes != null
+                    ? new ByteArrayInputStream(bodyBytes)
+                    : new ByteArrayInputStream(new byte[0]);
+
+            WebResourceResponse response = new WebResourceResponse(
+                    contentType, encoding, status, statusText, headers, body
+            );
+
+            pending.resolve(response);
+        }
+    }
+
+    /**
+     * WebViewClient that intercepts all requests and forwards them to JS.
+     */
+    private static class SandboxWebViewClient extends WebViewClient {
+        private final SandboxInstance sandbox;
+        private boolean bridgeInjected = false;
+
+        SandboxWebViewClient(SandboxInstance sandbox) {
+            this.sandbox = sandbox;
+        }
+
+        @Override
+        public WebResourceResponse shouldInterceptRequest(WebView view, WebResourceRequest request) {
+            String url = request.getUrl().toString();
+
+            // Only intercept requests to the sandbox domain.
+            if (!url.contains(".sandbox.native")) {
+                return null;
+            }
+
+            String requestId = UUID.randomUUID().toString();
+
+            // Create a pending request with a blocking latch.
+            PendingRequest pending = new PendingRequest();
+            sandbox.pendingRequests.put(requestId, pending);
+
+            // Rewrite URL to include the sandbox ID for the JS handler.
+            String path = request.getUrl().getPath();
+            if (path == null || path.isEmpty()) path = "/";
+            String rewrittenURL = "https://" + sandbox.id + ".sandbox.native" + path;
+
+            // Serialise the request.
+            JSObject serialisedRequest = new JSObject();
+            serialisedRequest.put("url", rewrittenURL);
+            serialisedRequest.put("method", request.getMethod());
+
+            JSObject headers = new JSObject();
+            for (Map.Entry<String, String> entry : request.getRequestHeaders().entrySet()) {
+                headers.put(entry.getKey(), entry.getValue());
+            }
+            serialisedRequest.put("headers", headers);
+            serialisedRequest.put("body", JSONObject.NULL);
+
+            // Emit to JS.
+            sandbox.plugin.emitFetchRequest(sandbox.id, requestId, serialisedRequest);
+
+            // Block until JS responds. Each asset is fetched from a Blossom
+            // server over the network, so we need a generous timeout.  The
+            // WebView IO thread pool has ~6 threads; if all are blocked,
+            // subsequent requests queue until a thread frees up.
+            WebResourceResponse response = pending.awaitResponse(60000);
+
+            if (response != null) {
+                return response;
+            }
+
+            // Timeout — return error response.
+            sandbox.pendingRequests.remove(requestId);
+            return new WebResourceResponse(
+                    "text/plain", "UTF-8", 504,
+                    "Gateway Timeout", new HashMap<>(),
+                    new ByteArrayInputStream("Request timed out".getBytes())
+            );
+        }
+
+        @Override
+        public void onPageFinished(WebView view, String url) {
+            super.onPageFinished(view, url);
+
+            if (!bridgeInjected) {
+                bridgeInjected = true;
+                view.evaluateJavascript(getBridgeScript(), null);
+            }
+
+            // Remove the native spinner once the first page has finished
+            // loading (all initial resources resolved). This runs on the
+            // main thread, so the removal is safe.
+            sandbox.hideSpinner();
+        }
+
+        private String getBridgeScript() {
+            return "(function() {" +
+                    "'use strict';" +
+                    "var messageListeners = [];" +
+                    "window.__sandboxBridge = {" +
+                    "  onMessage: function(data) {" +
+                    "    var event = {" +
+                    "      data: data," +
+                    "      origin: 'https://" + sandbox.id + ".sandbox.native'," +
+                    "      source: window.parent," +
+                    "      type: 'message'" +
+                    "    };" +
+                    "    for (var i = 0; i < messageListeners.length; i++) {" +
+                    "      try { messageListeners[i](event); } catch(e) {}" +
+                    "    }" +
+                    "  }" +
+                    "};" +
+                    "var origAdd = window.addEventListener;" +
+                    "window.addEventListener = function(type, fn, opts) {" +
+                    "  if (type === 'message' && typeof fn === 'function') messageListeners.push(fn);" +
+                    "  return origAdd.call(window, type, fn, opts);" +
+                    "};" +
+                    "var origRemove = window.removeEventListener;" +
+                    "window.removeEventListener = function(type, fn, opts) {" +
+                    "  if (type === 'message') {" +
+                    "    var idx = messageListeners.indexOf(fn);" +
+                    "    if (idx !== -1) messageListeners.splice(idx, 1);" +
+                    "  }" +
+                    "  return origRemove.call(window, type, fn, opts);" +
+                    "};" +
+                    "if (!window.parent || window.parent === window) window.parent = {};" +
+                    "window.parent.postMessage = function(data) {" +
+                    "  if (data && typeof data === 'object' && data.jsonrpc === '2.0') {" +
+                    "    try { window.__sandboxNative.postMessage(JSON.stringify(data)); } catch(e) {}" +
+                    "  }" +
+                    "};" +
+                    "})();";
+        }
+    }
+
+    /**
+     * JavaScript interface exposed to the sandbox WebView.
+     */
+    private static class SandboxBridge {
+        private final SandboxInstance sandbox;
+
+        SandboxBridge(SandboxInstance sandbox) {
+            this.sandbox = sandbox;
+        }
+
+        @JavascriptInterface
+        public void postMessage(String json) {
+            try {
+                JSONObject obj = new JSONObject(json);
+                JSObject jsObj = new JSObject();
+                for (java.util.Iterator<String> it = obj.keys(); it.hasNext(); ) {
+                    String key = it.next();
+                    jsObj.put(key, obj.get(key));
+                }
+                sandbox.plugin.emitScriptMessage(sandbox.id, jsObj);
+            } catch (JSONException e) {
+                Log.w(TAG, "Failed to parse script message", e);
+            }
+        }
+    }
+
+    /**
+     * A pending request that blocks the WebViewClient IO thread until JS
+     * responds with the complete resource.
+     */
+    private static class PendingRequest {
+        private volatile WebResourceResponse response;
+        private final CountDownLatch latch = new CountDownLatch(1);
+
+        void resolve(WebResourceResponse response) {
+            this.response = response;
+            latch.countDown();
+        }
+
+        WebResourceResponse awaitResponse(long timeoutMs) {
+            try {
+                latch.await(timeoutMs, TimeUnit.MILLISECONDS);
+            } catch (InterruptedException e) {
+                Thread.currentThread().interrupt();
+            }
+            return response;
+        }
+    }
+}

android/capacitor.settings.gradle

@@ -8,11 +8,17 @@ project(':capacitor-app').projectDir = new File('../node_modules/@capacitor/app/
 include ':capacitor-filesystem'
 project(':capacitor-filesystem').projectDir = new File('../node_modules/@capacitor/filesystem/android')
 
+include ':capacitor-keyboard'
+project(':capacitor-keyboard').projectDir = new File('../node_modules/@capacitor/keyboard/android')
+
 include ':capacitor-local-notifications'
 project(':capacitor-local-notifications').projectDir = new File('../node_modules/@capacitor/local-notifications/android')
 
 include ':capacitor-share'
 project(':capacitor-share').projectDir = new File('../node_modules/@capacitor/share/android')
 
-include ':capacitor-status-bar'
-project(':capacitor-status-bar').projectDir = new File('../node_modules/@capacitor/status-bar/android')
+include ':capgo-capacitor-autofill-save-password'
+project(':capgo-capacitor-autofill-save-password').projectDir = new File('../node_modules/@capgo/capacitor-autofill-save-password/android')
+
+include ':capacitor-secure-storage-plugin'
+project(':capacitor-secure-storage-plugin').projectDir = new File('../node_modules/capacitor-secure-storage-plugin/android')

capacitor.config.ts

@@ -5,8 +5,6 @@ const config: CapacitorConfig = {
   appName: 'Ditto',
   webDir: 'dist',
   server: {
-    // Handle deep links from your domain
-    hostname: 'ditto.pub',
     androidScheme: 'https',
     iosScheme: 'https'
   },
@@ -17,9 +15,16 @@ const config: CapacitorConfig = {
   },
   ios: {
     backgroundColor: '#14161f',
-    contentInset: 'automatic',
+    contentInset: 'never',
     scheme: 'Ditto'
-  }
+  },
+  plugins: {
+    SystemBars: {
+      // Inject --safe-area-inset-* CSS variables on Android to work around
+      // a Chromium bug (<140) where env(safe-area-inset-*) reports 0.
+      insetsHandling: 'css',
+    },
+  },
 };
 
 export default config;

docs/THEME_SYSTEM.md

@@ -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
 

docs/blobbi/blobbi-tag-schema.md

@@ -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)

eslint.config.js

@@ -8,7 +8,7 @@ import htmlParser from "@html-eslint/parser";
 import customRules from "./eslint-rules/index.js";
 
 export default tseslint.config(
-  { ignores: ["dist", "android"] },
+  { ignores: ["dist", "android", "ios"] },
   {
     extends: [js.configs.recommended, ...tseslint.configs.recommended],
     files: ["**/*.{ts,tsx}"],

index.html

@@ -3,7 +3,7 @@
   <head>
     <title>Ditto — Your content. Your vibe. Your rules.</title>
     <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover, interactive-widget=resizes-content" />
     <meta name="description" content="Ditto — Your content. Your vibe. Your rules." />
 
     <!-- Open Graph -->

ios/App/App.xcodeproj/project.pbxproj

@@ -15,6 +15,9 @@
 		504EC30F1FED79650016851F /* Assets.xcassets in Resources */ = {isa = PBXBuildFile; fileRef = 504EC30E1FED79650016851F /* Assets.xcassets */; };
 		504EC3121FED79650016851F /* LaunchScreen.storyboard in Resources */ = {isa = PBXBuildFile; fileRef = 504EC3101FED79650016851F /* LaunchScreen.storyboard */; };
 		50B271D11FEDC1A000F3C39B /* public in Resources */ = {isa = PBXBuildFile; fileRef = 50B271D01FEDC1A000F3C39B /* public */; };
+		B1A2C3D40001000100000001 /* SandboxPlugin.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40001000100000002 /* SandboxPlugin.swift */; };
+		B1A2C3D40002000100000001 /* DittoBridgeViewController.swift in Sources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40002000100000002 /* DittoBridgeViewController.swift */; };
+		B1A2C3D40005000100000001 /* PrivacyInfo.xcprivacy in Resources */ = {isa = PBXBuildFile; fileRef = B1A2C3D40005000100000002 /* PrivacyInfo.xcprivacy */; };
 /* End PBXBuildFile section */
 
 /* Begin PBXFileReference section */
@@ -28,6 +31,10 @@
 		504EC3131FED79650016851F /* Info.plist */ = {isa = PBXFileReference; lastKnownFileType = text.plist.xml; path = Info.plist; sourceTree = "<group>"; };
 		50B271D01FEDC1A000F3C39B /* public */ = {isa = PBXFileReference; lastKnownFileType = folder; path = public; sourceTree = "<group>"; };
 		958DCC722DB07C7200EA8C5F /* debug.xcconfig */ = {isa = PBXFileReference; lastKnownFileType = text.xcconfig; name = debug.xcconfig; path = ../debug.xcconfig; sourceTree = SOURCE_ROOT; };
+		B1A2C3D40001000100000002 /* SandboxPlugin.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = SandboxPlugin.swift; sourceTree = "<group>"; };
+		B1A2C3D40002000100000002 /* DittoBridgeViewController.swift */ = {isa = PBXFileReference; lastKnownFileType = sourcecode.swift; path = DittoBridgeViewController.swift; sourceTree = "<group>"; };
+		B1A2C3D40004000100000002 /* App.entitlements */ = {isa = PBXFileReference; lastKnownFileType = text.plist.entitlements; path = App.entitlements; sourceTree = "<group>"; };
+		B1A2C3D40005000100000002 /* PrivacyInfo.xcprivacy */ = {isa = PBXFileReference; lastKnownFileType = text.xml; path = PrivacyInfo.xcprivacy; sourceTree = "<group>"; };
 /* End PBXFileReference section */
 
 /* Begin PBXFrameworksBuildPhase section */
@@ -63,11 +70,15 @@
 			isa = PBXGroup;
 			children = (
 				50379B222058CBB4000EE86E /* capacitor.config.json */,
+				B1A2C3D40004000100000002 /* App.entitlements */,
 				504EC3071FED79650016851F /* AppDelegate.swift */,
+				B1A2C3D40001000100000002 /* SandboxPlugin.swift */,
+				B1A2C3D40002000100000002 /* DittoBridgeViewController.swift */,
 				504EC30B1FED79650016851F /* Main.storyboard */,
 				504EC30E1FED79650016851F /* Assets.xcassets */,
 				504EC3101FED79650016851F /* LaunchScreen.storyboard */,
 				504EC3131FED79650016851F /* Info.plist */,
+				B1A2C3D40005000100000002 /* PrivacyInfo.xcprivacy */,
 				2FAD9762203C412B000D30F8 /* config.xml */,
 				50B271D01FEDC1A000F3C39B /* public */,
 			);
@@ -145,6 +156,7 @@
 				50379B232058CBB4000EE86E /* capacitor.config.json in Resources */,
 				504EC30D1FED79650016851F /* Main.storyboard in Resources */,
 				2FAD9763203C412B000D30F8 /* config.xml in Resources */,
+				B1A2C3D40005000100000001 /* PrivacyInfo.xcprivacy in Resources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -156,6 +168,8 @@
 			buildActionMask = 2147483647;
 			files = (
 				504EC3081FED79650016851F /* AppDelegate.swift in Sources */,
+				B1A2C3D40001000100000001 /* SandboxPlugin.swift in Sources */,
+				B1A2C3D40002000100000001 /* DittoBridgeViewController.swift in Sources */,
 			);
 			runOnlyForDeploymentPostprocessing = 0;
 		};
@@ -295,15 +309,17 @@
 			baseConfigurationReference = 958DCC722DB07C7200EA8C5F /* debug.xcconfig */;
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CODE_SIGN_STYLE = Automatic;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = GZLTTH5DLM;
 				INFOPLIST_FILE = App/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 2.2.0;
+				MARKETING_VERSION = 2.6.6;
 				OTHER_SWIFT_FLAGS = "$(inherited) \"-D\" \"COCOAPODS\" \"-DDEBUG\"";
 				PRODUCT_BUNDLE_IDENTIFIER = pub.ditto.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
@@ -317,15 +333,17 @@
 			isa = XCBuildConfiguration;
 			buildSettings = {
 				ASSETCATALOG_COMPILER_APPICON_NAME = AppIcon;
+				CODE_SIGN_ENTITLEMENTS = App/App.entitlements;
 				CODE_SIGN_STYLE = Automatic;
 				CURRENT_PROJECT_VERSION = 1;
+				DEVELOPMENT_TEAM = GZLTTH5DLM;
 				INFOPLIST_FILE = App/Info.plist;
 				IPHONEOS_DEPLOYMENT_TARGET = 15.0;
 				LD_RUNPATH_SEARCH_PATHS = (
 					"$(inherited)",
 					"@executable_path/Frameworks",
 				);
-				MARKETING_VERSION = 2.2.0;
+				MARKETING_VERSION = 2.6.6;
 				PRODUCT_BUNDLE_IDENTIFIER = pub.ditto.app;
 				PRODUCT_NAME = "$(TARGET_NAME)";
 				SWIFT_ACTIVE_COMPILATION_CONDITIONS = "";

ios/App/App/App.entitlements

@@ -0,0 +1,11 @@
+<?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>com.apple.developer.associated-domains</key>
+	<array>
+		<string>webcredentials:ditto.pub</string>
+		<string>webcredentials:ditto.pub?mode=developer</string>
+	</array>
+</dict>
+</plist>

ios/App/App/Base.lproj/Main.storyboard

@@ -11,7 +11,7 @@
         <!--Bridge View Controller-->
         <scene sceneID="tne-QT-ifu">
             <objects>
-                <viewController id="BYZ-38-t0r" customClass="CAPBridgeViewController" customModule="Capacitor" sceneMemberID="viewController"/>
+                <viewController id="BYZ-38-t0r" customClass="DittoBridgeViewController" customModule="App" sceneMemberID="viewController"/>
                 <placeholder placeholderIdentifier="IBFirstResponder" id="dkx-z0-nzr" sceneMemberID="firstResponder"/>
             </objects>
         </scene>

ios/App/App/DittoBridgeViewController.swift

@@ -0,0 +1,9 @@
+import UIKit
+import Capacitor
+
+class DittoBridgeViewController: CAPBridgeViewController {
+    override func capacitorDidLoad() {
+        super.capacitorDidLoad()
+        webView?.allowsBackForwardNavigationGestures = true
+    }
+}

ios/App/App/Info.plist

@@ -47,5 +47,13 @@
 	</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>NSCameraUsageDescription</key>
+	<string>Ditto needs camera access to take photos and videos for your posts.</string>
+	<key>NSMicrophoneUsageDescription</key>
+	<string>Ditto needs access to your microphone to record voice messages.</string>
+	<key>ITSAppUsesNonExemptEncryption</key>
+	<false/>
 </dict>
 </plist>

ios/App/App/PrivacyInfo.xcprivacy

@@ -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>

ios/App/App/SandboxPlugin.swift

@@ -0,0 +1,541 @@
+import Foundation
+import Capacitor
+import WebKit
+
+// MARK: - Plugin
+
+/// Capacitor plugin that creates isolated WKWebViews for sandboxed content.
+///
+/// Each sandbox gets a unique custom URL scheme (`sbx-<id>://`) so that
+/// every embedded app has its own origin (separate localStorage, cookies, etc.).
+/// All requests on the custom scheme are intercepted via `WKURLSchemeHandler`
+/// and forwarded to the JS layer as fetch events — the same protocol
+/// iframe.diy uses. This lets the existing React code serve files identically.
+@objc(SandboxPlugin)
+public class SandboxPlugin: CAPPlugin, CAPBridgedPlugin {
+    public let identifier = "SandboxPlugin"
+    public let jsName = "SandboxPlugin"
+    public let pluginMethods: [CAPPluginMethod] = [
+        CAPPluginMethod(name: "create", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "navigate", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "updateFrame", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "respondToFetch", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "postMessage", returnType: CAPPluginReturnPromise),
+        CAPPluginMethod(name: "destroy", returnType: CAPPluginReturnPromise),
+    ]
+
+    /// Active sandbox instances, keyed by sandbox ID.
+    private var sandboxes: [String: SandboxInstance] = [:]
+
+    // MARK: - Plugin Methods
+
+    @objc func create(_ call: CAPPluginCall) {
+        guard let sandboxId = call.getString("id") else {
+            call.reject("Missing required parameter: id")
+            return
+        }
+        guard let frame = call.getObject("frame"),
+              let x = frame["x"] as? Double,
+              let y = frame["y"] as? Double,
+              let width = frame["width"] as? Double,
+              let height = frame["height"] as? Double else {
+            call.reject("Missing or invalid parameter: frame")
+            return
+        }
+
+        if sandboxes[sandboxId] != nil {
+            call.reject("Sandbox already exists: \(sandboxId)")
+            return
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+
+            let webViewFrame = CGRect(x: x, y: y, width: width, height: height)
+            let sandbox = SandboxInstance(
+                id: sandboxId,
+                frame: webViewFrame,
+                plugin: self
+            )
+            self.sandboxes[sandboxId] = sandbox
+
+            // Add the container (WebView + spinner overlay) on top of
+            // the Capacitor WebView.
+            if let bridge = self.bridge,
+               let webView = bridge.webView {
+                webView.superview?.addSubview(sandbox.containerView)
+            }
+
+            call.resolve()
+        }
+    }
+
+    @objc func navigate(_ call: CAPPluginCall) {
+        guard let sandboxId = call.getString("id") else {
+            call.reject("Missing required parameter: id")
+            return
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            guard let sandbox = self?.sandboxes[sandboxId] else {
+                call.reject("Sandbox not found: \(sandboxId)")
+                return
+            }
+            sandbox.navigateToApp()
+            call.resolve()
+        }
+    }
+
+    @objc func updateFrame(_ call: CAPPluginCall) {
+        guard let sandboxId = call.getString("id") else {
+            call.reject("Missing required parameter: id")
+            return
+        }
+        guard let frame = call.getObject("frame"),
+              let x = frame["x"] as? Double,
+              let y = frame["y"] as? Double,
+              let width = frame["width"] as? Double,
+              let height = frame["height"] as? Double else {
+            call.reject("Missing or invalid parameter: frame")
+            return
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            guard let sandbox = self?.sandboxes[sandboxId] else {
+                call.reject("Sandbox not found: \(sandboxId)")
+                return
+            }
+            sandbox.containerView.frame = CGRect(x: x, y: y, width: width, height: height)
+            call.resolve()
+        }
+    }
+
+    @objc func respondToFetch(_ call: CAPPluginCall) {
+        guard let sandboxId = call.getString("id") else {
+            call.reject("Missing required parameter: id")
+            return
+        }
+        guard let requestId = call.getString("requestId") else {
+            call.reject("Missing required parameter: requestId")
+            return
+        }
+        guard let response = call.getObject("response") else {
+            call.reject("Missing required parameter: response")
+            return
+        }
+
+        guard let sandbox = sandboxes[sandboxId] else {
+            call.reject("Sandbox not found: \(sandboxId)")
+            return
+        }
+
+        sandbox.schemeHandler.resolveRequest(
+            requestId: requestId,
+            status: response["status"] as? Int ?? 200,
+            statusText: response["statusText"] as? String ?? "OK",
+            headers: response["headers"] as? [String: String] ?? [:],
+            bodyBase64: response["body"] as? String
+        )
+
+        call.resolve()
+    }
+
+    @objc func postMessage(_ call: CAPPluginCall) {
+        guard let sandboxId = call.getString("id") else {
+            call.reject("Missing required parameter: id")
+            return
+        }
+        guard let message = call.getObject("message") else {
+            call.reject("Missing required parameter: message")
+            return
+        }
+
+        guard let sandbox = sandboxes[sandboxId] else {
+            call.reject("Sandbox not found: \(sandboxId)")
+            return
+        }
+
+        DispatchQueue.main.async {
+            sandbox.postMessageToWebView(message)
+        }
+
+        call.resolve()
+    }
+
+    @objc func destroy(_ call: CAPPluginCall) {
+        guard let sandboxId = call.getString("id") else {
+            call.reject("Missing required parameter: id")
+            return
+        }
+
+        DispatchQueue.main.async { [weak self] in
+            guard let self = self else { return }
+            if let sandbox = self.sandboxes.removeValue(forKey: sandboxId) {
+                sandbox.containerView.removeFromSuperview()
+                sandbox.schemeHandler.cancelAll()
+            }
+            call.resolve()
+        }
+    }
+
+    // MARK: - Event Forwarding
+
+    /// Forward a fetch request from the native WebView to JS.
+    func emitFetchRequest(sandboxId: String, requestId: String, request: [String: Any]) {
+        notifyListeners("fetch", data: [
+            "id": sandboxId,
+            "requestId": requestId,
+            "request": request,
+        ])
+    }
+
+    /// Forward a script message from the sandbox to JS.
+    func emitScriptMessage(sandboxId: String, message: [String: Any]) {
+        notifyListeners("scriptMessage", data: [
+            "id": sandboxId,
+            "message": message,
+        ])
+    }
+}
+
+// MARK: - SandboxInstance
+
+/// Manages a single sandboxed WKWebView instance.
+private class SandboxInstance: NSObject, WKScriptMessageHandler, WKNavigationDelegate {
+    let id: String
+    let webView: WKWebView
+    let schemeHandler: SandboxSchemeHandler
+    private weak var plugin: SandboxPlugin?
+    private let customScheme: String
+
+    /// Container view that holds the WebView and spinner overlay.
+    let containerView: UIView
+
+    /// Native spinner overlay, removed when the first page finishes loading.
+    private var spinnerOverlay: UIView?
+
+    init(id: String, frame: CGRect, plugin: SandboxPlugin) {
+        self.id = id
+        self.plugin = plugin
+
+        // Each sandbox gets a unique custom URL scheme so that WKWebView
+        // assigns a distinct origin, isolating localStorage/IndexedDB/cookies.
+        self.customScheme = "sbx-\(id)"
+
+        self.schemeHandler = SandboxSchemeHandler(
+            sandboxId: id,
+            scheme: self.customScheme,
+            plugin: plugin
+        )
+
+        let config = WKWebViewConfiguration()
+        config.setURLSchemeHandler(self.schemeHandler, forURLScheme: self.customScheme)
+
+        // Add a script message handler for communication from injected scripts.
+        let userContentController = WKUserContentController()
+
+        // Inject a bridge script that:
+        // 1. Provides window.parent.postMessage()-like functionality
+        // 2. Routes messages through the native bridge
+        let bridgeScript = WKUserScript(
+            source: SandboxInstance.bridgeScript(scheme: self.customScheme),
+            injectionTime: .atDocumentStart,
+            forMainFrameOnly: false
+        )
+        userContentController.addUserScript(bridgeScript)
+
+        config.userContentController = userContentController
+        config.preferences.javaScriptCanOpenWindowsAutomatically = false
+        config.defaultWebpagePreferences.allowsContentJavaScript = true
+
+        // Container view that holds the WebView + spinner overlay.
+        self.containerView = UIView(frame: frame)
+
+        self.webView = WKWebView(frame: containerView.bounds, configuration: config)
+        self.webView.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        self.webView.isOpaque = false
+        self.webView.backgroundColor = UIColor(red: 0x14/255.0, green: 0x16/255.0, blue: 0x1f/255.0, alpha: 1)
+        self.webView.scrollView.backgroundColor = self.webView.backgroundColor
+        self.webView.scrollView.bounces = false
+        self.containerView.addSubview(self.webView)
+
+        // Dark overlay behind the spinner.
+        let overlay = UIView(frame: containerView.bounds)
+        overlay.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+        overlay.backgroundColor = UIColor(red: 0x14/255.0, green: 0x16/255.0, blue: 0x1f/255.0, alpha: 1)
+        self.containerView.addSubview(overlay)
+
+        // Native spinner — uses UIActivityIndicatorView which animates on
+        // the render thread independently of JS/main-thread work.
+        let spinner = UIActivityIndicatorView(style: .medium)
+        spinner.color = UIColor(red: 124/255.0, green: 92/255.0, blue: 220/255.0, alpha: 1)
+        spinner.translatesAutoresizingMaskIntoConstraints = false
+        spinner.startAnimating()
+        overlay.addSubview(spinner)
+        NSLayoutConstraint.activate([
+            spinner.centerXAnchor.constraint(equalTo: overlay.centerXAnchor),
+            spinner.centerYAnchor.constraint(equalTo: overlay.centerYAnchor),
+        ])
+
+        self.spinnerOverlay = overlay
+
+        super.init()
+
+        // Register the message handler and navigation delegate after super.init().
+        userContentController.add(self, name: "sandboxBridge")
+        self.webView.navigationDelegate = self
+    }
+
+    /// Navigate the WebView to the sandbox's entry point.
+    func navigateToApp() {
+        let initialURL = URL(string: "\(customScheme)://app/index.html")!
+        webView.load(URLRequest(url: initialURL))
+    }
+
+    /// Remove the native loading overlay. Safe to call multiple times.
+    func hideSpinner() {
+        spinnerOverlay?.removeFromSuperview()
+        spinnerOverlay = nil
+    }
+
+    /// Post a JSON-RPC message to injected scripts inside the WebView.
+    func postMessageToWebView(_ message: [String: Any]) {
+        guard let jsonData = try? JSONSerialization.data(withJSONObject: message),
+              let jsonString = String(data: jsonData, encoding: .utf8) else {
+            return
+        }
+
+        let js = """
+        (function() {
+            if (window.__sandboxBridge && window.__sandboxBridge.onMessage) {
+                window.__sandboxBridge.onMessage(\(jsonString));
+            }
+        })();
+        """
+        webView.evaluateJavaScript(js, completionHandler: nil)
+    }
+
+    // MARK: - WKScriptMessageHandler
+
+    /// Receive messages from injected scripts via webkit.messageHandlers.sandboxBridge.
+    func userContentController(
+        _ userContentController: WKUserContentController,
+        didReceive message: WKScriptMessage
+    ) {
+        guard message.name == "sandboxBridge",
+              let body = message.body as? [String: Any] else {
+            return
+        }
+        plugin?.emitScriptMessage(sandboxId: id, message: body)
+    }
+
+    // MARK: - WKNavigationDelegate
+
+    /// Remove the spinner overlay once the first page finishes loading.
+    func webView(_ webView: WKWebView, didFinish navigation: WKNavigation!) {
+        hideSpinner()
+    }
+
+    // MARK: - Bridge Script
+
+    /// JavaScript injected at document start that provides:
+    ///   - `window.parent.postMessage()` emulation via WKScriptMessageHandler
+    ///   - `window.__sandboxBridge.onMessage()` for receiving messages from parent
+    ///   - `window.addEventListener("message", ...)` support for injected scripts
+    private static func bridgeScript(scheme: String) -> String {
+        return """
+        (function() {
+            'use strict';
+
+            // Message listeners registered by injected scripts.
+            var messageListeners = [];
+
+            // Bridge object for native communication.
+            window.__sandboxBridge = {
+                onMessage: function(data) {
+                    // Dispatch to all registered message listeners.
+                    var event = {
+                        data: data,
+                        origin: '\(scheme)://app',
+                        source: window.parent,
+                        type: 'message'
+                    };
+                    for (var i = 0; i < messageListeners.length; i++) {
+                        try {
+                            messageListeners[i](event);
+                        } catch (e) {
+                            console.error('[SandboxBridge] Listener error:', e);
+                        }
+                    }
+                }
+            };
+
+            // Override addEventListener to capture "message" listeners.
+            var originalAddEventListener = window.addEventListener;
+            window.addEventListener = function(type, listener, options) {
+                if (type === 'message' && typeof listener === 'function') {
+                    messageListeners.push(listener);
+                }
+                return originalAddEventListener.call(window, type, listener, options);
+            };
+
+            var originalRemoveEventListener = window.removeEventListener;
+            window.removeEventListener = function(type, listener, options) {
+                if (type === 'message') {
+                    var idx = messageListeners.indexOf(listener);
+                    if (idx !== -1) messageListeners.splice(idx, 1);
+                }
+                return originalRemoveEventListener.call(window, type, listener, options);
+            };
+
+            // Emulate window.parent.postMessage for scripts that use it
+            // (e.g. the webxdc bridge script, preview injected script).
+            if (!window.parent || window.parent === window) {
+                window.parent = {};
+            }
+            window.parent.postMessage = function(data, targetOrigin, transfer) {
+                if (data && typeof data === 'object' && data.jsonrpc === '2.0') {
+                    try {
+                        window.webkit.messageHandlers.sandboxBridge.postMessage(data);
+                    } catch (e) {
+                        console.error('[SandboxBridge] postMessage failed:', e);
+                    }
+                }
+            };
+        })();
+        """;
+    }
+}
+
+// MARK: - SandboxSchemeHandler
+
+/// WKURLSchemeHandler that intercepts all requests on the sandbox's custom
+/// URL scheme and forwards them to the JS layer as fetch events.
+private class SandboxSchemeHandler: NSObject, WKURLSchemeHandler {
+    private let sandboxId: String
+    private let scheme: String
+    private weak var plugin: SandboxPlugin?
+
+    /// Pending scheme tasks waiting for a response from JS.
+    /// Key: requestId (UUID string), Value: the WKURLSchemeTask to respond to.
+    private var pendingTasks: [String: WKURLSchemeTask] = [:]
+    private let lock = NSLock()
+
+    init(sandboxId: String, scheme: String, plugin: SandboxPlugin) {
+        self.sandboxId = sandboxId
+        self.scheme = scheme
+        self.plugin = plugin
+    }
+
+    func webView(_ webView: WKWebView, start urlSchemeTask: WKURLSchemeTask) {
+        let request = urlSchemeTask.request
+        guard let url = request.url else {
+            urlSchemeTask.didFailWithError(NSError(
+                domain: "SandboxPlugin", code: -1,
+                userInfo: [NSLocalizedDescriptionKey: "No URL in request"]
+            ))
+            return
+        }
+
+        let requestId = UUID().uuidString
+
+        lock.lock()
+        pendingTasks[requestId] = urlSchemeTask
+        lock.unlock()
+
+        // Serialise the request for the fetch event.
+        // Rewrite the URL so it looks like a normal HTTP URL to the parent
+        // (e.g. "sbx-abc123://app/index.html" -> "https://<sandboxId>.sandbox.native/index.html")
+        // The JS side only cares about the pathname.
+        var headers: [String: String] = [:]
+        if let allHeaders = request.allHTTPHeaderFields {
+            headers = allHeaders
+        }
+
+        var bodyBase64: String? = nil
+        if let bodyData = request.httpBody {
+            bodyBase64 = bodyData.base64EncodedString()
+        }
+
+        let path = url.path.isEmpty ? "/" : url.path
+        let rewrittenURL = "https://\(sandboxId).sandbox.native\(path)"
+
+        let serialisedRequest: [String: Any] = [
+            "url": rewrittenURL,
+            "method": request.httpMethod ?? "GET",
+            "headers": headers,
+            "body": bodyBase64 as Any,
+        ]
+
+        plugin?.emitFetchRequest(
+            sandboxId: sandboxId,
+            requestId: requestId,
+            request: serialisedRequest
+        )
+    }
+
+    func webView(_ webView: WKWebView, stop urlSchemeTask: WKURLSchemeTask) {
+        // Remove the task from pending — JS response will be ignored if it arrives later.
+        lock.lock()
+        let removed = pendingTasks.first(where: { $0.value === urlSchemeTask })
+        if let key = removed?.key {
+            pendingTasks.removeValue(forKey: key)
+        }
+        lock.unlock()
+    }
+
+    /// Called by the plugin when JS responds to a fetch request.
+    func resolveRequest(
+        requestId: String,
+        status: Int,
+        statusText: String,
+        headers: [String: String],
+        bodyBase64: String?
+    ) {
+        lock.lock()
+        guard let task = pendingTasks.removeValue(forKey: requestId) else {
+            lock.unlock()
+            return
+        }
+        lock.unlock()
+
+        // Decode the base64 body.
+        var bodyData: Data? = nil
+        if let b64 = bodyBase64 {
+            bodyData = Data(base64Encoded: b64)
+        }
+
+        // Build the response.
+        // Use the task's original URL for the response.
+        let responseURL = task.request.url ?? URL(string: "\(scheme)://app/")!
+        let response = HTTPURLResponse(
+            url: responseURL,
+            statusCode: status,
+            httpVersion: "HTTP/1.1",
+            headerFields: headers
+        )!
+
+        DispatchQueue.main.async {
+            task.didReceive(response)
+            if let data = bodyData {
+                task.didReceive(data)
+            }
+            task.didFinish()
+        }
+    }
+
+    /// Cancel all pending tasks (called on destroy).
+    func cancelAll() {
+        lock.lock()
+        let tasks = pendingTasks
+        pendingTasks.removeAll()
+        lock.unlock()
+
+        for (_, task) in tasks {
+            task.didFailWithError(NSError(
+                domain: "SandboxPlugin", code: -999,
+                userInfo: [NSLocalizedDescriptionKey: "Sandbox destroyed"]
+            ))
+        }
+    }
+}

ios/App/CapApp-SPM/Package.swift

@@ -14,9 +14,11 @@ let package = Package(
         .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", exact: "8.2.0"),
         .package(name: "CapacitorApp", path: "../../../node_modules/@capacitor/app"),
         .package(name: "CapacitorFilesystem", path: "../../../node_modules/@capacitor/filesystem"),
+        .package(name: "CapacitorKeyboard", path: "../../../node_modules/@capacitor/keyboard"),
         .package(name: "CapacitorLocalNotifications", path: "../../../node_modules/@capacitor/local-notifications"),
         .package(name: "CapacitorShare", path: "../../../node_modules/@capacitor/share"),
-        .package(name: "CapacitorStatusBar", path: "../../../node_modules/@capacitor/status-bar")
+        .package(name: "CapgoCapacitorAutofillSavePassword", path: "../../../node_modules/@capgo/capacitor-autofill-save-password"),
+        .package(name: "CapacitorSecureStoragePlugin", path: "../../../node_modules/capacitor-secure-storage-plugin")
     ],
     targets: [
         .target(
@@ -26,9 +28,11 @@ let package = Package(
                 .product(name: "Cordova", package: "capacitor-swift-pm"),
                 .product(name: "CapacitorApp", package: "CapacitorApp"),
                 .product(name: "CapacitorFilesystem", package: "CapacitorFilesystem"),
+                .product(name: "CapacitorKeyboard", package: "CapacitorKeyboard"),
                 .product(name: "CapacitorLocalNotifications", package: "CapacitorLocalNotifications"),
                 .product(name: "CapacitorShare", package: "CapacitorShare"),
-                .product(name: "CapacitorStatusBar", package: "CapacitorStatusBar")
+                .product(name: "CapgoCapacitorAutofillSavePassword", package: "CapgoCapacitorAutofillSavePassword"),
+                .product(name: "CapacitorSecureStoragePlugin", package: "CapacitorSecureStoragePlugin")
             ]
         )
     ]

package.json

@@ -1,12 +1,13 @@
 {
   "name": "ditto",
   "private": true,
-  "version": "2.2.0",
+  "version": "2.6.6",
   "type": "module",
   "scripts": {
     "dev": "npm i --silent && vite",
     "build": "npm i --silent && vite build -l error && cp dist/index.html dist/404.html && echo 'Project built successfully!'",
     "test": "npm i --silent && tsc --noEmit && eslint && vitest run --reporter=dot --silent && vite build -l error && cp dist/index.html dist/404.html && echo 'All tests passed!'",
+    "cap:sync": "npx cap sync && node scripts/patch-cap-config.mjs",
     "keygen": "keytool -genkey -v -keystore android/app/my-upload-key.keystore -keyalg RSA -keysize 2048 -validity 10000 -alias upload",
     "icons": "bash scripts/generate-icons.sh"
   },
@@ -17,9 +18,10 @@
     "@capacitor/app": "^8.0.0",
     "@capacitor/core": "^8.1.0",
     "@capacitor/filesystem": "^8.1.2",
+    "@capacitor/keyboard": "^8.0.3",
     "@capacitor/local-notifications": "^8.0.1",
     "@capacitor/share": "^8.0.1",
-    "@capacitor/status-bar": "^8.0.0",
+    "@capgo/capacitor-autofill-save-password": "^8.0.22",
     "@dnd-kit/core": "^6.3.1",
     "@dnd-kit/sortable": "^10.0.0",
     "@dnd-kit/utilities": "^3.2.2",
@@ -44,6 +46,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",
@@ -52,8 +55,19 @@
     "@fontsource/special-elite": "^5.2.8",
     "@getalby/sdk": "^5.1.1",
     "@hookform/resolvers": "^5.2.2",
-    "@nostrify/nostrify": "^0.51.0",
-    "@nostrify/react": "^0.4.0",
+    "@milkdown/core": "^7.20.0",
+    "@milkdown/ctx": "^7.20.0",
+    "@milkdown/plugin-clipboard": "^7.20.0",
+    "@milkdown/plugin-history": "^7.20.0",
+    "@milkdown/plugin-listener": "^7.20.0",
+    "@milkdown/plugin-upload": "^7.20.0",
+    "@milkdown/preset-commonmark": "^7.20.0",
+    "@milkdown/preset-gfm": "^7.20.0",
+    "@milkdown/prose": "^7.20.0",
+    "@milkdown/react": "^7.20.0",
+    "@milkdown/utils": "^7.20.0",
+    "@nostrify/nostrify": "^0.51.1",
+    "@nostrify/react": "^0.5.1",
     "@nostrify/types": "^0.36.9",
     "@plausible-analytics/tracker": "^0.4.4",
     "@radix-ui/react-accordion": "^1.2.0",
@@ -85,10 +99,11 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@sentry/react": "^10.42.0",
     "@tanstack/react-query": "^5.56.2",
-    "@unhead/addons": "^2.0.10",
-    "@unhead/react": "^2.0.10",
+    "@unhead/addons": "^2.1.13",
+    "@unhead/react": "^2.1.13",
     "blurhash": "^2.0.5",
     "buffer": "^6.0.3",
+    "capacitor-secure-storage-plugin": "^0.13.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "cmdk": "^1.0.0",
@@ -116,6 +131,7 @@
     "react-router-dom": "^6.26.2",
     "recharts": "^2.12.7",
     "rehype-sanitize": "^6.0.0",
+    "slugify": "^1.6.8",
     "smol-toml": "^1.6.0",
     "tailwind-merge": "^2.5.2",
     "tailwindcss-animate": "^1.0.7",

public/.well-known/apple-app-site-association

@@ -0,0 +1,7 @@
+{
+  "webcredentials": {
+    "apps": [
+      "GZLTTH5DLM.pub.ditto.app"
+    ]
+  }
+}

public/CHANGELOG.md

@@ -1,5 +1,340 @@
 # Changelog
 
+## [2.6.6] - 2026-04-12
+
+### Fixed
+- Emoji and mention autocomplete dropdowns no longer get clipped by the compose box
+- Emoji shortcodes now render as color emoji instead of plain text glyphs
+- Dialogs and input fields on Android are no longer obscured by the virtual keyboard
+- Signing requests on Android are more reliable and no longer silently fail after switching apps
+
+## [2.6.5] - 2026-04-11
+
+### Changed
+- Apps and games load significantly faster on Android with smarter prefetching and server affinity
+- Native loading spinners replace HTML-based ones on iOS and Android for a smoother experience
+
+### Fixed
+- External API requests on Android no longer fail due to hostname restrictions
+- iOS App Store compliance issues resolved
+
+## [2.6.4] - 2026-04-11
+
+### Added
+- iCloud Keychain integration on iOS -- your login credentials are now saved and restored automatically across devices
+
+### Changed
+- Empty feeds show a friendlier state with a discover button to help you find people to follow
+- Signup flow simplified -- cleaner profile step with a single Continue button
+
+### Fixed
+- Avatar fallback now shows the user's initial instead of a question mark
+- Android 16+ devices no longer have content hidden behind system bars
+- Signup dialog background clears properly when switching between light and dark themes
+- Sticky compose button stays anchored to the bottom even on empty feeds
+
+## [2.6.3] - 2026-04-10
+
+### Added
+- Lightning invoices embedded in posts now render as tappable payment cards
+- Blobbi companions in the feed reflect their current condition and projected health
+
+### Changed
+- Profile headers are cleaner -- lightning addresses and verification badges moved out of the way, and website URLs no longer show a trailing slash
+- Login credentials are saved to your browser's built-in password manager for easier sign-in across sessions
+- "Request to Vanish" renamed to "Delete Account" for clarity
+
+### Fixed
+- Badge image uploads now show a recommended 1:1 aspect ratio hint so your badges don't get cropped unexpectedly
+- Security hardening for URLs and styles sourced from the network
+
+## [2.6.2] - 2026-04-08
+
+### Added
+- Share follow packs and follow sets via link -- recipients see an immersive preview with member avatars, a "Follow All" button, and a combined feed from everyone in the pack
+- Curated home feed with a mix of photos, short videos, livestreams, and music -- content types are spaced out so your timeline stays fresh and varied
+- "Write a letter" option on profile menus for a more personal way to reach out
+- Push vs persistent notification delivery option on Android
+
+### Changed
+- Webxdc games and apps always open fullscreen for a more immersive experience
+- Login credentials are now stored in the device's secure keychain on iOS and Android instead of plain local storage
+- Profile fields now appear inline instead of in a separate right sidebar
+- Trending hashtags removed from the logged-out homepage for a cleaner first impression
+
+### Fixed
+- Webxdc and nsites work natively on iOS and Android without relying on browser sandboxing tricks
+- File downloads now save directly to Documents on iOS and Android instead of silently failing
+- Mobile search no longer scrolls the page behind it and properly hides the bottom navigation bar
+- iOS swipe-back navigation works correctly throughout the app
+- Blobbi companions appear reliably on profiles instead of sometimes going missing
+- IndexedDB no longer crashes on devices with Lockdown Mode enabled
+
+## [2.6.1] - 2026-04-06
+
+### Added
+- Manage your interest tabs (hashtags and locations) from the settings page
+- Edit button on custom profile tabs so you can tweak them without recreating from scratch
+- Follow packs and follow sets now show author info and action headers in the feed
+- Posts now show whether they were created or updated, so you can tell when something's been edited
+
+### Changed
+- Webxdc games and apps run in a more secure sandbox with stricter content policies and private subdomains
+- Nsite previews now use the same secure sandbox as webxdc apps
+- Blobbi items work as instant abilities instead of consumable inventory -- no more fiddly quantity pickers
+
+### Fixed
+- Desktop tab bar no longer overflows when you have lots of tabs -- scroll arrows appear automatically
+- Mobile compose box no longer randomly collapses or becomes unclickable
+- Profile avatar and banner lightbox no longer hides behind the right sidebar
+- Infinite scroll on custom profile tab feeds no longer reloads the same content
+- Reaction emoji are now visible on each row in the interactions modal
+- Missing bottom border on collapsed thread expand button restored
+
+## [2.6.0] - 2026-04-05
+
+### Added
+- Follow links and QR codes -- share a link or scannable code that lets anyone follow you with one tap, complete with your themed profile preview and recent posts
+- Immersive Blobbi hatching ceremony -- crack your egg through cinematic stages with shaking animations, a burst of light, sparkles, typewriter dialog, and a naming moment
+
+### Changed
+- Footer links redesigned as compact icon chips for a cleaner look
+- Custom emoji now render crisp at small sizes with pixel-perfect scaling
+
+### Fixed
+- Custom themes now apply correctly when logging in on a new device
+- Settings and preferences sync reliably across devices
+- Mobile sidebar links no longer clip into the safe area
+- Blobbi page background overlay now appears properly on custom themes
+- Blobbi companion state no longer resets unexpectedly from stale cache data
+- Letter compose picker no longer gets hidden behind the top navigation arc
+
+## [2.5.2] - 2026-04-04
+
+### Added
+- See who voted on each poll option -- tap the vote count to open a voters list with avatar stacks and per-option filter tabs
+- Poll votes now appear as activity cards in feeds and on detail pages
+
+### Fixed
+- Threads and replies load more reliably by following relay and author hints when fetching parent events
+
+## [2.5.1] - 2026-04-03
+
+### Fixed
+- Lightbox now reliably appears above all content, not just when opened from photo galleries
+
+## [2.5.0] - 2026-04-03
+
+### Added
+- Run nsites and web apps directly inside Ditto -- hit the "Run" button on any nsite or app card to preview it in an overlay without leaving your feed
+- File uploads in the poll composer -- attach images and media to your polls
+- Blobbi posts now appear in the homepage feed
+
+### Changed
+- Profile media sidebar fills remaining slots with photos from text posts when there aren't enough dedicated media posts
+- App cards now show banner images and improved layout
+
+### Fixed
+- Lightbox no longer appears behind the right sidebar
+- Compose box corners are properly rounded
+- Clicking buttons or links inside a post card no longer accidentally navigates to the post detail page
+
+## [2.4.1] - 2026-04-02
+
+### Added
+- Rich cards for Zapstore app releases and assets -- see download links, version info, platform badges, and hashes right in your feed
+
+### Fixed
+- First-hatch tour now shows for accounts that were onboarded before the tour existed, so no one misses the hatching moment
+
+## [2.4.0] - 2026-04-02
+
+### Added
+- First-hatch tour: a guided experience for hatching your very first Blobbi egg, with progressive crack animations, an inline card flow, and a reveal moment
+- Customizable bottom bar: rearrange or hide any item in the navigation bar to make Ditto feel like yours
+- Mission surface card in the feed that surfaces your active quests at a glance
+
+### Changed
+- Missions redesigned as a quest board with collapsible cards and a lighter aesthetic
+- "Edit Profile" mission now completes when you update any profile field, not just wall-specific edits
+- Media tab on profiles now shows only photos, videos, and other media -- not plain text posts
+- Blobbi onboarding state now syncs to your profile so it follows you across devices
+
+### Fixed
+- Notification dot no longer reappears after you've already marked notifications as read
+- Dialogs no longer fly up when the mobile keyboard opens
+
+## [2.3.1] - 2026-04-02
+
+### Changed
+- Drafts now save instantly to your device and sync to relays in the background, with a cloud sync indicator so you always know the status
+
+### Fixed
+- Dialogs stay visible above the keyboard on mobile instead of getting hidden behind it
+- Editing an existing article no longer incorrectly warns about a duplicate slug
+- Switching between rich text and markdown source mode no longer clears your content
+- Fix crash when editing in markdown source mode
+
+## [2.3.0] - 2026-04-02
+
+### Added
+- In-app article editor with a rich text toolbar, image uploads, auto-saving drafts, and a "My Articles" tab to manage drafts and published articles
+
+### Fixed
+- Custom emoji no longer stretch to fill their container
+- Mobile drawer now closes when tapping footer links like Changelog or Privacy
+- Logged-out users now default to the global tab on content feeds instead of seeing an empty follows tab
+
+## [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 now display in feeds and detail pages with hero images, icons, 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 login flows with Amber, Primal, and other signing apps
+
+### 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
+- 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 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
+- Event links now route correctly for all event types
+- 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
+- New posts no longer cause scroll jumps -- they buffer while you're reading and appear with a tap
+- Mobile header no longer shows double-layered backgrounds on notched devices
+- Pinned tabs stay properly positioned when scrolling on mobile
+- Signer approval toasts no longer fire in rapid succession on unstable connections
+- Toasts are easier to swipe away on mobile
+- Content warnings now blur thumbnails in the media grid
+
 ## [2.2.0] - 2026-03-28
 
 ### Added
@@ -7,11 +342,11 @@
 - 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
-- NIP-11 relay information panel on the network settings page
+- Immersive full-screen divines experience on both mobile and desktop with floating controls
+- 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
-- Remote signer UX improvements for Amber and NIP-46 users on Android
+- Remote signer UX improvements for Amber users on Android
 - Badge awards now trigger push notifications
 - Badges display in profile bio section with a "Give badge" option in the profile menu
 

scripts/nip46-auth.mjs

@@ -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);
+});

scripts/patch-cap-config.mjs

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+/**
+ * Patch capacitor.config.json to include local (non-SPM) plugin classes.
+ *
+ * `npx cap sync` regenerates the `packageClassList` array from SPM packages
+ * only, so local plugins compiled directly into the app binary (like
+ * SandboxPlugin) are not included. This script appends them after sync so
+ * the Capacitor bridge eagerly registers them at startup.
+ *
+ * Usage: node scripts/patch-cap-config.mjs
+ * Typically run after `npx cap sync`.
+ */
+
+import { readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+
+/** Local plugin class names to ensure are registered. */
+const LOCAL_PLUGINS = ['SandboxPlugin'];
+
+const platforms = ['ios/App/App', 'android/app/src/main/assets'];
+
+for (const platform of platforms) {
+  const configPath = resolve(platform, 'capacitor.config.json');
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, 'utf-8'));
+  } catch {
+    // Platform may not exist or config not yet generated — skip.
+    continue;
+  }
+
+  const classList = new Set(config.packageClassList ?? []);
+  let changed = false;
+
+  for (const plugin of LOCAL_PLUGINS) {
+    if (!classList.has(plugin)) {
+      classList.add(plugin);
+      changed = true;
+    }
+  }
+
+  if (changed) {
+    config.packageClassList = [...classList];
+    writeFileSync(configPath, JSON.stringify(config, null, '\t') + '\n');
+    console.log(`Patched ${configPath}: added ${LOCAL_PLUGINS.join(', ')}`);
+  }
+}

src/App.tsx

@@ -1,8 +1,7 @@
 // NOTE: This file should normally not be modified unless you are adding a new provider.
 // To add new routes, edit the AppRouter.tsx file.
 
-import { Capacitor } from "@capacitor/core";
-import { StatusBar, Style } from "@capacitor/status-bar";
+import { Capacitor, SystemBars, SystemBarsStyle } from "@capacitor/core";
 import { NostrLoginProvider } from "@nostrify/react/login";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { InferSeoMetaPlugin } from "@unhead/addons";
@@ -16,17 +15,20 @@ 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 { secureStorage } from "@/lib/secureStorage";
 import { EmotionDevProvider } from "@/blobbi/dev/EmotionDevContext";
 import AppRouter from "./AppRouter";
 
 const dmConfig: DMConfig = {
-  enabled: true,
+  enabled: false,
   protocolMode: PROTOCOL_MODE.NIP04_OR_NIP17,
 };
 
@@ -49,6 +51,7 @@ const hardcodedConfig: AppConfig = {
   appName: "Ditto",
   appId: "ditto",
   homePage: "feed",
+  client: "naddr1qvzqqqru7cpzq7q6z5ns2hm5c8msyv83qwzxpxe52j8c4d4q5m92wsp9sflelkh9qqzkg6t5w3hswjl4yp",
   magicMouse: false,
   theme: "system",
   autoShareTheme: true,
@@ -59,7 +62,9 @@ const hardcodedConfig: AppConfig = {
   },
   feedSettings: {
     feedIncludePosts: true,
+    feedIncludeComments: true,
     feedIncludeReposts: true,
+    feedIncludeGenericReposts: true,
     feedIncludeArticles: true,
     showArticles: true,
     showEvents: true,
@@ -112,18 +117,18 @@ const hardcodedConfig: AppConfig = {
     feedIncludeBadgeDefinitions: true,
     feedIncludeProfileBadges: true,
     feedIncludeVanish: true,
+    feedIncludeBlobbi: true,
     followsFeedShowReplies: true,
   },
   sidebarOrder: [
     "feed",
     "notifications",
     "search",
-    "bookmarks",
-    "profile",
-    "photos",
-    "videos",
+    "blobbi",
+    "badges",
+    "emojis",
+    "letters",
     "themes",
-    "theme",
     "settings",
     "help",
   ],
@@ -144,30 +149,47 @@ const hardcodedConfig: AppConfig = {
   plausibleEndpoint: import.meta.env.VITE_PLAUSIBLE_ENDPOINT || "",
   savedFeeds: [],
   imageQuality: 'compressed',
+  curatorPubkey: '932614571afcbad4d17a191ee281e39eebbb41b93fac8fd87829622aeb112f4d',
+  sandboxDomain: 'iframe.diy',
 };
 
+/**
+ * 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() {
   useNsecPasteGuard();
 
   useEffect(() => {
-    // Initialize StatusBar for mobile apps
+    // Initialize system bars for mobile apps.
+    // On Android 16+ (API 36), edge-to-edge is enforced by the OS so
+    // setOverlaysWebView / setBackgroundColor no longer work. The new
+    // SystemBars API (bundled with @capacitor/core 8+) is the replacement.
     if (Capacitor.isNativePlatform()) {
-      StatusBar.setStyle({ style: Style.Dark }).catch(() => {
-        // StatusBar may not be available on all platforms
-      });
-      StatusBar.setOverlaysWebView({ overlay: true }).catch(() => {
-        // Ignore errors on unsupported platforms
+      SystemBars.setStyle({ style: SystemBarsStyle.Dark }).catch(() => {
+        // SystemBars may not be available on all platforms
       });
     }
   }, []);
@@ -178,15 +200,15 @@ export function App() {
         <SentryProvider>
           <PlausibleProvider>
             <QueryClientProvider client={queryClient}>
-              <NostrLoginProvider storageKey="nostr:login">
+              <NostrLoginProvider storageKey="nostr:login" storage={secureStorage}>
                 <NostrProvider>
                   <NostrSync />
                   <NativeNotifications />
+
                     <NWCProvider>
                     <DMProvider config={dmConfig}>
                       <EmotionDevProvider>
                         <TooltipProvider>
-                          <Toaster />
                           <InitialSyncGate>
                             <AppRouter />
                           </InitialSyncGate>

src/AppRouter.tsx

@@ -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 })));
 
@@ -29,6 +34,7 @@ const HomePage = lazy(() => import("./pages/HomePage").then(m => ({ default: m.H
 const AdvancedSettingsPage = lazy(() => import("./pages/AdvancedSettingsPage").then(m => ({ default: m.AdvancedSettingsPage })));
 const AIChatPage = lazy(() => import("./pages/AIChatPage").then(m => ({ default: m.AIChatPage })));
 const ArchivePage = lazy(() => import("./pages/ArchivePage").then(m => ({ default: m.ArchivePage })));
+const ArticleEditorPage = lazy(() => import("./pages/ArticleEditorPage").then(m => ({ default: m.ArticleEditorPage })));
 const BadgesPage = lazy(() => import("./pages/BadgesPage").then(m => ({ default: m.BadgesPage })));
 const BlobbiPage = lazy(() => import("./pages/BlobbiPage").then(m => ({ default: m.BlobbiPage })));
 const BlueskyPage = lazy(() => import("./pages/BlueskyPage").then(m => ({ default: m.BlueskyPage })));
@@ -45,6 +51,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 +77,8 @@ 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 FollowPage = lazy(() => import("./pages/FollowPage").then(m => ({ default: m.FollowPage })));
+const RemoteLoginSuccessPage = lazy(() => import("./pages/RemoteLoginSuccessPage").then(m => ({ default: m.RemoteLoginSuccessPage })));
 
 const pollsDef = getExtraKindDef("polls")!;
 const colorsDef = getExtraKindDef("colors")!;
@@ -99,6 +108,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 +140,8 @@ export function AppRouter() {
   return (
     <AudioPlayerProvider>
       <BrowserRouter>
+        <Toaster />
+        <VersionCheck />
         <MinimizedAudioBar />
         <AudioNavigationGuard />
         <DeepLinkHandler />
@@ -121,6 +152,9 @@ export function AppRouter() {
           </Suspense>
         </BlobbiActionsProvider>
         <Routes>
+          {/* Auto-follow deep link: fullscreen immersive (no sidebars/nav) */}
+          <Route path="/follow/:npub" element={<FollowPage />} />
+
           {/* All routes share the persistent MainLayout (sidebar + nav) */}
           <Route element={<MainLayout />}>
             <Route path="/" element={<HomePage />} />
@@ -182,6 +216,8 @@ export function AppRouter() {
               }
             />
             <Route path="/webxdc" element={<WebxdcFeedPage />} />
+            <Route path="/articles/new" element={<ArticleEditorPage />} />
+            <Route path="/articles/edit/:naddr" element={<ArticleEditorPage />} />
             <Route
               path="/articles"
               element={
@@ -189,6 +225,7 @@ export function AppRouter() {
                   kind={articlesDef.kind}
                   title={articlesDef.label}
                   icon={sidebarItemIcon("articles", "size-5")}
+                  fabHref="/articles/new"
                 />
               }
             />
@@ -202,16 +239,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 +265,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 +278,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 */}

src/blobbi/actions/components/BlobbiActionInventoryModal.tsx

@@ -1,21 +1,18 @@
 // src/blobbi/actions/components/BlobbiActionInventoryModal.tsx
 
-import { useMemo, useState } from 'react';
-import { Loader2, ShoppingBag, Minus, Plus, X } from 'lucide-react';
+import { useMemo } from 'react';
+import { Loader2, X } from 'lucide-react';
 
 import {
   Dialog,
   DialogContent,
   DialogHeader,
   DialogTitle,
-  DialogFooter,
   DialogClose,
 } from '@/components/ui/dialog';
 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 {
@@ -37,8 +34,8 @@ interface BlobbiActionInventoryModalProps {
   action: InventoryAction;
   companion: BlobbiCompanion;
   profile: BlobbonautProfile | null;
-  /** Called when user confirms using item(s). Now accepts quantity. */
-  onUseItem: (itemId: string, quantity: number) => void;
+  /** Called when user taps Use on an item. Always uses once. */
+  onUseItem: (itemId: string) => void;
   onOpenShop: () => void;
   isUsingItem: boolean;
   usingItemId: string | null;
@@ -49,24 +46,19 @@ export function BlobbiActionInventoryModal({
   onOpenChange,
   action,
   companion,
-  profile,
+  profile: _profile,
   onUseItem,
-  onOpenShop,
+  onOpenShop: _onOpenShop,
   isUsingItem,
   usingItemId,
 }: BlobbiActionInventoryModalProps) {
   const actionMeta = ACTION_METADATA[action];
-  
-  // State for confirmation dialog
-  const [selectedItem, setSelectedItem] = useState<ResolvedInventoryItem | null>(null);
-  const [quantity, setQuantity] = useState(1);
-  const [showConfirmDialog, setShowConfirmDialog] = useState(false);
 
-  // Filter inventory by action type, respecting egg-compatible effects
+  // Get all available items for this action from the catalog (not inventory).
+  // Items are abilities/tools — no ownership required.
   const availableItems = useMemo(() => {
-    if (!profile) return [];
-    return filterInventoryByAction(profile.storage, action, { stage: companion.stage });
-  }, [profile, action, companion.stage]);
+    return filterInventoryByAction([], action, { stage: companion.stage });
+  }, [action, companion.stage]);
 
   // Check stage restrictions for this specific action
   const canUse = canUseAction(companion, action);
@@ -74,46 +66,9 @@ export function BlobbiActionInventoryModal({
 
   const isEmpty = availableItems.length === 0;
 
-  const handleSelectItem = (item: ResolvedInventoryItem) => {
+  const handleUseItem = (item: ResolvedInventoryItem) => {
     if (isUsingItem) return;
-    setSelectedItem(item);
-    setQuantity(1);
-    setShowConfirmDialog(true);
-  };
-
-  const handleConfirmUse = () => {
-    if (!selectedItem || isUsingItem) return;
-    onUseItem(selectedItem.itemId, quantity);
-    // Reset after starting use
-    setShowConfirmDialog(false);
-    setSelectedItem(null);
-    setQuantity(1);
-  };
-
-  const handleCloseConfirmDialog = (isOpen: boolean) => {
-    if (!isOpen) {
-      setShowConfirmDialog(false);
-      setSelectedItem(null);
-      setQuantity(1);
-    }
-  };
-
-  const handleOpenShop = () => {
-    onOpenChange(false);
-    onOpenShop();
-  };
-
-  // 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));
-  const handleQuantityInput = (e: React.ChangeEvent<HTMLInputElement>) => {
-    const value = parseInt(e.target.value, 10);
-    if (isNaN(value) || value < 1) {
-      setQuantity(1);
-    } else {
-      setQuantity(Math.min(value, maxQuantity));
-    }
+    onUseItem(item.itemId);
   };
 
   return (
@@ -161,14 +116,10 @@ export function BlobbiActionInventoryModal({
               <div className="size-16 rounded-2xl bg-muted/50 flex items-center justify-center mb-4">
                 <span className="text-3xl">{actionMeta.icon}</span>
               </div>
-              <h3 className="text-lg font-semibold mb-2">No Items</h3>
-              <p className="text-sm text-muted-foreground max-w-sm mb-4">
-                You don't have any items for this action. Visit the shop to get some!
+              <h3 className="text-lg font-semibold mb-2">No Items Available</h3>
+              <p className="text-sm text-muted-foreground max-w-sm">
+                No items are available for this action at your Blobbi's current stage.
               </p>
-              <Button onClick={handleOpenShop} className="gap-2">
-                <ShoppingBag className="size-4" />
-                Open Shop
-              </Button>
             </div>
           )}
 
@@ -181,7 +132,7 @@ export function BlobbiActionInventoryModal({
                   item={item}
                   companion={companion}
                   action={action}
-                  onUse={() => handleSelectItem(item)}
+                  onUse={() => handleUseItem(item)}
                   isUsing={isUsingItem && usingItemId === item.itemId}
                   disabled={isUsingItem}
                 />
@@ -190,24 +141,6 @@ export function BlobbiActionInventoryModal({
           )}
         </div>
       </DialogContent>
-
-      {/* Confirmation Dialog with Quantity Selector */}
-      {selectedItem && (
-        <BlobbiUseItemConfirmDialog
-          open={showConfirmDialog}
-          onOpenChange={handleCloseConfirmDialog}
-          item={selectedItem}
-          companion={companion}
-          action={action}
-          quantity={quantity}
-          maxQuantity={maxQuantity}
-          onIncrease={handleIncrease}
-          onDecrease={handleDecrease}
-          onQuantityChange={handleQuantityInput}
-          onConfirm={handleConfirmUse}
-          isUsing={isUsingItem}
-        />
-      )}
     </Dialog>
   );
 }
@@ -238,15 +171,12 @@ function BlobbiInventoryUseRow({
   // Preview stat changes - handle egg-specific preview for medicine and clean
   const { normalStatChanges, eggStatChanges } = useMemo(() => {
     if (isEgg && isMedicine) {
-      // For eggs using medicine, show health preview
-      // Eggs use the 3-stat model: health, hygiene, happiness
       return {
         normalStatChanges: [],
         eggStatChanges: previewMedicineForEgg(companion.stats.health, item.effect),
       };
     }
     if (isEgg && isClean) {
-      // For eggs using hygiene items, show hygiene (and possibly happiness) preview
       return {
         normalStatChanges: [],
         eggStatChanges: previewCleanForEgg(
@@ -255,7 +185,6 @@ function BlobbiInventoryUseRow({
         ),
       };
     }
-    // Normal stats preview
     return {
       normalStatChanges: previewStatChanges(companion.stats, item.effect),
       eggStatChanges: [] as EggStatPreview[],
@@ -280,16 +209,12 @@ function BlobbiInventoryUseRow({
         <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 shrink-0">
-              x{item.quantity}
-            </Badge>
           </div>
 
           {/* Effect Preview - shown inline on desktop */}
           <div className="hidden sm:block">
             {hasChanges && (
               <div className="flex flex-wrap gap-x-3 gap-y-1">
-                {/* Normal stat changes */}
                 {normalStatChanges.map(({ stat, delta }) => (
                   <span key={stat} className="text-xs">
                     <span
@@ -308,7 +233,6 @@ function BlobbiInventoryUseRow({
                     </span>
                   </span>
                 ))}
-                {/* Egg stat changes (health for medicine) */}
                 {eggStatChanges.map(({ stat, delta }) => (
                   <span key={stat} className="text-xs">
                     <span
@@ -350,7 +274,6 @@ function BlobbiInventoryUseRow({
       {/* Effect Preview - shown below on mobile */}
       {hasChanges && (
         <div className="sm:hidden flex flex-wrap gap-x-3 gap-y-1 pl-13">
-          {/* Normal stat changes */}
           {normalStatChanges.map(({ stat, delta }) => (
             <span key={stat} className="text-xs">
               <span
@@ -369,7 +292,6 @@ function BlobbiInventoryUseRow({
               </span>
             </span>
           ))}
-          {/* Egg stat changes (health for medicine) */}
           {eggStatChanges.map(({ stat, delta }) => (
             <span key={stat} className="text-xs">
               <span
@@ -393,222 +315,3 @@ function BlobbiInventoryUseRow({
     </div>
   );
 }
-
-// ─── Use Item Confirmation Dialog ─────────────────────────────────────────────
-
-interface BlobbiUseItemConfirmDialogProps {
-  open: boolean;
-  onOpenChange: (open: boolean) => void;
-  item: ResolvedInventoryItem;
-  companion: BlobbiCompanion;
-  action: InventoryAction;
-  quantity: number;
-  maxQuantity: number;
-  onIncrease: () => void;
-  onDecrease: () => void;
-  onQuantityChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
-  onConfirm: () => void;
-  isUsing: boolean;
-}
-
-function BlobbiUseItemConfirmDialog({
-  open,
-  onOpenChange,
-  item,
-  companion,
-  action,
-  quantity,
-  maxQuantity,
-  onIncrease,
-  onDecrease,
-  onQuantityChange,
-  onConfirm,
-  isUsing,
-}: BlobbiUseItemConfirmDialogProps) {
-  const actionMeta = ACTION_METADATA[action];
-  const isEgg = companion.stage === 'egg';
-  const isMedicine = action === 'medicine';
-  const isClean = action === 'clean';
-
-  // Preview stat changes for the selected quantity
-  const statPreview = useMemo(() => {
-    if (!item.effect) return { normalChanges: [], eggChanges: [] };
-
-    if (isEgg && isMedicine) {
-      // Calculate health change for N items
-      const healthDelta = item.effect.health ?? 0;
-      let currentHealth = companion.stats.health ?? 0;
-      for (let i = 0; i < quantity; i++) {
-        currentHealth = Math.max(0, Math.min(100, currentHealth + healthDelta));
-      }
-      const totalDelta = currentHealth - (companion.stats.health ?? 0);
-      return {
-        normalChanges: [],
-        eggChanges: totalDelta !== 0 ? [{ stat: 'health' as const, delta: totalDelta }] : [],
-      };
-    }
-
-    if (isEgg && isClean) {
-      // Calculate hygiene and happiness changes for N items
-      const hygieneDelta = item.effect.hygiene ?? 0;
-      const happinessDelta = item.effect.happiness ?? 0;
-      let currentHygiene = companion.stats.hygiene ?? 0;
-      let currentHappiness = companion.stats.happiness ?? 0;
-      for (let i = 0; i < quantity; i++) {
-        currentHygiene = Math.max(0, Math.min(100, currentHygiene + hygieneDelta));
-        currentHappiness = Math.max(0, Math.min(100, currentHappiness + happinessDelta));
-      }
-      const changes: Array<{ stat: 'health' | 'hygiene' | 'happiness'; delta: number }> = [];
-      const totalHygieneDelta = currentHygiene - (companion.stats.hygiene ?? 0);
-      const totalHappinessDelta = currentHappiness - (companion.stats.happiness ?? 0);
-      if (totalHygieneDelta !== 0) changes.push({ stat: 'hygiene', delta: totalHygieneDelta });
-      if (totalHappinessDelta !== 0) changes.push({ stat: 'happiness', delta: totalHappinessDelta });
-      return { normalChanges: [], eggChanges: changes };
-    }
-
-    // Normal stats preview - simulate N applications
-    const statKeys = ['hunger', 'happiness', 'energy', 'hygiene', 'health'] as const;
-    const currentStats = { ...companion.stats };
-    for (let i = 0; i < quantity; i++) {
-      for (const stat of statKeys) {
-        const delta = item.effect[stat];
-        if (delta !== undefined) {
-          currentStats[stat] = Math.max(0, Math.min(100, (currentStats[stat] ?? 0) + delta));
-        }
-      }
-    }
-    const changes: Array<{ stat: string; delta: number }> = [];
-    for (const stat of statKeys) {
-      const delta = (currentStats[stat] ?? 0) - (companion.stats[stat] ?? 0);
-      if (delta !== 0) {
-        changes.push({ stat, delta });
-      }
-    }
-    return { normalChanges: changes, eggChanges: [] };
-  }, [item.effect, companion.stats, quantity, isEgg, isMedicine, isClean]);
-
-  const hasChanges = statPreview.normalChanges.length > 0 || statPreview.eggChanges.length > 0;
-
-  return (
-    <Dialog open={open} onOpenChange={onOpenChange}>
-      <DialogContent className="max-w-sm w-[calc(100%-2rem)]">
-        <DialogHeader>
-          <DialogTitle>{actionMeta.label}</DialogTitle>
-        </DialogHeader>
-
-        <div className="space-y-4 py-2">
-          {/* Item Preview */}
-          <div className="flex items-center gap-3 sm:gap-4 p-3 sm:p-4 rounded-lg bg-muted/50">
-            <div className="text-3xl sm:text-4xl shrink-0">{item.icon}</div>
-            <div className="flex-1 min-w-0">
-              <h3 className="font-semibold truncate">{item.name}</h3>
-              <p className="text-sm text-muted-foreground">
-                {item.quantity} in inventory
-              </p>
-            </div>
-          </div>
-
-          {/* Quantity Selector */}
-          <div className="space-y-2">
-            <div className="flex items-center justify-between">
-              <label className="text-sm font-medium">Quantity</label>
-              <span className="text-xs text-muted-foreground">
-                Max: {maxQuantity}
-              </span>
-            </div>
-            <div className="flex items-center gap-2">
-              <Button
-                variant="outline"
-                size="icon"
-                onClick={onDecrease}
-                disabled={quantity <= 1 || isUsing}
-              >
-                <Minus className="size-4" />
-              </Button>
-              <Input
-                type="number"
-                min="1"
-                max={maxQuantity}
-                value={quantity}
-                onChange={onQuantityChange}
-                disabled={isUsing}
-                className="text-center"
-              />
-              <Button
-                variant="outline"
-                size="icon"
-                onClick={onIncrease}
-                disabled={quantity >= maxQuantity || isUsing}
-              >
-                <Plus className="size-4" />
-              </Button>
-            </div>
-          </div>
-
-          {/* Effects Summary */}
-          {hasChanges && (
-            <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">
-                Total effect{quantity > 1 ? ` (x${quantity})` : ''}
-              </h4>
-              <div className="flex flex-wrap gap-2">
-                {statPreview.normalChanges.map(({ stat, delta }) => (
-                  <Badge
-                    key={stat}
-                    variant="secondary"
-                    className={cn(
-                      'text-xs',
-                      delta > 0
-                        ? 'bg-green-500/20 text-green-700 dark:text-green-300'
-                        : 'bg-red-500/20 text-red-700 dark:text-red-300'
-                    )}
-                  >
-                    {delta > 0 ? '+' : ''}{delta} {stat}
-                  </Badge>
-                ))}
-                {statPreview.eggChanges.map(({ stat, delta }) => (
-                  <Badge
-                    key={stat}
-                    variant="secondary"
-                    className={cn(
-                      'text-xs',
-                      delta > 0
-                        ? 'bg-green-500/20 text-green-700 dark:text-green-300'
-                        : 'bg-red-500/20 text-red-700 dark:text-red-300'
-                    )}
-                  >
-                    {delta > 0 ? '+' : ''}{delta} {stat}
-                  </Badge>
-                ))}
-              </div>
-            </div>
-          )}
-        </div>
-
-        <DialogFooter>
-          <Button
-            variant="outline"
-            onClick={() => onOpenChange(false)}
-            disabled={isUsing}
-          >
-            Cancel
-          </Button>
-          <Button
-            onClick={onConfirm}
-            disabled={isUsing}
-            className="min-w-24"
-          >
-            {isUsing ? (
-              <>
-                <Loader2 className="size-4 mr-2 animate-spin" />
-                Using...
-              </>
-            ) : (
-              `Use${quantity > 1 ? ` (x${quantity})` : ''}`
-            )}
-          </Button>
-        </DialogFooter>
-      </DialogContent>
-    </Dialog>
-  );
-}

src/blobbi/actions/components/BlobbiActionsModal.tsx

@@ -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 {

src/blobbi/actions/components/BlobbiMissionsModal.tsx

@@ -1,19 +1,39 @@
 // src/blobbi/actions/components/BlobbiMissionsModal.tsx
 
 /**
- * Missions modal for Blobbi.
- * 
- * Shows:
- * - Daily missions (always visible, separate reward system)
- * - Incubation tasks when the current Blobbi is incubating (egg stage)
- * - Evolve tasks when evolving (baby stage)
+ * Missions modal for Blobbi — card-grid quest board.
+ *
+ * Layout:
+ * 1. Sticky header with title, subtitle, legend help button, close
+ * 2. Current Focus section (hatch / evolve) — collapsible, default open
+ * 3. Daily Bounties section — collapsible, default open
+ * 4. Settings row — low emphasis toggle (not collapsible)
+ *
+ * Both main sections use lightweight Radix Collapsible wrappers.
+ * Collapsed headers still show summary info (progress / coins).
  */
 
-import { Target, Loader2, XCircle, AlertTriangle, Calendar, Coins, X, ChevronDown } from 'lucide-react';
+import {
+  Loader2,
+  XCircle,
+  AlertTriangle,
+  Coins,
+  X,
+  Eye,
+  Scroll,
+  Compass,
+  HelpCircle,
+  ChevronDown,
+} from 'lucide-react';
 import { formatCompactNumber, cn } from '@/lib/utils';
 
 import { Button } from '@/components/ui/button';
-import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogClose } from '@/components/ui/dialog';
+import { Switch } from '@/components/ui/switch';
+import { Label } from '@/components/ui/label';
+import { Badge } from '@/components/ui/badge';
+import { Dialog, DialogContent, DialogClose } from '@/components/ui/dialog';
+import { Popover, PopoverContent, PopoverTrigger } from '@/components/ui/popover';
+import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '@/components/ui/collapsible';
 import {
   AlertDialog,
   AlertDialogAction,
@@ -24,10 +44,9 @@ import {
   AlertDialogHeader,
   AlertDialogTitle,
 } from '@/components/ui/alert-dialog';
-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';
@@ -42,36 +61,86 @@ import { useRerollMission } from '../hooks/useRerollMission';
 interface BlobbiMissionsModalProps {
   open: boolean;
   onOpenChange: (open: boolean) => void;
-  /** Current companion being viewed */
   companion: BlobbiCompanion;
-  /** Current Blobbonaut profile (required for coin updates) */
   profile: BlobbonautProfile | null;
-  /** Callback to update profile in query cache after claiming */
   updateProfileEvent: (event: NostrEvent) => void;
-  /** Hatch tasks result from useHatchTasks */
   hatchTasks: HatchTasksResult;
-  /** Evolve tasks result from useEvolveTasks */
   evolveTasks: EvolveTasksResult;
-  /** Called when user clicks "Create Post" action in tasks */
   onOpenPostModal: () => void;
-  /** Called when all hatch tasks are complete and user clicks "Hatch" */
   onHatch: () => void;
-  /** Whether hatching is in progress */
   isHatching: boolean;
-  /** Called when all evolve tasks are complete and user clicks "Evolve" */
   onEvolve: () => void;
-  /** Whether evolving is in progress */
   isEvolving: boolean;
-  /** Called when user confirms stopping incubation */
   onStopIncubation: () => Promise<void>;
-  /** Whether stop incubation is in progress */
   isStoppingIncubation: boolean;
-  /** Called when user confirms stopping evolution */
   onStopEvolution: () => Promise<void>;
-  /** Whether stop evolution is in progress */
   isStoppingEvolution: boolean;
-  /** Available Blobbi stages across all user's companions (for mission filtering) */
   availableStages?: ('egg' | 'baby' | 'adult')[];
+  showMissionCard?: boolean;
+  onToggleMissionCard?: (visible: boolean) => void;
+}
+
+// ─── Section Chevron ─────────────────────────────────────────────────────────
+
+function SectionChevron({ open }: { open: boolean }) {
+  return (
+    <ChevronDown
+      className={cn(
+        'size-4 text-muted-foreground/60 transition-transform duration-200',
+        open && 'rotate-180',
+      )}
+    />
+  );
+}
+
+// ─── Mission Type Legend ──────────────────────────────────────────────────────
+
+function MissionTypeLegend() {
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          className="rounded-full p-1.5 opacity-50 hover:opacity-100 hover:bg-muted transition-all"
+          aria-label="Mission types legend"
+        >
+          <HelpCircle className="size-4" />
+        </button>
+      </PopoverTrigger>
+      <PopoverContent side="bottom" align="end" className="w-56 p-3">
+        <p className="text-xs font-semibold mb-2">Mission Types</p>
+        <div className="space-y-2">
+          <div className="flex items-center gap-2">
+            <div className="size-5 rounded-full bg-amber-500/15 flex items-center justify-center shrink-0">
+              <Scroll className="size-3 text-amber-500" />
+            </div>
+            <div>
+              <p className="text-xs font-medium">Daily Bounty</p>
+              <p className="text-[10px] text-muted-foreground">Resets every day</p>
+            </div>
+          </div>
+          <div className="flex items-center gap-2">
+            <div className="size-5 rounded-full bg-sky-500/15 flex items-center justify-center shrink-0">
+              <span className="text-xs">🥚</span>
+            </div>
+            <div>
+              <p className="text-xs font-medium">Hatch Task</p>
+              <p className="text-[10px] text-muted-foreground">Egg progression</p>
+            </div>
+          </div>
+          <div className="flex items-center gap-2">
+            <div className="size-5 rounded-full bg-violet-500/15 flex items-center justify-center shrink-0">
+              <span className="text-xs">🐣</span>
+            </div>
+            <div>
+              <p className="text-xs font-medium">Evolve Task</p>
+              <p className="text-[10px] text-muted-foreground">Baby progression</p>
+            </div>
+          </div>
+        </div>
+      </PopoverContent>
+    </Popover>
+  );
 }
 
 // ─── Daily Missions Section ───────────────────────────────────────────────────
@@ -79,14 +148,20 @@ interface BlobbiMissionsModalProps {
 interface DailyMissionsSectionProps {
   profile: BlobbonautProfile | null;
   updateProfileEvent: (event: NostrEvent) => void;
-  /** Available Blobbi stages the user has */
   availableStages?: ('egg' | 'baby' | 'adult')[];
   disabled?: boolean;
   defaultOpen?: boolean;
 }
 
-function DailyMissionsSection({ profile, updateProfileEvent, availableStages, disabled, defaultOpen = true }: DailyMissionsSectionProps) {
+function DailyMissionsSection({
+  profile,
+  updateProfileEvent,
+  availableStages,
+  disabled,
+  defaultOpen = true,
+}: DailyMissionsSectionProps) {
   const [isOpen, setIsOpen] = useState(defaultOpen);
+
   const {
     missions,
     todayClaimedReward,
@@ -100,58 +175,56 @@ function DailyMissionsSection({ profile, updateProfileEvent, availableStages, di
 
   const { mutate: claimReward, isPending: isClaiming } = useClaimMissionReward(
     profile,
-    updateProfileEvent
+    updateProfileEvent,
   );
 
   const { mutate: rerollMission, isPending: isRerolling } = useRerollMission();
 
-  const handleClaimReward = (missionId: string) => {
-    claimReward({ missionId });
-  };
-
-  const handleRerollMission = (missionId: string) => {
-    rerollMission({ missionId, availableStages });
-  };
+  const claimableCount = missions.filter((m) => m.completed && !m.claimed).length;
 
   return (
-    <Collapsible open={isOpen} onOpenChange={setIsOpen} className="overflow-hidden">
-      {/* Section header - Clickable */}
+    <Collapsible open={isOpen} onOpenChange={setIsOpen}>
+      {/* Section header — tappable */}
       <CollapsibleTrigger className="w-full">
-        <div className="flex items-center justify-between gap-2 p-3 rounded-lg bg-muted/50 hover:bg-muted/70 transition-colors">
+        <div className="flex items-center justify-between py-1 group">
           <div className="flex items-center gap-2">
-            <Calendar className="size-4 text-primary shrink-0" />
-            <h3 className="font-semibold text-sm">Daily Missions</h3>
+            <Scroll className="size-4 text-amber-500 dark:text-amber-400 shrink-0" />
+            <h3 className="font-semibold text-sm">Daily Bounties</h3>
           </div>
           <div className="flex items-center gap-2">
-            <div className="flex items-center gap-1 text-xs text-muted-foreground">
-              <Coins className="size-3 shrink-0" />
-              <span className="whitespace-nowrap">
+            {/* Summary pill — always visible */}
+            <div className="flex items-center gap-1.5 text-xs text-muted-foreground">
+              <Coins className="size-3 shrink-0 text-amber-500 dark:text-amber-400" />
+              <span className="tabular-nums">
                 {formatCompactNumber(todayClaimedReward)} / {formatCompactNumber(totalPotentialReward)}
               </span>
+              {claimableCount > 0 && (
+                <span className="size-4 rounded-full bg-emerald-500 text-white text-[10px] font-bold flex items-center justify-center shrink-0">
+                  {claimableCount}
+                </span>
+              )}
             </div>
-            <ChevronDown className={cn(
-              "size-4 text-muted-foreground transition-transform duration-200",
-              isOpen && "rotate-180"
-            )} />
+            <SectionChevron open={isOpen} />
           </div>
         </div>
       </CollapsibleTrigger>
 
-      {/* Mission list */}
-      <CollapsibleContent className="pt-3">
-        <DailyMissionsPanel
-          missions={missions}
-          onClaimReward={handleClaimReward}
-          onRerollMission={handleRerollMission}
-          todayCoins={todayClaimedReward}
-          disabled={disabled || isClaiming || isRerolling}
-          bonusAvailable={bonusAvailable}
-          bonusClaimed={bonusClaimed}
-          bonusReward={bonusReward}
-          noMissionsAvailable={noMissionsAvailable}
-          rerollsRemaining={rerollsRemaining}
-          isRerolling={isRerolling}
-        />
+      <CollapsibleContent className="overflow-hidden data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up">
+        <div className="pt-3">
+          <DailyMissionsPanel
+            missions={missions}
+            onClaimReward={(id) => claimReward({ missionId: id })}
+            onRerollMission={(id) => rerollMission({ missionId: id, availableStages })}
+            todayCoins={todayClaimedReward}
+            disabled={disabled || isClaiming || isRerolling}
+            bonusAvailable={bonusAvailable}
+            bonusClaimed={bonusClaimed}
+            bonusReward={bonusReward}
+            noMissionsAvailable={noMissionsAvailable}
+            rerollsRemaining={rerollsRemaining}
+            isRerolling={isRerolling}
+          />
+        </div>
       </CollapsibleContent>
     </Collapsible>
   );
@@ -224,9 +297,9 @@ function StopConfirmationDialog({
   );
 }
 
-// ─── Process Content (Incubation or Evolution) ────────────────────────────────
+// ─── Current Focus Section (Hatch / Evolve) ──────────────────────────────────
 
-interface ProcessContentProps {
+interface CurrentFocusSectionProps {
   companion: BlobbiCompanion;
   tasks: HatchTasksResult | EvolveTasksResult;
   processType: 'incubation' | 'evolution';
@@ -238,7 +311,7 @@ interface ProcessContentProps {
   defaultOpen?: boolean;
 }
 
-function ProcessContent({
+function CurrentFocusSection({
   companion,
   tasks,
   processType,
@@ -248,93 +321,98 @@ function ProcessContent({
   onStop,
   isStopping,
   defaultOpen = true,
-}: ProcessContentProps) {
+}: CurrentFocusSectionProps) {
   const [isOpen, setIsOpen] = useState(defaultOpen);
   const [showStopConfirmation, setShowStopConfirmation] = useState(false);
 
   const isIncubation = processType === 'incubation';
-  const emoji = isIncubation ? '🥚' : '🐣';
   const title = isIncubation ? 'Hatch Tasks' : 'Evolve Tasks';
-  const description = isIncubation
-    ? 'Complete these tasks to hatch your Blobbi'
-    : 'Complete these tasks to evolve your Blobbi';
   const completeLabel = isIncubation ? 'Hatch Your Blobbi!' : 'Evolve Your Blobbi!';
   const completingLabel = isIncubation ? 'Hatching...' : 'Evolving...';
   const completeEmoji = isIncubation ? '🐣' : '✨';
   const stopLabel = isIncubation ? 'Stop Incubation' : 'Stop Evolution';
+  const badgeLabel = isIncubation ? 'Hatch' : 'Evolve';
+  const category = isIncubation ? ('hatch' as const) : ('evolve' as const);
 
-  const completedCount = tasks.tasks.filter(t => t.completed).length;
+  const completedCount = tasks.tasks.filter((t) => t.completed).length;
   const totalTasks = tasks.tasks.length;
 
   return (
-    <Collapsible open={isOpen} onOpenChange={setIsOpen} className="overflow-hidden">
-      {/* Section header - Clickable */}
+    <Collapsible open={isOpen} onOpenChange={setIsOpen}>
+      {/* Section header — tappable */}
       <CollapsibleTrigger className="w-full">
-        <div className="flex items-center justify-between gap-2 p-3 rounded-lg bg-muted/50 hover:bg-muted/70 transition-colors">
+        <div className="flex items-center justify-between py-1 group">
           <div className="flex items-center gap-2">
-            <span className="text-lg">{emoji}</span>
-            <h3 className="font-semibold text-sm">{title}</h3>
+            <Badge
+              variant="secondary"
+              className={cn(
+                'text-xs font-semibold px-2 py-0.5',
+                isIncubation
+                  ? 'bg-sky-500/15 text-sky-600 dark:text-sky-400'
+                  : 'bg-violet-500/15 text-violet-600 dark:text-violet-400',
+              )}
+            >
+              {badgeLabel}
+            </Badge>
+            <span className="text-sm font-semibold">{title}</span>
           </div>
           <div className="flex items-center gap-2">
-            <span className={cn(
-              "text-xs font-medium px-2 py-0.5 rounded-full",
-              tasks.allCompleted 
-                ? "bg-emerald-500/20 text-emerald-600 dark:text-emerald-400"
-                : "bg-muted text-muted-foreground"
-            )}>
-              {completedCount}/{totalTasks}
+            <span
+              className={cn(
+                'text-xs font-medium tabular-nums',
+                tasks.allCompleted
+                  ? 'text-emerald-600 dark:text-emerald-400'
+                  : 'text-muted-foreground',
+              )}
+            >
+              {completedCount} / {totalTasks}
             </span>
-            <ChevronDown className={cn(
-              "size-4 text-muted-foreground transition-transform duration-200",
-              isOpen && "rotate-180"
-            )} />
+            <SectionChevron open={isOpen} />
           </div>
         </div>
       </CollapsibleTrigger>
 
-      {/* Tasks content */}
-      <CollapsibleContent className="pt-3">
-        {/* Tasks Panel */}
-        <TasksPanel
-          tasks={tasks.tasks}
-          allCompleted={tasks.allCompleted}
-          isLoading={tasks.isLoading}
-          onOpenPostModal={onOpenPostModal}
-          onComplete={onComplete}
-          isCompleting={isCompleting}
-          emoji={emoji}
-          title={title}
-          description={description}
-          completeLabel={completeLabel}
-          completingLabel={completingLabel}
-          completeEmoji={completeEmoji}
-        />
+      <CollapsibleContent className="overflow-hidden data-[state=open]:animate-collapsible-down data-[state=closed]:animate-collapsible-up">
+        <div className="pt-3">
+          {/* Task card grid */}
+          <TasksPanel
+            tasks={tasks.tasks}
+            allCompleted={tasks.allCompleted}
+            isLoading={tasks.isLoading}
+            onOpenPostModal={onOpenPostModal}
+            onComplete={onComplete}
+            isCompleting={isCompleting}
+            completeLabel={completeLabel}
+            completingLabel={completingLabel}
+            completeEmoji={completeEmoji}
+            category={category}
+          />
 
-        {/* Stop Process Button */}
-        <div className="mt-6 pt-4 border-t border-border">
-          <Button
-            variant="ghost"
-            size="sm"
-            onClick={() => setShowStopConfirmation(true)}
-            disabled={isStopping || isCompleting}
-            className="w-full text-muted-foreground hover:text-destructive hover:bg-destructive/10"
-          >
-            {isStopping ? (
-              <>
-                <Loader2 className="size-4 mr-2 animate-spin" />
-                Stopping...
-              </>
-            ) : (
-              <>
-                <XCircle className="size-4 mr-2" />
-                {stopLabel}
-              </>
-            )}
-          </Button>
+          {/* Stop process — low emphasis */}
+          <div className="mt-3 flex justify-center">
+            <Button
+              variant="ghost"
+              size="sm"
+              onClick={() => setShowStopConfirmation(true)}
+              disabled={isStopping || isCompleting}
+              className="text-xs text-muted-foreground hover:text-destructive hover:bg-destructive/10 h-8 px-3"
+            >
+              {isStopping ? (
+                <>
+                  <Loader2 className="size-3.5 mr-1.5 animate-spin" />
+                  Stopping...
+                </>
+              ) : (
+                <>
+                  <XCircle className="size-3.5 mr-1.5" />
+                  {stopLabel}
+                </>
+              )}
+            </Button>
+          </div>
         </div>
       </CollapsibleContent>
 
-      {/* Stop Confirmation Dialog */}
       <StopConfirmationDialog
         open={showStopConfirmation}
         onOpenChange={setShowStopConfirmation}
@@ -347,6 +425,17 @@ function ProcessContent({
   );
 }
 
+// ─── Empty Focus State ────────────────────────────────────────────────────────
+
+function EmptyFocusState() {
+  return (
+    <div className="py-6 text-center">
+      <Compass className="size-5 text-muted-foreground/50 mx-auto mb-2" />
+      <p className="text-sm text-muted-foreground">No active progression right now</p>
+    </div>
+  );
+}
+
 // ─── Main Modal ───────────────────────────────────────────────────────────────
 
 export function BlobbiMissionsModal({
@@ -367,54 +456,46 @@ export function BlobbiMissionsModal({
   onStopEvolution,
   isStoppingEvolution,
   availableStages,
+  showMissionCard,
+  onToggleMissionCard,
 }: BlobbiMissionsModalProps) {
   const isIncubating = companion.state === 'incubating';
   const isEvolvingState = companion.state === 'evolving';
   const isEgg = companion.stage === 'egg';
   const isBaby = companion.stage === 'baby';
 
-  // Check if there's an active hatch/evolve process
   const hasActiveProcess = (isIncubating && isEgg) || (isEvolvingState && isBaby);
   const isProcessBusy = isHatching || isEvolving || isStoppingIncubation || isStoppingEvolution;
 
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent className="max-w-lg w-[calc(100%-2rem)] max-h-[85vh] flex flex-col p-0 gap-0 overflow-hidden [&>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-4">
-            <div>
-              <DialogTitle className="flex items-center gap-2">
-                <Target className="size-5 shrink-0" />
-                Missions
-              </DialogTitle>
-              <DialogDescription className="break-words">
-                Complete missions to earn rewards for {companion.name}
-              </DialogDescription>
+        {/* ── Sticky Header ── */}
+        <div className="sticky top-0 z-10 bg-background px-4 sm:px-5 pt-4 pb-3 border-b border-border/60">
+          <div className="flex items-center justify-between">
+            <div className="min-w-0">
+              <h2 className="text-base font-bold tracking-tight">Missions</h2>
+              <p className="text-xs text-muted-foreground mt-0.5">
+                Quests & bounties for {companion.name}
+              </p>
+            </div>
+            <div className="flex items-center gap-0.5 shrink-0">
+              <MissionTypeLegend />
+              <DialogClose className="rounded-full p-1.5 opacity-60 hover:opacity-100 hover:bg-muted transition-all">
+                <X className="size-4" />
+                <span className="sr-only">Close</span>
+              </DialogClose>
             </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>
+        </div>
 
-        {/* Content - Scrollable */}
-        <div className="flex-1 min-h-0 overflow-y-auto overflow-x-hidden px-4 sm:px-6 py-3 sm:py-4 space-y-4">
-          {/* Daily Missions Section - Always visible, expanded by default */}
-          <DailyMissionsSection 
-            profile={profile}
-            updateProfileEvent={updateProfileEvent}
-            availableStages={availableStages}
-            disabled={isProcessBusy}
-            defaultOpen={true}
-          />
-
-          {/* Hatch/Evolve Process Section - Only when active, expanded by default */}
-          {hasActiveProcess && (
+        {/* ── Scrollable Content ── */}
+        <div className="flex-1 min-h-0 overflow-y-auto overflow-x-hidden px-4 sm:px-5 py-4 space-y-5">
+          {/* 1. Current Focus */}
+          {hasActiveProcess ? (
             <>
               {isIncubating && isEgg ? (
-                <ProcessContent
+                <CurrentFocusSection
                   companion={companion}
                   tasks={hatchTasks}
                   processType="incubation"
@@ -423,10 +504,9 @@ export function BlobbiMissionsModal({
                   isCompleting={isHatching}
                   onStop={onStopIncubation}
                   isStopping={isStoppingIncubation}
-                  defaultOpen={true}
                 />
               ) : isEvolvingState && isBaby ? (
-                <ProcessContent
+                <CurrentFocusSection
                   companion={companion}
                   tasks={evolveTasks}
                   processType="evolution"
@@ -435,10 +515,43 @@ export function BlobbiMissionsModal({
                   isCompleting={isEvolving}
                   onStop={onStopEvolution}
                   isStopping={isStoppingEvolution}
-                  defaultOpen={true}
                 />
               ) : null}
             </>
+          ) : (
+            <EmptyFocusState />
+          )}
+
+          {/* Divider */}
+          <div className="h-px bg-border/60" />
+
+          {/* 2. Daily Bounties */}
+          <DailyMissionsSection
+            profile={profile}
+            updateProfileEvent={updateProfileEvent}
+            availableStages={availableStages}
+            disabled={isProcessBusy}
+          />
+
+          {/* 3. Settings */}
+          {onToggleMissionCard !== undefined && showMissionCard !== undefined && (
+            <>
+              <div className="h-px bg-border/40" />
+              <div className="flex items-center justify-between py-1">
+                <Label
+                  htmlFor="mission-card-toggle"
+                  className="flex items-center gap-2 text-xs text-muted-foreground cursor-pointer"
+                >
+                  <Eye className="size-3.5" />
+                  Show mission card on main page
+                </Label>
+                <Switch
+                  id="mission-card-toggle"
+                  checked={showMissionCard}
+                  onCheckedChange={onToggleMissionCard}
+                />
+              </div>
+            </>
           )}
         </div>
       </DialogContent>

src/blobbi/actions/components/BlobbiPostModal.tsx

@@ -30,6 +30,7 @@ import { toast } from '@/hooks/useToast';
 
 import {
   BLOBBI_POST_REQUIRED_HASHTAGS,
+  buildHatchPhrase,
 } from '../hooks/useHatchTasks';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
@@ -49,33 +50,13 @@ interface BlobbiPostModalProps {
 
 // ─── Helpers ──────────────────────────────────────────────────────────────────
 
-/**
- * Sanitize a name into a valid hashtag format.
- * - Removes special characters
- * - Replaces spaces with nothing (camelCase-like)
- * - Ensures lowercase
- * - Handles edge cases
- */
-function sanitizeToHashtag(name: string): string {
-  return name
-    .toLowerCase()
-    // Remove emojis and special characters, keep letters, numbers, underscores
-    .replace(/[^\p{L}\p{N}_]/gu, '')
-    // Ensure it starts with a letter (prepend 'blobbi' if it starts with number)
-    .replace(/^(\d)/, 'blobbi$1')
-    // Limit length
-    .slice(0, 30)
-    // Fallback if empty
-    || 'myblobbi';
-}
-
 /**
  * Build the required prefix text based on process type.
  */
 function buildPrefix(process: BlobbiPostProcess): string {
   return process === 'evolve'
-    ? 'Hello Nostr! Posting to evolve'
-    : 'Hello Nostr! Posting to hatch';
+    ? 'Posting to evolve'
+    : 'Posting to hatch';
 }
 
 // ─── Main Component ───────────────────────────────────────────────────────────
@@ -91,20 +72,19 @@ export function BlobbiPostModal({
   const { mutateAsync: createEvent, isPending } = useNostrPublish();
   
   // Compute the required elements based on props
-  const blobbiHashtag = useMemo(() => sanitizeToHashtag(blobbiName), [blobbiName]);
   const prefix = useMemo(() => buildPrefix(process), [process]);
+  const capitalizedName = useMemo(() => blobbiName.charAt(0).toUpperCase() + blobbiName.slice(1), [blobbiName]);
   
-  // All required hashtags including the Blobbi name (first)
-  const allRequiredHashtags = useMemo(() => 
-    [blobbiHashtag, ...BLOBBI_POST_REQUIRED_HASHTAGS],
-    [blobbiHashtag]
+  // The required phrase that must appear in the post
+  const requiredPhrase = useMemo(() => 
+    process === 'hatch'
+      ? buildHatchPhrase(blobbiName)
+      : `${prefix} ${capitalizedName} #blobbi`,
+    [process, blobbiName, prefix, capitalizedName]
   );
   
-  // Build default content
-  const defaultContent = useMemo(() => 
-    `${prefix} #${allRequiredHashtags.join(' #')}`,
-    [prefix, allRequiredHashtags]
-  );
+  // Build default content (the phrase itself is enough)
+  const defaultContent = useMemo(() => requiredPhrase, [requiredPhrase]);
   
   const [content, setContent] = useState(defaultContent);
   const [validationError, setValidationError] = useState<string | null>(null);
@@ -118,24 +98,14 @@ export function BlobbiPostModal({
   }, [open, defaultContent]);
   
   /**
-   * Validate that the content still contains the required prefix and hashtags.
+   * Validate that the content contains the required phrase.
    */
   const validateContent = useCallback((text: string): string | null => {
-    // Check prefix
-    if (!text.startsWith(prefix)) {
-      return 'The post must start with the required text';
+    if (!text.includes(requiredPhrase)) {
+      return `The post must contain: "${requiredPhrase}"`;
     }
-    
-    // Check all required hashtags are present (including Blobbi name)
-    const lowerText = text.toLowerCase();
-    for (const tag of allRequiredHashtags) {
-      if (!lowerText.includes(`#${tag.toLowerCase()}`)) {
-        return `Missing required hashtag: #${tag}`;
-      }
-    }
-    
     return null;
-  }, [prefix, allRequiredHashtags]);
+  }, [requiredPhrase]);
   
   /**
    * Handle content change with validation.
@@ -180,21 +150,26 @@ export function BlobbiPostModal({
     }
     
     try {
-      // Build tags for the post
+      // Build tags for the post: extract all hashtags from content
       const tags: string[][] = [];
+      const seen = new Set<string>();
       
-      // Add all required hashtags as 't' tags
-      for (const hashtag of allRequiredHashtags) {
-        tags.push(['t', hashtag.toLowerCase()]);
+      // Always include BLOBBI_POST_REQUIRED_HASHTAGS as t tags
+      for (const hashtag of BLOBBI_POST_REQUIRED_HASHTAGS) {
+        const lower = hashtag.toLowerCase();
+        if (!seen.has(lower)) {
+          tags.push(['t', lower]);
+          seen.add(lower);
+        }
       }
       
-      // Extract any additional hashtags the user added
-      const additionalHashtags = content.match(/#(\w+)/g) || [];
-      const requiredLower = allRequiredHashtags.map(t => t.toLowerCase());
-      for (const tag of additionalHashtags) {
+      // Extract any additional hashtags from the content
+      const contentHashtags = content.match(/#(\w+)/g) || [];
+      for (const tag of contentHashtags) {
         const tagValue = tag.slice(1).toLowerCase();
-        if (!requiredLower.includes(tagValue)) {
+        if (!seen.has(tagValue)) {
           tags.push(['t', tagValue]);
+          seen.add(tagValue);
         }
       }
       
@@ -220,7 +195,7 @@ export function BlobbiPostModal({
         variant: 'destructive',
       });
     }
-  }, [user, content, validateContent, createEvent, onOpenChange, onSuccess, allRequiredHashtags, process]);
+  }, [user, content, validateContent, createEvent, onOpenChange, onSuccess, process]);
   
   const canPost = !validationError && content.trim().length > 0;
   
@@ -282,13 +257,9 @@ export function BlobbiPostModal({
           
           {/* Preview of required content */}
           <div className="p-3 rounded-lg bg-muted/50 border border-dashed">
-            <p className="text-xs text-muted-foreground mb-1">Required content:</p>
-            <p className="text-sm font-medium">
-              <span className="text-primary">{prefix}</span>
-              {' '}
-              {allRequiredHashtags.map(tag => (
-                <span key={tag} className="text-blue-500">#{tag} </span>
-              ))}
+            <p className="text-xs text-muted-foreground mb-1">Required phrase:</p>
+            <p className="text-sm font-medium text-primary">
+              {requiredPhrase}
             </p>
           </div>
         </div>

src/blobbi/actions/components/DailyMissionsPanel.tsx

@@ -1,285 +1,164 @@
 /**
- * DailyMissionsPanel - UI component for displaying daily missions
- * 
- * Shows:
- * - Daily mission list with progress bars
- * - Completion state
- * - Claim buttons for completed missions
- * - Coin rewards
- * - Bonus mission after completing all regular missions
- * - Empty state when no missions available (egg-only users)
- * - Reroll button to replace missions (max 3/day)
+ * DailyMissionsPanel — card-grid layout for daily bounties.
+ *
+ * Each mission is a compact card in a 2-col grid.
+ * Tapping a card expands it to show progress, claim button, and reroll.
+ * Only one card expanded at a time.
  */
 
-import { Check, Coins, Gift, Sparkles, Egg, Trophy, RefreshCw } from 'lucide-react';
+import { useState } from 'react';
+import {
+  Check,
+  Coins,
+  Gift,
+  Sparkles,
+  Egg,
+  Trophy,
+  RefreshCw,
+  Heart,
+  Utensils,
+  Droplets,
+  Moon,
+  Camera,
+  Mic,
+  Music,
+  Pill,
+  CircleDot,
+} from 'lucide-react';
 
 import { Button } from '@/components/ui/button';
-import { Progress } from '@/components/ui/progress';
 import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
 import { cn, formatCompactNumber } from '@/lib/utils';
-import type { DailyMission } from '../lib/daily-missions';
+import type { DailyMission, DailyMissionAction } from '../lib/daily-missions';
 import { BONUS_MISSION_ID } from '../hooks/useClaimMissionReward';
+import {
+  ExpandableMissionCard,
+  MissionDescription,
+  MissionProgress,
+} from './ExpandableMissionCard';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
 interface DailyMissionsPanelProps {
-  /** The daily missions to display */
   missions: DailyMission[];
-  /** Callback when claiming a mission reward */
   onClaimReward: (missionId: string) => void;
-  /** Callback when rerolling a mission */
   onRerollMission?: (missionId: string) => void;
-  /** Total coins earned today */
   todayCoins: number;
-  /** Whether claiming is disabled (e.g., during another operation) */
   disabled?: boolean;
-  /** Whether the bonus mission is available */
   bonusAvailable?: boolean;
-  /** Whether the bonus mission has been claimed */
   bonusClaimed?: boolean;
-  /** Bonus mission reward amount */
   bonusReward?: number;
-  /** Whether user has no eligible missions (e.g., only eggs) */
   noMissionsAvailable?: boolean;
-  /** Number of rerolls remaining today */
   rerollsRemaining?: number;
-  /** Whether a reroll is currently in progress */
   isRerolling?: boolean;
 }
 
-// ─── Mission Item ─────────────────────────────────────────────────────────────
+// ─── Daily Mission Icon Mapping ───────────────────────────────────────────────
 
-interface MissionItemProps {
-  mission: DailyMission;
-  onClaim: () => void;
-  onReroll?: () => void;
-  disabled?: boolean;
-  canReroll?: boolean;
-  isRerolling?: boolean;
+function DailyMissionIcon({ action }: { action: DailyMissionAction }) {
+  const cls = 'size-5';
+  switch (action) {
+    case 'interact':
+      return <Heart className={cls} />;
+    case 'feed':
+      return <Utensils className={cls} />;
+    case 'clean':
+      return <Droplets className={cls} />;
+    case 'sleep':
+      return <Moon className={cls} />;
+    case 'take_photo':
+      return <Camera className={cls} />;
+    case 'sing':
+      return <Mic className={cls} />;
+    case 'play_music':
+      return <Music className={cls} />;
+    case 'medicine':
+      return <Pill className={cls} />;
+    default:
+      return <CircleDot className={cls} />;
+  }
 }
 
-function MissionItem({ mission, onClaim, onReroll, disabled, canReroll = false, isRerolling = false }: MissionItemProps) {
-  const progressPercent = (mission.currentCount / mission.requiredCount) * 100;
-  const canClaim = mission.completed && !mission.claimed;
-  
-  // Can only reroll if: not completed, not claimed, has reroll callback, and has rerolls remaining
-  const showRerollButton = onReroll && !mission.completed && !mission.claimed && canReroll;
+// ─── Bonus Card ───────────────────────────────────────────────────────────────
 
-  return (
-    <div
-      className={cn(
-        'relative p-3 sm:p-4 rounded-lg border transition-colors overflow-hidden',
-        mission.claimed
-          ? 'bg-primary/5 border-primary/20'
-          : mission.completed
-            ? 'bg-green-500/5 border-green-500/30'
-            : 'bg-card border-border'
-      )}
-    >
-      {/* Top right area: Claimed badge OR Reroll button */}
-      <div className="absolute top-2 right-2">
-        {mission.claimed ? (
-          <div className="flex items-center gap-1 text-xs text-primary font-medium">
-            <Check className="size-3" />
-            Claimed
-          </div>
-        ) : showRerollButton ? (
-          <TooltipProvider>
-            <Tooltip>
-              <TooltipTrigger asChild>
-                <Button
-                  variant="ghost"
-                  size="icon"
-                  className="size-7 text-muted-foreground hover:text-foreground"
-                  onClick={onReroll}
-                  disabled={disabled || isRerolling}
-                >
-                  <RefreshCw className={cn("size-3.5", isRerolling && "animate-spin")} />
-                </Button>
-              </TooltipTrigger>
-              <TooltipContent side="left">
-                <p>Replace this mission</p>
-              </TooltipContent>
-            </Tooltip>
-          </TooltipProvider>
-        ) : null}
-      </div>
-
-      {/* Mission content */}
-      <div className="space-y-2 sm:space-y-3">
-        {/* Title and description */}
-        <div className="pr-14 sm:pr-16">
-          <h4 className="font-medium text-sm break-words">{mission.title}</h4>
-          <p className="text-xs text-muted-foreground mt-0.5 break-words">
-            {mission.description}
-          </p>
-        </div>
-
-        {/* Progress bar */}
-        <div className="space-y-1.5">
-          <div className="flex items-center justify-between text-xs gap-2">
-            <span className="text-muted-foreground whitespace-nowrap">
-              {mission.currentCount} / {mission.requiredCount}
-            </span>
-            <span className="flex items-center gap-1 font-medium text-amber-600 dark:text-amber-400 whitespace-nowrap">
-              <Coins className="size-3 shrink-0" />
-              {formatCompactNumber(mission.reward)}
-            </span>
-          </div>
-          <Progress
-            value={progressPercent}
-            className={cn(
-              'h-2',
-              mission.completed && '[&>div]:bg-green-500'
-            )}
-          />
-        </div>
-
-        {/* Claim button */}
-        {canClaim && (
-          <Button
-            size="sm"
-            onClick={onClaim}
-            disabled={disabled}
-            className="w-full bg-green-600 hover:bg-green-700 text-white"
-          >
-            <Gift className="size-4 mr-2 shrink-0" />
-            <span className="truncate">Claim {formatCompactNumber(mission.reward)} Coins</span>
-          </Button>
-        )}
-      </div>
-    </div>
-  );
-}
-
-// ─── Bonus Mission Item ───────────────────────────────────────────────────────
-
-interface BonusMissionItemProps {
+interface BonusCardProps {
   isAvailable: boolean;
   isClaimed: boolean;
   reward: number;
   onClaim: () => void;
   disabled?: boolean;
+  isExpanded: boolean;
+  onToggle: (id: string) => void;
 }
 
-function BonusMissionItem({ isAvailable, isClaimed, reward, onClaim, disabled }: BonusMissionItemProps) {
+function BonusCard({ isAvailable, isClaimed, reward, onClaim, disabled, isExpanded, onToggle }: BonusCardProps) {
+  const progress = isClaimed ? 1 : isAvailable ? 1 : 0;
+
   return (
-    <div
-      className={cn(
-        'relative p-3 sm:p-4 rounded-lg border-2 transition-colors overflow-hidden',
-        isClaimed
-          ? 'bg-amber-500/10 border-amber-500/30'
-          : isAvailable
-            ? 'bg-gradient-to-br from-amber-500/10 to-orange-500/10 border-amber-500/40 animate-pulse'
-            : 'bg-muted/30 border-dashed border-muted-foreground/20'
-      )}
+    <ExpandableMissionCard
+      id="bonus"
+      category="daily"
+      icon={<Trophy className="size-5" />}
+      title="Daily Champion"
+      completed={isClaimed}
+      progress={progress}
+      isExpanded={isExpanded}
+      onToggle={onToggle}
     >
-      {/* Claimed badge */}
-      {isClaimed && (
-        <div className="absolute top-2 right-2">
-          <div className="flex items-center gap-1 text-xs text-amber-600 dark:text-amber-400 font-medium">
-            <Check className="size-3" />
-            Claimed
-          </div>
-        </div>
-      )}
+      <MissionDescription>
+        {isAvailable || isClaimed
+          ? 'Bonus reward for completing all daily missions!'
+          : 'Complete all missions to unlock this bonus'}
+      </MissionDescription>
 
-      {/* Mission content */}
-      <div className="space-y-2 sm:space-y-3">
-        {/* Title and description */}
-        <div className={cn("pr-14 sm:pr-16", !isAvailable && !isClaimed && "opacity-50")}>
-          <div className="flex items-center gap-2">
-            <Trophy className={cn(
-              "size-4 shrink-0",
-              isClaimed 
-                ? "text-amber-600 dark:text-amber-400"
-                : isAvailable 
-                  ? "text-amber-500" 
-                  : "text-muted-foreground"
-            )} />
-            <h4 className="font-medium text-sm">Daily Champion</h4>
-          </div>
-          <p className="text-xs text-muted-foreground mt-0.5">
-            {isAvailable || isClaimed 
-              ? 'Bonus reward for completing all daily missions!'
-              : 'Complete all missions above to unlock this bonus'}
-          </p>
-        </div>
-
-        {/* Reward display */}
-        <div className="flex items-center justify-between text-xs gap-2">
-          <span className={cn(
-            "text-muted-foreground",
-            !isAvailable && !isClaimed && "opacity-50"
-          )}>
-            Bonus Reward
-          </span>
-          <span className={cn(
-            "flex items-center gap-1 font-medium",
-            isClaimed || isAvailable 
-              ? "text-amber-600 dark:text-amber-400" 
-              : "text-muted-foreground"
-          )}>
-            <Coins className="size-3 shrink-0" />
-            +{formatCompactNumber(reward)}
-          </span>
-        </div>
-
-        {/* Claim button */}
-        {isAvailable && !isClaimed && (
-          <Button
-            size="sm"
-            onClick={onClaim}
-            disabled={disabled}
-            className="w-full bg-gradient-to-r from-amber-500 to-orange-500 hover:from-amber-600 hover:to-orange-600 text-white"
-          >
-            <Trophy className="size-4 mr-2 shrink-0" />
-            <span className="truncate">Claim Bonus {formatCompactNumber(reward)} Coins!</span>
-          </Button>
-        )}
+      <div className="flex items-center gap-1 text-xs font-medium text-amber-600 dark:text-amber-400">
+        <Coins className="size-3" />
+        +{formatCompactNumber(reward)}
       </div>
-    </div>
+
+      {isAvailable && !isClaimed && (
+        <Button
+          size="sm"
+          onClick={onClaim}
+          disabled={disabled}
+          className="w-full bg-gradient-to-r from-amber-500 to-orange-500 hover:from-amber-600 hover:to-orange-600 text-white h-8 text-xs"
+        >
+          <Trophy className="size-3.5 mr-1.5" />
+          Claim Bonus {formatCompactNumber(reward)} Coins
+        </Button>
+      )}
+    </ExpandableMissionCard>
   );
 }
 
-// ─── No Missions Available State ──────────────────────────────────────────────
+// ─── Empty / Done States ──────────────────────────────────────────────────────
 
 function NoMissionsState() {
   return (
-    <div className="flex flex-col items-center gap-3 py-6 text-center">
-      <div className="size-12 rounded-full bg-muted flex items-center justify-center">
-        <Egg className="size-6 text-muted-foreground" />
-      </div>
-      <div className="space-y-1">
-        <h4 className="font-semibold text-sm">Hatch Your Blobbi First</h4>
-        <p className="text-xs text-muted-foreground">
-          Daily missions will be available once you have
-          <br />
-          a hatched Blobbi to interact with!
+    <div className="flex flex-col items-center gap-2 py-6 text-center">
+      <Egg className="size-5 text-muted-foreground/50" />
+      <div>
+        <p className="text-sm font-medium">Hatch your Blobbi first</p>
+        <p className="text-xs text-muted-foreground mt-0.5">
+          Daily missions unlock after hatching
         </p>
       </div>
     </div>
   );
 }
 
-// ─── All Claimed State ────────────────────────────────────────────────────────
-
-interface AllClaimedStateProps {
-  todayCoins: number;
-}
-
-function AllClaimedState({ todayCoins }: AllClaimedStateProps) {
+function AllClaimedState({ todayCoins }: { todayCoins: number }) {
   return (
-    <div className="flex flex-col items-center gap-3 py-6 text-center">
-      <div className="size-12 rounded-full bg-primary/10 flex items-center justify-center">
-        <Sparkles className="size-6 text-primary" />
-      </div>
-      <div className="space-y-1">
-        <h4 className="font-semibold text-sm">All Done for Today!</h4>
-        <p className="text-xs text-muted-foreground">
-          You earned <span className="font-medium text-amber-600 dark:text-amber-400">{formatCompactNumber(todayCoins)} coins</span> today.
-          <br />
-          Come back tomorrow for new missions!
+    <div className="flex flex-col items-center gap-2 py-6 text-center">
+      <Sparkles className="size-5 text-primary/60" />
+      <div>
+        <p className="text-sm font-medium">All done for today</p>
+        <p className="text-xs text-muted-foreground mt-0.5">
+          Earned{' '}
+          <span className="font-medium text-amber-600 dark:text-amber-400">
+            {formatCompactNumber(todayCoins)} coins
+          </span>{' '}
+          — come back tomorrow!
         </p>
       </div>
     </div>
@@ -288,20 +167,17 @@ function AllClaimedState({ todayCoins }: AllClaimedStateProps) {
 
 // ─── Reroll Counter ───────────────────────────────────────────────────────────
 
-interface RerollCounterProps {
-  remaining: number;
-}
+function RerollCounter({ remaining }: { remaining: number }) {
+  const text =
+    remaining === 0
+      ? 'No rerolls left'
+      : remaining === 1
+        ? '1 reroll left'
+        : `${remaining} rerolls left`;
 
-function RerollCounter({ remaining }: RerollCounterProps) {
-  const text = remaining === 0
-    ? 'No rerolls left'
-    : remaining === 1
-      ? '1 reroll left'
-      : `${remaining} rerolls left`;
-  
   return (
-    <div className="flex items-center justify-end gap-1.5 text-xs text-muted-foreground">
-      <RefreshCw className="size-3" />
+    <div className="flex items-center justify-end gap-1 text-[11px] text-muted-foreground col-span-full">
+      <RefreshCw className="size-2.5" />
       <span>{text}</span>
     </div>
   );
@@ -322,48 +198,121 @@ export function DailyMissionsPanel({
   rerollsRemaining = 0,
   isRerolling = false,
 }: DailyMissionsPanelProps) {
-  // Show empty state if user has no eligible missions (e.g., only eggs)
-  if (noMissionsAvailable) {
-    return <NoMissionsState />;
-  }
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+
+  if (noMissionsAvailable) return <NoMissionsState />;
 
   const allRegularClaimed = missions.every((m) => m.claimed);
   const allDone = allRegularClaimed && bonusClaimed;
 
-  // Show "all done" state only when everything including bonus is claimed
-  if (allDone) {
-    return <AllClaimedState todayCoins={todayCoins} />;
-  }
+  if (allDone) return <AllClaimedState todayCoins={todayCoins} />;
 
   const canReroll = rerollsRemaining > 0 && !!onRerollMission;
 
+  const handleToggle = (id: string) => {
+    setExpandedId((prev) => (prev === id ? null : id));
+  };
+
   return (
-    <div className="space-y-3">
-      {/* Reroll counter - only show if reroll functionality is available */}
-      {onRerollMission && (
-        <RerollCounter remaining={rerollsRemaining} />
-      )}
-      
-      {/* Regular missions */}
-      {missions.map((mission) => (
-        <MissionItem
-          key={mission.id}
-          mission={mission}
-          onClaim={() => onClaimReward(mission.id)}
-          onReroll={onRerollMission ? () => onRerollMission(mission.id) : undefined}
-          disabled={disabled}
-          canReroll={canReroll}
-          isRerolling={isRerolling}
-        />
-      ))}
-      
-      {/* Bonus mission - always visible */}
-      <BonusMissionItem
+    <div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
+      {/* Reroll counter */}
+      {onRerollMission && <RerollCounter remaining={rerollsRemaining} />}
+
+      {/* Regular mission cards */}
+      {missions.map((mission) => {
+        const progress = mission.requiredCount > 0 ? mission.currentCount / mission.requiredCount : 0;
+        const canClaim = mission.completed && !mission.claimed;
+        const showReroll = onRerollMission && !mission.completed && !mission.claimed && canReroll;
+
+        return (
+          <ExpandableMissionCard
+            key={mission.id}
+            id={mission.id}
+            category="daily"
+            icon={<DailyMissionIcon action={mission.action} />}
+            title={mission.title}
+            completed={mission.claimed}
+            progress={Math.min(progress, 1)}
+            isExpanded={expandedId === mission.id}
+            onToggle={handleToggle}
+          >
+            {/* Description */}
+            <MissionDescription>{mission.description}</MissionDescription>
+
+            {/* Progress */}
+            {!mission.claimed && (
+              <MissionProgress
+                current={mission.currentCount}
+                required={mission.requiredCount}
+                completed={mission.completed}
+              />
+            )}
+
+            {/* Reward + reroll row */}
+            <div className="flex items-center justify-between">
+              <span className="inline-flex items-center gap-0.5 text-xs font-medium text-amber-600 dark:text-amber-400">
+                <Coins className="size-3" />
+                {formatCompactNumber(mission.reward)}
+              </span>
+
+              {showReroll && (
+                <TooltipProvider>
+                  <Tooltip>
+                    <TooltipTrigger asChild>
+                      <button
+                        onClick={(e) => {
+                          e.stopPropagation();
+                          onRerollMission(mission.id);
+                        }}
+                        disabled={disabled || isRerolling}
+                        className="p-1 rounded-md text-muted-foreground hover:text-foreground hover:bg-muted transition-colors disabled:opacity-40"
+                      >
+                        <RefreshCw className={cn('size-3', isRerolling && 'animate-spin')} />
+                      </button>
+                    </TooltipTrigger>
+                    <TooltipContent side="left">
+                      <p>Replace mission</p>
+                    </TooltipContent>
+                  </Tooltip>
+                </TooltipProvider>
+              )}
+
+              {mission.claimed && (
+                <span className="inline-flex items-center gap-0.5 text-[10px] font-medium text-primary">
+                  <Check className="size-2.5" />
+                  Done
+                </span>
+              )}
+            </div>
+
+            {/* Claim button */}
+            {canClaim && (
+              <Button
+                size="sm"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onClaimReward(mission.id);
+                }}
+                disabled={disabled}
+                className="w-full bg-emerald-600 hover:bg-emerald-700 text-white h-8 text-xs"
+              >
+                <Gift className="size-3.5 mr-1.5" />
+                Claim {formatCompactNumber(mission.reward)} Coins
+              </Button>
+            )}
+          </ExpandableMissionCard>
+        );
+      })}
+
+      {/* Bonus card */}
+      <BonusCard
         isAvailable={bonusAvailable}
         isClaimed={bonusClaimed}
         reward={bonusReward}
         onClaim={() => onClaimReward(BONUS_MISSION_ID)}
         disabled={disabled}
+        isExpanded={expandedId === 'bonus'}
+        onToggle={handleToggle}
       />
     </div>
   );

src/blobbi/actions/components/ExpandableMissionCard.tsx

@@ -0,0 +1,250 @@
+// src/blobbi/actions/components/ExpandableMissionCard.tsx
+
+/**
+ * Expandable mission card for the quest-board grid.
+ *
+ * Collapsed: compact square-ish card showing icon, title, and a tiny
+ *            progress ring / checkmark.
+ * Expanded:  full-width row that reveals description, progress bar,
+ *            action link, claim button, dynamic hints, etc.
+ *
+ * Only one card is expanded at a time per section (controlled by parent).
+ */
+
+import type { ReactNode } from 'react';
+import { Check, ChevronRight, ExternalLink, AlertCircle } from 'lucide-react';
+import { Progress } from '@/components/ui/progress';
+import { cn } from '@/lib/utils';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export type MissionCategory = 'daily' | 'hatch' | 'evolve';
+
+export interface ExpandableMissionCardProps {
+  /** Unique id used to track which card is expanded */
+  id: string;
+  /** Mission category for visual styling */
+  category: MissionCategory;
+  /** Icon rendered in the compact card (ReactNode — usually a lucide icon or emoji span) */
+  icon: ReactNode;
+  /** Short title */
+  title: string;
+  /** Whether the mission is complete */
+  completed: boolean;
+  /** Progress fraction 0-1 (used for the tiny ring in compact mode) */
+  progress: number;
+  /** Whether this card is currently expanded */
+  isExpanded: boolean;
+  /** Parent calls this to toggle expansion */
+  onToggle: (id: string) => void;
+  /** Content rendered only when expanded */
+  children: ReactNode;
+  /** Optional extra className on the outer wrapper */
+  className?: string;
+}
+
+// ─── Tiny Progress Ring ───────────────────────────────────────────────────────
+
+function ProgressRing({ progress, completed, category }: { progress: number; completed: boolean; category: MissionCategory }) {
+  const size = 28;
+  const stroke = 2.5;
+  const radius = (size - stroke) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const offset = circumference - progress * circumference;
+
+  if (completed) {
+    return (
+      <div className="size-7 rounded-full bg-emerald-500/20 flex items-center justify-center">
+        <Check className="size-3.5 text-emerald-600 dark:text-emerald-400" />
+      </div>
+    );
+  }
+
+  const ringColor =
+    category === 'hatch'
+      ? 'text-sky-500'
+      : category === 'evolve'
+        ? 'text-violet-500'
+        : 'text-amber-500';
+
+  return (
+    <svg width={size} height={size} className={cn('shrink-0 -rotate-90', ringColor)}>
+      <circle
+        cx={size / 2}
+        cy={size / 2}
+        r={radius}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={stroke}
+        opacity={0.15}
+      />
+      <circle
+        cx={size / 2}
+        cy={size / 2}
+        r={radius}
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={stroke}
+        strokeDasharray={circumference}
+        strokeDashoffset={offset}
+        strokeLinecap="round"
+        className="transition-all duration-300"
+      />
+    </svg>
+  );
+}
+
+// ─── Accent colors per category ───────────────────────────────────────────────
+
+const CATEGORY_STYLES: Record<MissionCategory, { bg: string; expandedBg: string; border: string }> = {
+  daily: {
+    bg: 'bg-amber-500/[0.06] hover:bg-amber-500/10',
+    expandedBg: 'bg-amber-500/[0.06]',
+    border: 'ring-amber-500/20',
+  },
+  hatch: {
+    bg: 'bg-sky-500/[0.06] hover:bg-sky-500/10',
+    expandedBg: 'bg-sky-500/[0.06]',
+    border: 'ring-sky-500/20',
+  },
+  evolve: {
+    bg: 'bg-violet-500/[0.06] hover:bg-violet-500/10',
+    expandedBg: 'bg-violet-500/[0.06]',
+    border: 'ring-violet-500/20',
+  },
+};
+
+// ─── Component ────────────────────────────────────────────────────────────────
+
+export function ExpandableMissionCard({
+  id,
+  category,
+  icon,
+  title,
+  completed,
+  progress,
+  isExpanded,
+  onToggle,
+  children,
+  className,
+}: ExpandableMissionCardProps) {
+  const styles = CATEGORY_STYLES[category];
+
+  // ── Collapsed card ──
+  if (!isExpanded) {
+    return (
+      <button
+        type="button"
+        onClick={() => onToggle(id)}
+        className={cn(
+          'flex flex-col items-center gap-1.5 rounded-xl p-3 transition-all text-center cursor-pointer select-none',
+          'ring-1 ring-transparent',
+          completed ? 'bg-emerald-500/[0.06] hover:bg-emerald-500/10' : styles.bg,
+          className,
+        )}
+      >
+        {/* Icon */}
+        <div className="text-lg leading-none">{icon}</div>
+
+        {/* Title — 2 lines max */}
+        <span className={cn(
+          'text-[11px] font-medium leading-tight line-clamp-2 min-h-[2lh]',
+          completed && 'text-emerald-600 dark:text-emerald-400',
+        )}>
+          {title}
+        </span>
+
+        {/* Progress ring / check */}
+        <ProgressRing progress={progress} completed={completed} category={category} />
+      </button>
+    );
+  }
+
+  // ── Expanded card (spans full row) ──
+  return (
+    <div
+      className={cn(
+        'col-span-full rounded-xl ring-1 transition-all overflow-hidden',
+        completed ? 'bg-emerald-500/[0.06] ring-emerald-500/20' : cn(styles.expandedBg, styles.border),
+        className,
+      )}
+    >
+      {/* Compact header — click to collapse */}
+      <button
+        type="button"
+        onClick={() => onToggle(id)}
+        className="w-full flex items-center gap-3 p-3 text-left cursor-pointer select-none"
+      >
+        <div className="text-lg leading-none shrink-0">{icon}</div>
+        <span className={cn(
+          'text-sm font-medium flex-1 min-w-0',
+          completed && 'text-emerald-600 dark:text-emerald-400',
+        )}>
+          {title}
+        </span>
+        <ProgressRing progress={progress} completed={completed} category={category} />
+      </button>
+
+      {/* Expanded details */}
+      <div className="px-3 pb-3 pt-0 space-y-2">
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// ─── Shared detail sub-components ─────────────────────────────────────────────
+
+/** Description text */
+export function MissionDescription({ children }: { children: ReactNode }) {
+  return <p className="text-xs text-muted-foreground leading-snug">{children}</p>;
+}
+
+/** Progress bar with fraction label */
+export function MissionProgress({ current, required, completed }: { current: number; required: number; completed: boolean }) {
+  const pct = required > 0 ? Math.round((current / required) * 100) : 0;
+  return (
+    <div>
+      <div className="flex items-center justify-between text-[11px] text-muted-foreground mb-1">
+        <span className="tabular-nums">{current} / {required}</span>
+        <span className="tabular-nums">{pct}%</span>
+      </div>
+      <Progress value={pct} className={cn('h-1.5', completed && '[&>div]:bg-emerald-500')} />
+    </div>
+  );
+}
+
+/** Inline action link (navigate, external, modal) */
+export function MissionAction({
+  label,
+  type,
+  onClick,
+}: {
+  label: string;
+  type: 'navigate' | 'external_link' | 'open_modal';
+  onClick: () => void;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      className="inline-flex items-center gap-1 text-xs font-medium text-primary hover:underline"
+    >
+      {label}
+      {type === 'external_link' ? (
+        <ExternalLink className="size-3" />
+      ) : (
+        <ChevronRight className="size-3" />
+      )}
+    </button>
+  );
+}
+
+/** Dynamic / live task hint */
+export function DynamicHint({ current, required }: { current: number; required: number }) {
+  return (
+    <div className="flex items-center gap-1.5 text-[11px] text-amber-600/80 dark:text-amber-400/80">
+      <AlertCircle className="size-3 shrink-0" />
+      <span>Lowest stat: {current}% (need {required}%+)</span>
+    </div>
+  );
+}

src/blobbi/actions/components/HatchTasksPanel.tsx

@@ -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') {

src/blobbi/actions/components/InlineMusicPlayer.tsx

@@ -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';

src/blobbi/actions/components/InlineSingCard.tsx

@@ -98,13 +98,6 @@ export function InlineSingCard({
     cleanup: cleanupPlayback,
   } = useAudioPlayback();
   
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      cleanupAll();
-    };
-  }, []);
-  
   // Cleanup all resources
   const cleanupAll = useCallback(() => {
     // Stop timer
@@ -138,6 +131,13 @@ export function InlineSingCard({
     }
   }, [audioUrl, cleanupPlayback]);
   
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      cleanupAll();
+    };
+  }, [cleanupAll]);
+  
   // Reset recording
   const resetRecording = useCallback(() => {
     cleanupAll();

src/blobbi/actions/components/PlayMusicModal.tsx

@@ -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;
 }

src/blobbi/actions/components/SingModal.tsx

@@ -82,22 +82,6 @@ export function SingModal({
   // Track the actual MIME type used by the recorder
   const actualMimeTypeRef = useRef<string | undefined>(undefined);
   
-  // Cleanup on unmount
-  useEffect(() => {
-    return () => {
-      cleanup();
-    };
-  }, []);
-  
-  // Reset state when modal opens
-  useEffect(() => {
-    if (open) {
-      resetRecording();
-    } else {
-      cleanup();
-    }
-  }, [open]);
-  
   const cleanup = useCallback(() => {
     // Stop timer
     if (timerRef.current) {
@@ -142,6 +126,22 @@ export function SingModal({
     // Keep lyrics when re-recording so user can sing the same song
   }, [cleanup]);
   
+  // Cleanup on unmount
+  useEffect(() => {
+    return () => {
+      cleanup();
+    };
+  }, [cleanup]);
+  
+  // Reset state when modal opens
+  useEffect(() => {
+    if (open) {
+      resetRecording();
+    } else {
+      cleanup();
+    }
+  }, [open, cleanup, resetRecording]);
+  
   // Handle getting random lyrics
   const handleRandomLyrics = useCallback(() => {
     const lyrics = getRandomLyrics();

src/blobbi/actions/components/StartEvolutionDialog.tsx

@@ -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 ────────────────────────────────────────────────────────────────────
 

src/blobbi/actions/components/StartIncubationDialog.tsx

@@ -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 ────────────────────────────────────────────────────────────────────

src/blobbi/actions/components/TasksPanel.tsx

@@ -1,21 +1,38 @@
 // src/blobbi/actions/components/TasksPanel.tsx
 
 /**
- * Generic UI component for displaying task progress.
- * Shows a list of tasks with progress indicators and action buttons.
- * Used for both hatch and evolve tasks.
+ * Card-grid presentation for hatch / evolve tasks.
+ *
+ * Each task is a compact card in a 2-column grid.
+ * Tapping a card expands it inline (full row) to reveal details.
+ * Only one card is expanded at a time.
  */
 
-import { ExternalLink, Check, Loader2, ChevronRight, AlertCircle } from 'lucide-react';
+import { useState } from 'react';
 import { useNavigate } from 'react-router-dom';
+import {
+  Palette,
+  Droplets,
+  MessageSquare,
+  Heart,
+  UserPen,
+  Activity,
+  Loader2,
+  HelpCircle,
+} from 'lucide-react';
+import { openUrl } from '@/lib/downloadFile';
 
 import { Button } from '@/components/ui/button';
-import { Progress } from '@/components/ui/progress';
-import { Card, CardContent, CardHeader, CardTitle, CardDescription } from '@/components/ui/card';
-import { Badge } from '@/components/ui/badge';
-import { cn } from '@/lib/utils';
 
 import type { HatchTask } from '../hooks/useHatchTasks';
+import type { MissionCategory } from './ExpandableMissionCard';
+import {
+  ExpandableMissionCard,
+  MissionDescription,
+  MissionProgress,
+  MissionAction,
+  DynamicHint,
+} from './ExpandableMissionCard';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -23,149 +40,38 @@ interface TasksPanelProps {
   tasks: HatchTask[];
   allCompleted: boolean;
   isLoading: boolean;
-  /** Called when user clicks "Create Post" action */
   onOpenPostModal: () => void;
-  /** Called when all tasks are complete and user clicks the complete button */
   onComplete: () => void;
-  /** Whether completion is in progress */
   isCompleting?: boolean;
-  /** Emoji to show in header */
-  emoji: string;
-  /** Title for the tasks panel */
-  title: string;
-  /** Description for the tasks panel */
-  description: string;
-  /** Label for the complete button */
   completeLabel: string;
-  /** Label while completing */
   completingLabel: string;
-  /** Emoji for complete button */
   completeEmoji: string;
+  /** Mission category for styling the cards */
+  category?: MissionCategory;
 }
 
-// ─── Task Row Component ───────────────────────────────────────────────────────
+// ─── Task Icon Mapping ────────────────────────────────────────────────────────
 
-interface TaskRowProps {
-  task: HatchTask;
-  onOpenPostModal: () => void;
-}
+/** Map task ids to lucide icons. Falls back to a generic icon. */
+function TaskIcon({ taskId }: { taskId: string }) {
+  const iconClass = 'size-5';
 
-function TaskRow({ task, onOpenPostModal }: TaskRowProps) {
-  const navigate = useNavigate();
-  const isDynamic = task.type === 'dynamic';
-  
-  const handleAction = () => {
-    if (!task.action || !task.actionTarget) return;
-    
-    switch (task.action) {
-      case 'navigate':
-        navigate(task.actionTarget);
-        break;
-      case 'external_link':
-        window.open(task.actionTarget, '_blank', 'noopener,noreferrer');
-        break;
-      case 'open_modal':
-        if (task.actionTarget === 'blobbi_post') {
-          onOpenPostModal();
-        }
-        break;
-    }
-  };
-  
-  const progress = task.required > 1 
-    ? Math.round((task.current / task.required) * 100)
-    : task.completed ? 100 : 0;
-  
-  return (
-    <div
-      className={cn(
-        "flex flex-col sm:flex-row sm:items-center gap-2 sm:gap-4 p-3 sm:p-4 rounded-xl border transition-all overflow-hidden",
-        task.completed 
-          ? "bg-emerald-500/5 border-emerald-500/20" 
-          : isDynamic
-            ? "bg-amber-500/5 border-amber-500/20"
-            : "bg-card/60 border-border hover:border-primary/30"
-      )}
-    >
-      {/* Top row on mobile: Status + Task info */}
-      <div className="flex items-start sm:items-center gap-3 sm:contents">
-        {/* Status indicator */}
-        <div className={cn(
-          "size-8 sm:size-10 rounded-full flex items-center justify-center shrink-0",
-          task.completed 
-            ? "bg-emerald-500/20 text-emerald-600 dark:text-emerald-400"
-            : isDynamic
-              ? "bg-amber-500/20 text-amber-600 dark:text-amber-400"
-              : "bg-muted text-muted-foreground"
-        )}>
-          {task.completed ? (
-            <Check className="size-4 sm:size-5" />
-          ) : isDynamic ? (
-            <AlertCircle className="size-4 sm:size-5" />
-          ) : task.required > 1 ? (
-            <span className="text-xs sm:text-sm font-medium">{task.current}/{task.required}</span>
-          ) : (
-            <span className="text-base sm:text-lg">○</span>
-          )}
-        </div>
-        
-        {/* Task info */}
-        <div className="flex-1 min-w-0">
-          <div className="flex flex-wrap items-center gap-1 sm:gap-2 mb-0.5 sm:mb-1">
-            <h4 className={cn(
-              "font-medium text-sm sm:text-base break-words",
-              task.completed && "text-emerald-600 dark:text-emerald-400",
-              isDynamic && !task.completed && "text-amber-600 dark:text-amber-400"
-            )}>
-              {task.name}
-            </h4>
-            {task.completed && (
-              <Badge variant="secondary" className="bg-emerald-500/20 text-emerald-700 dark:text-emerald-300 text-xs shrink-0">
-                Complete
-              </Badge>
-            )}
-            {isDynamic && !task.completed && (
-              <Badge variant="secondary" className="bg-amber-500/20 text-amber-700 dark:text-amber-300 text-xs shrink-0">
-                Live
-              </Badge>
-            )}
-          </div>
-          <p className="text-xs sm:text-sm text-muted-foreground break-words">
-            {task.description}
-          </p>
-          
-          {/* Progress bar for multi-step tasks (not for dynamic stat tasks) */}
-          {task.required > 1 && !task.completed && !isDynamic && (
-            <Progress value={progress} className="h-1.5 mt-2" />
-          )}
-          
-          {/* Dynamic task hint */}
-          {isDynamic && !task.completed && (
-            <p className="text-xs text-amber-600/70 dark:text-amber-400/70 mt-1">
-              Lowest stat: {task.current}% (need {task.required}%+)
-            </p>
-          )}
-        </div>
-      </div>
-      
-      {/* Action button - full width on mobile when present */}
-      {task.action && task.actionLabel && !task.completed && (
-        <Button
-          variant="outline"
-          size="sm"
-          onClick={handleAction}
-          className="shrink-0 gap-2 w-full sm:w-auto mt-1 sm:mt-0"
-        >
-          <span className="truncate">{task.actionLabel}</span>
-          {task.action === 'external_link' ? (
-            <ExternalLink className="size-3.5 shrink-0" />
-          ) : (
-            <ChevronRight className="size-3.5 shrink-0" />
-          )}
-        </Button>
-      )}
-    </div>
-  );
+  switch (taskId) {
+    case 'create_themes':
+      return <Palette className={iconClass} />;
+    case 'color_moments':
+      return <Droplets className={iconClass} />;
+    case 'create_posts':
+      return <MessageSquare className={iconClass} />;
+    case 'interactions':
+      return <Heart className={iconClass} />;
+    case 'edit_profile':
+      return <UserPen className={iconClass} />;
+    case 'maintain_stats':
+      return <Activity className={iconClass} />;
+    default:
+      return <HelpCircle className={iconClass} />;
+  }
 }
 
 // ─── Main Component ───────────────────────────────────────────────────────────
@@ -177,86 +83,113 @@ export function TasksPanel({
   onOpenPostModal,
   onComplete,
   isCompleting = false,
-  emoji,
-  title,
-  description,
   completeLabel,
   completingLabel,
   completeEmoji,
+  category = 'hatch',
 }: TasksPanelProps) {
-  const completedCount = tasks.filter(t => t.completed).length;
-  const totalTasks = tasks.length;
-  const overallProgress = totalTasks > 0 ? Math.round((completedCount / totalTasks) * 100) : 0;
-  
+  const [expandedId, setExpandedId] = useState<string | null>(null);
+  const navigate = useNavigate();
+
+  const handleToggle = (id: string) => {
+    setExpandedId((prev) => (prev === id ? null : id));
+  };
+
+  if (isLoading) {
+    return (
+      <div className="flex items-center justify-center py-8">
+        <Loader2 className="size-5 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
   return (
-    <Card className="border-primary/20 bg-gradient-to-br from-primary/5 to-transparent overflow-hidden">
-      <CardHeader className="pb-3 sm:pb-4 px-3 sm:px-6">
-        <div className="flex items-start sm:items-center justify-between gap-2">
-          <div className="min-w-0 flex-1">
-            <CardTitle className="flex items-center gap-2 text-base sm:text-lg">
-              <span className="text-xl sm:text-2xl shrink-0">{emoji}</span>
-              <span className="break-words">{title}</span>
-            </CardTitle>
-            <CardDescription className="text-xs sm:text-sm break-words">
-              {description}
-            </CardDescription>
-          </div>
-          <Badge variant="outline" className="text-sm sm:text-base px-2 sm:px-3 py-0.5 sm:py-1 shrink-0">
-            {completedCount}/{totalTasks}
-          </Badge>
-        </div>
-        
-        {/* Overall progress */}
-        <div className="mt-3 sm:mt-4">
-          <div className="flex items-center justify-between text-xs sm:text-sm mb-2">
-            <span className="text-muted-foreground">Overall progress</span>
-            <span className="font-medium">{overallProgress}%</span>
-          </div>
-          <Progress value={overallProgress} className="h-2" />
-        </div>
-      </CardHeader>
-      
-      <CardContent className="space-y-2 sm:space-y-3 px-3 sm:px-6">
-        {isLoading ? (
-          <div className="flex items-center justify-center py-8">
-            <Loader2 className="size-6 animate-spin text-muted-foreground" />
-          </div>
-        ) : (
-          <>
-            {tasks.map(task => (
-              <TaskRow 
-                key={task.id} 
-                task={task} 
-                onOpenPostModal={onOpenPostModal}
-              />
-            ))}
-            
-            {/* Complete button - only visible when all tasks complete */}
-            {allCompleted && (
-              <div className="pt-4 border-t border-border mt-4">
-                <Button
-                  onClick={onComplete}
-                  disabled={isCompleting}
-                  size="lg"
-                  className="w-full gap-2 bg-gradient-to-r from-amber-500 to-orange-500 hover:from-amber-600 hover:to-orange-600 text-white"
-                >
-                  {isCompleting ? (
-                    <>
-                      <Loader2 className="size-5 animate-spin" />
-                      {completingLabel}
-                    </>
-                  ) : (
-                    <>
-                      <span className="text-xl">{completeEmoji}</span>
-                      {completeLabel}
-                    </>
-                  )}
-                </Button>
-              </div>
-            )}
-          </>
-        )}
-      </CardContent>
-    </Card>
+    <div className="space-y-3">
+      {/* Card grid */}
+      <div className="grid grid-cols-2 sm:grid-cols-3 gap-2">
+        {tasks.map((task) => {
+          const isDynamic = task.type === 'dynamic';
+          const progress =
+            task.required > 0 ? task.current / task.required : task.completed ? 1 : 0;
+
+          const handleAction = () => {
+            if (!task.action || !task.actionTarget) return;
+            switch (task.action) {
+              case 'navigate':
+                navigate(task.actionTarget);
+                break;
+              case 'external_link':
+                openUrl(task.actionTarget);
+                break;
+              case 'open_modal':
+                if (task.actionTarget === 'blobbi_post') onOpenPostModal();
+                break;
+            }
+          };
+
+          return (
+            <ExpandableMissionCard
+              key={task.id}
+              id={task.id}
+              category={category}
+              icon={<TaskIcon taskId={task.id} />}
+              title={task.name}
+              completed={task.completed}
+              progress={Math.min(progress, 1)}
+              isExpanded={expandedId === task.id}
+              onToggle={handleToggle}
+            >
+              {/* Expanded content */}
+              <MissionDescription>{task.description}</MissionDescription>
+
+              {/* Progress bar for multi-step tasks */}
+              {task.required > 1 && !isDynamic && (
+                <MissionProgress
+                  current={task.current}
+                  required={task.required}
+                  completed={task.completed}
+                />
+              )}
+
+              {/* Dynamic stat hint */}
+              {isDynamic && !task.completed && (
+                <DynamicHint current={task.current} required={task.required} />
+              )}
+
+              {/* Action link */}
+              {task.action && task.actionLabel && !task.completed && (
+                <MissionAction
+                  label={task.actionLabel}
+                  type={task.action}
+                  onClick={handleAction}
+                />
+              )}
+            </ExpandableMissionCard>
+          );
+        })}
+      </div>
+
+      {/* CTA button when all tasks are done */}
+      {allCompleted && (
+        <Button
+          onClick={onComplete}
+          disabled={isCompleting}
+          size="lg"
+          className="w-full gap-2 bg-gradient-to-r from-amber-500 to-orange-500 hover:from-amber-600 hover:to-orange-600 text-white shadow-sm"
+        >
+          {isCompleting ? (
+            <>
+              <Loader2 className="size-5 animate-spin" />
+              {completingLabel}
+            </>
+          ) : (
+            <>
+              <span className="text-lg">{completeEmoji}</span>
+              {completeLabel}
+            </>
+          )}
+        </Button>
+      )}
+    </div>
   );
 }

src/blobbi/actions/hooks/useActiveTaskProcess.ts

@@ -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';
@@ -168,7 +168,7 @@ export function useActiveTaskProcess(
   }, [processType, hatchTasks, evolveTasks]);
   
   // Extract tasks and state from active result
-  const tasks = activeResult?.tasks ?? [];
+  const tasks = useMemo(() => activeResult?.tasks ?? [], [activeResult]);
   const isLoading = activeResult?.isLoading ?? false;
   const allCompleted = activeResult?.allCompleted ?? false;
   const persistentTasksComplete = activeResult?.persistentTasksComplete ?? false;

src/blobbi/actions/hooks/useBlobbiCareActivity.ts

@@ -17,14 +17,20 @@
  */
 
 import { useCallback, useRef } from 'react';
+import { useNostr } from '@nostrify/react';
 import { useMutation } from '@tanstack/react-query';
 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,
+  isValidBlobbiEvent,
+  parseBlobbiEvent,
+} from '@/blobbi/core/lib/blobbi';
 
 import { getStreakTagUpdates, calculateStreakUpdate, type StreakUpdateResult } from '../lib/blobbi-streak';
 
@@ -34,8 +40,6 @@ export interface UseBlobbiCareActivityParams {
   companion: BlobbiCompanion | null;
   /** Update companion event in local cache */
   updateCompanionEvent: (event: NostrEvent) => void;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
 }
 
 export interface CareActivityResult {
@@ -59,8 +63,8 @@ export interface CareActivityResult {
 export function useBlobbiCareActivity({
   companion,
   updateCompanionEvent,
-  invalidateCompanion,
 }: UseBlobbiCareActivityParams) {
+  const { nostr } = useNostr();
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
   
@@ -78,12 +82,24 @@ export function useBlobbiCareActivity({
         throw new Error('No companion available');
       }
 
+      // Fetch fresh companion from relays (read-modify-write pattern)
+      const freshEvents = await nostr.query([{
+        kinds: [KIND_BLOBBI_STATE],
+        authors: [user.pubkey],
+        '#d': [companion.d],
+      }]);
+      const freshCompanion = freshEvents
+        .filter(isValidBlobbiEvent)
+        .sort((a, b) => b.created_at - a.created_at)
+        .map(e => parseBlobbiEvent(e))
+        .find(Boolean) ?? companion;
+
       const now = new Date();
       
-      // Calculate what the streak update should be
+      // Calculate what the streak update should be using fresh data
       const result = calculateStreakUpdate(
-        companion.careStreak,
-        companion.careStreakLastDay,
+        freshCompanion.careStreak,
+        freshCompanion.careStreakLastDay,
         now
       );
       
@@ -96,29 +112,29 @@ export function useBlobbiCareActivity({
         };
       }
       
-      // Get the tag updates
-      const streakUpdates = getStreakTagUpdates(companion, now);
+      // Get the tag updates using fresh data
+      const streakUpdates = getStreakTagUpdates(freshCompanion, now);
       
       if (!streakUpdates) {
         // Shouldn't happen if wasUpdated is true, but handle gracefully
         return {
           wasUpdated: false,
-          newStreak: companion.careStreak ?? 0,
+          newStreak: freshCompanion.careStreak ?? 0,
           action: 'same_day',
         };
       }
       
-      // Build updated tags
-      const updatedTags = updateBlobbiTags(companion.allTags, streakUpdates);
+      // Build updated tags from fresh data
+      const updatedTags = updateBlobbiTags(freshCompanion.allTags, streakUpdates);
       
       // Publish the updated event
       const event = await publishEvent({
         kind: KIND_BLOBBI_STATE,
-        content: companion.event.content,
+        content: freshCompanion.event.content,
         tags: updatedTags,
       });
       
-      // Update local cache
+      // Update local cache (optimistic — no invalidation needed)
       updateCompanionEvent(event);
       
       // Update session tracker
@@ -128,9 +144,9 @@ export function useBlobbiCareActivity({
       if (import.meta.env.DEV) {
         console.log('[CareActivity] Streak updated:', {
           action: result.action,
-          previousStreak: companion.careStreak,
+          previousStreak: freshCompanion.careStreak,
           newStreak: result.newStreak,
-          lastDay: companion.careStreakLastDay,
+          lastDay: freshCompanion.careStreakLastDay,
           newDay: result.newLastDay,
         });
       }
@@ -141,11 +157,6 @@ export function useBlobbiCareActivity({
         action: result.action,
       };
     },
-    onSuccess: (result) => {
-      if (result.wasUpdated) {
-        invalidateCompanion();
-      }
-    },
     onError: (error: Error) => {
       console.error('[CareActivity] Failed to update streak:', error);
     },

src/blobbi/actions/hooks/useBlobbiDirectAction.ts

@@ -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;
 }
 
 /**
@@ -66,15 +69,11 @@ export interface UseBlobbiDirectActionParams {
   } | null>;
   /** Update companion event in local cache */
   updateCompanionEvent: (event: NostrEvent) => void;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries (needed if migration happened) */
-  invalidateProfile: () => void;
 }
 
 /**
  * Hook to execute a direct action on a Blobbi companion.
- * Direct actions (play_music, sing) don't consume inventory items.
+ * Direct actions (play_music, sing) don't require selecting an item.
  * They directly affect happiness stat.
  * 
  * This hook:
@@ -89,8 +88,6 @@ export function useBlobbiDirectAction({
   companion,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseBlobbiDirectActionParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -129,6 +126,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 +161,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,
       });
@@ -176,22 +183,19 @@ export function useBlobbiDirectAction({
 
       updateCompanionEvent(blobbiEvent);
 
-      // ─── Invalidate Queries ───
-      invalidateCompanion();
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
-
       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

src/blobbi/actions/hooks/useBlobbiIncubation.ts

@@ -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,14 +62,10 @@ 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;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries (needed if migration occurred) */
-  invalidateProfile: () => void;
 }
 
 /**
@@ -112,8 +108,6 @@ export function useStartIncubation({
   profile,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseStartIncubationParams) {
   const { user } = useCurrentUser();
   const { nostr } = useNostr();
@@ -269,12 +263,6 @@ export function useStartIncubation({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-      
-      // Invalidate profile if migration occurred
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       return {
         name: canonical.companion.name,
@@ -325,14 +313,10 @@ 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;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries (needed if migration occurred) */
-  invalidateProfile: () => void;
 }
 
 /**
@@ -363,8 +347,6 @@ export function useStopIncubation({
   companion,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseStopIncubationParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -435,12 +417,6 @@ export function useStopIncubation({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-      
-      // Invalidate profile if migration occurred
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       return {
         name: canonical.companion.name,
@@ -476,14 +452,10 @@ 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;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries (needed if migration occurred) */
-  invalidateProfile: () => void;
 }
 
 /**
@@ -511,8 +483,6 @@ export function useStartEvolution({
   companion,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseStartEvolutionParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -585,12 +555,6 @@ export function useStartEvolution({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-      
-      // Invalidate profile if migration occurred
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       return {
         name: canonical.companion.name,
@@ -627,14 +591,10 @@ 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;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries (needed if migration occurred) */
-  invalidateProfile: () => void;
 }
 
 /**
@@ -665,8 +625,6 @@ export function useStopEvolution({
   companion,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseStopEvolutionParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -736,12 +694,6 @@ export function useStopEvolution({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-      
-      // Invalidate profile if migration occurred
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       return {
         name: canonical.companion.name,
@@ -780,14 +732,10 @@ 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;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries */
-  invalidateProfile: () => void;
 }
 
 /**
@@ -827,8 +775,6 @@ export function useSyncTaskCompletions({
   companion,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseSyncTaskCompletionsParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -923,11 +869,6 @@ export function useSyncTaskCompletions({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       if (DEBUG_TASK_SYNC) {
         console.log('[TaskSync] Published successfully:', tagsToAdd);

src/blobbi/actions/hooks/useBlobbiStageTransition.ts

@@ -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[];
 }
 
 /**
@@ -69,10 +69,6 @@ export interface UseBlobbiStageTransitionParams {
   ensureCanonicalBeforeAction: () => Promise<CanonicalActionResult | null>;
   /** Update companion event in local cache */
   updateCompanionEvent: (event: NostrEvent) => void;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries (needed if migration occurred) */
-  invalidateProfile: () => void;
 }
 
 /**
@@ -113,8 +109,6 @@ export function useBlobbiHatch({
   profile,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseBlobbiStageTransitionParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -157,14 +151,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 ───
@@ -221,12 +214,6 @@ export function useBlobbiHatch({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-      
-      // Invalidate profile if migration occurred
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       return {
         previousStage: 'egg',
@@ -269,8 +256,6 @@ export function useBlobbiEvolve({
   profile,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  invalidateCompanion,
-  invalidateProfile,
 }: UseBlobbiStageTransitionParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
@@ -377,12 +362,6 @@ export function useBlobbiEvolve({
       });
 
       updateCompanionEvent(event);
-      invalidateCompanion();
-      
-      // Invalidate profile if migration occurred
-      if (canonical.wasMigrated) {
-        invalidateProfile();
-      }
 
       return {
         previousStage: 'baby',

src/blobbi/actions/hooks/useBlobbiUseInventoryItem.ts

@@ -6,19 +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 } 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,
-  decrementStorageItem,
   canUseAction,
   getStageRestrictionMessage,
   clampStat,
@@ -32,27 +28,27 @@ 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';
 
 /**
- * Request payload for using an inventory item
+ * Request payload for using an item on a Blobbi companion
  */
 export interface UseItemRequest {
   itemId: string;
   action: InventoryAction;
-  /** Number of items to use (defaults to 1) */
-  quantity?: number;
 }
 
 /**
- * Result of using an inventory item
+ * Result of using an item on a Blobbi companion
  */
 export interface UseItemResult {
   itemName: string;
   action: InventoryAction;
-  quantity: number;
   statsChanged: Record<string, number>;
+  xpGained: number;
+  newXP: number;
 }
 
 /**
@@ -67,50 +63,44 @@ export interface UseBlobbiUseInventoryItemParams {
     content: string;
     allTags: string[][];
     wasMigrated: boolean;
-    /** Latest profile tags after migration (use instead of profile.allTags) */
+    /** Latest profile tags after migration */
     profileAllTags: string[][];
-    /** Latest profile storage after migration (use instead of profile.storage) */
-    profileStorage: import('@/lib/blobbi').StorageItem[];
+    /** Latest profile storage after migration */
+    profileStorage: import('@/blobbi/core/lib/blobbi').StorageItem[];
   } | null>;
   /** Update companion event in local cache */
   updateCompanionEvent: (event: NostrEvent) => void;
   /** Update profile event in local cache */
   updateProfileEvent: (event: NostrEvent) => void;
-  /** Invalidate companion queries */
-  invalidateCompanion: () => void;
-  /** Invalidate profile queries */
-  invalidateProfile: () => void;
 }
 
 // Import NostrEvent type
 import type { NostrEvent } from '@nostrify/nostrify';
 
 /**
- * Hook to use an inventory item on a Blobbi companion.
+ * Hook to use an item on a Blobbi companion.
+ * 
+ * Items are reusable abilities sourced from the shop catalog — no
+ * inventory ownership or quantity is required.
  * 
  * This hook:
- * 1. Validates the companion stage (eggs can't use items)
- * 2. Validates the item exists in storage
- * 3. Ensures canonical format before action
- * 4. Applies item effects to Blobbi stats
- * 5. Updates Blobbi state (kind 31124)
- * 6. Decrements item from profile storage (kind 11125)
- * 7. Invalidates relevant queries
+ * 1. Validates the companion and item compatibility
+ * 2. Ensures canonical format before action
+ * 3. Applies accumulated decay, then item effects to Blobbi stats
+ * 4. Updates Blobbi state (kind 31124)
  */
 export function useBlobbiUseInventoryItem({
   companion,
   profile,
   ensureCanonicalBeforeAction,
   updateCompanionEvent,
-  updateProfileEvent,
-  invalidateCompanion,
-  invalidateProfile,
+  updateProfileEvent: _updateProfileEvent,
 }: UseBlobbiUseInventoryItemParams) {
   const { user } = useCurrentUser();
   const { mutateAsync: publishEvent } = useNostrPublish();
 
   return useMutation({
-    mutationFn: async ({ itemId, action, quantity = 1 }: UseItemRequest): Promise<UseItemResult> => {
+    mutationFn: async ({ itemId, action }: UseItemRequest): Promise<UseItemResult> => {
       // ─── Validation ───
       if (!user?.pubkey) {
         throw new Error('You must be logged in to use items');
@@ -124,11 +114,6 @@ export function useBlobbiUseInventoryItem({
         throw new Error('Profile not found');
       }
 
-      // Validate quantity
-      if (quantity < 1) {
-        throw new Error('Quantity must be at least 1');
-      }
-
       // Check stage restrictions for this specific action
       if (!canUseAction(companion, action)) {
         const message = getStageRestrictionMessage(companion, action);
@@ -141,15 +126,6 @@ export function useBlobbiUseInventoryItem({
         throw new Error('Item not found in catalog');
       }
 
-      // Validate item exists in storage with sufficient quantity
-      const storageItem = profile.storage.find(s => s.itemId === itemId);
-      if (!storageItem || storageItem.quantity <= 0) {
-        throw new Error('Item not found in your inventory');
-      }
-      if (storageItem.quantity < quantity) {
-        throw new Error(`Not enough items in inventory (have ${storageItem.quantity}, need ${quantity})`);
-      }
-
       // Validate item has effects
       if (!shopItem.effect) {
         throw new Error('This item has no effect');
@@ -186,54 +162,51 @@ export function useBlobbiUseInventoryItem({
       // Start with decayed stats as the base
       const statsAfterDecay = decayResult.stats;
       
-      // ─── 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.
-      // Use canonical companion stage for egg checks
+      // ─── 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 (single use) ───
       const isEggCompanion = canonical.companion.stage === 'egg';
       const statsUpdate: Record<string, string> = {};
       const statsChanged: Record<string, number> = {};
 
       if (isEggCompanion && action === 'medicine') {
-        // Egg medicine handling:
-        // Eggs use the 3-stat model: health, hygiene, happiness
-        // Medicine with health effect directly affects the egg's health stat
-        // hunger and energy remain fixed at 100 for eggs
-        
         const healthDelta = shopItem.effect.health ?? 0;
-        // Apply health effect N times in sequence with clamping at each step
-        let currentHealth = statsAfterDecay.health ?? 0;
-        for (let i = 0; i < quantity; i++) {
-          currentHealth = applyStat(currentHealth, healthDelta);
-        }
+        const currentHealth = applyStat(statsAfterDecay.health ?? 0, healthDelta);
         
         statsUpdate.health = currentHealth.toString();
-        // Track total actual change (may be less than healthDelta * quantity due to clamping)
         statsChanged.health = currentHealth - (statsAfterDecay.health ?? 0);
         
-        // Apply decayed values for other egg stats
         statsUpdate.hygiene = (statsAfterDecay.hygiene ?? 0).toString();
         statsUpdate.happiness = (statsAfterDecay.happiness ?? 0).toString();
-        // hunger and energy stay at 100 for eggs
         statsUpdate.hunger = '100';
         statsUpdate.energy = '100';
       } else if (isEggCompanion && action === 'clean') {
-        // Egg clean/hygiene handling:
-        // Hygiene items affect the egg's hygiene stat
-        // Some hygiene items also give happiness (e.g., bubble bath)
-        // hunger and energy remain fixed at 100 for eggs
-        
-        const hygieneDelta = shopItem.effect.hygiene ?? 0;
-        const happinessDelta = shopItem.effect.happiness ?? 0;
-        
-        // Apply effects N times in sequence
-        let currentHygiene = statsAfterDecay.hygiene ?? 0;
-        let currentHappiness = statsAfterDecay.happiness ?? 0;
-        for (let i = 0; i < quantity; i++) {
-          currentHygiene = applyStat(currentHygiene, hygieneDelta);
-          currentHappiness = applyStat(currentHappiness, happinessDelta);
-        }
+        const currentHygiene = applyStat(statsAfterDecay.hygiene ?? 0, shopItem.effect.hygiene ?? 0);
+        const currentHappiness = applyStat(statsAfterDecay.happiness ?? 0, shopItem.effect.happiness ?? 0);
         
         statsUpdate.hygiene = currentHygiene.toString();
         statsChanged.hygiene = currentHygiene - (statsAfterDecay.hygiene ?? 0);
@@ -244,18 +217,12 @@ export function useBlobbiUseInventoryItem({
           statsChanged.happiness = totalHappinessChange;
         }
         
-        // Apply decayed health
         statsUpdate.health = (statsAfterDecay.health ?? 0).toString();
-        // hunger and energy stay at 100 for eggs
         statsUpdate.hunger = '100';
         statsUpdate.energy = '100';
       } else {
-        // Normal stats application for baby/adult
-        // Apply item effects N times in sequence ON TOP of decayed stats
-        let currentStats: Partial<BlobbiStats> = { ...statsAfterDecay };
-        for (let i = 0; i < quantity; i++) {
-          currentStats = applyItemEffects(currentStats, shopItem.effect);
-        }
+        // Normal stats application for baby/adult — apply once
+        const currentStats = applyItemEffects({ ...statsAfterDecay }, shopItem.effect);
 
         statsUpdate.hunger = clampStat(currentStats.hunger).toString();
         statsChanged.hunger = (currentStats.hunger ?? 0) - (statsAfterDecay.hunger ?? 0);
@@ -288,9 +255,15 @@ export function useBlobbiUseInventoryItem({
       // Get streak updates (will only update if needed based on day)
       const streakUpdates = getStreakTagUpdates(canonical.companion) ?? {};
       
+      // ─── Apply XP Gain ───
+      const xpGained = calculateInventoryActionXP(action, 1);
+      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,
       });
@@ -303,42 +276,25 @@ export function useBlobbiUseInventoryItem({
 
       updateCompanionEvent(blobbiEvent);
 
-      // ─── Update Profile Storage (kind 11125) ───
-      // CRITICAL: Use canonical.profileStorage and canonical.profileAllTags
-      // instead of profile.storage/profile.allTags to avoid restoring
-      // stale/legacy values after migration
-      const newStorage = decrementStorageItem(canonical.profileStorage, itemId, quantity);
-      const storageValues = createStorageTags(newStorage).map(tag => tag[1]);
-
-      const profileTags = updateBlobbonautTags(canonical.profileAllTags, {
-        storage: storageValues,
-      });
-
-      const profileEvent = await publishEvent({
-        kind: KIND_BLOBBONAUT_PROFILE,
-        content: '',
-        tags: profileTags,
-      });
-
-      updateProfileEvent(profileEvent);
-
-      // ─── Invalidate Queries ───
-      invalidateCompanion();
-      invalidateProfile();
+      // Items are free to use — no storage decrement needed.
+      // No query invalidation needed — the optimistic update above keeps the
+      // cache correct, and ensureCanonicalBeforeAction fetches fresh from relays
+      // before every mutation (read-modify-write pattern).
 
       return {
         itemName: shopItem.name,
         action,
-        quantity,
         statsChanged,
+        xpGained,
+        newXP,
       };
     },
-    onSuccess: ({ itemName, action, quantity }) => {
+    onSuccess: ({ itemName, action, 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} on your Blobbi. ${xpText}`,
       });
 
       // Track daily mission progress

src/blobbi/actions/hooks/useClaimMissionReward.ts

@@ -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,

src/blobbi/actions/hooks/useEvolveTasks.ts

@@ -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,
@@ -30,8 +30,8 @@ import {
 
 // ─── Constants ────────────────────────────────────────────────────────────────
 
-/** Kind for wall edit events */
-export const KIND_WALL_EDIT = 16769;
+/** Kind for custom profile tabs event */
+export const KIND_PROFILE_TABS = 16769;
 
 /** Required themes for evolve task */
 export const EVOLVE_REQUIRED_THEMES = 3;
@@ -117,7 +117,7 @@ export function isValidEvolvePost(event: NostrEvent, blobbiName: string): boolea
  * 2. Create 3 Color Moments (kind 3367)
  * 3. Create 1 Evolve Post (kind 1) - lighter than hatch, evolve-specific
  * 4. Interact 21 times (tracked via companion.tasks cache)
- * 5. Edit Wall once (kind 16769)
+ * 5. Edit Profile once (kind 0 profile metadata OR kind 16769 custom tabs)
  * 
  * DYNAMIC TASK (stat-based, NEVER cached):
  * 6. Maintain All Stats >= 80
@@ -165,14 +165,14 @@ export function useEvolveTasks(
           since: stateStartedAt,
           limit: 50, // Only need 1 valid evolve post
         },
-        // Wall edits after start
+        // Custom profile tabs after start
         {
-          kinds: [KIND_WALL_EDIT],
+          kinds: [KIND_PROFILE_TABS],
           authors: [pubkey],
           since: stateStartedAt,
           limit: 1, // Only need 1
         },
-        // Profile metadata after start (for Blobbi shape check)
+        // Profile metadata after start (for Blobbi shape check + profile edit mission)
         {
           kinds: [KIND_PROFILE_METADATA],
           authors: [pubkey],
@@ -197,8 +197,8 @@ export function useEvolveTasks(
         e.kind === KIND_SHORT_TEXT_NOTE && e.created_at >= stateStartedAt
       );
       
-      const wallEditEvents = events.filter(e => 
-        e.kind === KIND_WALL_EDIT && e.created_at >= stateStartedAt
+      const profileTabsEvents = events.filter(e => 
+        e.kind === KIND_PROFILE_TABS && e.created_at >= stateStartedAt
       );
       
       // Get latest profile after start
@@ -211,7 +211,7 @@ export function useEvolveTasks(
         themeEvents,
         colorMomentEvents,
         postEvents,
-        wallEditEvents,
+        profileTabsEvents,
         profileAfter,
       };
     },
@@ -287,20 +287,21 @@ export function useEvolveTasks(
     // No action - just interact with Blobbi
   });
   
-  // 5. Edit Wall once (PERSISTENT)
-  const wallEditCount = data?.wallEditEvents?.length ?? 0;
-  const hasWallEdit = wallEditCount >= 1;
+  // 5. Edit Profile once (PERSISTENT) — kind 0 profile metadata OR kind 16769 custom tabs
+  const hasTabsEdit = (data?.profileTabsEvents?.length ?? 0) >= 1;
+  const hasMetadataEdit = !!data?.profileAfter;
+  const hasProfileEdit = hasTabsEdit || hasMetadataEdit;
   tasks.push({
-    id: 'edit_wall',
-    name: 'Edit Your Wall',
-    description: 'Customize your profile wall',
-    current: hasWallEdit ? 1 : 0,
+    id: 'edit_profile',
+    name: 'Edit Your Profile',
+    description: 'Update your profile info or customize your profile tabs',
+    current: hasProfileEdit ? 1 : 0,
     required: 1,
-    completed: hasWallEdit,
+    completed: hasProfileEdit,
     type: 'persistent',
     action: 'navigate',
     actionTarget: '/settings/profile',
-    actionLabel: 'Edit Wall',
+    actionLabel: 'Edit Profile',
   });
   
   // ─── Compute DYNAMIC Task (stat-based, NEVER cached) ───

src/blobbi/actions/hooks/useHatchTasks.ts

@@ -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 ────────────────────────────────────────────────────────────────
 
@@ -33,13 +34,10 @@ export const KIND_SHORT_TEXT_NOTE = 1;
 export const HATCH_REQUIRED_INTERACTIONS = 7;
 
 /** Required hashtags for the Blobbi post (excludes Blobbi name, which is dynamic) */
-export const BLOBBI_POST_REQUIRED_HASHTAGS = ['blobbi', 'ditto', 'nostr'];
+export const BLOBBI_POST_REQUIRED_HASHTAGS = ['blobbi'];
 
-/** 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;
+/** Prefix text for Blobbi hatch post (the Blobbi name is appended after this) */
+export const BLOBBI_POST_PREFIX = 'Posting to hatch';
 
 // Legacy export for backwards compatibility
 export const REQUIRED_INTERACTIONS = HATCH_REQUIRED_INTERACTIONS;
@@ -112,16 +110,28 @@ export interface HatchTasksResult {
 
 // ─── Helper Functions ─────────────────────────────────────────────────────────
 
+/**
+ * Build the required phrase for a hatch post.
+ * Format: "Posting to hatch {CapitalizedName} #blobbi"
+ */
+export function buildHatchPhrase(blobbiName: string): string {
+  const capitalized = blobbiName.charAt(0).toUpperCase() + blobbiName.slice(1);
+  return `${BLOBBI_POST_PREFIX} ${capitalized} #blobbi`;
+}
+
 /**
  * Check if a post is a valid Blobbi hatch post.
- * Must contain the required prefix and all required hashtags including the Blobbi name.
+ * The post must contain the required phrase: "Posting to hatch {Name} #blobbi"
+ * The user may add extra text before or after it.
  * 
  * @param event - The Nostr event to validate
- * @param blobbiName - The Blobbi's name (will be sanitized and checked as hashtag)
+ * @param blobbiName - The Blobbi's name
  */
 export function isValidHatchPost(event: NostrEvent, blobbiName: string): boolean {
-  // Check content starts with prefix
-  if (!event.content.startsWith(BLOBBI_POST_PREFIX)) {
+  const phrase = buildHatchPhrase(blobbiName);
+
+  // The phrase must appear somewhere in the content
+  if (!event.content.includes(phrase)) {
     return false;
   }
   
@@ -130,18 +140,12 @@ export function isValidHatchPost(event: NostrEvent, blobbiName: string): boolean
     .filter(tag => tag[0] === 't')
     .map(tag => tag[1]?.toLowerCase());
   
-  // All required hashtags must be present
+  // All required hashtags must be present as t tags
   const hasRequiredHashtags = BLOBBI_POST_REQUIRED_HASHTAGS.every(required => 
     hashtags.includes(required.toLowerCase())
   );
   
-  if (!hasRequiredHashtags) {
-    return false;
-  }
-  
-  // Blobbi name hashtag must also be present
-  const blobbiHashtag = sanitizeToHashtag(blobbiName);
-  return hashtags.includes(blobbiHashtag);
+  return hasRequiredHashtags;
 }
 
 // Legacy function name for backwards compatibility
@@ -158,8 +162,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 +327,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');

src/blobbi/actions/index.ts

@@ -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';
@@ -56,12 +55,9 @@ export {
   getInteractionCount,
   filterPersistentTasks,
   sanitizeToHashtag,
-  isValidHatchPost,
-  isValidBlobbiPost, // Legacy export
   KIND_THEME_DEFINITION,
   KIND_COLOR_MOMENT,
   HATCH_REQUIRED_INTERACTIONS,
-  HATCH_STAT_THRESHOLD,
   REQUIRED_INTERACTIONS, // Legacy export
   BLOBBI_POST_PREFIX,
   BLOBBI_POST_REQUIRED_HASHTAGS,
@@ -72,7 +68,7 @@ export {
   useEvolveTasks,
   getEvolveInteractionCount,
   isValidEvolvePost,
-  KIND_WALL_EDIT,
+  KIND_PROFILE_TABS,
   EVOLVE_REQUIRED_THEMES,
   EVOLVE_REQUIRED_COLOR_MOMENTS,
   EVOLVE_REQUIRED_POSTS,
@@ -88,14 +84,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 +104,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 {

src/blobbi/actions/lib/blobbi-action-utils.ts

@@ -1,24 +1,24 @@
 // 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';
+import { getShopItemById, getLiveShopItems } from '@/blobbi/shop/lib/blobbi-shop-items';
 
 // ─── Action Types ─────────────────────────────────────────────────────────────
 
 /**
- * Actions that consume inventory items
+ * Item-based care actions (use a shop catalog item on the companion)
  */
 export type InventoryAction = 'feed' | 'play' | 'clean' | 'medicine';
 
 /**
- * Non-inventory actions that don't consume items
- * These actions affect stats directly without using shop items.
+ * Direct actions that don't use items.
+ * These actions affect stats directly without selecting a shop item.
  */
 export type DirectAction = 'play_music' | 'sing';
 
 /**
- * All Blobbi actions (inventory + direct)
+ * All Blobbi actions (item-based + direct)
  */
 export type BlobbiAction = InventoryAction | DirectAction;
 
@@ -33,7 +33,7 @@ export const ACTION_TO_ITEM_TYPE: Record<InventoryAction, ShopItemCategory> = {
 };
 
 /**
- * Action metadata for UI display (inventory actions)
+ * Action metadata for UI display (item-based care actions)
  */
 export const ACTION_METADATA: Record<InventoryAction, { label: string; description: string; icon: string }> = {
   feed: {
@@ -59,7 +59,7 @@ export const ACTION_METADATA: Record<InventoryAction, { label: string; descripti
 };
 
 /**
- * Action metadata for direct actions (non-inventory)
+ * Action metadata for direct actions (no item required)
  */
 export const DIRECT_ACTION_METADATA: Record<DirectAction, { label: string; description: string; icon: string }> = {
   play_music: {
@@ -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 };
 }
 
@@ -275,10 +270,10 @@ export function hasHappinessEffectForEgg(effects: ItemEffect | undefined): boole
   return effects.happiness !== undefined && effects.happiness !== 0;
 }
 
-// ─── Inventory Helpers ────────────────────────────────────────────────────────
+// ─── Item Helpers ─────────────────────────────────────────────────────────────
 
 /**
- * Resolved inventory item with shop metadata
+ * Resolved catalog item with shop metadata
  */
 export interface ResolvedInventoryItem {
   itemId: string;
@@ -290,7 +285,7 @@ export interface ResolvedInventoryItem {
 }
 
 /**
- * Options for filtering inventory by action
+ * Options for filtering catalog items by action
  */
 export interface FilterInventoryOptions {
   /** Companion stage - used to filter items by egg-compatible effects */
@@ -298,8 +293,8 @@ export interface FilterInventoryOptions {
 }
 
 /**
- * Filter inventory items by action type.
- * Returns resolved items with shop metadata.
+ * Get all available items for an action type from the shop catalog.
+ * Items are abilities/tools — no inventory ownership is required.
  * 
  * Filtering rules:
  * - Only items matching the action's item type are included
@@ -309,22 +304,20 @@ export interface FilterInventoryOptions {
  *   - clean action: only items with hygiene or happiness effect
  */
 export function filterInventoryByAction(
-  storage: StorageItem[],
+  _storage: StorageItem[],
   action: InventoryAction,
   options: FilterInventoryOptions = {}
 ): ResolvedInventoryItem[] {
   const allowedType = ACTION_TO_ITEM_TYPE[action];
   const result: ResolvedInventoryItem[] = [];
   const isEgg = options.stage === 'egg';
+  const allItems = getLiveShopItems();
 
-  for (const storageItem of storage) {
-    const shopItem = getShopItemById(storageItem.itemId);
-    if (!shopItem) continue;
+  for (const shopItem of allItems) {
     if (shopItem.type !== allowedType) continue;
-    if (storageItem.quantity <= 0) continue;
 
     // Shell Repair Kit: only show for eggs in medicine modal
-    if (storageItem.itemId === SHELL_REPAIR_KIT_ID && !isEgg) {
+    if (shopItem.id === SHELL_REPAIR_KIT_ID && !isEgg) {
       continue;
     }
 
@@ -339,8 +332,8 @@ export function filterInventoryByAction(
     }
 
     result.push({
-      itemId: storageItem.itemId,
-      quantity: storageItem.quantity,
+      itemId: shopItem.id,
+      quantity: Infinity,
       name: shopItem.name,
       icon: shopItem.icon,
       type: shopItem.type,
@@ -381,7 +374,7 @@ export function decrementStorageItem(
 // ─── Stage Restriction Helpers ────────────────────────────────────────────────
 
 /**
- * Stages that can use general inventory items (food, toys, hygiene)
+ * Stages that can use general items (food, toys, hygiene)
  */
 export const GENERAL_ITEM_USABLE_STAGES = ['baby', 'adult'] as const;
 
@@ -414,14 +407,14 @@ export const EGG_VISIBLE_ACTIONS: BlobbiAction[] = ['clean', 'medicine', 'play_m
 export const EGG_ALLOWED_ACTIONS = EGG_ALLOWED_INVENTORY_ACTIONS;
 
 /**
- * Check if a companion can use a specific inventory action.
+ * Check if a companion can use a specific item action.
  * 
  * Note: This function no longer hard-blocks egg actions at the domain layer.
  * UI visibility is handled separately by `isActionVisibleForStage()`.
  * The domain layer allows all actions - UI chooses what to show.
  */
 export function canUseAction(_companion: BlobbiCompanion, _action: InventoryAction): boolean {
-  // All stages can technically use all inventory actions at the domain layer.
+  // All stages can technically use all item actions at the domain layer.
   // UI filtering determines what actions are shown to users.
   return true;
 }
@@ -447,7 +440,7 @@ export function isActionVisibleForStage(stage: 'egg' | 'baby' | 'adult', action:
 }
 
 /**
- * Check if a companion can use general inventory items (feed, play, clean).
+ * Check if a companion can use general items (feed, play, clean).
  * Eggs cannot use food, toys, or hygiene items.
  * @deprecated Use canUseAction(companion, action) for action-specific checks
  */

src/blobbi/actions/lib/blobbi-activity-state.ts

@@ -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,
   };
 }

src/blobbi/actions/lib/blobbi-builtin-tracks.ts

@@ -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')}`;
-}

src/blobbi/actions/lib/blobbi-streak.ts

@@ -21,7 +21,7 @@ import {
   getLocalDayString,
   getDaysDifference,
   type BlobbiCompanion,
-} from '@/lib/blobbi';
+} from '@/blobbi/core/lib/blobbi';
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 

src/blobbi/actions/lib/blobbi-track-catalog.ts

@@ -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')}`;
+}

src/blobbi/actions/lib/blobbi-xp.test.ts

@@ -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);
+    }
+  });
+});

src/blobbi/actions/lib/blobbi-xp.ts

@@ -0,0 +1,136 @@
+/**
+ * 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
+ * - Item actions (feed, play, clean, medicine) give varied XP per action type
+ * - Direct actions (sing, play_music) give moderate XP
+ * - 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 item-based care actions (feed, play, clean, medicine).
+ */
+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 critical - highest item XP
+};
+
+/**
+ * Base XP values for direct actions (play_music, sing).
+ * These actions don't require selecting an item.
+ */
+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 XP gain for an item-based care action.
+ * 
+ * @param action - The action performed
+ * @param quantity - Number of times performed (always 1 in current usage)
+ * @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 (always 1 in current usage)
+ * @returns Object with xpGained and 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!`;
+}

src/blobbi/adult-blobbi/lib/adult-svg-customizer.ts

@@ -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
  */

src/blobbi/adult-blobbi/lib/adult-svg-resolver.ts

@@ -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,

src/blobbi/adult-blobbi/types/adult.types.ts

@@ -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.

src/blobbi/baby-blobbi/lib/baby-svg-customizer.ts

@@ -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
  */

src/blobbi/baby-blobbi/lib/baby-svg-resolver.ts

@@ -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';
 

src/blobbi/baby-blobbi/types/baby.types.ts

@@ -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

src/blobbi/companion/components/BlobbiCompanion.tsx

@@ -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>

src/blobbi/companion/components/BlobbiCompanionLayer.tsx

@@ -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);
-      
+      const result = await contextUseItem(item.id, action);
+
       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}

src/blobbi/companion/components/BlobbiCompanionVisual.tsx

@@ -1,197 +1,212 @@
 /**
  * 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 { useEffectiveEmotion } from '@/blobbi/dev/EmotionDevContext';
+import { BlobbiStageVisual } from '@/blobbi/ui/BlobbiStageVisual';
+import { companionDataToBlobbi } from '@/blobbi/ui/lib/adapters';
+import { useEffectiveEmotion } from '@/blobbi/dev/useEmotionDev';
+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 type { BlobbiCompanion } from '@/blobbi/core/lib/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 +215,60 @@ 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 === 'egg' ? (
+            <BlobbiStageVisual
+              companion={companion as unknown as BlobbiCompanion}
+              size="sm"
+              animated={false}
+              className="size-full"
+            />
+          ) : (
+            <MemoizedBlobbiVisual
+              stage={companion.stage}
+              blobbi={blobbi}
+              eyeOffsetRef={eyeOffsetRef}
+              recipe={effectiveRecipe}
+              recipeLabel={effectiveRecipeLabel}
+              emotion={effectiveEmotion}
+              bodyEffects={effectiveBodyEffects}
+            />
+          )}
+        </div>
       </div>
     </div>
   );

src/blobbi/companion/components/DebugGroundOverlay.tsx

@@ -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>
+      )}
+    </>
+  );
+}

src/blobbi/companion/core/companionMachine.ts

@@ -233,17 +233,18 @@ export function updateDragPosition(motion: CompanionMotion, position: Position):
 }
 
 /**
- * End dragging - let gravity take over.
+ * End dragging - hold position where dropped.
  */
 export function endDrag(motion: CompanionMotion, groundY: number): CompanionMotion {
   return {
     ...motion,
     isDragging: false,
-    // If already at or below ground, snap to ground
-    isGrounded: motion.position.y >= groundY,
+    // Always treat as grounded so companion holds position where dropped
+    isGrounded: true,
     position: {
       ...motion.position,
-      y: motion.position.y >= groundY ? groundY : motion.position.y,
+      // Clamp to ground if below it
+      y: Math.min(motion.position.y, groundY),
     },
   };
 }

src/blobbi/companion/hooks/useActionEmotionOverride.ts

@@ -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 };
+}

src/blobbi/companion/hooks/useBlobbiCompanion.ts

@@ -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 */
@@ -98,7 +104,8 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
   // Track if first entry has completed (for position initialization)
   const [hasEnteredOnce, setHasEnteredOnce] = useState(false);
   
-  // Track viewport size
+  // Track viewport size — listen to both window resize and visualViewport
+  // (mobile browsers fire visualViewport resize when URL bar shows/hides)
   useEffect(() => {
     const handleResize = () => {
       setViewport({
@@ -108,7 +115,11 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
     };
     
     window.addEventListener('resize', handleResize, { passive: true });
-    return () => window.removeEventListener('resize', handleResize);
+    window.visualViewport?.addEventListener('resize', handleResize, { passive: true });
+    return () => {
+      window.removeEventListener('resize', handleResize);
+      window.visualViewport?.removeEventListener('resize', handleResize);
+    };
   }, []);
   
   // Calculate bounds and positions
@@ -128,10 +139,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 +215,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 +229,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 +252,7 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
     targetX,
     energy: companion?.energy ?? 50,
     onReachedTarget,
+    sharedMotionRef: motionRef,
   });
   
   // Entry animation management (handles route changes and companion changes)
@@ -292,7 +308,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 +326,7 @@ export function useBlobbiCompanion(): UseBlobbiCompanionResult {
     isVisible: shouldBeVisible,
     state: isEntering ? 'idle' : state,
     motion,
-    gaze,
-    eyeOffset,
+    eyeOffsetRef,
     isEntering,
     entryProgress: entryState.progress,
     entryState,

src/blobbi/companion/hooks/useBlobbiCompanionData.ts

@@ -4,22 +4,16 @@
  * 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.
+ * Uses useBlobbisCollection with a targeted dList (single d-tag) for efficiency.
+ * Optimistic updates from mutations propagate across all blobbi-collection
+ * queries (including BlobbiPage's 'all' mode) via updateCompanionEvent.
  */
 
 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 +30,78 @@ 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 (targeted fetch)
+ * 3. Use useBlobbisCollection with the dList 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
+ * - Optimistic updates propagate across all blobbi-collection queries
+ * - Projected decay recalculates every 60 seconds while mounted
  */
 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,
   };
 }

src/blobbi/companion/hooks/useBlobbiCompanionGaze.ts

@@ -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,
   };
 }

src/blobbi/companion/hooks/useBlobbiCompanionMotion.ts

@@ -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) => {

src/blobbi/companion/hooks/useBlobbiCompanionState.ts

@@ -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(() => {
@@ -98,7 +102,7 @@ export function useBlobbiCompanionState({
     setState('walking');
     setDirection('right');
     setTargetX(targetX);
-  }, [bounds.maxX]);
+  }, [bounds.maxX, motionRef]);
   
   /**
    * Generate a random observation target on screen.
@@ -132,11 +136,11 @@ export function useBlobbiCompanionState({
     setState('walking');
     setDirection(newDirection);
     setTargetX(targetXPos);
-  }, [bounds, generateObservationTarget]);
+  }, [bounds, generateObservationTarget, motionRef]);
   
   // 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, motionRef]);
   
   // 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, motionRef]);
   
   // 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(() => {

src/blobbi/companion/hooks/useBlobbiEntryAnimation.ts

@@ -19,9 +19,8 @@
  *   idle -> rising -> inspecting -> entering -> complete
  * 
  * Route change behavior:
- * - Cancels current entry immediately
- * - Waits 1 second
- * - Restarts entry for the new page
+ * - Companion keeps its current position (no re-entry animation)
+ * - Only initial mount and companion changes trigger entry animations
  */
 
 import { useState, useEffect, useRef, useCallback } from 'react';
@@ -310,20 +309,11 @@ export function useBlobbiEntryAnimation({
       // Random entry type for new companion (fall or rise)
       const entryType: EntryType = Math.random() < 0.5 ? 'fall' : 'rise';
       startEntry(entryType);
-    } else if (routeChanged && companionId) {
-      // Route changed - determine direction for new route
-      const entryType = getEntryDirection(previousPath, pathname, sidebarOrder);
-      
-      // Immediately hide Blobbi and cancel current entry
-      cancelEntry();
-      setIsHiddenForTransition(true);
-      
-      // Wait 1 second, then start the new entry animation
-      routeChangeTimeoutRef.current = setTimeout(() => {
-        startEntry(entryType);
-      }, entryConfig.routeChangeRestartDelay);
+    } else if (routeChanged) {
+      // Route changed - companion keeps its position, no re-entry animation.
+      // Just update the ref so future changes compare against the new path.
     }
-  }, [isActive, pathname, companionId, sidebarOrder, startEntry, cancelEntry, entryConfig.routeChangeRestartDelay]);
+  }, [isActive, pathname, companionId, sidebarOrder, startEntry, cancelEntry]);
   
   /**
    * Animation loop for FALL entry.

src/blobbi/companion/hooks/useCompanionItemReaction.ts

@@ -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';

src/blobbi/companion/interaction/BlobbiActionsContext.ts

@@ -15,17 +15,15 @@ import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'r
 import { useBlobbiItemUse } from './useBlobbiItemUse';
 import {
   BlobbiActionsContext,
-  BlobbiActionsProvider,
   type UseItemFunction,
   type UseItemResult,
   type BlobbiActionsContextValue,
   type BlobbiActionsContextInternal,
-} from './BlobbiActionsProvider';
+} from './BlobbiActionsContextDef';
 
-// Re-export everything from the provider module for backward compatibility
+// Re-export types and context from the def module for backward compatibility
 export {
   BlobbiActionsContext,
-  BlobbiActionsProvider,
   type UseItemFunction,
   type UseItemResult,
   type BlobbiActionsContextValue,
@@ -64,13 +62,13 @@ export function useBlobbiActions(): BlobbiActionsContextValue {
   // Create stable useItem function that:
   // 1. Uses registered function if available (from BlobbiPage)
   // 2. Falls back to built-in hook if no registration
-  const useItem = useCallback<UseItemFunction>(async (itemId, action, quantity = 1) => {
+  const useItem = useCallback<UseItemFunction>(async (itemId, action) => {
     // Try registered function first (from BlobbiPage)
     if (context?.registerRef.current) {
       if (import.meta.env.DEV) {
         console.log('[BlobbiActions] Using registered item-use function');
       }
-      return context.registerRef.current(itemId, action, quantity);
+      return context.registerRef.current(itemId, action);
     }
     
     // Check if fallback can handle it
@@ -88,7 +86,7 @@ export function useBlobbiActions(): BlobbiActionsContextValue {
     if (import.meta.env.DEV) {
       console.log('[BlobbiActions] Using fallback item-use hook');
     }
-    return fallbackItemUse.useItem(itemId, action, quantity);
+    return fallbackItemUse.useItem(itemId, action);
   }, [context, fallbackItemUse]);
   
   // Determine canUseItems: true if registered OR fallback can use
@@ -136,14 +134,14 @@ export function useBlobbiActionsRegistration(
   useItemRef.current = useItemFn;
   
   // Create a stable wrapper that delegates to the ref
-  const stableUseItem = useCallback<UseItemFunction>(async (itemId, action, quantity = 1) => {
+  const stableUseItem = useCallback<UseItemFunction>(async (itemId, action) => {
     if (!useItemRef.current) {
       return {
         success: false,
         error: 'Item use function not available',
       };
     }
-    return useItemRef.current(itemId, action, quantity);
+    return useItemRef.current(itemId, action);
   }, []);
   
   // Update refs and notify only when canUseItems actually changes

src/blobbi/companion/interaction/BlobbiActionsContextDef.ts

@@ -0,0 +1,75 @@
+/**
+ * BlobbiActionsContextDef
+ *
+ * Lightweight context definition and types for the Blobbi actions system.
+ * Separated from the provider component to avoid react-refresh warnings.
+ */
+
+import { createContext } from 'react';
+
+import type { InventoryAction } from '@/blobbi/actions/lib/blobbi-action-utils';
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+/**
+ * Result of using an item via the context.
+ */
+export interface UseItemResult {
+  /** Whether the use was successful */
+  success: boolean;
+  /** Stats that changed (key = stat name, value = delta) */
+  statsChanged?: Record<string, number>;
+  /** Error message if failed */
+  error?: string;
+}
+
+/**
+ * Function signature for using an item (always uses once).
+ */
+export type UseItemFunction = (
+  itemId: string,
+  action: InventoryAction,
+) => Promise<UseItemResult>;
+
+/**
+ * Context value for Blobbi actions (consumer side).
+ */
+export interface BlobbiActionsContextValue {
+  /**
+   * Use an item on the current companion.
+   * Works even without BlobbiPage registration (uses fallback).
+   */
+  useItem: UseItemFunction;
+
+  /** Whether an item use operation is currently in progress */
+  isUsingItem: boolean;
+
+  /** Whether items can be used (companion exists and profile loaded) */
+  canUseItems: boolean;
+
+  /** Check if an item is on cooldown (recently attempted) */
+  isItemOnCooldown: (itemId: string) => boolean;
+
+  /** Clear cooldown for an item */
+  clearItemCooldown: (itemId: string) => void;
+}
+
+/**
+ * Internal context value (includes registration functions).
+ */
+export interface BlobbiActionsContextInternal {
+  /** Register item-use functionality (called by BlobbiPage) */
+  registerRef: React.MutableRefObject<UseItemFunction | null>;
+  /** Whether items can currently be used (via registration) */
+  canUseItemsRegisteredRef: React.MutableRefObject<boolean>;
+  /** Whether an item is currently being used (via registration) */
+  isUsingItemRegisteredRef: React.MutableRefObject<boolean>;
+  /** Force update consumers (called sparingly) */
+  notifyUpdate: () => void;
+  /** Subscribe to updates */
+  subscribe: (callback: () => void) => () => void;
+}
+
+// ─── Context ──────────────────────────────────────────────────────────────────
+
+export const BlobbiActionsContext = createContext<BlobbiActionsContextInternal | null>(null);

src/blobbi/companion/interaction/BlobbiActionsProvider.tsx

@@ -10,75 +10,13 @@
  * BlobbiPage, both of which are lazy-loaded.
  */
 
-import { createContext, useCallback, useMemo, useRef, type ReactNode } from 'react';
+import { useCallback, useMemo, useRef, type ReactNode } from 'react';
 
-import type { InventoryAction } from '@/blobbi/actions/lib/blobbi-action-utils';
-
-// ─── Types ────────────────────────────────────────────────────────────────────
-
-/**
- * Result of using an item via the context.
- */
-export interface UseItemResult {
-  /** Whether the use was successful */
-  success: boolean;
-  /** Stats that changed (key = stat name, value = delta) */
-  statsChanged?: Record<string, number>;
-  /** Error message if failed */
-  error?: string;
-}
-
-/**
- * Function signature for using an item.
- */
-export type UseItemFunction = (
-  itemId: string,
-  action: InventoryAction,
-  quantity?: number
-) => Promise<UseItemResult>;
-
-/**
- * Context value for Blobbi actions (consumer side).
- */
-export interface BlobbiActionsContextValue {
-  /**
-   * Use an inventory item on the current companion.
-   * Works even without BlobbiPage registration (uses fallback).
-   */
-  useItem: UseItemFunction;
-
-  /** Whether an item use operation is currently in progress */
-  isUsingItem: boolean;
-
-  /** Whether items can be used (companion exists and profile loaded) */
-  canUseItems: boolean;
-
-  /** Check if an item is on cooldown (recently attempted) */
-  isItemOnCooldown: (itemId: string) => boolean;
-
-  /** Clear cooldown for an item */
-  clearItemCooldown: (itemId: string) => void;
-}
-
-/**
- * Internal context value (includes registration functions).
- */
-export interface BlobbiActionsContextInternal {
-  /** Register item-use functionality (called by BlobbiPage) */
-  registerRef: React.MutableRefObject<UseItemFunction | null>;
-  /** Whether items can currently be used (via registration) */
-  canUseItemsRegisteredRef: React.MutableRefObject<boolean>;
-  /** Whether an item is currently being used (via registration) */
-  isUsingItemRegisteredRef: React.MutableRefObject<boolean>;
-  /** Force update consumers (called sparingly) */
-  notifyUpdate: () => void;
-  /** Subscribe to updates */
-  subscribe: (callback: () => void) => () => void;
-}
-
-// ─── Context ──────────────────────────────────────────────────────────────────
-
-export const BlobbiActionsContext = createContext<BlobbiActionsContextInternal | null>(null);
+import {
+  BlobbiActionsContext,
+  type UseItemFunction,
+  type BlobbiActionsContextInternal,
+} from './BlobbiActionsContextDef';
 
 // ─── Provider ─────────────────────────────────────────────────────────────────
 
@@ -100,7 +38,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());
 

src/blobbi/companion/interaction/CompanionActionMenu.tsx

@@ -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>
         );

src/blobbi/companion/interaction/HangingItems.tsx

@@ -1,26 +1,24 @@
 /**
  * HangingItems
  * 
- * Displays inventory items as hanging elements from the top of the screen.
+ * Displays available items as hanging elements from the top of the screen.
  * Each item appears as a circle connected to the top by a thin vertical line,
  * creating a playful, spatial feel.
  * 
+ * Items are reusable abilities sourced from the shop catalog — they are
+ * always available and not consumed on use.
+ * 
  * State Model:
  * - Container states: hidden → opening → open → closing → hidden
- * - Hanging items = available inventory that can still be released
+ * - Hanging items = catalog items available for the selected action
  * - Released/dropped items = instances currently in the world (tracked with unique IDs)
  * - Multiple instances of the same item type can exist simultaneously on the ground
  * 
- * Key Design Principle:
- * The hanging row represents "releasable quantity" - clicking releases ONE instance
- * and immediately decrements the visible quantity. A new hanging copy remains if
- * quantity > 1. The released instance tracks separately with a unique instance ID.
- * 
  * Features:
  * - Smooth open/close slide animations (items descend/ascend)
  * - Thin vertical lines from the top of screen
  * - Circular containers for hanging items
- * - Click releases item: one instance falls, remaining quantity stays hanging
+ * - Click releases item: one instance falls to the ground
  * - Multiple dropped instances of same item type can exist
  * - Contact detection: items auto-use when touching Blobbi
  * - Click-to-use: click landed items to use them
@@ -119,7 +117,7 @@ interface HangingItemsProps {
   onItemUse?: (item: CompanionItem) => Promise<ItemUseAttemptResult>;
   /** 
    * Callback when an item is collected by Blobbi (contact).
-   * @deprecated Use onItemUse instead for proper item consumption flow.
+   * @deprecated Use onItemUse instead for proper item-use flow.
    */
   onItemCollected?: (item: CompanionItem) => void;
   /**
@@ -156,7 +154,7 @@ const HANGING_CONFIG = {
   baseFallDistance: 500,
   /** Ground offset from bottom of viewport */
   defaultGroundOffset: 40,
-  /** Size of quantity badge */
+  /** Size of badge (unused — kept for config consistency) */
   badgeSize: 20,
   /** Size of landed item hitbox for contact detection */
   landedItemSize: 40,
@@ -406,7 +404,7 @@ export function HangingItems({
   
   // Track how many instances of each item type have been released (not yet used)
   // Key: item.id (type ID), Value: count of released instances
-  const [releasedCountByItemId, setReleasedCountByItemId] = useState<Map<string, number>>(new Map());
+  const [_releasedCountByItemId, setReleasedCountByItemId] = useState<Map<string, number>>(new Map());
   
   // Counter for generating unique instance IDs
   const instanceCounterRef = useRef(0);
@@ -566,7 +564,7 @@ export function HangingItems({
     
     // Start the loop
     animationRef.current = requestAnimationFrame(animate);
-  }, []);
+  }, [calculateFallDuration]);
   
   // Cleanup animation on unmount
   useEffect(() => {
@@ -670,7 +668,7 @@ export function HangingItems({
           });
           // Also remove from zone tracking
           itemsInZoneRef.current.delete(instanceId);
-          // Decrement the released count for this item type (since the instance is now consumed)
+          // Decrement the released count for this item type (instance removed from screen)
           setReleasedCountByItemId(prev => {
             const next = new Map(prev);
             const currentCount = next.get(item.id) || 0;
@@ -985,15 +983,9 @@ export function HangingItems({
     return viewportCenterX + startX + index * HANGING_CONFIG.itemSpacing;
   };
   
-  // Calculate hanging items with their remaining quantities
-  // An item appears in the hanging row if (quantity - releasedCount) > 0
-  const hangingItems = items
-    .map(item => {
-      const releasedCount = releasedCountByItemId.get(item.id) || 0;
-      const remainingQuantity = item.quantity - releasedCount;
-      return { ...item, quantity: remainingQuantity };
-    })
-    .filter(item => item.quantity > 0);
+  // All items are always visible — they are abilities, not consumable inventory.
+  // No quantity filtering needed.
+  const hangingItems = items;
   
   // Should we render the hanging container?
   const shouldRenderContainer = containerState !== 'hidden' || (isVisible && selectedAction);
@@ -1033,7 +1025,7 @@ export function HangingItems({
         >
           <div className="bg-background/95 backdrop-blur-sm rounded-2xl px-6 py-4 shadow-lg border">
             <p className="text-sm text-muted-foreground text-center">
-              No {getMenuActionConfig(selectedAction)?.label.toLowerCase()} items in your inventory
+              No {getMenuActionConfig(selectedAction)?.label.toLowerCase()} items available
             </p>
           </div>
         </div>
@@ -1102,8 +1094,8 @@ export function HangingItems({
                       marginLeft: (HANGING_CONFIG.circleSize / 2) * -1 + HANGING_CONFIG.lineWidth / 2,
                     }}
                     onClick={() => handleItemClick(item, itemX)}
-                    title={`${item.name} (x${item.quantity})`}
-                    aria-label={`${item.name}, quantity ${item.quantity}. Click to release.`}
+                    title={item.name}
+                    aria-label={`${item.name}. Click to release.`}
                   >
                     {/* Item emoji */}
                     <span 
@@ -1114,24 +1106,6 @@ export function HangingItems({
                     >
                       {item.emoji}
                     </span>
-                    
-                    {/* Quantity badge */}
-                    <span
-                      className={cn(
-                        "absolute -top-1 -right-1",
-                        "flex items-center justify-center",
-                        "bg-primary text-primary-foreground",
-                        "text-xs font-semibold rounded-full",
-                        "shadow-md"
-                      )}
-                      style={{
-                        minWidth: HANGING_CONFIG.badgeSize,
-                        height: HANGING_CONFIG.badgeSize,
-                        padding: '0 5px',
-                      }}
-                    >
-                      {item.quantity}
-                    </span>
                   </button>
                 </div>
               );

src/blobbi/companion/interaction/index.ts

@@ -76,10 +76,10 @@ export { useBlobbiItemUse } from './useBlobbiItemUse';
 // Context
 export {
   BlobbiActionsContext,
-  BlobbiActionsProvider,
   useBlobbiActions,
   useBlobbiActionsRegistration,
 } from './BlobbiActionsContext';
+export { BlobbiActionsProvider } from './BlobbiActionsProvider';
 
 // Components
 export { CompanionActionMenu } from './CompanionActionMenu';

src/blobbi/companion/interaction/needDetection.ts

@@ -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 ─────────────────────────────────────────────────

src/blobbi/companion/interaction/types.ts

@@ -63,7 +63,7 @@ export function getItemCategoryForAction(actionId: CompanionMenuAction): ShopIte
 
 /**
  * Normalized item representation for the companion UI.
- * This is a simplified view of inventory items optimized for rendering.
+ * This is a simplified view of shop catalog items optimized for rendering.
  */
 export interface CompanionItem {
   /** Unique item ID (matches shop item ID) */
@@ -74,7 +74,7 @@ export interface CompanionItem {
   emoji: string;
   /** Item category */
   category: ShopItemCategory;
-  /** Quantity available in inventory */
+  /** Availability (always Infinity — items are reusable abilities) */
   quantity: number;
   /** Item effects when used */
   effect?: ItemEffect;

src/blobbi/companion/interaction/useBlobbiItemUse.ts

@@ -27,21 +27,17 @@ 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 } from '@/blobbi/core/lib/blobbi';
 import {
   KIND_BLOBBI_STATE,
-  KIND_BLOBBONAUT_PROFILE,
   updateBlobbiTags,
-  updateBlobbonautTags,
-  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,
-  decrementStorageItem,
   canUseAction,
   canUseItemForStage,
   getStageRestrictionMessage,
@@ -59,7 +55,7 @@ import { getStreakTagUpdates } from '@/blobbi/actions/lib/blobbi-streak';
 import { HATCH_REQUIRED_INTERACTIONS } from '@/blobbi/actions/hooks/useHatchTasks';
 import { EVOLVE_REQUIRED_INTERACTIONS } from '@/blobbi/actions/hooks/useEvolveTasks';
 
-import type { UseItemFunction } from './BlobbiActionsProvider';
+import type { UseItemFunction } from './BlobbiActionsContextDef';
 
 // ─── Configuration ────────────────────────────────────────────────────────────
 
@@ -126,7 +122,7 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
   const queryClient = useQueryClient();
   
   // Fetch profile if not provided
-  const { profile: fetchedProfile, updateProfileEvent } = useBlobbonautProfile();
+  const { profile: fetchedProfile } = useBlobbonautProfile();
   const profile = options.profile ?? fetchedProfile;
   
   // Per-item cooldown tracking (ref to avoid re-renders)
@@ -188,29 +184,58 @@ 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] 
     });
   }, [queryClient, user?.pubkey, profile?.currentCompanion]);
   
-  // Core mutation for using items
+  // Core mutation for using items (always uses once)
   const mutation = useMutation({
     mutationFn: async ({ 
       itemId, 
       action, 
-      quantity = 1,
     }: { 
       itemId: string; 
       action: InventoryAction; 
-      quantity?: number;
     }): Promise<{ statsChanged: Record<string, number> }> => {
       // ─── Validation ───
       if (!user?.pubkey) {
@@ -228,11 +253,6 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
         throw new Error('No companion selected');
       }
       
-      // Validate quantity
-      if (quantity < 1) {
-        throw new Error('Quantity must be at least 1');
-      }
-      
       // Check stage restrictions
       if (!canUseAction(companion, action)) {
         const message = getStageRestrictionMessage(companion, action);
@@ -252,15 +272,6 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
         throw new Error(itemUsability.reason ?? 'This item cannot be used by this companion');
       }
       
-      // Validate item exists in storage with sufficient quantity
-      const storageItem = profile.storage.find(s => s.itemId === itemId);
-      if (!storageItem || storageItem.quantity <= 0) {
-        throw new Error('Item not found in your inventory');
-      }
-      if (storageItem.quantity < quantity) {
-        throw new Error(`Not enough items in inventory (have ${storageItem.quantity}, need ${quantity})`);
-      }
-      
       // Validate item has effects
       if (!shopItem.effect) {
         throw new Error('This item has no effect');
@@ -288,17 +299,13 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
       // Start with decayed stats as the base
       const statsAfterDecay = decayResult.stats;
       
-      // ─── Apply Item Effects ───
+      // ─── Apply Item Effects (single use) ───
       const isEggCompanion = companion.stage === 'egg';
       const statsUpdate: Record<string, string> = {};
       const statsChanged: Record<string, number> = {};
       
       if (isEggCompanion && action === 'medicine') {
-        const healthDelta = shopItem.effect.health ?? 0;
-        let currentHealth = statsAfterDecay.health ?? 0;
-        for (let i = 0; i < quantity; i++) {
-          currentHealth = applyStat(currentHealth, healthDelta);
-        }
+        const currentHealth = applyStat(statsAfterDecay.health ?? 0, shopItem.effect.health ?? 0);
         
         statsUpdate.health = currentHealth.toString();
         statsChanged.health = currentHealth - (statsAfterDecay.health ?? 0);
@@ -308,15 +315,8 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
         statsUpdate.hunger = '100';
         statsUpdate.energy = '100';
       } else if (isEggCompanion && action === 'clean') {
-        const hygieneDelta = shopItem.effect.hygiene ?? 0;
-        const happinessDelta = shopItem.effect.happiness ?? 0;
-        
-        let currentHygiene = statsAfterDecay.hygiene ?? 0;
-        let currentHappiness = statsAfterDecay.happiness ?? 0;
-        for (let i = 0; i < quantity; i++) {
-          currentHygiene = applyStat(currentHygiene, hygieneDelta);
-          currentHappiness = applyStat(currentHappiness, happinessDelta);
-        }
+        const currentHygiene = applyStat(statsAfterDecay.hygiene ?? 0, shopItem.effect.hygiene ?? 0);
+        const currentHappiness = applyStat(statsAfterDecay.happiness ?? 0, shopItem.effect.happiness ?? 0);
         
         statsUpdate.hygiene = currentHygiene.toString();
         statsChanged.hygiene = currentHygiene - (statsAfterDecay.hygiene ?? 0);
@@ -331,11 +331,8 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
         statsUpdate.hunger = '100';
         statsUpdate.energy = '100';
       } else {
-        // Normal stats application for baby/adult
-        let currentStats: Partial<BlobbiStats> = { ...statsAfterDecay };
-        for (let i = 0; i < quantity; i++) {
-          currentStats = applyItemEffects(currentStats, shopItem.effect);
-        }
+        // Normal stats application for baby/adult — apply once
+        const currentStats = applyItemEffects({ ...statsAfterDecay }, shopItem.effect);
         
         statsUpdate.hunger = clampStat(currentStats.hunger).toString();
         statsChanged.hunger = (currentStats.hunger ?? 0) - (statsAfterDecay.hunger ?? 0);
@@ -383,36 +380,19 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
       
       updateCompanionInCache(blobbiEvent);
       
-      // ─── Update Profile Storage (kind 11125) ───
-      const newStorage = decrementStorageItem(profile.storage, itemId, quantity);
-      const storageValues = createStorageTags(newStorage).map(tag => tag[1]);
-      
-      const profileTags = updateBlobbonautTags(profile.allTags, {
-        storage: storageValues,
-      });
-      
-      const profileEvent = await publishEvent({
-        kind: KIND_BLOBBONAUT_PROFILE,
-        content: '',
-        tags: profileTags,
-      });
-      
-      updateProfileEvent(profileEvent);
-      
       // ─── Invalidate Queries ───
-      queryClient.invalidateQueries({ queryKey: ['blobbonaut-profile', user.pubkey] });
+      // Items are free to use — no storage decrement needed.
       queryClient.invalidateQueries({ queryKey: ['blobbi-collection', user.pubkey] });
       
       return { statsChanged };
     },
-    onSuccess: (_, { itemId, action, quantity = 1 }) => {
+    onSuccess: (_, { itemId, action }) => {
       const shopItem = getShopItemById(itemId);
       const actionMeta = ACTION_METADATA[action];
-      const quantityText = quantity > 1 ? ` (x${quantity})` : '';
       
       toast({
         title: `${actionMeta.label} successful!`,
-        description: `Used ${shopItem?.name ?? 'item'}${quantityText} on your Blobbi.`,
+        description: `Used ${shopItem?.name ?? 'item'} on your Blobbi.`,
       });
       
       // Track daily mission progress
@@ -437,7 +417,7 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
   });
   
   // Wrapper function that matches UseItemFunction signature and includes cooldown check
-  const useItem = useCallback<UseItemFunction>(async (itemId, action, quantity = 1) => {
+  const useItem = useCallback<UseItemFunction>(async (itemId, action) => {
     // Check cooldown first
     if (isItemOnCooldown(itemId)) {
       if (import.meta.env.DEV) {
@@ -450,7 +430,7 @@ export function useBlobbiItemUse(options: UseBlobbiItemUseOptions = {}): UseBlob
     }
     
     try {
-      const result = await mutation.mutateAsync({ itemId, action, quantity });
+      const result = await mutation.mutateAsync({ itemId, action });
       return {
         success: true,
         statsChanged: result.statsChanged,

src/blobbi/companion/interaction/useBlobbiSleepToggle.ts

@@ -0,0 +1,183 @@
+/**
+ * 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) 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.
+    // No invalidation needed — we fetched fresh from relays before mutating,
+    // so the optimistic update is the correct state.
+    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),
+      });
+    }
+  }, [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
+  };
+}

src/blobbi/companion/interaction/useCompanionActionMenu.ts

@@ -18,8 +18,7 @@ import { useState, useCallback, useEffect, useMemo } from 'react';
 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 { getLiveShopItems } from '@/blobbi/shop/lib/blobbi-shop-items';
 import { canUseItemForStage } from '@/blobbi/actions/lib/blobbi-action-utils';
 
 import type {
@@ -68,7 +67,10 @@ interface UseCompanionActionMenuResult {
 }
 
 /**
- * Resolve inventory items for a specific action/category.
+ * Resolve available items for a specific action/category from the shop catalog.
+ * 
+ * Items are sourced from the full shop catalog — all items are
+ * available as reusable abilities/tools, filtered only by stage.
  * 
  * Uses the centralized `canUseItemForStage` function to ensure consistent
  * stage-based filtering across all UIs:
@@ -80,7 +82,6 @@ interface UseCompanionActionMenuResult {
  * filters out all egg-only items from the companion interaction system.
  */
 function resolveItemsForAction(
-  storage: StorageItem[],
   action: CompanionMenuAction,
   stage: 'egg' | 'baby' | 'adult'
 ): CompanionItem[] {
@@ -89,13 +90,10 @@ function resolveItemsForAction(
   // Sleep action has no items
   if (!category) return [];
   
+  const allItems = getLiveShopItems();
   const items: CompanionItem[] = [];
   
-  for (const storageItem of storage) {
-    if (storageItem.quantity <= 0) continue;
-    
-    const shopItem = getShopItemById(storageItem.itemId);
-    if (!shopItem) continue;
+  for (const shopItem of allItems) {
     if (shopItem.type !== category) continue;
     
     // Use centralized stage-based filtering
@@ -104,17 +102,17 @@ function resolveItemsForAction(
     // - Food/Toys: only for baby/adult (excluded for eggs)
     // - Medicine: must have health effect
     // - Hygiene: must have hygiene or happiness effect
-    const usability = canUseItemForStage(storageItem.itemId, stage);
+    const usability = canUseItemForStage(shopItem.id, stage);
     if (!usability.canUse) {
       continue;
     }
     
     items.push({
-      id: storageItem.itemId,
+      id: shopItem.id,
       name: shopItem.name,
       emoji: shopItem.icon,
       category: shopItem.type,
-      quantity: storageItem.quantity,
+      quantity: Infinity,
       effect: shopItem.effect,
     });
   }
@@ -197,8 +195,8 @@ export function useCompanionActionMenu({
       return;
     }
     
-    // Resolve items for this action
-    const items = resolveItemsForAction(profile.storage, action, stage);
+    // Resolve items for this action from the catalog (not inventory)
+    const items = resolveItemsForAction(action, stage);
     
     setMenuState(prev => ({
       ...prev,