@farmslot/adapter-rn 0.20.1 → 0.21.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@farmslot/adapter-rn` (published as `@farmslot/expo-reci
 
 ## Unreleased
 
+- Active-development baseline; add user-facing changes here before release or package publication.
+
+## 0.21.0 - 2026-10-13
+
+- Honor HUD top/bottom placement through automatic progress and capture the painted final outcome. Native HUD consumers need the optional `react-native-safe-area-context` peer.
+
 ## 0.20.1 - 2026-10-12
 
 - Update shared runtime dependencies for bounded recipe log observations.

package/README.md

@@ -136,6 +136,10 @@ The generated bridge no-ops unless both conditions are true:
 - `__DEV__`
 - `EXPO_PUBLIC_FARMSLOT_RECIPE_BRIDGE=1`
 
+Native HUD consumers install the optional `react-native-safe-area-context` peer.
+The generated provider supplies that context and the shared renderer uses host
+insets for top placement. CLI-only consumers need no native peers.
+
 The bridge and HUD are copied into local source files by design, so each app can customize `bridgeName`, bridge enablement, HUD text, HUD styles, or full HUD rendering without forking the harness.
 
 Default HUD text is compact and wraps instead of ellipsizing. To tune the generated HUD without replacing it:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@farmslot/adapter-rn",
