@haiyue/native 0.1.0

package/bridge/lifecycle/host.ts

@@ -0,0 +1,330 @@
+import { PresentationPause } from './presentation-pause';
+import { Application, File, knownFolders, path, isAndroid } from '@nativescript/core';
+import type { Canvas } from '@nativescript/canvas';
+import { HaiyueEngine } from '@haiyue/engine';
+import { getEngineDiagnosticsSnapshot } from '@haiyue/engine/diagnostics';
+import { FramePerformance } from './frame-performance';
+import { NativeDemandFrames } from './demand-frames';
+import { NativeSurface, NativeSurfaceUnavailableError, type NativeCanvasInput } from '../render/surface';
+import { captureSurfaceFrame, isFrameCaptureRequested } from '../render/frame-capture';
+import { nativeFrames, installNativeFrameRuntime } from './runtime';
+
+export interface NativeHostInput {
+  suspend(): void;
+  resume(): void;
+  dispose(): void;
+  snapshot(): unknown;
+}
+
+export interface NativeRenderHostOptions {
+  /** Opt-in demand rendering. Call requestFrame() for input/async changes. */
+  needsAnimationFrame?: () => boolean;
+  performance?: boolean;
+  /** Zero disables periodic snapshots/writes; lifecycle and errors remain logged. */
+  diagnosticIntervalFrames?: number;
+  canvasInput?: NativeCanvasInput;
+  engineOptions?: Pick<ConstructorParameters<typeof HaiyueEngine>[0], 'clearColor' | 'renderProfile' | 'msaaSamples' | 'reverseZ' | 'diagnostics'>;
+  bindInput?: (engine: HaiyueEngine, report: (event: string, detail: unknown) => void) => NativeHostInput;
+  prepareScene?: (engine: HaiyueEngine) => unknown | Promise<unknown>;
+  disposeScene?: () => void;
+  diagnosticName?: string;
+  capture?: { requested: boolean; file: string };
+}
+
+export class NativeRenderHost {
+  private engine: HaiyueEngine | null = null;
+  private surface: NativeSurface;
+  private initializing = false;
+  private disposed = false;
+  private suspended = false;
+  private readonly presentationPause = new PresentationPause(() => this.suspend(), () => this.resume());
+  private readonly appSuspend = () => this.presentationPause.setBackground(true);
+  private readonly appResume = () => this.presentationPause.setBackground(false);
+  /** Stops frames, audio and input until BOTH the presentation and background suspension end. */
+  pausePresentation(): () => void { return this.disposed ? () => {} : this.presentationPause.acquire(); }
+  /** Present the disabled/loading UI once before stopping the demand renderer. */
+  preparePresentation(): Promise<() => void> {
+    const engine = this.engine;
+    if (!engine || engine.state !== 'ready' || this.suspended || this.disposed) return Promise.resolve(this.pausePresentation());
+    return new Promise(resolve => {
+      let complete = false;
+      const finish = () => {
+        if (complete) return;
+        complete = true; clearTimeout(timeout); engine.off('after-update', finish);
+        resolve(this.pausePresentation());
+      };
+      const timeout = setTimeout(finish, 150);
+      engine.on('after-update', finish); this.requestFrame();
+    });
+  }
+  private surfaceRetry: ReturnType<typeof setTimeout> | null = null;
+  private surfaceMisses = 0;
+  private surfaceInputPaused = false;
+  private surfacePause: (() => void) | null = null;
+  private layoutPause: (() => void) | null = null;
+  private readonly surfaceDestroyed = (): void => {
+    if (!this.disposed && !this.failed && !this.surfacePause) this.surfacePause = this.presentationPause.acquire();
+  };
+  private readonly surfaceCreated = (): void => {
+    const release = this.surfacePause;
+    this.surfacePause = null;
+    release?.();
+  };
+  private failed = false;
+  private generation = 0;
+  private input: NativeHostInput | null = null;
+  private sceneDisposed = false;
+  private resumeCount = 0;
+  private observedDevice: GPUDevice | null = null;
+  private captureRequested: boolean;
+  private readonly journal: string[] = [];
+  private readonly logFile: File;
+  private readonly performance = new FramePerformance();
+  private readonly demand: NativeDemandFrames | null;
+
+  constructor(private readonly view: Canvas, private readonly status: (text: string) => void, private readonly options: NativeRenderHostOptions = {}) {
+    this.captureRequested = options.capture?.requested ?? isFrameCaptureRequested();
+    this.demand = options.needsAnimationFrame ? new NativeDemandFrames({
+      start: () => { try { this.engine?.run(); } catch (error) { this.fail(error); } },
+      stop: () => this.engine?.stop(),
+      defer: callback => { void Promise.resolve().then(callback); },
+    }) : null;
+    this.logFile = File.fromPath(path.join(knownFolders.documents().path, `${options.diagnosticName ?? 'g02'}-host.jsonl`));
+    this.surface = new NativeSurface(view, this.report, options.canvasInput);
+    installNativeFrameRuntime(error => this.fail(error));
+    Application.on(Application.suspendEvent, this.appSuspend);
+    Application.on(Application.resumeEvent, this.appResume);
+    view.on('layoutChanged', this.layout);
+    view.on('surfaceDestroyed', this.surfaceDestroyed);
+    view.on('surfaceCreated', this.surfaceCreated);
+    this.report('host-created', { engine: '0.1.0', canvas: '2.1.18', runtime: '9.0.3', backendRoute: isAndroid ? 'Canvas/wgpu/Vulkan' : 'Canvas/wgpu/Metal', dpr: this.surface.pixelRatio, captureRequested: this.captureRequested });
+    this.layout();
+  }
+
+  private readonly report = (event: string, detail: unknown): void => {
+    const record = JSON.stringify({ time: Date.now(), event, detail });
+    console.log(`[${this.options.diagnosticName ?? 'g02'}] ${record}`);
+    this.journal.push(record);
+    if (this.journal.length > 200) this.journal.splice(1, 1);
+    try { this.logFile.writeTextSync(this.journal.join('\n') + '\n'); }
+    catch (error) { console.error('[G02] Failed to persist diagnostic journal', error); }
+  };
+
+  private readonly layout = (): void => {
+    if (this.disposed || this.failed) return;
+    if (!this.surface.hasLayout) {
+      if (this.engine && !this.layoutPause) this.layoutPause = this.presentationPause.acquire();
+      return;
+    }
+    if (this.layoutPause) {
+      const release = this.layoutPause; this.layoutPause = null; release(); return;
+    }
+    if (this.suspended || this.surfaceRetry !== null) return;
+    if (!this.engine) { void this.initialize(); return; }
+    if (this.engine.state === 'ready') {
+      try { this.engine.resizeToDisplaySize(); this.requestFrame(); } catch (error) { this.fail(error); }
+    }
+  };
+
+  private async initialize(): Promise<void> {
+    if (this.initializing || this.disposed || this.failed) return;
+    this.initializing = true;
+    const generation = ++this.generation;
+    this.status('正在初始化原生 WebGPU…');
+    try {
+      const engine = new HaiyueEngine({ ...this.surface.engineOptions(), renderProfile: 'simple', msaaSamples: 1, timestampQuery: false, diagnostics:{enabled:this.options.performance===true}, recoverDeviceLost: false, clearColor: { r: 0.025, g: 0.055, b: 0.095, a: 1 }, ...this.options.engineOptions });
+      this.engine = engine;
+      await engine.init();
+      if (this.disposed || this.failed || generation !== this.generation) { engine.destroy(); return; }
+      this.observedDevice = engine.device;
+      this.observedDevice.addEventListener('uncapturederror', this.onGpuError);
+      engine.on('update',this.beforeFrame);
+      engine.on('device-lost', event => this.fail(new Error(`WebGPU device lost: ${event.detail?.message}`)));
+      if (this.options.prepareScene) this.report('scene-ready', await this.options.prepareScene(engine));
+      else engine.switchScene(engine.createScene({ render3D: true, view: { clearColor: engine.clearColor } }));
+      if (this.disposed || this.failed || generation !== this.generation) { engine.destroy(); return; }
+      this.input = this.options.bindInput?.(engine, this.report) ?? null;
+      if (this.suspended) this.input?.suspend();
+      this.report('input-ready', this.input?.snapshot() ?? null);
+      engine.on('after-update', this.afterFrame);
+      this.report('engine-ready', { width: engine.width, height: engine.height, format: engine.format, profile: engine.renderProfile, clearColor: engine.clearColor });
+      if (!this.suspended) { if (this.demand) this.demand.resume(); else engine.run(); }
+    } catch (error) { if (!this.disposed) this.fail(error); }
+    finally {
+      this.initializing = false;
+      if (this.failed) void this.releaseFailedEngine();
+    }
+  }
+
+  private readonly afterFrame = (): void => {
+    if (this.failed || this.disposed || this.suspended) return;
+    if (this.captureRequested && this.surface.presentedFrames === 119) {
+      this.captureRequested = false;
+      try { this.report('frame-capture', { ...captureSurfaceFrame(this.view, this.options.capture?.file), frame: 120 }); }
+      catch (error) { this.report('capture-error', { message: String(error) }); }
+    }
+    if (!this.surface.present()) { this.finishDemandFrame(); return; }
+    if (this.surfaceMisses) {
+      this.report('surface-recovered', { attempts: this.surfaceMisses, frames: this.surface.presentedFrames });
+      this.surfaceMisses = 0;
+    }
+    if(this.options.performance)this.performance.end(performance.now());
+    const frames = this.surface.presentedFrames;
+    const interval = this.options.diagnosticIntervalFrames ?? 120;
+    if (frames === 1 || (interval > 0 && frames % interval === 0)) {
+      this.status(`原生 WebGPU 已呈现 ${frames} 帧`);
+      this.report('present', { frames, width: this.engine?.width, height: this.engine?.height, scheduledCallbacks: nativeFrames.pendingCount, input: this.input?.snapshot() ?? null });
+      if(this.options.performance && this.engine)this.report('performance',{frames,...this.performance.take(),thermalState:isAndroid ? null : NSProcessInfo.processInfo.thermalState,engine:getEngineDiagnosticsSnapshot(this.engine)});
+    }
+    this.finishDemandFrame();
+  };
+
+  requestFrame(): void { this.demand?.request(); }
+  renderingSnapshot() {
+    return { frames: this.surface.presentedFrames, scheduledCallbacks: nativeFrames.pendingCount, demand: this.demand?.snapshot() ?? null };
+  }
+  private finishDemandFrame(): void {
+    this.demand?.afterFrame(this.captureRequested || this.options.needsAnimationFrame?.() === true);
+  }
+
+  private readonly beforeFrame = ():void => {
+    if (this.options.performance) this.performance.begin(performance.now());
+    this.surface.beginFrame();
+    if (this.surfaceInputPaused) { this.surfaceInputPaused = false; this.input?.resume(); }
+  };
+
+  private cancelSurfaceRetry(): void {
+    if (this.surfaceRetry !== null) clearTimeout(this.surfaceRetry);
+    this.surfaceRetry = null;
+  }
+
+  private retrySurface(): void {
+    if (this.suspended || this.surfaceRetry !== null) return;
+    if (++this.surfaceMisses > 8) { this.fail(new Error('Native surface remained unavailable after 8 retries.')); return; }
+    this.demand?.suspend();
+    this.engine?.stop();
+    nativeFrames.cancelAll();
+    if (!this.surfaceInputPaused) { this.surfaceInputPaused = true; this.input?.suspend(); }
+    this.performance.reset();
+    this.report('surface-wait', { attempt: this.surfaceMisses });
+    // Never restart inside the failing RAF. Backoff avoids hot-looping a lost surface.
+    this.surfaceRetry = setTimeout(() => {
+      this.surfaceRetry = null;
+      if (this.disposed || this.failed || this.suspended || this.engine?.state !== 'ready') return;
+      try {
+        if (!this.surface.hasLayout) { this.layout(); return; }
+        this.engine.resizeToDisplaySize();
+        this.surface.reconfigure();
+        if (this.demand) this.demand.resume(); else this.engine.run();
+      } catch (error) { this.fail(error); }
+    }, Math.min(50 * 2 ** (this.surfaceMisses - 1), 400));
+  }
+
+  private readonly suspend = (): void => {
+    this.cancelSurfaceRetry();
+    this.surfaceMisses = 0;
+    this.performance.reset();
+    this.suspended = true;
+    this.demand?.suspend();
+    this.input?.suspend();
+    this.engine?.stop();
+    nativeFrames.cancelAll();
+    this.report('suspend', { frames: this.surface.presentedFrames, scheduledCallbacks: nativeFrames.pendingCount, input: this.input?.snapshot() ?? null });
+  };
+
+  private readonly resume = (): void => {
+    if (this.disposed || this.failed || !this.suspended) return;
+    this.suspended = false;
+    try {
+      this.layout();
+      if (this.suspended) return;
+      if (this.engine?.state === 'ready' && !this.initializing) {
+        this.engine.resizeToDisplaySize(true);
+        this.surface.reconfigure();
+        this.input?.resume();
+        this.surfaceInputPaused = false;
+        if (this.demand) this.demand.resume(); else this.engine.run();
+      }
+    } catch (error) { this.fail(error); return; }
+    this.report('resume', { count: ++this.resumeCount, frames: this.surface.presentedFrames, scheduledCallbacks: nativeFrames.pendingCount, input: this.input?.snapshot() ?? null });
+  };
+
+  fail(error: unknown): void {
+    if (this.disposed || this.failed) return;
+    if (error instanceof NativeSurfaceUnavailableError && this.engine?.state === 'ready' && !this.initializing) {
+      this.retrySurface(); return;
+    }
+    this.failed = true;
+    this.cancelSurfaceRetry();
+    this.demand?.suspend();
+    this.input?.suspend();
+    this.engine?.stop();
+    nativeFrames.cancelAll();
+    const message = error instanceof Error ? `${error.message}\n${error.stack ?? ''}` : String(error);
+    this.status(`初始化或渲染失败\n${message}`);
+    this.report('error', { message });
+    if (!this.initializing) void this.releaseFailedEngine();
+  }
+
+  private readonly onGpuError = (event: GPUUncapturedErrorEvent): void => this.fail(event.error);
+
+  private removeDeviceListener(): void {
+    this.engine?.off('update',this.beforeFrame);
+    this.observedDevice?.removeEventListener('uncapturederror', this.onGpuError);
+    this.observedDevice = null;
+  }
+
+  private async releaseFailedEngine(): Promise<void> {
+    const engine = this.engine;
+    if (!engine) return;
+    // Yield past the current render callback and any Engine device-loss cleanup.
+    try { await engine.waitForRecovery(); }
+    catch (error) { this.report('recovery-cleanup-error', { message: String(error) }); }
+    try {
+      this.disposeInput();
+      this.disposeScene();
+      this.removeDeviceListener();
+      engine.destroy();
+      if (this.engine === engine) this.engine = null;
+      this.report('failure-cleanup', { state: engine.state, scheduledCallbacks: nativeFrames.pendingCount });
+    } catch (error) {
+      this.report('cleanup-error', { message: String(error) });
+    } finally {
+      try { this.surface.release(); }
+      catch (error) { this.report('surface-cleanup-error', { message: String(error) }); }
+    }
+  }
+
+  private disposeInput(): void {
+    if (!this.input) return;
+    this.input.dispose();
+    this.report('input-disposed', this.input.snapshot());
+    this.input = null;
+  }
+
+  private disposeScene(): void {
+    if (this.sceneDisposed) return;
+    this.sceneDisposed = true;
+    this.options.disposeScene?.();
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.cancelSurfaceRetry();
+    this.demand?.dispose();
+    ++this.generation;
+    this.disposeInput();
+    this.disposeScene();
+    Application.off(Application.suspendEvent, this.appSuspend);
+    Application.off(Application.resumeEvent, this.appResume);
+    this.view.off('layoutChanged', this.layout);
+    this.view.off('surfaceDestroyed', this.surfaceDestroyed);
+    this.view.off('surfaceCreated', this.surfaceCreated);
+    nativeFrames.cancelAll();
+    this.removeDeviceListener();
+    this.engine?.destroy();
+    this.engine = null;
+    this.report('disposed', { frames: this.surface.presentedFrames, scheduledCallbacks: nativeFrames.pendingCount, input: null });
+  }
+}

