@g9tm/lynxcontrols-native 1.4.3 → 1.4.5

package/ios/g9lynx-native.podspec

@@ -4,8 +4,8 @@
 # package version, which always equals the pinned G9MAUIControls version (npm run check:versions).
 Pod::Spec.new do |s|
   s.name = 'g9lynx-native'
-  s.version = '1.4.3'
-  s.summary = 'G9 SQLite and host native modules and the <g9-video> element for Lynx (sqlite3, NSUserDefaults, UIKit, AVFoundation).'
+  s.version = '1.4.5'
+  s.summary = 'G9 SQLite, host and speech native modules and the <g9-video> element for Lynx (sqlite3, NSUserDefaults, UIKit, AVFoundation, Speech).'
   s.homepage = 'https://github.com/imankari/g9lynxcontrols'
   s.license = { :type => 'MIT' }
   s.author = 'G9LynxControls'
@@ -16,7 +16,8 @@ Pod::Spec.new do |s|
   # flattened Pods/Headers/Public cannot resolve from the host app (found building apps/ios-host, 2026-10-06).
   s.header_mappings_dir = 'src'
   s.libraries = 'sqlite3'
-  s.frameworks = 'UIKit', 'AVFoundation'
+  # Speech: G9SpeechModule (dictation; the host's Info.plist carries NSSpeechRecognitionUsageDescription).
+  s.frameworks = 'UIKit', 'AVFoundation', 'Speech'
   s.requires_arc = true
   s.dependency 'Lynx', '4.0.3'
 

package/ios/src/G9SpeechModule.h

@@ -0,0 +1,18 @@
+#import <Foundation/Foundation.h>
+#import <Lynx/LynxContextModule.h>
+#import "generated/G9SpeechModuleSpec.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Lynx 4.0.3 has no @LynxNativeModuleRegister: hosts register the module on their LynxConfig
+// (`[config registerModule:G9SpeechModule.class]`). The host's Info.plist needs NSMicrophoneUsageDescription and
+// NSSpeechRecognitionUsageDescription.
+
+/**
+ * `NativeModules.G9SpeechModule` on iOS (`G9SpeechToText`): `SFSpeechRecognizer` over `AVAudioEngine`, one session at a
+ * time; partial hypotheses go out as the global event `g9:speech` (`{"session","text"}`). TWIN: G9SpeechModule.kt.
+ */
+@interface G9SpeechModule : NSObject <G9SpeechModuleSpec, LynxContextModule>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/src/G9SpeechModule.m

