npm - worldorbit - Versions diffs - 3.2.2 → 5.0.0 - Mend

worldorbit 3.2.2 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (82) hide show

package/README.md +543 -543
package/dist/browser/core/dist/atlas-edit.js +146 -1
package/dist/browser/core/dist/atlas-validate.js +105 -10
package/dist/browser/core/dist/draft-parse.js +461 -17
package/dist/browser/core/dist/draft.d.ts +2 -1
package/dist/browser/core/dist/draft.js +26 -4
package/dist/browser/core/dist/format.js +126 -5
package/dist/browser/core/dist/index.d.ts +1 -0
package/dist/browser/core/dist/index.js +1 -0
package/dist/browser/core/dist/load.js +12 -2
package/dist/browser/core/dist/normalize.js +1 -0
package/dist/browser/core/dist/scene.js +226 -5
package/dist/browser/core/dist/schema.js +11 -1
package/dist/browser/core/dist/solver.d.ts +33 -0
package/dist/browser/core/dist/solver.js +99 -0
package/dist/browser/core/dist/spatial-scene.js +56 -0
package/dist/browser/core/dist/types.d.ts +130 -4
package/dist/browser/editor/dist/editor.js +844 -719
package/dist/browser/editor/dist/types.d.ts +2 -1
package/dist/browser/viewer/dist/minimap.js +9 -7
package/dist/browser/viewer/dist/render.js +78 -18
package/dist/browser/viewer/dist/runtime-3d.js +2 -0
package/dist/browser/viewer/dist/theme.js +1 -0
package/dist/browser/viewer/dist/types.d.ts +7 -0
package/dist/browser/viewer/dist/viewer.js +34 -3
package/dist/obsidian-plugin/README.md +141 -124
package/dist/obsidian-plugin/main.js +82 -68
package/dist/unpkg/core/dist/atlas-edit.js +146 -1
package/dist/unpkg/core/dist/atlas-validate.js +105 -10
package/dist/unpkg/core/dist/draft-parse.js +461 -17
package/dist/unpkg/core/dist/draft.d.ts +2 -1
package/dist/unpkg/core/dist/draft.js +26 -4
package/dist/unpkg/core/dist/format.js +126 -5
package/dist/unpkg/core/dist/index.d.ts +1 -0
package/dist/unpkg/core/dist/index.js +1 -0
package/dist/unpkg/core/dist/load.js +12 -2
package/dist/unpkg/core/dist/normalize.js +1 -0
package/dist/unpkg/core/dist/scene.js +226 -5
package/dist/unpkg/core/dist/schema.js +11 -1
package/dist/unpkg/core/dist/solver.d.ts +33 -0
package/dist/unpkg/core/dist/solver.js +99 -0
package/dist/unpkg/core/dist/spatial-scene.js +56 -0
package/dist/unpkg/core/dist/types.d.ts +130 -4
package/dist/unpkg/editor/dist/editor.js +844 -719
package/dist/unpkg/editor/dist/types.d.ts +2 -1
package/dist/unpkg/viewer/dist/minimap.js +9 -7
package/dist/unpkg/viewer/dist/render.js +78 -18
package/dist/unpkg/viewer/dist/runtime-3d.js +2 -0
package/dist/unpkg/viewer/dist/theme.js +1 -0
package/dist/unpkg/viewer/dist/types.d.ts +7 -0
package/dist/unpkg/viewer/dist/viewer.js +34 -3
package/dist/unpkg/worldorbit-core.min.js +12 -12
package/dist/unpkg/worldorbit-editor.min.js +381 -340
package/dist/unpkg/worldorbit-markdown.min.js +47 -33
package/dist/unpkg/worldorbit-viewer.min.js +238 -224
package/dist/unpkg/worldorbit.js +1218 -46
package/dist/unpkg/worldorbit.min.js +242 -228
package/package.json +5 -1
package/packages/core/dist/atlas-edit.js +146 -1
package/packages/core/dist/atlas-validate.js +105 -10
package/packages/core/dist/draft-parse.js +461 -17
package/packages/core/dist/draft.d.ts +2 -1
package/packages/core/dist/draft.js +26 -4
package/packages/core/dist/format.js +126 -5
package/packages/core/dist/index.d.ts +1 -0
package/packages/core/dist/index.js +1 -0
package/packages/core/dist/load.js +12 -2
package/packages/core/dist/normalize.js +1 -0
package/packages/core/dist/scene.js +226 -5
package/packages/core/dist/schema.js +11 -1
package/packages/core/dist/solver.d.ts +33 -0
package/packages/core/dist/solver.js +99 -0
package/packages/core/dist/spatial-scene.js +56 -0
package/packages/core/dist/types.d.ts +130 -4
package/packages/editor/dist/editor.js +844 -719
package/packages/editor/dist/types.d.ts +2 -1
package/packages/viewer/dist/minimap.js +9 -7
package/packages/viewer/dist/render.js +78 -18
package/packages/viewer/dist/runtime-3d.js +2 -0
package/packages/viewer/dist/theme.js +1 -0
package/packages/viewer/dist/types.d.ts +7 -0
package/packages/viewer/dist/viewer.js +34 -3

