@octane-xplat/platform 0.1.0

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@octane-xplat/platform",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./*": "./src/*"
+  },
+  "dependencies": {
+    "@nativescript/biometrics": "1.3.1",
+    "@nativescript/haptics": "3.1.0",
+    "@nativescript/imagepicker": "5.0.0",
+    "@nativescript/local-notifications": "7.0.0",
+    "@nativescript/secure-storage": "4.0.2",
+    "@nativescript/social-share": "2.3.0",
+    "nativescript-clipboard": "2.1.1"
+  },
+  "devDependencies": {
+    "@nativescript/core": "9.1.2",
+    "octane": "0.4.0"
+  },
+  "peerDependencies": {
+    "octane": ">=0.1.51 <1"
+  },
+  "description": "Headless platform capabilities for Octane xplat — web + NativeScript leaf pairs",
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/a11y.native.ts

@@ -0,0 +1,14 @@
+// A11y announce — native leaf. UIAccessibility announcement notification on
+// iOS; View.announceForAccessibility on Android (posted on the content view).
+import { Application } from '@nativescript/core';
+
+export function announce(text: string): void {
+	if (Application.ios) {
+		UIAccessibilityPostNotification(UIAccessibilityAnnouncementNotification, text);
+		return;
+	}
+	if (Application.android) {
+		const view = Application.android.foregroundActivity?.findViewById?.(16908290 /* android.R.id.content */);
+		view?.announceForAccessibility?.(text);
+	}
+}

package/src/a11y.web.ts

@@ -0,0 +1,19 @@
+// A11y announce — web leaf. A polite aria-live region receives the text;
+// screen readers speak the DOM mutation.
+let region: HTMLElement | null = null;
+
+export function announce(text: string): void {
+	if (!region) {
+		region = document.createElement('div');
+		region.setAttribute('aria-live', 'polite');
+		region.setAttribute('role', 'status');
+		region.style.cssText =
+			'position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);';
+		document.body.appendChild(region);
+	}
+	region.textContent = '';
+	// Two writes in one frame collapse — force the SR to see a change.
+	requestAnimationFrame(() => {
+		if (region) region.textContent = text;
+	});
+}

package/src/biometrics.native.ts

@@ -0,0 +1,24 @@
+// Biometrics — FaceID/TouchID/fingerprint via @nativescript/biometrics.
+import { BiometricAuth } from '@nativescript/biometrics';
+import type { Capability } from './types';
+import type { BiometricsImpl } from './types';
+
+const bio = new BiometricAuth();
+
+export const biometrics: Capability<BiometricsImpl> = {
+	supported: true,
+	async ensure() {
+		const r = await bio.available();
+		return r.any ? 'granted' : 'unsupported';
+	},
+	impl: {
+		async verify(reason) {
+			try {
+				const r = await bio.verifyBiometric({ title: reason });
+				return r.code === 0;
+			} catch {
+				return false;
+			}
+		},
+	},
+};

package/src/biometrics.web.ts

@@ -0,0 +1,21 @@
+// Biometrics — web leaf. Platform authenticator presence is the honest
+// signal; an actual WebAuthn ceremony is an auth-flow concern, not this seam.
+import type { BiometricsImpl, Capability } from './types';
+
+const pkc = () => (globalThis as any).PublicKeyCredential;
+
+export const biometrics: Capability<BiometricsImpl> = {
+	supported: typeof pkc() !== 'undefined',
+	async ensure() {
+		if (!pkc()) return 'unsupported';
+		const ok = await pkc().isUserVerifyingPlatformAuthenticatorAvailable();
+		return ok ? 'granted' : 'unsupported';
+	},
+	impl: {
+		// A bare verify() has no ceremony target — WebAuthn needs a challenge.
+		// Report presence; wire real attestation when an auth flow exists.
+		async verify(_reason: string) {
+			return false;
+		},
+	},
+};

package/src/clipboard.native.ts

@@ -0,0 +1,17 @@
+// Clipboard — pasteboard via nativescript-clipboard (sync API wrapped async
+// to keep the shared contract awaitable on both sides).
+import { getTextSync, setTextSync } from 'nativescript-clipboard';
+
+export const clipboard = {
+	async write(text: string): Promise<boolean> {
+		setTextSync(text);
+		return true;
+	},
+	async read(): Promise<string | null> {
+		try {
+			return getTextSync();
+		} catch {
+			return null;
+		}
+	},
+};

