@retray-dev/ui-kit 9.3.1 → 10.0.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v9.3.0)
+# @retray-dev/ui-kit — Component Reference (v10.0.0)
 
 This file is the AI reference for this package. Add all three lines below to your project's `CLAUDE.md` to give Claude full context — components, setup guide, and usage examples:
 
@@ -129,9 +129,49 @@ module.exports = config
 
 All components use **Sohne** as the font family. You **must** load it before rendering any UI kit component.
 
+### How it works
+
+1. When you install `@retray-dev/ui-kit`, the **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project root
+2. You must define `SohneFonts` with static `require()` calls in your `App.tsx` (see boilerplate below)
+3. Pass it to `expo-font`'s `useFonts()` hook at your app root
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
+
+### SohneFonts boilerplate — copy this into your App.tsx
+
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
 
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
@@ -142,18 +182,22 @@ export default function App() {
 }
 ```
 
-**How it works:**
-1. Import `SohneFonts` from `@retray-dev/ui-kit/fonts` (separate export path)
-2. Pass it to `expo-font`'s `useFonts()` hook at your app root
-3. Metro resolves font files from `node_modules/@retray-dev/ui-kit/src/assets/fonts/` at bundle time
-4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
+### .gitignore recommendation
 
-**Included weights:**
+Fonts are copied to `assets/fonts/sohne/` on install. You can either:
+- **Commit them** (no network needed during CI builds)
+- **Ignore them** (re-copied on every `pnpm install`)
+
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+# Either commit these or ignore them (re-copied on install)
+assets/fonts/sohne/
+```
+
+**Included weights (28 files):**
 - Sohne: `Sohne-ExtraLight`, `Sohne-Light`, `Sohne-Regular`, `Sohne-Medium`, `Sohne-SemiBold`, `Sohne-Bold`, `Sohne-ExtraBold` + italic variants
 - SohneMono: `SohneMono-ExtraLight`, `SohneMono-Light`, `SohneMono-Regular`, `SohneMono-Medium`, `SohneMono-SemiBold`, `SohneMono-Bold`, `SohneMono-ExtraBold` + italic variants
 
-**Total: 28 font files** exported from the package. Font `.otf` files ship as raw assets in `src/assets/fonts/` — NOT bundled into `dist/`. Metro resolves `require()` calls at build time.
-
 Pair with `expo-splash-screen` in production:
 ```tsx
 import * as SplashScreen from 'expo-splash-screen'
@@ -572,6 +616,74 @@ import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 
 ---
 
+## Migration Guide: v9 → v10
+
+### Breaking Changes
+
+**1. `SohneFonts` export removed from `@retray-dev/ui-kit/fonts`**
+
+The `SohneFonts` object with `require()` calls is no longer exported. Metro cannot reliably resolve `require()` from inside `node_modules`, especially in monorepos. The export now returns `undefined` and logs a deprecation warning.
+
+**New approach — postinstall script:**
+1. When you install `@retray-dev/ui-kit`, a **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project root
+2. Define `SohneFonts` locally in your `App.tsx` with static `require()` calls (see below)
+3. Pass it to `expo-font`'s `useFonts()` hook
+
+**Migration:**
+
+```diff
+// App.tsx
+import { useFonts } from 'expo-font'
+-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
++// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
++const SohneFonts = {
++  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
++  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
++  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
++  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
++  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
++  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
++  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
++  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
++  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
++  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
++  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
++  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
++  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
++  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
++  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
++  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
++  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
++  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
++  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
++  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
++  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
++  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
++  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
++  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
++  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
++  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
++  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
++  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
++}
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  // ...
+}
+```
+
+**.gitignore recommendation:**
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
+```
+
+**Why this change:** Metro bundler requires `require()` calls to originate from the consumer's source tree, not from `node_modules`. The previous approach worked in simple setups but failed in monorepos and symlinked workspaces.
+
+---
+
 ## Components
 
 ---

package/CONSUMER.md

@@ -119,9 +119,40 @@ module.exports = config
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 import { RetrayProvider } from '@retray-dev/ui-kit'
 
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
+
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
   if (!fontsLoaded) return null
@@ -234,14 +265,23 @@ npx expo install @shopify/react-native-skia expo-sensors
 
 ## Fonts
 
-All components use the **Sohne** font family. Load fonts before rendering any component:
+All components use the **Sohne** font family.
 
-```tsx
-import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+### How it works
+
+1. When you install `@retray-dev/ui-kit`, the **postinstall script** copies 28 `.otf` font files to `assets/fonts/sohne/` in your project
+2. You define `SohneFonts` with static `require()` calls in your `App.tsx` (see Provider Setup above for the full boilerplate)
+3. Metro resolves fonts from your project's `assets/` folder at bundle time
+
+### .gitignore recommendation
+
+Fonts are copied to `assets/fonts/sohne/` on install. You can either:
+- **Commit them** — no network needed during CI builds
+- **Ignore them** — re-copied on every `pnpm install`
 
-const [fontsLoaded] = useFonts(SohneFonts)
-if (!fontsLoaded) return null
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
 ```
 
 See `FONTS.md` for the full font inventory and weight reference.

package/FONTS.md

@@ -4,13 +4,51 @@
 
 All components in `@retray-dev/ui-kit` use the **Sohne** font family. Consumer apps must load these fonts at the app root using `expo-font`.
 
