@found-in-space/skykit 0.2.0-alpha.1 → 0.2.0-dev.20260527.0

package/src/__tests__/skykit-xr.test.js

@@ -1,4 +1,5 @@
 import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
 import test from 'node:test';
 import * as THREE from 'three';
 
@@ -11,6 +12,7 @@ import {
   createSkykitXrObserverRig,
   createSkykitXrPickRouter,
   createSkykitXrRaySource,
+  createSkykitXrRayVisualPlugin,
   createSkykitXrRig,
   createSkykitXrSessionPlugin,
   createSkykitXrStarPickingPlugin,
@@ -20,6 +22,32 @@ import {
 } from '../xr.js';
 import { createSkykitActionRegistry } from '../index.js';
 
+test('xr free-roam demo uses restored alpha XR regressions defaults', () => {
+  const source = readFileSync(new URL('../../examples/xr-free-roam/xr-free-roam.js', import.meta.url), 'utf8');
+
+  assert.match(source, /createDefaultThreeStarFieldMaterialProfile/);
+  assert.doesNotMatch(source, /createVrThreeStarFieldMaterialProfile/);
+  assert.match(source, /createSkykitXrRayVisualPlugin/);
+  assert.match(source, /createSurfaceShell/);
+  assert.match(source, /createMetaSidecarProviderService/);
+  assert.match(source, /deriveMetaSidecarUrlFromRenderUrl/);
+  assert.match(source, /metaSidecarEntryDisplayFields/);
+  assert.match(source, /datasetId:\s*DATASET_ID_c56103/);
+  assert.match(source, /attributes:\s*\[\s*'objectRef'\s*,\s*'pickMeta'\s*\]/);
+  assert.match(source, /selectSun:\s*'xr-demo:selected\.sun'/);
+  assert.match(source, /primaryActionId:\s*XR_DEMO_ACTIONS\.goSelected/);
+  assert.match(source, /primaryActionLabel:\s*'Fly to'/);
+  assert.match(source, /homeControl:\s*'button'/);
+  assert.match(source, /pointerType:\s*'ray'/);
+  assert.doesNotMatch(source, /dragThreshold/);
+  assert.doesNotMatch(source, /createChoiceGroup/);
+  assert.doesNotMatch(source, /createSlider/);
+  assert.doesNotMatch(source, /createToggle/);
+  assert.doesNotMatch(source, /createStack/);
+  assert.doesNotMatch(source, /waypointPrefix/);
+  assert.doesNotMatch(source, /panelState\.page/);
+});
+
 test('skykit/xr rig builds multi-root hierarchy', () => {
   const camera = new THREE.PerspectiveCamera();
   const rig = createSkykitXrRig({
@@ -102,6 +130,32 @@ test('skykit/xr depth helpers compute and apply render state', () => {
   assert.deepEqual(state, { depthNear: range.depthNear, depthFar: range.depthFar });
 });
 
+test('skykit/xr depth helpers include distant visible star bounds', () => {
+  const range = computeSkykitXrDepthRange({
+    observer: { x: 0, y: 0, z: 0 },
+    visibleBounds: {
+      min: { x: 62, y: 602, z: -13 },
+      max: { x: 64, y: 604, z: -11 },
+    },
+    observerCentricSpheres: [{ radiusNavigationUnits: 16 }],
+    scale: {
+      navigationUnits: 'pc',
+      metersPerNavigationUnit: 1,
+      worldUnitsPerNavigationUnit: 1,
+    },
+    policy: {
+      near: 0.03,
+      minFar: 100,
+      maxFar: 2000000,
+      marginFactor: 1.2,
+    },
+  });
+
+  assert.ok(range.far > 720);
+  assert.ok(range.telemetry.farthestVisibleBoundsDistance > 600);
+  assert.equal(range.telemetry.farthestObserverCentricSphereDistance, 16);
+});
+
 test('skykit/xr session helpers use injected navigator', async () => {
   let ended = false;
   const session = {
@@ -118,7 +172,8 @@ test('skykit/xr session helpers use injected navigator', async () => {
       async isSessionSupported(mode) {
         return mode === 'immersive-vr';
       },
-      async requestSession() {
+      async requestSession(_mode, init) {
+        this.lastInit = init;
         return session;
       },
     },
@@ -126,6 +181,7 @@ test('skykit/xr session helpers use injected navigator', async () => {
   assert.equal(await isSkykitXrModeSupported('immersive-vr', { navigator }), true);
   const handle = await enterSkykitXrSession({ navigator, mode: 'immersive-vr' });
   assert.equal(handle.presenting, true);
+  assert.deepEqual(navigator.xr.lastInit.optionalFeatures, ['local-floor']);
   await exitSkykitXrSession(handle);
   assert.equal(ended, true);
 });
@@ -147,15 +203,20 @@ test('skykit/xr observer rig bridges viewer state to an XR rig without camera re
 
 test('skykit/xr session plugin registers enter/exit actions and syncs snapshot state', async () => {
   let activeSession = null;
+  let requestedReferenceSpaceCount = 0;
   const session = {
     async requestReferenceSpace(type) {
+      requestedReferenceSpaceCount += 1;
       return { type };
     },
     async end() {
       this.ended = true;
+      activeSession = null;
+      renderer.xr.isPresenting = false;
     },
     addEventListener() {},
   };
+  let rendererReferenceSpaceType = null;
   const renderer = {
     xr: {
       enabled: false,
@@ -163,6 +224,9 @@ test('skykit/xr session plugin registers enter/exit actions and syncs snapshot s
       getSession() {
         return activeSession;
       },
+      setReferenceSpaceType(type) {
+        rendererReferenceSpaceType = type;
+      },
       async setSession(nextSession) {
         activeSession = nextSession;
         this.isPresenting = Boolean(nextSession);
@@ -174,7 +238,8 @@ test('skykit/xr session plugin registers enter/exit actions and syncs snapshot s
       async isSessionSupported() {
         return true;
       },
-      async requestSession() {
+      async requestSession(_mode, init) {
+        this.lastInit = init;
         return session;
       },
     },
@@ -195,8 +260,12 @@ test('skykit/xr session plugin registers enter/exit actions and syncs snapshot s
 
   await actions.invoke('skykit:xr.enter');
   assert.equal(renderer.xr.enabled, true);
+  assert.equal(rendererReferenceSpaceType, 'local-floor');
+  assert.deepEqual(navigator.xr.lastInit.optionalFeatures, ['local-floor']);
+  assert.equal(requestedReferenceSpaceCount, 0);
   assert.equal(activeSession, session);
   assert.equal(plugin.getSnapshot().presenting, true);
+  assert.equal(plugin.getSnapshot().enterStage, 'presenting');
 
   const frame = createXrFrame({ renderer });
   part.update(frame);
@@ -240,6 +309,58 @@ test('skykit/xr navigation plugin updates viewer state from controller axes', ()
   assert.deepEqual(actions.getControlValue('skykit:ship.control.move'), { x: 0, y: 0, z: -10 });
 });
 
+test('skykit/xr ray visual shows the controller ray and shortens at blockers', () => {
+  let part = null;
+  let disposedRaySource = false;
+  const plugin = createSkykitXrRayVisualPlugin({
+    raySource: {
+      getRay() {
+        return {
+          id: 'ray',
+          kind: 'target-ray',
+          handedness: 'right',
+          origin: { x: 1, y: 2, z: 3 },
+          direction: { x: 0, y: 0, z: -1 },
+          length: 10,
+        };
+      },
+      getSnapshot() {
+        return { id: 'ray-source' };
+      },
+      dispose() {
+        disposedRaySource = true;
+      },
+    },
+    blockers: [{
+      blockRay() {
+        return { blocked: true, distance: 3, hit: { componentId: 'panel' } };
+      },
+    }],
+  });
+  const context = createPluginContext({
+    addPart(nextPart) {
+      part = nextPart;
+    },
+  });
+  plugin.setup(context);
+  part.attach(context);
+
+  part.update(createXrFrame());
+
+  assert.equal(part.object3d.visible, true);
+  assert.equal(plugin.getSnapshot().blocked, true);
+  assert.equal(plugin.getSnapshot().lastLength, 3);
+  assert.deepEqual(
+    Array.from(part.object3d.children[0].geometry.getAttribute('position').array),
+    [1, 2, 3, 1, 2, 0],
+  );
+
+  part.update({ ...createXrFrame(), xr: { presenting: false } });
+  assert.equal(part.object3d.visible, false);
+  part.dispose();
+  assert.equal(disposedRaySource, true);
+});
+
 test('skykit/xr star picking fires only on trigger edge and registers attribute-only demand', () => {
   const actions = createSkykitActionRegistry();
   let part = null;

package/src/__tests__/skykit.test.js

@@ -77,6 +77,57 @@ function createRenderer() {
   };
 }
 
+function createTextureRenderer() {
+  const renderer = createRenderer();
+  return {
+    ...renderer,
+    xr: { enabled: true },
+    currentTarget: null,
+    viewport: new THREE.Vector4(0, 0, 1, 1),
+    scissor: new THREE.Vector4(0, 0, 1, 1),
+    scissorTest: false,
+    getRenderTarget() {
+      return this.currentTarget;
+    },
+    setRenderTarget(target) {
+      this.currentTarget = target;
+    },
+    getViewport(target) {
+      return target.copy(this.viewport);
+    },
+    setViewport(value) {
+      if (value?.isVector4) this.viewport.copy(value);
+    },
+    getScissor(target) {
+      return target.copy(this.scissor);
+    },
+    setScissor(value) {
+      if (value?.isVector4) this.scissor.copy(value);
+    },
+    getScissorTest() {
+      return this.scissorTest;
+    },
+    setScissorTest(value) {
+      this.scissorTest = Boolean(value);
+    },
+  };
+}
+
+function createEmbeddedSurfaceSpy() {
+  const publishCalls = [];
+  const unpublishCalls = [];
+  return {
+    publishCalls,
+    unpublishCalls,
+    publish(sourceId, update) {
+      publishCalls.push({ sourceId, update });
+    },
+    unpublish(sourceId) {
+      unpublishCalls.push(sourceId);
+    },
+  };
+}
+
 async function flushMicrotasks(count = 10) {
   for (let index = 0; index < count; index += 1) {
     await Promise.resolve();
@@ -242,6 +293,51 @@ test('viewer exposes action registry, emits action events, and resets to initial
   await viewer.dispose();
 });
 
+test('viewer derives camera orientation from lookAt targets, sky coordinates, and stars', async () => {
+  const targetViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: {
+      observerPc: { x: 0, y: 0, z: 0 },
+      lookAt: { targetPc: { x: 10, y: 0, z: 0 }, positionAngleDeg: 0 },
+    },
+  });
+  let view = targetViewer.getViewState();
+  assert.deepEqual(view.targetPc, { x: 10, y: 0, z: 0 });
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 0, z: -1 }), { x: 1, y: 0, z: 0 });
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 1, z: 0 }), { x: 0, y: 0, z: 1 });
+  await targetViewer.dispose();
+
+  const skyViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: {
+      lookAt: { raDeg: 0, decDeg: 0, positionAngleDeg: 90 },
+    },
+  });
+  view = skyViewer.getViewState();
+  assert.equal(view.targetPc, null);
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 0, z: -1 }), { x: 1, y: 0, z: 0 });
+  assertVectorApprox(localVectorFromView(view, { x: 0, y: 1, z: 0 }), { x: 0, y: 1, z: 0 });
+  await skyViewer.dispose();
+
+  const starViewer = await createSkykitViewer({
+    renderer: createRenderer(),
+    view: { lookAt: { star: 'hyades' } },
+    resolveLookAtStar: async (star) => star === 'hyades'
+      ? { targetPc: { x: 4, y: 5, z: 6 } }
+      : null,
+  });
+  view = starViewer.getViewState();
+  assert.equal(view.lookAt?.star, 'hyades');
+  assert.deepEqual(view.targetPc, { x: 4, y: 5, z: 6 });
+  assert.ok(view.orientationIcrs);
+
+  starViewer.requestViewState({ lookAt: { star: 'orion' } }, 'test-star-look');
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  starViewer.update(0);
+  assert.deepEqual(starViewer.getViewState().targetPc, null);
+  await starViewer.dispose();
+});
+
 test('requestViewState batches patches and observer-centric root follows translation without rotation', async () => {
   const viewer = await createSkykitViewer({
     renderer: createRenderer(),
@@ -682,6 +778,41 @@ test('HR diagram mode changes refresh shared demand and update the renderer view
   await viewer.dispose();
 });
 
+test('HR diagram touch-os surfaces can be resolved lazily from panel runtimes', async () => {
+  const session = createFakeSession();
+  const provider = {
+    id: 'provider',
+    createSession() {
+      return session;
+    },
+  };
+  const source = createSkykitStarSourcePlugin({ provider });
+  const surfaces = createEmbeddedSurfaceSpy();
+  let activeSurfaces = null;
+  const hr = createSkykitHrDiagramPlugin({
+    id: 'hr',
+    source,
+    touchOs: {
+      sourceId: 'hr:surface',
+      surfaces: () => activeSurfaces,
+    },
+  });
+  const viewer = await createSkykitViewer({
+    renderer: createTextureRenderer(),
+    plugins: [source, hr],
+  });
+
+  activeSurfaces = surfaces;
+  viewer.frame(0.016);
+
+  assert.equal(surfaces.publishCalls.length, 1);
+  assert.equal(surfaces.publishCalls[0].sourceId, 'hr:surface');
+  assert.equal(surfaces.publishCalls[0].update.available, true);
+
+  await viewer.dispose();
+  assert.deepEqual(surfaces.unpublishCalls, ['hr:surface']);
+});
+
 test('HR diagram demand strategy override can be supplied and restored at runtime', async () => {
   const sessions = [];
   const provider = {
@@ -1698,7 +1829,7 @@ test('journey plugin can route to non-orbit scenes before applying the arrival t
         },
       },
       local: {
-        view: { targetPc: { x: 1, y: 0, z: 0 } },
+        view: { lookAt: { targetPc: { x: 1, y: 0, z: 0 } } },
         navigation: {
           transitionTo: {
             observerPc: { x: 0, y: 0, z: 0 },
@@ -2323,6 +2454,12 @@ function localVectorFromView(view, vector) {
   return { x: result.x, y: result.y, z: result.z };
 }
 
+function assertVectorApprox(actual, expected, epsilon = 1e-9) {
+  assert.ok(Math.abs(actual.x - expected.x) < epsilon, `x ${actual.x} !== ${expected.x}`);
+  assert.ok(Math.abs(actual.y - expected.y) < epsilon, `y ${actual.y} !== ${expected.y}`);
+  assert.ok(Math.abs(actual.z - expected.z) < epsilon, `z ${actual.z} !== ${expected.z}`);
+}
+
 function createPointerTarget() {
   const target = createEventTarget();
   target.clientWidth = 800;

package/src/anchored-images.js

@@ -107,16 +107,16 @@ export async function createAnchoredImageCatalog(options = {}) {
         }),
       };
     },
-    resolveNearest(directionIcrs, nearestOptions = {}) {
-      const matches = scoreEntries(directionIcrs, selectEntries(entries, nearestOptions.selection, catalog));
+    resolveNearest(lookDirection, nearestOptions = {}) {
+      const matches = scoreEntries(lookDirection, selectEntries(entries, nearestOptions.selection, catalog));
       if (matches.length === 0) return null;
       const maxAngleRad = optionalAngleRad(nearestOptions.maxAngleDeg);
       return matches.find((match) => maxAngleRad == null || match.viewDistanceRad <= maxAngleRad) ?? null;
     },
-    resolveWithinAngle(directionIcrs, withinOptions) {
+    resolveWithinAngle(lookDirection, withinOptions) {
       const maxAngleRad = requiredAngleRad(withinOptions?.maxAngleDeg);
       if (!Number.isFinite(maxAngleRad)) return [];
-      return scoreEntries(directionIcrs, selectEntries(entries, withinOptions?.selection, catalog))
+      return scoreEntries(lookDirection, selectEntries(entries, withinOptions?.selection, catalog))
         .filter((match) => match.viewDistanceRad <= maxAngleRad);
     },
   };
@@ -308,7 +308,8 @@ export function createAnchoredImageSkyPlugin(options) {
         id,
         priority: options.priority,
         object3d: root,
-        anchorMode: fixedAtInfinity ? 'observer-centric' : 'world-space',
+        anchorMode: options.anchorMode ?? (fixedAtInfinity ? 'observer-centric' : 'world-space'),
+        scaleBandId: options.scaleBandId,
       });
       pluginContext.addPart({
         ...layer,
@@ -661,26 +662,24 @@ function targetDirectionAt(solved, x, y) {
 
 /** @param {SkykitViewState} view @returns {Vector3Like} */
 function resolveViewDirection(view) {
-  const explicitDirection = normalizeVector3(view.directionIcrs, null);
-  if (explicitDirection) return explicitDirection;
-  const orientation = normalizeQuaternion(view.orientationIcrs);
-  if (orientation) return normalizeVector3(rotateVectorByQuaternion(LOCAL_FORWARD, orientation), LOCAL_FORWARD) ?? { ...LOCAL_FORWARD };
   const targetPc = normalizeVector3(view.targetPc, null);
   const observerPc = normalizeVector3(view.observerPc, { x: 0, y: 0, z: 0 }) ?? { x: 0, y: 0, z: 0 };
   if (targetPc) {
     const direction = normalizeVector3(subtractVectors(targetPc, observerPc), null);
     if (direction) return direction;
   }
+  const orientation = normalizeQuaternion(view.orientationIcrs);
+  if (orientation) return normalizeVector3(rotateVectorByQuaternion(LOCAL_FORWARD, orientation), LOCAL_FORWARD) ?? { ...LOCAL_FORWARD };
   return { ...LOCAL_FORWARD };
 }
 
 /**
- * @param {Vector3Like | [number, number, number]} directionIcrs
+ * @param {Vector3Like | [number, number, number]} lookDirection
  * @param {AnchoredImageCatalogEntry[]} entries
  * @returns {AnchoredImageMatch[]}
  */
-function scoreEntries(directionIcrs, entries) {
-  const direction = vector3FromArray(normalizeDirection(directionIcrs));
+function scoreEntries(lookDirection, entries) {
+  const direction = vector3FromArray(normalizeDirection(lookDirection));
   if (!direction) return [];
   return entries
     .map((entry) => scoreEntry(direction, entry))
@@ -689,13 +688,13 @@ function scoreEntries(directionIcrs, entries) {
 }
 
 /**
- * @param {Vector3Like | [number, number, number]} directionIcrs
+ * @param {Vector3Like | [number, number, number]} lookDirection
  * @param {AnchoredImageCatalogEntry | null | undefined} entry
  * @returns {AnchoredImageMatch | null}
  */
-function scoreEntry(directionIcrs, entry) {
+function scoreEntry(lookDirection, entry) {
   if (!entry) return null;
-  const direction = vector3FromArray(normalizeDirection(directionIcrs));
+  const direction = vector3FromArray(normalizeDirection(lookDirection));
   if (!direction) return null;
   const angleRad = angularDistance(direction, entry.centroidIcrs);
   const viewDistanceRad = Math.max(0, angleRad - entry.boundsConeRadiusRad);

package/src/browser-addons.d.ts

@@ -0,0 +1,16 @@
+import type {
+  SkykitBrowser,
+  SkykitBrowserAddon,
+  SkykitBrowserGlobal,
+} from './browser.js';
+
+export declare function installSkykitBrowserGlobal(target?: typeof globalThis): SkykitBrowserGlobal;
+export declare function registerBrowserAddon(
+  service: SkykitBrowserGlobal,
+  addon: SkykitBrowserAddon
+): () => void;
+export declare function registerBrowserInstance(
+  service: SkykitBrowserGlobal,
+  host: unknown,
+  browser: SkykitBrowser
+): () => void;

package/src/browser-addons.js

@@ -0,0 +1,155 @@
+const STATE = Symbol.for('found-in-space.skykit.browserAddons');
+const GLOBAL_NAME = 'Skykit';
+
+/**
+ * Install or upgrade the small global service used by the noob embed path.
+ *
+ * @param {typeof globalThis} [target]
+ * @returns {import('./browser.d.ts').SkykitBrowserGlobal}
+ */
+export function installSkykitBrowserGlobal(target = globalThis) {
+  const globalTarget = /** @type {typeof globalThis & { Skykit?: Partial<import('./browser.d.ts').SkykitBrowserGlobal> & Record<PropertyKey, unknown> }} */ (target);
+  const service = /** @type {Partial<import('./browser.d.ts').SkykitBrowserGlobal> & Record<PropertyKey, unknown>} */ (
+    globalTarget[GLOBAL_NAME] && typeof globalTarget[GLOBAL_NAME] === 'object'
+      ? globalTarget[GLOBAL_NAME]
+      : {}
+  );
+  const state = getState(service);
+  const queuedAddons = Array.isArray(service.browserAddons)
+    ? service.browserAddons.splice(0)
+    : [];
+
+  service.browserAddons = state.addons;
+  service.registerBrowserAddon = (addon) => registerBrowserAddon(service, addon);
+  service.whenReady = (targetOrSelector) => whenReady(service, targetOrSelector);
+  service.getBrowsers = () => state.records.map((record) => record.browser);
+  globalTarget[GLOBAL_NAME] = service;
+
+  for (const addon of queuedAddons) {
+    registerBrowserAddon(service, addon);
+  }
+
+  return /** @type {import('./browser.d.ts').SkykitBrowserGlobal} */ (service);
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowserGlobal} service
+ * @param {import('./browser.d.ts').SkykitBrowserAddon} addon
+ */
+export function registerBrowserAddon(service, addon) {
+  if (!addon || typeof addon.install !== 'function') {
+    throw new TypeError('SkyKit browser add-ons must provide install(context).');
+  }
+  const state = getState(service);
+  if (state.addons.includes(addon)) return () => {};
+  state.addons.push(addon);
+  for (const record of state.records) {
+    void installAddonOnRecord(record, addon);
+  }
+  return () => {
+    const index = state.addons.indexOf(addon);
+    if (index >= 0) state.addons.splice(index, 1);
+  };
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowserGlobal} service
+ * @param {unknown} host
+ * @param {import('./browser.d.ts').SkykitBrowser} browser
+ * @returns {() => void}
+ */
+export function registerBrowserInstance(service, host, browser) {
+  const state = getState(service);
+  const record = {
+    host,
+    browser,
+    installedAddonIds: new Set(),
+  };
+  state.records.push(record);
+  for (const addon of state.addons) {
+    void installAddonOnRecord(record, addon);
+  }
+  resolveWaiters(state, record);
+  return () => {
+    const index = state.records.indexOf(record);
+    if (index >= 0) state.records.splice(index, 1);
+  };
+}
+
+/**
+ * @param {Partial<import('./browser.d.ts').SkykitBrowserGlobal> & Record<PropertyKey, unknown>} service
+ * @returns {{
+ *   addons: import('./browser.d.ts').SkykitBrowserAddon[];
+ *   records: Array<{ host: unknown; browser: import('./browser.d.ts').SkykitBrowser; installedAddonIds: Set<string> }>;
+ *   waiters: Array<{ target: unknown; resolve: (browser: import('./browser.d.ts').SkykitBrowser) => void; reject: (error: unknown) => void }>;
+ * }}
+ */
+function getState(service) {
+  if (!service[STATE]) {
+    Object.defineProperty(service, STATE, {
+      configurable: false,
+      enumerable: false,
+      value: {
+        addons: [],
+        records: [],
+        waiters: [],
+      },
+    });
+  }
+  return /** @type {ReturnType<typeof getState>} */ (service[STATE]);
+}
+
+/**
+ * @param {ReturnType<typeof getState>['records'][number]} record
+ * @param {import('./browser.d.ts').SkykitBrowserAddon} addon
+ */
+async function installAddonOnRecord(record, addon) {
+  const addonId = addon.id ?? addon.install;
+  const dedupeId = typeof addonId === 'string' ? addonId : String(record.installedAddonIds.size + 1);
+  if (record.installedAddonIds.has(dedupeId)) return;
+  record.installedAddonIds.add(dedupeId);
+  await record.browser.install(addon);
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowserGlobal} service
+ * @param {unknown} target
+ * @returns {Promise<import('./browser.d.ts').SkykitBrowser>}
+ */
+function whenReady(service, target) {
+  const state = getState(service);
+  const existing = state.records.find((record) => matchesTarget(record.host, target));
+  if (existing) return Promise.resolve(existing.browser);
+  return new Promise((resolve, reject) => {
+    state.waiters.push({ target, resolve, reject });
+  });
+}
+
+/**
+ * @param {ReturnType<typeof getState>} state
+ * @param {ReturnType<typeof getState>['records'][number]} record
+ */
+function resolveWaiters(state, record) {
+  for (const waiter of [...state.waiters]) {
+    if (!matchesTarget(record.host, waiter.target)) continue;
+    const index = state.waiters.indexOf(waiter);
+    if (index >= 0) state.waiters.splice(index, 1);
+    waiter.resolve(record.browser);
+  }
+}
+
+/** @param {unknown} host @param {unknown} target */
+function matchesTarget(host, target) {
+  if (target == null) return true;
+  if (target === host) return true;
+  if (typeof target !== 'string') return false;
+  const element = /** @type {{ matches?: (selector: string) => boolean }} */ (host);
+  if (typeof element.matches === 'function') {
+    try {
+      if (element.matches(target)) return true;
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}

package/src/browser-constellations.d.ts

@@ -0,0 +1,13 @@
+import type {
+  SkykitBrowser,
+  SkykitBrowserConstellationsFacade,
+  SkykitBrowserConstellationsOptions,
+} from './browser.js';
+
+export declare function installSkykitConstellationsBrowserCapability(
+  context: {
+    browser: SkykitBrowser;
+    host?: unknown;
+    options?: SkykitBrowserConstellationsOptions;
+  }
+): Promise<SkykitBrowserConstellationsFacade>;