worldorbit 4.0.0 → 5.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worldorbit",
-  "version": "4.0.0",
+  "version": "5.0.0",
   "description": "A text-based DSL and parser pipeline for orbital worldbuilding",
   "type": "module",
   "main": "./dist/unpkg/worldorbit.esm.js",

package/packages/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/packages/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/packages/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/packages/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;

package/packages/core/dist/scene.js

@@ -138,7 +138,8 @@ export function renderDocumentToScene(document, options = {}) {
     const labels = createSceneLabels(objects, width, height, scaleModel.labelMultiplier);
     const relations = createSceneRelations(document, objects);
     const events = createSceneEvents(document.events ?? [], objects, activeEventId);
-    const layers = createSceneLayers(orbitVisuals, relations, events, leaders, objects, labels);
+    const trajectories = createSceneTrajectories(document, objects, events, options);
+    const layers = createSceneLayers(orbitVisuals, trajectories, relations, events, leaders, objects, labels);
     const groups = createSceneGroups(objects, orbitVisuals, leaders, labels, relationships, scaleModel.labelMultiplier);
     const semanticGroups = createSceneSemanticGroups(document, objects);
     const viewpoints = createSceneViewpoints(document, schemaProjection, frame.preset, relationships, objectMap);
@@ -179,6 +180,7 @@ export function renderDocumentToScene(document, options = {}) {
         viewpoints,
         events,
         activeEventId,
+        trajectories,
         objects,
         orbitVisuals,
         relations,
@@ -662,7 +664,7 @@ function createLabelPlacement(object, direction, attempt, labelMultiplier) {
         }
     }
 }