package/README.md CHANGED Viewed

@@ -1,545 +1,545 @@
-# WorldOrbit
-WorldOrbit is a text-first DSL, viewer, and optional editor platform for fictional orbital systems.
-It is designed as a specialized Mermaid-like alternative for worldbuilding: you can describe stellar systems in plain text, embed them in Markdown, render them as static diagrams, or explore them interactively with pan, rotate, zoom, and object tooltips.
-WorldOrbit is built for:
-- worldbuilding projects
-- Markdown-based lore repositories and CMS setups
-- fictional atlases and codices
-- interactive setting documentation
-- browser-based orbital diagram tooling
-## Why WorldOrbit?
-Generic diagram tools can show relationships, but they are not built for fictional orbital systems.
-WorldOrbit is designed specifically for:
-- stars, planets, moons, belts, structures, and phenomena
-- orbit-aware layouts instead of generic node graphs
-- Markdown-native embedding
-- optional interactivity
-- optional visual authoring through Studio
-WorldOrbit is not intended to be a real-world astronomy simulator or a high-precision astrophysics engine. Its goal is clear, expressive orbital worldbuilding that works well in content workflows.
-## Quick Example
-```worldorbit
-schema 2.5
-system Iyath
-  title "Iyath System"
-  epoch "JY-0001.0"
-  referencePlane ecliptic
-defaults
-  view orthographic
-  scale presentation
-  preset atlas-card
-  theme atlas
-group inner-system
-  label "Inner System"
-  color #d9b37a
-viewpoint eclipse
-  label "Eclipse View"
-  projection perspective
-  camera
-    azimuth 36
-    elevation 22
-    distance 6
-  layers background guides orbits-back events objects labels metadata
-  events naar-eclipse
-object star Iyath
-object planet Naar
-  orbit Iyath
-  semiMajor 1.18au
-  eccentricity 0.08
-  angle 28deg
-  inclination 24deg
-  phase 42deg
-  atmosphere nitrogen-oxygen
-  groups inner-system
-object moon Seyra
-  orbit Naar
-  distance 384400km
-event naar-eclipse
-  kind solar-eclipse
-  target Naar
-  participants Iyath Naar Seyra
-````
-## Installation
-### npm
-```bash
-npm install worldorbit
-```
-### What the `worldorbit` package contains
-The published `worldorbit` package is the public entry point.
-It includes:
-* the browser bundles
-* subpath exports for core modules
-* the packages used by the viewer, Markdown integration, and editor tooling
-So for most users, this is enough:
-```bash
-npm install worldorbit
-```
-And then:
-```ts
-import { parse, loadWorldOrbitSource } from "worldorbit";
-import * as Viewer from "worldorbit/viewer";
-```
-## Browser / CDN Quick Setup
-For direct browser usage, use the browser bundle:
-```html
-<!DOCTYPE html>
-<html>
-  <head>
-    <meta charset="utf-8" />
-    <style>
-      html, body {
-        margin: 0;
-        width: 100%;
-        height: 100%;
-      }
-      #view {
-        width: 100vw;
-        height: 100vh;
-      }
-    </style>
-  </head>
-  <body>
-    <div id="view"></div>
-    <script type="module">
-      import {
-        createInteractiveViewer,
-        loadWorldOrbitSource
-      } from "https://unpkg.com/worldorbit@3.0.7/dist/unpkg/worldorbit.esm.js";
-      const source = `
-schema 2.5
-system Iyath
-  epoch "JY-0001.0"
-object star Iyath
-object planet Naar
-  orbit Iyath
-  semiMajor 1.18au
-`.trim();
-      const loaded = loadWorldOrbitSource(source);
-      createInteractiveViewer(document.getElementById("view"), {
-        document: loaded.document
-      });
-    </script>
-  </body>
-</html>
-```
-For browser usage today, prefer the ESM entry point `worldorbit.esm.js`.
-## Static and Interactive Rendering
-WorldOrbit can be used in different ways from the same source:
-* as a static diagram
-* as an interactive SVG viewer
-* inside Markdown pipelines
-* inside the optional Studio editor
-This means the same WorldOrbit document can be:
-* written in plain text
-* embedded in Markdown
-* rendered in a documentation page
-* explored interactively
-* edited visually if needed
-## Studio Editor
-WorldOrbit includes an optional Studio editor for easier authoring and exploration.
-Studio is useful when you want:
-* visual placement editing
-* source and preview side by side
-* inspector-based editing
-* faster onboarding for non-technical users
-The editor is optional. The core format remains text-first.
-## Canonical Schema
+# WorldOrbit
+WorldOrbit is a text-first DSL, viewer, and optional editor platform for fictional orbital systems.
+It is designed as a specialized Mermaid-like alternative for worldbuilding: you can describe stellar systems in plain text, embed them in Markdown, render them as static diagrams, or explore them interactively with pan, rotate, zoom, and object tooltips.
+WorldOrbit is built for:
+- worldbuilding projects
+- Markdown-based lore repositories and CMS setups
+- fictional atlases and codices
+- interactive setting documentation
+- browser-based orbital diagram tooling
+## Why WorldOrbit?
+Generic diagram tools can show relationships, but they are not built for fictional orbital systems.
+WorldOrbit is designed specifically for:
+- stars, planets, moons, belts, structures, and phenomena
+- orbit-aware layouts instead of generic node graphs
+- Markdown-native embedding
+- optional interactivity
+- optional visual authoring through Studio
+WorldOrbit is not intended to be a real-world astronomy simulator or a high-precision astrophysics engine. Its goal is clear, expressive orbital worldbuilding that works well in content workflows.
+## Quick Example
+```worldorbit
+schema 3.1
+system Iyath
+  title "Iyath System"
+  epoch "JY-0001.0"
+  referencePlane ecliptic
+defaults
+  view orthographic
+  scale presentation
+  preset atlas-card
+  theme atlas
+group inner-system
+  label "Inner System"
+  color #d9b37a
+viewpoint eclipse
+  label "Eclipse View"
+  projection perspective
+  camera
+    azimuth 36
+    elevation 22
+    distance 6
+  layers background guides orbits-back events objects labels metadata
+  events naar-eclipse
+object star Iyath
+object planet Naar
+  orbit Iyath
+  semiMajor 1.18au
+  eccentricity 0.08
+  angle 28deg
+  inclination 24deg
+  phase 42deg
+  atmosphere nitrogen-oxygen
+  groups inner-system
+object moon Seyra
+  orbit Naar
+  distance 384400km
+event naar-eclipse
+  kind solar-eclipse
+  target Naar
+  participants Iyath Naar Seyra
+````
+## Installation
+### npm
+```bash
+npm install worldorbit
+```
+### What the `worldorbit` package contains
+The published `worldorbit` package is the public entry point.
+It includes:
+* the browser bundles
+* subpath exports for core modules
+* the packages used by the viewer, Markdown integration, and editor tooling
+So for most users, this is enough:
+```bash
+npm install worldorbit
+```
+And then:
+```ts
+import { parse, loadWorldOrbitSource } from "worldorbit";
+import * as Viewer from "worldorbit/viewer";
+```
+## Browser / CDN Quick Setup
+For direct browser usage, use the browser bundle:
+```html
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <style>
+      html, body {
+        margin: 0;
+        width: 100%;
+        height: 100%;
+      }
+      #view {
+        width: 100vw;
+        height: 100vh;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="view"></div>
+    <script type="module">
+      import {
+        createInteractiveViewer,
+        loadWorldOrbitSource
+      } from "https://unpkg.com/worldorbit@5.0.0/dist/unpkg/worldorbit.esm.js";
+      const source = `
+schema 3.1
+system Iyath
+  epoch "JY-0001.0"
+object star Iyath
+object planet Naar
+  orbit Iyath
+  semiMajor 1.18au
+`.trim();
+      const loaded = loadWorldOrbitSource(source);
+      createInteractiveViewer(document.getElementById("view"), {
+        document: loaded.document
+      });
+    </script>
+  </body>
+</html>
+```
+For browser usage today, prefer the ESM entry point `worldorbit.esm.js`.
+## Static and Interactive Rendering
+WorldOrbit can be used in different ways from the same source:
+* as a static diagram
+* as an interactive SVG viewer
+* inside Markdown pipelines
+* inside the optional Studio editor
+This means the same WorldOrbit document can be:
+* written in plain text
+* embedded in Markdown
+* rendered in a documentation page
+* explored interactively
+* edited visually if needed
+## Studio Editor
+WorldOrbit includes an optional Studio editor for easier authoring and exploration.
+Studio is useful when you want:
+* visual placement editing
+* source and preview side by side
+* inspector-based editing
+* faster onboarding for non-technical users
+The editor is optional. The core format remains text-first.
+## Canonical Schema
 New atlas authoring should start with:
-```worldorbit
-schema 2.5
-```
-Example:
-```worldorbit
-schema 2.5
-system Iyath
-  title "Iyath System"
-  epoch "JY-0001.0"
-  referencePlane ecliptic
-defaults
-  view orthographic
-  scale presentation
-  preset atlas-card
-  theme atlas
-group inner-system
-  label "Inner System"
-  summary "Naar and its inhabited infrastructure"
-  color #d9b37a
-viewpoint overview
-  label "Atlas Overview"
-  summary "Fit the whole system."
-  projection orthographic
-  camera
-    azimuth 24
-    elevation 18
-  layers background guides orbits-back events objects labels metadata
-  events naar-eclipse
-  filter
-    groups inner-system
-annotation naar-notes
-  label "Naar Notes"
-  target Naar
-  body "Heimatwelt der Enari."
-object star Iyath
-  mass 1.02sol
-object planet Naar
-  orbit Iyath
-  semiMajor 1.18au
-  eccentricity 0.08
-  angle 28deg
-  inclination 24deg
-  phase 42deg
-  groups inner-system
-  image /demo/assets/naar-map.png
-  atmosphere nitrogen-oxygen
-object moon Seyra
-  orbit Naar
-  distance 384400km
-  groups inner-system
-event naar-eclipse
-  kind solar-eclipse
-  label "Naar Eclipse"
-  target Naar
-  participants Iyath Naar Seyra
-  epoch "JY-0001.0"
-  referencePlane ecliptic
-  positions
-    pose Naar
-      orbit Iyath
-      semiMajor 1.18au
-      phase 90deg
-    pose Seyra
-      orbit Naar
-      distance 384400km
-      phase 90deg
-```
-## What's New In Schema 2.5
-Schema `2.5` keeps Schema `2.1` fully readable and adds a clearer 3D-ready authoring surface without turning WorldOrbit into a full 3D engine.
+```worldorbit
+schema 3.1
+```
+Example:
+```worldorbit
+schema 3.0
+system Iyath
+  title "Iyath System"
+  epoch "JY-0001.0"
+  referencePlane ecliptic
+defaults
+  view orthographic
+  scale presentation
+  preset atlas-card
+  theme atlas
+group inner-system
+  label "Inner System"
+  summary "Naar and its inhabited infrastructure"
+  color #d9b37a
+viewpoint overview
+  label "Atlas Overview"
+  summary "Fit the whole system."
+  projection orthographic
+  camera
+    azimuth 24
+    elevation 18
+  layers background guides orbits-back events objects labels metadata
+  events naar-eclipse
+  filter
+    groups inner-system
+annotation naar-notes
+  label "Naar Notes"
+  target Naar
+  body "Heimatwelt der Enari."
+object star Iyath
+  mass 1.02sol
+object planet Naar
+  orbit Iyath
+  semiMajor 1.18au
+  eccentricity 0.08
+  angle 28deg
+  inclination 24deg
+  phase 42deg
+  groups inner-system
+  image /demo/assets/naar-map.png
+  atmosphere nitrogen-oxygen
+object moon Seyra
+  orbit Naar
+  distance 384400km
+  groups inner-system
+event naar-eclipse
+  kind solar-eclipse
+  label "Naar Eclipse"
+  target Naar
+  participants Iyath Naar Seyra
+  epoch "JY-0001.0"
+  referencePlane ecliptic
+  positions
+    pose Naar
+      orbit Iyath
+      semiMajor 1.18au
+      phase 90deg
+    pose Seyra
+      orbit Naar
+      distance 384400km
+      phase 90deg
+```
+## What's New In Schema 3.1
+Schema `3.1` keeps Schema `3.0` and Schema `2.6` fully readable and expands WorldOrbit from declarative mission authoring into visible mission-curve rendering.
 It adds:
-* new viewpoint projections: `orthographic` and `perspective`
-* a Schema-level `camera` block with `azimuth`, `elevation`, optional `roll`, and optional `distance`
-* clearer inheritance for `epoch` and `referencePlane` across system, object, event, and pose contexts
-* more stable event snapshots, where missing pose fields fall back to object, event, and system context instead of implying empty values
-* stronger validation around viewpoints, camera fields, event/pose consistency, and ambiguous authoring combinations
-Schema `2.5` still does **not** add full 3D coordinates, meshes, materials, quaternions, lighting, or simulation-heavy orbital solving.
-Schema `2.1` already added comments, semantic `group` and `relation` sections, declarative `event` sections with per-event `positions`/`pose` snapshots, viewpoint-linked `events`, object-level `epoch` and `referencePlane`, declarative resonance and validation hints, and optional structured lore blocks such as `climate`, `habitability`, and `settlement`.
-Stable `1.0` source is still accepted. Canonical `schema 2.0` source remains fully supported, and legacy `schema 2.0-draft` files stay readable as a compatibility path with a deprecation diagnostic.
-## Basic Usage
-### Parse and load source
-```ts
-import {
-  loadWorldOrbitSource,
-  parse,
-} from "worldorbit";
-const parsed = parse(`
-system Iyath
-star Iyath
-planet Naar orbit Iyath distance 1.18au
-`.trim());
-const loaded = loadWorldOrbitSource(`
-schema 2.5
-system Iyath
-object star Iyath
-object planet Naar
-  orbit Iyath
-  semiMajor 1.18au
-`.trim());
-```
-### Render a scene
-```ts
-import {
-  loadWorldOrbitSource,
-  renderDocumentToScene,
-} from "worldorbit";
-const loaded = loadWorldOrbitSource(source);
-const scene = renderDocumentToScene(loaded.document, {
-  projection: "isometric",
-  scaleModel: {
-    orbitDistanceMultiplier: 1.1,
-    bodyRadiusMultiplier: 1.15,
-  },
-});
-```
-### Create an interactive viewer
-```ts
-import { loadWorldOrbitSource } from "worldorbit";
-import { createInteractiveViewer } from "worldorbit/viewer";
-const loaded = loadWorldOrbitSource(source);
-createInteractiveViewer(document.getElementById("preview"), {
-  document: loaded.document,
-  projection: "isometric",
-  theme: "atlas",
-  viewMode: "3d",
-});
-```
-## Package Overview
-WorldOrbit is organized internally as a small ecosystem.
-### `worldorbit`
-Public package entry point with browser bundles and main exports.
-### `worldorbit/core`
-Use this when you need:
-* parsing
-* normalization
-* validation
-* diagnostics
-* schema loading
-* canonical formatting
-* scene generation
-### `worldorbit/viewer`
-Use this when you need:
-* static SVG rendering
-* interactive viewing
-* atlas-style exploration
-* themes and embeds
-### `worldorbit/markdown`
-Use this when you want to transform fenced `worldorbit` blocks inside Markdown pipelines.
-### `worldorbit/editor`
-Use this when you want browser-based visual authoring on top of the text format.
-## Core Example
-```ts
-import {
-  formatDocument,
-  loadWorldOrbitSource,
-  parse,
-  parseWorldOrbitAtlas,
-  renderDocumentToScene,
-  upgradeDocumentToV2,
-} from "worldorbit/core";
-const stable = parse(`
-system Iyath
-star Iyath
-planet Naar orbit Iyath distance 1.18au
-`.trim());
-const atlasDocument = upgradeDocumentToV2(stable.document, {
-  preset: "atlas-card",
-});
-const atlasSource = formatDocument(atlasDocument, { schema: "2.5" });
-const loaded = loadWorldOrbitSource(atlasSource);
-const parsedAtlas = parseWorldOrbitAtlas(atlasSource);
-const scene = renderDocumentToScene(loaded.document, {
-  projection: "isometric",
-  scaleModel: {
-    orbitDistanceMultiplier: 1.1,
-    bodyRadiusMultiplier: 1.15,
-  },
-});
-```
-## Viewer Capabilities
-Viewer features in `v3.0.7` include:
-* scene-based SVG rendering
-* renderer-neutral spatial scenes through `renderDocumentToSpatialScene(...)`
-* a full 3D viewer mode on the same documents and placements as 2D
-* deterministic orbit animation with play, pause, reset, and speed controls
-* projections: `topdown`, `isometric`, `orthographic`, and `perspective`
-* theme presets: `atlas`, `nightglass`, `ember`
-* layer controls for background, guides, orbits, events, objects, labels, metadata, and relations
-* selection, hover, focus, fit, pan, zoom, and rotate
-* tooltip cards and object detail payloads
-* viewpoints, filters, search, and bookmark capture
-* deep-linkable atlas state
-* embeddable viewer custom elements
-* semantic group filters, relation and event overlays, active event scenes, Schema 2.5 camera metadata, and event/object reference-context detail metadata
-## Markdown Integration
-Use `worldorbit/markdown` to transform fenced `worldorbit` blocks into static output, interactive 2D output, or interactive 3D output.
-```ts
-import rehypeStringify from "rehype-stringify";
-import remarkParse from "remark-parse";
-import remarkRehype from "remark-rehype";
-import { unified } from "unified";
-import { remarkWorldOrbit } from "worldorbit/markdown";
-const html = String(
-  await unified()
-    .use(remarkParse)
-    .use(remarkWorldOrbit, { mode: "interactive-3d" })
-    .use(remarkRehype, { allowDangerousHtml: true })
-    .use(rehypeStringify, { allowDangerousHtml: true })
-    .process(markdownSource),
-);
-```
-In the browser:
-```ts
-import { mountWorldOrbitEmbeds } from "worldorbit/viewer";
-mountWorldOrbitEmbeds(document, {
-  mode: "interactive-3d",
-});
-```
-## Examples
-Examples live in:
-* [examples/minimal.worldorbit](./examples/minimal.worldorbit)
-* [examples/minimal-3d.worldorbit](./examples/minimal-3d.worldorbit)
-* [examples/showcase-3d.worldorbit](./examples/showcase-3d.worldorbit)
-* [examples/schema25-camera.worldorbit](./examples/schema25-camera.worldorbit)
-* [examples/schema25-event-snapshot.worldorbit](./examples/schema25-event-snapshot.worldorbit)
-* [examples/studio.schema25.worldorbit](./examples/studio.schema25.worldorbit)
-* [examples/iyath.worldorbit](./examples/iyath.worldorbit)
-* [examples/iyath.schema2.worldorbit](./examples/iyath.schema2.worldorbit)
-* [examples/iyath.schema21.worldorbit](./examples/iyath.schema21.worldorbit)
-* [examples/iyath.schema2-draft.worldorbit](./examples/iyath.schema2-draft.worldorbit)
-* [examples/markdown/static.md](./examples/markdown/static.md)
-* [examples/markdown/interactive.md](./examples/markdown/interactive.md)
-* [examples/markdown/build.mjs](./examples/markdown/build.mjs)
-Browser-facing examples and demos live in the repository under `demo/`, `studio/`, and `examples/`.
-## Documentation
-* [migration guide: v0.8 to v1.0](./docs/migration-v0.8-to-v1.0.md)
-* [migration guide: v1 to v2](./docs/migration-v1-to-v2.md)
-* [migration guide: v2.0 to v2.1](./docs/migration-v2-to-v2.1.md)
-* [migration guide: v2.1 to v2.5](./docs/migration-v2.1-to-v2.5.md)
-* [migration guide: v2.6 to v3.0](./docs/migration-v2.6-to-v3.0.md)
-* [language reference](./docs/language-reference.md)
-* [language reference (DE)](./docs/language-reference.de.md)
-* [API inventory](./docs/api-inventory.md)
-* [changelog](./docs/changelog.md)
-## Development
-```bash
-npm install
-npm run build
-npm test
-```
-The workspace builds outputs into package-specific distribution folders and browser bundles.
-Useful notes:
-* `npm run build` compiles all packages and refreshes local package shims
-* `npm test` rebuilds first, then runs the regression suite
-* the repository remains parser-first: rendering and atlas interaction stay downstream of parse, normalize, and validate
-## Project Direction
-WorldOrbit is intended as a specialized Mermaid-like solution for fictional orbital systems.
-The long-term focus is:
-* strong text-first authoring
-* clean Markdown embedding
-* rich static and interactive rendering
-* optional visual editing
-* stable schema evolution over time
-## License
-MIT
+* visible `trajectory` rendering in 2D and 3D scenes
+* official `illustrative`, `solver`, and `auto` trajectory render modes
+* trajectory waypoint labels, dates, marker controls, and per-segment render hints
+* official trajectory sampling APIs through `worldorbit/core/solver`
+* continued support for declarative `craft`, `trajectory`, `event`, and `pose` mission authoring
+Schema `3.1` still does **not** add a built-in N-body simulator, NASA-grade ephemerides, continuous freeform XYZ authoring, or hard astrophysics requirements.
+Schema `2.6` remains the direct compatibility base, and older documents continue to load through the same parser and normalization pipeline.
+Stable `1.0` source is still accepted. Canonical `schema 2.0` source remains fully supported, and legacy `schema 2.0-draft` files stay readable as a compatibility path with a deprecation diagnostic.
+## Basic Usage
+### Parse and load source
+```ts
+import {
+  loadWorldOrbitSource,
+  parse,
+} from "worldorbit";
+const parsed = parse(`
+system Iyath
+star Iyath
+planet Naar orbit Iyath distance 1.18au
+`.trim());
+const loaded = loadWorldOrbitSource(`
+schema 3.0
+system Iyath
+object star Iyath
+object planet Naar
+  orbit Iyath
+  semiMajor 1.18au
+`.trim());
+```
+### Render a scene
+```ts
+import {
+  loadWorldOrbitSource,
+  renderDocumentToScene,
+} from "worldorbit";
+const loaded = loadWorldOrbitSource(source);
+const scene = renderDocumentToScene(loaded.document, {
+  projection: "isometric",
+  scaleModel: {
+    orbitDistanceMultiplier: 1.1,
+    bodyRadiusMultiplier: 1.15,
+  },
+});
+```
+### Create an interactive viewer
+```ts
+import { loadWorldOrbitSource } from "worldorbit";
+import { createInteractiveViewer } from "worldorbit/viewer";
+const loaded = loadWorldOrbitSource(source);
+createInteractiveViewer(document.getElementById("preview"), {
+  document: loaded.document,
+  projection: "isometric",
+  theme: "atlas",
+  viewMode: "3d",
+});
+```
+## Package Overview
+WorldOrbit is organized internally as a small ecosystem.
+### `worldorbit`
+Public package entry point with browser bundles and main exports.
+### `worldorbit/core`
+Use this when you need:
+* parsing
+* normalization
+* validation
+* diagnostics
+* schema loading
+* canonical formatting
+* scene generation
+### `worldorbit/viewer`
+Use this when you need:
+* static SVG rendering
+* interactive viewing
+* atlas-style exploration
+* themes and embeds
+### `worldorbit/markdown`
+Use this when you want to transform fenced `worldorbit` blocks inside Markdown pipelines.
+### `worldorbit/editor`
+Use this when you want browser-based visual authoring on top of the text format.
+## Core Example
+```ts
+import {
+  formatDocument,
+  loadWorldOrbitSource,
+  parse,
+  parseWorldOrbitAtlas,
+  renderDocumentToScene,
+  upgradeDocumentToV2,
+} from "worldorbit/core";
+const stable = parse(`
+system Iyath
+star Iyath
+planet Naar orbit Iyath distance 1.18au
+`.trim());
+const atlasDocument = upgradeDocumentToV2(stable.document, {
+  preset: "atlas-card",
+});
+const atlasSource = formatDocument(atlasDocument, { schema: "3.1" });
+const loaded = loadWorldOrbitSource(atlasSource);
+const parsedAtlas = parseWorldOrbitAtlas(atlasSource);
+const scene = renderDocumentToScene(loaded.document, {
+  projection: "isometric",
+  scaleModel: {
+    orbitDistanceMultiplier: 1.1,
+    bodyRadiusMultiplier: 1.15,
+  },
+});
+```
+## Viewer Capabilities
+Viewer features in `v5.0.0` include:
+* scene-based SVG rendering
+* renderer-neutral spatial scenes through `renderDocumentToSpatialScene(...)`
+* a full 3D viewer mode on the same documents and placements as 2D
+* deterministic orbit animation with play, pause, reset, and speed controls
+* projections: `topdown`, `isometric`, `orthographic`, and `perspective`
+* theme presets: `atlas`, `nightglass`, `ember`
+* layer controls for background, guides, orbits, events, objects, labels, metadata, and relations
+* selection, hover, focus, fit, pan, zoom, and rotate
+* tooltip cards and object detail payloads
+* viewpoints, filters, search, and bookmark capture
+* deep-linkable atlas state
+* embeddable viewer custom elements
+* semantic group filters, relation and event overlays, active event scenes, Schema 3.1 camera and trajectory metadata, visible mission curves, waypoint labels, and event/object reference-context detail metadata
+## Markdown Integration
+Use `worldorbit/markdown` to transform fenced `worldorbit` blocks into static output, interactive 2D output, or interactive 3D output.
+```ts
+import rehypeStringify from "rehype-stringify";
+import remarkParse from "remark-parse";
+import remarkRehype from "remark-rehype";
+import { unified } from "unified";
+import { remarkWorldOrbit } from "worldorbit/markdown";
+const html = String(
+  await unified()
+    .use(remarkParse)
+    .use(remarkWorldOrbit, { mode: "interactive-3d" })
+    .use(remarkRehype, { allowDangerousHtml: true })
+    .use(rehypeStringify, { allowDangerousHtml: true })
+    .process(markdownSource),
+);
+```
+In the browser:
+```ts
+import { mountWorldOrbitEmbeds } from "worldorbit/viewer";
+mountWorldOrbitEmbeds(document, {
+  mode: "interactive-3d",
+});
+```
+## Examples
+Examples live in:
+* [examples/minimal.worldorbit](./examples/minimal.worldorbit)
+* [examples/minimal-3d.worldorbit](./examples/minimal-3d.worldorbit)
+* [examples/showcase-3d.worldorbit](./examples/showcase-3d.worldorbit)
+* [examples/schema25-camera.worldorbit](./examples/schema25-camera.worldorbit)
+* [examples/schema25-event-snapshot.worldorbit](./examples/schema25-event-snapshot.worldorbit)
+* [examples/studio.schema25.worldorbit](./examples/studio.schema25.worldorbit)
+* [examples/iyath.worldorbit](./examples/iyath.worldorbit)
+* [examples/iyath.schema2.worldorbit](./examples/iyath.schema2.worldorbit)
+* [examples/iyath.schema21.worldorbit](./examples/iyath.schema21.worldorbit)
+* [examples/iyath.schema2-draft.worldorbit](./examples/iyath.schema2-draft.worldorbit)
+* [examples/markdown/static.md](./examples/markdown/static.md)
+* [examples/markdown/interactive.md](./examples/markdown/interactive.md)
+* [examples/markdown/build.mjs](./examples/markdown/build.mjs)
+Browser-facing examples and demos live in the repository under `demo/`, `studio/`, and `examples/`.
+## Documentation
+* [migration guide: v0.8 to v1.0](./docs/migration-v0.8-to-v1.0.md)
+* [migration guide: v1 to v2](./docs/migration-v1-to-v2.md)
+* [migration guide: v2.0 to v2.1](./docs/migration-v2-to-v2.1.md)
+* [migration guide: v2.1 to v2.5](./docs/migration-v2.1-to-v2.5.md)
+* [migration guide: v2.6 to v3.0](./docs/migration-v2.6-to-v3.0.md)
+* [language reference](./docs/language-reference.md)
+* [language reference (DE)](./docs/language-reference.de.md)
+* [API inventory](./docs/api-inventory.md)
+* [changelog](./docs/changelog.md)
+## Development
+```bash
+npm install
+npm run build
+npm test
+```
+The workspace builds outputs into package-specific distribution folders and browser bundles.
+Useful notes:
+* `npm run build` compiles all packages and refreshes local package shims
+* `npm test` rebuilds first, then runs the regression suite
+* the repository remains parser-first: rendering and atlas interaction stay downstream of parse, normalize, and validate
+## Project Direction
+WorldOrbit is intended as a specialized Mermaid-like solution for fictional orbital systems.
+The long-term focus is:
+* strong text-first authoring
+* clean Markdown embedding
+* rich static and interactive rendering
+* optional visual editing
+* stable schema evolution over time
+## License
+MIT