@flighthq/device 0.4.0-next.1920.b93ad0f → 0.4.0-next.1932.1ef883a

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2013-2026 Joshua Granick and other contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,104 +1,17 @@
 # @flighthq/device
 
-Device identity, hardware, and safe-area insets over a swappable web/native backend.
+Device identity, hardware, and safe-area insets over a swappable web/native backend
 
-`device` is a host-identity leaf in the platform-integration suite. Every public function is a free function that delegates to the active `DeviceBackend`. A web/DOM backend is lazily available, so every function works on the web; a native host (Electron, Tauri, Capacitor, a C/C++ shell) replaces it via `setDeviceBackend`. Snapshot reads fill an `out` value and return it. Unknown or unavailable fields resolve to sentinels (`''` / `-1` / `false`), never throwing.
+## Install
 
-Battery state is **not** here — it is a live, event-bearing concern owned by `@flighthq/power`. `DeviceInfo` is a static identity snapshot. Live multi-display enumeration and work-area geometry belong to `@flighthq/screen`; `DeviceDisplayMetrics` describes only the built-in display.
-
-## Functions
-
-| Function | Purpose |
-| --- | --- |
-| `createDeviceCapabilities()` | Allocate a zeroed `DeviceCapabilities` (all `false`) to pass as `out`. |
-| `createDeviceDisplayMetrics()` | Allocate a zeroed `DeviceDisplayMetrics` (all `-1`) to pass as `out`. |
-| `createDeviceInfo()` | Allocate a zeroed `DeviceInfo` (strings `''`, booleans `false`, arrays `[]`, numbers `-1`) to pass as `out`. |
-| `createSafeAreaInsets()` | Allocate a zeroed `SafeAreaInsets` (all edges `0`) to pass as `out`. |
-| `createWebDeviceBackend()` | Build the default web backend. |
-| `enableWebSafeAreaInsets()` | Mount a CSS `env(safe-area-inset-*)` probe; returns a dispose function. Opt-in (touches the DOM). |
-| `getDeviceBackend()` | Return the active backend, lazily creating the web default. There is always a backend. |
-| `getDeviceCapabilities(out)` | Fill `out` with input/hardware capability flags. |
-| `getDeviceDisplayMetrics(out)` | Fill `out` with the built-in display metrics. |
-| `getDeviceId()` | Return a stable install identifier (resettable, not a hardware serial). |
-| `getDeviceInfo(out)` | Fill `out` with the device's identity snapshot. |
-| `getSafeAreaInsets(out)` | Fill `out` with safe-area insets, in CSS pixels. |
-| `refreshDeviceInfo()` | Invalidate a backend snapshot cache so the next read is fresh. No-op on the stateless web default. |
-| `setDeviceBackend(backend)` | Install a native host backend; pass `null` to fall back to the web default. |
-
-## `DeviceInfo` fields
-
-| Field | Type | Unit | Sentinel | Web backend |
-| --- | --- | --- | --- | --- |
-| `arch` | `string` | CPU architecture token (e.g. `x86_64`, `arm64`) | `''` | Parsed from the UA / `userAgentData.platform`. Best-effort. |
-| `availableMemory` | `number` | bytes of currently-available RAM | `-1` | Not exposed by browsers — always `-1`. |
-| `boardName` | `string` | hardware board / mainboard name | `''` | Not exposed — always `''`. |
-| `colorGamut` | `string` | display color gamut token | `''` | Not exposed — always `''`. |
-| `cpuCores` | `number` | logical CPU core count | `-1` | `navigator.hardwareConcurrency` when present. |
-| `fontScale` | `number` | OS font-scale multiplier (`1.0` = default) | `-1` | Not exposed — always `-1`. |
-| `formFactor` | `DeviceFormFactor` | physical device class (open string-kind: `Desktop`, `Phone`, `Tablet`, `TV`, `Watch`, `Car`, `Unknown`, or vendor-prefixed) | `'Unknown'` | Parsed from the UA + `maxTouchPoints`. |
-| `gpuRenderer` | `string` | GPU renderer string | `''` | `WEBGL_debug_renderer_info`; may be masked/randomized by browser privacy budget. |
-| `gpuVendor` | `string` | GPU vendor string | `''` | `WEBGL_debug_renderer_info`; same caveat. |
-| `isHdr` | `boolean` | display is HDR-capable | `false` | Not exposed — always `false`. |
-| `isJailbroken` | `boolean` | iOS jailbreak detected | `false` | No web detection — always `false`. |
-| `isLowEndDevice` | `boolean` | heuristically a low-end device | `false` | Heuristic: `≤ 1 GiB` RAM or `≤ 2` cores. Unknown inputs → `false`. |
-| `isRooted` | `boolean` | Android root detected | `false` | No web detection — always `false`. |
-| `isVirtual` | `boolean` | running on an emulator / VM | `false` | No web detection — always `false`. |
-| `manufacturer` | `string` | hardware manufacturer | `''` | Not exposed — always `''`. |
-| `marketingName` | `string` | consumer marketing name | `''` | Not exposed — always `''`. |
-| `model` | `string` | hardware model identifier | `''` | Not exposed — always `''`. |
-| `osBuild` | `string` | OS build number | `''` | Not exposed — always `''`. |
-| `osName` | `string` | OS name | `''` | Parsed from the UA. |
-| `osVersion` | `string` | OS version string | `''` | Parsed from the UA. |
-| `platformString` | `string` | raw platform identifier | `''` | The full UA string. |
-| `productName` | `string` | product / device codename | `''` | Not exposed — always `''`. |
-| `supportedAbis` | `readonly string[]` | supported native ABIs | `[]` | Not exposed — always `[]`. |
-| `totalMemory` | `number` | bytes of total RAM | `-1` | `navigator.deviceMemory` (GiB) converted to bytes; coarse, privacy-clamped. |
-| `webViewVersion` | `string` | host WebView version | `''` | Not applicable (we are the browser) — always `''`. |
-
-## `DeviceCapabilities` fields
-
-| Field | Type | Sentinel | Web backend |
-| --- | --- | --- | --- |
-| `hasKeyboard` | `boolean` | `false` | Heuristic: desktop UA likely has a physical keyboard. Cannot distinguish hybrid (Surface, iPad + keyboard). |
-| `hasMouse` | `boolean` | `false` | Heuristic: `maxTouchPoints === 0` is a strong pointer-device signal. Cannot confirm a physical mouse. |
-| `hasStylus` | `boolean` | `false` | No reliable browser signal — always `false`. |
-
-Richer pointer/keyboard event handling lives in `@flighthq/input` and `@flighthq/interaction`; `DeviceCapabilities` only surfaces capabilities with no dedicated package owner.
-
-## `DeviceDisplayMetrics` fields
-
-| Field | Type | Unit | Sentinel | Web backend |
-| --- | --- | --- | --- | --- |
-| `colorDepth` | `number` | bits per pixel | `-1` | `screen.colorDepth`. |
-| `densityDpi` | `number` | dots per inch | `-1` | Not exposed by browsers — always `-1`. |
-| `logicalHeight` | `number` | CSS pixels | `-1` | `screen.height`. |
-| `logicalWidth` | `number` | CSS pixels | `-1` | `screen.width`. |
-| `physicalHeight` | `number` | device pixels | `-1` | `screen.height × devicePixelRatio` when the ratio is known. |
-| `physicalWidth` | `number` | device pixels | `-1` | `screen.width × devicePixelRatio` when the ratio is known. |
-| `pixelRatio` | `number` | device pixels per CSS pixel | `-1` | `window.devicePixelRatio`. |
-
-## `SafeAreaInsets` fields
-
-| Field | Type | Unit | Sentinel | Web backend |
-| --- | --- | --- | --- | --- |
-| `top` | `number` | CSS pixels | `0` | `0` by default; real `env(safe-area-inset-top)` after `enableWebSafeAreaInsets()`. |
-| `right` | `number` | CSS pixels | `0` | `0` by default; real `env(safe-area-inset-right)` after `enableWebSafeAreaInsets()`. |
-| `bottom` | `number` | CSS pixels | `0` | `0` by default; real `env(safe-area-inset-bottom)` after `enableWebSafeAreaInsets()`. |
-| `left` | `number` | CSS pixels | `0` | `0` by default; real `env(safe-area-inset-left)` after `enableWebSafeAreaInsets()`. |
-
-Edge insets keep content clear of notches, rounded corners, and system bars. The web backend returns zeros until `enableWebSafeAreaInsets()` mounts a live CSS-var probe (one hidden element, no polling).
-
-## `getDeviceId`
-
-The web default generates a `crypto.randomUUID()` and persists it to `localStorage` as a stable install id. It returns `''` when no stable id can be formed (SSR, blocked storage, privacy mode). This is an **install** id — it resets when storage is cleared — not a hardware serial.
-
-## Usage
+```sh
+npm install @flighthq/device
+```
 