package/bridge/lifecycle/launch-flags.ts

@@ -0,0 +1,6 @@
+import { Application, isAndroid } from '@nativescript/core';
+/** Explicit development launch flags; no persistent change to production saves. */
+export function nativeLaunchFlag(name: string): boolean {
+  if (isAndroid) return (Application.android.foregroundActivity ?? Application.android.startActivity)?.getIntent()?.getBooleanExtra(name, false) ?? false;
+  return String(NSProcessInfo.processInfo.environment.objectForKey(name)) === '1';
+}

package/bridge/lifecycle/presentation-pause.ts

@@ -0,0 +1,18 @@
+/** Reconciles OS backgrounding with overlapping native full-screen presentations. */
+export class PresentationPause {
+  private background = false;
+  private tokens = new Set<object>();
+  private paused = false;
+  constructor(private readonly suspend: () => void, private readonly resume: () => void) {}
+  setBackground(value: boolean): void { this.background = value; this.sync(); }
+  acquire(): () => void {
+    const token = {}; this.tokens.add(token); this.sync();
+    return () => { this.tokens.delete(token); this.sync(); };
+  }
+  private sync(): void {
+    const paused = this.background || this.tokens.size > 0;
+    if (paused === this.paused) return;
+    this.paused = paused;
+    if (paused) this.suspend(); else this.resume();
+  }
+}

