@chipmobilesdk/rn-theme 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,4 +1,76 @@
-# Changelog
+# @chipmobilesdk/rn-theme
+
+## 1.1.0
+
+### Minor Changes
+
+- One diagnostic stream: install a sink with `installSdkSink` from
+  `@chipmobilesdk/rn-core` and it receives what every package observes (events,
+  failures, warnings) as `SdkDiagnostic`s, redacted. Listeners are notified through
+  rn-core, so a listener that throws no longer stops the others nor fails the call that
+  notified, and its error is reported rather than swallowed. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ads: a banner's auto-refresh is a new cycle, so its `loaded` and `impression`
+    events are no longer deduplicated away; the dedupe memory is bounded. A throwing
+    status, consent or placement listener is reported as an `internal_error` event.
+  - rn-i18n: new `onDiagnostic` config receives every diagnostic (`I18nDiagnostic`,
+    with a stable `code`); without it, warnings go to `console.warn` in development
+    builds only. The warn-once memory is bounded.
+  - rn-chart: now depends on rn-core for its diagnostics.
+  - rn-payment: status, entitlement and pending listeners report a throw to the logger
+    instead of swallowing it.
+
+- The package's errors extend `SdkError` from the new `@chipmobilesdk/rn-core`
+  dependency: `isSdkError` recognises them alongside every other package's, and each
+  carries `pkg`, `code` and `retryable`. Names and codes are unchanged. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-ai and rn-camera: `retryable` is the new name of `recoverable`, which stays as a
+    deprecated alias.
+  - rn-auth: `retryable` is true for `network-unavailable`. `redact` also removes URLs,
+    e-mail addresses and UUIDs.
+  - rn-ads: `redact` also removes JWTs and e-mail addresses, and reduces an `AdsError`
+    to its code.
+  - rn-ai: an error message quoted from the gateway is pattern-redacted.
+  - rn-camera: `redact` also removes JWTs, e-mail addresses and UUIDs.
+  - rn-theme: `ThemeConfigError` has `code: 'invalid_config'` and `ThemeContrastError`
+    `code: 'contrast'` (new `ThemeErrorCode` type).
+  - rn-i18n: `I18nConfigError` has `code: 'invalid_config'` and `UnitConversionError`
+    `code: 'unit_conversion'` (new `I18nErrorCode` type).
+
+- Native peers load through `lazyPeer` from `@chipmobilesdk/rn-core`, on first use,
+  and a missing one is each package's own typed error. ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17))
+
+  - rn-auth: creating `auth` no longer loads react-native-app-auth or
+    react-native-keychain; each loads on first use. New entrypoints
+    `@chipmobilesdk/rn-auth/app-auth` and `/keychain`. The default platform comes from
+    rn-core.
+  - rn-camera: a preview whose VisionCamera feed cannot load fails the session with
+    `cameraUnavailable` (new `controller.reportSurfaceUnavailable()`), instead of
+    showing black with no error. A missing VisionCamera module is `cameraUnavailable`.
+  - rn-notification: `createMmkvStore` reports a fallback to memory as
+    `STATE_STORE_DEGRADED` (to the SDK sinks and a new `onDegraded` option) and
+    exposes `durable`.
+  - rn-payment: an iOS app validates its catalog against the iOS product ids; the
+    default platform used to be Android everywhere. A missing react-native-iap is
+    `PAYMENT_UNAVAILABLE`.
+  - rn-theme: `buildThemes` runs without React Native (new `hairlineWidth` option) and
+    importing the package no longer loads Unistyles; `applyThemeMode` loads it on
+    first use.
+  - rn-ads, rn-local-db: the same loading, with the same error codes as before.
+
+### Patch Changes
+
+- Updated dependencies ([#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17), [#17](https://github.com/operationd8979/chip-mobile-sdk/pull/17)):
+  - @chipmobilesdk/rn-core@0.1.0
+
+## 1.0.1
+
+### Patch Changes
+
+- Documentation and packaging only; no code change. The README no longer writes a
+  version into its header (the changelog is the one place a version lives), the agent
+  skill no longer carries one (the consuming app's skill sync stamps the installed
+  version), and the changelog goes straight from its title to its releases. ([#15](https://github.com/operationd8979/chip-mobile-sdk/pull/15))
 
 ## 1.0.0 - 2026-10-17
 

package/README.md

@@ -7,7 +7,7 @@ Native apps, configured for `react-native-unistyles` 3.
 > applications; no open-source license is granted. Includes Apache-2.0 code from
 > material-color-utilities — see `NOTICE`.
 
-- **Version**: `1.0.0`
+- **Version**: see [CHANGELOG](CHANGELOG.md)
 - **Entrypoint**: `@chipmobilesdk/rn-theme`
 - **Demo**: `src/screens/ExampleScreen.tsx`
 
@@ -90,6 +90,7 @@ applyThemeMode('dark');   // fixed; survives later OS scheme changes
 
 `applyThemeMode` switches adaptive themes off before setting a manual theme — in the other
 order the next OS change overrides the user's choice. Persisting the preference is the app's.
+Unistyles is loaded the first time a mode is applied, never when the package is imported.
 
 ## Colour System
 
@@ -220,7 +221,10 @@ belong in `extend`.
 
 ## Integrations
 
-- `buildThemes(config)` — the same themes without Unistyles, e.g. for tests or other libraries.
+- `buildThemes(config, options?)` — the same themes without Unistyles, e.g. for tests, other
+  libraries or a token export. It needs no React Native either: pass `platform` and
+  `hairlineWidth`, or they default to the running platform and
+  `StyleSheet.hairlineWidth` (1 where React Native is not loaded).
 - `toNavigationTheme(theme, scheme)` — a React Navigation theme (no navigation dependency).
 
 ## Public Runtime Exports
@@ -244,6 +248,10 @@ Only `@chipmobilesdk/rn-theme` is public. Deep imports (`.../src/...`) are unsup
 
 ## Configuration Validation
 
+Both errors extend `SdkError` from `@chipmobilesdk/rn-core` and carry a `code`
+(`ThemeErrorCode`): `invalid_config` for `ThemeConfigError`, `contrast` for
+`ThemeContrastError`.
+
 Invalid input throws `ThemeConfigError` whose `path` names the field, e.g.
 `overrides.dark.color.error`. Checked: brand and seed colours (opaque, supported format),
 tone colours, typography numbers and font maps, named themes, override keys (must exist),
@@ -291,7 +299,7 @@ spreads and casts into `extend`.
 ## Release Validation
 
 ```bash
-npm run validate:theme
+npm run validate
 ```
 
 ## Semver and Migration

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@chipmobilesdk/rn-theme",
-	"version": "1.0.0",
+	"version": "1.1.0",
 	"private": false,
 	"license": "UNLICENSED",
 	"main": "src/index.ts",
@@ -29,8 +29,11 @@
 	],
 	"sideEffects": false,
 	"scripts": {
-		"typecheck": "tsc -p tsconfig.json --noEmit",
-		"pack:dry-run": "npm pack --dry-run"
+		"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json",
+		"pack:check": "npm pack --dry-run"
+	},
+	"dependencies": {
+		"@chipmobilesdk/rn-core": "^0.1.0"
 	},
 	"peerDependencies": {
 		"react": ">=19",

package/skills/sdk-rn-theme/SKILL.md

@@ -3,7 +3,6 @@ name: sdk-rn-theme
 description: "Theming for @chipmobilesdk/rn-theme: accessible brand palettes, Unistyles config, colour/typography/spacing tokens, tones and byTone variants, layout and text presets, app token extension, dark mode and theme mode. Use when setting up theming, writing or shortening a stylesheet, adding a design token, wiring light/dark, or debugging Unistyles setup, stale styles or type errors."
 metadata:
   package: "@chipmobilesdk/rn-theme"
-  packageVersion: "1.0.0"
 user-invocable: true
 disable-model-invocation: false
 ---
@@ -46,11 +45,12 @@ Unistyles 3. Single source of truth for visual tokens; app tokens join through `
   package) augments `UnistylesThemes` / `UnistylesBreakpoints` from `typeof config`.
 - Merge Unistyles styles with arrays, never object spread of Unistyles entries.
 
-## Public API (v1.0.0)
+## Public API
 
 Runtime: `createUnistylesConfig`, `buildThemes`, `applyThemeMode`, `byTone`, `layout`,
 `presets`, `auditTheme`, `contrastRatio`, `withAlpha`, `toNavigationTheme`,
-`DEFAULT_BREAKPOINTS`, `ThemeConfigError`, `ThemeContrastError`.
+`DEFAULT_BREAKPOINTS`, `ThemeConfigError`, `ThemeContrastError` (both rn-core SDK errors with a
+`ThemeErrorCode`).
 
 Theme groups: `color`, `tone`, `typography`, `font`, `fontWeight`, `spacing`, `radius`,
 `borderWidth`, `size`, `opacity`, `motion`, `shadow`, `zIndex`, `maxFontScale`,

package/src/color/contrast.ts

@@ -107,7 +107,11 @@ function guaranteedPairs(theme: object): ContrastPair[] {
 			const tone = `tone.${name}`;
 			pairs.push(
 				...onBase(`${tone}.fg`),
-				{ foreground: `${tone}.onContainer`, background: `${tone}.container`, target: TEXT_CONTRAST },
+				{
+					foreground: `${tone}.onContainer`,
+					background: `${tone}.container`,
+					target: TEXT_CONTRAST,
+				},
 				{ foreground: `${tone}.onFill`, background: `${tone}.fill`, target: TEXT_CONTRAST },
 				{ foreground: `${tone}.border`, background: 'color.background', target: NON_TEXT_CONTRAST },
 			);
@@ -161,11 +165,7 @@ function channelLuminance(channel: number): number {
 }
 
 function relativeLuminance({ r, g, b }: Rgba): number {
-	return (
-		0.2126 * channelLuminance(r) +
-		0.7152 * channelLuminance(g) +
-		0.0722 * channelLuminance(b)
-	);
+	return 0.2126 * channelLuminance(r) + 0.7152 * channelLuminance(g) + 0.0722 * channelLuminance(b);
 }
 
 function composite(top: Rgba, bottom: Rgba): Rgba {
@@ -190,7 +190,10 @@ export function contrastRatio(foreground: string, background: string, base?: str
 
 	const opaqueBackground = composite(bg, composite(baseColor, WHITE));
 	const opaqueForeground = composite(fg, opaqueBackground);
-	const lighter = Math.max(relativeLuminance(opaqueForeground), relativeLuminance(opaqueBackground));
+	const lighter = Math.max(
+		relativeLuminance(opaqueForeground),
+		relativeLuminance(opaqueBackground),
+	);
 	const darker = Math.min(relativeLuminance(opaqueForeground), relativeLuminance(opaqueBackground));
 
 	return (lighter + LUMINANCE_OFFSET) / (darker + LUMINANCE_OFFSET);

package/src/color/parse.ts

@@ -50,12 +50,11 @@ function parseHex(digits: string): Rgba {
 	const full =
 		digits.length <= 4
 			? digits
-				.split('')
-				.map(digit => digit + digit)
-				.join('')
+					.split('')
+					.map(digit => digit + digit)
+					.join('')
 			: digits;
-	const channel = (index: number) =>
-		parseInt(full.slice(index * 2, index * 2 + 2), 16);
+	const channel = (index: number) => parseInt(full.slice(index * 2, index * 2 + 2), 16);
 
 	return {
 		r: channel(0),

package/src/index.ts

@@ -2,13 +2,11 @@
 export { buildThemes } from './theme/buildThemes';
 export type { BuildThemesOptions } from './theme/buildThemes';
 export { ThemeConfigError, ThemeContrastError } from './theme/errors';
+export type { ThemeErrorCode } from './theme/errors';
 
 // ─── Unistyles ──────────────────────────────────────────────────────────────
 export { createUnistylesConfig } from './unistyles/createUnistylesConfig';
-export type {
-	UnistylesConfig,
-	UnistylesConfigOptions,
-} from './unistyles/createUnistylesConfig';
+export type { UnistylesConfig, UnistylesConfigOptions } from './unistyles/createUnistylesConfig';
 export { applyThemeMode } from './unistyles/themeMode';
 export type { ThemeMode, ThemeModeRuntime } from './unistyles/themeMode';
 export { DEFAULT_BREAKPOINTS } from './tokens/defaults';

package/src/theme/buildThemes.ts

@@ -1,4 +1,6 @@
-import { Platform as ReactNativePlatform } from 'react-native';
+import { createDiagnosticChannel } from '@chipmobilesdk/rn-core';
+
+import { currentPlatform, lazyPeer } from '@chipmobilesdk/rn-core';
 import { buildCategorical } from '../color/categorical';
 import { auditTheme } from '../color/contrast';
 import { buildColorRoles, buildPalettes, buildTones } from '../color/roles';
@@ -32,6 +34,26 @@ import { validateThemeConfig } from './validateThemeConfig';
 export interface BuildThemesOptions {
 	/** Platform whose font resolution applies. Defaults to the running platform. */
 	platform?: Platform;
+	/**
+	 * `borderWidth.hairline`. Defaults to React Native's `StyleSheet.hairlineWidth`,
+	 * or 1 where React Native is not loaded, so `buildThemes` runs on Node (THM-04).
+	 */
+	hairlineWidth?: number;
+}
+
+/** Read only when no `hairlineWidth` is given, so building themes needs no React Native. */
+const reactNative = lazyPeer('react-native', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native') as { StyleSheet?: { hairlineWidth?: number } };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function deviceHairlineWidth(): number {
+	const result = reactNative.get();
+	return (result.ok ? result.module.StyleSheet?.hairlineWidth : undefined) ?? 1;
 }
 
 /** Groups that come straight from tokens (presets and tones are derived after). */
@@ -74,6 +96,7 @@ function buildOne(
 	source: ThemeSource,
 	fonts: ReturnType<typeof buildFonts>,
 	overrides: unknown,
+	hairlineWidth: number,
 ): object {
 	const { name, scheme, config, palettes } = source;
 	const path = `overrides.${name}`;
@@ -86,7 +109,7 @@ function buildOne(
 		fontWeight: buildFontWeight(),
 		spacing: buildSpacing(),
 		radius: buildRadius(),
-		borderWidth: buildBorderWidth(),
+		borderWidth: buildBorderWidth(hairlineWidth),
 		size: buildSize(),
 		opacity: buildOpacity(),
 		motion: buildMotion(),
@@ -129,11 +152,15 @@ function checkContrast(name: string, theme: object, strict: boolean): void {
 		throw new ThemeContrastError(name, failures);
 	}
 
+	channel.emit('contrast', 'warn', { theme: name, failures: failures.length });
 	console.warn(
 		`[rn-theme] Theme "${name}" breaks contrast guarantees after overrides:\n${describeFailures(failures)}`,
 	);
 }
 
+/** Contrast warnings also reach the app's SDK sinks (`installSdkSink`, CORE-08). */
+const channel = createDiagnosticChannel<'contrast'>('rn-theme');
+
 /**
  * Builds every theme from brand config — pure, with no Unistyles dependency
  * (spec AC-9.4). `createUnistylesConfig` wraps this; call it directly to feed
@@ -143,11 +170,16 @@ export function buildThemes<
 	TExt extends object = EmptyExtension,
 	TTone extends string = never,
 	TName extends string = never,
->(config: ThemeConfig<TExt, TTone, TName>, options?: BuildThemesOptions): Themes<TExt, TTone, TName> {
+>(
+	config: ThemeConfig<TExt, TTone, TName>,
+	options?: BuildThemesOptions,
+): Themes<TExt, TTone, TName> {
 	validateThemeConfig(config);
 
 	const loose = config as unknown as ThemeConfig<object, string, string>;
-	const platform = options?.platform ?? (ReactNativePlatform.OS === 'ios' ? 'ios' : 'android');
+	// rn-core's one platform source (CORE-09); off-device, fonts resolve as on Android.
+	const platform = options?.platform ?? (currentPlatform() === 'ios' ? 'ios' : 'android');
+	const hairlineWidth = options?.hairlineWidth ?? deviceHairlineWidth();
 	const fonts = buildFonts(loose.typography, platform);
 	const basePalettes = buildPalettes(loose);
 	const sources: ThemeSource[] = [
@@ -161,14 +193,19 @@ export function buildThemes<
 				tones: { ...loose.tones, ...named.tones } as Record<string, string>,
 			};
 
-			return { name, scheme: named.scheme, config: namedConfig, palettes: buildPalettes(namedConfig) };
+			return {
+				name,
+				scheme: named.scheme,
+				config: namedConfig,
+				palettes: buildPalettes(namedConfig),
+			};
 		}),
 	];
 	const themes: Record<string, object> = {};
 
 	for (const source of sources) {
 		const overrides = (loose.overrides as Record<string, unknown> | undefined)?.[source.name];
-		const theme = buildOne(source, fonts, overrides);
+		const theme = buildOne(source, fonts, overrides, hairlineWidth);
 
 		checkContrast(source.name, theme, loose.strict === true);
 		themes[source.name] = theme;

package/src/theme/errors.ts

@@ -1,23 +1,36 @@
+import { SdkError } from '@chipmobilesdk/rn-core';
+
 import type { ContrastFailure } from '../color/contrast';
 
-/** Invalid configuration or override; `path` names the offending field. */
-export class ThemeConfigError extends Error {
+/**
+ * The package's error codes (THM-09): `invalid_config` for a config or override
+ * the package rejects, `contrast` for a theme that breaks a contrast guarantee.
+ */
+export type ThemeErrorCode = 'invalid_config' | 'contrast';
+
+/**
+ * Invalid configuration or override; `path` names the offending field. An
+ * `SdkError` (`@chipmobilesdk/rn-core`) with `pkg: 'rn-theme'`.
+ */
+export class ThemeConfigError extends SdkError<ThemeErrorCode> {
 	readonly path: string;
 
 	constructor(path: string, message: string) {
-		super(`${path}: ${message}`);
+		super('rn-theme', 'invalid_config', { message: `${path}: ${message}` });
 		this.name = 'ThemeConfigError';
 		this.path = path;
 	}
 }
 
 /** Thrown in `strict` mode when a theme breaks a contrast guarantee. */
-export class ThemeContrastError extends Error {
+export class ThemeContrastError extends SdkError<ThemeErrorCode> {
 	readonly themeName: string;
 	readonly failures: ContrastFailure[];
 
 	constructor(themeName: string, failures: ContrastFailure[]) {
-		super(`Theme "${themeName}" breaks contrast guarantees:\n${describeFailures(failures)}`);
+		super('rn-theme', 'contrast', {
+			message: `Theme "${themeName}" breaks contrast guarantees:\n${describeFailures(failures)}`,
+		});
 		this.name = 'ThemeContrastError';
 		this.themeName = themeName;
 		this.failures = failures;

package/src/theme/overrides.ts

@@ -85,7 +85,12 @@ function mergeEntry(entry: Entry): unknown {
  * keys must exist in `base`, colours must parse, numbers must be finite.
  * Arrays are replaced whole. `base` itself is never mutated.
  */
-export function mergeOverrides<T>(base: T, overrides: unknown, path: string, segments: string[] = []): T {
+export function mergeOverrides<T>(
+	base: T,
+	overrides: unknown,
+	path: string,
+	segments: string[] = [],
+): T {
 	if (overrides == null) {
 		return base;
 	}

package/src/theme/validateThemeConfig.ts

@@ -70,7 +70,10 @@ function validateFontMap(value: unknown, path: string): void {
 
 	for (const [weight, family] of Object.entries(value)) {
 		if (!FONT_WEIGHT_NAMES.includes(weight as FontWeightName)) {
-			throw new ThemeConfigError(`${path}.${weight}`, `is not one of ${FONT_WEIGHT_NAMES.join(', ')}.`);
+			throw new ThemeConfigError(
+				`${path}.${weight}`,
+				`is not one of ${FONT_WEIGHT_NAMES.join(', ')}.`,
+			);
 		}
 		assertNonEmptyString(family, `${path}.${weight}`);
 	}
@@ -114,7 +117,10 @@ function validateNamedThemes(value: unknown): void {
 		const path = `themes.${name}`;
 
 		if (RESERVED_THEME_NAMES.has(name)) {
-			throw new ThemeConfigError(path, 'light and dark are built in; customise them with overrides.');
+			throw new ThemeConfigError(
+				path,
+				'light and dark are built in; customise them with overrides.',
+			);
 		}
 
 		assertObject(theme, path);

package/src/tokens/defaults.ts

@@ -1,4 +1,3 @@
-import { StyleSheet } from 'react-native';
 import { withAlpha } from '../color/parse';
 import type {
 	BorderWidthTokens,
@@ -35,8 +34,9 @@ export function buildRadius(): RadiusTokens {
 	return { none: 0, xs: 2, sm: 4, md: 8, lg: 16, xl: 24, full: 9999 };
 }
 
-export function buildBorderWidth(): BorderWidthTokens {
-	return { hairline: StyleSheet.hairlineWidth, thin: 1, thick: 2 };
+/** `hairline` is the device's thinnest line, resolved by `buildThemes` (THM-04). */
+export function buildBorderWidth(hairline: number): BorderWidthTokens {
+	return { hairline, thin: 1, thick: 2 };
 }
 
 export function buildSize(): SizeTokens {

package/src/tokens/typography.ts

@@ -84,7 +84,9 @@ export function buildFonts(config: TypographyConfig | undefined, platform: Platf
 		// iOS picks weights inside one family, so a partial iOS map only renames
 		// the weights it lists; Android needs a file per weight, hence nearest.
 		const nearest =
-			platform === 'ios' ? (perWeight?.[weight] && weight) : perWeight && nearestWeight(weight, perWeight);
+			platform === 'ios'
+				? perWeight?.[weight] && weight
+				: perWeight && nearestWeight(weight, perWeight);
 
 		if (!perWeight || !nearest) {
 			return { fontFamily: family, fontWeight: FONT_WEIGHTS[weight] };
@@ -117,7 +119,8 @@ export function buildTypography(
 	font: Record<FontWeightName, FontToken>,
 	family: string,
 ): Typography {
-	const scale = ((config?.baseFontSize ?? DEFAULT_BODY_SIZE) / DEFAULT_BODY_SIZE) * (config?.fontScale ?? 1);
+	const scale =
+		((config?.baseFontSize ?? DEFAULT_BODY_SIZE) / DEFAULT_BODY_SIZE) * (config?.fontScale ?? 1);
 	const typography = { fontFamily: family } as Typography;
 
 	for (const role of Object.keys(SCALE) as TypographyRole[]) {

package/src/types/colors.ts

@@ -2,13 +2,7 @@ export type ColorScheme = 'light' | 'dark';
 
 /** Colours whose roles come in sets of four: X, onX, XContainer, onXContainer. */
 export type AccentRoleName =
-	| 'primary'
-	| 'secondary'
-	| 'tertiary'
-	| 'error'
-	| 'success'
-	| 'warning'
-	| 'info';
+	'primary' | 'secondary' | 'tertiary' | 'error' | 'success' | 'warning' | 'info';
 
 export interface ColorRoles {
 	primary: string;
@@ -69,13 +63,7 @@ export interface ColorRoles {
 	disabled: string;
 }
 
-export type StandardToneName =
-	| 'neutral'
-	| 'primary'
-	| 'info'
-	| 'success'
-	| 'warning'
-	| 'error';
+export type StandardToneName = 'neutral' | 'primary' | 'info' | 'success' | 'warning' | 'error';
 
 /** A matched colour set for one tone, for use with `byTone`. */
 export interface ToneColors {

package/src/types/theme.ts

@@ -114,8 +114,10 @@ export interface BaseTheme<TTone extends string = never> {
 
 export type EmptyExtension = Record<never, never>;
 
-export type Theme<TExt extends object = EmptyExtension, TTone extends string = never> = BaseTheme<TTone> &
-	TExt;
+export type Theme<
+	TExt extends object = EmptyExtension,
+	TTone extends string = never,
+> = BaseTheme<TTone> & TExt;
 
 export type ThemeName<TName extends string = never> = 'light' | 'dark' | TName;
 

package/src/types/typography.ts

@@ -32,9 +32,7 @@ export interface TypographyConfig {
 export type TypographyRole = 'display' | 'headline' | 'title' | 'body' | 'label' | 'caption';
 
 export type TypographyStyleName =
-	| TypographyRole
-	| `${TypographyRole}Small`
-	| `${TypographyRole}Large`;
+	TypographyRole | `${TypographyRole}Small` | `${TypographyRole}Large`;
 
 export interface TypographyToken {
 	fontSize: number;

package/src/unistyles/createUnistylesConfig.ts

@@ -21,15 +21,15 @@ export type UnistylesConfigOptions<
 		breakpoints?: TBreakpoints;
 	} & (
 		| {
-			/** Theme active on first launch. Defaults to 'light'. */
-			initialTheme?: ThemeName<TName> | (() => ThemeName<TName>);
-			adaptiveThemes?: false;
-		}
+				/** Theme active on first launch. Defaults to 'light'. */
+				initialTheme?: ThemeName<TName> | (() => ThemeName<TName>);
+				adaptiveThemes?: false;
+		  }
 		| {
-			/** Follow the system colour scheme between light and dark. */
-			adaptiveThemes: boolean;
-			initialTheme?: never;
-		}
+				/** Follow the system colour scheme between light and dark. */
+				adaptiveThemes: boolean;
+				initialTheme?: never;
+		  }
 	);
 
 type UnistylesSettings<TName extends string> = UnistylesBaseSettings &
@@ -103,7 +103,11 @@ function validateOptions(options: unknown, themeNames: string[]): void {
 		throw new ThemeConfigError('options.CSSVars', 'must be a boolean.');
 	}
 
-	if (nativeBreakpointsMode != null && nativeBreakpointsMode !== 'pixels' && nativeBreakpointsMode !== 'points') {
+	if (
+		nativeBreakpointsMode != null &&
+		nativeBreakpointsMode !== 'pixels' &&
+		nativeBreakpointsMode !== 'points'
+	) {
 		throw new ThemeConfigError('options.nativeBreakpointsMode', "must be 'pixels' or 'points'.");
 	}
 

package/src/unistyles/themeMode.ts

@@ -1,4 +1,6 @@
-import { UnistylesRuntime } from 'react-native-unistyles';
+import { lazyPeer } from '@chipmobilesdk/rn-core';
+
+import { ThemeConfigError } from '../theme/errors';
 
 export type ThemeMode = 'system' | 'light' | 'dark';
 
@@ -8,16 +10,37 @@ export interface ThemeModeRuntime {
 	setTheme(name: string): void;
 }
 
-// The package cannot see the app's augmented `UnistylesThemes`, so `setTheme`
-// is typed as `never` here; the runtime accepts any configured theme name.
-const defaultRuntime = UnistylesRuntime as unknown as ThemeModeRuntime;
+// Loaded when a mode is first applied, so importing the package (and building
+// themes) never loads Unistyles (THM-04). The package cannot see the app's
+// augmented `UnistylesThemes`, so the runtime is typed by the two calls it needs.
+const unistyles = lazyPeer('react-native-unistyles', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-unistyles') as { UnistylesRuntime: ThemeModeRuntime };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+function defaultRuntime(): ThemeModeRuntime {
+	return unistyles.require(
+		peer =>
+			new ThemeConfigError(
+				'applyThemeMode',
+				`${peer} is not installed; pass a runtime or install it`,
+			),
+	).UnistylesRuntime;
+}
 
 /**
  * Applies a light/dark/system preference. Adaptive themes are switched off
  * before a manual theme is set; in the other order the next OS colour-scheme
  * change overrides the user's choice. Persisting the preference is the app's.
  */
-export function applyThemeMode(mode: ThemeMode, runtime: ThemeModeRuntime = defaultRuntime): void {
+export function applyThemeMode(
+	mode: ThemeMode,
+	runtime: ThemeModeRuntime = defaultRuntime(),
+): void {
 	if (mode === 'system') {
 		runtime.setAdaptiveThemes(true);
 		return;