-```ts
-import { createDeviceInfo, getDeviceInfo, getDeviceId } from '@flighthq/device';
+Import the supported application-facing API from `@flighthq/device`. The `@flighthq/device/contract` export is the wider package-to-package contract used to compose Flight itself.
 
-const info = getDeviceInfo(createDeviceInfo());
-console.log(info.formFactor, info.osName, info.cpuCores);
+This package is part of the locked-version Flight SDK graph. Applications may instead install and import `@flighthq/sdk` when package-level tree shaking is sufficient.
 
-const installId = getDeviceId();
-```
+- [Flight project](https://github.com/flighthq/flight)
+- [Source for @flighthq/device@0.4.0-next.1932.1ef883a](https://github.com/flighthq/flight/tree/1ef883a866729a9bc6f461111970f6377de1499f/packages/device)
+- [License](https://github.com/flighthq/flight/blob/1ef883a866729a9bc6f461111970f6377de1499f/LICENSE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/device",
-  "version": "0.4.0-next.1920.b93ad0f",
+  "version": "0.4.0-next.1932.1ef883a",
   "author": "Joshua Granick and other contributors",
   "license": "MIT",
   "repository": {
@@ -38,8 +38,8 @@
     "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
   },
   "dependencies": {
-    "@flighthq/types": "0.4.0-next.1920.b93ad0f",
-    "@flighthq/useragent": "0.4.0-next.1920.b93ad0f"
+    "@flighthq/types": "0.4.0-next.1932.1ef883a",
+    "@flighthq/useragent": "0.4.0-next.1932.1ef883a"
   },
   "devDependencies": {
     "typescript": "^5.3.0"