@flighthq/host 0.5.1-edge.1370.903f328

package/dist/index.js

@@ -0,0 +1,4 @@
+// The public lane: querying a host and diagnosing one. createHost/initializeHost stay on ./contract —
+// an app imports a prebuilt host constant from a @flighthq/host-* package rather than constructing one.
+export { enableHostGuards, explainHost, explainHostAudioDevice, explainHostAudioMixer, explainHostImage, explainHostInputIngress, explainHostTextSegmenter, explainHostTextShaper, explainHostVideo, getHostAudioDevice, getHostAudioMixer, getHostBitmapEncode, getHostBitmapReadback, getHostClipboardFormats, getHostDevice, getHostFileSystem, getHostFontLoading, getHostGeolocation, getHostGlyphRasterizer, getHostHaptics, getHostImage, getHostInputIngress, getHostLifecycle, getHostNet, getHostNotificationPermission, getHostPlatform, getHostPowerKeepAwake, getHostScreenQuery, getHostSensors, getHostSocket, getHostSoftKeyboardInfo, getHostStorage, getHostStoragePersistenceQuery, getHostTextSegmenter, getHostTextShaper, getHostVideo, getHostWgpu, hasHostAudioDevice, hasHostAudioMixer, hasHostBitmapEncode, hasHostBitmapReadback, hasHostClipboardFormats, hasHostDevice, hasHostFileSystem, hasHostFontLoading, hasHostGeolocation, hasHostGlyphRasterizer, hasHostHaptics, hasHostImage, hasHostInputIngress, hasHostLifecycle, hasHostNet, hasHostNotificationPermission, hasHostPlatform, hasHostPowerKeepAwake, hasHostScreenQuery, hasHostSensors, hasHostSocket, hasHostSoftKeyboardInfo, hasHostStorage, hasHostStoragePersistenceQuery, hasHostTextSegmenter, hasHostTextShaper, hasHostVideo, hasHostWgpu, } from './contract';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,wGAAwG;AACxG,OAAO,EACL,gBAAgB,EAChB,WAAW,EACX,sBAAsB,EACtB,qBAAqB,EACrB,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,qBAAqB,EACrB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,6BAA6B,EAC7B,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,cAAc,EACd,8BAA8B,EAC9B,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,uBAAuB,EACvB,aAAa,EACb,iBAAiB,EACjB,kBAAkB,EAClB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,gBAAgB,EAChB,UAAU,EACV,6BAA6B,EAC7B,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,cAAc,EACd,aAAa,EACb,uBAAuB,EACvB,cAAc,EACd,8BAA8B,EAC9B,oBAAoB,EACpB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@flighthq/host",
+  "version": "0.5.1-edge.1370.903f328",
+  "author": "Joshua Granick and other contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flighthq/flight.git",
+    "directory": "packages/host"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./contract": {
+      "types": "./dist/contract.d.ts",
+      "default": "./dist/contract.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src/**/*.test.ts",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.test.js.map",
+    "!dist/**/*.test.d.ts.map"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "vitest run --config vitest.config.ts",
+    "test:watch": "vitest --watch --config vitest.config.ts",
+    "prepack": "npm run clean && npm run clean:dist && npm run build",
+    "clean:dist": "tsx ../../scripts/clean-package-dist.ts"
+  },
+  "dependencies": {
+    "@flighthq/entity": "0.5.1-edge.1370.903f328",
+    "@flighthq/log": "0.5.1-edge.1370.903f328",
+    "@flighthq/types": "0.5.1-edge.1370.903f328"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0"
+  },
+  "description": "Portable host interface: host construction, capability queries, and host diagnostics",
+  "sideEffects": false
+}

package/src/enableHostGuards.test.ts