package/src/clipboard.web.ts

@@ -0,0 +1,18 @@
+// Clipboard — async permission-gated on web; read may be denied silently.
+export const clipboard = {
+	async write(text: string): Promise<boolean> {
+		try {
+			await navigator.clipboard.writeText(text);
+			return true;
+		} catch {
+			return false;
+		}
+	},
+	async read(): Promise<string | null> {
+		try {
+			return await navigator.clipboard.readText();
+		} catch {
+			return null;
+		}
+	},
+};

package/src/deep-links.native.ts

@@ -0,0 +1,39 @@
+// Deep links — native leaf. iOS delivers openUrl + launchOptions; Android
+// delivers an intent on resume/newIntent. Handlers get the raw URL string —
+// the app maps it onto its route table.
+import { Application } from '@nativescript/core';
+
+type LinkHandler = (url: string) => void;
+const handlers = new Set<LinkHandler>();
+let wired = false;
+let initial: string | null = null;
+
+function wire() {
+	if (wired) return;
+	wired = true;
+	if (Application.ios) {
+		Application.on('openUrl', (args: any) => {
+			const url = args.url?.absoluteString ?? String(args.url ?? '');
+			for (const h of handlers) h(url);
+		});
+	}
+	if (Application.android) {
+		Application.on(Application.resumeEvent, () => {
+			const intent = Application.android.foregroundActivity?.getIntent?.();
+			const url = intent?.getDataString?.();
+			if (url) for (const h of handlers) h(url);
+		});
+	}
+}
+
+export function onDeepLink(cb: LinkHandler): () => void {
+	wire();
+	handlers.add(cb);
+	return () => handlers.delete(cb);
+}
+
+export function consumeInitialUrl(): string | null {
+	const u = initial;
+	initial = null;
+	return u;
+}

package/src/deep-links.web.ts

@@ -0,0 +1,23 @@
+// Deep links — web leaf. The URL IS the link: consumeInitialUrl returns the
+// current path; onDeepLink listens for popstate (back/forward = link events).
+type LinkHandler = (url: string) => void;
+const handlers = new Set<LinkHandler>();
+let wired = false;
+
+function wire() {
+	if (wired) return;
+	wired = true;
+	window.addEventListener('popstate', () => {
+		for (const h of handlers) h(location.pathname + location.search);
+	});
+}
+
+export function onDeepLink(cb: LinkHandler): () => void {
+	wire();
+	handlers.add(cb);
+	return () => handlers.delete(cb);
+}
+
+export function consumeInitialUrl(): string | null {
+	return location.pathname === '/' ? null : location.pathname + location.search;
+}

package/src/device.native.ts

@@ -0,0 +1,11 @@
+import { Device } from '@nativescript/core';
+import type { DeviceInfo } from './types';
+
+export const device: DeviceInfo = {
+	os: Device.os.toLowerCase() === 'ios' ? 'ios' : 'android',
+	osVersion: Device.osVersion,
+	model: Device.model,
+	manufacturer: Device.manufacturer,
+	language: Device.language.split('-')[0] ?? '',
+	region: Device.region,
+};

package/src/device.web.ts

@@ -0,0 +1,13 @@
+import type { DeviceInfo } from './types';
+
+const ua = navigator.userAgent;
+const osVersion = ua.match(/(?:Mac OS X|Windows NT|Android|OS) ([\d._]+)/)?.[1]?.replace(/_/g, '.') ?? '';
+
+export const device: DeviceInfo = {
+	os: 'web',
+	osVersion,
+	model: 'browser',
+	manufacturer: '',
+	language: navigator.language.split('-')[0] ?? '',
+	region: navigator.language.split('-')[1] ?? '',
+};

package/src/files.native.ts

@@ -0,0 +1,24 @@
+// Files — native leaf. FileRef wraps a real filesystem path under the app's
+// documents folder; picking delegates to the imagepicker/file picker seam.
+import { File, knownFolders, path } from '@nativescript/core';
+import type { FileRef } from './types';
+
+const docs = () => knownFolders.documents();
+
+export const files = {
+	/** Not implemented on native yet — file pickers are plugin-shaped;
+	 *  media.pickImage covers the common case. Returns null. */
+	async pick(_accept?: string): Promise<FileRef | null> {
+		return null;
+	},
+	async readText(ref: FileRef): Promise<string> {
+		return File.fromPath(ref.uri).readText();
+	},
+	async writeText(name: string, text: string): Promise<FileRef> {
+		const p = path.join(docs().path, name);
+		const f = File.fromPath(p);
+		f.writeTextSync(text);
+		return { name, uri: p };
+	},
+	release(_ref: FileRef): void {},
+};

