@flighthq/platform 0.3.1-next.975.01aea94 → 0.4.0-edge.1908.751021c

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { comparePlatformVersions, getPlatformEngine, getPlatformInfo, getPlatformKind, getPlatformName, isPlatformDesktop, isPlatformMobile, isPlatformNative, isPlatformTouch, isPlatformVersionAtLeast, isPlatformWeb, } from './contract';
+export { explainPlatformBackend, comparePlatformVersions, getPlatformEngine, getPlatformInfo, getPlatformKind, getPlatformName, isPlatformDesktop, isPlatformMobile, isPlatformNative, isPlatformTouch, isPlatformVersionAtLeast, isPlatformWeb, } from './contract';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-export { comparePlatformVersions, getPlatformEngine, getPlatformInfo, getPlatformKind, getPlatformName, isPlatformDesktop, isPlatformMobile, isPlatformNative, isPlatformTouch, isPlatformVersionAtLeast, isPlatformWeb, } from './contract';
+export { explainPlatformBackend, comparePlatformVersions, getPlatformEngine, getPlatformInfo, getPlatformKind, getPlatformName, isPlatformDesktop, isPlatformMobile, isPlatformNative, isPlatformTouch, isPlatformVersionAtLeast, isPlatformWeb, } from './contract';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,aAAa,GACd,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,sBAAsB,EACtB,uBAAuB,EACvB,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,eAAe,EACf,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,wBAAwB,EACxB,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/platform.d.ts

@@ -1,18 +1,23 @@
+import type { BackendExplanation } from '@flighthq/types/contract';
 import type { PlatformBackend, PlatformEngine, PlatformInfo, PlatformKind, PlatformName, PlatformRuntime } from '@flighthq/types/contract';
 export declare function comparePlatformVersions(a: string, b: string): -1 | 0 | 1;
 export declare function createPlatformInfo(): PlatformInfo;
 export declare function createWebPlatformBackend(): PlatformBackend;
+export declare function explainPlatformBackend(): BackendExplanation;
 export declare function getPlatformBackend(): PlatformBackend;
 export declare function getPlatformEngine(): PlatformEngine;
 export declare function getPlatformInfo(out: PlatformInfo): PlatformInfo;
 export declare function getPlatformKind(): PlatformKind;
 export declare function getPlatformName(): PlatformName;
 export declare function getPlatformRuntime(): PlatformRuntime;
+export declare function installPlatformHostBackend(backend: PlatformBackend): void;
 export declare function isPlatformDesktop(): boolean;
 export declare function isPlatformMobile(): boolean;
 export declare function isPlatformNative(): boolean;
 export declare function isPlatformTouch(): boolean;
 export declare function isPlatformVersionAtLeast(minimum: string): boolean;
 export declare function isPlatformWeb(): boolean;
+export declare function observePlatformHostResult(operation: string, succeeded: boolean): void;
+export declare function resetPlatformBackendForTest(): void;
 export declare function setPlatformBackend(backend: PlatformBackend | null): void;
 //# sourceMappingURL=platform.d.ts.map

package/dist/platform.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAgBlC,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAcxE;AAGD,wBAAgB,kBAAkB,IAAI,YAAY,CAiBjD;AAID,wBAAgB,wBAAwB,IAAI,eAAe,CAE1D;AAID,wBAAgB,kBAAkB,IAAI,eAAe,CAGpD;AAID,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAGD,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAE/D;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAID,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAGD,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAGD,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAID,wBAAgB,gBAAgB,IAAI,OAAO,CAG1C;AAGD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAKD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAIjE;AAGD,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAExE"}
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AACnE,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,eAAe,EAChB,MAAM,0BAA0B,CAAC;AAgBlC,wBAAgB,uBAAuB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAcxE;AAGD,wBAAgB,kBAAkB,IAAI,YAAY,CAiBjD;AAID,wBAAgB,wBAAwB,IAAI,eAAe,CAE1D;AAED,wBAAgB,sBAAsB,IAAI,kBAAkB,CAa3D;AAID,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAID,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAGD,wBAAgB,eAAe,CAAC,GAAG,EAAE,YAAY,GAAG,YAAY,CAE/D;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAGD,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAID,wBAAgB,kBAAkB,IAAI,eAAe,CAEpD;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,CAMzE;AAGD,wBAAgB,iBAAiB,IAAI,OAAO,CAE3C;AAGD,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAID,wBAAgB,gBAAgB,IAAI,OAAO,CAG1C;AAGD,wBAAgB,eAAe,IAAI,OAAO,CAEzC;AAKD,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAIjE;AAGD,wBAAgB,aAAa,IAAI,OAAO,CAEvC;AAED,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,GAAG,IAAI,CAKrF;AAED,wBAAgB,2BAA2B,IAAI,IAAI,CAKlD;AAID,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI,CAExE"}

