akanjs 3.0.0-beta.9 → 3.0.1

package/vendor/@akanjs/native/plugins/screen/src/desktop.ts

@@ -0,0 +1,50 @@
+
+
+import { defineDesktopPlugin } from "../../../packages/desktop/src/plugin.ts";
+import type { Display, ScreenApi, ScreenEvents } from "./index.ts";
+import { sameDisplays } from "./web.ts";
+
+export default defineDesktopPlugin<ScreenApi, ScreenEvents>({
+  id: "screen",
+  methods: {
+    getDisplays: (_args, ctx) => ctx.shell("screen.displays") as Promise<Display[]>,
+    getCursorPoint: (_args, ctx) => ctx.shell("screen.cursor") as Promise<{ x: number; y: number }>,
+  },
+  events: {
+    change(emit, ctx) {
+      let active = true;
+      let last: Display[] | null = null;
+      let reading = false;
+      let again = false;
+      
+      const refresh = async () => {
+        if (reading) {
+          again = true;
+          return;
+        }
+        reading = true;
+        try {
+          do {
+            again = false;
+            const displays = (await ctx.shell("screen.displays")) as Display[];
+            if (!active) return;
+            if (last && !sameDisplays(last, displays)) emit({ displays });
+            last = displays;
+          } while (again && active);
+        } catch (error) {
+          console.warn("[akan-native] screen: reading the displays failed", error);
+        } finally {
+          reading = false;
+        }
+      };
+      const stop = ctx.onNativeEvent("screen", () => void refresh());
+      ctx
+        .shell("screen.watch")
+        .then(refresh, (error) => console.warn("[akan-native] screen: cannot watch display changes", error));
+      return () => {
+        active = false;
+        stop();
+      };
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/screen/src/index.ts

@@ -0,0 +1,107 @@
+import { createLiveValue, definePlugin } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import { readWebDisplays, sameDisplays, web } from "./web.ts";
+
+export { sameDisplays } from "./web.ts";
+
+/**
+ * Displays and the mouse cursor (plugins.md §5).
+ *
+ * Coordinates are logical pixels (CSS px) with the origin at the top-left corner of the primary
+ * display (the one with the menu bar) and y growing down: the same space as the window plugin's
+ * positions (`appWindow.setPosition`, `getState().x/y`), so a window can be placed on a display
+ * with `setPosition({ x: d.workArea.x + 20, y: d.workArea.y + 20 })`. Displays above or left of
+ * the primary one have negative coordinates.
+ *
+ * - macOS: TAO monitors; `workArea` leaves out the menu bar and the Dock (NSScreen visibleFrame).
+ *   `change` fires when a display is added, removed or rearranged, or its resolution or scale
+ *   changes. Showing or hiding the Dock may not send it; call getDisplays() again before placing
+ *   a window if that matters.
+ * - Web: one display, the screen the page is on, from `window.screen` (bounds at 0,0; workArea
+ *   from availLeft/availTop/availWidth/availHeight). `scale` is devicePixelRatio, which includes
+ *   the page zoom. getCursorPoint is UNSUPPORTED: a page only sees the mouse over itself.
+ * - Windows: TAO monitors; `workArea` leaves out the taskbar (GetMonitorInfo). `change` fires for
+ *   display and work area changes.
+ * - Linux: GDK monitors, in the space of the X screen (or the Wayland compositor), whose origin
+ *   is the top-left corner of the whole desktop, not always the primary display's. `workArea`
+ *   comes from the window manager and is exact for the primary display only. `change` fires when
+ *   a display is added, removed or resized, not for work area changes. getCursorPoint is
+ *   UNSUPPORTED on Wayland, which tells an app where the pointer is only over its own windows.
+ * - iOS and Android: UNSUPPORTED.
+ */
+export interface ScreenRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface Display {
+  /** Stable while the display stays connected (macOS: CGDirectDisplayID). 0 on the web. */
+  id: number;
+  /** As the OS shows it, e.g. "Built-in Retina Display". "" on the web. */
+  name: string;
+  bounds: ScreenRect;
+  /** Where windows can go: bounds without the menu bar, Dock or taskbar. */
+  workArea: ScreenRect;
+  /** Device pixels per CSS pixel (2 on Retina displays). */
+  scale: number;
+  primary: boolean;
+}
+
+export interface ScreenApi {
+  /** The primary display first. */
+  getDisplays(): Promise<Display[]>;
+  /** Where the mouse pointer is, anywhere on the desktop (it may be over another app). */
+  getCursorPoint(): Promise<{ x: number; y: number }>;
+}
+
+export interface ScreenEvents {
+  /** The displays changed; sent only when getDisplays() would answer differently. */
+  change: { displays: Display[] };
+}
+
+export const screen = definePlugin<ScreenApi, ScreenEvents>("screen", {
+  methods: ["getDisplays", "getCursorPoint"],
+  events: ["change"],
+  web,
+});
+
+const current = createLiveValue<Display[]>(
+  readWebDisplays(),
+  (set) => {
+    let live = true;
+    const stop = screen.listen("change", (e) => set(e.displays));
+    screen
+      .getDisplays()
+      .then((displays) => live && set(displays))
+      .catch(() => {});
+    return () => {
+      live = false;
+      stop();
+    };
+  },
+  sameDisplays,
+);
+
+/**
+ * The connected displays, primary first. Re-renders when they change. Before the first answer
+ * (and where the plugin is unsupported) it holds the web view of the page's own screen, or [].
+ */
+export function useDisplays(): Display[] {
+  return useLiveValue(current);
+}
+
+/** The display that contains the point (e.g. getCursorPoint()), else the nearest one. */
+export function displayAt(point: { x: number; y: number }, displays: Display[]): Display | undefined {
+  let best: Display | undefined;
+  let bestDistance = Infinity;
+  for (const d of displays) {
+    const { x, y, width, height } = d.bounds;
+    const dx = Math.max(x - point.x, 0, point.x - (x + width));
+    const dy = Math.max(y - point.y, 0, point.y - (y + height));
+    const distance = dx * dx + dy * dy;
+    if (distance < bestDistance) [best, bestDistance] = [d, distance];
+  }
+  return best;
+}

package/vendor/@akanjs/native/plugins/screen/src/web.ts

@@ -0,0 +1,92 @@
+import { defineWebPlugin } from "../../../packages/core/src/index.ts";
+import type { Display, ScreenApi, ScreenEvents, ScreenRect } from "./index.ts";
+
+/** The parts of `window.screen` this reads (availLeft/availTop/left/top are non-standard). */
+export interface ScreenLike {
+  width: number;
+  height: number;
+  availWidth?: number;
+  availHeight?: number;
+  availLeft?: number;
+  availTop?: number;
+  left?: number;
+  top?: number;
+}
+
+export function webDisplay(s: ScreenLike, devicePixelRatio: number): Display {
+  const { width, height } = s;
+  const availWidth = s.availWidth ?? width;
+  const availHeight = s.availHeight ?? height;
+  let x = 0;
+  let y = 0;
+  if (typeof s.availLeft === "number" && typeof s.availTop === "number") {
+    if (typeof s.left === "number" && typeof s.top === "number") {
+      [x, y] = [s.availLeft - s.left, s.availTop - s.top];
+    } else if (
+      s.availLeft >= 0 &&
+      s.availTop >= 0 &&
+      s.availLeft + availWidth <= width &&
+      s.availTop + availHeight <= height
+    ) {
+      [x, y] = [s.availLeft, s.availTop];
+    }
+  }
+  const bounds: ScreenRect = { x: 0, y: 0, width, height };
+  return {
+    id: 0,
+    name: "",
+    bounds,
+    workArea: { x, y, width: availWidth, height: availHeight },
+    scale: devicePixelRatio > 0 ? devicePixelRatio : 1,
+    primary: true,
+  };
+}
+
+/** [] where there is no DOM (tests, the desktop plugin host). */
+export function readWebDisplays(): Display[] {
+  if (typeof window === "undefined" || !window.screen) return [];
+  return [webDisplay(window.screen as ScreenLike, window.devicePixelRatio)];
+}
+
+/** Displays are plain JSON; two lists are the same when they serialize the same. */
+export function sameDisplays(a: Display[], b: Display[]): boolean {
+  return a === b || JSON.stringify(a) === JSON.stringify(b);
+}
+
+export const web = defineWebPlugin<ScreenApi, ScreenEvents>({
+  methods: {
+    getDisplays: async () => readWebDisplays(),
+  },
+  events: {
+    change(emit) {
+      let last = readWebDisplays();
+      const check = () => {
+        const next = readWebDisplays();
+        if (sameDisplays(last, next)) return;
+        last = next;
+        emit({ displays: next });
+      };
+      
+      let query: MediaQueryList | null = null;
+      const watchScale = () => {
+        query?.removeEventListener("change", onScale);
+        query = window.matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+        query.addEventListener("change", onScale);
+      };
+      const onScale = () => {
+        watchScale();
+        check();
+      };
+      watchScale();
+      window.addEventListener("resize", check);
+      
+      const target = window.screen as unknown as Partial<EventTarget>;
+      target.addEventListener?.("change", check);
+      return () => {
+        query?.removeEventListener("change", onScale);
+        window.removeEventListener("resize", check);
+        target.removeEventListener?.("change", check);
+      };
+    },
+  },
+});

package/vendor/@akanjs/native/plugins/screen-orientation/android/ScreenOrientationPlugin.kt

@@ -0,0 +1,113 @@
+package com.akanjs.plugins.screenorientation
+
+import android.content.pm.ActivityInfo
+import android.hardware.display.DisplayManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import android.view.Surface
+import com.akanjs.runtime.AkanNativeCompat
+import com.akanjs.runtime.AkanNativeErrorCode
+import com.akanjs.runtime.AkanNativePluginContext
+import com.akanjs.runtime.AkanNativeReply
+import com.akanjs.runtime.AkanNativeVoidReply
+
+/**
+ * Activity.requestedOrientation for locks, the display rotation for the type.
+ * - Changes come from DisplayManager.DisplayListener: onConfigurationChanged misses 180° turns
+ *   (the configuration's orientation stays "landscape"), which is what capacitor-plugins/screen-orientation
+ *   ScreenOrientationPlugin.java:45-51 compares, so it never reports them.
+ * - The type depends on the display's natural orientation, as Surface rotations count from it:
+ *   phones are naturally portrait (ROTATION_90 = landscape-primary, ScreenOrientation.java:45-56),
+ *   many tablets landscape. The mapping follows what the system picks for the matching
+ *   SCREEN_ORIENTATION_* lock (DisplayRotation: portrait on a landscape device is ROTATION_270),
+ *   so lock("portrait-primary") then get() gives "portrait-primary" on both.
+ * - "portrait", "landscape" and "any" use the USER_* variants: either way up by the sensor, but the
+ *   user's rotation lock still wins, like everywhere else in the system.
+ * - Android 16 (API 36) ignores orientation requests on displays 600 dp and wider for apps targeting
+ *   it; lock() rejects UNSUPPORTED there instead of pretending (plugins.md §4.1).
+ * Arguments arrive decoded and checked by the generated ScreenOrientationPluginSpec (PL-10).
+ */
+class ScreenOrientationPlugin(private val context: AkanNativePluginContext) : ScreenOrientationPluginSpec {
+    private val displays: DisplayManager? = context.activity.getSystemService(DisplayManager::class.java)
+    private val main = Handler(Looper.getMainLooper())
+    private val events = ScreenOrientationEvents(context)
+    private var listener: DisplayManager.DisplayListener? = null
+    private var last: ScreenOrientationOrientationType? = null
+
+    override fun get(reply: AkanNativeReply<ScreenOrientationOrientationState>) = reply.resolve(ScreenOrientationOrientationState(type = type()))
+
+    override fun lock(args: ScreenOrientationLockArgs, reply: AkanNativeVoidReply) {
+        val activity = context.activity
+        val requested = when (args.orientation) {
+            ScreenOrientationOrientationLock.ANY -> ActivityInfo.SCREEN_ORIENTATION_FULL_USER
+            ScreenOrientationOrientationLock.PORTRAIT -> ActivityInfo.SCREEN_ORIENTATION_USER_PORTRAIT
+            ScreenOrientationOrientationLock.LANDSCAPE -> ActivityInfo.SCREEN_ORIENTATION_USER_LANDSCAPE
+            ScreenOrientationOrientationLock.PORTRAIT_PRIMARY -> ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
+            ScreenOrientationOrientationLock.PORTRAIT_SECONDARY -> ActivityInfo.SCREEN_ORIENTATION_REVERSE_PORTRAIT
+            ScreenOrientationOrientationLock.LANDSCAPE_PRIMARY -> ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE
+            ScreenOrientationOrientationLock.LANDSCAPE_SECONDARY -> ActivityInfo.SCREEN_ORIENTATION_REVERSE_LANDSCAPE
+        }
+        if (Build.VERSION.SDK_INT >= 36 && activity.resources.configuration.smallestScreenWidthDp >= 600) {
+            return reply.reject(AkanNativeErrorCode.UNSUPPORTED, "Android ignores orientation locks on screens 600 dp and wider")
+        }
+        activity.requestedOrientation = requested
+        reply.resolve()
+    }
+
+    override fun unlock(reply: AkanNativeVoidReply) {
+        context.activity.requestedOrientation = ActivityInfo.SCREEN_ORIENTATION_UNSPECIFIED
+        reply.resolve()
+    }
+
+    override fun startListening(event: String) {
+        val dm = displays
+        if (event != "change" || listener != null || dm == null) return
+        last = type()
+        val l = object : DisplayManager.DisplayListener {
+            override fun onDisplayChanged(displayId: Int) {
+                if (displayId != AkanNativeCompat.display(context.activity)?.displayId) return
+                val next = type()
+                if (next == last) return // also brightness and refresh rate changes land here
+                last = next
+                events.change(ScreenOrientationOrientationState(type = next))
+            }
+
+            override fun onDisplayAdded(displayId: Int) {}
+            override fun onDisplayRemoved(displayId: Int) {}
+        }
+        dm.registerDisplayListener(l, main)
+        listener = l
+    }
+
+    override fun stopListening(event: String) {
+        if (event != "change") return
+        listener?.let { displays?.unregisterDisplayListener(it) }
+        listener = null
+        last = null
+    }
+
+    override fun destroy() = stopListening("change")
+
+    private fun type(): ScreenOrientationOrientationType {
+        val display = AkanNativeCompat.display(context.activity) ?: return ScreenOrientationOrientationType.PORTRAIT_PRIMARY
+        val rotation = display.rotation
+        // Mode sizes are in the natural orientation, whatever the current rotation is.
+        val naturalPortrait = display.mode.physicalWidth <= display.mode.physicalHeight
+        return if (naturalPortrait) {
+            when (rotation) {
+                Surface.ROTATION_90 -> ScreenOrientationOrientationType.LANDSCAPE_PRIMARY
+                Surface.ROTATION_180 -> ScreenOrientationOrientationType.PORTRAIT_SECONDARY
+                Surface.ROTATION_270 -> ScreenOrientationOrientationType.LANDSCAPE_SECONDARY
+                else -> ScreenOrientationOrientationType.PORTRAIT_PRIMARY
+            }
+        } else {
+            when (rotation) {
+                Surface.ROTATION_90 -> ScreenOrientationOrientationType.PORTRAIT_SECONDARY
+                Surface.ROTATION_180 -> ScreenOrientationOrientationType.LANDSCAPE_SECONDARY
+                Surface.ROTATION_270 -> ScreenOrientationOrientationType.PORTRAIT_PRIMARY
+                else -> ScreenOrientationOrientationType.LANDSCAPE_PRIMARY
+            }
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/screen-orientation/ios/ScreenOrientationPlugin.swift

@@ -0,0 +1,150 @@
+import UIKit
+
+/// Interface orientation of the window scene, and a lock through the shell's view controller.
+/// - Lock: UIKit asks the root view controller's supportedInterfaceOrientations, so the shell's
+///   AkanNativeViewController returns `orientationLock` when set (shell hook). After changing it,
+///   setNeedsUpdateOfSupportedInterfaceOrientations + requestGeometryUpdate rotate the scene
+///   (capacitor-plugins/screen-orientation/ios/Sources/ScreenOrientationPlugin/ScreenOrientation.swift:29-47,
+///   which uses the deprecated UIDevice "orientation" key before iOS 16; not needed here).
+/// - The lock is intersected with the app's orientations first: a mask with none in common makes
+///   UIKit raise an exception. The iPhone Info.plist omits portrait upside down.
+/// - get/change read the scene's effectiveGeometry.interfaceOrientation (what the page is drawn in).
+///   Capacitor reads UIDevice.orientation, the physical device, which differs while locked and is
+///   "face up" on a table. effectiveGeometry is key-value observable and changes for 180° turns too.
+/// - landscape-primary is UIInterfaceOrientation.landscapeRight: the interface turns the opposite
+///   way from the device (ScreenOrientation.swift:83-120, Safari's screen.orientation agrees).
+/// Arguments arrive decoded and checked by the generated ScreenOrientationPluginSpec (PL-10).
+final class ScreenOrientationPlugin: ScreenOrientationPluginSpec {
+    static let id = "screen-orientation"
+    private static let lockWait: TimeInterval = 1.5
+
+    private static func mask(_ lock: ScreenOrientationOrientationLock) -> UIInterfaceOrientationMask {
+        switch lock {
+        case .any: .all
+        case .portrait: [.portrait, .portraitUpsideDown]
+        case .landscape: .landscape
+        case .portraitPrimary: .portrait
+        case .portraitSecondary: .portraitUpsideDown
+        case .landscapePrimary: .landscapeRight
+        case .landscapeSecondary: .landscapeLeft
+        }
+    }
+
+    private let context: AkanNativePluginContext
+    private var observation: NSKeyValueObservation?
+    private var observedScene: UIWindowScene?
+    private var listening = false
+    private var last: ScreenOrientationOrientationType?
+    /// lock() calls waiting for the scene to reach an allowed orientation.
+    private var waiting: [(reply: AkanNativeReply<Void>, mask: UIInterfaceOrientationMask)] = []
+
+    init(context: AkanNativePluginContext) {
+        self.context = context
+    }
+
+    func get(_ reply: AkanNativeReply<ScreenOrientationOrientationState>) {
+        reply.resolve(ScreenOrientationOrientationState(type: type()))
+    }
+
+    func lock(_ args: ScreenOrientationLockArgs, _ reply: AkanNativeReply<Void>) {
+        let name = args.orientation.rawValue
+        guard let controller = context.viewController as? AkanNativeViewController, let scene = context.windowScene else {
+            return reply.reject(.internalError, "no window to lock")
+        }
+        let supported = UIApplication.shared.supportedInterfaceOrientations(for: controller.view.window)
+        let mask = Self.mask(args.orientation).intersection(supported)
+        if mask.isEmpty {
+            return reply.reject(.unsupported, "\(name) is not one of the app's orientations on this device")
+        }
+        controller.orientationLock = mask
+        controller.setNeedsUpdateOfSupportedInterfaceOrientations()
+        if Self.contains(mask, scene.effectiveGeometry.interfaceOrientation) { return reply.resolve() }
+
+        waiting.append((reply, mask))
+        observe(scene)
+        scene.requestGeometryUpdate(.iOS(interfaceOrientations: mask)) { error in
+            // iPad multitasking, or a presented controller that does not allow the orientation.
+            let message = error.localizedDescription
+            reply.reject(.unsupported, "the system refused \(name): \(message)")
+        }
+        DispatchQueue.main.asyncAfter(deadline: .now() + Self.lockWait) { [weak self] in
+            // The lock is in place; the rotation may still be under way or come with the next device turn.
+            reply.resolve()
+            self?.waiting.removeAll { $0.reply === reply }
+            self?.stopObservingIfIdle()
+        }
+    }
+
+    func unlock(_ reply: AkanNativeReply<Void>) {
+        (context.viewController as? AkanNativeViewController)?.orientationLock = nil
+        context.viewController?.setNeedsUpdateOfSupportedInterfaceOrientations()
+        reply.resolve()
+    }
+
+    func startListening(_ event: String) {
+        guard event == "change" else { return }
+        listening = true
+        last = type()
+        if let scene = context.windowScene { observe(scene) }
+    }
+
+    func stopListening(_ event: String) {
+        guard event == "change" else { return }
+        listening = false
+        last = nil
+        stopObservingIfIdle()
+    }
+
+    private func observe(_ scene: UIWindowScene) {
+        guard observation == nil || observedScene !== scene else { return }
+        observedScene = scene
+        observation = scene.observe(\.effectiveGeometry, options: [.new]) { [weak self] scene, _ in
+            MainActor.assumeIsolated { self?.geometryChanged(scene.effectiveGeometry.interfaceOrientation) }
+        }
+    }
+
+    private func stopObservingIfIdle() {
+        guard !listening, waiting.isEmpty else { return }
+        observation?.invalidate()
+        observation = nil
+        observedScene = nil
+    }
+
+    private func geometryChanged(_ orientation: UIInterfaceOrientation) {
+        let reached = waiting.filter { Self.contains($0.mask, orientation) }
+        waiting.removeAll { Self.contains($0.mask, orientation) }
+        for entry in reached { entry.reply.resolve() }
+        if listening, let next = Self.type(orientation), next != last {
+            last = next
+            ScreenOrientationEvents(context).change(ScreenOrientationOrientationState(type: next))
+        }
+        stopObservingIfIdle()
+    }
+
+    private func type() -> ScreenOrientationOrientationType {
+        if let scene = context.windowScene, let type = Self.type(scene.effectiveGeometry.interfaceOrientation) { return type }
+        // No window yet: guess from the screen's shape.
+        let bounds = context.webView?.bounds.size ?? .zero
+        return bounds.width > bounds.height ? .landscapePrimary : .portraitPrimary
+    }
+
+    private static func type(_ orientation: UIInterfaceOrientation) -> ScreenOrientationOrientationType? {
+        switch orientation {
+        case .portrait: .portraitPrimary
+        case .portraitUpsideDown: .portraitSecondary
+        case .landscapeRight: .landscapePrimary
+        case .landscapeLeft: .landscapeSecondary
+        default: nil
+        }
+    }
+
+    private static func contains(_ mask: UIInterfaceOrientationMask, _ orientation: UIInterfaceOrientation) -> Bool {
+        switch orientation {
+        case .portrait: mask.contains(.portrait)
+        case .portraitUpsideDown: mask.contains(.portraitUpsideDown)
+        case .landscapeLeft: mask.contains(.landscapeLeft)
+        case .landscapeRight: mask.contains(.landscapeRight)
+        default: false
+        }
+    }
+}

package/vendor/@akanjs/native/plugins/screen-orientation/native-plugin.json

@@ -0,0 +1,17 @@
+{
+  "id": "screen-orientation",
+  "apiVersion": 1,
+  "methods": ["get", "lock", "unlock"],
+  "events": ["change"],
+  "codegen": true,
+  "web": "./src/web.ts",
+  "desktop": null,
+  "ios": {
+    "sources": ["ios/*.swift"],
+    "class": "ScreenOrientationPlugin"
+  },
+  "android": {
+    "sources": ["android/*.kt"],
+    "class": "com.akanjs.plugins.screenorientation.ScreenOrientationPlugin"
+  }
+}

package/vendor/@akanjs/native/plugins/screen-orientation/src/index.ts

@@ -0,0 +1,69 @@
+import { createLiveValue, definePlugin, shallowEqual } from "../../../packages/core/src/index.ts";
+import { useLiveValue } from "../../../packages/react/src/index.ts";
+import type { OrientationLock, OrientationType } from "./types.ts";
+import { readWebOrientation, web } from "./web.ts";
+
+export {
+  checkLock,
+  ORIENTATION_LOCKS,
+  ORIENTATION_TYPES,
+  type OrientationLock,
+  type OrientationType,
+} from "./types.ts";
+
+export interface OrientationState {
+  type: OrientationType;
+}
+
+/**
+ * Screen orientation (plugins.md §4.1): read it, follow it, lock it. Not available on desktop.
+ * The lock belongs to the app and outlives page reloads until unlock().
+ */
+export interface ScreenOrientationApi {
+  get(): Promise<OrientationState>;
+  /**
+   * Restricts the app to `orientation` and rotates to it if needed; resolves once the screen shows
+   * an allowed orientation (or after a moment, when the system rotates later).
+   * Rejects UNSUPPORTED where the lock is not honoured: an orientation the app does not support
+   * (portrait-secondary on iPhones), iPads with multitasking, Android 16+ screens 600 dp and wider
+   * (the system ignores locks there), and browsers without the API. Browsers that have it lock only
+   * in fullscreen or installed web apps: PERMISSION_DENIED otherwise.
+   */
+  lock(args: { orientation: OrientationLock }): Promise<void>;
+  /** Lets the system rotate freely again (the app's supported orientations). */
+  unlock(): Promise<void>;
+}
+
+export interface ScreenOrientationEvents {
+  /** The screen orientation changed, including 180° turns (landscape-primary ↔ landscape-secondary). */
+  change: OrientationState;
+}
+
+export const screenOrientation = definePlugin<ScreenOrientationApi, ScreenOrientationEvents>("screen-orientation", {
+  methods: ["get", "lock", "unlock"],
+  events: ["change"],
+  web,
+});
+
+const current = createLiveValue<OrientationState>(
+  readWebOrientation(),
+  (set) => {
+    if (screenOrientation.eventImplementation("change") === "none") return;
+    let live = true;
+    const stop = screenOrientation.listen("change", set);
+    screenOrientation
+      .get()
+      .then((state) => live && set(state))
+      .catch(() => {});
+    return () => {
+      live = false;
+      stop();
+    };
+  },
+  shallowEqual,
+);
+
+/** The current orientation type. Re-renders on every change. */
+export function useScreenOrientation(): OrientationState {
+  return useLiveValue(current);
+}

package/vendor/@akanjs/native/plugins/screen-orientation/src/types.ts

@@ -0,0 +1,26 @@
+import { AkanNativeError } from "../../../packages/core/src/index.ts";
+
+/** W3C screen orientation types. "primary" is the device's usual way up for that shape. */
+export type OrientationType = "portrait-primary" | "portrait-secondary" | "landscape-primary" | "landscape-secondary";
+
+/** What lock() accepts: one type, either way up of a shape, or any orientation. */
+export type OrientationLock = "any" | "portrait" | "landscape" | OrientationType;
+
+export const ORIENTATION_TYPES: readonly OrientationType[] = [
+  "portrait-primary",
+  "portrait-secondary",
+  "landscape-primary",
+  "landscape-secondary",
+];
+export const ORIENTATION_LOCKS: readonly OrientationLock[] = ["any", "portrait", "landscape", ...ORIENTATION_TYPES];
+
+/** Checks lock()'s argument; the native implementations check the same list. */
+export function checkLock(orientation: unknown): OrientationLock {
+  if (typeof orientation !== "string" || !(ORIENTATION_LOCKS as readonly string[]).includes(orientation)) {
+    throw new AkanNativeError(
+      "INVALID_ARGS",
+      `orientation must be one of ${ORIENTATION_LOCKS.join(", ")} (got ${JSON.stringify(orientation)})`,
+    );
+  }
+  return orientation as OrientationLock;
+}