package/bridge/lifecycle/runtime.ts

@@ -0,0 +1,31 @@
+import { requestAnimationFrame, cancelAnimationFrame } from '@nativescript/core/animation-frame';
+import { time } from '@nativescript/core/profiling';
+import { AbortController, AbortSignal } from '@nativescript/core/abortcontroller';
+import { createFrameScheduler } from './frame-scheduler';
+
+let reportFrameError: (error: unknown) => void = error => console.error(error);
+const clock = typeof globalThis.performance?.now === 'function'
+  ? globalThis.performance.now.bind(globalThis.performance) : time;
+export const nativeFrames = createFrameScheduler({
+  request: requestAnimationFrame,
+  cancel: cancelAnimationFrame,
+  now: clock,
+}, error => reportFrameError(error));
+
+/** Only the scheduling globals actually used by Engine; no synthetic DOM. */
+export function installNativeFrameRuntime(onError: (error: unknown) => void): void {
+  reportFrameError = onError;
+  // Core 9.1 leaves this to the runtime; the Canvas-compatible iOS 9.0.3
+  // runtime needs Core's existing implementation for Scene asset ownership.
+  if (typeof globalThis.AbortController === 'undefined') {
+    Object.defineProperty(globalThis, 'AbortController', { configurable: true, value: AbortController });
+    Object.defineProperty(globalThis, 'AbortSignal', { configurable: true, value: AbortSignal });
+  }
+  if (typeof globalThis.performance?.now !== 'function') {
+    Object.defineProperty(globalThis, 'performance', { configurable: true, value: { now: clock } });
+  }
+  // Core's CommonJS globals are configurable lazy getters without setters.
+  // Define our scheduler explicitly instead of assigning to those getters.
+  Object.defineProperty(globalThis, 'requestAnimationFrame', { configurable: true, writable: true, value: (callback: FrameRequestCallback) => nativeFrames.request(callback) });
+  Object.defineProperty(globalThis, 'cancelAnimationFrame', { configurable: true, writable: true, value: (id: number) => nativeFrames.cancel(id) });
+}

