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

package/README.md

@@ -20,17 +20,204 @@ 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
+## Website Use-Cases
+
+The beginner website entries are use-case bounded:
+
+| Use-case | Website owner says | Public entry |
+| --- | --- | --- |
+| Viewer | "Put stars on my page and let me customize the scene." | `embed.js`, `viewer.js` |
+| Data | "Give me star data so I can render, list, map, or game it myself." | `data.js` |
+| Story | "Let me tell a curated story through space." | `story.js` |
+
+`embed.js` is the no-code viewer entry. It is not a separate use-case.
+`viewer.js` is the JavaScript-customizable viewer entry. `data.js` is renderer
+independent. `story.js` is authored chapters plus 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@0.2.0-alpha.2/embed?bundle&deps=three@0.170.0"
+></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"
+  data-skykit-look-at="ra=4.496h, dec=16.948"
+  data-skykit-mouse-mode="strafe"
+  style="width: 100%; height: 520px; background: #02040b"
+></div>
+```
+
+`data-skykit-look-at` accepts RA/Dec text such as
+`ra=4.496h, dec=16.948`, decimal degrees such as `67.447,16.948`, or a
+parsec-space `x,y,z` target for exact generated coordinates. `data-skykit-mouse-mode`
+defaults to `grab`; use `look` or `strafe` for the first-person mouse-look
+direction, or `none` to disable mouse drag controls.
+
+The host dispatches `skykit-browser-ready` with `{ browser, viewer }` in
+`event.detail` after startup, and `skykit-browser-error` if startup fails. The
+embed also installs a small `Skykit` global for noob-path scripts:
+
+```js
+const browser = await Skykit.whenReady();
+```
+
+Pages can host multiple viewers. Pass a selector or element to choose one:
+
+```js
+const browser = await Skykit.whenReady('#orion-viewer');
+```
+
+Pin the package 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`.
+
+Optional first-party capabilities stay out of the initial browser until they are
+requested. This keeps the one-script noob path while avoiding bundle bloat.
+
+```html
+<div
+  data-skykit-browser
+  data-skykit-constellations="western"
+  data-skykit-constellation-art="off"
+  style="width:100%;height:520px;background:#02040b"
+></div>
+```
+
+For small scripted interactions, use the browser handle:
+
+```html
+<script type="module">
+  const browser = await Skykit.whenReady();
+
+  document.querySelector('#orion').addEventListener('click', () => {
+    browser.journey.transitionTo({
+      lookAt: 'ra=5.919h, dec=7.407',
+      durationSecs: 3,
+    });
+  });
+</script>
+```
+
+## Create a Viewer 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 'https://esm.sh/@found-in-space/skykit@0.2.0-alpha.2/viewer?bundle&deps=three@0.170.0';
+
+  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.addObject(marker, {
+  positionPc: { x: 17.574, y: 42.316, z: 13.963 },
+});
+sky.loop.stop();
+await sky.dispose();
+```
+
+For npm or bundlers, use the same beginner entry:
+
+```js
+import { THREE, createSkykitBrowser } from '@found-in-space/skykit/viewer';
+```
+
+## Use Star Data Without a Viewer
+
+Use `data.js` when SkyKit should supply rows and your app should own rendering:
+
+```js
+import { loadStarRows } from 'https://esm.sh/@found-in-space/skykit@0.2.0-alpha.2/data?bundle';
+
+const stars = await loadStarRows({
+  limitingMagnitude: 6.5,
+  maxStars: 100,
+  sortBy: 'apparentMagnitude',
+});
+
+console.table(stars);
+```
+
+For games and maps, load a local volume and hand rows to Canvas, PixiJS,
+Phaser, SVG, or your own renderer:
+
+```js
+const stars = await loadStarRows({
+  centerPc: { x: 0, y: 0, z: 0 },
+  radiusPc: 50,
+  maxStars: 2000,
+});
+```
+
+## Create a Guided Story
+
+Use `story.js` when the page is an authored article or tour:
+
+```html
+<div data-skykit-story style="height:600px;background:#02040b">
+  <section data-skykit-chapter data-title="The Sun" data-target-pc="0,0,0">
+    We start at the Sun.
+  </section>
+  <section data-skykit-chapter data-title="The Hyades" data-target-pc="17.574,42.316,13.963">
+    Now jump to the Hyades cluster.
+  </section>
+</div>
+
+<script
+  type="module"
+  src="https://esm.sh/@found-in-space/skykit@0.2.0-alpha.2/story?bundle&deps=three@0.170.0"
+></script>
+```
+
+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 +228,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 +242,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 +256,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({
@@ -185,6 +378,28 @@ For a slightly more playful example, see `examples/plugin-lab.js`. It builds
 app-owned Three objects and action-driven annotations from the same public hooks
 a learner would use.
 
+The pasteable browser embed has a smaller add-on convention for noob pages:
+
+```js
+Skykit.registerBrowserAddon({
+  id: 'lesson:marker',
+  install({ browser, THREE }) {
+    const marker = new THREE.Mesh(
+      new THREE.SphereGeometry(0.02),
+      new THREE.MeshBasicMaterial({ color: 0xffcc00 }),
+    );
+    const handle = browser.addObject(marker, {
+      positionPc: { x: 17.574, y: 42.316, z: 13.963 },
+    });
+    return () => handle.dispose();
+  },
+});
+```
+
+See `docs/skykit-browser-plugins.md` for the browser add-on spec,
+`Skykit.whenReady()`, first-party constellation support, and the
+`browser.journey` API.
+
 Browser lessons:
 
 - `examples/free-roam-lesson/` composes streamed stars, keyboard navigation,

package/examples/custom-object-layer/custom-object-layer.js

@@ -145,7 +145,7 @@ function createInitialViewState() {
     observerPc: { x: 0, y: 0, z: 0 },
     coordinateUnitsPerParsec: UNITS_PER_PARSEC,
     limitingMagnitude: 7.5,
-    orientationIcrs: lookAtFromOriginWithNorthUp(HYADES_CENTER_PC),
+    lookAt: { targetPc: HYADES_CENTER_PC },
   };
 }
 
@@ -332,29 +332,6 @@ function toRenderPosition(pointPc) {
   );
 }
 
-function lookAtFromOriginWithNorthUp(targetPc) {
-  const forward = new THREE.Vector3(targetPc.x, targetPc.y, targetPc.z).normalize();
-  const north = new THREE.Vector3(0, 0, 1);
-  let up = north.clone().sub(forward.clone().multiplyScalar(north.dot(forward)));
-  if (up.lengthSq() < 1e-8) {
-    up = new THREE.Vector3(0, 1, 0);
-  }
-  up.normalize();
-
-  const backward = forward.clone().negate();
-  const right = up.clone().cross(backward).normalize();
-  up = backward.clone().cross(right).normalize();
-
-  const matrix = new THREE.Matrix4().makeBasis(right, up, backward);
-  const quaternion = new THREE.Quaternion().setFromRotationMatrix(matrix);
-  return {
-    x: quaternion.x,
-    y: quaternion.y,
-    z: quaternion.z,
-    w: quaternion.w,
-  };
-}
-
 function directionFromRaDec(raDeg, decDeg) {
   const ra = THREE.MathUtils.degToRad(raDeg);
   const dec = THREE.MathUtils.degToRad(decDeg);

package/examples/xr-free-roam/index.html

@@ -10,10 +10,68 @@
   <body>
     <main class="xr-free-roam-shell">
       <div class="viewer-shell" data-viewer></div>
-      <div class="xr-actions" aria-label="XR actions">
-        <button type="button" data-action="enter-xr">Enter VR</button>
-        <button type="button" data-action="exit-xr">Exit VR</button>
-      </div>
+      <section class="xr-preflight" data-preflight aria-labelledby="xr-preflight-title">
+        <div class="xr-preflight-copy">
+          <p class="xr-kicker">SkyKit XR</p>
+          <h1 id="xr-preflight-title">Free Roam Preflight</h1>
+          <p>
+            Choose the rendering defaults for this headset run, then enter the immersive session.
+          </p>
+          <dl class="xr-status-list">
+            <div>
+              <dt>WebXR</dt>
+              <dd data-xr-supported>Checking</dd>
+            </div>
+            <div>
+              <dt>Scale</dt>
+              <dd data-setting-value="worldScaleLog10">1 m/pc</dd>
+            </div>
+            <div>
+              <dt>Stars</dt>
+              <dd data-setting-value="limitingMagnitude">Mag 7.5</dd>
+            </div>
+          </dl>
+        </div>
+
+        <form class="xr-settings" data-xr-settings>
+          <fieldset>
+            <legend>Rendering</legend>
+            <label>
+              <span>Magnitude limit</span>
+              <output data-setting-value="limitingMagnitude">7.5</output>
+              <input data-setting="limitingMagnitude" type="range" min="4" max="10" step="0.1" value="7.5" />
+            </label>
+            <label>
+              <span>Exposure</span>
+              <output data-setting-value="exposureLog10">100,000</output>
+              <input data-setting="exposureLog10" type="range" min="3.5" max="5.5" step="0.05" value="5" />
+            </label>
+            <label>
+              <span>World scale</span>
+              <output data-setting-value="worldScaleLog10">1 m/pc</output>
+              <input data-setting="worldScaleLog10" type="range" min="-3" max="0" step="0.05" value="0" />
+            </label>
+          </fieldset>
+
+          <fieldset>
+            <legend>Session Flags</legend>
+            <label class="xr-toggle">
+              <input data-setting="nearFloor" type="checkbox" checked />
+              <span>Near-star readability floor</span>
+            </label>
+            <label class="xr-toggle">
+              <input data-setting="constellationArt" type="checkbox" checked />
+              <span>Constellation art</span>
+            </label>
+          </fieldset>
+
+          <div class="xr-actions" aria-label="XR actions">
+            <button class="xr-primary-action" type="button" data-action="enter-xr">Enter VR</button>
+            <button type="button" data-action="exit-xr" hidden disabled>Exit VR</button>
+          </div>
+          <p class="xr-session-status" data-session-status>Idle</p>
+        </form>
+      </section>
     </main>
     <script type="module" src="./xr-free-roam.js"></script>
   </body>

package/examples/xr-free-roam/xr-free-roam.css

@@ -2,9 +2,20 @@ html,
 body {
   margin: 0;
   width: 100%;
+  min-width: 320px;
   height: 100%;
   overflow: hidden;
-  background: #020712;
+  background: #05070b;
+  color: #f4efe2;
+  font: 16px/1.45 "Avenir Next", Avenir, "Segoe UI", sans-serif;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+[hidden] {
+  display: none !important;
 }
 
 .xr-free-roam-shell,
@@ -13,39 +24,259 @@ body {
   inset: 0;
 }
 
+.xr-free-roam-shell {
+  background:
+    linear-gradient(90deg, rgba(5, 7, 11, 0.96) 0%, rgba(5, 7, 11, 0.84) 46%, rgba(5, 7, 11, 0.58) 100%),
+    #05070b;
+}
+
+.viewer-shell {
+  z-index: 0;
+  opacity: 0.34;
+  filter: saturate(0.78) contrast(1.08);
+  pointer-events: none;
+  transition: opacity 0.18s ease, filter 0.18s ease;
+}
+
+.xr-free-roam-shell.is-presenting .viewer-shell {
+  opacity: 1;
+  filter: none;
+  pointer-events: auto;
+}
+
 .viewer-shell canvas {
   display: block;
   width: 100%;
   height: 100%;
-  cursor: grab;
+  cursor: default;
   touch-action: none;
   user-select: none;
 }
 
-.viewer-shell canvas:active {
-  cursor: grabbing;
+.xr-preflight {
+  position: fixed;
+  inset: 0;
+  z-index: 10;
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(320px, 430px);
+  gap: clamp(24px, 5vw, 72px);
+  align-items: center;
+  width: 100%;
+  height: 100%;
+  padding: clamp(24px, 6vh, 72px) clamp(18px, 7vw, 92px);
+  overflow: auto;
+}
+
+.xr-free-roam-shell.is-presenting .xr-preflight {
+  display: none;
+}
+
+.xr-preflight-copy {
+  max-width: 720px;
+}
+
+.xr-kicker {
+  margin: 0 0 10px;
+  color: #6fd7c3;
+  font-size: 0.82rem;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.xr-preflight h1 {
+  margin: 0;
+  max-width: 11ch;
+  color: #fff9e8;
+  font-size: clamp(2.6rem, 6vh, 5.6rem);
+  line-height: 0.96;
+  font-weight: 760;
+}
+
+.xr-preflight-copy > p:not(.xr-kicker) {
+  max-width: 46rem;
+  margin: 22px 0 0;
+  color: #cfc7b8;
+  font-size: 1.08rem;
+}
+
+.xr-status-list {
+  display: grid;
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 1px;
+  max-width: 620px;
+  margin: 34px 0 0;
+  padding: 1px;
+  background: rgba(244, 239, 226, 0.14);
+  border-radius: 8px;
+  overflow: hidden;
+}
+
+.xr-status-list div {
+  min-width: 0;
+  padding: 13px 14px;
+  background: rgba(15, 18, 18, 0.88);
+}
+
+.xr-status-list dt {
+  color: #a7b2ac;
+  font-size: 0.76rem;
+  font-weight: 700;
+  text-transform: uppercase;
+}
+
+.xr-status-list dd {
+  margin: 4px 0 0;
+  color: #fff6dd;
+  font-weight: 700;
+  overflow-wrap: anywhere;
+}
+
+.xr-settings {
+  display: grid;
+  gap: 14px;
+  width: min(100%, 430px);
+  padding: 18px;
+  border: 1px solid rgba(244, 239, 226, 0.18);
+  border-radius: 8px;
+  background: rgba(14, 17, 16, 0.88);
+  box-shadow: 0 24px 80px rgba(0, 0, 0, 0.28);
+}
+
+.xr-settings fieldset {
+  display: grid;
+  gap: 14px;
+  min-width: 0;
+  margin: 0;
+  padding: 0 0 16px;
+  border: 0;
+  border-bottom: 1px solid rgba(244, 239, 226, 0.13);
+}
+
+.xr-settings fieldset:last-of-type {
+  padding-bottom: 2px;
+  border-bottom: 0;
+}
+
+.xr-settings legend {
+  padding: 0;
+  color: #d9b779;
+  font-size: 0.82rem;
+  font-weight: 760;
+  text-transform: uppercase;
+}
+
+.xr-settings label:not(.xr-toggle) {
+  display: grid;
+  grid-template-columns: 1fr auto;
+  gap: 8px 14px;
+  align-items: center;
+  color: #f4efe2;
+  font-weight: 650;
+}
+
+.xr-settings output {
+  color: #9ddbd1;
+  font-variant-numeric: tabular-nums;
+  font-weight: 760;
+  text-align: right;
+}
+
+.xr-settings input[type="range"] {
+  grid-column: 1 / -1;
+  width: 100%;
+  accent-color: #d9b779;
+}
+
+.xr-toggle {
+  display: grid;
+  grid-template-columns: 22px 1fr;
+  gap: 10px;
+  align-items: center;
+  min-height: 32px;
+  color: #e8dfcf;
+  font-weight: 650;
+}
+
+.xr-toggle input {
+  width: 18px;
+  height: 18px;
+  accent-color: #6fd7c3;
 }
 
 .xr-actions {
-  position: fixed;
-  top: 16px;
-  right: 16px;
-  z-index: 10;
   display: flex;
-  gap: 8px;
+  flex-wrap: wrap;
+  gap: 10px;
 }
 
 .xr-actions button {
-  min-height: 38px;
-  padding: 0 14px;
-  border: 1px solid rgba(145, 220, 255, 0.35);
+  min-height: 42px;
+  padding: 0 16px;
+  border: 1px solid rgba(244, 239, 226, 0.24);
   border-radius: 8px;
-  background: rgba(5, 13, 26, 0.76);
-  color: #eef8ff;
-  font: 600 0.9rem/1 "Avenir Next", Avenir, "Segoe UI", sans-serif;
+  background: rgba(244, 239, 226, 0.08);
+  color: #fff9e8;
+  font: inherit;
+  font-weight: 760;
+}
+
+.xr-actions button:hover:not(:disabled) {
+  border-color: rgba(244, 239, 226, 0.72);
+  background: rgba(244, 239, 226, 0.13);
+}
+
+.xr-actions button:disabled {
+  cursor: not-allowed;
+  opacity: 0.55;
+}
+
+.xr-actions .xr-primary-action {
+  min-width: 144px;
+  border-color: rgba(217, 183, 121, 0.72);
+  background: #d9b779;
+  color: #101313;
+}
+
+.xr-actions .xr-primary-action:hover:not(:disabled) {
+  border-color: #ffe0a6;
+  background: #e8c987;
 }
 
-.xr-actions button:hover {
-  border-color: rgba(145, 220, 255, 0.8);
-  background: rgba(10, 25, 44, 0.9);
+.xr-session-status {
+  min-height: 1.4em;
+  margin: 0;
+  color: #a7b2ac;
+  font-size: 0.88rem;
+}
+
+@media (max-width: 820px) {
+  .xr-preflight {
+    grid-template-columns: 1fr;
+    align-content: start;
+  }
+
+  .xr-preflight h1 {
+    max-width: 13ch;
+    font-size: clamp(2.3rem, 12vw, 4.4rem);
+  }
+
+  .xr-status-list {
+    grid-template-columns: 1fr;
+  }
+
+  .xr-settings {
+    width: 100%;
+  }
+}
+
+@media (max-height: 640px) and (min-width: 821px) {
+  .xr-preflight {
+    align-items: start;
+    padding-top: 28px;
+    padding-bottom: 28px;
+  }
+
+  .xr-preflight h1 {
+    font-size: 3.4rem;
+  }
 }