@symbiote-native/system-ui 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,138 @@
+# @symbiote-native/system-ui
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-system-ui`](https://github.com/expo/expo/tree/main/packages/expo-system-ui)
+— setting and reading the root view's background color — usable from **every** adapter,
+React, Vue, and Angular, not just React. Like
+[`@symbiote-native/device`](../device) and [`@symbiote-native/local-auth`](../local-auth) and
+unlike this repo's stateful Expo wrapper ([`@symbiote-native/sensors`](../sensors), an
+`EventEmitter` + live-subscription surface), both exports here are one-shot async calls with no
+per-instance state, so there is no hook/composable/service to wrap — the React, Vue, and
+Angular entry points are plain re-exports of the same `core`.
+
+## Install
+
+```bash
+npm install @symbiote-native/system-ui
+```
+
+`expo-system-ui` and `expo-modules-core` come along as regular dependencies, pinned to exact
+versions — never install either yourself, and never add the `expo` meta-package to your project
+(it bundles its own Metro/Babel pipeline, which conflicts with this project's own).
+
+## Required one-time step: native autolinking wiring
+
+Unlike a plain RN native module, `expo-system-ui`'s native code is discovered by
+`expo-modules-autolinking`, not RN's own `react-native.config.cjs` mechanism — this needs wiring
+into the native host app **once**, covering this package and every other `expo-modules-core`
+package with zero further changes:
+
+| Platform | Touches |
+|---|---|
+| iOS | `ios/Podfile` — add `use_expo_modules!` |
+| iOS | `AppDelegate.swift` — Expo's runtime-bootstrap hook |
+| Android | `settings.gradle` / `app/build.gradle` — resolve and include the Expo Gradle projects |
+| Android | `MainApplication.kt` — Expo's bootstrap hook, plus a hand-written native-module name map (there's no `expo` meta-package here to auto-generate one) |
+
+Full mechanics live in the `symbiote-expo-native-module` project skill. Reference
+implementation: `examples/expo-react/ios/Podfile` and
+`examples/expo-react/android/app/src/main/java/com/canaryexpo/MainApplication.kt`.
+
+`expo-system-ui` needs no runtime permission on either platform — it only sets/reads a stored
+background color, nothing gated by a permission prompt.
+
+## Shape
+
+```
+src/core/     setBackgroundColorAsync / getBackgroundColorAsync. native-module.ts resolves the
+              native module via expo-modules-core's requireNativeModule.
+src/react/    @symbiote-native/system-ui/react   — export * from '../core'
+src/vue/      @symbiote-native/system-ui/vue     — export * from '../core'
+src/angular/  @symbiote-native/system-ui/angular — export * from '../core'
+```
+
+No per-adapter lifecycle wrapper exists because there's nothing to subscribe to or clean up —
+each adapter entry is a single-file re-export.
+
+## Use it
+
+```tsx
+// React
+import { setBackgroundColorAsync } from '@symbiote-native/system-ui/react';
+
+setBackgroundColorAsync('black');
+```
+
+```vue
+<!-- Vue -->
+<script setup lang="ts">
+import { onMounted } from 'vue';
+import { setBackgroundColorAsync } from '@symbiote-native/system-ui/vue';
+
+onMounted(() => {
+  void setBackgroundColorAsync('black');
+});
+</script>
+```
+
+```ts
+// Angular
+import { Component } from '@angular/core';
+import { setBackgroundColorAsync } from '@symbiote-native/system-ui/angular';
+
+@Component({ standalone: true, template: `` })
+export class RootComponent {
+  constructor() {
+    void setBackgroundColorAsync('black');
+  }
+}
+```
+
+There's no per-instance service to `inject()` in the Angular case — both functions are plain
+exports off the core package, called straight in the constructor or wherever the app's root is
+set up. These snippets are not yet demoed in a real canary screen — no `SystemUiScreen.*` exists
+yet in `examples/expo-*` — so treat them as realistic reference code, not a trimmed-down copy of
+a running demo.
+
+## API
+
+Two one-shot async functions, no event stream, no per-instance state — so the React/Vue/Angular
+entry points above are plain re-exports of `core` with nothing adapter-specific to add.
+
+```ts
+setBackgroundColorAsync(color: ColorValue | null): Promise<void>
+getBackgroundColorAsync(): Promise<ColorValue | null>
+```
+
+```ts
+import { getBackgroundColorAsync, setBackgroundColorAsync } from '@symbiote-native/system-ui';
+// or the framework-scoped entry points — identical surface, re-exported verbatim:
+import { setBackgroundColorAsync } from '@symbiote-native/system-ui/react';
+import { setBackgroundColorAsync } from '@symbiote-native/system-ui/vue';
+import { setBackgroundColorAsync } from '@symbiote-native/system-ui/angular';
+```
+
+## Notes
+
+- **`setBackgroundColorAsync(null)` clears the override** rather than setting an actual color —
+  it's passed straight through to the native module without running `processColor`.
+- **On web, the raw `ColorValue` is passed through untouched** instead of being run through RN's
+  `processColor` — matching upstream, since `processColor` is a native-color-parsing step that
+  doesn't apply on that platform.
+- **On iOS/Android, a non-null color is run through RN's own `processColor` before reaching the
+  native module** — the same conversion RN's style pipeline uses internally.
+
+## Test it
+
+No Fabric/Descriptor angle at all — both exports here are one-shot async calls, never a view or
+per-instance state. Tests inject a fake native-module object in place of the real
+`requireNativeModule` resolution (`src/core/system-ui.test.ts`, `vitest`) — no `installFabric()`,
+no ViewConfig. Native rendering itself is verified on-device (see the parent
+[README](../../README.md) for the project's testing model).
+
+Native autolinking wiring for `expo-modules-core` packages is already done in the four Expo
+canary apps (`examples/expo-react`, `examples/expo-vue-sfc`, `examples/expo-vue-tsx`,
+`examples/expo-angular`) via `@symbiote-native/local-auth`/`@symbiote-native/sensors` — this
+package reuses that same wiring with zero further app-side changes, since
+`expo-modules-autolinking` discovers any `expo-modules-core` package already present in
+`node_modules`. A dedicated `SystemUiScreen` demo has not been wired into those canaries yet.

package/build/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build/angular/index.js

@@ -0,0 +1,4 @@
+// @symbiote-native/system-ui/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';

package/build/core/index.d.ts

@@ -0,0 +1 @@
+export { getBackgroundColorAsync, setBackgroundColorAsync } from './system-ui';

package/build/core/index.js

@@ -0,0 +1 @@
+export { getBackgroundColorAsync, setBackgroundColorAsync } from './system-ui';

package/build/core/native-module.d.ts

@@ -0,0 +1,6 @@
+import type { ColorValue, ProcessedColorValue } from 'react-native';
+export type INativeSystemUIModule = {
+    setBackgroundColorAsync(color: ColorValue | ProcessedColorValue | null | undefined): Promise<void>;
+    getBackgroundColorAsync(): Promise<ColorValue | null>;
+};
+export declare const expoSystemUI: INativeSystemUIModule;

package/build/core/native-module.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_SYSTEM_UI_MODULE_NAME = 'ExpoSystemUI';
+export const expoSystemUI = requireNativeModule(EXPO_SYSTEM_UI_MODULE_NAME);

package/build/core/system-ui.d.ts

@@ -0,0 +1,22 @@
+import type { ColorValue } from 'react-native';
+/**
+ * Changes the root view background color. Call this outside of your component tree, e.g. in
+ * the root file, since it affects the whole app.
+ * @example
+ * ```ts
+ * setBackgroundColorAsync("black");
+ * ```
+ * @param color Any valid [CSS 3 (SVG) color](http://www.w3.org/TR/css3-color/#svg-color), or
+ * `null` to clear the override.
+ */
+export declare function setBackgroundColorAsync(color: ColorValue | null): Promise<void>;
+/**
+ * Gets the root view background color.
+ * @example
+ * ```ts
+ * const color = await getBackgroundColorAsync();
+ * ```
+ * @returns Current root view background color in hex format. `null` if the background color is
+ * not set.
+ */
+export declare function getBackgroundColorAsync(): Promise<ColorValue | null>;

package/build/core/system-ui.js

@@ -0,0 +1,33 @@
+import { Platform, processColor } from 'react-native';
+import { expoSystemUI } from './native-module';
+/**
+ * Changes the root view background color. Call this outside of your component tree, e.g. in
+ * the root file, since it affects the whole app.
+ * @example
+ * ```ts
+ * setBackgroundColorAsync("black");
+ * ```
+ * @param color Any valid [CSS 3 (SVG) color](http://www.w3.org/TR/css3-color/#svg-color), or
+ * `null` to clear the override.
+ */
+export async function setBackgroundColorAsync(color) {
+    if (color == null) {
+        return await expoSystemUI.setBackgroundColorAsync(null);
+    }
+    else {
+        const colorNumber = Platform.OS === 'web' ? color : processColor(color);
+        return await expoSystemUI.setBackgroundColorAsync(colorNumber);
+    }
+}
+/**
+ * Gets the root view background color.
+ * @example
+ * ```ts
+ * const color = await getBackgroundColorAsync();
+ * ```
+ * @returns Current root view background color in hex format. `null` if the background color is
+ * not set.
+ */
+export async function getBackgroundColorAsync() {
+    return await expoSystemUI.getBackgroundColorAsync();
+}

package/build/react/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build/react/index.js

@@ -0,0 +1,6 @@
+// @symbiote-native/system-ui/react: the React entry over the framework-agnostic core. Both
+// exports are plain async functions with no per-instance state and no event stream (unlike
+// @symbiote-native/sensors) — there is nothing for a hook to wrap, so this is a plain
+// re-export, mirroring how @symbiote-native/device's React entry passes its own free
+// functions through untouched.
+export * from '../core';

package/build/vue/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build/vue/index.js

@@ -0,0 +1,4 @@
+// @symbiote-native/system-ui/vue: the Vue entry over the framework-agnostic core. Same
+// reasoning as the React entry — no per-instance state or event stream to wire onto Vue's
+// reactivity, so this is a plain re-export.
+export * from '../core';

package/build-ngc/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build-ngc/angular/index.js

@@ -0,0 +1,5 @@
+// @symbiote-native/system-ui/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';
+//# sourceMappingURL=index.js.map

package/build-ngc/angular/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/angular/index.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAC1F,+FAA+F;AAC/F,yCAAyC;AACzC,cAAc,SAAS,CAAC"}

package/build-ngc/core/index.d.ts

@@ -0,0 +1 @@
+export { getBackgroundColorAsync, setBackgroundColorAsync } from './system-ui';

package/build-ngc/core/index.js

@@ -0,0 +1,2 @@
+export { getBackgroundColorAsync, setBackgroundColorAsync } from './system-ui';
+//# sourceMappingURL=index.js.map

package/build-ngc/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAC"}

package/build-ngc/core/native-module.d.ts

@@ -0,0 +1,6 @@
+import type { ColorValue, ProcessedColorValue } from 'react-native';
+export type INativeSystemUIModule = {
+    setBackgroundColorAsync(color: ColorValue | ProcessedColorValue | null | undefined): Promise<void>;
+    getBackgroundColorAsync(): Promise<ColorValue | null>;
+};
+export declare const expoSystemUI: INativeSystemUIModule;

package/build-ngc/core/native-module.js

@@ -0,0 +1,4 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_SYSTEM_UI_MODULE_NAME = 'ExpoSystemUI';
+export const expoSystemUI = requireNativeModule(EXPO_SYSTEM_UI_MODULE_NAME);
+//# sourceMappingURL=native-module.js.map

package/build-ngc/core/native-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-module.js","sourceRoot":"","sources":["../../src/core/native-module.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,0BAA0B,GAAG,cAAc,CAAC;AAYlD,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAwB,0BAA0B,CAAC,CAAC"}

package/build-ngc/core/system-ui.d.ts

@@ -0,0 +1,22 @@
+import type { ColorValue } from 'react-native';
+/**
+ * Changes the root view background color. Call this outside of your component tree, e.g. in
+ * the root file, since it affects the whole app.
+ * @example
+ * ```ts
+ * setBackgroundColorAsync("black");
+ * ```
+ * @param color Any valid [CSS 3 (SVG) color](http://www.w3.org/TR/css3-color/#svg-color), or
+ * `null` to clear the override.
+ */
+export declare function setBackgroundColorAsync(color: ColorValue | null): Promise<void>;
+/**
+ * Gets the root view background color.
+ * @example
+ * ```ts
+ * const color = await getBackgroundColorAsync();
+ * ```
+ * @returns Current root view background color in hex format. `null` if the background color is
+ * not set.
+ */
+export declare function getBackgroundColorAsync(): Promise<ColorValue | null>;

package/build-ngc/core/system-ui.js

@@ -0,0 +1,34 @@
+import { Platform, processColor } from 'react-native';
+import { expoSystemUI } from './native-module';
+/**
+ * Changes the root view background color. Call this outside of your component tree, e.g. in
+ * the root file, since it affects the whole app.
+ * @example
+ * ```ts
+ * setBackgroundColorAsync("black");
+ * ```
+ * @param color Any valid [CSS 3 (SVG) color](http://www.w3.org/TR/css3-color/#svg-color), or
+ * `null` to clear the override.
+ */
+export async function setBackgroundColorAsync(color) {
+    if (color == null) {
+        return await expoSystemUI.setBackgroundColorAsync(null);
+    }
+    else {
+        const colorNumber = Platform.OS === 'web' ? color : processColor(color);
+        return await expoSystemUI.setBackgroundColorAsync(colorNumber);
+    }
+}
+/**
+ * Gets the root view background color.
+ * @example
+ * ```ts
+ * const color = await getBackgroundColorAsync();
+ * ```
+ * @returns Current root view background color in hex format. `null` if the background color is
+ * not set.
+ */
+export async function getBackgroundColorAsync() {
+    return await expoSystemUI.getBackgroundColorAsync();
+}
+//# sourceMappingURL=system-ui.js.map

package/build-ngc/core/system-ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-ui.js","sourceRoot":"","sources":["../../src/core/system-ui.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE/C;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAAC,KAAwB;IACpE,IAAI,KAAK,IAAI,IAAI,EAAE,CAAC;QAClB,OAAO,MAAM,YAAY,CAAC,uBAAuB,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;SAAM,CAAC;QACN,MAAM,WAAW,GAAG,QAAQ,CAAC,EAAE,KAAK,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC;QACxE,OAAO,MAAM,YAAY,CAAC,uBAAuB,CAAC,WAAW,CAAC,CAAC;IACjE,CAAC;AACH,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB;IAC3C,OAAO,MAAM,YAAY,CAAC,uBAAuB,EAAE,CAAC;AACtD,CAAC"}

package/native-link.json

@@ -0,0 +1,12 @@
+{
+  "android": {
+    "gradleProjectName": "expo-system-ui",
+    "modules": [
+      {
+        "importPath": "expo.modules.systemui.SystemUIModule",
+        "className": "SystemUIModule",
+        "nativeName": "ExpoSystemUI"
+      }
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "@symbiote-native/system-ui",
+  "version": "0.0.1",
+  "description": "expo-system-ui wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, and Angular adapters. Sets and reads the root view's background color.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/system-ui"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/system-ui#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/vue/index.d.ts",
+      "default": "./build/vue/index.js"
+    },
+    "./react": {
+      "types": "./build/react/index.d.ts",
+      "default": "./build/react/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-system-ui": "57.0.2",
+    "expo-modules-core": "57.0.5"
+  },
+  "peerDependencies": {
+    "@symbiote-native/engine": ">=0.1.7",
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/vue": "0.3.8"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "^22",
+    "@angular/compiler-cli": "^22",
+    "@angular/core": "^22",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "typescript": "~6.0.0",
+    "@symbiote-native/angular": "0.6.1",
+    "@symbiote-native/react": "0.2.8",
+    "@symbiote-native/vue": "0.3.8",
+    "@symbiote-native/test-utils": "0.1.6",
+    "@symbiote-native/engine": "0.1.7"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/system-ui/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';

package/src/core/index.ts

@@ -0,0 +1 @@
+export { getBackgroundColorAsync, setBackgroundColorAsync } from './system-ui';

package/src/core/native-module.ts

@@ -0,0 +1,16 @@
+import type { ColorValue, ProcessedColorValue } from 'react-native';
+import { requireNativeModule } from 'expo-modules-core';
+
+const EXPO_SYSTEM_UI_MODULE_NAME = 'ExpoSystemUI';
+
+// The color argument accepts everything system-ui.ts can pass it: the raw ColorValue on web,
+// or RN's own processColor() result (a number, an OpaqueColorValue, or undefined) on
+// iOS/Android.
+export type INativeSystemUIModule = {
+  setBackgroundColorAsync(
+    color: ColorValue | ProcessedColorValue | null | undefined,
+  ): Promise<void>;
+  getBackgroundColorAsync(): Promise<ColorValue | null>;
+};
+
+export const expoSystemUI = requireNativeModule<INativeSystemUIModule>(EXPO_SYSTEM_UI_MODULE_NAME);

package/src/core/system-ui.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+const FAKE_NATIVE_SYSTEM_UI = {
+  setBackgroundColorAsync: vi.fn(async () => undefined),
+  getBackgroundColorAsync: vi.fn(async () => '#000000'),
+};
+
+// The real ExpoSystemUI native module only exists on device — resolving it via
+// requireNativeModule() at import time would throw in this headless test run, so the
+// module-lookup file is faked in place of expo-modules-core's runtime resolution, the same
+// pattern packages/device/src/core/device.test.ts uses.
+vi.mock('./native-module', () => ({
+  expoSystemUI: FAKE_NATIVE_SYSTEM_UI,
+}));
+
+// react-native's real Platform module reads native constants that don't exist in this headless
+// run; processColor is stubbed to a simple, observable transform so the two branches
+// (color == null / Platform.OS === 'web' / native processColor) are each independently provable.
+vi.mock('react-native', () => ({
+  Platform: { OS: 'ios' },
+  processColor: vi.fn((color: string) => `processed(${color})`),
+}));
+
+const { getBackgroundColorAsync, setBackgroundColorAsync } = await import('./system-ui');
+const { Platform, processColor } = await import('react-native');
+
+afterEach(() => {
+  vi.clearAllMocks();
+  Platform.OS = 'ios';
+});
+
+describe('setBackgroundColorAsync', () => {
+  it('passes null straight through when color is null', async () => {
+    await setBackgroundColorAsync(null);
+
+    expect(processColor).not.toHaveBeenCalled();
+    expect(FAKE_NATIVE_SYSTEM_UI.setBackgroundColorAsync).toHaveBeenCalledWith(null);
+  });
+
+  it('runs a non-null color through processColor on native platforms', async () => {
+    await setBackgroundColorAsync('tomato');
+
+    expect(processColor).toHaveBeenCalledWith('tomato');
+    expect(FAKE_NATIVE_SYSTEM_UI.setBackgroundColorAsync).toHaveBeenCalledWith('processed(tomato)');
+  });
+
+  it('passes the raw color straight through on web, skipping processColor', async () => {
+    Platform.OS = 'web';
+
+    await setBackgroundColorAsync('tomato');
+
+    expect(processColor).not.toHaveBeenCalled();
+    expect(FAKE_NATIVE_SYSTEM_UI.setBackgroundColorAsync).toHaveBeenCalledWith('tomato');
+  });
+});
+
+describe('getBackgroundColorAsync', () => {
+  it('delegates to the native module', async () => {
+    await expect(getBackgroundColorAsync()).resolves.toBe('#000000');
+    expect(FAKE_NATIVE_SYSTEM_UI.getBackgroundColorAsync).toHaveBeenCalled();
+  });
+});

package/src/core/system-ui.ts

@@ -0,0 +1,40 @@
+// Hand-ported from .vendors/expo/packages/expo-system-ui/src/SystemUI.ts (sdk-57), verbatim
+// apart from resolving the native module through native-module.ts (this repo's convention,
+// matching local-auth/device/cellular) instead of a bare `import ExpoSystemUI from
+// './ExpoSystemUI'`.
+import type { ColorValue } from 'react-native';
+import { Platform, processColor } from 'react-native';
+
+import { expoSystemUI } from './native-module';
+
+/**
+ * Changes the root view background color. Call this outside of your component tree, e.g. in
+ * the root file, since it affects the whole app.
+ * @example
+ * ```ts
+ * setBackgroundColorAsync("black");
+ * ```
+ * @param color Any valid [CSS 3 (SVG) color](http://www.w3.org/TR/css3-color/#svg-color), or
+ * `null` to clear the override.
+ */
+export async function setBackgroundColorAsync(color: ColorValue | null): Promise<void> {
+  if (color == null) {
+    return await expoSystemUI.setBackgroundColorAsync(null);
+  } else {
+    const colorNumber = Platform.OS === 'web' ? color : processColor(color);
+    return await expoSystemUI.setBackgroundColorAsync(colorNumber);
+  }
+}
+
+/**
+ * Gets the root view background color.
+ * @example
+ * ```ts
+ * const color = await getBackgroundColorAsync();
+ * ```
+ * @returns Current root view background color in hex format. `null` if the background color is
+ * not set.
+ */
+export async function getBackgroundColorAsync(): Promise<ColorValue | null> {
+  return await expoSystemUI.getBackgroundColorAsync();
+}

package/src/react/index.ts

@@ -0,0 +1,6 @@
+// @symbiote-native/system-ui/react: the React entry over the framework-agnostic core. Both
+// exports are plain async functions with no per-instance state and no event stream (unlike
+// @symbiote-native/sensors) — there is nothing for a hook to wrap, so this is a plain
+// re-export, mirroring how @symbiote-native/device's React entry passes its own free
+// functions through untouched.
+export * from '../core';

package/src/vue/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/system-ui/vue: the Vue entry over the framework-agnostic core. Same
+// reasoning as the React entry — no per-instance state or event stream to wire onto Vue's
+// reactivity, so this is a plain re-export.
+export * from '../core';