package/src/files.web.ts

@@ -0,0 +1,34 @@
+// Files — web leaf. Opaque FileRef: a blob/object URL plus a name; reads go
+// through FileReader/fetch on the ref's URL.
+import type { FileRef } from './types';
+
+export const files = {
+	async pick(accept = '*/*'): Promise<FileRef | null> {
+		return new Promise((resolve) => {
+			const input = document.createElement('input');
+			input.type = 'file';
+			input.accept = accept;
+			input.onchange = () => {
+				const f = input.files?.[0];
+				resolve(f ? { name: f.name, uri: URL.createObjectURL(f) } : null);
+			};
+			input.oncancel = () => resolve(null);
+			input.click();
+		});
+	},
+	async readText(ref: FileRef): Promise<string> {
+		return (await fetch(ref.uri)).text();
+	},
+	/** "Write" on web = a download. Returns the object URL. */
+	async writeText(name: string, text: string): Promise<FileRef> {
+		const uri = URL.createObjectURL(new Blob([text], { type: 'text/plain' }));
+		const a = document.createElement('a');
+		a.href = uri;
+		a.download = name;
+		a.click();
+		return { name, uri };
+	},
+	release(ref: FileRef): void {
+		URL.revokeObjectURL(ref.uri);
+	},
+};

package/src/haptics.native.ts

@@ -0,0 +1,24 @@
+// Haptics — Taptic Engine (iOS) / Vibrator (Android) via @nativescript/haptics.
+import { Haptics, HapticImpactType, HapticNotificationType } from '@nativescript/haptics';
+import type { Capability } from './types';
+import type { HapticsImpl } from './types';
+
+export const haptics: Capability<HapticsImpl> = {
+	supported: true,
+	ensure: async () => 'granted',
+	impl: {
+		impact: (style = 'light') =>
+			Haptics.impact(
+				style === 'heavy' ? HapticImpactType.HEAVY
+				: style === 'medium' ? HapticImpactType.MEDIUM
+				: HapticImpactType.LIGHT,
+			),
+		notification: (kind) =>
+			Haptics.notification(
+				kind === 'error' ? HapticNotificationType.ERROR
+				: kind === 'warning' ? HapticNotificationType.WARNING
+				: HapticNotificationType.SUCCESS,
+			),
+		selection: () => Haptics.selection(),
+	},
+};

package/src/haptics.web.ts

@@ -0,0 +1,16 @@
+// Haptics — web leaf. navigator.vibrate exists on Android Chrome only;
+// iOS Safari and desktop report unsupported via the Capability contract.
+import type { Capability, HapticsImpl } from './types';
+
+const vibrate = (ms: number | number[]) =>
+	typeof navigator !== 'undefined' && 'vibrate' in navigator && navigator.vibrate(ms);
+
+export const haptics: Capability<HapticsImpl> = {
+	supported: typeof navigator !== 'undefined' && 'vibrate' in navigator,
+	ensure: async () => ('vibrate' in navigator ? 'granted' : 'unsupported'),
+	impl: {
+		impact: (style) => vibrate(style === 'heavy' ? 30 : style === 'medium' ? 20 : 10),
+		notification: (kind) => vibrate(kind === 'error' ? [50, 60, 50] : kind === 'warning' ? [30, 40, 30] : 15),
+		selection: () => vibrate(5),
+	},
+};

package/src/index.ts

