@haiyue/native 0.1.0

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

@@ -0,0 +1,121 @@
+import { Application } from '@nativescript/core';
+import { createMotionSample, validateMotionInterval, validateScreenRotation,
+  type NativeMotionSample, type MotionScreenRotation, type MotionReading } from './motion-sample';
+export type { NativeMotionSample, MotionScreenRotation } from './motion-sample';
+// NativeScript's default iOS typings omit CoreMotion. Keep this binding limited to the public SDK methods used here.
+interface CoreMotionManager {
+  readonly gyroAvailable: boolean;
+  readonly deviceMotionAvailable: boolean;
+  readonly deviceMotionActive: boolean;
+  readonly deviceMotion: MotionReading | null;
+  deviceMotionUpdateInterval: number;
+  startDeviceMotionUpdatesUsingReferenceFrame(frame: number): void;
+  stopDeviceMotionUpdates(): void;
+}
+declare const CMMotionManager: {
+  alloc(): { init(): CoreMotionManager };
+  availableAttitudeReferenceFrames(): number;
+};
+const X_ARBITRARY_Z_VERTICAL = 1; // CMAttitudeReferenceFrameXArbitraryZVertical in CoreMotion.framework.
+export interface NativeDeviceMotionOptions {
+  /** Requested sensor interval, 5–1000 ms. Actual hardware rate may differ. */
+  updateIntervalMs?: number;
+  screenRotation?: MotionScreenRotation;
+}
+let manager: CoreMotionManager | null = null;
+let owner: NativeDeviceMotion | null = null;
+/** One app-owned controller; poll from the existing Engine frame, never add another frame loop. */
+export class NativeDeviceMotion {
+  private readonly motion: CoreMotionManager;
+  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 timestampFloor = -Infinity;
+  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.');
+    if (typeof CMMotionManager === 'undefined') throw new Error('Core Motion is unavailable on this platform.');
+    manager ??= CMMotionManager.alloc().init();
+    this.motion = manager; 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.motion.gyroAvailable && this.motion.deviceMotionAvailable; }
+  get active(): boolean { return this.running && this.motion.deviceMotionActive; }
+  get latest(): NativeMotionSample | null { return this.sample; }
+  onUpdate(listener: (sample: NativeMotionSample) => void): () => void {
+    this.assertLive(); this.listeners.add(listener);
+    return () => { this.listeners.delete(listener); };
+  }
+  /** False means the physical gyro/device-motion service is unavailable (e.g. simulator). */
+  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.motion.deviceMotionUpdateInterval = this.interval / 1000;
+  }
+  setScreenRotation(rotation: MotionScreenRotation): void {
+    this.assertLive(); this.rotation = validateScreenRotation(rotation);
+    this.sample = null;
+  }
+  /** Call once per Engine update. No event is emitted until a new sensor timestamp arrives. */
+  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.motion.deviceMotion;
+    if (!reading || reading.timestamp <= this.timestampFloor || (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) return;
+    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.timestampFloor = this.motion.deviceMotion?.timestamp ?? -Infinity;
+    try {
+      if (!(CMMotionManager.availableAttitudeReferenceFrames() & X_ARBITRARY_Z_VERTICAL))
+        throw new Error('The gravity-aligned attitude reference frame is unavailable.');
+      this.motion.deviceMotionUpdateInterval = this.interval / 1000;
+      this.motion.startDeviceMotionUpdatesUsingReferenceFrame(X_ARBITRARY_Z_VERTICAL);
+    } catch (error) { this.requested = false; this.motion.stopDeviceMotionUpdates(); this.end(); throw error; }
+    this.running = true;
+  }
+  private end(): void {
+    if (this.running) this.motion.stopDeviceMotionUpdates();
+    this.running = false; this.lastTimestamp = null; this.sample = null;
+  }
+  private assertLive(): void { if (this.disposed) throw new Error('NativeDeviceMotion is disposed.'); }
+}

package/bridge/motion/device-motion.ts

@@ -0,0 +1,2 @@
+// NativeScript resolves .android/.ios; this fallback supplies the common TypeScript API.
+export * from './device-motion.ios';

package/bridge/motion/motion-sample.ts

