worldorbit 4.0.0 → 5.0.0

package/README.md

@@ -29,7 +29,7 @@ WorldOrbit is not intended to be a real-world astronomy simulator or a high-prec
 ## Quick Example
 
 ```worldorbit
-schema 3.0
+schema 3.1
 
 system Iyath
   title "Iyath System"
@@ -138,10 +138,10 @@ For direct browser usage, use the browser bundle:
       import {
         createInteractiveViewer,
         loadWorldOrbitSource
-      } from "https://unpkg.com/worldorbit@4.0.0/dist/unpkg/worldorbit.esm.js";
+      } from "https://unpkg.com/worldorbit@5.0.0/dist/unpkg/worldorbit.esm.js";
 
       const source = `
-schema 3.0
+schema 3.1
 
 system Iyath
   epoch "JY-0001.0"
@@ -196,10 +196,10 @@ The editor is optional. The core format remains text-first.
 
 ## Canonical Schema
 
-New atlas authoring should start with:
+New atlas authoring should start with:
 
 ```worldorbit
-schema 3.0
+schema 3.1
 ```
 
 Example:
@@ -279,20 +279,19 @@ event naar-eclipse
       phase 90deg
 ```
 
-## What's New In Schema 3.0
+## What's New In Schema 3.1
 
-Schema `3.0` keeps Schema `2.6` fully readable and expands WorldOrbit from orbit-only worldbuilding into declarative mission and trajectory authoring.
+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:
+It adds:
 
-* a canonical `craft` object type for ships, probes, and stations
-* a declarative `trajectory` top-level block for reusable mission paths
-* trajectory segments for transfers, departures, flybys, captures, escapes, and stationkeeping
-* swing-by and gravity-assist metadata such as `assist`, `turnAngle`, `periapsis`, `deltaV`, and `energy`
-* explicit links between `craft`, `trajectory`, `event`, and `pose` snapshots for curated mission states
-* a solver-friendly data model without forcing the core parser to perform numerical simulation
+* 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.0` still does **not** add a built-in orbital solver, continuous XYZ path authoring, meshes, materials, quaternions, or lighting.
+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.
 
@@ -419,7 +418,7 @@ const atlasDocument = upgradeDocumentToV2(stable.document, {
   preset: "atlas-card",
 });
 
