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

package/src/browser.d.ts

@@ -7,13 +7,18 @@ import type { ThreeStarField } from '@found-in-space/three-star-field';
 import type * as THREE from 'three';
 
 import type {
+  Object3dLayerOptions,
   SkykitAnimationLoop,
   SkykitAnimationLoopOptions,
   SkykitDragLookOptions,
+  SkykitLookAtInput,
   SkykitKeyboardNavigationOptions,
   SkykitPluginInput,
+  SkykitPluginTeardown,
+  SkykitThreePart,
   SkykitViewState,
   SkykitViewer,
+  Vector3Like,
 } from './index.js';
 
 export type SkykitBrowserHost = string | {
@@ -25,6 +30,78 @@ export type SkykitBrowserHost = string | {
 };
 
 export type SkykitBrowserStatusTarget = string | { textContent?: string | null };
+export type SkykitBrowserMouseMode = 'grab' | 'look' | 'strafe' | 'none';
+export type SkykitConstellationArtMode = 'off' | 'lazy' | 'preload';
+
+export interface SkykitBrowserAddonContext {
+  id?: string;
+  host: SkykitBrowserHost | Element;
+  browser: SkykitBrowser;
+  viewer: SkykitViewer;
+  THREE: typeof THREE;
+  skykit: Record<string, unknown>;
+}
+
+export interface SkykitBrowserAddon {
+  id?: string;
+  install(
+    context: SkykitBrowserAddonContext
+  ): void | Promise<void> | SkykitPluginTeardown | Promise<SkykitPluginTeardown | void>;
+}
+
+export type SkykitBrowserInstallInput = SkykitPluginInput | SkykitBrowserAddon;
+
+export interface SkykitBrowserGlobal {
+  browserAddons: SkykitBrowserAddon[];
+  registerBrowserAddon(addon: SkykitBrowserAddon): SkykitPluginTeardown;
+  whenReady(target?: string | Element): Promise<SkykitBrowser>;
+  getBrowsers(): SkykitBrowser[];
+}
+
+export interface SkykitBrowserJourneyFacade {
+  transitionTo(viewOrScene: unknown, options?: Record<string, unknown>): Promise<PromiseSettledResult<unknown>[]>;
+  applyScene(sceneSpec: unknown): Promise<unknown>;
+  load(input: string | Record<string, unknown>, options?: Record<string, unknown>): Promise<SkykitBrowserJourneyInstance>;
+  getSnapshot(): unknown | Promise<unknown>;
+}
+
+export interface SkykitBrowserJourneyInstance {
+  goTo(sceneId: string): Promise<unknown>;
+  next(): Promise<unknown>;
+  previous(): Promise<unknown>;
+  play(payload?: unknown): number;
+  pause(): number;
+  seek(timeSecs: number): number;
+  getSnapshot(): unknown;
+  dispose(): void;
+}
+
+export interface SkykitBrowserConstellationsOptions {
+  skyculture?: string;
+  manifest?: Record<string, unknown>;
+  manifestUrl?: string;
+  assetBaseUrl?: string;
+  art?: SkykitConstellationArtMode | string;
+  visible?: boolean;
+  priority?: number;
+  boundaryRadius?: number;
+  boundaryColor?: THREE.ColorRepresentation;
+  boundaryOpacity?: number;
+  renderOrder?: number;
+  artOpacity?: number;
+  artMaxAngleDeg?: number;
+  skipTextureErrors?: boolean;
+}
+
+export interface SkykitBrowserConstellationsFacade {
+  load(options?: SkykitBrowserConstellationsOptions): Promise<SkykitBrowserConstellationsFacade>;
+  show(): boolean | Promise<boolean>;
+  hide(): boolean | Promise<boolean>;
+  toggle(force?: boolean): boolean | Promise<boolean>;
+  setArt(mode: SkykitConstellationArtMode | string): SkykitConstellationArtMode | Promise<SkykitConstellationArtMode>;
+  getSnapshot(): unknown | Promise<unknown>;
+  dispose?(): void;
+}
 
 export interface SkykitBrowserOptions {
   host?: SkykitBrowserHost;
@@ -38,8 +115,10 @@ export interface SkykitBrowserOptions {
   session?: StarOctreeSessionOptions;
   keyboard?: false | SkykitKeyboardNavigationOptions;
   grab?: false | SkykitDragLookOptions;
+  mouseMode?: SkykitBrowserMouseMode;
   plugins?: Iterable<SkykitPluginInput>;
   view?: Partial<SkykitViewState>;
+  lookAt?: SkykitLookAtInput;
   loop?: SkykitAnimationLoopOptions;
   limitingMagnitude?: number;
   exposure?: number;
@@ -64,9 +143,28 @@ export interface SkykitBrowser {
   provider: StarOctreeProviderService;
   starField: ThreeStarField;
   loop: SkykitAnimationLoop;
+  capabilities: Set<string>;
+  journey: SkykitBrowserJourneyFacade;
+  constellations: SkykitBrowserConstellationsFacade;
+  install(input: SkykitBrowserInstallInput): Promise<SkykitPluginTeardown>;
+  addObject(
+    object3d: THREE.Object3D,
+    options?: SkykitBrowserObjectOptions
+  ): SkykitBrowserObjectHandle;
   resize(): void;
   dispose(): Promise<void>;
 }
 
+export interface SkykitBrowserObjectOptions extends Omit<Object3dLayerOptions, 'object3d'> {
+  positionPc?: Vector3Like;
+}
+
+export interface SkykitBrowserObjectHandle {
+  object3d: THREE.Object3D;
+  part: SkykitThreePart;
+  remove: SkykitPluginTeardown;
+  dispose: SkykitPluginTeardown;
+}
+
 export declare function createSkykitBrowser(host: SkykitBrowserHost): Promise<SkykitBrowser>;
 export declare function createSkykitBrowser(options?: SkykitBrowserOptions): Promise<SkykitBrowser>;

package/src/browser.js

@@ -8,12 +8,18 @@ import { createObserverShellStrategy } from '@found-in-space/star-trees';
 import { createThreeStarField } from '@found-in-space/three-star-field';
 
 import { createSkykitAnimationLoop } from './animation-loop.js';
+import { SKYKIT_ACTIONS, SKYKIT_CONTROLS } from './actions.js';
 import {
   createKeyboardNavigationPlugin,
+  createObject3dPlugin,
+  createMouseLookPlugin,
+  createSkykitJourneyPlugin,
+  createSkykitNavigationPlugin,
   createSkyGrabPlugin,
   createSkykitStatusPlugin,
   createStreamingStarsPlugin,
 } from './plugins.js';
+import { createObject3dLayer } from './layers.js';
 import { createSkykitViewer } from './viewer.js';
 
 const DEFAULT_LIMITING_MAGNITUDE = 6.5;
@@ -63,6 +69,7 @@ export async function createSkykitBrowser(input = {}) {
       observerPc: { x: 0, y: 0, z: 0 },
       coordinateUnitsPerParsec: positive(options.coordinateUnitsPerParsec, DEFAULT_UNITS_PER_PARSEC),
       limitingMagnitude,
+      ...(options.lookAt ? { lookAt: options.lookAt } : {}),
       ...(options.view ?? {}),
     },
     plugins: [
@@ -81,41 +88,57 @@ export async function createSkykitBrowser(input = {}) {
           ...(options.keyboard ?? {}),
         }),
       ]),
-      ...(options.grab === false ? [] : [
-        createSkyGrabPlugin({
-          target: host,
-          sensitivityRadiansPerPixel: 0.00075,
-          ...(options.grab ?? {}),
-        }),
-      ]),
+      ...createPointerPlugins(options, host),
       ...(statusTarget ? [createStatusPlugin(statusTarget)] : []),
       ...(options.plugins ?? []),
     ],
   });
 
   const loop = createSkykitAnimationLoop(viewer, options.loop);