@@ -0,0 +1,62 @@
+export interface MotionVector { readonly x: number; readonly y: number; readonly z: number }
+export interface MotionAngles { readonly pitch: number; readonly roll: number; readonly yaw: number }
+export interface MotionQuaternion extends MotionVector { readonly w: number }
+/** Screen rotation from the device's reference axes (iOS portrait; Android natural orientation). */
+export type MotionScreenRotation = 0 | 90 | 180 | 270;
+export interface MotionReading {
+  readonly timestamp: number;
+  readonly attitude: MotionAngles & { readonly quaternion: MotionQuaternion };
+  readonly rotationRate: MotionVector;
+  readonly gravity: MotionVector;
+  readonly userAcceleration: MotionVector;
+}
+export interface NativeMotionSample {
+  readonly timestampMs: number;
+  readonly deltaMs: number;
+  readonly sensorDeltaMs: number;
+  readonly angles: MotionAngles;
+  readonly radians: MotionAngles;
+  readonly quaternion: MotionQuaternion;
+  /** Device axes, radians/second. */
+  readonly rotationRate: MotionVector;
+  /** Device axes, units of g. */
+  readonly gravity: MotionVector;
+  readonly userAcceleration: MotionVector;
+  readonly screenRotation: MotionScreenRotation;
+  /** Degrees: positive right/forward means the screen's right/top edge is lower. */
+  readonly tilt: { readonly right: number; readonly forward: number; readonly total: number };
+}
+const DEGREES = 180 / Math.PI;
+export function validateMotionInterval(ms: number): number {
+  if (!Number.isFinite(ms) || ms < 5 || ms > 1000) throw new RangeError('Motion updateIntervalMs must be between 5 and 1000.');
+  return ms;
+}
+export function validateScreenRotation(rotation: number): MotionScreenRotation {
+  if (![0, 90, 180, 270].includes(rotation)) throw new RangeError('Motion screenRotation must be 0, 90, 180 or 270.');
+  return rotation as MotionScreenRotation;
+}
+/** Copy native structs; snapshots never retain mutable native sensor objects. */
+export function createMotionSample(raw: MotionReading, deltaMs: number, sensorDeltaMs: number, rotation: MotionScreenRotation): NativeMotionSample {
+  validateScreenRotation(rotation);
+  const vector = (v: MotionVector) => Object.freeze({ x: v.x, y: v.y, z: v.z });
+  const { pitch, roll, yaw, quaternion: q } = raw.attitude;
+  const gravity = vector(raw.gravity), rate = vector(raw.rotationRate), acceleration = vector(raw.userAcceleration);
+  const quaternion = Object.freeze({ x: q.x, y: q.y, z: q.z, w: q.w });
+  const numbers = [raw.timestamp, deltaMs, sensorDeltaMs, pitch, roll, yaw, ...Object.values(quaternion),
+    ...Object.values(gravity), ...Object.values(rate), ...Object.values(acceleration)];
+  if (numbers.some(n => !Number.isFinite(n)) || raw.timestamp < 0 || deltaMs < 0 || sensorDeltaMs < 0)
+    throw new RangeError('Motion samples must contain finite values and non-negative times.');
+  const length = Math.hypot(gravity.x, gravity.y, gravity.z);
+  if (length < 1e-8) throw new RangeError('Motion gravity vector is unavailable.');
+  const theta = rotation / DEGREES, c = Math.cos(theta), s = Math.sin(theta);
+  const x = c * gravity.x - s * gravity.y, y = s * gravity.x + c * gravity.y;
+  return Object.freeze({ timestampMs: raw.timestamp * 1000, deltaMs, sensorDeltaMs,
+    angles: Object.freeze({ pitch: pitch * DEGREES, roll: roll * DEGREES, yaw: yaw * DEGREES }),
+    radians: Object.freeze({ pitch, roll, yaw }), quaternion, rotationRate: rate, gravity, userAcceleration: acceleration,
+    screenRotation: rotation, tilt: Object.freeze({
+      right: Math.atan2(x, Math.hypot(y, gravity.z)) * DEGREES,
+      forward: Math.atan2(y, Math.hypot(x, gravity.z)) * DEGREES,
+      total: Math.acos(Math.max(-1, Math.min(1, -gravity.z / length))) * DEGREES,
+    }),
+  });
+}