@@ -0,0 +1,27 @@
+// Single index — each specifier resolves its own leaf through the suffix
+// chain (.web under web conditions, .native/.ios/.android under native).
+// Hook-bearing services live in .tsrx files with .ts shims so tsc's
+// moduleSuffixes can reach them (docs/module-resolution.md).
+export type {
+	AppState, BiometricsImpl, Capability, DeviceInfo, FileRef, HapticsImpl,
+	Insets, Locale, NotificationsImpl, PermissionKind, SecureStore,
+	ShareResult, WindowSize,
+} from './types';
+export { device } from './device';
+export { storage } from './storage';
+export { clipboard } from './clipboard';
+export { share } from './share';
+export { haptics } from './haptics';
+export { secureStorage } from './secure-storage';
+export { files } from './files';
+export { notifications } from './notifications';
+export { permissions } from './permissions';
+export { systemBars } from './system-bars';
+export { announce } from './a11y';
+export { locale } from './locale';
+export { media } from './media';
+export { biometrics } from './biometrics';
+export { onDeepLink, consumeInitialUrl } from './deep-links';
+export { useAppState, useBackHandler } from './lifecycle';
+export { useSafeAreaInsets } from './safe-area';
+export { useWindowSize } from './screen';

package/src/lifecycle.native.ts

@@ -0,0 +1 @@
+export { useAppState, useBackHandler } from './lifecycle.native.tsrx';

package/src/lifecycle.native.tsrx

@@ -0,0 +1,38 @@
+// App lifecycle — native leaf. Application suspend/resume/exit events map
+// onto the shared AppState vocabulary; activityBackPressed feeds
+// useBackHandler (Android hardware back).
+import { useEffect, useState } from 'octane';
+import { Application } from '@nativescript/core';
+import type { AppState } from './types';
+
+export function useAppState(): AppState {
+	const [state, setState] = useState<AppState>('active');
+	useEffect(() => {
+		const onSuspend = () => setState('background');
+		const onResume = () => setState('active');
+		const onExit = () => setState('inactive');
+		Application.on(Application.suspendEvent, onSuspend);
+		Application.on(Application.resumeEvent, onResume);
+		Application.on(Application.exitEvent, onExit);
+		return () => {
+			Application.off(Application.suspendEvent, onSuspend);
+			Application.off(Application.resumeEvent, onResume);
+			Application.off(Application.exitEvent, onExit);
+		};
+	}, []);
+	return state;
+}
+
+/** Android hardware back — handler returns true when it consumed the press. */
+export function useBackHandler(fn: () => boolean): void {
+	useEffect(() => {
+		if (!Application.android) return;
+		const cb = (e: { cancel: boolean }) => {
+			if (fn()) e.cancel = true;
+		};
+		Application.android.on(Application.AndroidApplication.activityBackPressedEvent, cb);
+		return () => {
+			Application.android.off(Application.AndroidApplication.activityBackPressedEvent, cb);
+		};
+	}, [fn]);
+}

package/src/lifecycle.web.ts

@@ -0,0 +1,2 @@
+// tsc shim — moduleSuffixes doesn't reach .tsrx (see docs/module-resolution.md).
+export { useAppState, useBackHandler } from './lifecycle.web.tsrx';

package/src/lifecycle.web.tsrx

@@ -0,0 +1,24 @@
+// App lifecycle — web leaf. visibilitychange ↔ 'active'/'background';
+// pagehide maps to 'inactive' (the unload-approaching state).
+import { useEffect, useState } from 'octane';
+import type { AppState } from './types';
+
+export function useAppState(): AppState {
+	const [state, setState] = useState<AppState>('active');
+	useEffect(() => {
+		const onVis = () => setState(document.visibilityState === 'visible' ? 'active' : 'background');
+		const onHide = () => setState('inactive');
+		document.addEventListener('visibilitychange', onVis);
+		window.addEventListener('pagehide', onHide);
+		window.addEventListener('pageshow', onVis);
+		return () => {
+			document.removeEventListener('visibilitychange', onVis);
+			window.removeEventListener('pagehide', onHide);
+			window.removeEventListener('pageshow', onVis);
+		};
+	}, []);
+	return state;
+}
+
+/** Browser back is already real history — nothing to intercept on web. */
+export function useBackHandler(_fn: () => boolean): void {}

package/src/locale.native.ts

@@ -0,0 +1,9 @@
+// Locale — Device.language/region on native.
+import { Device } from '@nativescript/core';
+import type { Locale } from './types';
+
+export const locale: Locale = {
+	tag: `${Device.language}-${Device.region}`,
+	language: Device.language.split('-')[0] ?? '',
+	region: Device.region,
+};

package/src/locale.web.ts

@@ -0,0 +1,12 @@
+// Locale — navigator.language on web ("en-US" → tag + parts).
+export interface Locale {
+	tag: string;
+	language: string;
+	region: string;
+}
+
+export const locale: Locale = (() => {
+	const tag = navigator.language ?? '';
+	const [language = '', region = ''] = tag.split('-');
+	return { tag, language, region };
+})();

