@sigx/lynx-appearance 0.4.1

package/dist/setters.js

@@ -0,0 +1,87 @@
+import { callAsync, isModuleAvailable } from '@sigx/lynx-core';
+const MODULE = 'Appearance';
+const UNSUPPORTED = { ok: false, reason: 'unsupported' };
+/**
+ * Set the status-bar *content* tint (clock + icons).
+ *
+ * - `'light'` = light content (white-ish icons) — use when behind a dark theme.
+ * - `'dark'`  = dark content — use when behind a light theme.
+ *
+ * On iOS the host VC must forward `preferredStatusBarStyle` to
+ * `AppearanceModule.preferredStatusBarStyle` for this to take effect — the
+ * lynx-cli iOS template wires that automatically.
+ *
+ * Resolves `{ ok: false, reason: 'unsupported' }` (never rejects) when the
+ * native module isn't registered — typical in web preview, SSR, tests, or
+ * apps that don't link the module. Fire-and-forget callers can therefore
+ * `void setStatusBarStyle(...)` without risking unhandled rejections.
+ */
+export function setStatusBarStyle(style) {
+    if (!isAvailable())
+        return Promise.resolve(UNSUPPORTED);
+    return callAsync(MODULE, 'setStatusBarStyle', { style });
+}
+/**
+ * Android only — set the status-bar background color. Pass `null` (or
+ * omit / pass `'transparent'`) to clear. iOS resolves `{ ok: false,
+ * reason: 'unsupported' }` since iOS has no separate status-bar background.
+ *
+ * On Android 15+ (API 35) edge-to-edge is enforced and this call is a no-op
+ * at the system level — callers should overlay their own background view
+ * inside the safe-area top padding.
+ *
+ * Resolves `{ ok: false, reason: 'unsupported' }` (never rejects) when the
+ * native module isn't registered. See `setStatusBarStyle` for the rationale.
+ */
+export function setStatusBarBackgroundColor(color) {
+    if (!isAvailable())
+        return Promise.resolve(UNSUPPORTED);
+    return callAsync(MODULE, 'setStatusBarBackgroundColor', { color });
+}
+/**
+ * Android only — set the navigation-bar content tint + optional background.
+ * iOS resolves `{ ok: false, reason: 'unsupported' }` since there's no
+ * separate navigation bar.
+ *
+ * Resolves `{ ok: false, reason: 'unsupported' }` (never rejects) when the
+ * native module isn't registered. See `setStatusBarStyle` for the rationale.
+ */
+export function setNavigationBarStyle(opts) {
+    if (!isAvailable())
+        return Promise.resolve(UNSUPPORTED);
+    return callAsync(MODULE, 'setNavigationBarStyle', opts);
+}
+/**
+ * Convenience: apply status-bar tint + (optionally) status-bar background +
+ * nav-bar tint in one call. Resolves to the aggregate result — `ok: false`
+ * if any leg returned a non-`unsupported` failure, with the first such
+ * failure's reason. `unsupported` legs (e.g. status-bar background on iOS)
+ * are intentionally ignored so a partially-supported platform can still
+ * report success for the legs that do apply.
+ *
+ * Fields are optional; omitting any leaves that surface untouched. Order is
+ * deterministic (statusBar → statusBarBackground → navigationBar) so the
+ * resolved reason on partial failure is unambiguous.
+ */
+export async function setSystemBarsStyle(opts) {
+    if (!isAvailable())
+        return UNSUPPORTED;
+    let firstFailure;
+    const record = (r) => {
+        if (!r.ok && !firstFailure && r.reason !== 'unsupported')
+            firstFailure = r;
+    };
+    if (opts.statusBar)
+        record(await setStatusBarStyle(opts.statusBar));
+    if (opts.statusBarBackground !== undefined) {
+        record(await setStatusBarBackgroundColor(opts.statusBarBackground));
+    }
+    if (opts.navigationBar)
+        record(await setNavigationBarStyle(opts.navigationBar));
+    return firstFailure ?? { ok: true };
+}
+/** Quick check whether the native Appearance module is registered. */
+export function isAvailable() {
+    return isModuleAvailable(MODULE);
+}
+//# sourceMappingURL=setters.js.map