package/bridge/render/canvas-textures.ios.ts

@@ -0,0 +1,45 @@
+import { Canvas } from '@nativescript/canvas';
+/** Canvas 2D rasterization with explicit RGBA upload; game rendering remains WebGPU. */
+export class NativeCanvasTextures {
+  private readonly textures = new Map<string, { texture: GPUTexture; width: number; height: number }>();
+  private canvasCreations = 0;
+  private uploads = 0;
+  constructor(private readonly device: GPUDevice, private readonly format: 'rgba8unorm' | 'rgba8unorm-srgb' = 'rgba8unorm') {}
+  readonly createCanvas2D = (width: number, height: number): HTMLCanvasElement => {
+    const canvas = new Canvas();
+    this.canvasCreations++;
+    canvas.width = width;
+    canvas.height = height;
+    // These offscreen canvases are always read back immediately for a WebGPU
+    // upload. CPU rasterization avoids Android GL readback artifacts and prevents
+    // transient iOS text/hint canvases from accumulating heavyweight Metal contexts.
+    canvas.getContext('2d', { willReadFrequently: true })?.clearRect(0, 0, width, height);
+    return canvas as unknown as HTMLCanvasElement;
+  };
+  readonly readAtlasPixels = (canvas: HTMLCanvasElement): Uint8Array => {
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('Native Canvas 2D context is unavailable.');
+    const pixels = context.getImageData(0, 0, canvas.width, canvas.height).data;
+    return new Uint8Array(pixels.buffer, pixels.byteOffset, pixels.byteLength);
+  };
+  readonly textureFromCanvas = (canvas: HTMLCanvasElement, key: string): GPUTexture => {
+    const { width, height } = canvas;
+    const context = canvas.getContext('2d');
+    if (!context) throw new Error('Native Canvas 2D context is unavailable.');
+    const pixels = context.getImageData(0, 0, width, height).data;
+    let entry = this.textures.get(key);
+    if (!entry || entry.width !== width || entry.height !== height) {
+      if (entry) {
+        const old = entry.texture;
+        void this.device.queue.onSubmittedWorkDone().then(() => old.destroy());
+      }
+      entry = { width, height, texture: this.device.createTexture({ label: `native-game:${key}`, size: [width, height], format: this.format, usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST }) };
+      this.textures.set(key, entry);
+    }
+    this.device.queue.writeTexture({ texture: entry.texture }, new Uint8Array(pixels.buffer, pixels.byteOffset, pixels.byteLength), { bytesPerRow: width * 4 }, [width, height]);
+    this.uploads++;
+    return entry.texture;
+  };
+  snapshot() { return { canvasesCreated: this.canvasCreations, uploads: this.uploads, textures: this.textures.size, bytes: [...this.textures.values()].reduce((sum, item) => sum + item.width * item.height * 4, 0) }; }
+  dispose(): void { for (const item of this.textures.values()) item.texture.destroy(); this.textures.clear(); }
+}

package/bridge/render/canvas-textures.ts

@@ -0,0 +1,2 @@
+// The Canvas implementation handles both Metal and Vulkan.
+export * from './canvas-textures.ios';

package/bridge/render/device-descriptor.ts

@@ -0,0 +1,8 @@
+/** Canvas mutates its input descriptor; never pass Engine's frozen values through. */
+export function copyDeviceDescriptor(descriptor?: GPUDeviceDescriptor): GPUDeviceDescriptor & { requiredFeatures: GPUFeatureName[] } {
+  return {
+    ...descriptor,
+    requiredFeatures: Array.from(descriptor?.requiredFeatures ?? []),
+    ...(descriptor?.requiredLimits ? { requiredLimits: { ...descriptor.requiredLimits } } : {}),
+  };
+}

package/bridge/render/frame-capture.android.ts