package/bridge/media/save-photo.android.ts

@@ -0,0 +1,49 @@
+import { Application } from '@nativescript/core';
+
+async function legacyPermission(): Promise<void> {
+  const activity = Application.android.foregroundActivity ?? Application.android.startActivity;
+  const permission = android.Manifest.permission.WRITE_EXTERNAL_STORAGE;
+  if (!activity || activity.checkSelfPermission(permission) === android.content.pm.PackageManager.PERMISSION_GRANTED) {
+    if (!activity) throw Error('No active activity');
+    return;
+  }
+  await new Promise<void>((resolve, reject) => {
+    const requestCode = 7042;
+    const listener = (args: { requestCode: number; grantResults: number[] }) => {
+      if (args.requestCode !== requestCode) return;
+      Application.android.off(Application.android.activityRequestPermissionsEvent, listener);
+      if (args.grantResults[0] === android.content.pm.PackageManager.PERMISSION_GRANTED) resolve();
+      else reject(Error('Photo permission denied'));
+    };
+    Application.android.on(Application.android.activityRequestPermissionsEvent, listener);
+    activity.requestPermissions([permission], requestCode);
+  });
+}
+
+/** Save only the image requested by the player; scoped storage needs no library access. */
+export async function savePhoto(canvas: HTMLCanvasElement, filename: string): Promise<'photos'> {
+  const scoped = android.os.Build.VERSION.SDK_INT >= 29;
+  if (!scoped) await legacyPermission();
+  const data = canvas.toDataURL('image/png').split(',')[1];
+  if (!data) throw Error('PNG encoding failed');
+  const bytes = android.util.Base64.decode(data, android.util.Base64.DEFAULT);
+  const resolver = Application.android.context.getContentResolver();
+  const values = new android.content.ContentValues();
+  values.put('_display_name', filename); values.put('mime_type', 'image/png');
+  if (scoped) { values.put('relative_path', 'Pictures/Haiyue'); values.put('is_pending', java.lang.Integer.valueOf(1)); }
+  const uri = resolver.insert(android.provider.MediaStore.Images.Media.EXTERNAL_CONTENT_URI, values);
+  if (!uri) throw Error('Cannot create photo');
+  try {
+    const stream = resolver.openOutputStream(uri);
+    if (!stream) throw Error('Cannot open photo');
+    try { stream.write(bytes); } finally { stream.close(); }
+    if (scoped) {
+      const complete = new android.content.ContentValues(); complete.put('is_pending', java.lang.Integer.valueOf(0));
+      if (resolver.update(uri, complete, '', []) !== 1) throw Error('Cannot publish photo');
+    }
+    return 'photos';
+  } catch (error) {
+    resolver.delete(uri, '', []);
+    throw error;
+  }
+}