-const atlasSource = formatDocument(atlasDocument, { schema: "3.0" });
+const atlasSource = formatDocument(atlasDocument, { schema: "3.1" });
 const loaded = loadWorldOrbitSource(atlasSource);
 const parsedAtlas = parseWorldOrbitAtlas(atlasSource);
 const scene = renderDocumentToScene(loaded.document, {
@@ -433,7 +432,7 @@ const scene = renderDocumentToScene(loaded.document, {
 
 ## Viewer Capabilities
 
-Viewer features in `v4.0.0` include:
+Viewer features in `v5.0.0` include:
 
 * scene-based SVG rendering
 * renderer-neutral spatial scenes through `renderDocumentToSpatialScene(...)`
@@ -447,7 +446,7 @@ Viewer features in `v4.0.0` include:
 * 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.0 camera metadata, mission trajectory overlays, and event/object reference-context detail metadata
+* 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
 

package/dist/browser/core/dist/draft-parse.js

@@ -179,7 +179,7 @@ function parseAtlasSource(source, forcedOutputVersion) {
         handleSectionLine(section, indent, tokens, lineNumber);
     }
     if (!sawSchemaHeader) {
-        throw new WorldOrbitError('Missing required atlas schema header "schema 2.0" or "schema 3.0"');
+        throw new WorldOrbitError('Missing required atlas schema header "schema 2.0", "schema 3.0", or "schema 3.1"');
     }
     const objects = objectNodes.map((node) => normalizeDraftObject(node, sourceSchemaVersion, diagnostics));
     const normalizedEvents = events.map((event) => normalizeDraftEvent(event, eventPoseNodes.get(event.id) ?? []));
@@ -225,21 +225,23 @@ function parseAtlasSource(source, forcedOutputVersion) {
 function assertDraftSchemaHeader(tokens, line) {
     if (tokens.length !== 2 ||
         tokens[0].value.toLowerCase() !== "schema" ||
-        !["2.0-draft", "2.0", "2.1", "2.5", "2.6", "3.0"].includes(tokens[1].value.toLowerCase())) {
-        throw new WorldOrbitError('Expected atlas header "schema 2.0", "schema 2.1", "schema 2.5", "schema 2.6", "schema 3.0", or legacy "schema 2.0-draft"', line, tokens[0]?.column ?? 1);
+        !["2.0-draft", "2.0", "2.1", "2.5", "2.6", "3.0", "3.1"].includes(tokens[1].value.toLowerCase())) {
+        throw new WorldOrbitError('Expected atlas header "schema 2.0", "schema 2.1", "schema 2.5", "schema 2.6", "schema 3.0", "schema 3.1", or legacy "schema 2.0-draft"', line, tokens[0]?.column ?? 1);
     }
     const version = tokens[1].value.toLowerCase();
     return version === "2.6"
         ? "2.6"
         : version === "3.0"
             ? "3.0"
-            : version === "2.5"
-                ? "2.5"
-                : version === "2.1"
-                    ? "2.1"
-                    : version === "2.0-draft"
-                        ? "2.0-draft"
-                        : "2.0";
+            : version === "3.1"
+                ? "3.1"
+                : version === "2.5"
+                    ? "2.5"
+                    : version === "2.1"
+                        ? "2.1"
+                        : version === "2.0-draft"
+                            ? "2.0-draft"
+                            : "2.0";
 }
 function startTopLevelSection(tokens, line, sourceSchemaVersion, diagnostics, system, objectNodes, groups, relations, events, trajectories, eventPoseNodes, viewpointIds, annotationIds, groupIds, relationIds, eventIds, trajectoryIds, flags) {
     const keyword = tokens[0]?.value.toLowerCase();
@@ -523,6 +525,12 @@ function startTrajectorySection(tokens, line, trajectories, trajectoryIds, sourc
         craftObjectId: null,
         tags: [],
         color: null,
+        renderMode: null,
+        stroke: null,
+        strokeWidth: null,
+        marker: null,
+        labelMode: null,
+        showWaypoints: null,
         hidden: false,
         segments: [],
     };
@@ -1090,6 +1098,10 @@ function applyTrajectoryField(section, indent, tokens, line) {
             aroundObjectId: null,
             assist: null,
             epoch: null,
+            waypointLabel: null,
+            waypointDate: null,
+            renderHidden: null,
+            sampleDensity: null,
             notes: [],
             maneuvers: [],
         };
@@ -1124,6 +1136,54 @@ function applyTrajectoryField(section, indent, tokens, line) {
         case "color":
             section.trajectory.color = value;
             return;
+        case "rendermode":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "trajectory.renderMode", {
+                line,
+                column: tokens[0].column,
+            });
+            if (value !== "illustrative" && value !== "solver" && value !== "auto") {
+                throw new WorldOrbitError(`Unknown trajectory render mode "${value}"`, line, tokens[0].column);
+            }
+            section.trajectory.renderMode = value;
+            return;
+        case "stroke":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "trajectory.stroke", {
+                line,
+                column: tokens[0].column,
+            });
+            section.trajectory.stroke = value;
+            return;
+        case "strokewidth":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "trajectory.strokeWidth", {
+                line,
+                column: tokens[0].column,
+            });
+            section.trajectory.strokeWidth = parsePositiveNumber(value, line, tokens[0].column, "strokeWidth");
+            return;
+        case "marker":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "trajectory.marker", {
+                line,
+                column: tokens[0].column,
+            });
+            section.trajectory.marker = value;
+            return;
+        case "labelmode":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "trajectory.labelMode", {
+                line,
+                column: tokens[0].column,
+            });
+            section.trajectory.labelMode = value;
+            return;
+        case "showwaypoints":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "trajectory.showWaypoints", {
+                line,
+                column: tokens[0].column,
+            });
+            section.trajectory.showWaypoints = parseAtlasBoolean(value, "showWaypoints", {
+                line,
+                column: tokens[0].column,
+            });
+            return;
         case "hidden":
             section.trajectory.hidden = parseAtlasBoolean(value, "hidden", {
                 line,
@@ -1199,6 +1259,37 @@ function applyTrajectorySegmentField(section, tokens, line) {
         case "energy":
             target.energy = parseAtlasUnitValue(value, { line, column: tokens[0].column });
             return;
+        case "waypointlabel":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "segment.waypointLabel", {
+                line,
+                column: tokens[0].column,
+            });
+            target.waypointLabel = value;
+            return;
+        case "waypointdate":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "segment.waypointDate", {
+                line,
+                column: tokens[0].column,
+            });
+            target.waypointDate = value;
+            return;
+        case "renderhidden":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "segment.renderHidden", {
+                line,
+                column: tokens[0].column,
+            });
+            target.renderHidden = parseAtlasBoolean(value, "renderHidden", {
+                line,
+                column: tokens[0].column,
+            });
+            return;
+        case "sampledensity":
+            warnIfSchema31Feature(section.sourceSchemaVersion, section.diagnostics, "segment.sampleDensity", {
+                line,
+                column: tokens[0].column,
+            });
+            target.sampleDensity = parsePositiveNumber(value, line, tokens[0].column, "sampleDensity");
+            return;
         case "notes":
             target.notes = parseTokenList(tokens.slice(1), line, "notes");
             return;
@@ -1345,7 +1436,8 @@ function parseLayerTokens(tokens, line, sourceSchemaVersion, diagnostics) {
             raw === "events" ||
             raw === "objects" ||
             raw === "labels" ||
-            raw === "metadata") {
+            raw === "metadata" ||
+            raw === "trajectories") {
             if (raw === "events" && sourceSchemaVersion && diagnostics) {
                 warnIfSchema21Feature(sourceSchemaVersion, diagnostics, "layers.events", {
                     line,
@@ -1476,6 +1568,12 @@ function parseInlineObjectFields(tokens, line, objectType, sourceSchemaVersion,
                 column: keyToken.column,
             });
         }
+        else if (spec.version === "3.1") {
+            warnIfSchema31Feature(sourceSchemaVersion, diagnostics, keyToken.value, {
+                line,
+                column: keyToken.column,
+            });
+        }
         index++;
         const valueTokens = [];
         if (spec.inlineMode === "single") {
@@ -1534,6 +1632,12 @@ function parseObjectField(tokens, line, objectType, sourceSchemaVersion, diagnos
             column: tokens[0].column,
         });
     }
+    else if (spec.version === "3.1") {
+        warnIfSchema31Feature(sourceSchemaVersion, diagnostics, tokens[0].value, {
+            line,
+            column: tokens[0].column,
+        });
+    }
     const field = {
         type: "field",
         key: tokens[0].value,
@@ -1876,6 +1980,19 @@ function warnIfSchema30Feature(sourceSchemaVersion, diagnostics, featureName, lo
         column: location.column,
     });
 }
+function warnIfSchema31Feature(sourceSchemaVersion, diagnostics, featureName, location) {
+    if (!isSchemaOlderThan(sourceSchemaVersion, "3.1")) {
+        return;
+    }
+    diagnostics.push({
+        code: "parse.schema31.featureCompatibility",
+        severity: "warning",
+        source: "parse",
+        message: `Feature "${featureName}" requires schema 3.1; parsed in compatibility mode because the document header is "schema ${sourceSchemaVersion}".`,
+        line: location.line,
+        column: location.column,
+    });
+}
 function isSchemaOlderThan(sourceSchemaVersion, requiredVersion) {
     return schemaVersionRank(sourceSchemaVersion) < schemaVersionRank(requiredVersion);
 }
@@ -1893,8 +2010,10 @@ function schemaVersionRank(version) {
             return 4;
         case "3.0":
             return 5;
-        default:
+        case "3.1":
             return 6;
+        default:
+            return 7;
     }
 }
 function preprocessAtlasSource(source) {

package/dist/browser/core/dist/draft.js

@@ -18,15 +18,15 @@ export function upgradeDocumentToV2(document, options = {}) {
     }
     return {
         format: "worldorbit",
-        version: "3.0",
-        schemaVersion: "3.0",
+        version: "3.1",
+        schemaVersion: "3.1",
         sourceVersion: document.version,
         theme: document.theme ?? null,
         system,
         groups: structuredClone(document.groups ?? []),
         relations: structuredClone(document.relations ?? []),
         events: structuredClone(document.events ?? []),
-        trajectories: [],
+        trajectories: structuredClone(document.trajectories ?? []),
         objects: document.objects.map(cloneWorldOrbitObject).map(normalizeLegacyCraftObject),
         diagnostics,
     };
@@ -490,7 +490,7 @@ function serializeViewpointLayers(layers) {
     if (orbitFront !== undefined || orbitBack !== undefined) {
         tokens.push(orbitFront !== false || orbitBack !== false ? "orbits" : "-orbits");
     }
-    for (const key of ["background", "guides", "relations", "events", "objects", "labels", "metadata"]) {
+    for (const key of ["background", "guides", "relations", "events", "objects", "trajectories", "labels", "metadata"]) {
         if (layers[key] !== undefined) {
             tokens.push(layers[key] ? key : `-${key}`);
         }

package/dist/browser/core/dist/format.js

@@ -41,11 +41,13 @@ export function formatDocument(document, options = {}) {
         schema === "2.5" ||
         schema === "2.6" ||
         schema === "3.0" ||
+        schema === "3.1" ||
         schema === "2.0-draft" ||
         document.version === "2.0" ||
         document.version === "2.1" ||
         document.version === "2.5" ||
         document.version === "3.0" ||
+        document.version === "3.1" ||
         document.version === "2.6" ||
         document.version === "2.0-draft";
     if (useDraft) {
@@ -61,7 +63,12 @@ export function formatDocument(document, options = {}) {
                     : upgradeDocumentToDraftV2(document);
             return formatDraftDocument(legacyDraftDocument);
         }
-        const atlasDocument = document.version === "2.0" || document.version === "2.1" || document.version === "2.5" || document.version === "2.6" || document.version === "3.0"
+        const atlasDocument = document.version === "2.0" ||
+            document.version === "2.1" ||
+            document.version === "2.5" ||
+            document.version === "2.6" ||
+            document.version === "3.0" ||
+            document.version === "3.1"
             ? document
             : document.version === "2.0-draft"
                 ? {
@@ -70,7 +77,13 @@ export function formatDocument(document, options = {}) {
                     schemaVersion: "2.0",
                 }
                 : upgradeDocumentToV2(document);
-        if ((schema === "2.0" || schema === "2.1" || schema === "2.5" || schema === "2.6" || schema === "3.0") && atlasDocument.version !== schema) {
+        if ((schema === "2.0" ||
+            schema === "2.1" ||
+            schema === "2.5" ||
+            schema === "2.6" ||
+            schema === "3.0" ||
+            schema === "3.1") &&
+            atlasDocument.version !== schema) {
             return formatAtlasDocument({
                 ...atlasDocument,
                 version: schema,
@@ -534,6 +547,24 @@ function formatAtlasTrajectory(trajectory) {
     if (trajectory.color) {
         lines.push(`  color ${quoteIfNeeded(trajectory.color)}`);
     }
+    if (trajectory.renderMode) {
+        lines.push(`  renderMode ${trajectory.renderMode}`);
+    }
+    if (trajectory.stroke) {
+        lines.push(`  stroke ${quoteIfNeeded(trajectory.stroke)}`);
+    }
+    if (trajectory.strokeWidth !== null && trajectory.strokeWidth !== undefined) {
+        lines.push(`  strokeWidth ${trajectory.strokeWidth}`);
+    }
+    if (trajectory.marker) {
+        lines.push(`  marker ${quoteIfNeeded(trajectory.marker)}`);
+    }
+    if (trajectory.labelMode) {
+        lines.push(`  labelMode ${quoteIfNeeded(trajectory.labelMode)}`);
+    }
+    if (trajectory.showWaypoints !== null && trajectory.showWaypoints !== undefined) {
+        lines.push(`  showWaypoints ${trajectory.showWaypoints ? "true" : "false"}`);
+    }
     if (trajectory.hidden) {
         lines.push("  hidden true");
     }
@@ -570,6 +601,14 @@ function formatTrajectorySegmentFields(segment) {
         ...formatOptionalUnit("phaseAngle", segment.phaseAngle),
         ...formatOptionalUnit("turnAngle", segment.turnAngle),
         ...formatOptionalUnit("energy", segment.energy),
+        ...(segment.waypointLabel ? [`waypointLabel ${quoteIfNeeded(segment.waypointLabel)}`] : []),
+        ...(segment.waypointDate ? [`waypointDate ${quoteIfNeeded(segment.waypointDate)}`] : []),
+        ...(segment.renderHidden !== null && segment.renderHidden !== undefined
+            ? [`renderHidden ${segment.renderHidden ? "true" : "false"}`]
+            : []),
+        ...(segment.sampleDensity !== null && segment.sampleDensity !== undefined
+            ? [`sampleDensity ${segment.sampleDensity}`]
+            : []),
         ...(segment.notes.length > 0 ? [`notes ${segment.notes.map(quoteIfNeeded).join(" ")}`] : []),
     ];
 }
@@ -634,7 +673,7 @@ function formatDraftLayers(layers) {
             ? "orbits"
             : "-orbits");
     }
-    for (const key of ["background", "guides", "relations", "events", "objects", "labels", "metadata"]) {
+    for (const key of ["background", "guides", "relations", "events", "objects", "trajectories", "labels", "metadata"]) {
         if (layers[key] !== undefined) {
             tokens.push(layers[key] ? key : `-${key}`);
         }

package/dist/browser/core/dist/load.js

@@ -5,11 +5,12 @@ import { WorldOrbitError } from "./errors.js";
 import { normalizeDocument } from "./normalize.js";
 import { parseWorldOrbit } from "./parse.js";
 import { validateDocument } from "./validate.js";
-const ATLAS_SCHEMA_PATTERN = /^schema\s+(?:2(?:\.0|\.1|\.5|\.6)?|3(?:\.0)?)$/i;
+const ATLAS_SCHEMA_PATTERN = /^schema\s+(?:2(?:\.0|\.1|\.5|\.6)?|3(?:\.0|\.1)?)$/i;
 const ATLAS_SCHEMA_21_PATTERN = /^schema\s+2\.1$/i;
 const ATLAS_SCHEMA_25_PATTERN = /^schema\s+2\.5$/i;
 const ATLAS_SCHEMA_26_PATTERN = /^schema\s+2\.6$/i;
 const ATLAS_SCHEMA_30_PATTERN = /^schema\s+3(?:\.0)?$/i;
+const ATLAS_SCHEMA_31_PATTERN = /^schema\s+3\.1$/i;
 const LEGACY_DRAFT_SCHEMA_PATTERN = /^schema\s+2\.0-draft$/i;
 export function detectWorldOrbitSchemaVersion(source) {
     for (const line of stripCommentsForSchemaDetection(source).split(/\r?\n/)) {
@@ -32,6 +33,9 @@ export function detectWorldOrbitSchemaVersion(source) {
         if (ATLAS_SCHEMA_30_PATTERN.test(trimmed)) {
             return "3.0";
         }
+        if (ATLAS_SCHEMA_31_PATTERN.test(trimmed)) {
+            return "3.1";
+        }
         if (ATLAS_SCHEMA_PATTERN.test(trimmed)) {
             return "2.0";
         }
@@ -97,7 +101,8 @@ export function loadWorldOrbitSourceWithDiagnostics(source) {
         schemaVersion === "2.1" ||
         schemaVersion === "2.5" ||
         schemaVersion === "2.6" ||
-        schemaVersion === "3.0") {
+        schemaVersion === "3.0" ||
+        schemaVersion === "3.1") {
         return loadAtlasSourceWithDiagnostics(source, schemaVersion);
     }
     let ast;