@@ -0,0 +1,93 @@
+import {
+  addLogSink,
+  clearLogOnceKeys,
+  createMemoryLogSink,
+  getMemoryLogSinkEntries,
+  removeLogSink,
+} from '@flighthq/log/contract';
+import type { EntityWithoutRuntime, Host, LogEntry } from '@flighthq/types/contract';
+import { LogLevel } from '@flighthq/types/contract';
+
+import { enableHostGuards } from './enableHostGuards';
+import { createHost } from './host';
+
+beforeEach(() => {
+  clearLogOnceKeys();
+});
+
+describe('enableHostGuards', () => {
+  it('warns once per commonly needed provider a host is missing', () => {
+    const entries = captureLog(() => enableHostGuards(createHost()));
+
+    expect(entries.length).toBe(GUARDED_SLOTS.length);
+    expect(entries.every((entry) => entry.level === LogLevel.Warn)).toBe(true);
+    expect(entries.map((entry) => slotOf(entry)).sort()).toEqual(GUARDED_SLOTS.slice().sort());
+  });
+
+  it('stays silent about a provider the host actually carries', () => {
+    const entries = captureLog(() => enableHostGuards(hostWith({ media: { video: PROVIDER } })));
+
+    expect(entries.map((entry) => slotOf(entry))).not.toContain('video');
+    expect(entries.length).toBe(GUARDED_SLOTS.length - 1);
+  });
+
+  it('says nothing at all when every guarded provider is present', () => {
+    const entries = captureLog(() =>
+      enableHostGuards(
+        hostWith({
+          graphics: { image: PROVIDER },
+          input: { ingress: PROVIDER },
+          media: { audioDevice: PROVIDER, audioMixer: PROVIDER, video: PROVIDER },
+          text: { segmenter: PROVIDER, shaper: PROVIDER },
+        }),
+      ),
+    );
+
+    expect(entries).toEqual([]);
+  });
+
+  it('warns once across hosts, because the logOnce key is the slot rather than the host', () => {
+    const entries = captureLog(() => {
+      enableHostGuards(createHost());
+      enableHostGuards(createHost());
+    });
+
+    expect(entries.length).toBe(GUARDED_SLOTS.length);
+  });
+
+  it('carries the remedy and its backends as structured data, not only as prose', () => {
+    const entries = captureLog(() => enableHostGuards(createHost()));
+    const video = entries.find((entry) => slotOf(entry) === 'video');
+    const data = video?.data as Readonly<Record<string, unknown>>;
+
+    expect(data.group).toBe('media');
+    expect(data.provider).toBe('HostVideoProvider');
+    expect(data.backends).toEqual(['webHost (@flighthq/host-web)']);
+    expect(String(data.message)).toContain('getHostVideo');
+  });
+});
+
+const PROVIDER = {};
+
+const GUARDED_SLOTS = ['audioDevice', 'audioMixer', 'image', 'ingress', 'segmenter', 'shaper', 'video'];
+
+function captureLog(run: () => void): readonly LogEntry[] {
+  const sink = createMemoryLogSink(32);
+  addLogSink(sink.sink);
+  try {
+    run();
+    return getMemoryLogSinkEntries(sink);
+  } finally {
+    removeLogSink(sink.sink);
+  }
+}
+
+function hostWith(groups: Readonly<Record<string, Readonly<Record<string, unknown>>>>): Host {
+  // A capability literal built from plain stand-ins cannot satisfy createHost's generic, so the shape is
+  // asserted. Only the presence of a slot value matters to the guard.
+  return createHost(groups as Partial<EntityWithoutRuntime<Host>>);
+}
+
+function slotOf(entry: Readonly<LogEntry>): string {
+  return String((entry.data as Readonly<Record<string, unknown>>).slot);
+}

package/src/host.test.ts

@@ -0,0 +1,99 @@
+import { EntityRuntimeKey } from '@flighthq/types/contract';
+
+import * as contract from './contract';
+import { initializeHost } from './host';
+
+describe('createHost', () => {
+  it('creates an Entity immediately while leaving its runtime allocation lazy', () => {
+    const host = requiredFunction(contract, 'createHost')();
+
+    expect(EntityRuntimeKey in host).toBe(true);
+    expect(host[EntityRuntimeKey]).toBeUndefined();
+  });
+
+  it('materializes the complete stable Host shape with truthful empty groups', () => {
+    const host = requiredFunction(contract, 'createHost')();
+
+    expect(
+      Object.keys(host)
+        .filter((key) => key !== String(EntityRuntimeKey))
+        .sort(),
+    ).toEqual(HOST_GROUPS);
+    for (const group of HOST_GROUPS) expect(host[group]).toEqual({});
+  });
+
+  it('preserves supplied capability-group and provider identities without populating another group', () => {
+    const provider = {};
+    const accessibility = { provider };
+    const host = requiredFunction(contract, 'createHost')({ accessibility });
+
+    expect(host.accessibility).toBe(accessibility);
+    expect(host.accessibility.provider).toBe(provider);
+    for (const group of HOST_GROUPS) {
+      if (group !== 'accessibility') expect(host[group]).toEqual({});
+    }
+  });
+
+  it('is reachable on the contract lane only, because an app imports a built host rather than constructing one', async () => {
+    const publicLane = (await import('./index')) as Record<string, unknown>;
+
+    expect('createHost' in contract).toBe(true);
+    expect('createHost' in publicLane).toBe(false);
+    expect('initializeHost' in publicLane).toBe(false);
+  });
+});
+
+describe('initializeHost', () => {
+  it('is the construction initializer of createHost', () => {
+    expect(typeof initializeHost).toBe('function');
+  });
+
+  it('writes every group into an existing construction target without allocating', () => {
+    const out = {} as Parameters<typeof initializeHost>[0];
+    const media = {};
+    initializeHost(out, { media });
+
+    expect(out.media).toBe(media);
+    expect(
+      Object.keys(out)
+        .filter((key) => key !== String(EntityRuntimeKey))
+        .sort(),
+    ).toEqual(HOST_GROUPS);
+  });
+});
+
+const HOST_GROUPS = [
+  'accessibility',
+  'app',
+  'clipboard',
+  'connectivity',
+  'dialog',
+  'graphics',
+  'input',
+  'ipc',
+  'media',
+  'menu',
+  'midi',
+  'net',
+  'notification',
+  'power',
+  'protocol',
+  'screen',
+  'share',
+  'shell',
+  'shortcut',
+  'storage',
+  'system',
+  'text',
+  'tray',
+  'ui',
+  'updater',
+  'window',
+] as const;
+
+function requiredFunction(module: object, name: string): (...args: any[]) => any {
+  const value = Reflect.get(module, name);
+  expect(value, `${name} export`).toBeTypeOf('function');
+  if (typeof value !== 'function') throw new TypeError(`${name} is not exported`);
+  return value as (...args: any[]) => any;
+}