package/bridge/media/save-photo.ios.ts

@@ -0,0 +1,19 @@
+/** Add-only permission is requested on export, never when the application starts. */
+export async function savePhoto(canvas: HTMLCanvasElement, _filename: string): Promise<'photos'> {
+  const status = await new Promise<PHAuthorizationStatus>(resolve =>
+    PHPhotoLibrary.requestAuthorizationForAccessLevelHandler(PHAccessLevel.AddOnly, resolve));
+  if (status !== PHAuthorizationStatus.Authorized && status !== PHAuthorizationStatus.Limited)
+    throw Error('Photo permission denied');
+  const encoded = canvas.toDataURL('image/png').split(',')[1];
+  if (!encoded) throw Error('PNG encoding failed');
+  const data = NSData.alloc().initWithBase64EncodedStringOptions(encoded, NSDataBase64DecodingOptions.IgnoreUnknownCharacters);
+  const image = data && UIImage.imageWithData(data);
+  if (!image) throw Error('Cannot decode photo');
+  await new Promise<void>((resolve, reject) => {
+    PHPhotoLibrary.sharedPhotoLibrary().performChangesCompletionHandler(
+      () => { PHAssetChangeRequest.creationRequestForAssetFromImage(image); },
+      (success, error) => success ? resolve() : reject(Error(error?.localizedDescription ?? 'Cannot save photo')),
+    );
+  });
+  return 'photos';
+}