package/src/media.native.ts

@@ -0,0 +1,15 @@
+// Media picking — @nativescript/imagepicker presents the system picker and
+// yields ImageAssets; the FileRef uri is the asset's file path.
+import { create as createImagePicker } from '@nativescript/imagepicker';
+import type { FileRef } from './types';
+
+export const media = {
+	async pickImage(): Promise<FileRef | null> {
+		const picker = createImagePicker({ mode: 'single' });
+		await picker.authorize();
+		const [asset] = await picker.present();
+		if (!asset) return null;
+		const uri = (asset as any).ios ?? (asset as any).android ?? '';
+		return { name: 'image', uri: String(uri) };
+	},
+};

package/src/media.web.ts

@@ -0,0 +1,10 @@
+// Media picking — web leaf. <input type=file accept="image/*"> → FileRef
+// (object URL). Multi-select stays out of v1.
+import type { FileRef } from './types';
+import { files } from './files';
+
+export const media = {
+	async pickImage(): Promise<FileRef | null> {
+		return files.pick('image/*');
+	},
+};

package/src/notifications.native.ts

@@ -0,0 +1,18 @@
+// Notifications — local notifications via plugin; push (APNs/FCM) is an
+// app-level concern, not this seam.
+import { LocalNotifications } from '@nativescript/local-notifications';
+import type { Capability } from './types';
+import type { NotificationsImpl } from './types';
+
+export const notifications: Capability<NotificationsImpl> = {
+	supported: true,
+	async ensure() {
+		const granted = await LocalNotifications.requestPermission();
+		return granted ? 'granted' : 'denied';
+	},
+	impl: {
+		notify(title, body) {
+			LocalNotifications.schedule([{ id: Date.now() % 2147483647, title, body: body ?? '' }]);
+		},
+	},
+};

package/src/notifications.web.ts

@@ -0,0 +1,18 @@
+// Notifications — Web Notification API. ensure() maps permission state;
+// notify() posts an immediate local notification (no push).
+import type { Capability, NotificationsImpl } from './types';
+
+export const notifications: Capability<NotificationsImpl> = {
+	supported: typeof Notification !== 'undefined',
+	async ensure() {
+		if (typeof Notification === 'undefined') return 'unsupported';
+		if (Notification.permission === 'granted') return 'granted';
+		if (Notification.permission === 'denied') return 'denied';
+		return (await Notification.requestPermission()) === 'granted' ? 'granted' : 'denied';
+	},
+	impl: {
+		notify(title, body) {
+			if (Notification.permission === 'granted') new Notification(title, { body });
+		},
+	},
+};

package/src/permissions.native.ts

@@ -0,0 +1,20 @@
+// Runtime permissions — native leaf. Maps the shared kind union onto the
+// owning plugin's request call; add kinds as services land.
+import { LocalNotifications } from '@nativescript/local-notifications';
+import type { PermissionKind } from './types';
+
+export const permissions = {
+	async ensure(kind: PermissionKind): Promise<'granted' | 'denied' | 'unsupported'> {
+		switch (kind) {
+			case 'notifications':
+				return (await LocalNotifications.requestPermission()) ? 'granted' : 'denied';
+			// camera/photos/location have dedicated plugins — the owning
+			// service leaf (media, geolocation) owns its own ensure(); this
+			// generic seam reports them unsupported until wired.
+			case 'camera':
+			case 'photos':
+			case 'location':
+				return 'unsupported';
+		}
+	},
+};

package/src/permissions.web.ts