@@ -0,0 +1,201 @@
+#import "G9SpeechModule.h"
+#import <AVFoundation/AVFoundation.h>
+#import <Lynx/LynxContext.h>
+#import <Speech/Speech.h>
+
+typedef void (^G9Reply)(id envelope);
+
+static NSDictionary *G9Ok(id value) {
+  return @{@"ok" : @YES, @"value" : value ?: [NSNull null]};
+}
+
+static NSDictionary *G9Fail(NSString *code, NSString *message) {
+  return @{@"ok" : @NO, @"error" : @{@"code" : code, @"message" : message ?: @""}};
+}
+
+static NSLocale *G9LocaleOf(NSString *locale) {
+  return [NSLocale localeWithLocaleIdentifier:locale.length ? locale : @"en-US"];
+}
+
+/** `granted` needs both speech recognition and the microphone; `restricted` is the device's policy. */
+static NSString *G9PermissionState(SFSpeechRecognizerAuthorizationStatus speech, BOOL mic) {
+  if (speech == SFSpeechRecognizerAuthorizationStatusRestricted) return @"restricted";
+  return speech == SFSpeechRecognizerAuthorizationStatusAuthorized && mic ? @"granted" : @"denied";
+}
+
+/** One dictation: the recogniser's task, the request the engine tap feeds, the reply that settles once. */
+@interface G9SpeechSession : NSObject
+@property(nonatomic, copy) NSString *identifier;
+@property(nonatomic, copy, nullable) G9Reply reply;
+@property(nonatomic, strong, nullable) SFSpeechRecognitionTask *task;
+@property(nonatomic, strong, nullable) SFSpeechAudioBufferRecognitionRequest *request;
+@property(nonatomic, copy) NSString *best;
+@property(nonatomic) BOOL settled;
+@end
+
+@implementation G9SpeechSession
+@end
+
+@interface G9SpeechModule ()
+@property(nonatomic, weak, nullable) LynxContext *lynxContext;
+@property(nonatomic, strong) AVAudioEngine *engine;
+@property(nonatomic, strong, nullable) G9SpeechSession *current;
+@end
+
+@implementation G9SpeechModule
+
++ (NSString *)name {
+  return @"G9SpeechModule";
+}
+
++ (NSDictionary<NSString *, NSString *> *)methodLookup {
+  return @{
+    @"isAvailable" : NSStringFromSelector(@selector(isAvailable:callback:)),
+    @"requestPermission" : NSStringFromSelector(@selector(requestPermission:)),
+    @"listen" : NSStringFromSelector(@selector(listen:locale:callback:)),
+    @"cancel" : NSStringFromSelector(@selector(cancel:)),
+  };
+}
+
+- (instancetype)initWithLynxContext:(LynxContext *)context {
+  if ((self = [super init])) {
+    _lynxContext = context;
+    _engine = [[AVAudioEngine alloc] init];
+  }
+  return self;
+}
+
+- (instancetype)init {
+  if ((self = [super init])) _engine = [[AVAudioEngine alloc] init];
+  return self;
+}
+
+- (void)isAvailable:(NSString *)locale callback:(id)callback {
+  SFSpeechRecognizer *r = [[SFSpeechRecognizer alloc] initWithLocale:G9LocaleOf(locale)];
+  ((G9Reply)callback)(G9Ok(@(r != nil && r.isAvailable)));
+}
+
+- (void)requestPermission:(id)callback {
+  G9Reply reply = [(G9Reply)callback copy];
+  [SFSpeechRecognizer requestAuthorization:^(SFSpeechRecognizerAuthorizationStatus speech) {
+    [AVAudioSession.sharedInstance requestRecordPermission:^(BOOL granted) {
+      reply(G9Ok(G9PermissionState(speech, granted)));
+    }];
+  }];
+}
+
+- (void)listen:(NSString *)session locale:(NSString *)locale callback:(id)callback {
+  G9Reply reply = [(G9Reply)callback copy];
+  dispatch_async(dispatch_get_main_queue(), ^{
+    BOOL mic = AVAudioSession.sharedInstance.recordPermission == AVAudioSessionRecordPermissionGranted;
+    if (![G9PermissionState(SFSpeechRecognizer.authorizationStatus, mic) isEqualToString:@"granted"]) {
+      reply(G9Ok(@{@"status" : @"denied"}));
+      return;
+    }
+    SFSpeechRecognizer *recognizer = [[SFSpeechRecognizer alloc] initWithLocale:G9LocaleOf(locale)];
+    if (recognizer == nil || !recognizer.isAvailable) {
+      reply(G9Fail(@"speech-unavailable", @"No speech recogniser for this language on this device."));
+      return;
+    }
+    if (self.current) [self finish:self.current value:@{@"status" : @"cancelled"}];
+
+    G9SpeechSession *s = [[G9SpeechSession alloc] init];
+    s.identifier = session ?: @"";
+    s.reply = reply;
+    s.best = @"";
+    s.request = [[SFSpeechAudioBufferRecognitionRequest alloc] init];
+    s.request.shouldReportPartialResults = YES;
+    self.current = s;
+
+    NSError *error = nil;
+    AVAudioSession *audio = AVAudioSession.sharedInstance;
+    [audio setCategory:AVAudioSessionCategoryRecord mode:AVAudioSessionModeMeasurement options:AVAudioSessionCategoryOptionDuckOthers error:&error];
+    if (!error) [audio setActive:YES withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation error:&error];
+    if (error) {
+      [self fail:s code:@"speech-recognition" message:error.localizedDescription];
+      return;
+    }
+    AVAudioInputNode *input = self.engine.inputNode;
+    SFSpeechAudioBufferRecognitionRequest *request = s.request;
+    [input removeTapOnBus:0];
+    [input installTapOnBus:0
+                bufferSize:1024
+                    format:[input outputFormatForBus:0]
+                     block:^(AVAudioPCMBuffer *buffer, AVAudioTime *when) {
+                       [request appendAudioPCMBuffer:buffer];
+                     }];
+    [self.engine prepare];
+    if (![self.engine startAndReturnError:&error]) {
+      [self fail:s code:@"speech-recognition" message:error.localizedDescription];
+      return;
+    }
+    __weak G9SpeechModule *weakSelf = self;
+    s.task = [recognizer recognitionTaskWithRequest:request
+                                      resultHandler:^(SFSpeechRecognitionResult *result, NSError *taskError) {
+                                        dispatch_async(dispatch_get_main_queue(), ^{
+                                          G9SpeechModule *me = weakSelf;
+                                          if (!me || s.settled) return;
+                                          if (result) {
+                                            s.best = result.bestTranscription.formattedString ?: @"";
+                                            if (!result.isFinal && s.best.length) [me emitPartial:s];
+                                            if (result.isFinal) {
+                                              NSString *text = [s.best stringByTrimmingCharactersInSet:NSCharacterSet.whitespaceAndNewlineCharacterSet];
+                                              [me finish:s value:text.length ? @{@"status" : @"recognized", @"text" : text} : @{@"status" : @"no-match"}];
+                                              return;
+                                            }
+                                          }
+                                          if (taskError) {
+                                            // 1110 = no speech detected; a cancelled task reports 216 / 301.
+                                            NSInteger code = taskError.code;
+                                            if (code == 1110) [me finish:s value:@{@"status" : @"no-match"}];
+                                            else if (code == 216 || code == 301) [me finish:s value:@{@"status" : @"cancelled"}];
+                                            else [me fail:s code:@"speech-recognition" message:taskError.localizedDescription];
+                                          }
+                                        });
+                                      }];
+  });
+}
+
+- (void)cancel:(NSString *)session {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    G9SpeechSession *s = self.current;
+    if (!s || ![s.identifier isEqualToString:session ?: @""]) return;
+    [s.task cancel];
+    [self finish:s value:@{@"status" : @"cancelled"}];
+  });
+}
+
+- (void)emitPartial:(G9SpeechSession *)s {
+  NSData *data = [NSJSONSerialization dataWithJSONObject:@{@"session" : s.identifier, @"text" : s.best} options:0 error:nil];
+  NSString *json = data ? [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding] : @"{}";
+  @try {
+    [self.lynxContext sendGlobalEvent:@"g9:speech" withParams:@[ json ]];
+  } @catch (NSException *ex) {
+    // A context being torn down must not take the recogniser down with it.
+  }
+}
+
+- (void)finish:(G9SpeechSession *)s value:(NSDictionary *)value {
+  if (s.settled) return;
+  s.settled = YES;
+  [self releaseSession:s];
+  if (s.reply) s.reply(G9Ok(value));
+}
+
+- (void)fail:(G9SpeechSession *)s code:(NSString *)code message:(NSString *)message {
+  if (s.settled) return;
+  s.settled = YES;
+  [self releaseSession:s];
+  if (s.reply) s.reply(G9Fail(code, message));
+}
+
+- (void)releaseSession:(G9SpeechSession *)s {
+  if (self.current == s) self.current = nil;
+  if (self.engine.isRunning) [self.engine stop];
+  [self.engine.inputNode removeTapOnBus:0];
+  [s.request endAudio];
+  s.task = nil;
+  [AVAudioSession.sharedInstance setActive:NO withOptions:AVAudioSessionSetActiveOptionNotifyOthersOnDeactivation error:nil];
+}
+
+@end