package/bridge/media/save-photo.ts

@@ -0,0 +1,2 @@
+// NativeScript resolves .android/.ios at bundle time; this entry provides shared types.
+export { savePhoto } from './save-photo.ios';

package/bridge/motion/android-reading.ts

@@ -0,0 +1,19 @@
+import type { MotionReading, MotionVector } from './motion-sample';
+/** Android rotation vectors describe device-to-world rotation; gravity points down, in g. */
+export function androidMotionReading(timestamp: number, vector: readonly number[], rotationRate: MotionVector, acceleration: MotionVector): MotionReading {
+  let [x, y, z, w = Math.sqrt(Math.max(0, 1 - vector[0] ** 2 - vector[1] ** 2 - vector[2] ** 2))] = vector;
+  const length = Math.hypot(x, y, z, w);
+  if (!Number.isFinite(length) || length < 1e-8) throw new RangeError('Invalid Android rotation vector.');
+  x /= length; y /= length; z /= length; w /= length;
+  const gravity = { x: -2 * (x * z - w * y), y: -2 * (y * z + w * x), z: -(1 - 2 * (x * x + y * y)) };
+  return { timestamp, attitude: {
+    pitch: Math.asin(Math.max(-1, Math.min(1, 2 * (w * x - y * z)))),
+    roll: Math.atan2(2 * (w * y + x * z), 1 - 2 * (x * x + y * y)),
+    yaw: Math.atan2(2 * (w * z + x * y), 1 - 2 * (x * x + z * z)),
+    quaternion: { x, y, z, w },
+  }, gravity, rotationRate: { ...rotationRate }, userAcceleration: {
+    x: acceleration.x / 9.80665 + gravity.x,
+    y: acceleration.y / 9.80665 + gravity.y,
+    z: acceleration.z / 9.80665 + gravity.z,
+  } };
+}