@@ -0,0 +1,12 @@
+import { knownFolders, path } from '@nativescript/core';
+import type { Canvas } from '@nativescript/canvas';
+import { nativeLaunchFlag } from '../lifecycle/launch-flags';
+export function isFrameCaptureRequested(): boolean { return nativeLaunchFlag('G02_CAPTURE_FRAME'); }
+export function captureSurfaceFrame(view: Canvas, file = 'g02-clear-frame.png'): { file: string; bytes: number } {
+  const url: unknown = view.toDataURL('image/png'), prefix = 'data:image/png;base64,';
+  if (typeof url !== 'string' || !url.startsWith(prefix)) throw new Error('Native WebGPU PNG readback returned no PNG.');
+  const bytes = android.util.Base64.decode(url.slice(prefix.length), android.util.Base64.DEFAULT);
+  const stream = new java.io.FileOutputStream(path.join(knownFolders.documents().path, file));
+  try { stream.write(bytes); } finally { stream.close(); }
+  return { file, bytes: bytes.length };
+}

package/bridge/render/frame-capture.ios.ts

@@ -0,0 +1,20 @@
+import { File, knownFolders, path } from '@nativescript/core';
+import type { Canvas } from '@nativescript/canvas';
+
+/** Opt-in device validation; normal launches do not capture or write images. */
+export function isFrameCaptureRequested(): boolean {
+  return NSProcessInfo.processInfo.environment.objectForKey('G02_CAPTURE_FRAME') === '1';
+}
+
+export function captureSurfaceFrame(view: Canvas, file = 'g02-clear-frame.png'): { file: string; bytes: number } {
+  // Canvas routes this to its native WebGPU readback, while the submitted
+  // current texture is still acquired and before present releases its handle.
+  const url: unknown = view.toDataURL('image/png');
+  const prefix = 'data:image/png;base64,';
+  if (typeof url !== 'string' || !url.startsWith(prefix)) throw new Error('Native WebGPU PNG readback returned no PNG.');
+  // Foundation's zero option means strict decoding; the generated enum omits it.
+  const data = NSData.alloc().initWithBase64EncodedStringOptions(url.slice(prefix.length), 0 as NSDataBase64DecodingOptions);
+  if (!data?.length) throw new Error('Native WebGPU PNG readback is empty.');
+  File.fromPath(path.join(knownFolders.documents().path, file)).writeSync(data, error => { throw error; });
+  return { file, bytes: data.length };
+}

package/bridge/render/frame-capture.ts

@@ -0,0 +1,2 @@
+// TypeScript fallback; NativeScript resolves the platform suffix at bundle time.
+export * from './frame-capture.ios';

package/bridge/render/queue-fence.android.ts

@@ -0,0 +1,39 @@
+/** Canvas 2.1.18's Android onSubmittedWorkDone callback crashes in JNI.
+ * A mapped readback after a queue submission supplies a real completion fence.
+ * Calls in the same JS turn share a fence; completed buffers are reused.
+ */
+export function installQueueFence(device: GPUDevice): void {
+  const queue = device.queue;
+  const idle: GPUBuffer[] = [];
+  let scheduled: Promise<undefined> | null = null;
+  let destroyed = false;
+  const destroy = device.destroy.bind(device);
+  device.destroy = () => {
+    destroyed = true;
+    for (const buffer of idle) buffer.destroy();
+    idle.length = 0;
+    destroy();
+  };
+  queue.onSubmittedWorkDone = () => {
+    if (scheduled) return scheduled;
+    scheduled = Promise.resolve().then(async () => {
+      scheduled = null;
+      if (destroyed) throw new Error('GPU device is destroyed.');
+      const buffer = idle.pop() ?? device.createBuffer({ label: 'android-queue-fence', size: 4, usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST });
+      let reusable = false;
+      try {
+        const encoder = device.createCommandEncoder({ label: 'android-queue-fence' });
+        encoder.clearBuffer(buffer, 0, 4);
+        queue.submit([encoder.finish()]);
+        await buffer.mapAsync(GPUMapMode.READ, 0, 4);
+        buffer.unmap();
+        reusable = true;
+      } finally {
+        if (reusable && !destroyed && idle.length < 3) idle.push(buffer);
+        else buffer.destroy();
+      }
+      return undefined;
+    });
+    return scheduled;
+  };
+}

package/bridge/render/queue-fence.ts

@@ -0,0 +1 @@
+export function installQueueFence(_device: GPUDevice): void {}

package/bridge/render/surface.ts

