worldorbit 2.5.13 → 2.5.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worldorbit",
-  "version": "2.5.13",
+  "version": "2.5.15",
   "description": "A text-based DSL and parser pipeline for orbital worldbuilding",
   "type": "module",
   "main": "./dist/unpkg/worldorbit.esm.js",
@@ -64,4 +64,4 @@
     "typescript": "^5.6.0",
     "unified": "^11.0.5"
   }
-}
+}

package/packages/core/README.md

@@ -1,13 +1,17 @@
 # @worldorbit/core
 
-WorldOrbit core contains the parser, schema, normalization, validation, formatting, and scene generation APIs.
+WorldOrbit core contains the parser, schema, normalization, validation, formatting, and scene generation APIs for Schema 1.0, canonical Schema 2.0, and Schema 2.1 atlas source.
 
 Main exports:
 
 - `parse(source)`
+- `parseWorldOrbitAtlas(source)`
+- `parseWorldOrbitDraft(source)`
 - `parseWorldOrbit(source)`
 - `normalizeDocument(ast)`
 - `validateDocument(document)`
+- `validateAtlasDocumentWithDiagnostics(document)`
 - `renderDocumentToScene(document, options?)`
 - `formatDocument(document)`
+- `loadWorldOrbitSource(source)`
 - `extractWorldOrbitBlocks(markdown)`

package/packages/core/dist/atlas-edit.d.ts

@@ -1,5 +1,5 @@
-import type { AtlasDocumentPath, AtlasResolvedDiagnostic, WorldOrbitAtlasDocument, WorldOrbitDiagnostic } from "./types.js";
-export declare function createEmptyAtlasDocument(systemId?: string): WorldOrbitAtlasDocument;
+import type { AtlasDocumentPath, AtlasResolvedDiagnostic, WorldOrbitAtlasDocument, WorldOrbitAtlasDocumentVersion, WorldOrbitDiagnostic } from "./types.js";
+export declare function createEmptyAtlasDocument(systemId?: string, version?: WorldOrbitAtlasDocumentVersion): WorldOrbitAtlasDocument;
 export declare function cloneAtlasDocument(document: WorldOrbitAtlasDocument): WorldOrbitAtlasDocument;
 export declare function listAtlasDocumentPaths(document: WorldOrbitAtlasDocument): AtlasDocumentPath[];
 export declare function getAtlasDocumentNode(document: WorldOrbitAtlasDocument, path: AtlasDocumentPath): unknown;

package/packages/core/dist/atlas-edit.js

