@g9tm/lynxcontrols-native 0.0.0-stage → 1.4.0

package/ios/src/G9HostModule.m

@@ -0,0 +1,121 @@
+#import "G9HostModule.h"
+#import <UIKit/UIKit.h>
+#import "core/G9HostPaths.h"
+#import "core/G9PreferencesCore.h"
+
+typedef void (^G9Reply)(id envelope);
+
+static NSDictionary *G9Ok(id value) {
+  return @{@"ok" : @YES, @"value" : value ?: [NSNull null]};
+}
+
+@implementation G9HostModule
+
++ (NSString *)name {
+  return @"G9HostModule";
+}
+
++ (NSDictionary<NSString *, NSString *> *)methodLookup {
+  return @{
+    @"capabilities" : NSStringFromSelector(@selector(capabilities:)),
+    @"getPreference" : NSStringFromSelector(@selector(getPreference:callback:)),
+    @"setPreference" : NSStringFromSelector(@selector(setPreference:kind:value:callback:)),
+    @"preferenceEntries" : NSStringFromSelector(@selector(preferenceEntries:callback:)),
+    @"safeInsets" : NSStringFromSelector(@selector(safeInsets:)),
+    @"moveToBack" : NSStringFromSelector(@selector(moveToBack)),
+    @"hideKeyboard" : NSStringFromSelector(@selector(hideKeyboard)),
+    @"setSoftInputMode" : NSStringFromSelector(@selector(setSoftInputMode:)),
+    @"hapticTick" : NSStringFromSelector(@selector(hapticTick)),
+    @"appDataDirectory" : NSStringFromSelector(@selector(appDataDirectory:)),
+    @"assetUri" : NSStringFromSelector(@selector(assetUri:callback:)),
+  };
+}
+
++ (G9PreferencesCore *)preferences {
+  static G9PreferencesCore *core;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    core = [[G9PreferencesCore alloc] initWithBackend:[[G9UserDefaultsBackend alloc] initWithSuiteName:@"g9lynx.preferences"]];
+  });
+  return core;
+}
+
+- (void)capabilities:(id)callback {
+  ((G9Reply)callback)(G9Ok(@{@"haptics" : @YES, @"softInputMode" : @NO, @"video" : @YES, @"platform" : @"ios"}));
+}
+
+- (void)getPreference:(NSString *)key callback:(id)callback {
+  ((G9Reply)callback)(G9Ok([[G9HostModule preferences] get:key]));
+}
+
+- (void)setPreference:(NSString *)key kind:(NSString *)kind value:(nullable NSString *)value callback:(id)callback {
+  NSDictionary *error = nil;
+  BOOL ok = [[G9HostModule preferences] set:key kind:kind value:value error:&error];
+  ((G9Reply)callback)(ok ? G9Ok(nil) : @{@"ok" : @NO, @"error" : error});
+}
+
+- (void)preferenceEntries:(NSString *)prefix callback:(id)callback {
+  ((G9Reply)callback)(G9Ok([[G9HostModule preferences] entries:prefix]));
+}
+
+- (void)appDataDirectory:(id)callback {
+  ((G9Reply)callback)(G9Ok([G9HostPaths appDataDirectory]));
+}
+
+- (void)assetUri:(NSString *)path callback:(id)callback {
+  NSString *uri = [G9HostPaths assetURIForPath:path resourceRoot:NSBundle.mainBundle.resourcePath];
+  if (uri != nil) {
+    ((G9Reply)callback)(G9Ok(uri));
+  } else {
+    NSString *message = [NSString stringWithFormat:@"The app ships no asset \"%@\".", path];
+    ((G9Reply)callback)(@{@"ok" : @NO, @"error" : @{@"code" : @"not-found", @"message" : message}});
+  }
+}
+
+static UIWindow *G9KeyWindow(void) {
+  for (UIScene *scene in UIApplication.sharedApplication.connectedScenes) {
+    if (![scene isKindOfClass:[UIWindowScene class]]) continue;
+    for (UIWindow *window in ((UIWindowScene *)scene).windows) {
+      if (window.isKeyWindow) return window;
+    }
+  }
+  return nil;
+}
+
+- (void)safeInsets:(id)callback {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    UIWindow *window = G9KeyWindow();
+    UIEdgeInsets insets = window != nil ? window.safeAreaInsets : UIEdgeInsetsZero;
+    BOOL rtl = [UIView userInterfaceLayoutDirectionForSemanticContentAttribute:window.semanticContentAttribute] ==
+               UIUserInterfaceLayoutDirectionRightToLeft;
+    ((G9Reply)callback)(G9Ok(@{
+      @"top" : @(insets.top),
+      @"bottom" : @(insets.bottom),
+      @"start" : @(rtl ? insets.right : insets.left),
+      @"end" : @(rtl ? insets.left : insets.right),
+    }));
+  });
+}
+
+// iOS has no programmatic "leave the app"; the system owns it (specs/06 §7).
+- (void)moveToBack {
+}
+
+- (void)hideKeyboard {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [UIApplication.sharedApplication sendAction:@selector(resignFirstResponder) to:nil from:nil forEvent:nil];
+  });
+}
+
+// Soft-input modes are an Android concept.
+- (void)setSoftInputMode:(NSString *)mode {
+}
+
+- (void)hapticTick {
+  dispatch_async(dispatch_get_main_queue(), ^{
+    UIImpactFeedbackGenerator *generator = [[UIImpactFeedbackGenerator alloc] initWithStyle:UIImpactFeedbackStyleLight];
+    [generator impactOccurred];
+  });
+}
+
+@end

