commit 06fae294b8655becb91300f6ef7fc30405e2ea95 Author: shakespeare.diy Date: Mon Jun 15 19:49:07 2026 +0700 New project created with Shakespeare Co-authored-by: shakespeare.diy diff --git a/.agents/skills/ai-chat/SKILL.md b/.agents/skills/ai-chat/SKILL.md new file mode 100644 index 0000000..b9670e9 --- /dev/null +++ b/.agents/skills/ai-chat/SKILL.md @@ -0,0 +1,359 @@ +--- +name: ai-chat +description: Build AI-powered chat interfaces, implement streaming responses, or integrate with Shakespeare AI. +--- + +# AI Integration with Shakespeare API + +This skill provides the `useShakespeare` hook for AI chat completions with Nostr authentication against the Shakespeare AI API. The API dynamically provides available models, so you should query them at runtime rather than hardcoding model names. + +**The Shakespeare integration is not included in the project by default.** When the user wants AI chat functionality, follow the setup instructions below to install the hook. + +## Files Provided by This Skill + +| Skill file | Copy to | +|---|---| +| `files/hooks/useShakespeare.ts` | `src/hooks/useShakespeare.ts` | + +## Setup Instructions + +### 1. Dependencies + +No extra npm packages are required — the hook uses only packages already present in the template (`react`, `@nostrify/react/login` via the existing `useCurrentUser` hook). + +### 2. Copy the Skill File Into `src/` + +Copy `.agents/skills/ai-chat/files/hooks/useShakespeare.ts` into `src/hooks/useShakespeare.ts`. The hook uses `@/hooks/useCurrentUser` and `@nostrify/react/login` types — both already present in the template — so no further wiring is required. + +## Usage + +Use the `useShakespeare` hook for AI chat completions with Nostr authentication. The API dynamically provides available models, so you should query them at runtime rather than hardcoding model names. + +```tsx +import { useShakespeare, type ChatMessage, type Model } from '@/hooks/useShakespeare'; + +const { + sendChatMessage, + sendStreamingMessage, + getAvailableModels, + isLoading, + error, + isAuthenticated +} = useShakespeare(); +``` + +#### Model Selector Component + +```tsx +function ModelSelector({ onModelSelect }: { onModelSelect: (modelId: string) => void }) { + const { getAvailableModels, isLoading } = useShakespeare(); + const [models, setModels] = useState([]); + const [selectedModel, setSelectedModel] = useState(''); + + useEffect(() => { + const fetchModels = async () => { + try { + const response = await getAvailableModels(); + // Sort models by total cost (cheapest first) + const sortedModels = response.data.sort((a, b) => { + const costA = parseFloat(a.pricing.prompt) + parseFloat(a.pricing.completion); + const costB = parseFloat(b.pricing.prompt) + parseFloat(b.pricing.completion); + return costA - costB; + }); + setModels(sortedModels); + + // Select the cheapest model by default + if (sortedModels.length > 0) { + const cheapestModel = sortedModels[0]; + setSelectedModel(cheapestModel.id); + onModelSelect(cheapestModel.id); + } + } catch (err) { + console.error('Failed to fetch models:', err); + } + }; + + fetchModels(); + }, [getAvailableModels, onModelSelect]); + + const handleModelChange = (modelId: string) => { + setSelectedModel(modelId); + onModelSelect(modelId); + }; + + return ( +

+ Choose Model: + +