@@ -0,0 +1,38 @@
+// Runtime permissions — web leaf. Browsers grant most capabilities per-API
+// (clipboard/notification have their own ensure()); this generic seam covers
+// feature-detection for the rest.
+export type PermissionKind = 'notifications' | 'camera' | 'photos' | 'location';
+
+export const permissions = {
+	async ensure(kind: PermissionKind): Promise<'granted' | 'denied' | 'unsupported'> {
+		switch (kind) {
+			case 'notifications': {
+				if (typeof Notification === 'undefined') return 'unsupported';
+				if (Notification.permission === 'granted') return 'granted';
+				if (Notification.permission === 'denied') return 'denied';
+				return (await Notification.requestPermission()) === 'granted' ? 'granted' : 'denied';
+			}
+			case 'camera':
+			case 'photos': {
+				if (!navigator.mediaDevices?.getUserMedia) return 'unsupported';
+				try {
+					const s = await navigator.mediaDevices.getUserMedia({ video: true });
+					s.getTracks().forEach((t) => t.stop());
+					return 'granted';
+				} catch {
+					return 'denied';
+				}
+			}
+			case 'location': {
+				if (!('geolocation' in navigator)) return 'unsupported';
+				return new Promise((resolve) =>
+					navigator.geolocation.getCurrentPosition(
+						() => resolve('granted'),
+						(e) => resolve(e.code === e.PERMISSION_DENIED ? 'denied' : 'unsupported'),
+						{ timeout: 15000 },
+					),
+				);
+			}
+		}
+	},
+};

package/src/safe-area.native.ts

@@ -0,0 +1 @@
+export { useSafeAreaInsets } from './safe-area.native.tsrx';

package/src/safe-area.native.tsrx

@@ -0,0 +1,27 @@
+// Safe-area insets — native leaf. Reads the window's safe area after layout;
+// falls back to zero before it exists.
+import { useEffect, useState } from 'octane';
+import type { Insets } from './types';
+import { Application } from '@nativescript/core';
+
+
+function readInsets(): Insets {
+	if (Application.ios) {
+		const v = Application.ios.rootController?.view;
+		const i = v?.safeAreaInsets;
+		if (i) return { top: i.top, bottom: i.bottom, left: i.left, right: i.right };
+	}
+	// Android: WindowInsets need an attached view — return 0 until a screen
+	// supplies its own; orientation change re-reads.
+	return { top: 0, bottom: 0, left: 0, right: 0 };
+}
+
+export function useSafeAreaInsets(): Insets {
+	const [insets, setInsets] = useState<Insets>(readInsets);
+	useEffect(() => {
+		const update = () => setInsets(readInsets());
+		Application.on(Application.orientationChangedEvent, update);
+		return () => Application.off(Application.orientationChangedEvent, update);
+	}, []);
+	return insets;
+}

package/src/safe-area.web.ts

@@ -0,0 +1 @@
+export { useSafeAreaInsets } from './safe-area.web.tsrx';

package/src/safe-area.web.tsrx

@@ -0,0 +1,34 @@
+// Safe-area insets — web leaf. env(safe-area-inset-*) only exists in CSS;
+// measure it once through a probe element.
+import { useEffect, useState } from 'octane';
+import type { Insets } from './types';
+
+
+function measure(): Insets {
+	const probe = document.createElement('div');
+	probe.style.cssText =
+		'position:fixed;top:0;left:0;pointer-events:none;visibility:hidden;' +
+		'padding-top:env(safe-area-inset-top);padding-bottom:env(safe-area-inset-bottom);' +
+		'padding-left:env(safe-area-inset-left);padding-right:env(safe-area-inset-right);';
+	document.body.appendChild(probe);
+	const cs = getComputedStyle(probe);
+	const insets = {
+		top: parseFloat(cs.paddingTop) || 0,
+		bottom: parseFloat(cs.paddingBottom) || 0,
+		left: parseFloat(cs.paddingLeft) || 0,
+		right: parseFloat(cs.paddingRight) || 0,
+	};
+	probe.remove();
+	return insets;
+}
+
+export function useSafeAreaInsets(): Insets {
+	const [insets, setInsets] = useState<Insets>({ top: 0, bottom: 0, left: 0, right: 0 });
+	useEffect(() => {
+		const update = () => setInsets(measure());
+		update();
+		window.addEventListener('resize', update);
+		return () => window.removeEventListener('resize', update);
+	}, []);
+	return insets;
+}

package/src/screen.native.ts

@@ -0,0 +1 @@
+export { useWindowSize } from './screen.native.tsrx';

package/src/screen.native.tsrx