package/ios/src/G9SqliteModule.h

@@ -0,0 +1,14 @@
+#import <Foundation/Foundation.h>
+#import <Lynx/LynxModule.h>
+#import "generated/G9SqliteModuleSpec.h"
+
+NS_ASSUME_NONNULL_BEGIN
+
+// Lynx 4.0.3 (the iOS pods) has no @LynxNativeModuleRegister: hosts register the module on their LynxConfig
+// (`[config registerModule:G9SqliteModule.class]`, apps/ios-host/Sources/GalleryViewController.m).
+
+/** `NativeModules.G9SqliteModule` on iOS (plan/specs/06 §5): G9SqliteCore over the system sqlite3, one serial queue per session. */
+@interface G9SqliteModule : NSObject <G9SqliteModuleSpec>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/src/G9SqliteModule.m

@@ -0,0 +1,167 @@
+#import "G9SqliteModule.h"
+#import "core/G9SqliteCore.h"
+#import "core/G9SqliteTransport.h"
+
+typedef void (^G9Reply)(id envelope);
+
+static const NSInteger G9QueueCapacity = 256;
+
+/** One process-wide core and its queues, so every LynxView of the app shares the open databases. */
+@interface G9SqliteService : NSObject
+@property(nonatomic, readonly) G9SqliteCore *core;
++ (instancetype)shared;
+- (void)submit:(nullable NSString *)session callback:(id)callback work:(id (^)(NSDictionary **error))work;
+- (void)retire:(NSString *)session;
+@end
+
+@implementation G9SqliteService {
+  NSMutableDictionary<NSString *, dispatch_queue_t> *_queues;
+  NSMutableDictionary<NSString *, NSNumber *> *_pending;
+  dispatch_queue_t _shared;
+}
+
++ (instancetype)shared {
+  static G9SqliteService *service;
+  static dispatch_once_t once;
+  dispatch_once(&once, ^{
+    service = [[G9SqliteService alloc] init];
+  });
+  return service;
+}
+
+- (instancetype)init {
+  if ((self = [super init])) {
+    _core = [[G9SqliteCore alloc] init];
+    _queues = [NSMutableDictionary dictionary];
+    _pending = [NSMutableDictionary dictionary];
+    _shared = dispatch_queue_create("g9.sqlite.open", DISPATCH_QUEUE_SERIAL);
+  }
+  return self;
+}
+
+- (dispatch_queue_t)queueFor:(NSString *)session {
+  if (session == nil) return _shared;
+  @synchronized(self) {
+    dispatch_queue_t queue = _queues[session];
+    if (queue == nil) {
+      queue = dispatch_queue_create([[@"g9.sqlite." stringByAppendingString:session] UTF8String], DISPATCH_QUEUE_SERIAL);
+      _queues[session] = queue;
+    }
+    return queue;
+  }
+}
+
+- (void)submit:(NSString *)session callback:(id)callback work:(id (^)(NSDictionary **error))work {
+  G9Reply reply = (G9Reply)callback;
+  NSString *key = session ?: @"";
+  @synchronized(self) {
+    NSInteger pending = [_pending[key] integerValue];
+    if (pending >= G9QueueCapacity) {
+      if (reply) reply(@{@"ok" : @NO, @"error" : G9SqliteErrorMake(@"busy", @"Too many queued requests for this database session.")});
+      return;
+    }
+    _pending[key] = @(pending + 1);
+  }
+  dispatch_async([self queueFor:session], ^{
+    NSDictionary *error = nil;
+    id value = nil;
+    @autoreleasepool {
+      value = work(&error);
+    }
+    @synchronized(self) {
+      self->_pending[key] = @([self->_pending[key] integerValue] - 1);
+    }
+    if (reply) reply(error != nil ? @{@"ok" : @NO, @"error" : error} : @{@"ok" : @YES, @"value" : value ?: [NSNull null]});
+  });
+}
+
+- (void)retire:(NSString *)session {
+  @synchronized(self) {
+    [_queues removeObjectForKey:session];
+    [_pending removeObjectForKey:session];
+  }
+}
+
+@end
+
+@implementation G9SqliteModule
+
++ (NSString *)name {
+  return @"G9SqliteModule";
+}
+
++ (NSDictionary<NSString *, NSString *> *)methodLookup {
+  return @{
+    @"capabilities" : NSStringFromSelector(@selector(capabilities:)),
+    @"open" : NSStringFromSelector(@selector(open:callback:)),
+    @"run" : NSStringFromSelector(@selector(run:statements:options:callback:)),
+    @"begin" : NSStringFromSelector(@selector(begin:mode:callback:)),
+    @"commit" : NSStringFromSelector(@selector(commit:callback:)),
+    @"rollback" : NSStringFromSelector(@selector(rollback:callback:)),
+    @"close" : NSStringFromSelector(@selector(close:callback:)),
+    @"interrupt" : NSStringFromSelector(@selector(interrupt:)),
+  };
+}
+
+- (G9SqliteService *)service {
+  return [G9SqliteService shared];
+}
+
+- (void)capabilities:(id)callback {
+  G9SqliteCore *core = self.service.core;
+  [self.service submit:nil callback:callback work:^id(NSDictionary **error) {
+    return [core capabilitiesWithError:error];
+  }];
+}
+
+- (void)open:(id)options callback:(id)callback {
+  G9SqliteCore *core = self.service.core;
+  [self.service submit:nil callback:callback work:^id(NSDictionary **error) {
+    return [core open:[options isKindOfClass:[NSDictionary class]] ? options : @{} error:error];
+  }];
+}
+
+- (void)run:(NSString *)session statements:(id)statements options:(id)options callback:(id)callback {
+  G9SqliteCore *core = self.service.core;
+  NSDictionary *opts = [options isKindOfClass:[NSDictionary class]] ? options : @{};
+  [self.service submit:session callback:callback work:^id(NSDictionary **error) {
+    NSArray *results = [core run:session statements:[statements isKindOfClass:[NSArray class]] ? statements : @[] options:opts error:error];
+    return results == nil ? nil : [G9SqliteTransport encode:results transport:opts[@"transport"]];
+  }];
+}
+
+- (void)begin:(NSString *)session mode:(NSString *)mode callback:(id)callback {
+  G9SqliteCore *core = self.service.core;
+  [self.service submit:session callback:callback work:^id(NSDictionary **error) {
+    return [core begin:session mode:mode error:error];
+  }];
+}
+
+- (void)commit:(NSString *)tx callback:(id)callback {
+  G9SqliteCore *core = self.service.core;
+  [self.service submit:[core sessionOfTx:tx] callback:callback work:^id(NSDictionary **error) {
+    return [core commit:tx error:error] ? [NSNull null] : nil;
+  }];
+}
+
+- (void)rollback:(NSString *)tx callback:(id)callback {
+  G9SqliteCore *core = self.service.core;
+  [self.service submit:[core sessionOfTx:tx] callback:callback work:^id(NSDictionary **error) {
+    return [core rollback:tx error:error] ? [NSNull null] : nil;
+  }];
+}
+
+- (void)close:(NSString *)session callback:(id)callback {
+  G9SqliteService *service = self.service;
+  [service submit:session callback:callback work:^id(NSDictionary **error) {
+    BOOL closed = [service.core close:session error:error];
+    [service retire:session];
+    return closed ? [NSNull null] : nil;
+  }];
+}
+
+- (void)interrupt:(NSString *)session {
+  [self.service.core interrupt:session];
+}
+
+@end