package/ios/src/generated/G9SpeechModuleSpec.h

@@ -0,0 +1,16 @@
+// Generated by @lynx-js/autolink-codegen. Do not edit.
+#import <Foundation/Foundation.h>
+#import <Lynx/LynxModule.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@protocol G9SpeechModuleSpec <LynxModule>
+
+- (void)isAvailable:(NSString *)locale callback:(id)callback;
+- (void)requestPermission:(id)callback;
+- (void)listen:(NSString *)session locale:(NSString *)locale callback:(id)callback;
+- (void)cancel:(NSString *)session;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/src/generated/G9SpeechModuleSpec.m

@@ -0,0 +1,2 @@
+// Generated by @lynx-js/autolink-codegen. Do not edit.
+#import "G9SpeechModuleSpec.h"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@g9tm/lynxcontrols-native",
-  "version": "1.4.3",
+  "version": "1.4.5",
   "description": "Android and iOS platform layer: the G9SqliteModule and G9HostModule native modules (Autolink) and their JS adapters.",
   "license": "MIT",
   "type": "module",
@@ -38,14 +38,14 @@
     "check:android-types": "node scripts/android-bridge-types.mjs"
   },
   "dependencies": {
-    "@g9tm/lynxcontrols-foundation": "1.4.3",
-    "@g9tm/lynxcontrols-sqlite": "1.4.3"
+    "@g9tm/lynxcontrols-foundation": "1.4.5",
+    "@g9tm/lynxcontrols-sqlite": "1.4.5"
   },
   "peerDependencies": {
     "@lynx-js/react": ">=0.126.2 <0.127.0"
   },
   "devDependencies": {
-    "@g9tm/lynxcontrols-lynxtron": "1.4.3",
+    "@g9tm/lynxcontrols-lynxtron": "1.4.5",
     "@lynx-js/autolink-codegen": "0.6.0"
   }
 }

package/types/platform-native-module.d.ts

@@ -44,3 +44,24 @@ export declare class G9HostModule {
    */
   assetUri(path: string, callback: (reply: Record<string, unknown>) => void): void;
 }
+
+/**
+ * Speech recognition for dictation into fields (`G9SpeechToText`, MAUI `IG9SpeechToText`): Android `SpeechRecognizer`,
+ * iOS `SFSpeechRecognizer` over `AVAudioEngine`. One session at a time; interim hypotheses arrive as the global event
+ * `g9:speech` with one JSON argument `{"session","text"}` while the user speaks.
+ *
+ * @lynxmodule
+ */
+export declare class G9SpeechModule {
+  /** Whether a recogniser exists for `locale` on this device (no permission prompt): `{ ok, value: boolean }`. */
+  isAvailable(locale: string, callback: (reply: Record<string, unknown>) => void): void;
+  /** Asks for the microphone (and, on iOS, speech recognition): `{ ok, value: 'granted' | 'denied' | 'restricted' }`. */
+  requestPermission(callback: (reply: Record<string, unknown>) => void): void;
+  /**
+   * Listens once and replies exactly once: `{ ok, value: { status: 'recognized', text } | { status: 'no-match' |
+   * 'cancelled' | 'denied' } }`, or `{ ok: false, error }` for a recogniser fault.
+   */
+  listen(session: string, locale: string, callback: (reply: Record<string, unknown>) => void): void;
+  /** Ends `session` early: its `listen` replies `cancelled`. Unknown or finished sessions are ignored. */
+  cancel(session: string): void;
+}