@@ -0,0 +1,153 @@
+import { Screen, isAndroid } from '@nativescript/core';
+import { Canvas, GPU, GPUAdapter, GPUCanvasContext } from '@nativescript/canvas';
+import type { HaiyueEngine } from '@haiyue/engine';
+import { nativeViewRect, nativeViewSize } from './view-rect';
+import { copyDeviceDescriptor } from './device-descriptor';
+import { installNativeWebGpuConstants } from './webgpu-constants';
+import { installQueueFence } from './queue-fence';
+
+type EngineOptions = ConstructorParameters<typeof HaiyueEngine>[0];
+export type NativeCanvasInput = Pick<HTMLCanvasElement, 'addEventListener' | 'removeEventListener' | 'setPointerCapture' | 'releasePointerCapture'>;
+
+/** Only a missing swapchain image is retryable; validation/device errors are not. */
+export class NativeSurfaceUnavailableError extends Error {
+  constructor() { super('Native surface returned an empty current texture.'); this.name = 'NativeSurfaceUnavailableError'; }
+}
+
+export class NativeSurface {
+  readonly pixelRatio = Math.min(Screen.mainScreen.scale, 2);
+  readonly gpu = new GPU();
+  private adapter: GPUAdapter | null = null;
+  private context: GPUCanvasContext | null = null;
+  private acquired: GPUTexture | null = null;
+  private configuration: GPUCanvasConfiguration | null = null;
+  private measuredSize: ReturnType<typeof nativeViewSize> | null = null;
+  presentedFrames = 0;
+
+  constructor(readonly view: Canvas, private readonly report: (event: string, detail: unknown) => void, private readonly input?: NativeCanvasInput) {
+    // Canvas.getContext('webgpu') uses this entry point internally, even when
+    // Engine receives its own injected provider. Use the same native GPU.
+    installNativeWebGpuConstants();
+    const navigatorObject = globalThis.navigator ?? {};
+    if (!globalThis.navigator) Object.defineProperty(globalThis, 'navigator', { value: navigatorObject, configurable: true });
+    Object.defineProperty(navigatorObject, 'gpu', { value: this.gpu, configurable: true });
+  }
+
+  readonly provider = {
+    requestAdapter: async (options?: GPURequestAdapterOptions) => {
+      if (options?.featureLevel && options.featureLevel !== 'core' && options.featureLevel !== 'compatibility') {
+        throw new Error(`Unsupported WebGPU feature level: ${options.featureLevel}`);
+      }
+      this.adapter = await this.gpu.requestAdapter({ powerPreference: options?.powerPreference, isFallbackAdapter: options?.forceFallbackAdapter, featureLevel: options?.featureLevel as 'core' | 'compatibility' | undefined });
+      if (!this.adapter) throw new Error('Native WebGPU returned no adapter.');
+      const info = await this.adapter.requestAdapterInfo();
+      this.report('adapter', { vendor: info?.vendor, architecture: info?.architecture, device: info?.device, description: info?.description, features: [...this.adapter.features] });
+      const adapter = this.adapter;
+      return {
+        features: adapter.features,
+        limits: adapter.limits,
+        isFallbackAdapter: adapter.isFallbackAdapter,
+        requestAdapterInfo: () => adapter.requestAdapterInfo(),
+        requestDevice: async (descriptor?: GPUDeviceDescriptor) => {
+          const device = await adapter.requestDevice(copyDeviceDescriptor(descriptor) as unknown as Parameters<GPUAdapter['requestDevice']>[0]);
+          installQueueFence(device as unknown as GPUDevice);
+          return device;
+        },
+      };
+    },
+    getPreferredCanvasFormat: () => this.gpu.getPreferredCanvasFormat(),
+  };
+
+  get hasLayout(): boolean {
+    // Host calls this on layout and resume, even while rendering is stopped.
+    this.measuredSize = nativeViewSize(this.view);
+    return this.measuredSize.width > 0 && this.measuredSize.height > 0;
+  }
+  private get size() { return this.measuredSize ??= nativeViewSize(this.view); }
+
+  engineOptions(): Pick<EngineOptions, 'canvas' | 'gpu' | 'devicePixelRatio'> {
+    const self = this;
+    const context = {
+      configure(options: GPUCanvasConfiguration): void {
+        const native = self.getContext();
+        if (!self.adapter) throw new Error('Cannot configure surface before adapter acquisition.');
+        const caps = native.getCapabilities(self.adapter);
+        if (!(caps.format as readonly string[]).includes(options.format)) throw new Error(`Surface does not support ${options.format}.`);
+        self.report('surface-configure', { format: options.format, capabilities: caps });
+        native.configure(options as unknown as Parameters<GPUCanvasContext['configure']>[0]);
+        self.configuration = { ...options };
+      },
+      unconfigure(): void { self.release(); },
+      getCurrentTexture(): GPUTexture {
+        return self.acquire();
+      },
+    };
+    const canvas = {
+      focus: () => isAndroid ? (self.view.nativeViewProtected as android.view.View | undefined)?.requestFocus() : (self.view.nativeViewProtected as UIView | undefined)?.becomeFirstResponder(),
+      addEventListener: (...args: Parameters<NativeCanvasInput['addEventListener']>) => self.input?.addEventListener(...args),
+      removeEventListener: (...args: Parameters<NativeCanvasInput['removeEventListener']>) => self.input?.removeEventListener(...args),
+      setPointerCapture: (id: number) => self.input?.setPointerCapture(id),
+      releasePointerCapture: (id: number) => self.input?.releasePointerCapture(id),
+      get width() { return self.view.width; },
+      set width(value: number) { self.view.width = value; },
+      get height() { return self.view.height; },
+      set height(value: number) { self.view.height = value; },
+      get clientWidth() { return self.size.width; },
+      get clientHeight() { return self.size.height; },
+      getBoundingClientRect() { return nativeViewRect(self.view); },
+      getContext(type: string) { return type === 'webgpu' ? context : null; },
+    };
+    // These are the two audited structural boundaries. Engine has a browser
+    // canvas type, but its render path only uses the members supplied above.
+    return { canvas: canvas as unknown as EngineOptions['canvas'], gpu: this.provider as unknown as EngineOptions['gpu'], devicePixelRatio: this.pixelRatio };
+  }
+
+  private acquire(): GPUTexture {
+    if (this.acquired) return this.acquired;
+    const texture = this.getContext().getCurrentTexture();
+    if (!texture) { this.measuredSize = null; throw new NativeSurfaceUnavailableError(); }
+    return this.acquired = texture as unknown as GPUTexture;
+  }
+
+  /** Called before scene update so an unavailable surface cannot advance gameplay. */
+  beginFrame(): void { this.acquire(); }
+
+  /** Rebind the existing device after a native surface recreation or acquisition miss. */
+  reconfigure(): void {
+    this.measuredSize = null;
+    if (this.acquired) throw new Error('Cannot reconfigure an acquired native frame.');
+    if (this.configuration) this.getContext().configure(this.configuration as unknown as Parameters<GPUCanvasContext['configure']>[0]);
+  }
+
+  present(): boolean {
+    // Bound the cache to one frame; hit testing still reads current window coordinates.
+    this.measuredSize = null;
+    if (!this.acquired) return false;
+    this.getContext().presentSurface();
+    this.acquired = null;
+    this.presentedFrames++;
+    return true;
+  }
+
+  /** Finish an interrupted acquired frame before releasing the surface. */
+  release(): void {
+    this.measuredSize = null;
+    try {
+      if (this.acquired) {
+        this.acquired = null;
+        // Canvas releases its per-frame native texture/view handles at present.
+        // An interrupted frame is never counted as a successful Engine frame.
+        this.context?.presentSurface();
+      }
+    } finally {
+      this.configuration = null;
+      this.context?.unconfigure();
+    }
+  }
+
+  private getContext(): GPUCanvasContext {
+    if (!this.context) this.context = this.view.getContext('webgpu');
+    if (!this.context) throw new Error('Native Canvas WebGPU context is unavailable.');
+    return this.context;
+  }
+}

