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

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>;

package/src/browser-constellations.js

@@ -0,0 +1,387 @@
+import * as THREE from 'three';
+
+import { raDecToIcrsDirection } from '@found-in-space/spatial';
+
+import {
+  createAnchoredImageCatalog,
+  createAnchoredImageSkyPlugin,
+  createViewAnchoredImageController,
+} from './anchored-images.js';
+import { createObject3dLayer } from './layers.js';
+
+const CONSTELLATIONS_CAPABILITY = 'skykit:browser.constellations';
+const WESTERN_SKYCULTURE_VERSION = '0.3.0';
+const WESTERN_SKYCULTURE_BASE =
+  `https://cdn.jsdelivr.net/npm/@found-in-space/stellarium-skycultures-western@${WESTERN_SKYCULTURE_VERSION}/dist/`;
+const WESTERN_SKYCULTURE_MANIFEST = `${WESTERN_SKYCULTURE_BASE}manifest.json`;
+const DEFAULT_BOUNDARY_RADIUS = 8;
+
+/**
+ * @param {{
+ *   browser: import('./browser.d.ts').SkykitBrowser;
+ *   host?: unknown;
+ *   options?: import('./browser.d.ts').SkykitBrowserConstellationsOptions;
+ * }} context
+ * @returns {Promise<import('./browser.d.ts').SkykitBrowserConstellationsFacade>}
+ */
+export async function installSkykitConstellationsBrowserCapability({ browser, host, options = {} }) {
+  const settings = normalizeConstellationOptions(host, options);
+  const loaded = await loadSkycultureManifest(settings);
+  const manifest = loaded.manifest;
+  const assetBaseUrl = settings.assetBaseUrl ?? loaded.assetBaseUrl;
+  const root = createConstellationBoundaryObject(manifest, settings);
+  let visible = settings.visible !== false;
+  let artMode = normalizeArtMode(settings.art);
+  /** @type {import('./index.d.ts').SkykitPluginTeardown | null} */
+  let boundaryTeardown = null;
+  /** @type {import('./index.d.ts').SkykitPluginTeardown | null} */
+  let artTeardown = null;
+  /** @type {import('./index.d.ts').AnchoredImageSkyPlugin | null} */
+  let artPlugin = null;
+
+  root.visible = visible;
+  boundaryTeardown = await browser.install({
+    id: 'constellation-boundaries',
+    setup(context) {
+      const layer = createObject3dLayer({
+        id: 'constellation-boundaries',
+        object3d: root,
+        anchorMode: 'observer-centric',
+        priority: settings.priority,
+      });
+      const remove = context.addPart({
+        ...layer,
+        dispose() {
+          layer.dispose?.();
+          disposeObject(root);
+        },
+        getSnapshot() {
+          return {
+            id: 'constellation-boundaries',
+            visible: root.visible,
+            lineCount: root.userData.lineCount ?? 0,
+          };
+        },
+      });
+      return remove;
+    },
+  });
+  browser.capabilities.add(CONSTELLATIONS_CAPABILITY);
+
+  if (artMode !== 'off') {
+    await installArt();
+  }
+
+  const handle = {
+    async load() {
+      return handle;
+    },
+    show() {
+      visible = true;
+      syncVisibility(browser, root, visible);
+      return visible;
+    },
+    hide() {
+      visible = false;
+      syncVisibility(browser, root, visible);
+      return visible;
+    },
+    toggle(force) {
+      visible = typeof force === 'boolean' ? force : !visible;
+      syncVisibility(browser, root, visible);
+      return visible;
+    },
+    async setArt(mode) {
+      artMode = normalizeArtMode(mode);
+      if (artMode === 'off') {
+        artTeardown?.();
+        artTeardown = null;
+        artPlugin = null;
+        return artMode;
+      }
+      await installArt();
+      return artMode;
+    },
+    getSnapshot() {
+      return {
+        capability: CONSTELLATIONS_CAPABILITY,
+        visible,
+        art: artMode,
+        manifestId: manifest.id ?? null,
+        lineCount: root.userData.lineCount ?? 0,
+        artPlugin: artPlugin?.getSnapshot?.() ?? null,
+      };
+    },
+    dispose() {
+      artTeardown?.();
+      boundaryTeardown?.();
+      artTeardown = null;
+      boundaryTeardown = null;
+      artPlugin = null;
+    },
+  };
+
+  return handle;
+
+  async function installArt() {
+    if (artPlugin) return;
+    const catalog = await createAnchoredImageCatalog({
+      manifest: toAnchoredImageManifest(manifest, assetBaseUrl),
+    });
+    artPlugin = createAnchoredImageSkyPlugin({
+      id: 'constellation-art',
+      catalog,
+      controller: createViewAnchoredImageController({
+        strategy: 'nearest',
+        maxAngleDeg: finiteNumber(settings.artMaxAngleDeg, 60),
+      }),
+      loading: artMode === 'preload' ? 'preload' : 'lazy',
+      opacity: finiteNumber(settings.artOpacity, 0.22),
+      skipTextureErrors: settings.skipTextureErrors !== false,
+    });
+    artTeardown = await browser.install(artPlugin);
+    syncVisibility(browser, root, visible);
+  }
+}
+
+/**
+ * @param {unknown} host
+ * @param {import('./browser.d.ts').SkykitBrowserConstellationsOptions} options
+ * @returns {import('./browser.d.ts').SkykitBrowserConstellationsOptions}
+ */
+function normalizeConstellationOptions(host, options) {
+  const data = host && typeof host === 'object' && 'dataset' in host
+    ? /** @type {{ dataset?: Record<string, string | undefined> }} */ (host).dataset ?? {}
+    : {};
+  const requested = options.skyculture ?? data.skykitConstellations ?? 'western';
+  const manifestUrl = options.manifestUrl
+    ?? data.skykitConstellationManifest
+    ?? (looksLikeUrl(requested) ? String(requested) : undefined)
+    ?? (String(requested || 'western').toLowerCase() === 'western' ? WESTERN_SKYCULTURE_MANIFEST : undefined);
+  const assetBaseUrl = options.assetBaseUrl
+    ?? data.skykitConstellationAssets
+    ?? (manifestUrl ? new URL('./', manifestUrl).href : undefined)
+    ?? WESTERN_SKYCULTURE_BASE;
+  return {
+    ...options,
+    skyculture: requested,
+    manifestUrl,
+    assetBaseUrl,
+    art: options.art ?? data.skykitConstellationArt ?? 'off',
+  };
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowserConstellationsOptions} options
+ * @returns {Promise<{ manifest: Record<string, unknown>; assetBaseUrl?: string }>}
+ */
+async function loadSkycultureManifest(options) {
+  if (options.manifest && typeof options.manifest === 'object') {
+    return {
+      manifest: /** @type {Record<string, unknown>} */ (options.manifest),
+      assetBaseUrl: options.assetBaseUrl,
+    };
+  }
+  const manifestUrl = options.manifestUrl ?? WESTERN_SKYCULTURE_MANIFEST;
+  const response = await fetch(manifestUrl);
+  if (!response.ok) throw new Error(`Failed to load SkyKit constellation manifest: ${response.status} ${response.statusText}`);
+  return {
+    manifest: /** @type {Record<string, unknown>} */ (await response.json()),
+    assetBaseUrl: options.assetBaseUrl ?? new URL('./', manifestUrl).href,
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} manifest
+ * @param {import('./browser.d.ts').SkykitBrowserConstellationsOptions} options
+ */
+function createConstellationBoundaryObject(manifest, options) {
+  const root = new THREE.Group();
+  root.name = 'constellation-boundaries';
+  const radius = finiteNumber(options.boundaryRadius, DEFAULT_BOUNDARY_RADIUS);
+  const positions = boundaryPositions(manifest, radius);
+  const geometry = new THREE.BufferGeometry();
+  geometry.setAttribute('position', new THREE.Float32BufferAttribute(positions, 3));
+  const material = new THREE.LineBasicMaterial({
+    color: options.boundaryColor ?? 0x7aa7ff,
+    transparent: true,
+    opacity: finiteNumber(options.boundaryOpacity, 0.35),
+    depthWrite: false,
+  });
+  const lines = new THREE.LineSegments(geometry, material);
+  lines.name = 'constellation-boundary-lines';
+  lines.renderOrder = finiteNumber(options.renderOrder, -2);
+  root.add(lines);
+  root.userData.lineCount = positions.length / 6;
+  return root;
+}
+
+/** @param {Record<string, unknown>} manifest @param {number} radius */
+function boundaryPositions(manifest, radius) {
+  const boundaries = /** @type {{ edges?: unknown }} */ (manifest.boundaries ?? {});
+  const edges = Array.isArray(boundaries.edges) ? boundaries.edges : [];
+  /** @type {number[]} */
+  const positions = [];
+  for (const edge of edges) {
+    if (typeof edge !== 'string') continue;
+    const parts = edge.trim().split(/\s+/);
+    if (parts.length < 6) continue;
+    const start = directionFromRaDecText(parts[2], parts[3]);
+    const end = directionFromRaDecText(parts[4], parts[5]);
+    if (!start || !end) continue;
+    positions.push(
+      start.x * radius, start.y * radius, start.z * radius,
+      end.x * radius, end.y * radius, end.z * radius,
+    );
+  }
+  return positions;
+}
+
+/** @param {string} raText @param {string} decText */
+function directionFromRaDecText(raText, decText) {
+  const raHours = parseSexagesimal(raText);
+  const decDeg = parseSexagesimal(decText);
+  if (!Number.isFinite(raHours) || !Number.isFinite(decDeg)) return null;
+  return raDecToIcrsDirection({ raHours, decDeg });
+}
+
+/** @param {string} value */
+function parseSexagesimal(value) {
+  const sign = value.trim().startsWith('-') ? -1 : 1;
+  const clean = value.trim().replace(/^[+-]/, '');
+  const parts = clean.split(':').map(Number);
+  if (parts.some((part) => !Number.isFinite(part))) return Number.NaN;
+  return sign * (parts[0] + (parts[1] ?? 0) / 60 + (parts[2] ?? 0) / 3600);
+}
+
+/** @param {Record<string, unknown>} manifest @param {string | undefined} assetBaseUrl */
+function toAnchoredImageManifest(manifest, assetBaseUrl) {
+  const constellations = Array.isArray(manifest.constellations) ? manifest.constellations : [];
+  return {
+    format: 'found-in-space/anchored-image-manifest@1',
+    id: String(manifest.id ?? 'constellations'),
+    label: String(manifest.id ?? 'Constellations'),
+    assetBaseUrl: assetBaseUrl ?? null,
+    images: constellations.map((constellation, index) => toAnchoredImage(constellation, assetBaseUrl, index)).filter(Boolean),
+    attribution: manifest.license,
+    metadata: {
+      sourceFormat: manifest.format,
+      sourcePackage: manifest.source,
+      astrometry: manifest.astrometry,
+    },
+  };
+}
+
+/** @param {unknown} input @param {string | undefined} assetBaseUrl @param {number} index */
+function toAnchoredImage(input, assetBaseUrl, index) {
+  const constellation = /** @type {Record<string, unknown>} */ (input && typeof input === 'object' ? input : {});
+  const image = /** @type {Record<string, unknown>} */ (constellation.image && typeof constellation.image === 'object' ? constellation.image : {});
+  const imageFile = typeof image.file === 'string' ? image.file : '';
+  const anchors = Array.isArray(image.anchors) ? image.anchors.map(toAnchoredImageAnchor).filter(Boolean) : [];
+  if (!imageFile || anchors.length < 2) return null;
+  return {
+    id: String(constellation.id ?? constellation.iau ?? `constellation-${index}`),
+    label: resolveConstellationLabel(constellation),
+    groupId: typeof constellation.iau === 'string' ? constellation.iau : undefined,
+    image: {
+      src: typeof image.url === 'string'
+        ? image.url
+        : assetBaseUrl
+          ? new URL(imageFile, assetBaseUrl).href
+          : imageFile,
+      width: Array.isArray(image.size) ? Number(image.size[0]) || 512 : 512,
+      height: Array.isArray(image.size) ? Number(image.size[1]) || 512 : 512,
+      anchors,
+    },
+    metadata: {
+      sourceConstellationId: constellation.id ?? null,
+      iau: constellation.iau ?? null,
+      common_name: constellation.common_name ?? null,
+    },
+  };
+}
+
+/** @param {unknown} input */
+function toAnchoredImageAnchor(input) {
+  const anchor = /** @type {Record<string, unknown>} */ (input && typeof input === 'object' ? input : {});
+  const icrs = /** @type {Record<string, unknown>} */ (anchor.icrs && typeof anchor.icrs === 'object' ? anchor.icrs : {});
+  const pixel = /** @type {Record<string, unknown>} */ (anchor.pixel && typeof anchor.pixel === 'object' ? anchor.pixel : {});
+  const target = {
+    x: Number(icrs.x),
+    y: Number(icrs.y),
+    z: Number(icrs.z),
+  };
+  const point = {
+    x: Number(pixel.x),
+    y: Number(pixel.y),
+  };
+  if (!Number.isFinite(target.x) || !Number.isFinite(target.y) || !Number.isFinite(target.z)) return null;
+  if (!Number.isFinite(point.x) || !Number.isFinite(point.y)) return null;
+  return {
+    pixel: point,
+    target: {
+      kind: 'direction',
+      frame: 'icrs',
+      ...target,
+    },
+    metadata: {
+      hip: anchor.hip,
+      raDeg: anchor.raDeg,
+      decDeg: anchor.decDeg,
+    },
+  };
+}
+
+/** @param {Record<string, unknown>} constellation */
+function resolveConstellationLabel(constellation) {
+  const commonName = constellation.common_name;
+  if (commonName && typeof commonName === 'object') {
+    const source = /** @type {Record<string, unknown>} */ (commonName);
+    if (typeof source.native === 'string' && source.native.trim()) return source.native.trim();
+    if (typeof source.english === 'string' && source.english.trim()) return source.english.trim();
+  }
+  return String(constellation.iau ?? constellation.id ?? 'Constellation');
+}
+
+/**
+ * @param {import('./browser.d.ts').SkykitBrowser} browser
+ * @param {THREE.Object3D} boundaryRoot
+ * @param {boolean} visible
+ */
+function syncVisibility(browser, boundaryRoot, visible) {
+  boundaryRoot.visible = visible;
+  const artRoot = browser.viewer.roots.observerContentRoot.children.find((child) => child.name === 'constellation-art');
+  if (artRoot) artRoot.visible = visible;
+}
+
+/** @param {unknown} value */
+function normalizeArtMode(value) {
+  const mode = String(value ?? 'off').trim().toLowerCase();
+  if (mode === 'preload') return 'preload';
+  if (mode === 'lazy' || mode === 'on' || mode === 'true') return 'lazy';
+  return 'off';
+}
+
+/** @param {unknown} value */
+function looksLikeUrl(value) {
+  return typeof value === 'string' && (/^https?:\/\//.test(value) || value.endsWith('.json'));
+}
+
+/** @param {unknown} value @param {number} fallback */
+function finiteNumber(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) ? number : fallback;
+}
+
+/** @param {THREE.Object3D} object */
+function disposeObject(object) {
+  object.traverse((child) => {
+    const mesh = /** @type {THREE.Object3D & { geometry?: { dispose?: () => void }; material?: { dispose?: () => void } | Array<{ dispose?: () => void }> }} */ (child);
+    mesh.geometry?.dispose?.();
+    if (Array.isArray(mesh.material)) {
+      for (const material of mesh.material) material.dispose?.();
+    } else {
+      mesh.material?.dispose?.();
+    }
+  });
+}

package/src/browser-journey.d.ts

@@ -0,0 +1,8 @@
+import type {
+  SkykitBrowser,
+  SkykitBrowserJourneyFacade,
+} from './browser.js';
+
+export declare function installSkykitJourneyBrowserCapability(
+  context: { browser: SkykitBrowser }
+): Promise<SkykitBrowserJourneyFacade>;