+ ); +} +``` + +#### Basic Chat Example + +```tsx +function AIChat() { + const { sendChatMessage, isLoading, error, isAuthenticated } = useShakespeare(); + const [messages, setMessages] = useState([]); + const [input, setInput] = useState(''); + const [selectedModel, setSelectedModel] = useState(''); + + const handleSend = async () => { + if (!input.trim() || !selectedModel) return; + + const newMessages = [...messages, { role: 'user', content: input }]; + setMessages(newMessages); + setInput(''); + + try { + const response = await sendChatMessage(newMessages, selectedModel); + setMessages(prev => [...prev, { + role: 'assistant', + content: response.choices[0].message.content as string + }]); + } catch (err) { + console.error('Chat error:', err); + } + }; + + if (!isAuthenticated) return

Please log in to use AI

; + + return ( +

+ {error &&

{error}

} + + {/* Model Selection */} +

+ +

+ {messages.map((msg, i) => ( +

+ {msg.role}: {msg.content} +

+ ))} +

+ +

+ setInput(e.target.value)} + onKeyPress={(e) => e.key === 'Enter' && handleSend()} + className="flex-1 p-2 border rounded" + disabled={isLoading || !selectedModel} + placeholder={!selectedModel ? "Select a model first..." : "Type your message..."} + /> + +

+ ); +} +``` + +#### Streaming Chat Example + +```tsx +function StreamingChat() { + const { sendStreamingMessage } = useShakespeare(); + const [messages, setMessages] = useState([]); + const [currentResponse, setCurrentResponse] = useState(''); + const [selectedModel, setSelectedModel] = useState(''); + + const handleStreaming = async (content: string) => { + if (!selectedModel) return; + + setCurrentResponse(''); + const newMessages = [...messages, { role: 'user', content }]; + setMessages(newMessages); + + try { + await sendStreamingMessage(newMessages, selectedModel, (chunk) => { + setCurrentResponse(prev => prev + chunk); + }); + + // Add the complete response to messages + if (currentResponse.trim()) { + setMessages(prev => [...prev, { + role: 'assistant', + content: currentResponse + }]); + } + } catch (err) { + console.error('Streaming error:', err); + } finally { + setCurrentResponse(''); + } + }; + + return ( +

+ {/* Model selection UI */} +

+ +

+ + {/* Chat interface */} + {/* ... rest of your chat UI */} +

+ ); +} +``` + +#### Model Information + +Models are dynamically fetched from the Shakespeare API and include: + +- **Model ID**: Unique identifier for the model +- **Name**: Human-readable model name +- **Description**: Model capabilities and use cases +- **Context Window**: Maximum token limit for conversations +- **Pricing**: Cost per token for prompt and completion +- **Free Models**: Models with `pricing.prompt === "0"` and `pricing.completion === "0"` + +#### Key Points + +- **Dynamic Model Discovery**: Always fetch available models using `getAvailableModels()` +- **Authentication Required**: User must be logged in with Nostr account +- **Free vs Premium**: Check pricing to determine if model requires credits +- **Error Handling**: Handle `isLoading` and `error` states appropriately +- **Model Selection**: Provide UI for users to choose between available models + +## Implementation Patterns and Best Practices + +### Dialog Component Patterns + +When using Dialog components, always ensure accessibility compliance by including required elements: + +```tsx +import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogDescription } from "@/components/ui/dialog"; + +// ✅ Correct - Always include DialogHeader with DialogTitle + +``` + +**Important**: Even if you want to hide the title visually, use the `VisuallyHidden` component to maintain accessibility: + +```tsx +import { VisuallyHidden } from "radix-ui"; + + + + Hidden Title for Screen Readers + + +``` + +### Streaming Response Handling + +When implementing streaming chat interfaces, always accumulate streamed content in a local variable before clearing the streaming state to prevent content loss: + +```tsx +const handleStreamingResponse = async () => { + let streamedContent = ''; // ✅ Use local variable to accumulate content + + try { + await sendStreamingMessage(messages, model, (chunk) => { + streamedContent += chunk; // ✅ Accumulate in local variable + setCurrentStreamingMessage(streamedContent); // Update UI + }); + + // ✅ Save accumulated content to persistent state + if (streamedContent.trim()) { + const assistantMessage: MessageDisplay = { + id: Date.now().toString(), + role: 'assistant', + content: streamedContent, // ✅ Use accumulated content + timestamp: new Date() + }; + setMessages(prev => [...prev, assistantMessage]); + } + } finally { + setCurrentStreamingMessage(''); // ✅ Clear streaming state after saving + } +}; +``` + +### Error Boundary Patterns + +Always wrap AI components with error boundaries and provide user-friendly error messages for common failure scenarios: + +```tsx +import { ErrorBoundary } from '@/components/ErrorBoundary'; +import { Alert, AlertDescription } from '@/components/ui/alert'; + +function AIChatWithErrorBoundary() { + return ( + + + + + Something went wrong with the AI chat. Please refresh the page and try again. + + + + } + > + + + ); +} + +// In your AI component, handle specific error types gracefully: +function useAIWithErrorHandling() { + const { sendChatMessage, error, clearError } = useShakespeare(); + + const sendMessage = async (messages: ChatMessage[], modelId: string) => { + try { + await sendChatMessage(messages, modelId); + } catch (err) { + // Handle specific error types with user-friendly messages + if (err.message.includes('401')) { + throw new Error('Authentication failed. Please log in again.'); + } else if (err.message.includes('402')) { + throw new Error('Insufficient credits. Please add credits to use premium features.'); + } else if (err.message.includes('network')) { + throw new Error('Network error. Please check your internet connection.'); + } + throw err; // Re-throw for error boundary + } + }; + + return { sendMessage, error, clearError }; +} +``` diff --git a/.agents/skills/ai-chat/files/hooks/useShakespeare.ts b/.agents/skills/ai-chat/files/hooks/useShakespeare.ts new file mode 100644 index 0000000..c29c3ee --- /dev/null +++ b/.agents/skills/ai-chat/files/hooks/useShakespeare.ts @@ -0,0 +1,372 @@ +import { useCallback, useState } from 'react'; +import { useCurrentUser } from './useCurrentUser'; +import type { NUser } from '@nostrify/react/login'; + +// Types for Shakespeare API (compatible with OpenAI ChatCompletionMessageParam) +export interface ChatMessage { + role: 'user' | 'assistant' | 'system'; + content: string | Array<{ + type: 'text' | 'image_url'; + text?: string; + image_url?: { + url: string; + }; + }>; +} + +export interface ChatCompletionRequest { + model: string; + messages: ChatMessage[]; + stream?: boolean; + temperature?: number; + max_tokens?: number; +} + +export interface ChatCompletionResponse { + id: string; + object: string; + created: number; + model: string; + choices: Array<{ + index: number; + message: ChatMessage; + finish_reason: string; + }>; + usage: { + prompt_tokens: number; + completion_tokens: number; + total_tokens: number; + }; +} + +export interface Model { + id: string; + name: string; + description: string; + object: string; + owned_by: string; + created: number; + context_window: number; + pricing: { + prompt: string; + completion: string; + }; +} + +export interface ModelsResponse { + object: string; + data: Model[]; +} + +// Configuration +const SHAKESPEARE_API_URL = 'https://ai.shakespeare.diy/v1'; + +// Helper function to create NIP-98 token +async function createNIP98Token( + method: string, + url: string, + body?: unknown, + user?: NUser +): Promise { + if (!user?.signer) { + throw new Error('User signer is required for NIP-98 authentication'); + } + + // Create the tags array + const tags: string[][] = [ + ['u', url], + ['method', method] + ]; + + // Add payload hash for requests with body (following NIP-98 spec) + if (body && (method === 'POST' || method === 'PUT' || method === 'PATCH')) { + const bodyString = JSON.stringify(body); + const encoder = new TextEncoder(); + const data = encoder.encode(bodyString); + const hashBuffer = await crypto.subtle.digest('SHA-256', data); + const payloadHash = Array.from(new Uint8Array(hashBuffer)) + .map(b => b.toString(16).padStart(2, '0')) + .join(''); + tags.push(['payload', payloadHash]); + } + + // Create the HTTP request event + const event = await user.signer.signEvent({ + kind: 27235, // NIP-98 HTTP Auth + content: '', + tags, + created_at: Math.floor(Date.now() / 1000) + }); + + // Return the token (base64 encoded event) + return btoa(JSON.stringify(event)); +} + +// Helper function to handle API errors with user-friendly messages +async function handleAPIError(response: Response) { + if (response.status === 401) { + throw new Error('Authentication failed. Please make sure you are logged in with a Nostr account.'); + } else if (response.status === 402) { + throw new Error('Insufficient credits. Please add credits to your account to use premium models, or use the free "tybalt" model.'); + } else if (response.status === 400) { + try { + const error = await response.json(); + if (error.error?.type === 'invalid_request_error') { + // Handle specific validation errors + if (error.error.code === 'minimum_amount_not_met') { + throw new Error(`Minimum credit amount is $${error.error.minimum_amount}. Please increase your payment amount.`); + } else if (error.error.code === 'unsupported_method') { + throw new Error('Payment method not supported. Please use "stripe" or "lightning".'); + } else if (error.error.code === 'invalid_url') { + throw new Error('Invalid redirect URL provided for Stripe payment.'); + } + } + throw new Error(`Invalid request: ${error.error?.message || error.details || error.error || 'Please check your request parameters.'}`); + } catch { + throw new Error('Invalid request. Please check your parameters and try again.'); + } + } else if (response.status === 404) { + throw new Error('Resource not found. Please check the payment ID or try again.'); + } else if (response.status >= 500) { + throw new Error('Server error. Please try again in a few moments.'); + } else if (!response.ok) { + try { + const errorData = await response.json(); + throw new Error(`API error: ${errorData.error?.message || errorData.details || errorData.error || response.statusText}`); + } catch { + throw new Error(`Network error: ${response.statusText}. Please check your connection and try again.`); + } + } +} + +export function useShakespeare() { + const { user } = useCurrentUser(); + const [isLoading, setIsLoading] = useState(false); + const [error, setError] = useState(null); + + // Clear error helper + const clearError = useCallback(() => { + setError(null); + }, []); + + // Chat completion function + const sendChatMessage = useCallback(async ( + messages: ChatMessage[], + model: string = 'shakespeare', + options?: Partial + ): Promise => { + if (!user) { + throw new Error('User must be logged in to use AI features'); + } + + setIsLoading(true); + setError(null); + + try { + const requestBody: ChatCompletionRequest = { + model, + messages, + ...options + }; + + const token = await createNIP98Token( + 'POST', + `${SHAKESPEARE_API_URL}/chat/completions`, + requestBody, + user + ); + + const response = await fetch(`${SHAKESPEARE_API_URL}/chat/completions`, { + method: 'POST', + headers: { + 'Authorization': `Nostr ${token}`, + 'Content-Type': 'application/json', + }, + body: JSON.stringify(requestBody), + }); + + await handleAPIError(response); + return await response.json(); + } catch (err) { + let errorMessage = 'An unexpected error occurred'; + + if (err instanceof Error) { + errorMessage = err.message; + } else if (typeof err === 'string') { + errorMessage = err; + } + + // Add context for common issues + if (errorMessage.includes('Failed to fetch') || errorMessage.includes('Network')) { + errorMessage = 'Network error: Please check your internet connection and try again.'; + } else if (errorMessage.includes('signer')) { + errorMessage = 'Authentication error: Please make sure you are logged in with a Nostr account that supports signing.'; + } + + setError(errorMessage); + throw new Error(errorMessage, { cause: err }); + } finally { + setIsLoading(false); + } + }, [user]); + + // Streaming chat completion function + const sendStreamingMessage = useCallback(async ( + messages: ChatMessage[], + model: string = 'shakespeare', + onChunk: (chunk: string) => void, + options?: Partial + ): Promise => { + if (!user) { + throw new Error('User must be logged in to use AI features'); + } + + setIsLoading(true); + setError(null); + + try { + const requestBody: ChatCompletionRequest = { + model, + messages, + stream: true, + ...options + }; + + const token = await createNIP98Token( + 'POST', + `${SHAKESPEARE_API_URL}/chat/completions`, + requestBody, + user + ); + + const response = await fetch(`${SHAKESPEARE_API_URL}/chat/completions`, { + method: 'POST', + headers: { + 'Authorization': `Nostr ${token}`, + 'Content-Type': 'application/json', + }, + body: JSON.stringify(requestBody), + }); + + await handleAPIError(response); + + if (!response.body) { + throw new Error('No response body'); + } + + const reader = response.body.getReader(); + const decoder = new TextDecoder(); + + try { + while (true) { + const { done, value } = await reader.read(); + if (done) break; + + const chunk = decoder.decode(value); + const lines = chunk.split('\n'); + + for (const line of lines) { + if (line.startsWith('data: ')) { + const data = line.slice(6); + if (data === '[DONE]') return; + + try { + const parsed = JSON.parse(data); + const content = parsed.choices?.[0]?.delta?.content; + if (content) { + onChunk(content); + } + } catch { + // Ignore parsing errors for incomplete chunks + } + } + } + } + } finally { + reader.releaseLock(); + } + } catch (err) { + let errorMessage = 'An unexpected error occurred'; + + if (err instanceof Error) { + errorMessage = err.message; + } else if (typeof err === 'string') { + errorMessage = err; + } + + // Add context for common issues + if (errorMessage.includes('Failed to fetch') || errorMessage.includes('Network')) { + errorMessage = 'Network error: Please check your internet connection and try again.'; + } else if (errorMessage.includes('signer')) { + errorMessage = 'Authentication error: Please make sure you are logged in with a Nostr account that supports signing.'; + } + + setError(errorMessage); + throw new Error(errorMessage, { cause: err }); + } finally { + setIsLoading(false); + } + }, [user]); + + // Get available models + const getAvailableModels = useCallback(async (): Promise => { + if (!user) { + throw new Error('User must be logged in to use AI features'); + } + + setIsLoading(true); + setError(null); + + try { + const token = await createNIP98Token( + 'GET', + `${SHAKESPEARE_API_URL}/models`, + undefined, + user + ); + + const response = await fetch(`${SHAKESPEARE_API_URL}/models`, { + method: 'GET', + headers: { + 'Authorization': `Nostr ${token}`, + }, + }); + + await handleAPIError(response); + return await response.json(); + } catch (err) { + let errorMessage = 'An unexpected error occurred'; + + if (err instanceof Error) { + errorMessage = err.message; + } else if (typeof err === 'string') { + errorMessage = err; + } + + // Add context for common issues + if (errorMessage.includes('Failed to fetch') || errorMessage.includes('Network')) { + errorMessage = 'Network error: Please check your internet connection and try again.'; + } else if (errorMessage.includes('signer')) { + errorMessage = 'Authentication error: Please make sure you are logged in with a Nostr account that supports signing.'; + } + + setError(errorMessage); + throw new Error(errorMessage, { cause: err }); + } finally { + setIsLoading(false); + } + }, [user]); + + return { + // State + isLoading, + error, + isAuthenticated: !!user, + + // Actions + sendChatMessage, + sendStreamingMessage, + getAvailableModels, + clearError, + }; +} diff --git a/.agents/skills/capacitor/SKILL.md b/.agents/skills/capacitor/SKILL.md new file mode 100644 index 0000000..8aed38c --- /dev/null +++ b/.agents/skills/capacitor/SKILL.md @@ -0,0 +1,184 @@ +--- +name: capacitor +description: Wrap the mkstack web app as a native iOS and Android application using Capacitor. Provides haptics, native file downloads / share sheet, OS-level secure storage (Keychain / KeyStore), deep-link routing, status-bar theme sync, and safe-area CSS utilities. +--- + +# Capacitor Native Wrapper + +This skill turns the web app into a native iOS and Android binary using [Capacitor](https://capacitorjs.com/) — no Swift or Kotlin required for the basics. The React UI runs unchanged inside a native WebView; the helpers below provide the cross-platform primitives that make it feel native. + +**Not included in the project by default.** Run the setup below when the user wants to ship to an app store or produce an `.apk` / `.ipa`. + +## What this skill provides + +| Capability | Web behavior | Native behavior | +|---|---|---| +| **Haptics** (`impactLight`, `notificationSuccess`, …) | `navigator.vibrate()` on Android browsers | Taptic engine / Android haptics | +| **`downloadTextFile(filename, content)`** | `` click | Writes to app Documents directory | +| **`openUrl(url)`** | `window.open(url, '_blank')` | Native share sheet | +| **`secureStorage` / `useSecureLocalStorage`** | `localStorage` | iOS Keychain / Android KeyStore, auto-migrates plaintext values | +| **``** | no-op | Forwards OS `appUrlOpen` into React Router | +| **`bootstrapNative()`** | no-op | Hides iOS keyboard accessory bar; syncs system-bar icon style with theme | +| **Safe-area utilities** (Tailwind) | `env(safe-area-inset-*)` | `env(safe-area-inset-*)` + `SystemBars` back-fill on Android | + +Every helper is SSR-safe and web-safe — import and call unconditionally from shared components. Each source file ships with a JSDoc header covering the exact API, gotchas, and usage examples; read them after copying. + +## Files to copy + +Copy from `.agents/skills/capacitor/files/` into the matching project location: + +| Skill file | Copy to | +|---|---| +| `files/lib/haptics.ts` | `src/lib/haptics.ts` | +| `files/lib/downloadFile.ts` | `src/lib/downloadFile.ts` | +| `files/lib/secureStorage.ts` | `src/lib/secureStorage.ts` | +| `files/lib/nativeBootstrap.ts` | `src/lib/nativeBootstrap.ts` | +| `files/hooks/useSecureLocalStorage.ts` | `src/hooks/useSecureLocalStorage.ts` | +| `files/components/DeepLinkHandler.tsx` | `src/components/DeepLinkHandler.tsx` | +| `files/capacitor.config.ts` | `capacitor.config.ts` (project root — edit `appId`, `appName`, `scheme`, background colors) | +| `files/scripts/patch-cap-config.mjs` | `scripts/patch-cap-config.mjs` — only needed if you add **local** (non-SPM) native plugin classes; otherwise skip | +| `files/safe-area-shim.css` | `src/safe-area-shim.css` — **only if** you need Android WebView <140 support (see shim file header and troubleshooting below) | + +## Setup + +### 1. Install + +```bash +# Runtime + plugins +npm install @capacitor/core @capacitor/app @capacitor/filesystem \ + @capacitor/haptics @capacitor/keyboard @capacitor/share \ + capacitor-secure-storage-plugin + +# Toolchain +npm install -D @capacitor/cli @capacitor/android @capacitor/ios + +# Safe-area utilities (Tailwind v4 — this project) +npm install -D tailwindcss-safe-area +``` + +mkstack ships **Tailwind v4** with CSS-first config (`@import "tailwindcss"` in `src/index.css`, no `tailwind.config.ts`). If you're adapting these instructions to a Tailwind v3 project, install `tailwindcss-safe-area@0.8.0` instead and register it in `tailwind.config.ts`'s `plugins` array — `1.x` emits no utilities on v3. + +### 2. Copy the skill files + +Copy every file from the table above. + +### 3. Register the safe-area plugin + +Add a second `@import` to `src/index.css`, right after the existing `@import "tailwindcss";`: + +```css +@import "tailwindcss"; +@import "tailwindcss-safe-area"; +@import "tw-animate-css"; +``` + +**Use `@import`, not `@plugin`.** The package ships a plain CSS file for Tailwind v4, not a JS plugin entry point. + +### 4. Fill in `capacitor.config.ts` + +Edit `appId` (reverse-DNS; **cannot be changed after publishing**), `appName`, `ios.scheme`, and the iOS/Android `backgroundColor` values. All other defaults in the skill's config are production-safe. + +### 5. Update `index.html` + +iOS won't expose `env(safe-area-inset-*)` without `viewport-fit=cover`: + +```html + +``` + +### 6. Wire up bootstrap and deep links + +Call `bootstrapNative()` **before** React mounts, so system bars are themed at first paint: + +```tsx +// src/main.tsx +import { bootstrapNative } from '@/lib/nativeBootstrap'; +bootstrapNative(); +createRoot(document.getElementById('root')!).render(); +``` + +Render `` **inside** `` so `useNavigate()` works: + +```tsx +// src/AppRouter.tsx + + + + {/* … */} + +``` + +### 7. Add platforms and build + +```bash +npx cap add android +npx cap add ios # macOS only + +npm run build # produces dist/ +npx cap sync # copies dist/ into android/ and ios/ + +npx cap open android # Android Studio; hit Run +npx cap open ios # Xcode (macOS only); hit Run +``` + +Commit the generated `android/` and `ios/` directories (signing keys stay excluded via the generated `.gitignore`s). If you later add a **local** (non-SPM) Capacitor plugin class, append `node scripts/patch-cap-config.mjs` to your sync command so `packageClassList` survives each `npx cap sync`. + +## Using the APIs + +Each file's JSDoc header has full usage details. Quick tour: + +```tsx +import { impactLight, notificationSuccess } from '@/lib/haptics'; +import { downloadTextFile, openUrl } from '@/lib/downloadFile'; +import { secureStorage } from '@/lib/secureStorage'; +import { useSecureLocalStorage } from '@/hooks/useSecureLocalStorage'; + +impactLight(); // fire-and-forget +notificationSuccess(); // silent no-op on unsupported platforms + +await downloadTextFile('export.json', JSON.stringify(data)); +await openUrl('https://example.com'); + +await secureStorage.setItem('nwc:active', conn); +await secureStorage.getItem('nwc:active'); + +const [conn, setConn, ready] = useSecureLocalStorage('nwc:active', null); +if (!ready) return ; // native reads are async +``` + +## Safe-area utilities + +Once step 3 is done, `*-safe` utilities are available for padding, margin, position, height, border, and scroll properties. The most useful ones: + +- `pt-safe`, `pb-safe`, `px-safe`, `py-safe`, `p-safe` (also logical `ps-`/`pe-` and `start-`/`end-` positions) +- `top-safe`, `bottom-safe`, `inset-safe`, `inset-x-safe` +- `h-dvh-safe`, `min-h-dvh-safe`, `h-svh-safe`, `h-lvh-safe`, `h-screen-safe` +- `{prop}-safe-offset-{n}` — safe area **plus** `{n}` (`pb-safe-offset-4` = inset + 1rem) +- `{prop}-safe-or-{n}` — `max(safe-area, {n})` (`pb-safe-or-8` = at least 2rem) + +```tsx +

…