@@ -1,14 +1,17 @@
-import { materializeAtlasDocument } from "./draft.js";
-import { validateDocumentWithDiagnostics } from "./diagnostics.js";
-export function createEmptyAtlasDocument(systemId = "WorldOrbit") {
+import { collectAtlasDiagnostics } from "./atlas-validate.js";
+export function createEmptyAtlasDocument(systemId = "WorldOrbit", version = "2.0") {
     return {
         format: "worldorbit",
-        version: "2.0",
+        version,
+        schemaVersion: version,
         sourceVersion: "1.0",
         system: {
             type: "system",
             id: systemId,
             title: systemId,
+            description: null,
+            epoch: null,
+            referencePlane: null,
             defaults: {
                 view: "topdown",
                 scale: null,
@@ -20,6 +23,8 @@ export function createEmptyAtlasDocument(systemId = "WorldOrbit") {
             viewpoints: [],
             annotations: [],
         },
+        groups: [],
+        relations: [],
         objects: [],
         diagnostics: [],
     };
@@ -40,6 +45,12 @@ export function listAtlasDocumentPaths(document) {
             paths.push({ kind: "annotation", id: annotation.id });
         }
     }
+    for (const group of [...document.groups].sort(compareIdLike)) {
+        paths.push({ kind: "group", id: group.id });
+    }
+    for (const relation of [...document.relations].sort(compareIdLike)) {
+        paths.push({ kind: "relation", id: relation.id });
+    }
     for (const object of [...document.objects].sort(compareIdLike)) {
         paths.push({ kind: "object", id: object.id });
     }
@@ -53,12 +64,16 @@ export function getAtlasDocumentNode(document, path) {
             return document.system?.defaults ?? null;
         case "metadata":
             return path.key ? (document.system?.atlasMetadata[path.key] ?? null) : null;
+        case "group":
+            return path.id ? findGroup(document, path.id) : null;
         case "object":
             return path.id ? findObject(document, path.id) : null;
         case "viewpoint":
             return path.id ? findViewpoint(document.system, path.id) : null;
         case "annotation":
             return path.id ? findAnnotation(document.system, path.id) : null;
+        case "relation":
+            return path.id ? findRelation(document, path.id) : null;
     }
 }
 export function upsertAtlasDocumentNode(document, path, value) {
@@ -85,6 +100,12 @@ export function upsertAtlasDocumentNode(document, path, value) {
                 system.atlasMetadata[path.key] = String(value);
             }
             return next;
+        case "group":
+            if (!path.id) {
+                throw new Error('Group updates require an "id" value.');
+            }
+            upsertById(next.groups, value);
+            return next;
         case "object":
             if (!path.id) {
                 throw new Error('Object updates require an "id" value.');
@@ -103,6 +124,12 @@ export function upsertAtlasDocumentNode(document, path, value) {
             }
             upsertById(system.annotations, value);
             return next;
+        case "relation":
+            if (!path.id) {
+                throw new Error('Relation updates require an "id" value.');
+            }
+            upsertById(next.relations, value);
+            return next;
     }
 }
 export function updateAtlasDocumentNode(document, path, updater) {
@@ -122,6 +149,11 @@ export function removeAtlasDocumentNode(document, path) {
                 next.objects = next.objects.filter((object) => object.id !== path.id);
             }
             return next;
+        case "group":
+            if (path.id) {
+                next.groups = next.groups.filter((group) => group.id !== path.id);
+            }
+            return next;
         case "viewpoint":
             if (path.id) {
                 system.viewpoints = system.viewpoints.filter((viewpoint) => viewpoint.id !== path.id);
@@ -132,6 +164,11 @@ export function removeAtlasDocumentNode(document, path) {
                 system.annotations = system.annotations.filter((annotation) => annotation.id !== path.id);
             }
             return next;
+        case "relation":
+            if (path.id) {
+                next.relations = next.relations.filter((relation) => relation.id !== path.id);
+            }
+            return next;
         default:
             return next;
     }
@@ -149,6 +186,15 @@ export function resolveAtlasDiagnosticPath(document, diagnostic) {
             id: diagnostic.objectId,
         };
     }
+    if (diagnostic.field?.startsWith("group.")) {
+        const parts = diagnostic.field.split(".");
+        if (parts[1] && findGroup(document, parts[1])) {
+            return {
+                kind: "group",
+                id: parts[1],
+            };
+        }
+    }
     if (diagnostic.field?.startsWith("viewpoint.")) {
         const parts = diagnostic.field.split(".");
         if (parts[1] && findViewpoint(document.system, parts[1])) {
@@ -167,6 +213,15 @@ export function resolveAtlasDiagnosticPath(document, diagnostic) {
             };
         }
     }
+    if (diagnostic.field?.startsWith("relation.")) {
+        const parts = diagnostic.field.split(".");
+        if (parts[1] && findRelation(document, parts[1])) {
+            return {
+                kind: "relation",
+                id: parts[1],
+            };
+        }
+    }
     if (diagnostic.field && diagnostic.field in ensureSystem(document).atlasMetadata) {
         return {
             kind: "metadata",
@@ -176,9 +231,11 @@ export function resolveAtlasDiagnosticPath(document, diagnostic) {
     return null;
 }
 export function validateAtlasDocumentWithDiagnostics(document) {
-    const materialized = materializeAtlasDocument(document);
-    const result = validateDocumentWithDiagnostics(materialized);
-    return resolveAtlasDiagnostics(document, result.diagnostics);
+    const diagnostics = [
+        ...document.diagnostics,
+        ...collectAtlasDiagnostics(document, document.version),
+    ];
+    return resolveAtlasDiagnostics(document, diagnostics);
 }
 function ensureSystem(document) {
     if (document.system) {
@@ -190,6 +247,12 @@ function ensureSystem(document) {
 function findObject(document, objectId) {
     return document.objects.find((object) => object.id === objectId) ?? null;
 }
+function findGroup(document, groupId) {
+    return document.groups.find((group) => group.id === groupId) ?? null;
+}
+function findRelation(document, relationId) {
+    return document.relations.find((relation) => relation.id === relationId) ?? null;
+}
 function findViewpoint(system, viewpointId) {
     return system?.viewpoints.find((viewpoint) => viewpoint.id === viewpointId) ?? null;
 }

package/packages/core/dist/atlas-utils.d.ts

@@ -0,0 +1,22 @@
+import type { AstFieldNode, AstSourceLocation, AtReference, NormalizedValue, UnitValue, WorldOrbitObjectType } from "./types.js";
+export interface AtlasFieldLike {
+    key: string;
+    values: string[];
+    location: AstSourceLocation;
+}
+export declare function normalizeIdentifier(value: string): string;
+export declare function humanizeIdentifier(value: string): string;
+export declare function parseAtlasUnitValue(input: string, location?: AstSourceLocation, fieldKey?: string): UnitValue;
+export declare function tryParseAtlasUnitValue(input: string): UnitValue | null;
+export declare function parseAtlasNumber(input: string, key: string, location?: AstSourceLocation): number;
+export declare function parseAtlasBoolean(input: string, key: string, location?: AstSourceLocation): boolean;
+export declare function parseAtlasFieldBoolean(field: AtlasFieldLike): boolean;
+export declare function parseAtlasAtReference(target: string, location?: AstSourceLocation): AtReference;
+export declare function validateAtlasImageSource(value: string, location?: AstSourceLocation): void;
+export declare function normalizeLegacyScalarValue(key: string, values: string[], location: AstSourceLocation): NormalizedValue;
+export declare function ensureAtlasFieldSupported(key: string, objectType: WorldOrbitObjectType, location: AstSourceLocation): void;
+export declare function singleAtlasFieldValue(field: Pick<AtlasFieldLike, "key" | "values" | "location">): string;
+export declare function singleAtlasValue(values: string[], key: string, location?: AstSourceLocation): string;
+export declare function isStructureLikeObjectType(objectType: WorldOrbitObjectType): boolean;
+export declare function cloneNormalizedValue(value: NormalizedValue): NormalizedValue;
+export declare function cloneFieldNode(field: AstFieldNode): AstFieldNode;

package/packages/core/dist/atlas-utils.js

@@ -0,0 +1,189 @@
+import { WorldOrbitError } from "./errors.js";
+import { getFieldSchema, unitFamilyAllowsUnit } from "./schema.js";
+const UNIT_PATTERN = /^(-?\d+(?:\.\d+)?)(kpc|min|mj|rj|ky|my|gy|au|km|me|re|pc|ly|deg|sol|K|m|s|h|d|y)?$/;
+const BOOLEAN_VALUES = new Map([
+    ["true", true],
+    ["false", false],
+    ["yes", true],
+    ["no", false],
+]);
+const URL_SCHEME_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+export function normalizeIdentifier(value) {
+    return value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+export function humanizeIdentifier(value) {
+    return value
+        .split(/[-_]+/)
+        .filter(Boolean)
+        .map((segment) => segment[0].toUpperCase() + segment.slice(1))
+        .join(" ");
+}
+export function parseAtlasUnitValue(input, location, fieldKey) {
+    const match = input.match(UNIT_PATTERN);
+    if (!match) {
+        throw WorldOrbitError.fromLocation(`Invalid unit value "${input}"`, location);
+    }
+    const unitValue = {
+        value: Number(match[1]),
+        unit: match[2] ?? null,
+    };
+    if (fieldKey) {
+        const schema = getFieldSchema(fieldKey);
+        if (schema?.unitFamily && !unitFamilyAllowsUnit(schema.unitFamily, unitValue.unit)) {
+            throw WorldOrbitError.fromLocation(`Unit "${unitValue.unit ?? "none"}" is not valid for "${fieldKey}"`, location);
+        }
+    }
+    return unitValue;
+}
+export function tryParseAtlasUnitValue(input) {
+    const match = input.match(UNIT_PATTERN);
+    if (!match) {
+        return null;
+    }
+    return {
+        value: Number(match[1]),
+        unit: match[2] ?? null,
+    };
+}
+export function parseAtlasNumber(input, key, location) {
+    const value = Number(input);
+    if (!Number.isFinite(value)) {
+        throw WorldOrbitError.fromLocation(`Invalid numeric value "${input}" for "${key}"`, location);
+    }
+    return value;
+}
+export function parseAtlasBoolean(input, key, location) {
+    const parsed = BOOLEAN_VALUES.get(input.toLowerCase());
+    if (parsed === undefined) {
+        throw WorldOrbitError.fromLocation(`Invalid boolean value "${input}" for "${key}"`, location);
+    }
+    return parsed;
+}
+export function parseAtlasFieldBoolean(field) {
+    return parseAtlasBoolean(singleAtlasFieldValue(field), field.key, field.location);
+}
+export function parseAtlasAtReference(target, location) {
+    if (/^[A-Za-z0-9._-]+-[A-Za-z0-9._-]+:L\d+$/i.test(target)) {
+        throw WorldOrbitError.fromLocation(`Invalid special position "${target}"`, location);
+    }
+    const pairedMatch = target.match(/^([A-Za-z0-9._-]+)-([A-Za-z0-9._-]+):(L[1-5])$/);
+    if (pairedMatch) {
+        return {
+            kind: "lagrange",
+            primary: pairedMatch[1],
+            secondary: pairedMatch[2],
+            point: pairedMatch[3],
+        };
+    }
+    const simpleMatch = target.match(/^([A-Za-z0-9._-]+):(L[1-5])$/);
+    if (simpleMatch) {
+        return {
+            kind: "lagrange",
+            primary: simpleMatch[1],
+            secondary: null,
+            point: simpleMatch[2],
+        };
+    }
+    if (/^[A-Za-z0-9._-]+:L\d+$/i.test(target)) {
+        throw WorldOrbitError.fromLocation(`Invalid special position "${target}"`, location);
+    }
+    const anchorMatch = target.match(/^([A-Za-z0-9._-]+):([A-Za-z0-9._-]+)$/);
+    if (anchorMatch) {
+        return {
+            kind: "anchor",
+            objectId: anchorMatch[1],
+            anchor: anchorMatch[2],
+        };
+    }
+    return {
+        kind: "named",
+        name: target,
+    };
+}
+export function validateAtlasImageSource(value, location) {
+    if (!value) {
+        throw WorldOrbitError.fromLocation('Field "image" must not be empty', location);
+    }
+    if (value.startsWith("//")) {
+        throw WorldOrbitError.fromLocation('Field "image" must use a relative path, root-relative path, or an http/https URL', location);
+    }
+    const schemeMatch = value.match(URL_SCHEME_PATTERN);
+    if (!schemeMatch) {
+        return;
+    }
+    const scheme = schemeMatch[0].slice(0, -1).toLowerCase();
+    if (scheme !== "http" && scheme !== "https") {
+        throw WorldOrbitError.fromLocation(`Field "image" does not support the "${scheme}" scheme`, location);
+    }
+}
+export function normalizeLegacyScalarValue(key, values, location) {
+    const schema = getFieldSchema(key);
+    if (!schema) {
+        throw WorldOrbitError.fromLocation(`Unknown field "${key}"`, location);
+    }
+    if (schema.arity === "single" && values.length !== 1) {
+        throw WorldOrbitError.fromLocation(`Field "${key}" expects exactly one value`, location);
+    }
+    switch (schema.kind) {
+        case "list":
+            return values;
+        case "boolean":
+            return parseAtlasBoolean(singleAtlasValue(values, key, location), key, location);
+        case "number":
+            return parseAtlasNumber(singleAtlasValue(values, key, location), key, location);
+        case "unit":
+            return parseAtlasUnitValue(singleAtlasValue(values, key, location), location, key);
+        case "string": {
+            const value = values.join(" ").trim();
+            if (key === "image") {
+                validateAtlasImageSource(value, location);
+            }
+            return value;
+        }
+    }
+}
+export function ensureAtlasFieldSupported(key, objectType, location) {
+    const schema = getFieldSchema(key);
+    if (!schema) {
+        throw WorldOrbitError.fromLocation(`Unknown field "${key}"`, location);
+    }
+    if (!schema.objectTypes.includes(objectType)) {
+        throw WorldOrbitError.fromLocation(`Field "${key}" is not valid on "${objectType}"`, location);
+    }
+}
+export function singleAtlasFieldValue(field) {
+    return singleAtlasValue(field.values, field.key, field.location);
+}
+export function singleAtlasValue(values, key, location) {
+    if (values.length !== 1) {
+        throw WorldOrbitError.fromLocation(`Field "${key}" expects exactly one value`, location);
+    }
+    return values[0];
+}
+export function isStructureLikeObjectType(objectType) {
+    return objectType === "structure" || objectType === "phenomenon";
+}
+export function cloneNormalizedValue(value) {
+    if (Array.isArray(value)) {
+        return [...value];
+    }
+    if (value && typeof value === "object" && "value" in value) {
+        return {
+            value: value.value,
+            unit: value.unit,
+        };
+    }
+    return value;
+}
+export function cloneFieldNode(field) {
+    return {
+        type: "field",
+        key: field.key,
+        values: [...field.values],
+        location: { ...field.location },
+    };
+}

package/packages/core/dist/atlas-validate.d.ts

@@ -0,0 +1,2 @@
+import type { WorldOrbitAnyDocumentVersion, WorldOrbitAtlasDocument, WorldOrbitDiagnostic, WorldOrbitDraftDocument } from "./types.js";
+export declare function collectAtlasDiagnostics(document: WorldOrbitAtlasDocument | WorldOrbitDraftDocument, sourceSchemaVersion?: WorldOrbitAnyDocumentVersion): WorldOrbitDiagnostic[];