package/ios/src/G9VideoUI.h

@@ -0,0 +1,21 @@
+#import <Lynx/LynxUI.h>
+#import <UIKit/UIKit.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** The element's view: its backing layer is an `AVPlayerLayer`. */
+@interface G9VideoView : UIView
+@end
+
+/**
+ * The `<g9-video>` element on iOS (plan/specs/06 §7), the same contract as Android's `G9VideoUI.kt`: muted looping
+ * playback (`AVQueuePlayer` + `AVPlayerLooper`) for the intro carousel. Props: `src` (`file://…`, `http(s)://…`),
+ * `paused` (default YES), `loop`, `muted` (default YES), `start-seconds`, `near-end-seconds`, `object-fit`
+ * (`cover` | `contain`). Events: `ready` (first frame displayable), `nearend` `{ seconds }`, `looped`, `error`
+ * `{ code, message }`. Self-registers as `g9-video` (`LYNX_REGISTER_UI`); a host may also call
+ * `[config registerUI:G9VideoUI.class withName:@"g9-video"]`.
+ */
+@interface G9VideoUI : LynxUI <G9VideoView *>
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/src/G9VideoUI.m

@@ -0,0 +1,250 @@
+#import "G9VideoUI.h"
+#import <AVFoundation/AVFoundation.h>
+#import <Lynx/LynxComponentRegistry.h>
+#import <Lynx/LynxEvent.h>
+#import <Lynx/LynxEventEmitter.h>
+#import <Lynx/LynxPropsProcessor.h>
+#import <Lynx/LynxUIContext.h>
+#import "core/G9VideoCore.h"
+#include <math.h>
+
+static void *G9VideoKVO = &G9VideoKVO;
+
+@implementation G9VideoView
+
++ (Class)layerClass {
+  return AVPlayerLayer.class;
+}
+
+- (AVPlayerLayer *)playerLayer {
+  return (AVPlayerLayer *)self.layer;
+}
+
+@end
+
+@implementation G9VideoUI {
+  AVQueuePlayer *_player;
+  AVPlayerLooper *_looper;
+  id _timeObserver;
+  NSString *_src;
+  NSString *_preparedSrc;
+  BOOL _prepared;
+  BOOL _paused;
+  BOOL _loop;
+  BOOL _preparedLoop;
+  BOOL _muted;
+  BOOL _cover;
+  BOOL _startApplied;
+  BOOL _readySent;
+  BOOL _applyScheduled;
+  double _startSeconds;
+  NSInteger _loopCount;
+  G9VideoLoopTracker *_tracker;
+}
+
+LYNX_REGISTER_UI("g9-video")
+
+- (instancetype)init {
+  if ((self = [super init])) {
+    _paused = YES;
+    _loop = YES;
+    _muted = YES;
+    _cover = YES;
+    _tracker = [[G9VideoLoopTracker alloc] init];
+  }
+  return self;
+}
+
+- (G9VideoView *)createView {
+  G9VideoView *view = [[G9VideoView alloc] init];
+  view.clipsToBounds = YES;
+  view.userInteractionEnabled = NO;
+  ((AVPlayerLayer *)view.layer).videoGravity = AVLayerVideoGravityResizeAspectFill;
+  return view;
+}
+
+LYNX_PROP_SETTER("src", setSrc, NSString *) {
+  _src = (requestReset || value.length == 0) ? nil : [value copy];
+  [self scheduleApply];
+}
+
+LYNX_PROP_SETTER("paused", setPaused, BOOL) {
+  _paused = requestReset ? YES : value;
+  [self scheduleApply];
+}
+
+LYNX_PROP_SETTER("loop", setLoop, BOOL) {
+  _loop = requestReset ? YES : value;
+  [self scheduleApply];
+}
+
+LYNX_PROP_SETTER("muted", setMuted, BOOL) {
+  _muted = requestReset ? YES : value;
+  [self scheduleApply];
+}
+
+LYNX_PROP_SETTER("start-seconds", setStartSeconds, double) {
+  _startSeconds = requestReset ? 0 : value;
+}
+
+LYNX_PROP_SETTER("near-end-seconds", setNearEndSeconds, double) {
+  _tracker.nearEndSeconds = requestReset ? 0 : value;
+}
+
+LYNX_PROP_SETTER("object-fit", setObjectFit, NSString *) {
+  _cover = requestReset || ![value isEqualToString:@"contain"];
+  [self scheduleApply];
+}
+
+// Props arrive one setter at a time; apply them together once per main-queue turn.
+- (void)scheduleApply {
+  if (_applyScheduled) return;
+  _applyScheduled = YES;
+  __weak G9VideoUI *weakSelf = self;
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [weakSelf apply];
+  });
+}
+
+- (void)apply {
+  _applyScheduled = NO;
+  ((AVPlayerLayer *)self.view.layer).videoGravity =
+      _cover ? AVLayerVideoGravityResizeAspectFill : AVLayerVideoGravityResizeAspect;
+  BOOL sourceChanged = !(_src == _preparedSrc || [_src isEqualToString:_preparedSrc]);
+  if (!_prepared || sourceChanged || _loop != _preparedLoop) [self prepare];
+  if (_player == nil) return;
+  _player.muted = _muted;
+  if (_paused) {
+    [_player pause];
+  } else {
+    [_player play];
+  }
+}
+
+- (void)prepare {
+  [self teardown];
+  _prepared = YES;
+  _preparedSrc = _src;
+  _preparedLoop = _loop;
+  if (_src == nil) return;
+  NSURL *url = [NSURL URLWithString:_src];
+  if (url == nil) {
+    [self send:@"error" detail:@{@"code" : @"invalid-src", @"message" : @"The video source is not a URL."}];
+    return;
+  }
+  _startApplied = NO;
+  _readySent = NO;
+  _loopCount = 0;
+  [_tracker looped];
+  AVPlayerItem *item = [AVPlayerItem playerItemWithURL:url];
+  _player = [AVQueuePlayer queuePlayerWithItems:@[]];
+  _player.muted = _muted;
+  if (_loop) {
+    _looper = [AVPlayerLooper playerLooperWithPlayer:_player templateItem:item];
+    [_looper addObserver:self forKeyPath:@"loopCount" options:NSKeyValueObservingOptionNew context:G9VideoKVO];
+    [_looper addObserver:self forKeyPath:@"status" options:NSKeyValueObservingOptionNew context:G9VideoKVO];
+  } else {
+    [_player insertItem:item afterItem:nil];
+  }
+  [_player addObserver:self forKeyPath:@"currentItem.status" options:NSKeyValueObservingOptionNew context:G9VideoKVO];
+  AVPlayerLayer *layer = (AVPlayerLayer *)self.view.layer;
+  layer.player = _player;
+  [layer addObserver:self forKeyPath:@"readyForDisplay" options:NSKeyValueObservingOptionNew context:G9VideoKVO];
+  __weak G9VideoUI *weakSelf = self;
+  _timeObserver = [_player addPeriodicTimeObserverForInterval:CMTimeMakeWithSeconds(0.1, 600)
+                                                        queue:dispatch_get_main_queue()
+                                                   usingBlock:^(CMTime time) {
+                                                     [weakSelf tick:time];
+                                                   }];
+}
+
+- (void)tick:(CMTime)time {
+  AVPlayerItem *item = _player.currentItem;
+  if (item == nil) return;
+  double duration = CMTimeGetSeconds(item.duration);
+  double position = CMTimeGetSeconds(time);
+  if (!isfinite(duration) || !isfinite(position)) return;
+  NSNumber *left = [_tracker progressPositionMs:position * 1000.0 durationMs:duration * 1000.0];
+  if (left != nil) [self send:@"nearend" detail:@{@"seconds" : left}];
+}
+
+- (void)observeValueForKeyPath:(NSString *)keyPath
+                      ofObject:(id)object
+                        change:(NSDictionary<NSKeyValueChangeKey, id> *)change
+                       context:(void *)context {
+  if (context != G9VideoKVO) {
+    [super observeValueForKeyPath:keyPath ofObject:object change:change context:context];
+    return;
+  }
+  dispatch_async(dispatch_get_main_queue(), ^{
+    [self handleChange:keyPath of:object];
+  });
+}
+
+- (void)handleChange:(NSString *)keyPath of:(id)object {
+  if (_player == nil) return;
+  if ([keyPath isEqualToString:@"readyForDisplay"]) {
+    if (!_readySent && ((AVPlayerLayer *)self.view.layer).readyForDisplay) {
+      _readySent = YES;
+      [self send:@"ready" detail:@{}];
+    }
+  } else if ([keyPath isEqualToString:@"loopCount"]) {
+    if (_looper.loopCount > _loopCount) {
+      _loopCount = _looper.loopCount;
+      [_tracker looped];
+      [self send:@"looped" detail:@{}];
+    }
+  } else if ([keyPath isEqualToString:@"status"] && object == _looper) {
+    if (_looper.status == AVPlayerLooperStatusFailed) [self fail:_looper.error];
+  } else if ([keyPath isEqualToString:@"currentItem.status"]) {
+    AVPlayerItem *item = _player.currentItem;
+    if (item.status == AVPlayerItemStatusFailed) {
+      [self fail:item.error];
+    } else if (item.status == AVPlayerItemStatusReadyToPlay && !_startApplied) {
+      _startApplied = YES;
+      double duration = CMTimeGetSeconds(item.duration);
+      NSNumber *start = [G9VideoMath startPositionMsForSeconds:_startSeconds
+                                                    durationMs:isfinite(duration) ? duration * 1000.0 : 0];
+      if (start != nil) {
+        [_player seekToTime:CMTimeMakeWithSeconds(start.doubleValue / 1000.0, 600)
+            toleranceBefore:kCMTimeZero
+             toleranceAfter:kCMTimeZero];
+      }
+    }
+  }
+}
+
+- (void)fail:(NSError *)error {
+  NSString *message = error.localizedDescription ?: @"The video could not be played.";
+  [self send:@"error" detail:@{@"code" : [NSString stringWithFormat:@"%ld", (long)error.code], @"message" : message}];
+}
+
+- (void)send:(NSString *)name detail:(NSDictionary *)detail {
+  LynxDetailEvent *event = [[LynxDetailEvent alloc] initWithName:name targetSign:self.sign detail:detail];
+  [self.context.eventEmitter dispatchCustomEvent:event];
+}
+
+- (void)teardown {
+  if (_player == nil) return;
+  AVPlayerLayer *layer = (AVPlayerLayer *)self.view.layer;
+  [layer removeObserver:self forKeyPath:@"readyForDisplay" context:G9VideoKVO];
+  [_player removeObserver:self forKeyPath:@"currentItem.status" context:G9VideoKVO];
+  if (_looper != nil) {
+    [_looper removeObserver:self forKeyPath:@"loopCount" context:G9VideoKVO];
+    [_looper removeObserver:self forKeyPath:@"status" context:G9VideoKVO];
+    [_looper disableLooping];
+    _looper = nil;
+  }
+  if (_timeObserver != nil) [_player removeTimeObserver:_timeObserver];
+  _timeObserver = nil;
+  [_player pause];
+  [_player removeAllItems];
+  layer.player = nil;
+  _player = nil;
+}
+
+- (void)dealloc {
+  [self teardown];
+}
+
+@end