package/bridge/motion/device-motion.android.ts

@@ -0,0 +1,109 @@
+import { Application, Utils } from '@nativescript/core';
+import { createMotionSample, validateMotionInterval, validateScreenRotation,
+  type NativeMotionSample, type MotionScreenRotation, type MotionReading, type MotionVector } from './motion-sample';
+import { androidMotionReading } from './android-reading';
+export type { NativeMotionSample, MotionScreenRotation } from './motion-sample';
+export interface NativeDeviceMotionOptions { updateIntervalMs?: number; screenRotation?: MotionScreenRotation }
+let owner: NativeDeviceMotion | null = null;
+/** Sensor callbacks only copy data. Game events are delivered from the existing Engine update. */
+export class NativeDeviceMotion {
+  private readonly manager: android.hardware.SensorManager;
+  private readonly sensors: (android.hardware.Sensor | null)[];
+  private readonly listener: android.hardware.SensorEventListener;
+  private readonly listeners = new Set<(sample: NativeMotionSample) => void>();
+  private interval: number;
+  private rotation: MotionScreenRotation;
+  private requested = false;
+  private running = false;
+  private suspended = false;
+  private disposed = false;
+  private lastTimestamp: number | null = null;
+  private floor = 0;
+  private rate: MotionVector | null = null;
+  private acceleration: MotionVector | null = null;
+  private reading: MotionReading | null = null;
+  private sample: NativeMotionSample | null = null;
+  constructor(options: NativeDeviceMotionOptions = {}) {
+    this.interval = validateMotionInterval(options.updateIntervalMs ?? 1000 / 60);
+    this.rotation = validateScreenRotation(options.screenRotation ?? 0);
+    if (owner) throw new Error('Only one NativeDeviceMotion controller may exist per app.');
+    this.manager = Utils.android.getApplicationContext().getSystemService(android.content.Context.SENSOR_SERVICE) as android.hardware.SensorManager;
+    const S = android.hardware.Sensor;
+    this.sensors = [this.manager.getDefaultSensor(S.TYPE_GAME_ROTATION_VECTOR) ?? this.manager.getDefaultSensor(S.TYPE_ROTATION_VECTOR),
+      this.manager.getDefaultSensor(S.TYPE_GYROSCOPE), this.manager.getDefaultSensor(S.TYPE_ACCELEROMETER)];
+    this.listener = new android.hardware.SensorEventListener({ onAccuracyChanged: () => {}, onSensorChanged: event => {
+      const timestamp = event.timestamp / 1e9;
+      if (!this.running || this.suspended || timestamp <= this.floor) return;
+      const values = event.values;
+      const vector = { x: values[0], y: values[1], z: values[2] };
+      switch (event.sensor.getType()) {
+        case S.TYPE_GYROSCOPE: this.rate = vector; break;
+        case S.TYPE_ACCELEROMETER: this.acceleration = vector; break;
+        default:
+          if (!this.rate || !this.acceleration) return;
+          try { this.reading = androidMotionReading(timestamp, Array.from({length: values.length}, (_, i) => values[i]), this.rate, this.acceleration); }
+          catch { this.reading = null; }
+      }
+    } });
+    owner = this;
+    this.suspended = !!(Application.inBackground || Application.suspended);
+    Application.on(Application.suspendEvent, this.suspend);
+    Application.on(Application.resumeEvent, this.resume);
+    Application.on(Application.exitEvent, this.dispose);
+  }
+  get available(): boolean { return this.sensors.every(Boolean); }
+  get active(): boolean { return this.running; }
+  get latest(): NativeMotionSample | null { return this.sample; }
+  onUpdate(listener: (sample: NativeMotionSample) => void): () => void {
+    this.assertLive(); this.listeners.add(listener); return () => { this.listeners.delete(listener); };
+  }
+  start(): boolean {
+    this.assertLive(); if (!this.available) return false;
+    this.requested = true; if (!this.suspended) this.begin(); return true;
+  }
+  stop(): void { this.requested = false; this.end(); }
+  setUpdateInterval(ms: number): void {
+    this.assertLive(); this.interval = validateMotionInterval(ms);
+    if (this.running) { this.end(); this.begin(); }
+  }
+  setScreenRotation(rotation: MotionScreenRotation): void {
+    this.assertLive(); this.rotation = validateScreenRotation(rotation); this.sample = null;
+  }
+  update(deltaMs: number): NativeMotionSample | null {
+    if (!Number.isFinite(deltaMs) || deltaMs < 0) throw new RangeError('Motion deltaMs must be finite and non-negative.');
+    if (this.disposed || !this.running || this.suspended) return null;
+    const reading = this.reading;
+    if (!reading || (this.lastTimestamp !== null && reading.timestamp <= this.lastTimestamp)) return null;
+    const sample = createMotionSample(reading, deltaMs, this.lastTimestamp === null ? 0 : (reading.timestamp - this.lastTimestamp) * 1000, this.rotation);
+    this.lastTimestamp = reading.timestamp; this.sample = sample;
+    for (const listener of [...this.listeners]) {
+      if (!this.running || this.disposed) break;
+      if (this.listeners.has(listener)) listener(sample);
+    }
+    return sample;
+  }
+  readonly suspend = (): void => { this.suspended = true; this.end(); };
+  readonly resume = (): void => { if (!this.disposed) { this.suspended = false; if (this.requested) this.begin(); } };
+  readonly dispose = (): void => {
+    if (this.disposed) return;
+    this.stop(); this.disposed = true; this.listeners.clear();
+    Application.off(Application.suspendEvent, this.suspend);
+    Application.off(Application.resumeEvent, this.resume);
+    Application.off(Application.exitEvent, this.dispose);
+    if (owner === this) owner = null;
+  };
+  private begin(): void {
+    if (this.running) return;
+    this.floor = android.os.SystemClock.elapsedRealtimeNanos() / 1e9;
+    this.running = true;
+    try {
+      for (const sensor of this.sensors) if (!sensor || !this.manager.registerListener(this.listener, sensor, Math.round(this.interval * 1000)))
+        throw new Error('Android motion sensor registration failed.');
+    } catch (error) { this.requested = false; this.end(); throw error; }
+  }
+  private end(): void {
+    if (this.running) this.manager.unregisterListener(this.listener);
+    this.running = false; this.lastTimestamp = null; this.sample = null; this.reading = null; this.rate = null; this.acceleration = null;
+  }
+  private assertLive(): void { if (this.disposed) throw new Error('NativeDeviceMotion is disposed.'); }
+}