package/dist/platform.js

@@ -44,12 +44,24 @@ export function createPlatformInfo() {
 export function createWebPlatformBackend() {
     return { getInfo: getWebPlatformInfo };
 }
-// The active platform backend, or the web default when no native host has registered one. Capability
-// packages call their own get*Backend; this is the root one for environment identification.
+export function explainPlatformBackend() {
+    if (_custom !== null) {
+        return { conflict: _hostConflict, layer: 'custom', operation: null, viability: 'unobserved' };
+    }
+    if (_host !== null) {
+        return {
+            conflict: _hostConflict,
+            layer: 'host',
+            operation: _hostObservation !== null ? _hostObservation.operation : null,
+            viability: _hostObservation !== null ? _hostObservation.viability : 'unobserved',
+        };
+    }
+    return { conflict: false, layer: 'host-not-enabled', operation: null, viability: 'unobserved' };
+}
+// The active platform backend. Capability packages call their own get*Backend; this is the root
+// one for environment identification.
 export function getPlatformBackend() {
-    if (_backend === null)
-        _backend = createWebPlatformBackend();
-    return _backend;
+    return _custom ?? _host ?? _sentinel;
 }
 // The browser rendering engine — 'blink' | 'gecko' | 'webkit' | 'unknown'. Convenience over
 // getPlatformInfo. 'unknown' on native hosts where no browser engine is present.
@@ -73,6 +85,14 @@ export function getPlatformName() {
 export function getPlatformRuntime() {
     return getPlatformInfo(_scratch).runtime;
 }
+export function installPlatformHostBackend(backend) {
+    if (_host !== null) {
+        if (_host !== backend)
+            _hostConflict = true;
+        return;
+    }
+    _host = backend;
+}
 // True on a desktop host (Electron/Tauri/native window shell). False on mobile and plain web.
 export function isPlatformDesktop() {
     return getPlatformKind() === 'desktop';
@@ -104,15 +124,49 @@ export function isPlatformVersionAtLeast(minimum) {
 export function isPlatformWeb() {
     return getPlatformKind() === 'web';
 }
-// Installs a native host backend (Electron/Tauri/Capacitor/native). Pass null to fall back to web.
-// Opt-in and side-effect-free at import: nothing registers until a host calls this.
+export function observePlatformHostResult(operation, succeeded) {
+    _hostObservation = {
+        operation,
+        viability: succeeded ? 'available' : 'runtime-api-unavailable',
+    };
+}
+export function resetPlatformBackendForTest() {
+    _custom = null;
+    _host = null;
+    _hostConflict = false;
+    _hostObservation = null;
+}
+// Installs a native host backend (Electron/Tauri/Capacitor/native). Pass null to fall back to
+// the host or sentinel layer.
 export function setPlatformBackend(backend) {
-    _backend = backend;
+    _custom = backend;
 }
-let _backend = null;
+let _custom = null;
+let _host = null;
+let _hostConflict = false;
+let _hostObservation = null;
 // Single-threaded JS no-alloc scratch for scalar convenience reads (getPlatformKind, etc.).
 // Rust/native mirror uses a per-call local or thread-local instead.
 const _scratch = createPlatformInfo();
+const _sentinel = {
+    getInfo(out) {
+        out.arch = '';
+        out.distro = '';
+        out.distroVersion = '';
+        out.endianness = 'unknown';
+        out.engine = 'unknown';
+        out.engineVersion = '';
+        out.isTouch = false;
+        out.kind = 'unknown';
+        out.locale = '';
+        out.name = 'unknown';
+        out.osBuild = '';
+        out.pointerWidth = -1;
+        out.runtime = 'unknown';
+        out.version = '';
+        return out;
+    },
+};
 function getWebPlatformInfo(out) {
     const nav = typeof navigator !== 'undefined' ? navigator : null;
     const ua = nav?.userAgent ?? '';

package/dist/platform.js.map

@@ -1 +1 @@
-{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"platform.js","sourceRoot":"","sources":["../src/platform.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flighthq/platform",
-  "version": "0.3.1-next.975.01aea94",
+  "version": "0.4.0-edge.1908.751021c",
   "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.3.1-next.975.01aea94",
-    "@flighthq/useragent": "0.3.1-next.975.01aea94"
+    "@flighthq/types": "0.4.0-edge.1908.751021c",
+    "@flighthq/useragent": "0.4.0-edge.1908.751021c"
   },
   "devDependencies": {
     "typescript": "^5.3.0"

package/src/platform.test.ts

@@ -17,6 +17,10 @@ import {
   isPlatformVersionAtLeast,
   isPlatformWeb,
   setPlatformBackend,
+  explainPlatformBackend,
+  installPlatformHostBackend,
+  observePlatformHostResult,
+  resetPlatformBackendForTest,
 } from './platform';
 
 function fakeBackend(info: Partial<PlatformInfo>): PlatformBackend {
@@ -141,6 +145,34 @@ describe('createWebPlatformBackend', () => {
   });
 });
 
+describe('explainPlatformBackend', () => {
+  afterEach(() => resetPlatformBackendForTest());
+
+  it('reports host-not-enabled when no backend is installed', () => {
+    resetPlatformBackendForTest();
+    const explanation = explainPlatformBackend();
+    expect(explanation.layer).toBe('host-not-enabled');
+    expect(explanation.conflict).toBe(false);
+    expect(explanation.viability).toBe('unobserved');
+  });
+
+  it('reports custom layer when a custom backend is set', () => {
+    setPlatformBackend(fakeBackend({}));
+    expect(explainPlatformBackend().layer).toBe('custom');
+  });
+
+  it('reports host layer when a host backend is installed', () => {
+    installPlatformHostBackend(fakeBackend({}));
+    expect(explainPlatformBackend().layer).toBe('host');
+  });
+
+  it('reports conflict when two different host backends are installed', () => {
+    installPlatformHostBackend(fakeBackend({}));
+    installPlatformHostBackend(fakeBackend({}));
+    expect(explainPlatformBackend().conflict).toBe(true);
+  });
+});
+
 describe('getPlatformBackend', () => {
   it('falls back to a web backend when none is registered', () => {
     expect(getPlatformBackend()).not.toBeNull();
@@ -226,6 +258,25 @@ describe('getPlatformRuntime', () => {
   });
 });
 
+describe('installPlatformHostBackend', () => {
+  afterEach(() => resetPlatformBackendForTest());
+
+  it('installs a host backend that getPlatformBackend returns', () => {
+    const backend = fakeBackend({});
+    installPlatformHostBackend(backend);
+    expect(getPlatformBackend()).toBe(backend);
+  });
+
+  it('is first-host-wins: a second different backend sets conflict', () => {
+    const first = fakeBackend({});
+    const second = fakeBackend({});
+    installPlatformHostBackend(first);
+    installPlatformHostBackend(second);
+    expect(getPlatformBackend()).toBe(first);
+    expect(explainPlatformBackend().conflict).toBe(true);
+  });
+});
+
 describe('isPlatformDesktop', () => {
   it('is true only for desktop kind', () => {
     setPlatformBackend(fakeBackend({ kind: 'desktop' }));
@@ -317,6 +368,36 @@ describe('isPlatformWeb', () => {
   });
 });
 
+describe('observePlatformHostResult', () => {
+  afterEach(() => resetPlatformBackendForTest());
+
+  it('records a successful observation', () => {
+    installPlatformHostBackend(fakeBackend({}));
+    observePlatformHostResult('getInfo', true);
+    const explanation = explainPlatformBackend();
+    expect(explanation.operation).toBe('getInfo');
+    expect(explanation.viability).toBe('available');
+  });
+
+  it('records a failed observation', () => {
+    installPlatformHostBackend(fakeBackend({}));
+    observePlatformHostResult('getInfo', false);
+    expect(explainPlatformBackend().viability).toBe('runtime-api-unavailable');
+  });
+});
+
+describe('resetPlatformBackendForTest', () => {
+  it('clears all backend slots', () => {
+    setPlatformBackend(fakeBackend({}));
+    installPlatformHostBackend(fakeBackend({}));
+    observePlatformHostResult('getInfo', true);
+    resetPlatformBackendForTest();
+    expect(explainPlatformBackend().layer).toBe('host-not-enabled');
+    expect(explainPlatformBackend().conflict).toBe(false);
+    expect(explainPlatformBackend().viability).toBe('unobserved');
+  });
+});
+
 describe('setPlatformBackend', () => {
   it('clears back to the web fallback when passed null', () => {
     setPlatformBackend(fakeBackend({ name: 'linux' }));