package/ios/src/core/G9HostPaths.h

@@ -0,0 +1,20 @@
+// Where an iOS app's files are (plan/specs/06 §7): the app data directory and bundled assets. Foundation only, so the
+// Linux harness (`npm run test:ios-core`) runs it.
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface G9HostPaths : NSObject
+/**
+ * The app's private data directory, absolute (MAUI `FileSystem.AppDataDirectory` on iOS: the user-domain `Library`
+ * directory), created if missing, so an app keeps the files its MAUI version wrote.
+ */
++ (NSString *)appDataDirectory;
+/**
+ * The `file://` URI of `path` under `resourceRoot` (the main bundle's resources), or nil when the app does not ship
+ * it or the path escapes the root (`..`).
+ */
++ (nullable NSString *)assetURIForPath:(NSString *)path resourceRoot:(NSString *)resourceRoot;
+@end
+
+NS_ASSUME_NONNULL_END

package/ios/src/core/G9HostPaths.m

@@ -0,0 +1,23 @@
+#import "G9HostPaths.h"
+
+@implementation G9HostPaths
+
++ (NSString *)appDataDirectory {
+  NSArray *found = NSSearchPathForDirectoriesInDomains(NSLibraryDirectory, NSUserDomainMask, YES);
+  NSString *path = [found count] > 0 ? [found objectAtIndex:0] : nil;
+  if (path == nil) path = [NSHomeDirectory() stringByAppendingPathComponent:@"Library"];
+  [[NSFileManager defaultManager] createDirectoryAtPath:path withIntermediateDirectories:YES attributes:nil error:NULL];
+  return path;
+}
+
++ (nullable NSString *)assetURIForPath:(NSString *)path resourceRoot:(NSString *)resourceRoot {
+  NSString *relative = path;
+  while ([relative hasPrefix:@"/"]) relative = [relative substringFromIndex:1];
+  if ([relative length] == 0 || [[relative pathComponents] containsObject:@".."]) return nil;
+  NSString *full = [resourceRoot stringByAppendingPathComponent:relative];
+  BOOL isDir = NO;
+  if (![[NSFileManager defaultManager] fileExistsAtPath:full isDirectory:&isDir] || isDir) return nil;
+  return [[NSURL fileURLWithPath:full] absoluteString];
+}
+
+@end