package/bridge/render/view-capture.android.ts

@@ -0,0 +1,11 @@
+import { ImageSource, knownFolders, path, type View } from '@nativescript/core';
+
+export function captureNativeView(view: View, filename: string): void {
+  const native = view.nativeViewProtected as android.view.View;
+  if (!native || native.getWidth() <= 0 || native.getHeight() <= 0) throw new Error('View is not laid out.');
+  const bitmap = android.graphics.Bitmap.createBitmap(native.getWidth(), native.getHeight(), android.graphics.Bitmap.Config.ARGB_8888);
+  try {
+    native.draw(new android.graphics.Canvas(bitmap));
+    if (!new ImageSource(bitmap).saveToFile(path.join(knownFolders.documents().path, filename), 'png')) throw new Error('View capture failed.');
+  } finally { bitmap.recycle(); }
+}

package/bridge/render/view-capture.ios.ts

@@ -0,0 +1,17 @@
+import { File, knownFolders, path, type View } from '@nativescript/core';
+
+/** Diagnostic-only capture of native overlays, which WebGPU readback excludes. */
+export function captureNativeView(view: View, filename: string): void {
+  const native = view.nativeViewProtected as UIView;
+  if (!native || native.bounds.size.width <= 0 || native.bounds.size.height <= 0) throw new Error('View is not laid out.');
+  UIGraphicsBeginImageContextWithOptions(native.bounds.size, false, 2);
+  try {
+    const context = UIGraphicsGetCurrentContext();
+    if (!context) throw new Error('View capture context unavailable.');
+    native.layer.renderInContext(context);
+    const image = UIGraphicsGetImageFromCurrentImageContext();
+    const data = image && UIImagePNGRepresentation(image);
+    if (!data) throw new Error('View capture returned no image.');
+    File.fromPath(path.join(knownFolders.documents().path, filename)).writeSync(data, error => { throw error; });
+  } finally { UIGraphicsEndImageContext(); }
+}