package/src/hostExplain.test.ts

@@ -0,0 +1,218 @@
+import type { EntityWithoutRuntime, Host } from '@flighthq/types/contract';
+
+import { createHost } from './host';
+import {
+  explainHost,
+  explainHostAudioDevice,
+  explainHostAudioMixer,
+  explainHostImage,
+  explainHostInputIngress,
+  explainHostTextSegmenter,
+  explainHostTextShaper,
+  explainHostVideo,
+} from './hostExplain';
+import * as hostQuery from './hostQuery';
+
+describe('explainHost', () => {
+  it('enumerates every capability group the host object carries', () => {
+    const explanation = explainHost(createHost());
+
+    expect(explanation.groups.map((group) => group.group)).toEqual(HOST_GROUPS);
+  });
+
+  it('lists the slot keys a populated group actually holds', () => {
+    const host = hostWith({ media: { audioDevice: PROVIDER, video: PROVIDER } });
+    const media = explainHost(host).groups.find((group) => group.group === 'media');
+
+    expect(media?.slots.slice().sort()).toEqual(['audioDevice', 'video']);
+    expect(media?.isProvider).toBe(false);
+  });
+
+  it('marks host.window as a provider rather than reporting its operations as slots', () => {
+    const host = hostWith({ window: { getWindowSize: () => undefined } });
+    const window = explainHost(host).groups.find((group) => group.group === 'window');
+
+    expect(window?.isProvider).toBe(true);
+    expect(window?.slots).toEqual([]);
+  });
+
+  it('reports every covered provider as absent on an empty host', () => {
+    const providers = explainHost(createHost()).providers;
+
+    expect(providers.length).toBeGreaterThan(0);
+    expect(providers.every((provider) => !provider.isPresent)).toBe(true);
+    expect(providers.map((provider) => `${provider.group}.${provider.slot}`)).toContain('media.video');
+  });
+
+  it('flips a covered provider to present when its slot is filled', () => {
+    const host = hostWith({ media: { video: PROVIDER } });
+    const video = explainHost(host).providers.find((provider) => provider.slot === 'video');
+
+    expect(video?.isPresent).toBe(true);
+    expect(video?.provider).toBe('HostVideoProvider');
+  });
+
+  it('covers exactly the slots hostQuery exposes accessors for, in both directions', () => {
+    const censused = explainHost(createHost())
+      .providers.map((provider) => `get${provider.provider.slice(0, -'Provider'.length)}`)
+      .sort();
+    const exported = Object.keys(hostQuery)
+      .filter((name) => name.startsWith('getHost'))
+      .sort();
+
+    expect(censused).toEqual(exported);
+  });
+
+  it('keeps every per-provider explainer naming the backends it returns as data', () => {
+    for (const explain of EXPLAINERS) {
+      const explanation = explain(createHost());
+      expect(explanation.backends.length, explanation.provider).toBeGreaterThan(0);
+      for (const backend of explanation.backends) {
+        expect(explanation.message, explanation.provider).toContain(backend.entryPoint);
+        expect(explanation.message, explanation.provider).toContain(backend.packageName);
+      }
+    }
+  });
+
+  it('pairs every getHost accessor with a hasHost accessor', () => {
+    const getters = Object.keys(hostQuery)
+      .filter((name) => name.startsWith('getHost'))
+      .sort();
+    const predicates = Object.keys(hostQuery)
+      .filter((name) => name.startsWith('hasHost'))
+      .sort();
+
+    expect(predicates).toEqual(getters.map((name) => `has${name.slice('get'.length)}`));
+  });
+});
+
+describe('explainHostAudioDevice', () => {
+  it('names the accessor, the slot, and where to get the provider when it is absent', () => {
+    const explanation = explainHostAudioDevice(createHost());
+
+    expect(explanation.isPresent).toBe(false);
+    expect(explanation.group).toBe('media');
+    expect(explanation.slot).toBe('audioDevice');
+    expect(explanation.provider).toBe('HostAudioDeviceProvider');
+    expect(explanation.message).toContain('getHostAudioDevice');
+    expect(explanation.backends.map((backend) => backend.packageName)).toEqual(['@flighthq/host-web']);
+  });
+
+  it('reports presence without a remedy when the slot is filled', () => {
+    const explanation = explainHostAudioDevice(hostWith({ media: { audioDevice: PROVIDER } }));
+
+    expect(explanation.isPresent).toBe(true);
+    expect(explanation.message).toBe('getHostAudioDevice: host.media.audioDevice is present');
+  });
+});
+
+describe('explainHostAudioMixer', () => {
+  it('explains an absent mixer against the media group', () => {
+    const explanation = explainHostAudioMixer(createHost());
+
+    expect(explanation.slot).toBe('audioMixer');
+    expect(explanation.isPresent).toBe(false);
+    expect(explanation.backends.length).toBeGreaterThan(0);
+  });
+});
+
+describe('explainHostImage', () => {
+  it('explains an absent image provider against the graphics group', () => {
+    const explanation = explainHostImage(createHost());
+
+    expect(explanation.group).toBe('graphics');
+    expect(explanation.provider).toBe('HostImageProvider');
+    expect(explanation.isPresent).toBe(false);
+  });
+});
+
+describe('explainHostInputIngress', () => {
+  it('explains an absent ingress provider against the input group', () => {
+    const explanation = explainHostInputIngress(createHost());
+
+    expect(explanation.group).toBe('input');
+    expect(explanation.slot).toBe('ingress');
+    expect(explanation.isPresent).toBe(false);
+  });
+});
+
+describe('explainHostTextSegmenter', () => {
+  it('points at the package that builds a segmenter rather than at a host backend', () => {
+    const explanation = explainHostTextSegmenter(createHost());
+
+    expect(explanation.backends.map((backend) => backend.packageName)).toEqual(['@flighthq/textsegment']);
+    expect(explanation.message).toContain('createWebTextSegmenterBackend');
+  });
+});
+
+describe('explainHostTextShaper', () => {
+  it('points at the package that builds a shaper rather than at a host backend', () => {
+    const explanation = explainHostTextShaper(createHost());
+
+    expect(explanation.backends.map((backend) => backend.packageName)).toEqual(['@flighthq/textshaper-canvas']);
+    expect(explanation.message).toContain('createCanvasTextShaperBackend');
+  });
+
+  it('reports presence when the shaper is composed into the text group', () => {
+    const explanation = explainHostTextShaper(hostWith({ text: { shaper: PROVIDER } }));
+
+    expect(explanation.isPresent).toBe(true);
+  });
+});
+
+describe('explainHostVideo', () => {
+  it('explains an absent video provider against the media group', () => {
+    const explanation = explainHostVideo(createHost());
+
+    expect(explanation.group).toBe('media');
+    expect(explanation.provider).toBe('HostVideoProvider');
+    expect(explanation.isPresent).toBe(false);
+  });
+});
+
+const PROVIDER = {};
+
+function hostWith(groups: Readonly<Record<string, Readonly<Record<string, unknown>>>>): Host {
+  // A capability literal built from plain stand-ins cannot satisfy createHost's generic, so the shape is
+  // asserted. Identity, not structure, is what every assertion below reads.
+  return createHost(groups as Partial<EntityWithoutRuntime<Host>>);
+}
+
+const EXPLAINERS = [
+  explainHostAudioDevice,
+  explainHostAudioMixer,
+  explainHostImage,
+  explainHostInputIngress,
+  explainHostTextSegmenter,
+  explainHostTextShaper,
+  explainHostVideo,
+];
+
+const HOST_GROUPS = [
+  'accessibility',
+  'app',
+  'clipboard',
+  'connectivity',
+  'dialog',
+  'graphics',
+  'input',
+  'ipc',
+  'media',
+  'menu',
+  'midi',
+  'net',
+  'notification',
+  'power',
+  'protocol',
+  'screen',
+  'share',
+  'shell',
+  'shortcut',
+  'storage',
+  'system',
+  'text',
+  'tray',
+  'ui',
+  'updater',
+  'window',
+];