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

package/README.md

@@ -20,17 +20,89 @@ strategies. SkyKit passes strategies through to provider sessions; it does not
 redefine planning, inspect strategy kinds, or hide loader registries behind
 string names.
 
-## Create A Viewer
+## Paste into a static page or CMS
+
+For the beginner path, use the auto-booting embed. Paste this into a static HTML
+page or a CMS custom HTML block:
+
+```html
+<div
+  data-skykit-browser
+  data-skykit-status="#skykit-status"
+  style="width: 100%; height: 70vh; min-height: 420px; background: #02040b"
+></div>
+
+<pre id="skykit-status">Loading stars...</pre>
+
+<script
+  type="module"
+  src="https://esm.sh/@found-in-space/skykit/embed?bundle"
+></script>
+```
+
+The embed script finds every `[data-skykit-browser]` element and creates the
+standard star browser there. It owns the normal beginner plumbing: Three.js
+renderer and camera, the public star provider, the star-field renderer, streaming
+stars, keyboard navigation, drag-to-look controls, resize handling, the animation
+loop, and page-lifecycle cleanup.
+
+Optional attributes keep small tweaks HTML-only:
+
+```html
+<div
+  data-skykit-browser
+  data-skykit-status="#skykit-status"
+  data-skykit-magnitude="7"
+  data-skykit-speed="4"
+  data-skykit-exposure="2600"
+  style="width: 100%; height: 520px; background: #02040b"
+></div>
+```
+
+The host dispatches `skykit-browser-ready` with `{ browser, viewer }` in
+`event.detail` after startup, and `skykit-browser-error` if startup fails. The
+embed does not install a global object, so pages can host multiple viewers.
+
+Pin the CDN URL to a released SkyKit version when publishing long-lived pages,
+for example
+`https://esm.sh/@found-in-space/skykit@x.y.z/embed?bundle&deps=three@0.170.0`.
+
+## Create a browser from JavaScript
+
+If your site has a module script, npm, or a bundler, call the helper directly:
+
+```html
+<div id="viewer" style="width: 100vw; height: 100vh"></div>
+<pre id="status">Loading stars...</pre>
+
+<script type="module">
+  import { createSkykitBrowser } from '@found-in-space/skykit/browser';
+
+  await createSkykitBrowser({
+    host: '#viewer',
+    status: '#status',
+  });
+</script>
+```
+
+The helper still returns the pieces when a lesson wants to grow:
+
+```js
+const sky = await createSkykitBrowser('#viewer');
+
+sky.viewer.requestViewState({ observerPc: { x: 4, y: 0, z: -8 } });
+sky.loop.stop();
+await sky.dispose();
+```
+
+Use the lower-level factories when a lesson is teaching composition or replacing
+a part of the stack:
 
 ```js
 import {
-  SKYKIT_ACTIONS,
-  SKYKIT_DEFAULT_KEYBOARD_NAVIGATION_BINDINGS,
   createKeyboardNavigationPlugin,
-  createSkykitDefaultKeyboardNavigationBindings,
   createSkyGrabPlugin,
   createSkykitAnimationLoop,
-  createSkykitStatusPlugin,
   createSkykitViewer,
   createStreamingStarsPlugin,
 } from '@found-in-space/skykit';
@@ -41,11 +113,12 @@ import {
 import { createObserverShellStrategy } from '@found-in-space/star-trees';
 import { createThreeStarField } from '@found-in-space/three-star-field';
 
+const host = document.querySelector('#viewer');
 const provider = createStarOctreeProviderService({ url: OCTREE_DEFAULT });
 const starField = createThreeStarField();
 
 const viewer = await createSkykitViewer({
-  host: document.querySelector('#skykit'),
+  host,
   view: { coordinateUnitsPerParsec: 0.001 },
   plugins: [
     createStreamingStarsPlugin({
@@ -54,8 +127,7 @@ const viewer = await createSkykitViewer({
       session: { strategy: createObserverShellStrategy() },
     }),
     createKeyboardNavigationPlugin({ speedPcPerSec: 2 }),
-    createSkyGrabPlugin({ target: document.querySelector('#skykit') }),
-    createSkykitStatusPlugin({ target: document.querySelector('#status') }),
+    createSkyGrabPlugin({ target: host }),
   ],
 });
 
@@ -69,6 +141,12 @@ supplied, it is the complete key map. Multiple keys can still point to the same
 action:
 
 ```js