@@ -0,0 +1,25 @@
+// Window size + orientation — native leaf. Screen.mainScreen gives DIPs;
+// Application.orientationChangedEvent drives updates.
+import { useEffect, useState } from 'octane';
+import type { WindowSize } from './types';
+import { Application, Screen } from '@nativescript/core';
+
+
+function read(): WindowSize {
+	const s = Screen.mainScreen;
+	return {
+		width: s.widthDIPs,
+		height: s.heightDIPs,
+		orientation: s.widthDIPs >= s.heightDIPs ? 'landscape' : 'portrait',
+	};
+}
+
+export function useWindowSize(): WindowSize {
+	const [size, setSize] = useState<WindowSize>(read);
+	useEffect(() => {
+		const update = () => setSize(read());
+		Application.on(Application.orientationChangedEvent, update);
+		return () => Application.off(Application.orientationChangedEvent, update);
+	}, []);
+	return size;
+}

package/src/screen.web.ts

@@ -0,0 +1 @@
+export { useWindowSize } from './screen.web.tsrx';

package/src/screen.web.tsrx

@@ -0,0 +1,26 @@
+// Window size + orientation — web leaf.
+import { useEffect, useState } from 'octane';
+import type { WindowSize } from './types';
+
+
+function read(): WindowSize {
+	return {
+		width: window.innerWidth,
+		height: window.innerHeight,
+		orientation: window.innerWidth >= window.innerHeight ? 'landscape' : 'portrait',
+	};
+}
+
+export function useWindowSize(): WindowSize {
+	const [size, setSize] = useState<WindowSize>(read);
+	useEffect(() => {
+		const update = () => setSize(read());
+		window.addEventListener('resize', update);
+		window.addEventListener('orientationchange', update);
+		return () => {
+			window.removeEventListener('resize', update);
+			window.removeEventListener('orientationchange', update);
+		};
+	}, []);
+	return size;
+}

package/src/secure-storage.native.ts

@@ -0,0 +1,17 @@
+// Secure storage — Keychain (iOS) / Keystore (Android) via plugin.
+import { SecureStorage } from '@nativescript/secure-storage';
+import type { Capability } from './types';
+import type { SecureStore } from './types';
+
+const store = new SecureStorage();
+
+export const secureStorage: Capability<SecureStore> = {
+	supported: true,
+	// No runtime permission needed — Keychain/Keystore is device-owned.
+	ensure: async () => 'granted',
+	impl: {
+		get: (key) => store.get({ key }).then((v) => v ?? null),
+		set: (key, value) => store.set({ key, value }),
+		remove: (key) => store.remove({ key }),
+	},
+};

package/src/secure-storage.web.ts

@@ -0,0 +1,10 @@
+// Secure storage — web has no equivalent trust boundary (IndexedDB is not
+// secure enclave storage). Declared unsupported per the Capability contract;
+// callers must branch on `supported` rather than catching.
+import type { Capability, SecureStore } from './types';
+
+export const secureStorage: Capability<SecureStore> = {
+	supported: false,
+	ensure: async () => 'unsupported',
+	impl: null,
+};

package/src/share.native.ts

@@ -0,0 +1,13 @@
+// Share — native share sheet via @nativescript/social-share.
+import { shareText, shareUrl } from '@nativescript/social-share';
+
+export const share = {
+	async text(text: string, subject?: string): Promise<'shared'> {
+		shareText(text, subject);
+		return 'shared';
+	},
+	async url(url: string, title?: string): Promise<'shared'> {
+		shareUrl(url, title ?? url);
+		return 'shared';
+	},
+};

package/src/share.web.ts

@@ -0,0 +1,28 @@
+// Share — web leaf. navigator.share where present (mobile Safari/Chrome);
+// desktop degrades to clipboard copy so the call still does something useful.
+export const share = {
+	async text(text: string, subject?: string): Promise<'shared' | 'copied' | 'unavailable'> {
+		const nav = navigator as any;
+		if (nav.share) {
+			await nav.share({ text, title: subject });
+			return 'shared';
+		}
+		if (nav.clipboard) {
+			await nav.clipboard.writeText(text);
+			return 'copied';
+		}
+		return 'unavailable';
+	},
+	async url(url: string, title?: string): Promise<'shared' | 'copied' | 'unavailable'> {
+		const nav = navigator as any;
+		if (nav.share) {
+			await nav.share({ url, title });
+			return 'shared';
+		}
+		if (nav.clipboard) {
+			await nav.clipboard.writeText(url);
+			return 'copied';
+		}
+		return 'unavailable';
+	},
+};

package/src/storage.native.ts