-### Installation
+### How It Works
+
+1. When you install `@retray-dev/ui-kit`, the **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project root
+2. You must define `SohneFonts` with static `require()` calls in your `App.tsx` (see boilerplate below)
+3. Pass it to `expo-font`'s `useFonts()` hook at your app root
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
 
-The library includes Sohne font files as raw `.otf` assets. Import and load them:
+### SohneFonts Boilerplate
+
+Copy this into your `App.tsx`:
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
 
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
@@ -32,12 +70,11 @@ export default function App() {
 ```tsx
 import * as SplashScreen from 'expo-splash-screen'
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 
 SplashScreen.preventAutoHideAsync()
 
 export default function App() {
-  const [fontsLoaded] = useFonts(SohneFonts)
+  const [fontsLoaded] = useFonts(SohneFonts) // Use the SohneFonts object above
 
   useEffect(() => {
     if (fontsLoaded) {
@@ -57,9 +94,20 @@ export default function App() {
 }
 ```
 
+### .gitignore Recommendation
+
+Fonts are copied to `assets/fonts/sohne/` on install. You can either:
+- **Commit them** — no network needed during CI builds
+- **Ignore them** — re-copied on every `pnpm install`
+
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
+```
+
 ### Font Weights Included
 
-`SohneFonts` exports 28 `.otf` files total.
+`SohneFonts` includes 28 `.otf` files total.
 
 **Sohne (14 files):**
 - `Sohne-ExtraLight`
@@ -93,13 +141,6 @@ export default function App() {
 - `SohneMono-ExtraBold`
 - `SohneMono-ExtraBoldItalic`
 
-### How It Works
-
-1. **Library components** reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
-2. **Consumer app** loads font files at startup via `useFonts(SohneFonts)`
-3. **Metro bundler** resolves `require()` calls to `.otf` files in `node_modules/@retray-dev/ui-kit/src/assets/fonts/`
-4. **React Native** maps family names to loaded font files
-
 Font files ship as raw assets — **not bundled into `dist/`**. Metro handles asset resolution natively.
 
 ### Peer Dependency

package/README.md

@@ -46,11 +46,44 @@ module.exports = function (api) {
 
 ## Typography
 
-All components use **Sohne** font family. You must load the fonts at app root before rendering any component:
+All components use **Sohne** font family. You must load the fonts at app root before rendering any component.
+
+When you install `@retray-dev/ui-kit`, a **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project. Then define `SohneFonts` locally in your `App.tsx`:
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
 
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
@@ -62,7 +95,11 @@ export default function App() {
 }
 ```
 
-The library ships 28 font files (14 Sohne base + 14 SohneMono, each with 7 weights + italic variants) as raw `.otf` files. Metro resolves them at bundle time.
+**.gitignore recommendation:**
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
+```
 
 ## Setup
 

package/dist/fonts.d.mts

@@ -1,32 +1,40 @@
-declare const SohneFonts: {
-    readonly 'Sohne-ExtraLight': number;
-    readonly 'Sohne-ExtraLightItalic': number;
-    readonly 'Sohne-Light': number;
-    readonly 'Sohne-LightItalic': number;
-    readonly 'Sohne-Regular': number;
-    readonly 'Sohne-Italic': number;
-    readonly 'Sohne-Medium': number;
-    readonly 'Sohne-MediumItalic': number;
-    readonly 'Sohne-SemiBold': number;
-    readonly 'Sohne-SemiBoldItalic': number;
-    readonly 'Sohne-Bold': number;
-    readonly 'Sohne-BoldItalic': number;
-    readonly 'Sohne-ExtraBold': number;
-    readonly 'Sohne-ExtraBoldItalic': number;
-    readonly 'SohneMono-ExtraLight': number;
-    readonly 'SohneMono-ExtraLightItalic': number;
-    readonly 'SohneMono-Light': number;
-    readonly 'SohneMono-LightItalic': number;
-    readonly 'SohneMono-Regular': number;
-    readonly 'SohneMono-Italic': number;
-    readonly 'SohneMono-Medium': number;
-    readonly 'SohneMono-MediumItalic': number;
-    readonly 'SohneMono-SemiBold': number;
-    readonly 'SohneMono-SemiBoldItalic': number;
-    readonly 'SohneMono-Bold': number;
-    readonly 'SohneMono-BoldItalic': number;
-    readonly 'SohneMono-ExtraBold': number;
-    readonly 'SohneMono-ExtraBoldItalic': number;
-};
+/**
+ * Sohne font family names for @retray-dev/ui-kit components.
+ *
+ * The postinstall script copies 28 .otf files to your project's assets/fonts/sohne/ folder.
+ * You must define SohneFonts with static require() calls in your App.tsx:
+ *
+ * @example
+ * import { useFonts } from 'expo-font'
+ *
+ * // Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+ * const SohneFonts = {
+ *   'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+ *   'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+ *   // ... see CONSUMER.md for full boilerplate
+ * }
+ *
+ * function App() {
+ *   const [fontsLoaded] = useFonts(SohneFonts)
+ *   if (!fontsLoaded) return null
+ *   // render app
+ * }
+ *
+ * @see CONSUMER.md for the full SohneFonts boilerplate to copy into your App.tsx
+ */
+/**
+ * Array of all 28 Sohne font family names.
+ * Use this for validation or programmatic checks — NOT for loading fonts.
+ * To load fonts, use the static require() boilerplate from CONSUMER.md.
+ */
+declare const SohneFontNames: readonly ["Sohne-ExtraLight", "Sohne-ExtraLightItalic", "Sohne-Light", "Sohne-LightItalic", "Sohne-Regular", "Sohne-Italic", "Sohne-Medium", "Sohne-MediumItalic", "Sohne-SemiBold", "Sohne-SemiBoldItalic", "Sohne-Bold", "Sohne-BoldItalic", "Sohne-ExtraBold", "Sohne-ExtraBoldItalic", "SohneMono-ExtraLight", "SohneMono-ExtraLightItalic", "SohneMono-Light", "SohneMono-LightItalic", "SohneMono-Regular", "SohneMono-Italic", "SohneMono-Medium", "SohneMono-MediumItalic", "SohneMono-SemiBold", "SohneMono-SemiBoldItalic", "SohneMono-Bold", "SohneMono-BoldItalic", "SohneMono-ExtraBold", "SohneMono-ExtraBoldItalic"];
+/** Type for any valid Sohne font family name */
+type SohneFontName = (typeof SohneFontNames)[number];
+/**
+ * @deprecated SohneFonts export removed in v10.0.0.
+ * Metro cannot resolve require() calls from node_modules reliably.
+ * Copy the static SohneFonts boilerplate from CONSUMER.md into your App.tsx instead.
+ */
+declare const SohneFonts: undefined;
 
-export { SohneFonts };
+export { type SohneFontName, SohneFontNames, SohneFonts };

package/dist/fonts.d.ts

@@ -1,32 +1,40 @@
-declare const SohneFonts: {
-    readonly 'Sohne-ExtraLight': number;
-    readonly 'Sohne-ExtraLightItalic': number;
-    readonly 'Sohne-Light': number;
-    readonly 'Sohne-LightItalic': number;
-    readonly 'Sohne-Regular': number;
-    readonly 'Sohne-Italic': number;
-    readonly 'Sohne-Medium': number;
-    readonly 'Sohne-MediumItalic': number;
-    readonly 'Sohne-SemiBold': number;
-    readonly 'Sohne-SemiBoldItalic': number;
-    readonly 'Sohne-Bold': number;
-    readonly 'Sohne-BoldItalic': number;
-    readonly 'Sohne-ExtraBold': number;
-    readonly 'Sohne-ExtraBoldItalic': number;
-    readonly 'SohneMono-ExtraLight': number;
-    readonly 'SohneMono-ExtraLightItalic': number;
-    readonly 'SohneMono-Light': number;
-    readonly 'SohneMono-LightItalic': number;
-    readonly 'SohneMono-Regular': number;
-    readonly 'SohneMono-Italic': number;
-    readonly 'SohneMono-Medium': number;
-    readonly 'SohneMono-MediumItalic': number;
-    readonly 'SohneMono-SemiBold': number;
-    readonly 'SohneMono-SemiBoldItalic': number;
-    readonly 'SohneMono-Bold': number;
-    readonly 'SohneMono-BoldItalic': number;
-    readonly 'SohneMono-ExtraBold': number;
-    readonly 'SohneMono-ExtraBoldItalic': number;
-};
+/**
+ * Sohne font family names for @retray-dev/ui-kit components.
+ *
+ * The postinstall script copies 28 .otf files to your project's assets/fonts/sohne/ folder.
+ * You must define SohneFonts with static require() calls in your App.tsx:
+ *
+ * @example
+ * import { useFonts } from 'expo-font'
+ *
+ * // Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+ * const SohneFonts = {
+ *   'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+ *   'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+ *   // ... see CONSUMER.md for full boilerplate
+ * }
+ *
+ * function App() {
+ *   const [fontsLoaded] = useFonts(SohneFonts)
+ *   if (!fontsLoaded) return null
+ *   // render app
+ * }
+ *
+ * @see CONSUMER.md for the full SohneFonts boilerplate to copy into your App.tsx
+ */
+/**
+ * Array of all 28 Sohne font family names.
+ * Use this for validation or programmatic checks — NOT for loading fonts.
+ * To load fonts, use the static require() boilerplate from CONSUMER.md.
+ */
+declare const SohneFontNames: readonly ["Sohne-ExtraLight", "Sohne-ExtraLightItalic", "Sohne-Light", "Sohne-LightItalic", "Sohne-Regular", "Sohne-Italic", "Sohne-Medium", "Sohne-MediumItalic", "Sohne-SemiBold", "Sohne-SemiBoldItalic", "Sohne-Bold", "Sohne-BoldItalic", "Sohne-ExtraBold", "Sohne-ExtraBoldItalic", "SohneMono-ExtraLight", "SohneMono-ExtraLightItalic", "SohneMono-Light", "SohneMono-LightItalic", "SohneMono-Regular", "SohneMono-Italic", "SohneMono-Medium", "SohneMono-MediumItalic", "SohneMono-SemiBold", "SohneMono-SemiBoldItalic", "SohneMono-Bold", "SohneMono-BoldItalic", "SohneMono-ExtraBold", "SohneMono-ExtraBoldItalic"];
+/** Type for any valid Sohne font family name */
+type SohneFontName = (typeof SohneFontNames)[number];
+/**
+ * @deprecated SohneFonts export removed in v10.0.0.
+ * Metro cannot resolve require() calls from node_modules reliably.
+ * Copy the static SohneFonts boilerplate from CONSUMER.md into your App.tsx instead.
+ */
+declare const SohneFonts: undefined;
 
-export { SohneFonts };
+export { type SohneFontName, SohneFontNames, SohneFonts };

package/dist/fonts.js

@@ -1,44 +1,39 @@
 'use strict';
 
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // src/fonts.ts
-var SohneFonts = {
-  // Sohne base
-  "Sohne-ExtraLight": __require("./assets/fonts/Sohne-ExtraLight.otf"),
-  "Sohne-ExtraLightItalic": __require("./assets/fonts/Sohne-ExtraLightItalic.otf"),
-  "Sohne-Light": __require("./assets/fonts/Sohne-Light.otf"),
-  "Sohne-LightItalic": __require("./assets/fonts/Sohne-LightItalic.otf"),
-  "Sohne-Regular": __require("./assets/fonts/Sohne-Regular.otf"),
-  "Sohne-Italic": __require("./assets/fonts/Sohne-Italic.otf"),
-  "Sohne-Medium": __require("./assets/fonts/Sohne-Medium.otf"),
-  "Sohne-MediumItalic": __require("./assets/fonts/Sohne-MediumItalic.otf"),
-  "Sohne-SemiBold": __require("./assets/fonts/Sohne-SemiBold.otf"),
-  "Sohne-SemiBoldItalic": __require("./assets/fonts/Sohne-SemiBoldItalic.otf"),
-  "Sohne-Bold": __require("./assets/fonts/Sohne-Bold.otf"),
-  "Sohne-BoldItalic": __require("./assets/fonts/Sohne-BoldItalic.otf"),
-  "Sohne-ExtraBold": __require("./assets/fonts/Sohne-ExtraBold.otf"),
-  "Sohne-ExtraBoldItalic": __require("./assets/fonts/Sohne-ExtraBoldItalic.otf"),
-  // SohneMono
-  "SohneMono-ExtraLight": __require("./assets/fonts/SohneMono-ExtraLight.otf"),
-  "SohneMono-ExtraLightItalic": __require("./assets/fonts/SohneMono-ExtraLightItalic.otf"),
-  "SohneMono-Light": __require("./assets/fonts/SohneMono-Light.otf"),
-  "SohneMono-LightItalic": __require("./assets/fonts/SohneMono-LightItalic.otf"),
-  "SohneMono-Regular": __require("./assets/fonts/SohneMono-Regular.otf"),
-  "SohneMono-Italic": __require("./assets/fonts/SohneMono-Italic.otf"),
-  "SohneMono-Medium": __require("./assets/fonts/SohneMono-Medium.otf"),
-  "SohneMono-MediumItalic": __require("./assets/fonts/SohneMono-MediumItalic.otf"),
-  "SohneMono-SemiBold": __require("./assets/fonts/SohneMono-SemiBold.otf"),
-  "SohneMono-SemiBoldItalic": __require("./assets/fonts/SohneMono-SemiBoldItalic.otf"),
-  "SohneMono-Bold": __require("./assets/fonts/SohneMono-Bold.otf"),
-  "SohneMono-BoldItalic": __require("./assets/fonts/SohneMono-BoldItalic.otf"),
-  "SohneMono-ExtraBold": __require("./assets/fonts/SohneMono-ExtraBold.otf"),
-  "SohneMono-ExtraBoldItalic": __require("./assets/fonts/SohneMono-ExtraBoldItalic.otf")
-};
+var SohneFontNames = [
+  // Sohne base (14)
+  "Sohne-ExtraLight",
+  "Sohne-ExtraLightItalic",
+  "Sohne-Light",
+  "Sohne-LightItalic",
+  "Sohne-Regular",
+  "Sohne-Italic",
+  "Sohne-Medium",
+  "Sohne-MediumItalic",
+  "Sohne-SemiBold",
+  "Sohne-SemiBoldItalic",
+  "Sohne-Bold",
+  "Sohne-BoldItalic",
+  "Sohne-ExtraBold",
+  "Sohne-ExtraBoldItalic",
+  // SohneMono (14)
+  "SohneMono-ExtraLight",
+  "SohneMono-ExtraLightItalic",
+  "SohneMono-Light",
+  "SohneMono-LightItalic",
+  "SohneMono-Regular",
+  "SohneMono-Italic",
+  "SohneMono-Medium",
+  "SohneMono-MediumItalic",
+  "SohneMono-SemiBold",
+  "SohneMono-SemiBoldItalic",
+  "SohneMono-Bold",
+  "SohneMono-BoldItalic",
+  "SohneMono-ExtraBold",
+  "SohneMono-ExtraBoldItalic"
+];
+var SohneFonts = void 0;
 
+exports.SohneFontNames = SohneFontNames;
 exports.SohneFonts = SohneFonts;

package/dist/fonts.mjs

@@ -1,37 +1,38 @@
-import { __require } from './chunk-Y6FXYEAI.mjs';
+import './chunk-Y6FXYEAI.mjs';
 
 // src/fonts.ts
-var SohneFonts = {
-  // Sohne base
-  "Sohne-ExtraLight": __require("./assets/fonts/Sohne-ExtraLight.otf"),
-  "Sohne-ExtraLightItalic": __require("./assets/fonts/Sohne-ExtraLightItalic.otf"),
-  "Sohne-Light": __require("./assets/fonts/Sohne-Light.otf"),
-  "Sohne-LightItalic": __require("./assets/fonts/Sohne-LightItalic.otf"),
-  "Sohne-Regular": __require("./assets/fonts/Sohne-Regular.otf"),
-  "Sohne-Italic": __require("./assets/fonts/Sohne-Italic.otf"),
-  "Sohne-Medium": __require("./assets/fonts/Sohne-Medium.otf"),
-  "Sohne-MediumItalic": __require("./assets/fonts/Sohne-MediumItalic.otf"),
-  "Sohne-SemiBold": __require("./assets/fonts/Sohne-SemiBold.otf"),
-  "Sohne-SemiBoldItalic": __require("./assets/fonts/Sohne-SemiBoldItalic.otf"),
-  "Sohne-Bold": __require("./assets/fonts/Sohne-Bold.otf"),
-  "Sohne-BoldItalic": __require("./assets/fonts/Sohne-BoldItalic.otf"),
-  "Sohne-ExtraBold": __require("./assets/fonts/Sohne-ExtraBold.otf"),
-  "Sohne-ExtraBoldItalic": __require("./assets/fonts/Sohne-ExtraBoldItalic.otf"),
-  // SohneMono
-  "SohneMono-ExtraLight": __require("./assets/fonts/SohneMono-ExtraLight.otf"),
-  "SohneMono-ExtraLightItalic": __require("./assets/fonts/SohneMono-ExtraLightItalic.otf"),
-  "SohneMono-Light": __require("./assets/fonts/SohneMono-Light.otf"),
-  "SohneMono-LightItalic": __require("./assets/fonts/SohneMono-LightItalic.otf"),
-  "SohneMono-Regular": __require("./assets/fonts/SohneMono-Regular.otf"),
-  "SohneMono-Italic": __require("./assets/fonts/SohneMono-Italic.otf"),
-  "SohneMono-Medium": __require("./assets/fonts/SohneMono-Medium.otf"),
-  "SohneMono-MediumItalic": __require("./assets/fonts/SohneMono-MediumItalic.otf"),
-  "SohneMono-SemiBold": __require("./assets/fonts/SohneMono-SemiBold.otf"),
-  "SohneMono-SemiBoldItalic": __require("./assets/fonts/SohneMono-SemiBoldItalic.otf"),
-  "SohneMono-Bold": __require("./assets/fonts/SohneMono-Bold.otf"),
-  "SohneMono-BoldItalic": __require("./assets/fonts/SohneMono-BoldItalic.otf"),
-  "SohneMono-ExtraBold": __require("./assets/fonts/SohneMono-ExtraBold.otf"),
-  "SohneMono-ExtraBoldItalic": __require("./assets/fonts/SohneMono-ExtraBoldItalic.otf")
-};
+var SohneFontNames = [
+  // Sohne base (14)
+  "Sohne-ExtraLight",
+  "Sohne-ExtraLightItalic",
+  "Sohne-Light",
+  "Sohne-LightItalic",
+  "Sohne-Regular",
+  "Sohne-Italic",
+  "Sohne-Medium",
+  "Sohne-MediumItalic",
+  "Sohne-SemiBold",
+  "Sohne-SemiBoldItalic",
+  "Sohne-Bold",
+  "Sohne-BoldItalic",
+  "Sohne-ExtraBold",
+  "Sohne-ExtraBoldItalic",
+  // SohneMono (14)
+  "SohneMono-ExtraLight",
+  "SohneMono-ExtraLightItalic",
+  "SohneMono-Light",
+  "SohneMono-LightItalic",
+  "SohneMono-Regular",
+  "SohneMono-Italic",
+  "SohneMono-Medium",
+  "SohneMono-MediumItalic",
+  "SohneMono-SemiBold",
+  "SohneMono-SemiBoldItalic",
+  "SohneMono-Bold",
+  "SohneMono-BoldItalic",
+  "SohneMono-ExtraBold",
+  "SohneMono-ExtraBoldItalic"
+];
+var SohneFonts = void 0;
 
-export { SohneFonts };
+export { SohneFontNames, SohneFonts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retray-dev/ui-kit",
-  "version": "9.3.1",
+  "version": "10.0.0",
   "description": "Personal UI Kit for React Native / Expo",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -25,6 +25,7 @@
   "files": [
     "dist",
     "src",
+    "scripts",
     "COMPONENTS.md",
     "CONSUMER.md",
     "EXAMPLES.md",
@@ -32,6 +33,7 @@
     "DESIGN.md"
   ],
   "scripts": {
+    "postinstall": "node scripts/copy-fonts.js",
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",

package/scripts/build-apk.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+#
+# build-apk.sh — Build a standalone release APK of the example app for phone install.
+#
+# Produces: build-output/retray-ui-kit-example.apk (signed with debug keystore,
+# installable on any Android phone via "Install unknown apps").
+#
+# Requirements (already set up on this machine):
+#   - Android SDK at $ANDROID_HOME (default: ~/Library/Android/sdk)
+#   - Java 17 (JDK)
+#   - pnpm, node
+#
+# Usage:
+#   ./scripts/build-apk.sh              # full build
+#   ./scripts/build-apk.sh --install    # build, then adb install to connected phone
+#   ./scripts/build-apk.sh --clean      # wipe android/ + gradle cache first (slow, fixes weird errors)
+#
+set -euo pipefail
+
+# --- resolve repo root regardless of cwd ---
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+EXAMPLE="$ROOT/example"
+OUT_DIR="$ROOT/build-output"
+APK_NAME="retray-ui-kit-example.apk"
+
+export ANDROID_HOME="${ANDROID_HOME:-$HOME/Library/Android/sdk}"
+
+DO_INSTALL=false
+DO_CLEAN=false
+for arg in "$@"; do
+  case "$arg" in
+    --install) DO_INSTALL=true ;;
+    --clean)   DO_CLEAN=true ;;
+    *) echo "Unknown arg: $arg"; exit 1 ;;
+  esac
+done
+
+echo "==> repo:    $ROOT"
+echo "==> sdk:     $ANDROID_HOME"
+[ -d "$ANDROID_HOME" ] || { echo "ERROR: Android SDK not found at $ANDROID_HOME"; exit 1; }
+
+# --- 1. build the ui-kit (example depends on dist/) ---
+echo "==> [1/4] Building @retray-dev/ui-kit ..."
+( cd "$ROOT" && pnpm build )
+
+# --- 2. ensure deps + native android/ dir exist ---
+echo "==> [2/4] Prebuild (generate android/ if missing) ..."
+if $DO_CLEAN; then
+  echo "    --clean: removing android/ and gradle build cache"
+  rm -rf "$EXAMPLE/android"
+fi
+# babel-preset-expo must be a top-level dep of example so Metro resolves it
+# under pnpm hoisted layout. Declared in example/package.json devDependencies.
+( cd "$ROOT" && pnpm install --frozen-lockfile=false )
+if [ ! -d "$EXAMPLE/android" ]; then
+  ( cd "$EXAMPLE" && CI=1 npx expo prebuild --platform android --no-install )
+fi
+
+# --- 3. assemble release APK ---
+echo "==> [3/4] Gradle assembleRelease (first run ~7 min) ..."
+( cd "$EXAMPLE/android" && ANDROID_HOME="$ANDROID_HOME" ./gradlew assembleRelease )
+
+# --- 4. copy to build-output/ ---
+echo "==> [4/4] Copying APK ..."
+SRC_APK="$EXAMPLE/android/app/build/outputs/apk/release/app-release.apk"
+[ -f "$SRC_APK" ] || { echo "ERROR: APK not found at $SRC_APK"; exit 1; }
+mkdir -p "$OUT_DIR"
+cp "$SRC_APK" "$OUT_DIR/$APK_NAME"
+
+echo ""
+echo "✅ APK ready: $OUT_DIR/$APK_NAME ($(du -h "$OUT_DIR/$APK_NAME" | cut -f1))"
+
+# --- optional install ---
+if $DO_INSTALL; then
+  echo "==> adb install ..."
+  "$ANDROID_HOME/platform-tools/adb" install -r "$OUT_DIR/$APK_NAME"
+  echo "✅ Installed to connected device."
+else
+  echo ""
+  echo "To put on your phone:"
+  echo "  • USB:   $ANDROID_HOME/platform-tools/adb install -r \"$OUT_DIR/$APK_NAME\""
+  echo "  • or run again with --install"
+  echo "  • or AirDrop/Drive the .apk and tap it (enable 'Install unknown apps')"
+fi

package/scripts/copy-fonts.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Postinstall script: copies Sohne font files to consumer project's assets/fonts/sohne/
+ *
+ * This runs automatically when a consumer installs @retray-dev/ui-kit.
+ * Fonts are copied from dist/assets/fonts/ to <consumer-root>/assets/fonts/sohne/
+ * so Metro can resolve require() calls in the consumer's App.tsx.
+ */
+const fs = require('fs')
+const path = require('path')
+
+// npm sets INIT_CWD to consumer project root, pnpm sets PROJECT_CWD
+const consumerRoot =
+  process.env.INIT_CWD ||
+  process.env.PROJECT_CWD ||
+  process.cwd()
+
+// Don't run when installing inside the ui-kit repo itself
+const pkgPath = path.join(consumerRoot, 'package.json')
+if (!fs.existsSync(pkgPath)) {
+  process.exit(0)
+}
+
+let pkg
+try {
+  pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'))
+} catch {
+  // Can't read package.json — skip silently
+  process.exit(0)
+}
+
+// Skip if we're in the ui-kit repo itself
+if (pkg.name === '@retray-dev/ui-kit') {
+  process.exit(0)
+}
+
+// Source: dist/assets/fonts/ (relative to this script in scripts/)
+const src = path.join(__dirname, '..', 'dist', 'assets', 'fonts')
+
+// Destination: consumer's assets/fonts/sohne/
+const dest = path.join(consumerRoot, 'assets', 'fonts', 'sohne')
+
+// If source doesn't exist (maybe dist not built yet), skip gracefully
+if (!fs.existsSync(src)) {
+  console.warn('[ui-kit] Font source not found:', src)
+  console.warn('[ui-kit] Run `pnpm build` in the ui-kit package first, or fonts will need manual setup.')
+  process.exit(0)
+}
+
+// Create destination directory
+try {
+  fs.mkdirSync(dest, { recursive: true })
+} catch (err) {
+  console.warn('[ui-kit] Could not create font directory:', dest)
+  console.warn('[ui-kit] Error:', err.message)
+  console.warn('[ui-kit] You may need to copy fonts manually. See FONTS.md for setup.')
+  process.exit(0)
+}
+
+// Copy .otf files (skip if already exists to avoid overwriting user modifications)
+const files = fs.readdirSync(src).filter(f => f.endsWith('.otf'))
+let copied = 0
+let skipped = 0
+
+for (const file of files) {
+  const srcFile = path.join(src, file)
+  const destFile = path.join(dest, file)
+
+  if (fs.existsSync(destFile)) {
+    skipped++
+    continue
+  }
+
+  try {
+    fs.copyFileSync(srcFile, destFile)
+    copied++
+  } catch (err) {
+    console.warn(`[ui-kit] Failed to copy ${file}:`, err.message)
+  }
+}
+
+if (copied > 0) {
+  console.log(`[ui-kit] Copied ${copied} Sohne font files → assets/fonts/sohne/`)
+}
+if (skipped > 0 && copied === 0) {
+  // All fonts already present — no message needed
+}
+if (copied > 0 || (skipped > 0 && process.env.VERBOSE)) {
+  console.log('[ui-kit] Add SohneFonts to your App.tsx — see CONSUMER.md for the boilerplate.')
+}

package/scripts/test-consumer-fonts.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Verifies that dist/fonts.js paths resolve correctly from a consumer's perspective.
+# Simulates what npm publish sends: packs the package, installs into a temp Expo app,
+# then checks that Metro can find all .otf files without ../traversal.
+#
+# Run from repo root: ./scripts/test-consumer-fonts.sh
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+TMP="$(mktemp -d)"
+PACK_DIR="$TMP/pack"
+
+# Find npm — prefer nvm node, fallback to PATH
+NPM_BIN=""
+for node_dir in "$HOME"/.nvm/versions/node/*/bin; do
+  if [ -f "$node_dir/npm" ]; then NPM_BIN="$node_dir/npm"; fi
+done
+if [ -z "$NPM_BIN" ]; then NPM_BIN="npm"; fi
+
+cleanup() { rm -rf "$TMP"; }
+trap cleanup EXIT
+
+echo "=== 1. Build ui-kit ==="
+cd "$ROOT"
+pnpm build
+
+echo ""
+echo "=== 2. Pack (simulates npm publish tarball) ==="
+mkdir -p "$PACK_DIR"
+cd "$ROOT"
+TARBALL=$("$NPM_BIN" pack --pack-destination "$PACK_DIR" 2>/dev/null | tail -1)
+TARBALL_PATH="$PACK_DIR/$TARBALL"
+echo "Packed: $TARBALL_PATH"
+
+echo ""
+echo "=== 3. Verify tarball contents ==="
+echo "Files in tarball matching fonts:"
+tar -tzf "$TARBALL_PATH" | grep -E "(fonts|\.otf)" | sort
+
+echo ""
+echo "=== 4. Check dist/fonts.js paths stay within dist/ ==="
+tar -xzf "$TARBALL_PATH" -C "$TMP" package/dist/fonts.js 2>/dev/null
+
+FONTS_JS="$TMP/package/dist/fonts.js"
+if grep -q "\.\./src" "$FONTS_JS"; then
+  echo "FAIL: dist/fonts.js still contains ../src traversal:"
+  grep "\.\./src" "$FONTS_JS"
+  exit 1
+else
+  echo "OK: No ../src traversal found in dist/fonts.js"
+fi
+
+echo ""
+echo "=== 5. Verify all 28 .otf files exist in dist/assets/fonts/ ==="
+OTF_COUNT=$(tar -tzf "$TARBALL_PATH" | grep "^package/dist/assets/fonts/.*\.otf$" | wc -l | tr -d ' ')
+if [ "$OTF_COUNT" -eq 28 ]; then
+  echo "OK: 28 .otf files present in dist/assets/fonts/ inside tarball"
+else
+  echo "FAIL: expected 28 .otf files in dist/assets/fonts/, found $OTF_COUNT"
+  tar -tzf "$TARBALL_PATH" | grep "^package/dist/assets/fonts/.*\.otf$"
+  exit 1
+fi
+
+echo ""
+echo "=== 6. Validate require paths — no ../traversal ==="
+TRAVERSALS=$(grep -oE '"[^"]+\.otf"' "$FONTS_JS" | grep "\.\." || true)
+if [ -n "$TRAVERSALS" ]; then
+  echo "FAIL: Traversal paths found in dist/fonts.js:"
+  echo "$TRAVERSALS"
+  exit 1
+else
+  echo "OK: All .otf require() paths use ./ (within dist/)"
+fi
+
+echo ""
+echo "=== PASS: Consumer font resolution looks correct ==="
+echo "dist/fonts.js uses ./assets/fonts/ paths"
+echo "All 28 .otf files are present in dist/assets/fonts/ in the tarball"
+echo ""
+echo "Consumer usage (no watchFolders hack needed):"
+echo "  import { SohneFonts } from '@retray-dev/ui-kit/fonts'"
+echo "  useFonts(SohneFonts)"

package/src/fonts.ts

@@ -1,53 +1,72 @@
 /**
- * Sohne font family required by @retray-dev/ui-kit components.
+ * Sohne font family names for @retray-dev/ui-kit components.
  *
- * Consumer apps must load these fonts at app root using expo-font:
+ * The postinstall script copies 28 .otf files to your project's assets/fonts/sohne/ folder.
+ * You must define SohneFonts with static require() calls in your App.tsx:
  *
  * @example
  * import { useFonts } from 'expo-font'
- * import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+ *
+ * // Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+ * const SohneFonts = {
+ *   'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+ *   'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+ *   // ... see CONSUMER.md for full boilerplate
+ * }
  *
  * function App() {
  *   const [fontsLoaded] = useFonts(SohneFonts)
  *   if (!fontsLoaded) return null
  *   // render app
  * }
+ *
+ * @see CONSUMER.md for the full SohneFonts boilerplate to copy into your App.tsx
  */
-// `.otf` assets resolve to a Metro asset module id (number) via require() at the
-// consumer's build time. Paths are relative to dist/fonts.js (the compiled output).
-// The build step copies all .otf files into dist/assets/fonts/ so these paths
-// resolve correctly without any ../traversal that Metro would reject.
-declare const require: (path: string) => number
 
-export const SohneFonts = {
-  // Sohne base
-  'Sohne-ExtraLight':         require('./assets/fonts/Sohne-ExtraLight.otf'),
-  'Sohne-ExtraLightItalic':   require('./assets/fonts/Sohne-ExtraLightItalic.otf'),
-  'Sohne-Light':              require('./assets/fonts/Sohne-Light.otf'),
-  'Sohne-LightItalic':        require('./assets/fonts/Sohne-LightItalic.otf'),
-  'Sohne-Regular':            require('./assets/fonts/Sohne-Regular.otf'),
-  'Sohne-Italic':             require('./assets/fonts/Sohne-Italic.otf'),
-  'Sohne-Medium':             require('./assets/fonts/Sohne-Medium.otf'),
-  'Sohne-MediumItalic':       require('./assets/fonts/Sohne-MediumItalic.otf'),
-  'Sohne-SemiBold':           require('./assets/fonts/Sohne-SemiBold.otf'),
-  'Sohne-SemiBoldItalic':     require('./assets/fonts/Sohne-SemiBoldItalic.otf'),
-  'Sohne-Bold':               require('./assets/fonts/Sohne-Bold.otf'),
-  'Sohne-BoldItalic':         require('./assets/fonts/Sohne-BoldItalic.otf'),
-  'Sohne-ExtraBold':          require('./assets/fonts/Sohne-ExtraBold.otf'),
-  'Sohne-ExtraBoldItalic':    require('./assets/fonts/Sohne-ExtraBoldItalic.otf'),
-  // SohneMono
-  'SohneMono-ExtraLight':         require('./assets/fonts/SohneMono-ExtraLight.otf'),
-  'SohneMono-ExtraLightItalic':   require('./assets/fonts/SohneMono-ExtraLightItalic.otf'),
-  'SohneMono-Light':              require('./assets/fonts/SohneMono-Light.otf'),
-  'SohneMono-LightItalic':        require('./assets/fonts/SohneMono-LightItalic.otf'),
-  'SohneMono-Regular':            require('./assets/fonts/SohneMono-Regular.otf'),
-  'SohneMono-Italic':             require('./assets/fonts/SohneMono-Italic.otf'),
-  'SohneMono-Medium':             require('./assets/fonts/SohneMono-Medium.otf'),
-  'SohneMono-MediumItalic':       require('./assets/fonts/SohneMono-MediumItalic.otf'),
-  'SohneMono-SemiBold':           require('./assets/fonts/SohneMono-SemiBold.otf'),
-  'SohneMono-SemiBoldItalic':     require('./assets/fonts/SohneMono-SemiBoldItalic.otf'),
-  'SohneMono-Bold':               require('./assets/fonts/SohneMono-Bold.otf'),
-  'SohneMono-BoldItalic':         require('./assets/fonts/SohneMono-BoldItalic.otf'),
-  'SohneMono-ExtraBold':          require('./assets/fonts/SohneMono-ExtraBold.otf'),
-  'SohneMono-ExtraBoldItalic':    require('./assets/fonts/SohneMono-ExtraBoldItalic.otf'),
-} as const
+/**
+ * Array of all 28 Sohne font family names.
+ * Use this for validation or programmatic checks — NOT for loading fonts.
+ * To load fonts, use the static require() boilerplate from CONSUMER.md.
+ */
+export const SohneFontNames = [
+  // Sohne base (14)
+  'Sohne-ExtraLight',
+  'Sohne-ExtraLightItalic',
+  'Sohne-Light',
+  'Sohne-LightItalic',
+  'Sohne-Regular',
+  'Sohne-Italic',
+  'Sohne-Medium',
+  'Sohne-MediumItalic',
+  'Sohne-SemiBold',
+  'Sohne-SemiBoldItalic',
+  'Sohne-Bold',
+  'Sohne-BoldItalic',
+  'Sohne-ExtraBold',
+  'Sohne-ExtraBoldItalic',
+  // SohneMono (14)
+  'SohneMono-ExtraLight',
+  'SohneMono-ExtraLightItalic',
+  'SohneMono-Light',
+  'SohneMono-LightItalic',
+  'SohneMono-Regular',
+  'SohneMono-Italic',
+  'SohneMono-Medium',
+  'SohneMono-MediumItalic',
+  'SohneMono-SemiBold',
+  'SohneMono-SemiBoldItalic',
+  'SohneMono-Bold',
+  'SohneMono-BoldItalic',
+  'SohneMono-ExtraBold',
+  'SohneMono-ExtraBoldItalic',
+] as const
+
+/** Type for any valid Sohne font family name */
+export type SohneFontName = (typeof SohneFontNames)[number]
+
+/**
+ * @deprecated SohneFonts export removed in v10.0.0.
+ * Metro cannot resolve require() calls from node_modules reliably.
+ * Copy the static SohneFonts boilerplate from CONSUMER.md into your App.tsx instead.
+ */
+export const SohneFonts = undefined