+import {
+  SKYKIT_ACTIONS,
+  createKeyboardNavigationPlugin,
+  createSkykitDefaultKeyboardNavigationBindings,
+} from '@found-in-space/skykit';
+
 createKeyboardNavigationPlugin({
   rotationSpeedDegPerSec: 45,
   bindings: createSkykitDefaultKeyboardNavigationBindings({

package/package.json

@@ -1,9 +1,14 @@
 {
   "name": "@found-in-space/skykit",
-  "version": "0.2.0-alpha.0",
+  "version": "0.2.0-alpha.1",
   "description": "Slim composition and teaching layer for Found in Space packages",
   "license": "MIT",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Found-in-Space/skykit",
+    "directory": "packages/skykit"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -14,6 +19,14 @@
       "types": "./src/index.d.ts",
       "default": "./src/index.js"
     },
+    "./browser": {
+      "types": "./src/browser.d.ts",
+      "default": "./src/browser.js"
+    },
+    "./embed": {
+      "types": "./src/embed.d.ts",
+      "default": "./src/embed.js"
+    },
     "./parallax": {
       "types": "./src/parallax.d.ts",
       "default": "./src/parallax.js"
@@ -32,7 +45,9 @@
     "examples",
     "README.md"
   ],
-  "sideEffects": false,
+  "sideEffects": [
+    "./src/embed.js"
+  ],
   "scripts": {
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "node --test"

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

@@ -0,0 +1,225 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import * as THREE from 'three';
+
+import { createSkykitBrowser } from '../browser.js';
+
+test('createSkykitBrowser wires the starter viewer and extra plugins', async () => {
+  await withFakeWindow(async (fakeWindow) => {
+    const host = createHost();
+    const status = { textContent: '' };
+    const renderer = createRenderer();
+    const provider = createProvider();
+    const starField = createStarField();
+    const extraPartCalls = [];
+
+    const browser = await createSkykitBrowser({
+      host,
+      status,
+      renderer,
+      camera: new THREE.PerspectiveCamera(),
+      provider,
+      starField,
+      autoResize: false,
+      autoDispose: false,
+      autoStart: false,
+      maxDevicePixelRatio: 1.5,
+      plugins: [
+        (context) => context.addPart({
+          id: 'extra-part',
+          attach() { extraPartCalls.push('attach'); },
+          start() { extraPartCalls.push('start'); },
+        }),
+      ],
+    });
+
+    assert.equal(host.children[0], renderer.domElement);
+    assert.equal(host.style.touchAction, 'none');
+    assert.equal(renderer.clearColor.color, 0x02040b);
+    assert.deepEqual(renderer.size, { width: 640, height: 360, updateStyle: true });
+    assert.equal(renderer.pixelRatio, 1.5);
+    assert.equal(provider.sessions.length, 1);
+    assert.equal(provider.sessions[0].subscribers.size, 1);
+    assert.equal(provider.sessions[0].updateViewCalls.length, 2);
+    assert.deepEqual(extraPartCalls, ['attach', 'start']);
+    assert.match(status.textContent, /"starsLoaded": 0/);
+
+    browser.resize();
+    assert.equal(fakeWindow.addedEvents.length, 0);
+
+    await browser.dispose();
+    assert.equal(provider.disposed, false, 'caller-owned provider should not be disposed');
+    assert.equal(provider.sessions[0].disposed, true);
+    assert.equal(starField.disposed, true);
+    assert.equal(renderer.disposed, false, 'caller-owned renderer should not be disposed');
+    assert.equal(host.children.length, 0);
+  });
+});
+
+test('createSkykitBrowser registers resize and page-lifecycle cleanup by default', async () => {
+  await withFakeWindow(async (fakeWindow) => {
+    const host = createHost();
+    const renderer = createRenderer();
+    const provider = createProvider();
+    const starField = createStarField();
+
+    const browser = await createSkykitBrowser({
+      host,
+      status: false,
+      renderer,
+      provider,
+      starField,
+      autoStart: false,
+    });
+
+    assert.deepEqual(fakeWindow.addedEvents.map((entry) => entry.type), [
+      'resize',
+      'pagehide',
+      'beforeunload',
+    ]);
+
+    await browser.dispose();
+
+    assert.deepEqual(fakeWindow.removedEvents.map((entry) => entry.type), [
+      'resize',
+      'pagehide',
+      'beforeunload',
+    ]);
+  });
+});
+
+async function withFakeWindow(callback) {
+  const previousWindow = globalThis.window;
+  const fakeWindow = {
+    devicePixelRatio: 2,
+    addedEvents: [],
+    removedEvents: [],
+    addEventListener(type, listener, options) {
+      this.addedEvents.push({ type, listener, options });
+    },
+    removeEventListener(type, listener) {
+      this.removedEvents.push({ type, listener });
+    },
+  };
+
+  Object.defineProperty(globalThis, 'window', {
+    configurable: true,
+    value: fakeWindow,
+  });
+
+  try {
+    await callback(fakeWindow);
+  } finally {
+    if (previousWindow === undefined) {
+      delete globalThis.window;
+    } else {
+      Object.defineProperty(globalThis, 'window', {
+        configurable: true,
+        value: previousWindow,
+      });
+    }
+  }
+}
+
+function createHost() {
+  return {
+    children: [],
+    clientWidth: 640,
+    clientHeight: 360,
+    style: {},
+    appendChild(node) {
+      this.children.push(node);
+    },
+    removeChild(node) {
+      const index = this.children.indexOf(node);
+      if (index >= 0) this.children.splice(index, 1);
+    },
+  };
+}
+
+function createRenderer() {
+  return {
+    domElement: { nodeName: 'CANVAS' },
+    clearColor: null,
+    size: null,
+    pixelRatio: null,
+    disposed: false,
+    setClearColor(color, alpha) {
+      this.clearColor = { color, alpha };
+    },
+    setSize(width, height, updateStyle) {
+      this.size = { width, height, updateStyle };
+    },
+    setPixelRatio(value) {
+      this.pixelRatio = value;
+    },
+    render() {},
+    dispose() {
+      this.disposed = true;
+    },
+  };
+}
+
+function createProvider() {
+  return {
+    sessions: [],
+    disposed: false,
+    createSession(options) {
+      const session = createSession(options);
+      this.sessions.push(session);
+      return session;
+    },
+    dispose() {
+      this.disposed = true;
+    },
+  };
+}
+
+function createSession(options) {
+  return {
+    id: 'test-session',
+    options,
+    subscribers: new Set(),
+    updateViewCalls: [],
+    disposed: false,
+    subscribe(callback) {
+      this.subscribers.add(callback);
+      return () => {
+        this.subscribers.delete(callback);
+      };
+    },
+    updateView(view, options) {
+      this.updateViewCalls.push({ view, options });
+    },
+    getSnapshot() {
+      return {
+        id: this.id,
+        updateViewCalls: this.updateViewCalls.length,
+      };
+    },
+    async dispose() {
+      this.disposed = true;
+    },
+  };
+}
+
+function createStarField() {
+  return {
+    object3d: new THREE.Group(),
+    disposed: false,
+    view: null,
+    apply() {},
+    setView(view) {
+      this.view = view;
+    },
+    getSnapshot() {
+      return {
+        starCount: 0,
+        hasView: Boolean(this.view),
+      };
+    },
+    dispose() {
+      this.disposed = true;
+    },
+  };
+}

package/src/browser.d.ts

@@ -0,0 +1,72 @@
+import type { StarCellStrategy } from '@found-in-space/star-trees';
+import type {
+  StarOctreeProviderService,
+  StarOctreeSessionOptions,
+} from '@found-in-space/star-octree-provider';
+import type { ThreeStarField } from '@found-in-space/three-star-field';
+import type * as THREE from 'three';
+
+import type {
+  SkykitAnimationLoop,
+  SkykitAnimationLoopOptions,
+  SkykitDragLookOptions,
+  SkykitKeyboardNavigationOptions,
+  SkykitPluginInput,
+  SkykitViewState,
+  SkykitViewer,
+} from './index.js';
+
+export type SkykitBrowserHost = string | {
+  appendChild?: (node: unknown) => void;
+  removeChild?: (node: unknown) => void;
+  clientWidth?: number;
+  clientHeight?: number;
+  style?: { touchAction?: string };
+};
+
+export type SkykitBrowserStatusTarget = string | { textContent?: string | null };
+
+export interface SkykitBrowserOptions {
+  host?: SkykitBrowserHost;
+  status?: boolean | SkykitBrowserStatusTarget | null;
+  renderer?: THREE.WebGLRenderer;
+  camera?: THREE.PerspectiveCamera;
+  provider?: StarOctreeProviderService;
+  starField?: ThreeStarField;
+  octreeUrl?: string;
+  strategy?: StarCellStrategy;
+  session?: StarOctreeSessionOptions;
+  keyboard?: false | SkykitKeyboardNavigationOptions;
+  grab?: false | SkykitDragLookOptions;
+  plugins?: Iterable<SkykitPluginInput>;
+  view?: Partial<SkykitViewState>;
+  loop?: SkykitAnimationLoopOptions;
+  limitingMagnitude?: number;
+  exposure?: number;
+  coordinateUnitsPerParsec?: number;
+  speedPcPerSec?: number;
+  fovDeg?: number;
+  near?: number;
+  far?: number;
+  antialias?: boolean;
+  background?: THREE.ColorRepresentation;
+  maxDevicePixelRatio?: number;
+  autoStart?: boolean;
+  autoResize?: boolean;
+  autoDispose?: boolean;
+  disableTouchAction?: boolean;
+}
+
+export interface SkykitBrowser {
+  viewer: SkykitViewer;
+  renderer: THREE.WebGLRenderer;
+  camera: THREE.PerspectiveCamera;
+  provider: StarOctreeProviderService;
+  starField: ThreeStarField;
+  loop: SkykitAnimationLoop;
+  resize(): void;
+  dispose(): Promise<void>;
+}
+
+export declare function createSkykitBrowser(host: SkykitBrowserHost): Promise<SkykitBrowser>;
+export declare function createSkykitBrowser(options?: SkykitBrowserOptions): Promise<SkykitBrowser>;

package/src/browser.js

@@ -0,0 +1,167 @@
+import * as THREE from 'three';
+
+import {
+  OCTREE_DEFAULT,
+  createStarOctreeProviderService,
+} from '@found-in-space/star-octree-provider';
+import { createObserverShellStrategy } from '@found-in-space/star-trees';
+import { createThreeStarField } from '@found-in-space/three-star-field';
+
+import { createSkykitAnimationLoop } from './animation-loop.js';
+import {
+  createKeyboardNavigationPlugin,
+  createSkyGrabPlugin,
+  createSkykitStatusPlugin,
+  createStreamingStarsPlugin,
+} from './plugins.js';
+import { createSkykitViewer } from './viewer.js';
+
+const DEFAULT_LIMITING_MAGNITUDE = 6.5;
+const DEFAULT_EXPOSURE = 2400;
+const DEFAULT_UNITS_PER_PARSEC = 0.001;
+const DEFAULT_MAX_DEVICE_PIXEL_RATIO = 2;
+
+/**
+ * Create the default browser star viewer used by the starter lessons.
+ *
+ * @param {import('./browser.d.ts').SkykitBrowserOptions | import('./browser.d.ts').SkykitBrowserHost} [input]
+ * @returns {Promise<import('./browser.d.ts').SkykitBrowser>}
+ */
+export async function createSkykitBrowser(input = {}) {
+  const options = normalizeOptions(input);
+  const host = resolveTarget(options.host ?? '#viewer', 'SkyKit browser host');
+  const statusInput = options.status === true ? '#status' : options.status;
+  const statusTarget = statusInput === false || statusInput == null
+    ? null
+    : resolveTarget(statusInput, 'SkyKit status target');
+  const limitingMagnitude = positive(options.limitingMagnitude, DEFAULT_LIMITING_MAGNITUDE);
+  const renderer = options.renderer ?? new THREE.WebGLRenderer({
+    antialias: options.antialias !== false,
+  });
+  const camera = options.camera ?? new THREE.PerspectiveCamera(
+    positive(options.fovDeg, 58),
+    1,
+    positive(options.near, 0.0001),
+    positive(options.far, 1000),
+  );
+  const provider = options.provider ?? createStarOctreeProviderService({
+    url: options.octreeUrl ?? OCTREE_DEFAULT,
+  });
+  const starField = options.starField ?? createThreeStarField({
+    limitingMagnitude,
+    exposure: positive(options.exposure, DEFAULT_EXPOSURE),
+  });
+
+  renderer.setClearColor?.(options.background ?? 0x02040b, 1);
+  if (host.style && options.disableTouchAction !== false) host.style.touchAction = 'none';
+
+  const viewer = await createSkykitViewer({
+    host,
+    renderer,
+    camera,
+    view: {
+      observerPc: { x: 0, y: 0, z: 0 },
+      coordinateUnitsPerParsec: positive(options.coordinateUnitsPerParsec, DEFAULT_UNITS_PER_PARSEC),
+      limitingMagnitude,
+      ...(options.view ?? {}),
+    },
+    plugins: [
+      createStreamingStarsPlugin({
+        id: 'stars',
+        provider,
+        renderer: starField,
+        session: {
+          strategy: options.strategy ?? createObserverShellStrategy(),
+          ...(options.session ?? {}),
+        },
+      }),
+      ...(options.keyboard === false ? [] : [
+        createKeyboardNavigationPlugin({
+          speedPcPerSec: positive(options.speedPcPerSec, 2),
+          ...(options.keyboard ?? {}),
+        }),
+      ]),
+      ...(options.grab === false ? [] : [
+        createSkyGrabPlugin({
+          target: host,
+          sensitivityRadiansPerPixel: 0.00075,
+          ...(options.grab ?? {}),
+        }),
+      ]),
+      ...(statusTarget ? [createStatusPlugin(statusTarget)] : []),
+      ...(options.plugins ?? []),
+    ],
+  });
+
+  const loop = createSkykitAnimationLoop(viewer, options.loop);
+  let disposed = false;
+
+  const resize = () => {
+    viewer.resize({
+      devicePixelRatio: Math.min(
+        window.devicePixelRatio || 1,
+        positive(options.maxDevicePixelRatio, DEFAULT_MAX_DEVICE_PIXEL_RATIO),
+      ),
+    });
+  };
+  const dispose = async () => {
+    if (disposed) return;
+    disposed = true;
+    window.removeEventListener('resize', resize);
+    window.removeEventListener('pagehide', disposeSoon);
+    window.removeEventListener('beforeunload', disposeSoon);
+    loop.dispose();
+    await viewer.dispose();
+    if (!options.provider) await provider.dispose?.();
+    if (!options.renderer) renderer.dispose?.();
+  };
+  const disposeSoon = () => { void dispose(); };
+
+  if (options.autoResize !== false) window.addEventListener('resize', resize);
+  if (options.autoDispose !== false) {
+    window.addEventListener('pagehide', disposeSoon, { once: true });
+    window.addEventListener('beforeunload', disposeSoon, { once: true });
+  }
+  resize();
+  if (options.autoStart !== false) loop.start();
+
+  return { viewer, renderer, camera, provider, starField, loop, resize, dispose };
+}
+
+function createStatusPlugin(target) {
+  return createSkykitStatusPlugin({
+    intervalSeconds: 0.5,
+    render({ viewer }) {
+      const stars = viewer.parts.find((part) => part.id === 'stars')?.snapshot;
+      target.textContent = JSON.stringify({
+        observerPc: viewer.view.observerPc,
+        starsLoaded: stars?.renderer?.starCount ?? 0,
+        stream: stars?.status ?? 'starting',
+      }, null, 2);
+    },
+  });
+}
+
+function normalizeOptions(input) {
+  if (typeof input === 'string' || isElementLike(input)) return { host: input };
+  return input ?? {};
+}
+
+function resolveTarget(input, label) {
+  if (typeof input !== 'string') {
+    if (input) return input;
+    throw new Error(`${label} is missing.`);
+  }
+  const target = document.querySelector(input);
+  if (!target) throw new Error(`${label} not found: ${input}`);
+  return target;
+}
+
+function isElementLike(value) {
+  return Boolean(value && typeof value === 'object' && 'appendChild' in value);
+}
+
+function positive(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : fallback;
+}

package/src/embed.d.ts

@@ -0,0 +1 @@
+export { createSkykitBrowser } from './browser.js';

package/src/embed.js

@@ -0,0 +1,69 @@
+import { createSkykitBrowser } from './browser.js';
+
+const DEFAULT_SELECTOR = '[data-skykit-browser]';
+const started = new WeakSet();
+
+if (typeof document !== 'undefined') {
+  ready(() => {
+    for (const host of document.querySelectorAll(DEFAULT_SELECTOR)) {
+      if (started.has(host)) continue;
+      started.add(host);
+      void createSkykitBrowser(readOptions(host))
+        .then((browser) => {
+          reportReady(host, browser);
+        })
+        .catch((error) => {
+          reportError(host, error);
+        });
+    }
+  });
+}
+
+/** @param {Element} host */
+function readOptions(host) {
+  const data = host instanceof HTMLElement ? host.dataset : {};
+  return {
+    host,
+    ...(data.skykitStatus ? { status: data.skykitStatus } : {}),
+    ...(data.skykitMagnitude ? { limitingMagnitude: Number(data.skykitMagnitude) } : {}),
+    ...(data.skykitSpeed ? { speedPcPerSec: Number(data.skykitSpeed) } : {}),
+    ...(data.skykitExposure ? { exposure: Number(data.skykitExposure) } : {}),
+  };
+}
+
+/**
+ * @param {Element} host
+ * @param {import('./browser.d.ts').SkykitBrowser} browser
+ */
+function reportReady(host, browser) {
+  host.dispatchEvent(new CustomEvent('skykit-browser-ready', {
+    detail: { browser, viewer: browser.viewer },
+    bubbles: true,
+  }));
+}
+
+/**
+ * @param {Element} host
+ * @param {unknown} error
+ */
+function reportError(host, error) {
+  host.dispatchEvent(new CustomEvent('skykit-browser-error', {
+    detail: { error },
+    bubbles: true,
+  }));
+  const data = host instanceof HTMLElement ? host.dataset : {};
+  if (!data.skykitStatus) return;
+  const status = document.querySelector(data.skykitStatus);
+  if (status) status.textContent = error instanceof Error ? error.stack ?? error.message : String(error);
+}
+
+/** @param {() => void} callback */
+function ready(callback) {
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', callback, { once: true });
+    return;
+  }
+  callback();
+}
+
+export { createSkykitBrowser } from './browser.js';