@@ -0,0 +1,10 @@
+import { ApplicationSettings } from '@nativescript/core';
+
+/** Sync KV seam — NS ApplicationSettings (NSUserDefaults) on native,
+ *  the web leaf uses the DOM's string store. String-only for v1;
+ *  serialize objects at the edge. */
+export const storage = {
+	getString: (k: string): string | null => ApplicationSettings.getString(k) ?? null,
+	setString: (k: string, v: string): void => { ApplicationSettings.setString(k, v); },
+	remove: (k: string): void => { ApplicationSettings.remove(k); },
+};

package/src/storage.web.ts

@@ -0,0 +1,6 @@
+/** Sync KV seam — localStorage on web. */
+export const storage = {
+	getString: (k: string): string | null => localStorage.getItem(k),
+	setString: (k: string, v: string): void => { localStorage.setItem(k, v); },
+	remove: (k: string): void => { localStorage.removeItem(k); },
+};

package/src/system-bars.native.ts

@@ -0,0 +1,22 @@
+// Status/nav bars — native leaf. iOS status-bar style + Android
+// navigation-bar color via the application window.
+import { Application, Color } from '@nativescript/core';
+
+export const systemBars = {
+	setStatusBarStyle(style: 'light' | 'dark'): void {
+		if (Application.ios) {
+			const app = Application.ios.nativeApp;
+			// NS 9: per-page statusBarStyle is the preferred seam; fall back to
+			// the app-level setter on older systems.
+			(app as any)?.setStatusBarStyle?.(style === 'light' ? 1 : 0);
+		}
+	},
+	setColor(color: string): void {
+		const c = new Color(color);
+		if (Application.android?.startActivity) {
+			const win = Application.android.startActivity.getWindow();
+			win.setStatusBarColor(c.android);
+			win.setNavigationBarColor(c.android);
+		}
+	},
+};

package/src/system-bars.web.ts

@@ -0,0 +1,14 @@
+// Status/nav bars — web leaf. No status bar on web, but theme-color is the
+// honest equivalent: it tints mobile browser chrome.
+export const systemBars = {
+	setStatusBarStyle(_style: 'light' | 'dark'): void {},
+	setColor(color: string): void {
+		let meta = document.querySelector('meta[name="theme-color"]');
+		if (!meta) {
+			meta = document.createElement('meta');
+			meta.setAttribute('name', 'theme-color');
+			document.head.appendChild(meta);
+		}
+		meta.setAttribute('content', color);
+	},
+};

package/src/types.ts

@@ -0,0 +1,71 @@
+// Shared contract shapes — imported by BOTH leaves. Types must live here,
+// never in a leaf: `import … from './x.web'` inside x.native.ts drags the
+// web implementation into the native typecheck program.
+
+/** Optional capability — never throws for absence (docs/platform-services.md). */
+export interface Capability<T> {
+	supported: boolean;
+	ensure(): Promise<'granted' | 'denied' | 'unsupported'>;
+	/** usable iff supported && ensured */
+	impl: T | null;
+}
+
+export type AppState = 'active' | 'background' | 'inactive';
+
+export interface DeviceInfo {
+	os: 'web' | 'ios' | 'android';
+	osVersion: string;
+	model: string;
+	manufacturer: string;
+	language: string;
+	region: string;
+}
+
+export interface Insets {
+	top: number;
+	bottom: number;
+	left: number;
+	right: number;
+}
+
+export interface WindowSize {
+	width: number;
+	height: number;
+	orientation: 'portrait' | 'landscape';
+}
+
+export interface FileRef {
+	name: string;
+	/** blob:/object URL on web, filesystem path on native — opaque */
+	uri: string;
+}
+
+export interface Locale {
+	tag: string;
+	language: string;
+	region: string;
+}
+
+export interface SecureStore {
+	get(key: string): Promise<string | null>;
+	set(key: string, value: string): Promise<boolean>;
+	remove(key: string): Promise<boolean>;
+}
+
+export interface HapticsImpl {
+	impact(style?: 'light' | 'medium' | 'heavy'): void;
+	notification(kind: 'success' | 'warning' | 'error'): void;
+	selection(): void;
+}
+
+export interface NotificationsImpl {
+	notify(title: string, body?: string): void;
+}
+
+export interface BiometricsImpl {
+	verify(reason: string): Promise<boolean>;
+}
+
+export type PermissionKind = 'notifications' | 'camera' | 'photos' | 'location';
+
+export type ShareResult = 'shared' | 'copied' | 'unavailable';