package/ios/src/core/G9PreferencesCore.h

@@ -0,0 +1,43 @@
+// The G9PreferenceStore operations of G9HostModule (plan/specs/06 §7), as on Android: typed values (a 32-bit integer is
+// not readable as a string and vice versa), `null` string removes, prefix enumeration. Foundation only.
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+/** Where values live: NSUserDefaults in the module, a dictionary in tests. */
+@protocol G9PreferenceBackend <NSObject>
+- (NSDictionary *)allValues;
+- (void)setValue:(id)value forPreference:(NSString *)key;
+- (void)removePreference:(NSString *)key;
+@end
+
+@interface G9PreferencesCore : NSObject {
+ @private
+  id<G9PreferenceBackend> _backend;
+}
+- (instancetype)initWithBackend:(id<G9PreferenceBackend>)backend;
+/** `{ type: 'int' | 'string', value }` or NSNull. */
+- (id)get:(NSString *)key;
+/** `kind`: `int` (decimal text of a 32-bit integer), `string` (nil removes) or `remove`. NO with `error` on bad input. */
+- (BOOL)set:(NSString *)key kind:(NSString *)kind value:(nullable NSString *)value error:(NSDictionary *_Nullable *_Nullable)error;
+/** `[[key, value], …]` for keys starting with `prefix`, sorted by key. */
+- (NSArray *)entries:(NSString *)prefix;
+@end
+
+/** NSUserDefaults with one suite per app (`g9lynx.preferences`). */
+@interface G9UserDefaultsBackend : NSObject <G9PreferenceBackend> {
+ @private
+  NSUserDefaults *_defaults;
+  NSString *_suite;
+}
+- (instancetype)initWithSuiteName:(NSString *)suite;
+@end
+
+/** An in-memory backend (tests). */
+@interface G9MemoryPreferenceBackend : NSObject <G9PreferenceBackend> {
+ @private
+  NSMutableDictionary *_values;
+}
+@end
+
+NS_ASSUME_NONNULL_END