+  const capabilities = new Set();
+  /** @type {Array<() => void | Promise<void>>} */
+  const browserDisposables = [];
   let disposed = false;
+  /** @type {import('./browser.d.ts').SkykitBrowser} */
+  const browser = {
+    viewer,
+    renderer,
+    camera,
+    provider,
+    starField,
+    loop,
+    capabilities,
+    install,
+    addObject,
+    resize,
+    dispose,
+  };
+  browser.journey = createLazyJourneyFacade(browser);
+  browser.constellations = createLazyConstellationsFacade(browser, host);
 
-  const resize = () => {
+  function resize() {
     viewer.resize({
       devicePixelRatio: Math.min(
         window.devicePixelRatio || 1,
         positive(options.maxDevicePixelRatio, DEFAULT_MAX_DEVICE_PIXEL_RATIO),
       ),
     });
-  };
-  const dispose = async () => {
+  }
+  async function dispose() {
     if (disposed) return;
     disposed = true;
     window.removeEventListener('resize', resize);
     window.removeEventListener('pagehide', disposeSoon);
     window.removeEventListener('beforeunload', disposeSoon);
+    for (const disposable of browserDisposables.splice(0).reverse()) {
+      await disposable();
+    }
     loop.dispose();
     await viewer.dispose();
     if (!options.provider) await provider.dispose?.();
     if (!options.renderer) renderer.dispose?.();
-  };
-  const disposeSoon = () => { void dispose(); };
+  }
+  function disposeSoon() { void dispose(); }
 
   if (options.autoResize !== false) window.addEventListener('resize', resize);
   if (options.autoDispose !== false) {
@@ -125,7 +148,173 @@ export async function createSkykitBrowser(input = {}) {
   resize();
   if (options.autoStart !== false) loop.start();
 
-  return { viewer, renderer, camera, provider, starField, loop, resize, dispose };
+  return browser;
+
+  /**
+   * @param {import('./browser.d.ts').SkykitBrowserInstallInput} input
+   * @returns {Promise<import('./index.d.ts').SkykitPluginTeardown>}
+   */
+  async function install(input) {
+    if (!input) return () => {};
+    const teardown = isBrowserAddon(input)
+      ? await input.install(createBrowserAddonContext(input))
+      : await viewer.addPlugin(/** @type {import('./index.d.ts').SkykitPluginInput} */ (input));
+    if (typeof teardown !== 'function') return () => {};
+    browserDisposables.push(teardown);
+    return () => {
+      const index = browserDisposables.indexOf(teardown);
+      if (index >= 0) browserDisposables.splice(index, 1);
+      void teardown();
+    };
+  }
+
+  /**
+   * @param {import('./browser.d.ts').SkykitBrowserAddon} addon
+   * @returns {import('./browser.d.ts').SkykitBrowserAddonContext}
+   */
+  function createBrowserAddonContext(addon) {
+    return {
+      id: addon.id,
+      host,
+      browser,
+      viewer,
+      THREE,
+      skykit: {
+        SKYKIT_ACTIONS,
+        SKYKIT_CONTROLS,
+        createObject3dPlugin,
+        createSkykitJourneyPlugin,
+        createSkykitNavigationPlugin,
+      },
+    };
+  }
+
+  /**
+   * @param {THREE.Object3D} object3d
+   * @param {import('./browser.d.ts').SkykitBrowserObjectOptions} [objectOptions]
+   * @returns {import('./browser.d.ts').SkykitBrowserObjectHandle}
+   */
+  function addObject(object3d, objectOptions = {}) {
+    if (!object3d) {
+      throw new TypeError('SkykitBrowser.addObject() requires a THREE.Object3D.');
+    }
+    const { positionPc, ...layerOptions } = objectOptions;
+    if (positionPc) {
+      setObjectPositionPc(
+        object3d,
+        positionPc,
+        viewer.getViewState().coordinateUnitsPerParsec,
+      );
+    }
+    const part = createObject3dLayer({
+      ...layerOptions,
+      object3d,
+      anchorMode: layerOptions.anchorMode ?? 'world-space',
+    });
+    const remove = viewer.addPart(part);
+    return {
+      object3d,
+      part,
+      remove,
+      dispose: remove,
+    };
+  }
+}
+
+/** @param {unknown} input */
+function isBrowserAddon(input) {
+  return Boolean(input && typeof input === 'object' && typeof /** @type {{ install?: unknown }} */ (input).install === 'function');
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowser} browser
+ * @returns {import('./browser.d.ts').SkykitBrowserJourneyFacade}
+ */
+function createLazyJourneyFacade(browser) {
+  /** @type {Promise<import('./browser.d.ts').SkykitBrowserJourneyFacade> | null} */
+  let loaded = null;
+  const loadCapability = () => {
+    loaded ??= import('./browser-journey.js')
+      .then((module) => module.installSkykitJourneyBrowserCapability({ browser }));
+    return loaded;
+  };
+  return {
+    async transitionTo(viewOrScene, options) {
+      return (await loadCapability()).transitionTo(viewOrScene, options);
+    },
+    async applyScene(sceneSpec) {
+      return (await loadCapability()).applyScene(sceneSpec);
+    },
+    async load(input, options) {
+      return (await loadCapability()).load(input, options);
+    },
+    async getSnapshot() {
+      return (await loadCapability()).getSnapshot();
+    },
+  };
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowser} browser
+ * @param {Element | import('./browser.d.ts').SkykitBrowserHost} host
+ * @returns {import('./browser.d.ts').SkykitBrowserConstellationsFacade}
+ */
+function createLazyConstellationsFacade(browser, host) {
+  /** @type {Promise<import('./browser.d.ts').SkykitBrowserConstellationsFacade> | null} */
+  let loaded = null;
+  const loadCapability = (options = {}) => {
+    loaded ??= import('./browser-constellations.js')
+      .then((module) => module.installSkykitConstellationsBrowserCapability({
+        browser,
+        host,
+        options,
+      }));
+    return loaded;
+  };
+  return {
+    async load(options) {
+      return loadCapability(options);
+    },
+    async show() {
+      return (await loadCapability()).show();
+    },
+    async hide() {
+      return (await loadCapability()).hide();
+    },
+    async toggle(force) {
+      return (await loadCapability()).toggle(force);
+    },
+    async setArt(mode) {
+      return (await loadCapability()).setArt(mode);
+    },
+    async getSnapshot() {
+      return (await loadCapability()).getSnapshot();
+    },
+  };
+}
+
+function createPointerPlugins(options, host) {
+  const mouseMode = normalizeMouseMode(options.mouseMode);
+  if (options.grab === false || mouseMode === 'none') return [];
+  const pointerOptions = {
+    target: host,
+    sensitivityRadiansPerPixel: 0.00075,
+    ...(options.grab ?? {}),
+  };
+  return [
+    mouseMode === 'look' || mouseMode === 'strafe'
+      ? createMouseLookPlugin(pointerOptions)
+      : createSkyGrabPlugin(pointerOptions),
+  ];
+}
+
+function normalizeMouseMode(value) {
+  const mode = String(value ?? 'grab').trim().toLowerCase();
+  if (mode === 'look' || mode === 'mouse-look' || mode === 'mouselook' || mode === 'game' || mode === 'strafe') {
+    return mode === 'strafe' ? 'strafe' : 'look';
+  }
+  if (mode === 'none' || mode === 'off' || mode === 'false') return 'none';
+  return 'grab';
 }
 
 function createStatusPlugin(target) {
@@ -165,3 +354,16 @@ function positive(value, fallback) {
   const number = Number(value);
   return Number.isFinite(number) && number > 0 ? number : fallback;
 }
+
+/**
+ * @param {THREE.Object3D} object3d
+ * @param {{ x: number; y: number; z: number }} positionPc
+ * @param {number} unitsPerParsec
+ */
+function setObjectPositionPc(object3d, positionPc, unitsPerParsec) {
+  object3d.position?.set?.(
+    positionPc.x * unitsPerParsec,
+    positionPc.y * unitsPerParsec,
+    positionPc.z * unitsPerParsec,
+  );
+}

package/src/data.d.ts

@@ -0,0 +1,133 @@
+import type { MetaSidecarEntry, MetaSidecarProviderService } from '@found-in-space/meta-sidecar-provider';
+import type {
+  StarOctreeCellStreamOptions,
+  StarOctreeProviderService,
+  StarOctreeProviderServiceOptions,
+} from '@found-in-space/star-octree-provider';
+import type {
+  StarObjectRef,
+  StarTreePointPc,
+} from '@found-in-space/star-trees';
+
+export {
+  OCTREE_DEFAULT,
+  createStarOctreeProviderService,
+} from '@found-in-space/star-octree-provider';
+export {
+  createObserverShellStrategy,
+  createSphereVolumeStrategy,
+  createStarCellKey,
+  decodeTemperatureK,
+  temperatureToRgb,
+} from '@found-in-space/star-trees';
+export {
+  createMetaSidecarProviderService,
+  deriveMetaSidecarUrlFromRenderUrl,
+  metaSidecarEntryDisplayFields,
+} from '@found-in-space/meta-sidecar-provider';
+
+export interface SkykitStarRow {
+  ref: StarObjectRef | null;
+  cellKey: string;
+  level: number;
+  mortonCode: string;
+  ordinal: number;
+  positionPc: StarTreePointPc;
+  xPc: number;
+  yPc: number;
+  zPc: number;
+  distancePc: number;
+  magAbs: number | null;
+  absoluteMagnitude: number | null;
+  apparentMagnitude: number | null;
+  teffLog8: number | null;
+  temperatureK: number | null;
+}
+
+export interface SkykitRowsFromCellsOptions {
+  observerPc?: StarTreePointPc;
+  limitingMagnitude?: number;
+  filterVisible?: boolean;
+}
+
+export interface SkykitStarDataOptions extends Omit<StarOctreeCellStreamOptions, 'view' | 'strategy'> {
+  provider?: StarOctreeProviderService;
+  providerId?: string;
+  octreeUrl?: string;
+  persistentCache?: StarOctreeProviderServiceOptions['persistentCache'];
+  limits?: StarOctreeProviderServiceOptions['limits'];
+  observerPc?: StarTreePointPc;
+  centerPc?: StarTreePointPc;
+  radiusPc?: number;
+  limitingMagnitude?: number;
+  maxStars?: number;
+  filterVisible?: boolean;
+  sortBy?:
+    | 'apparentMagnitude'
+    | 'distancePc'
+    | 'magAbs'
+    | 'absoluteMagnitude'
+    | null
+    | false
+    | ((left: SkykitStarRow, right: SkykitStarRow) => number);
+  view?: StarOctreeCellStreamOptions['view'];
+  strategy?: StarOctreeCellStreamOptions['strategy'];
+}
+
+export type SkykitStarLabelInput = SkykitStarRow | StarObjectRef;
+
+export interface SkykitStarLabelOptions {
+  metaProvider?: MetaSidecarProviderService;
+  metaProviderId?: string;
+  metaUrl?: string;
+  parentDatasetId?: string;
+  datasetId?: string;
+  persistentCache?: 'on' | 'off';
+  metaLimits?: {
+    shardPrefetchBytes?: number;
+  };
+  provider?: StarOctreeProviderService;
+  octreeUrl?: string;
+}
+
+export interface SkykitStarLabel {
+  star: SkykitStarLabelInput;
+  ref: StarObjectRef | null;
+  entry: MetaSidecarEntry | null;
+  fields: {
+    properName: string;
+    bayer: string;
+    hd: string;
+    hip: string;
+    gaia: string;
+    primaryLabel: string;
+  };
+  label: string;
+}
+
+export declare function createStarStream(
+  options?: SkykitStarDataOptions
+): AsyncIterable<SkykitStarRow[]>;
+
+export declare function loadStarRows(
+  options?: SkykitStarDataOptions
+): Promise<SkykitStarRow[]>;
+
+export declare function streamStarRows(
+  options?: SkykitStarDataOptions
+): AsyncIterable<SkykitStarRow[]>;
+
+export declare function rowsFromStarCells(
+  cells: Iterable<import('@found-in-space/star-trees').StarCellData>,
+  options?: SkykitRowsFromCellsOptions
+): SkykitStarRow[];
+
+export declare function loadStarLabels(
+  input: Iterable<SkykitStarLabelInput> | SkykitStarDataOptions,
+  options?: SkykitStarLabelOptions
+): Promise<SkykitStarLabel[]>;
+
+export declare function formatStarLabel(
+  entry?: MetaSidecarEntry | null,
+  fallback?: string
+): string;