package/bridge/render/view-capture.ts

@@ -0,0 +1 @@
+export * from './view-capture.ios';

package/bridge/render/view-rect.android.ts

@@ -0,0 +1,15 @@
+import { Screen } from '@nativescript/core';
+import type { Canvas } from '@nativescript/canvas';
+/** Drawing and touch bounds share Android density-independent pixels. */
+export function nativeViewSize(view: Canvas) {
+  const native = view.nativeViewProtected as android.view.View | undefined;
+  const scale = Screen.mainScreen.scale;
+  return { width: native ? native.getWidth() / scale : view.clientWidth,
+    height: native ? native.getHeight() / scale : view.clientHeight };
+}
+export function nativeViewRect(view: Canvas) {
+  const origin = view.getLocationInWindow();
+  const x = origin?.x ?? 0, y = origin?.y ?? 0;
+  const { width, height } = nativeViewSize(view);
+  return { x, y, width, height, left: x, top: y, right: x + width, bottom: y + height };
+}

package/bridge/render/view-rect.ios.ts

@@ -0,0 +1,12 @@
+import type { Canvas } from '@nativescript/canvas';
+/** Actual UIKit drawing bounds, which may extend beyond NativeScript's safe-area measurement. */
+export function nativeViewSize(view: Canvas) {
+  const bounds = (view.nativeViewProtected as UIView | undefined)?.bounds;
+  return { width: bounds?.size.width ?? view.clientWidth, height: bounds?.size.height ?? view.clientHeight };
+}
+export function nativeViewRect(view: Canvas) {
+  const origin = view.getLocationInWindow();
+  const x = origin?.x ?? 0, y = origin?.y ?? 0;
+  const { width, height } = nativeViewSize(view);
+  return { x, y, width, height, left: x, top: y, right: x + width, bottom: y + height };
+}

package/bridge/render/view-rect.ts

@@ -0,0 +1,2 @@
+// TypeScript fallback; NativeScript resolves the platform suffix at bundle time.
+export * from './view-rect.ios';

package/bridge/render/webgpu-constants.ts

@@ -0,0 +1,5 @@
+/** Canvas 2.1.x omits GPUColorWrite; expose the standard WebGPU bitmask once. */
+export function installNativeWebGpuConstants(target: object = globalThis): void {
+  if ('GPUColorWrite' in target) return;
+  Object.defineProperty(target, 'GPUColorWrite', { configurable: true, value: Object.freeze({ RED: 1, GREEN: 2, BLUE: 4, ALPHA: 8, ALL: 15 }) });
+}

package/bridge/rewards/admob.ts