package/dist/setters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"setters.js","sourceRoot":"","sources":["../src/setters.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAG/D,MAAM,MAAM,GAAG,YAAY,CAAC;AAE5B,MAAM,WAAW,GAAiB,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAqB;IACrD,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACxD,OAAO,SAAS,CAAe,MAAM,EAAE,mBAAmB,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,2BAA2B,CAAC,KAAoB;IAC9D,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACxD,OAAO,SAAS,CAAe,MAAM,EAAE,6BAA6B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;AACnF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAA+C;IACnF,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,OAAO,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACxD,OAAO,SAAS,CAAe,MAAM,EAAE,uBAAuB,EAAE,IAAI,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CAAC,IAA0B;IACjE,IAAI,CAAC,WAAW,EAAE;QAAE,OAAO,WAAW,CAAC;IACvC,IAAI,YAAsC,CAAC;IAC3C,MAAM,MAAM,GAAG,CAAC,CAAe,EAAQ,EAAE;QACvC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,MAAM,KAAK,aAAa;YAAE,YAAY,GAAG,CAAC,CAAC;IAC7E,CAAC,CAAC;IACF,IAAI,IAAI,CAAC,SAAS;QAAE,MAAM,CAAC,MAAM,iBAAiB,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC;IACpE,IAAI,IAAI,CAAC,mBAAmB,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,MAAM,2BAA2B,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC,CAAC;IACtE,CAAC;IACD,IAAI,IAAI,CAAC,aAAa;QAAE,MAAM,CAAC,MAAM,qBAAqB,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC;IAChF,OAAO,YAAY,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtC,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,WAAW;IACzB,OAAO,iBAAiB,CAAC,MAAM,CAAC,CAAC;AACnC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/** The two color schemes the platform reports. iOS `unspecified` and
+ *  Android `UI_MODE_NIGHT_UNDEFINED` both collapse to `'light'` at the
+ *  native publisher boundary so JS only ever sees these two values. */
+export type ColorScheme = 'light' | 'dark';
+/** Tint of system-bar *content* (clock, icons), not its background. */
+export type SystemBarStyle = 'light' | 'dark';
+/** Result envelope returned by every native setter. */
+export interface SetterResult {
+    ok: boolean;
+    /** Present when `ok === false` — `'unsupported'` on iOS for nav-bar and
+     *  status-bar-background calls, or an Android failure message. */
+    reason?: string;
+}
+/** Argument to `setSystemBarsStyle` — partial; omitted fields are left alone. */
+export interface SystemBarsStyleInput {
+    /** Status-bar content tint. `'light'` = light icons (legible on dark bg). */
+    statusBar?: SystemBarStyle;
+    /** Android only — status-bar background color. `null` clears (transparent). */
+    statusBarBackground?: string | null;
+    /** Android only — navigation-bar tint + optional background. */
+    navigationBar?: {
+        style: SystemBarStyle;
+        color?: string;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;uEAEuE;AACvE,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C,uEAAuE;AACvE,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,uDAAuD;AACvD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,OAAO,CAAC;IACZ;sEACkE;IAClE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,iFAAiF;AACjF,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,+EAA+E;IAC/E,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,gEAAgE;IAChE,aAAa,CAAC,EAAE;QAAE,KAAK,EAAE,cAAc,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CAC3D"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/ios/AppearanceModule.swift

@@ -0,0 +1,130 @@
+import UIKit
+import Lynx
+
+/// System-bar appearance setters + a sync getter for the current color scheme.
+/// JS usage:
+///   NativeModules.Appearance.setStatusBarStyle({ "style": "light" }, callback)
+///   NativeModules.Appearance.getColorScheme(callback)
+///
+/// iOS exposes two routes to control status-bar style; we try both so apps
+/// don't have to wire boilerplate:
+///
+/// 1. **VC-controlled (modern, default)** — iOS reads
+///    `preferredStatusBarStyle` from the root view controller. The host app
+///    overrides that getter to return `AppearanceModule.preferredStatusBarStyle`
+///    (the static we update). We call `setNeedsStatusBarAppearanceUpdate()` to
+///    force a re-evaluation.
+///
+/// 2. **UIApplication-controlled (legacy)** — if the host's Info.plist has
+///    `UIViewControllerBasedStatusBarAppearance = NO`, iOS reads style from
+///    `UIApplication.shared` directly. We invoke the deprecated setter via
+///    `perform(_:with:with:)` so SwiftUI hosts (which can't easily override
+///    their hidden UIHostingController) get a working path with one plist
+///    change. Apps that leave the plist default (YES) get the silent no-op
+///    for this leg — Path 1 covers them.
+///
+/// `setStatusBarBackgroundColor` and `setNavigationBarStyle` are Android-only
+/// in practice. iOS resolves the system-bar background from the underlying
+/// view's color and has no separate navigation bar. We return
+/// `{ ok: false, reason: "unsupported" }` so JS callers can decide whether to
+/// treat that as an error.
+class AppearanceModule: NSObject, LynxModule {
+
+    /// Last requested status-bar style; the host VC's
+    /// `preferredStatusBarStyle` should return this.
+    @objc public static var preferredStatusBarStyle: UIStatusBarStyle = .default
+
+    @objc static var name: String { "Appearance" }
+
+    @objc static var methodLookup: [String: String] {
+        [
+            "setStatusBarStyle": NSStringFromSelector(#selector(setStatusBarStyle(_:callback:))),
+            "setStatusBarBackgroundColor": NSStringFromSelector(#selector(setStatusBarBackgroundColor(_:callback:))),
+            "setNavigationBarStyle": NSStringFromSelector(#selector(setNavigationBarStyle(_:callback:))),
+            "getColorScheme": NSStringFromSelector(#selector(getColorScheme(_:))),
+        ]
+    }
+
+    required override init() { super.init() }
+    required init(param: Any) { super.init() }
+
+    @objc func setStatusBarStyle(_ params: [String: Any]?, callback: LynxCallbackBlock?) {
+        let style = (params?["style"] as? String) ?? "default"
+        // 'light' style means "light content" — i.e. white icons on a dark
+        // background. 'dark' means dark icons on a light background.
+        // iOS uses lightContent / darkContent to express the *content* color.
+        let resolved: UIStatusBarStyle
+        switch style {
+        case "light":
+            resolved = .lightContent
+        case "dark":
+            resolved = .darkContent
+        default:
+            resolved = .default
+        }
+
+        DispatchQueue.main.async {
+            AppearanceModule.preferredStatusBarStyle = resolved
+
+            // Path 1 — VC-controlled (the modern, recommended path):
+            // re-evaluate `preferredStatusBarStyle` on every key window's
+            // root view controller. The host app's VC must override
+            // `preferredStatusBarStyle` to return
+            // `AppearanceModule.preferredStatusBarStyle` for this to take
+            // effect.
+            for scene in UIApplication.shared.connectedScenes {
+                guard let windowScene = scene as? UIWindowScene else { continue }
+                for window in windowScene.windows {
+                    window.rootViewController?.setNeedsStatusBarAppearanceUpdate()
+                }
+            }
+
+            // Path 2 — UIApplication-controlled (legacy, deprecated but
+            // still functional when `UIViewControllerBasedStatusBarAppearance`
+            // is `false` in Info.plist). For SwiftUI hosts where overriding
+            // a UIHostingController's preferredStatusBarStyle is awkward,
+            // setting that plist key to NO and letting this path do the work
+            // is the path of least resistance. No-op on apps that leave the
+            // plist key default (true) — iOS silently ignores the call.
+            //
+            // Invoked via `perform(_:with:with:)` so the deprecation warning
+            // doesn't fire at this single intentional call site.
+            let plist = Bundle.main.infoDictionary
+            let vcBased = (plist?["UIViewControllerBasedStatusBarAppearance"] as? Bool) ?? true
+            if !vcBased {
+                let app = UIApplication.shared
+                let sel = NSSelectorFromString("setStatusBarStyle:animated:")
+                if app.responds(to: sel) {
+                    app.perform(sel, with: resolved.rawValue, with: true)
+                }
+            }
+
+            callback?(["ok": true])
+        }
+    }
+
+    @objc func setStatusBarBackgroundColor(_ params: [String: Any]?, callback: LynxCallbackBlock?) {
+        // No-op on iOS — the status bar background is the underlying view's
+        // color, not a system property we can set.
+        _ = params
+        callback?(["ok": false, "reason": "unsupported"])
+    }
+
+    @objc func setNavigationBarStyle(_ params: [String: Any]?, callback: LynxCallbackBlock?) {
+        // No-op on iOS — there's no separate navigation bar to style.
+        _ = params
+        callback?(["ok": false, "reason": "unsupported"])
+    }
+
+    @objc func getColorScheme(_ callback: LynxCallbackBlock?) {
+        // Read from the active key window so we pick up the user's preference
+        // even if no LynxView has fired its publisher yet.
+        let style = UIApplication.shared.connectedScenes
+            .compactMap { $0 as? UIWindowScene }
+            .first(where: { $0.activationState == .foregroundActive })?
+            .windows.first?.traitCollection.userInterfaceStyle
+            ?? UITraitCollection.current.userInterfaceStyle
+        let scheme = style == .dark ? "dark" : "light"
+        callback?(["colorScheme": scheme])
+    }
+}

package/ios/AppearancePublisher.swift

@@ -0,0 +1,86 @@
+import UIKit
+import Lynx
+
+/// Publishes the host's current system color scheme (light / dark) to JS via:
+///
+/// 1. **`lynx.__globalProps.appearance`** — populated synchronously via
+///    `LynxView.updateGlobalProps(withDictionary:)` before MT first paint, so
+///    apps can render the correct theme on cold start without a flash.
+///
+/// 2. **`appearanceChanged` global event** — fired via
+///    `LynxView.sendGlobalEvent(_:withParams:)` whenever the trait collection
+///    flips light/dark. JS-side `<AppearanceProvider>` subscribes via
+///    `lynx.getJSModule("GlobalEventEmitter").addListener` and updates its
+///    reactive signal so consumers (e.g. `<ThemeProvider>` with `followSystem`)
+///    swap themes live.
+///
+/// One publisher per `LynxView`. The autolinker wires
+/// `GeneratedLifecyclePublishers.attachAll(to: lynxView)` to instantiate this
+/// after each LynxView is built; the host coordinator retains the instance for
+/// the LynxView's lifetime.
+final class AppearancePublisher {
+    private weak var lynxView: LynxView?
+    private var lastScheme: String = ""
+
+    init(lynxView: LynxView) {
+        self.lynxView = lynxView
+
+        // Observe trait-collection changes via the window — handles the
+        // Settings → Display & Brightness → Appearance flip in real time.
+        // UIScreen.traitCollectionDidChange isn't reliable here (only fires
+        // when the screen *itself* changes), so we listen for the
+        // app-foreground notification (catches changes made while the app was
+        // backgrounded) and rely on the LynxContainerView's trait observer to
+        // call back into us via `republish(scheme:)` on every real-time flip.
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(handleAppearanceMayHaveChanged),
+            name: UIApplication.didBecomeActiveNotification,
+            object: nil
+        )
+
+        // Seed on the next runloop tick — the LynxView's window may not be
+        // attached yet at construction time, so reading `traitCollection`
+        // immediately can yield the unspecified style.
+        DispatchQueue.main.async { [weak self] in
+            self?.publish()
+        }
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    @objc private func handleAppearanceMayHaveChanged() {
+        publish()
+    }
+
+    /// Force a republish. Called from the seed tick, the app-foreground
+    /// observer, and (optionally) from a host-side trait-collection observer
+    /// that calls into `republish(scheme:)` when the real-time flip happens.
+    @discardableResult
+    @objc func publish() -> Bool {
+        guard let view = lynxView else { return false }
+        let style = view.traitCollection.userInterfaceStyle
+        let scheme = style == .dark ? "dark" : "light"
+        return republish(scheme: scheme)
+    }
+
+    @discardableResult
+    func republish(scheme: String) -> Bool {
+        guard let view = lynxView else { return false }
+        if scheme == lastScheme { return false }
+        lastScheme = scheme
+
+        let map: [String: Any] = ["colorScheme": scheme]
+
+        // Channel 1: __globalProps — sync MT read at first paint.
+        view.updateGlobalProps(with: ["appearance": map])
+
+        // Channel 2: appearanceChanged event — live update for the BG-side
+        // <AppearanceProvider> listener. First param is the map itself;
+        // GlobalEventEmitter delivers it as the listener's first argument.
+        view.sendGlobalEvent("appearanceChanged", withParams: [map])
+        return true
+    }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@sigx/lynx-appearance",
+  "version": "0.4.1",
+  "description": "System appearance (color scheme observation + status/navigation bar tint setters) for sigx-lynx",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./signalx-module.json": "./signalx-module.json"
+  },
+  "files": [
+    "src",
+    "dist",
+    "ios",
+    "android",
+    "signalx-module.json"
+  ],
+  "keywords": [
+    "sigx",
+    "lynx",
+    "appearance",
+    "color-scheme",
+    "dark-mode",
+    "status-bar"
+  ],
+  "author": "Andreas Ekdahl",
+  "license": "MIT",
+  "dependencies": {
+    "@sigx/reactivity": "^0.4.8",
+    "@sigx/lynx": "^0.4.1",
+    "@sigx/lynx-core": "^0.4.1"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260521.1",
+    "typescript": "^6.0.3",
+    "@sigx/lynx-plugin": "^0.4.1",
+    "@sigx/lynx-testing": "^0.4.1",
+    "@sigx/lynx-runtime-main": "^0.4.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/signalxjs/lynx.git",
+    "directory": "packages/lynx-appearance"
+  },
+  "homepage": "https://github.com/signalxjs/lynx/tree/main/packages/lynx-appearance",
+  "bugs": {
+    "url": "https://github.com/signalxjs/lynx/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node ../../scripts/clean.mjs dist && tsgo",
+    "dev": "tsgo --watch",
+    "clean": "node ../../scripts/clean.mjs dist .turbo"
+  }
+}

package/signalx-module.json

@@ -0,0 +1,22 @@
+{
+    "name": "Appearance",
+    "package": "@sigx/lynx-appearance",
+    "description": "System color-scheme observer + status-bar / navigation-bar tint setters",
+    "platforms": ["android", "ios"],
+    "ios": {
+        "moduleClass": "AppearanceModule",
+        "publisherClass": "AppearancePublisher",
+        "sourceDir": "ios",
+        "methods": [
+            "setStatusBarStyle",
+            "setStatusBarBackgroundColor",
+            "setNavigationBarStyle",
+            "getColorScheme"
+        ]
+    },
+    "android": {
+        "moduleClass": "com.sigx.appearance.AppearanceModule",
+        "publisherClass": "com.sigx.appearance.AppearancePublisher",
+        "sourceDir": "android"
+    }
+}

package/src/globals.ts

@@ -0,0 +1,40 @@
+import type { ColorScheme } from './types.js';
+
+/**
+ * Key under `lynx.__globalProps` where the native publisher writes the
+ * appearance map. Single string shared by iOS / Android publishers, the JS
+ * reader, and tests.
+ */
+export const GLOBAL_PROPS_KEY = 'appearance';
+
+export interface RawAppearanceProps {
+  colorScheme?: ColorScheme;
+}
+
+interface LynxGlobalLike {
+  __globalProps?: { [k: string]: unknown };
+}
+
+// Closure-injected identifier from
+// `@lynx-js/runtime-wrapper-webpack-plugin`'s `__init_card_bundle__` wrapper;
+// declared locally so the package doesn't need to depend on lynx-runtime-internal
+// just for the ambient (same pattern as lynx-safe-area).
+declare const lynx: unknown | undefined;
+
+/**
+ * Synchronously read the current system color scheme from
+ * `lynx.__globalProps`. Returns `null` when the publisher hasn't populated
+ * yet (early cold start) or when running outside a Lynx host (web preview,
+ * SSR, tests). Callers should treat `null` as "unknown — fall back to your
+ * default theme".
+ *
+ * Safe on both BG and MT threads — `__globalProps` is mirrored across both.
+ */
+export function readGlobalColorScheme(): ColorScheme | null {
+  const lynxObj: LynxGlobalLike | undefined = typeof lynx !== 'undefined'
+    ? (lynx as unknown as LynxGlobalLike)
+    : undefined;
+  const raw = lynxObj?.__globalProps?.[GLOBAL_PROPS_KEY] as RawAppearanceProps | undefined;
+  if (!raw || typeof raw !== 'object') return null;
+  return raw.colorScheme === 'dark' ? 'dark' : raw.colorScheme === 'light' ? 'light' : null;
+}

package/src/hooks.ts

@@ -0,0 +1,46 @@
+import { signal, type Computed, type PrimitiveSignal } from '@sigx/reactivity';
+import { useAppearanceContext } from './injectable.js';
+import { readGlobalColorScheme } from './globals.js';
+import type { ColorScheme } from './types.js';
+
+type ColorSchemeRead = PrimitiveSignal<ColorScheme> | Computed<ColorScheme>;
+
+/**
+ * BG-side reactive read of the current system color scheme. Returns the
+ * live signal — components calling this re-render when the user flips dark
+ * mode in system settings.
+ *
+ * If no `<AppearanceProvider>` is in scope, returns a fallback signal seeded
+ * from `lynx.__globalProps` once at first call (still gives the correct
+ * value on cold start; just doesn't update live). This lets ThemeProvider
+ * use the hook even when its consumer hasn't mounted `<AppearanceProvider>`.
+ */
+export function useSystemColorScheme(): ColorSchemeRead {
+  const ctx = useAppearanceContext();
+  if (ctx) return ctx.colorScheme;
+  return fallbackSignal();
+}
+
+/**
+ * MT-thread synchronous read of the current system color scheme. For use
+ * inside `'main thread'`-marked worklet bodies. Reads `lynx.__globalProps`
+ * directly — no subscription, callers re-evaluate per worklet invocation.
+ *
+ * Returns `'light'` when the publisher hasn't populated yet (cold start before
+ * first publish, or non-Lynx hosts).
+ */
+export function useSystemColorSchemeMT(): ColorScheme {
+  return readGlobalColorScheme() ?? 'light';
+}
+
+let _fallback: PrimitiveSignal<ColorScheme> | undefined;
+function fallbackSignal(): PrimitiveSignal<ColorScheme> {
+  if (!_fallback) {
+    _fallback = signal<ColorScheme>(readGlobalColorScheme() ?? 'light');
+  }
+  return _fallback;
+}
+
+// Re-export a typed PrimitiveSignal/Computed pair so consumers can write
+// `useSystemColorScheme().value` without importing from @sigx/reactivity.
+export type { PrimitiveSignal, Computed } from '@sigx/reactivity';

package/src/index.ts

@@ -0,0 +1,33 @@
+// Public API for @sigx/lynx-appearance.
+
+export { AppearanceProvider, APPEARANCE_EVENT } from './provider.js';
+export type { AppearanceProviderProps } from './provider.js';
+
+export { useAppearanceContext } from './injectable.js';
+export type { AppearanceContextValue } from './injectable.js';
+
+export {
+  useSystemColorScheme,
+  useSystemColorSchemeMT,
+} from './hooks.js';
+
+export {
+  setStatusBarStyle,
+  setStatusBarBackgroundColor,
+  setNavigationBarStyle,
+  setSystemBarsStyle,
+  isAvailable,
+} from './setters.js';
+
+export {
+  readGlobalColorScheme,
+  GLOBAL_PROPS_KEY,
+} from './globals.js';
+export type { RawAppearanceProps } from './globals.js';
+
+export type {
+  ColorScheme,
+  SystemBarStyle,
+  SystemBarsStyleInput,
+  SetterResult,
+} from './types.js';

package/src/injectable.ts

@@ -0,0 +1,20 @@
+import { defineInjectable } from '@sigx/lynx';
+import type { PrimitiveSignal } from '@sigx/reactivity';
+import type { ColorScheme } from './types.js';
+
+/** DI shape exposed by `<AppearanceProvider>`. */
+export interface AppearanceContextValue {
+  /** BG-side reactive color scheme. Re-renders consumers on system flip. */
+  readonly colorScheme: PrimitiveSignal<ColorScheme>;
+}
+
+/**
+ * The DI handle for the appearance context.
+ *
+ * Factory returns `null` so consumers outside a provider get a clear signal
+ * (vs. a phantom `'light'` signal that silently never updates). Hooks in
+ * `./hooks.ts` wrap this with the null-check + fallback signal.
+ */
+export const useAppearanceContext = defineInjectable<AppearanceContextValue | null>(
+  () => null,
+);

package/src/provider.tsx

@@ -0,0 +1,89 @@
+import {
+  component,
+  defineProvide,
+  signal,
+  onMounted,
+  onUnmounted,
+  type Define,
+} from '@sigx/lynx';
+import { useAppearanceContext, type AppearanceContextValue } from './injectable.js';
+import { readGlobalColorScheme } from './globals.js';
+import type { ColorScheme } from './types.js';
+
+/**
+ * Event name fired by the native publisher (iOS `AppearancePublisher.swift`,
+ * Android `AppearancePublisher.kt`) via `GlobalEventEmitter` every time the
+ * host's system color scheme flips. Payload mirrors the same map stored under
+ * `lynx.__globalProps.appearance`.
+ *
+ * Kept as a constant so iOS/Android publishers and the JS listener agree on
+ * a single string.
+ */
+export const APPEARANCE_EVENT = 'appearanceChanged';
+
+interface GlobalEventEmitterLike {
+  addListener: (name: string, fn: (...a: unknown[]) => void) => void;
+  removeListener: (name: string, fn: (...a: unknown[]) => void) => void;
+}
+
+interface LynxLike {
+  getJSModule?: (name: string) => GlobalEventEmitterLike | undefined;
+}
+
+declare const lynx: unknown | undefined;
+
+export type AppearanceProviderProps =
+  & Define.Prop<'class', string, false>
+  & Define.Prop<'style', Record<string, string | number>, false>
+  & Define.Slot<'default'>;
+
+/**
+ * Mount near the root of an app (above any consumer of `useSystemColorScheme`).
+ * Cheap — just one BG signal + one GlobalEventEmitter subscription. The
+ * native publisher writes `lynx.__globalProps.appearance` before MT first
+ * paint, so the initial value is correct on cold start with no flash.
+ *
+ * On platforms where the publisher isn't wired (web preview, tests),
+ * `readGlobalColorScheme()` returns `null` and we seed `'light'` as a safe
+ * default. Consumers can detect the unwired case via the live-update
+ * subscription never firing.
+ */
+export const AppearanceProvider = component<AppearanceProviderProps>(({ props, slots }) => {
+  const initial: ColorScheme = readGlobalColorScheme() ?? 'light';
+  const colorScheme = signal<ColorScheme>(initial);
+
+  const ctx: AppearanceContextValue = { colorScheme };
+  defineProvide(useAppearanceContext, () => ctx);
+
+  let listener: ((...a: unknown[]) => void) | undefined;
+  let emitter: GlobalEventEmitterLike | undefined;
+
+  onMounted(() => {
+    const lynxObj: LynxLike | undefined = typeof lynx !== 'undefined'
+      ? (lynx as unknown as LynxLike)
+      : undefined;
+    emitter = lynxObj?.getJSModule?.('GlobalEventEmitter');
+    if (!emitter) return;
+    listener = (raw: unknown) => {
+      const next = normaliseScheme(raw);
+      if (next && next !== colorScheme.value) colorScheme.value = next;
+    };
+    emitter.addListener(APPEARANCE_EVENT, listener);
+  });
+
+  onUnmounted(() => {
+    if (emitter && listener) emitter.removeListener(APPEARANCE_EVENT, listener);
+  });
+
+  return () => (
+    <view class={props.class} style={props.style}>
+      {slots.default?.()}
+    </view>
+  );
+});
+
+function normaliseScheme(raw: unknown): ColorScheme | null {
+  if (!raw || typeof raw !== 'object') return null;
+  const v = (raw as Record<string, unknown>)['colorScheme'];
+  return v === 'dark' ? 'dark' : v === 'light' ? 'light' : null;
+}