-  "version": "0.20.1",
+  "version": "0.21.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,15 +46,16 @@
     "prepublishOnly": "node ../../scripts/quality/check-farmslot-package-readiness.mjs --publish --packages @farmslot/adapter-rn"
   },
   "dependencies": {
-    "@farmslot/protocol": "0.40.0",
-    "@farmslot/recipe-runner": "0.31.0",
+    "@farmslot/protocol": "0.41.0",
+    "@farmslot/recipe-runner": "0.32.0",
     "pngjs": "^7.0.0",
     "ws": "^8.18.0"
   },
   "peerDependencies": {
     "agent-device": ">=0.19.3",
     "react": ">=19",
-    "react-native": ">=0.79"
+    "react-native": ">=0.79",
+    "react-native-safe-area-context": ">=5"
   },
   "peerDependenciesMeta": {
     "agent-device": {
@@ -65,6 +66,9 @@
     },
     "react-native": {
       "optional": true
+    },
+    "react-native-safe-area-context": {
+      "optional": true
     }
   },
   "devDependencies": {

package/react-native/RecipeHud.tsx

@@ -1,4 +1,4 @@
-import React from 'react';
+import React, { useCallback, useContext, useEffect, useRef, useState } from 'react';
 import {
   type StyleProp,
   StyleSheet,
@@ -8,8 +8,13 @@ import {
   type ViewProps,
   type ViewStyle,
 } from 'react-native';
+import { initialWindowMetrics, SafeAreaInsetsContext } from 'react-native-safe-area-context';
 
-import { hudIntentDisplay } from '@farmslot/protocol/recipe';
+import {
+  hudIntentDisplay,
+  type RecipeHudPlacement,
+  waitForHudPaint,
+} from '@farmslot/protocol/recipe';
 
 export type FarmslotRecipeHudStatus = 'idle' | 'running' | 'pass' | 'fail';
 
@@ -19,6 +24,55 @@ export interface FarmslotRecipeHudState {
   currentStep?: number;
   totalSteps?: number;
   error?: string;
+  position?: RecipeHudPlacement;
+}
+
+export type RecipeHudStateController = readonly [
+  FarmslotRecipeHudState | null,
+  (state: FarmslotRecipeHudState | null) => Promise<void>,
+];
+
+interface HudAcknowledgement {
+  resolve(): void;
+  reject(error: unknown): void;
+}
+
+/** Bridge acknowledgement follows the committed HUD rather than the state setter. */
+export function useRecipeHudState(): RecipeHudStateController {
+  const [state, setState] = useState<FarmslotRecipeHudState | null>(null);
+  const current = useRef(state);
+  current.current = state;
+  const pending = useRef<HudAcknowledgement[]>([]);
+  const lifecycle = useRef<AbortController | null>(null);
+  const update = useCallback((next: FarmslotRecipeHudState | null) => {
+    if (next === current.current) return Promise.resolve();
+    return new Promise<void>((resolve, reject) => {
+      pending.current.push({ resolve, reject });
+      setState(next);
+    });
+  }, []);
+  useEffect(() => {
+    const controller = new AbortController();
+    lifecycle.current = controller;
+    return () => {
+      const error = new Error('HUD provider unmounted.');
+      controller.abort(error);
+      for (const acknowledgement of pending.current.splice(0)) acknowledgement.reject(error);
+    };
+  }, []);
+  useEffect(() => {
+    const acknowledgements = pending.current.splice(0);
+    if (acknowledgements.length)
+      void waitForHudPaint(requestAnimationFrame, lifecycle.current?.signal).then(
+        () => {
+          for (const acknowledgement of acknowledgements) acknowledgement.resolve();
+        },
+        (error: unknown) => {
+          for (const acknowledgement of acknowledgements) acknowledgement.reject(error);
+        },
+      );
+  }, [state]);
+  return [state, update];
 }
 
 export interface FarmslotRecipeHudText {
@@ -61,6 +115,7 @@ export function RecipeHud({
   overlay: Overlay,
   onLayout,
 }: Readonly<RecipeHudProps>): React.ReactElement | null {
+  const insets = useContext(SafeAreaInsetsContext) ?? initialWindowMetrics?.insets;
   if (!state || state.status === 'idle') return null;
   const badge = text?.badge?.(state) ?? formatBadge(state);
   const intent = hudIntentDisplay(text?.intent?.(state) ?? state.intent, 'native');
@@ -75,7 +130,13 @@ export function RecipeHud({
       pointerEvents="none"
       style={[
         styles.container,
+        state.position === 'top' ? { top: (insets?.top ?? 0) + 16, bottom: undefined } : undefined,
         customStyles?.container,
+        state.position === 'top'
+          ? { bottom: undefined }
+          : state.position === 'bottom'
+            ? { top: undefined }
+            : undefined,
         intent.panel,
         { overflow: 'hidden', flexDirection: 'row' },
       ]}

package/templates/scripts/agentic/recipe/README.md

@@ -2,6 +2,11 @@
 
 This directory was generated by `@farmslot/adapter-rn`.
 
+Native bridge consumers install `react-native-safe-area-context` alongside their
+React Native peers. The generated provider supplies its context to the shared
+HUD so top captions respect status bars and cutouts. CLI-only consumers need no
+native peers.
+
 The files use Recipe Protocol v1, but the project-facing path and scripts are intentionally versionless so future protocol upgrades do not churn app code.
 
 ## Quality rules

package/templates/scripts/agentic/recipe/action-manifest.with-bridge.json

@@ -66,6 +66,16 @@
         "properties": {
           "clear": {
             "type": "boolean"
+          },
+          "display": {
+            "type": "object",
+            "properties": {
+              "position": {
+                "type": "string",
+                "enum": ["top", "bottom", "top-left", "top-right", "bottom-left", "bottom-right"]
+              }
+            },
+            "additionalProperties": true
           }
         },
         "additionalProperties": false

package/templates/src/farmslot/RecipeBridgeProvider.tsx

@@ -1,7 +1,15 @@
-import React, { createContext, useEffect, useMemo, useState } from 'react';
+import React, { createContext, useEffect, useMemo } from 'react';
 import { Platform, View } from 'react-native';
+import { initialWindowMetrics, SafeAreaProvider } from 'react-native-safe-area-context';
 
-import { type FarmslotRecipeHudState, RecipeHud, type RecipeHudOptions } from './RecipeHud';
+import { hudPlacement } from '@farmslot/protocol/recipe';
+
+import {
+  type FarmslotRecipeHudState,
+  RecipeHud,
+  type RecipeHudOptions,
+  useRecipeHudState,
+} from './RecipeHud';
 
 export interface FarmslotRecipeBridgeCommand {
   command: string;
@@ -38,7 +46,7 @@ export function RecipeBridgeProvider({
   renderHud,
 }: Readonly<RecipeBridgeProviderProps>): React.ReactElement {
   const enabled = isEnabled();
-  const [hud, setHud] = useState<FarmslotRecipeHudState | null>(null);
+  const [hud, setHud] = useRecipeHudState();
 
   const bridge = useMemo<FarmslotRecipeBridgeApi>(
     () => ({
@@ -50,7 +58,7 @@ export function RecipeBridgeProvider({
           return { ok: true, bridge: bridgeName, platform: Platform.OS, hud: true };
         }
         if (command.command === 'hud') {
-          setHud(normalizeHudState(command.payload));
+          await setHud(normalizeHudState(command.payload));
           return { ok: true };
         }
         if (command.command === 'trace') {
@@ -59,7 +67,7 @@ export function RecipeBridgeProvider({
         return { ok: false, error: `Unsupported Farmslot bridge command: ${command.command}` };
       },
     }),
-    [bridgeName, enabled],
+    [bridgeName, enabled, setHud],
   );
 
   useEffect(() => {
@@ -76,10 +84,12 @@ export function RecipeBridgeProvider({
 
   return (
     <FarmslotRecipeBridgeContext.Provider value={bridge}>
-      <View style={{ flex: 1 }}>
-        {children}
-        {renderHud ? renderHud(hud) : <RecipeHud state={hud} {...hudOptions} />}
-      </View>
+      <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+        <View style={{ flex: 1 }}>
+          {children}
+          {renderHud ? renderHud(hud) : <RecipeHud state={hud} {...hudOptions} />}
+        </View>
+      </SafeAreaProvider>
     </FarmslotRecipeBridgeContext.Provider>
   );
 }
@@ -102,6 +112,7 @@ function normalizeHudState(payload: Record<string, unknown> | undefined): Farmsl
     ),
     totalSteps: asOptionalNumber(payload?.totalSteps ?? payload?.total_steps ?? progress?.total),
     error: asOptionalString(payload?.error),
+    position: hudPlacement(payload?.display),
   };
 }
 

package/templates/src/farmslot/RecipeHud.tsx

@@ -7,4 +7,4 @@ export type {
   RecipeHudOverlayProps,
   RecipeHudProps,
 } from '@farmslot/adapter-rn/recipe-hud';
-export { RecipeHud } from '@farmslot/adapter-rn/recipe-hud';
+export { RecipeHud, useRecipeHudState } from '@farmslot/adapter-rn/recipe-hud';