-function createSceneLayers(orbitVisuals, relations, events, leaders, objects, labels) {
+function createSceneLayers(orbitVisuals, trajectories, relations, events, leaders, objects, labels) {
     const backOrbitIds = orbitVisuals
         .filter((visual) => !visual.hidden && Boolean(visual.backArcPath))
         .map((visual) => visual.renderId);
@@ -677,6 +679,15 @@ function createSceneLayers(orbitVisuals, relations, events, leaders, objects, la
         },
         { id: "orbits-back", renderIds: backOrbitIds },
         { id: "orbits-front", renderIds: frontOrbitIds },
+        {
+            id: "trajectories",
+            renderIds: trajectories
+                .filter((trajectory) => !trajectory.hidden)
+                .flatMap((trajectory) => [
+                trajectory.renderId,
+                ...trajectory.waypoints.filter((waypoint) => !waypoint.hidden).map((waypoint) => waypoint.renderId),
+            ]),
+        },
         {
             id: "relations",
             renderIds: relations.filter((relation) => !relation.hidden).map((relation) => relation.renderId),
@@ -819,6 +830,206 @@ function createSceneEvents(events, objects, activeEventId) {
     })
         .sort((left, right) => left.event.id.localeCompare(right.event.id));
 }
+function createSceneTrajectories(document, objects, events, options) {
+    const objectMap = new Map(objects.map((object) => [object.objectId, object]));
+    return document.trajectories
+        .map((trajectory) => createSceneTrajectory(trajectory, objectMap, events, options))
+        .sort((left, right) => left.trajectoryId.localeCompare(right.trajectoryId));
+}
+function createSceneTrajectory(trajectory, objectMap, events, options) {
+    const craftObject = trajectory.craftObjectId ? objectMap.get(trajectory.craftObjectId) ?? null : null;
+    const mode = resolveTrajectoryMode(trajectory, options);
+    const stroke = trajectory.stroke ?? trajectory.color ?? craftObject?.fillColor ?? null;
+    const strokeWidth = trajectory.strokeWidth ?? 2.4;
+    const showWaypoints = options.showTrajectoryWaypoints ?? trajectory.showWaypoints ?? true;
+    const labelMode = trajectory.labelMode ?? (options.showTrajectoryLabels === false ? "hidden" : "waypoint");
+    const pathParts = [];
+    const waypoints = [];
+    const objectIds = new Set();
+    let lastAnchor = craftObject;
+    if (craftObject) {
+        objectIds.add(craftObject.objectId);
+    }
+    trajectory.segments.forEach((segment, index) => {
+        const geometry = buildTrajectorySegmentGeometry(trajectory, segment, index, mode, objectMap, lastAnchor, showWaypoints);
+        if (geometry.path) {
+            pathParts.push(geometry.path);
+        }
+        geometry.objectIds.forEach((objectId) => objectIds.add(objectId));
+        waypoints.push(...geometry.waypoints);
+        lastAnchor = geometry.lastAnchor ?? lastAnchor;
+    });
+    for (const event of events.filter((entry) => entry.event.trajectoryId === trajectory.id)) {
+        const eventObject = event.targetObjectId
+            ? objectMap.get(event.targetObjectId) ?? null
+            : event.objectIds.map((objectId) => objectMap.get(objectId) ?? null).find(Boolean) ?? null;
+        if (!eventObject) {
+            continue;
+        }
+        waypoints.push({
+            renderId: `${createRenderId(`${trajectory.id}-${event.eventId}`)}-waypoint`,
+            trajectoryId: trajectory.id,
+            segmentId: null,
+            maneuverId: null,
+            objectId: eventObject.objectId,
+            x: eventObject.x,
+            y: eventObject.y,
+            label: event.event.label ?? event.event.id,
+            dateLabel: event.event.epoch ?? null,
+            hidden: trajectory.hidden || event.hidden || !showWaypoints,
+        });
+        objectIds.add(eventObject.objectId);
+    }
+    return {
+        renderId: `${createRenderId(trajectory.id)}-trajectory`,
+        trajectoryId: trajectory.id,
+        trajectory,
+        craftObjectId: trajectory.craftObjectId,
+        mode,
+        path: pathParts.join(" "),
+        stroke,
+        strokeWidth,
+        marker: trajectory.marker ?? "arrow",
+        labelMode,
+        showWaypoints,
+        objectIds: [...objectIds],
+        waypoints,
+        hidden: trajectory.hidden || pathParts.length === 0,
+    };
+}
+function buildTrajectorySegmentGeometry(trajectory, segment, segmentIndex, mode, objectMap, fallbackStart, showWaypoints) {
+    const start = resolveTrajectoryObject(segment.fromObjectId, objectMap) ??
+        fallbackStart;
+    const assist = resolveTrajectoryObject(segment.assist?.objectId ?? segment.aroundObjectId ?? null, objectMap);
+    const end = resolveTrajectoryObject(segment.toObjectId, objectMap) ??
+        resolveTrajectoryObject(segment.aroundObjectId, objectMap) ??
+        assist ??
+        start;
+    if (!start || !end) {
+        return {
+            path: "",
+            objectIds: [],
+            waypoints: [],
+            lastAnchor: fallbackStart,
+        };
+    }
+    const objectIds = [start.objectId, end.objectId];
+    if (assist) {
+        objectIds.push(assist.objectId);
+    }
+    const hidden = trajectory.hidden || segment.renderHidden === true || start.hidden || end.hidden;
+    const waypoints = [];
+    const label = segment.waypointLabel ?? segment.label ?? humanizeIdentifier(segment.id);
+    const dateLabel = segment.waypointDate ?? segment.epoch ?? null;
+    if (showWaypoints) {
+        if (segmentIndex === 0) {
+            waypoints.push(createTrajectoryWaypoint(trajectory.id, segment.id, null, start, start.label, null, hidden));
+        }
+        if (assist && assist.objectId !== start.objectId && assist.objectId !== end.objectId) {
+            waypoints.push(createTrajectoryWaypoint(trajectory.id, segment.id, null, assist, label, dateLabel, hidden));
+        }
+        waypoints.push(createTrajectoryWaypoint(trajectory.id, segment.id, null, end, label, dateLabel, hidden));
+    }
+    const samples = mode === "solver"
+        ? sampleQuadraticPoints(start, resolveTrajectoryControlPoint(start, end, assist, segmentIndex), end, Math.max(10, Math.round((segment.sampleDensity ?? 1) * 14)))
+        : null;
+    const control = resolveTrajectoryControlPoint(start, end, assist, segmentIndex);
+    const path = mode === "solver"
+        ? pointsToPath(samples ?? [start, end])
+        : `M ${formatPathNumber(start.x)} ${formatPathNumber(start.y)} Q ${formatPathNumber(control.x)} ${formatPathNumber(control.y)} ${formatPathNumber(end.x)} ${formatPathNumber(end.y)}`;
+    segment.maneuvers.forEach((maneuver, maneuverIndex) => {
+        if (!showWaypoints) {
+            return;
+        }
+        const point = samplePointOnQuadratic(start, control, end, (maneuverIndex + 1) / (segment.maneuvers.length + 1));
+        waypoints.push({
+            renderId: `${createRenderId(`${trajectory.id}-${segment.id}-${maneuver.id}`)}-waypoint`,
+            trajectoryId: trajectory.id,
+            segmentId: segment.id,
+            maneuverId: maneuver.id,
+            objectId: null,
+            x: point.x,
+            y: point.y,
+            label: maneuver.label ?? maneuver.kind,
+            dateLabel: maneuver.epoch ?? null,
+            hidden,
+        });
+    });
+    return {
+        path,
+        objectIds: [...new Set(objectIds)],
+        waypoints,
+        lastAnchor: end,
+    };
+}
+function createTrajectoryWaypoint(trajectoryId, segmentId, maneuverId, object, label, dateLabel, hidden) {
+    return {
+        renderId: `${createRenderId(`${trajectoryId}-${segmentId ?? object.objectId}-${maneuverId ?? object.objectId}`)}-waypoint`,
+        trajectoryId,
+        segmentId,
+        maneuverId,
+        objectId: object.objectId,
+        x: object.x,
+        y: object.y,
+        label,
+        dateLabel,
+        hidden,
+    };
+}
+function resolveTrajectoryMode(trajectory, options) {
+    const requested = options.trajectoryMode ?? trajectory.renderMode ?? "auto";
+    if (requested !== "auto") {
+        return requested;
+    }
+    const segmentCount = trajectory.segments.filter((segment) => segment.fromObjectId || segment.toObjectId || segment.assist?.objectId || segment.aroundObjectId).length;
+    return segmentCount > 0 ? "solver" : "illustrative";
+}
+function resolveTrajectoryObject(objectId, objectMap) {
+    return objectId ? objectMap.get(objectId) ?? null : null;
+}
+function resolveTrajectoryControlPoint(start, end, assist, segmentIndex) {
+    if (assist) {
+        return {
+            x: assist.x,
+            y: assist.y,
+        };
+    }
+    const dx = end.x - start.x;
+    const dy = end.y - start.y;
+    const length = Math.max(Math.hypot(dx, dy), 1);
+    const offset = Math.min(Math.max(length * 0.18, 26), 120) * (segmentIndex % 2 === 0 ? 1 : -1);
+    const normalX = -dy / length;
+    const normalY = dx / length;
+    return {
+        x: (start.x + end.x) / 2 + normalX * offset,
+        y: (start.y + end.y) / 2 + normalY * offset,
+    };
+}
+function sampleQuadraticPoints(start, control, end, count) {
+    const samples = [];
+    for (let index = 0; index <= count; index += 1) {
+        samples.push(samplePointOnQuadratic(start, control, end, index / count));
+    }
+    return samples;
+}
+function samplePointOnQuadratic(start, control, end, t) {
+    const inverse = 1 - t;
+    return {
+        x: inverse * inverse * start.x + 2 * inverse * t * control.x + t * t * end.x,
+        y: inverse * inverse * start.y + 2 * inverse * t * control.y + t * t * end.y,
+    };
+}
+function pointsToPath(points) {
+    if (points.length === 0) {
+        return "";
+    }
+    return points
+        .map((point, index) => `${index === 0 ? "M" : "L"} ${formatPathNumber(point.x)} ${formatPathNumber(point.y)}`)
+        .join(" ");
+}
+function formatPathNumber(value) {
+    return Number.isFinite(value) ? value.toFixed(2) : "0";
+}
 function createSceneViewpoints(document, projection, preset, relationships, objectMap) {
     const generatedOverview = createGeneratedOverviewViewpoint(document, projection, preset);
     const drafts = new Map();
@@ -1099,7 +1310,8 @@ function parseViewpointLayers(value) {
             rawLayer === "events" ||
             rawLayer === "objects" ||
             rawLayer === "labels" ||
-            rawLayer === "metadata") {
+            rawLayer === "metadata" ||
+            rawLayer === "trajectories") {
             next[rawLayer] = enabled;
         }
     }

package/packages/core/dist/solver.d.ts

@@ -1,4 +1,4 @@
-import type { UnitValue, WorldOrbitTrajectory, WorldOrbitTrajectorySegment } from "./types.js";
+import type { SceneRenderOptions, SpatialTrajectory, UnitValue, WorldOrbitDocument, WorldOrbitTrajectory, WorldOrbitTrajectorySegment } from "./types.js";
 export interface SolverSegmentSample {
     segmentId: string;
     kind: WorldOrbitTrajectorySegment["kind"];
@@ -23,4 +23,11 @@ export interface SolverTrajectorySnapshot {
     segments: SolverSegmentSample[];
     maneuvers: SolverManeuverSample[];
 }
+export interface TrajectorySamplingOptions extends Pick<SceneRenderOptions, "width" | "height" | "padding" | "preset" | "projection" | "camera" | "scaleModel" | "bodyScaleMode"> {
+    trajectoryMode?: "illustrative" | "solver" | "auto";
+    showTrajectoryWaypoints?: boolean;
+    showTrajectoryLabels?: boolean;
+}
 export declare function createTrajectorySolverSnapshot(trajectory: WorldOrbitTrajectory): SolverTrajectorySnapshot;
+export declare function sampleTrajectory(trajectory: WorldOrbitTrajectory, document: WorldOrbitDocument, options?: TrajectorySamplingOptions): SpatialTrajectory | null;
+export declare function sampleDocumentTrajectories(document: WorldOrbitDocument, options?: TrajectorySamplingOptions): SpatialTrajectory[];