@@ -0,0 +1,80 @@
+import { Application, Connectivity, isAndroid, isIOS } from '@nativescript/core';
+import type { RewardGateway, RewardPresentation } from './controller';
+
+declare const HYRewardedAds: { new(): { privacyRequired: boolean; consentRequired: boolean; continuePresentation(ready: boolean): void; performUnitEvents(action: string, unit: string, events: (event: string) => void): void; dispose(): void } };
+declare const org: any;
+/** Platform adapter is lazy: paid users and players who never opt in make no ad requests. */
+export class AdMobRewardGateway implements RewardGateway {
+  private native: any;
+  private disposed = false;
+  private initialization?: Promise<void>;
+  constructor(private readonly config: { iosUnit: string; androidUnit: string; development: boolean }) {}
+  private getNative(): any {
+    return this.native ??= isAndroid ? new org.haiyue.rewards.HYRewardedAds() : new HYRewardedAds();
+  }
+  privacyRequired(): boolean {
+    if (this.disposed) return false;
+    try {
+      const native = this.getNative();
+      return isAndroid ? native.privacyRequired(Application.android.context) : native.privacyRequired;
+    } catch { return false; }
+  }
+  private async call(action: string, earned: () => void, presentation?: RewardPresentation): Promise<void> {
+    if (this.disposed) throw Error('unavailable');
+    if (Connectivity.getConnectionType() === Connectivity.connectionType.none) throw Error('offline');
+    const unit = this.config.development
+      ? (isIOS ? 'ca-app-pub-3940256099942544/1712485313' : 'ca-app-pub-3940256099942544/5224354917')
+      : (isIOS ? this.config.iosUnit : this.config.androidUnit);
+    if (action === 'show' && (!unit || (!this.config.development && unit.includes('3940256099942544')))) throw Error('unavailable');
+    this.getNative();
+    await new Promise<void>((resolve, reject) => {
+      let ended = false, preparing = false;
+      const onEvent = (event: string) => {
+        if (ended) return;
+        if (this.config.development) console.log('[haiyue-rewards]', event);
+        if (event === 'earned') { earned(); return; }
+        if (event === 'presenting') {
+          if (preparing) return;
+          preparing = true;
+          void (async () => {
+            let ready = false;
+            try { ready = presentation ? await presentation.prepare() : true; } catch { /* Tell native to cancel safely. */ }
+            if (!ended) this.native.continuePresentation(ready && !this.disposed);
+          })();
+          return;
+        }
+        if (event === 'presentation-closed') { preparing = false; presentation?.closed(); return; }
+        ended = true;
+        presentation?.closed();
+        if (event === 'closed') resolve(); else reject(Error(event.split(':')[1] || 'unavailable'));
+      };
+      if (isAndroid) {
+        const activity = Application.android.foregroundActivity;
+        if (!activity) { reject(Error('unavailable')); return; }
+        this.native.perform(activity, action, unit, new org.haiyue.rewards.HYRewardedAds.Events({ onEvent }));
+      } else this.native.performUnitEvents(action, unit, onEvent);
+    });
+  }
+  async show(earned: () => void, presentation?: RewardPresentation): Promise<void> {
+    // The native gateway accepts one operation at a time. An explicit request
+    // retries even if the background startup refresh failed.
+    if (this.initialization) await this.initialization.catch(() => {});
+    return this.call('show', earned, presentation);
+  }
+  /** Update consent once per host session, without initializing or preloading ads. */
+  initialize(presentForm: boolean, beforePresent: () => Promise<boolean>): Promise<void> {
+    if (!isIOS) return Promise.resolve();
+    return this.initialization ??= this.initializeConsent(presentForm, beforePresent);
+  }
+  private async initializeConsent(presentForm: boolean, beforePresent: () => Promise<boolean>): Promise<void> {
+    await this.call('refreshPrivacy', () => {});
+    if (!this.disposed && presentForm && this.getNative().consentRequired) {
+      await this.call('presentConsent', () => {}, { prepare: beforePresent, closed() {} });
+    }
+  }
+  async privacy(presentation?: RewardPresentation): Promise<void> {
+    if (this.initialization) await this.initialization.catch(() => {});
+    return this.call('privacy', () => {}, presentation);
+  }
+  dispose(): void { this.disposed = true; this.native?.dispose(); }
+}