worldorbit 2.5.12 → 2.5.15

package/packages/core/dist/scene.js

@@ -130,8 +130,10 @@ export function renderDocumentToScene(document, options = {}) {
     const orbitVisuals = orbitDrafts.map((draft) => createOrbitVisual(draft, relationships.groupIds.get(draft.object.id) ?? null));
     const leaders = leaderDrafts.map((draft) => createLeaderLine(draft));
     const labels = createSceneLabels(objects, height, scaleModel.labelMultiplier);
-    const layers = createSceneLayers(orbitVisuals, leaders, objects, labels);
+    const relations = createSceneRelations(document, objects);
+    const layers = createSceneLayers(orbitVisuals, relations, leaders, objects, labels);
     const groups = createSceneGroups(objects, orbitVisuals, leaders, labels, relationships);
+    const semanticGroups = createSceneSemanticGroups(document, objects);
     const viewpoints = createSceneViewpoints(document, projection, frame.preset, relationships, objectMap);
     const contentBounds = calculateContentBounds(width, height, objects, orbitVisuals, leaders, labels);
     return {
@@ -141,7 +143,7 @@ export function renderDocumentToScene(document, options = {}) {
         renderPreset: frame.preset,
         projection,
         scaleModel,
-        title: String(document.system?.properties.title ?? document.system?.id ?? "WorldOrbit") ||
+        title: String(document.system?.title ?? document.system?.properties.title ?? document.system?.id ?? "WorldOrbit") ||
             "WorldOrbit",
         subtitle: `${capitalizeLabel(projection)} view - ${capitalizeLabel(layoutPreset)} layout`,
         systemId,
@@ -158,9 +160,11 @@ export function renderDocumentToScene(document, options = {}) {
         contentBounds,
         layers,
         groups,
+        semanticGroups,
         viewpoints,
         objects,
         orbitVisuals,
+        relations,
         leaders,
         labels,
     };
@@ -272,6 +276,7 @@ function layoutPresetSpacing(layoutPreset) {
 }
 function createSceneObject(position, scaleModel, relationships) {
     const { object, x, y, radius, sortKey, anchorX, anchorY } = position;
+    const renderPriority = object.renderHints?.renderPriority ?? 0;
     return {
         renderId: createRenderId(object.id),
         objectId: object.id,
@@ -280,11 +285,12 @@ function createSceneObject(position, scaleModel, relationships) {
         ancestorIds: relationships.ancestorIds.get(object.id) ?? [],
         childIds: relationships.childIds.get(object.id) ?? [],
         groupId: relationships.groupIds.get(object.id) ?? null,
+        semanticGroupIds: [...(object.groups ?? [])],
         x,
         y,
         radius,
         visualRadius: visualExtentForObject(object, radius, scaleModel),
-        sortKey,
+        sortKey: sortKey + renderPriority * 0.001,
         anchorX,
         anchorY,
         label: object.id,
@@ -303,6 +309,7 @@ function createOrbitVisual(draft, groupId) {
         object: draft.object,
         parentId: draft.parentId,
         groupId,
+        semanticGroupIds: [...(draft.object.groups ?? [])],
         kind: draft.kind,
         cx: draft.cx,
         cy: draft.cy,
@@ -314,7 +321,7 @@ function createOrbitVisual(draft, groupId) {
         bandThickness: draft.bandThickness,
         frontArcPath: draft.frontArcPath,
         backArcPath: draft.backArcPath,
-        hidden: draft.object.properties.hidden === true,
+        hidden: draft.object.properties.hidden === true || draft.object.renderHints?.renderOrbit === false,
     };
 }
 function createLeaderLine(draft) {
@@ -323,6 +330,7 @@ function createLeaderLine(draft) {
         objectId: draft.object.id,
         object: draft.object,
         groupId: draft.groupId,
+        semanticGroupIds: [...(draft.object.groups ?? [])],
         x1: draft.x1,
         y1: draft.y1,
         x2: draft.x2,
@@ -335,7 +343,7 @@ function createSceneLabels(objects, sceneHeight, labelMultiplier) {
     const labels = [];
     const occupied = [];
     const visibleObjects = [...objects]
-        .filter((object) => !object.hidden)
+        .filter((object) => !object.hidden && object.object.renderHints?.renderLabel !== false)
         .sort((left, right) => left.sortKey - right.sortKey);
     for (const object of visibleObjects) {
         const direction = object.y > sceneHeight * 0.62 ? -1 : 1;
@@ -356,6 +364,7 @@ function createSceneLabels(objects, sceneHeight, labelMultiplier) {
             objectId: object.objectId,
             object: object.object,
             groupId: object.groupId,
+            semanticGroupIds: [...object.semanticGroupIds],
             label: object.label,
             secondaryLabel: object.secondaryLabel,
             x: object.x,
@@ -368,7 +377,7 @@ function createSceneLabels(objects, sceneHeight, labelMultiplier) {
     }
     return labels;
 }
-function createSceneLayers(orbitVisuals, leaders, objects, labels) {
+function createSceneLayers(orbitVisuals, relations, leaders, objects, labels) {
     const backOrbitIds = orbitVisuals
         .filter((visual) => !visual.hidden && Boolean(visual.backArcPath))
         .map((visual) => visual.renderId);
@@ -383,6 +392,10 @@ function createSceneLayers(orbitVisuals, leaders, objects, labels) {
         },
         { id: "orbits-back", renderIds: backOrbitIds },
         { id: "orbits-front", renderIds: frontOrbitIds },
+        {
+            id: "relations",
+            renderIds: relations.filter((relation) => !relation.hidden).map((relation) => relation.renderId),
+        },
         {
             id: "objects",
             renderIds: objects.filter((object) => !object.hidden).map((object) => object.renderId),
@@ -447,6 +460,42 @@ function createSceneGroups(objects, orbitVisuals, leaders, labels, relationships
     }
     return [...groups.values()].sort((left, right) => left.label.localeCompare(right.label));
 }
+function createSceneSemanticGroups(document, objects) {
+    return [...document.groups]
+        .map((group) => ({
+        id: group.id,
+        label: group.label,
+        summary: group.summary,
+        color: group.color,
+        tags: [...group.tags],
+        hidden: group.hidden,
+        objectIds: objects
+            .filter((object) => !object.hidden && object.semanticGroupIds.includes(group.id))
+            .map((object) => object.objectId),
+    }))
+        .sort((left, right) => left.label.localeCompare(right.label));
+}
+function createSceneRelations(document, objects) {
+    const objectMap = new Map(objects.map((object) => [object.objectId, object]));
+    return document.relations
+        .map((relation) => {
+        const from = objectMap.get(relation.from);
+        const to = objectMap.get(relation.to);
+        return {
+            renderId: `${createRenderId(relation.id)}-relation`,
+            relationId: relation.id,
+            relation,
+            fromObjectId: relation.from,
+            toObjectId: relation.to,
+            x1: from?.x ?? 0,
+            y1: from?.y ?? 0,
+            x2: to?.x ?? 0,
+            y2: to?.y ?? 0,
+            hidden: relation.hidden || !from || !to || from.hidden || to.hidden,
+        };
+    })
+        .sort((left, right) => left.relation.id.localeCompare(right.relation.id));
+}
 function createSceneViewpoints(document, projection, preset, relationships, objectMap) {
     const generatedOverview = createGeneratedOverviewViewpoint(document, projection, preset);
     const drafts = new Map();
@@ -464,7 +513,7 @@ function createSceneViewpoints(document, projection, preset, relationships, obje
         }
         const field = fieldParts.join(".").toLowerCase();
         const draft = drafts.get(id) ?? { id };
-        applyViewpointField(draft, field, value, projection, preset, relationships, objectMap);
+        applyViewpointField(draft, field, value, document, projection, preset, relationships, objectMap);
         drafts.set(id, draft);
     }
     const viewpoints = [...drafts.values()]
@@ -495,9 +544,8 @@ function createSceneViewpoints(document, projection, preset, relationships, obje
     });
 }
 function createGeneratedOverviewViewpoint(document, projection, preset) {
-    const label = document.system?.properties.title
-        ? `${String(document.system.properties.title)} Overview`
-        : "Overview";
+    const title = document.system?.title ?? document.system?.properties.title;
+    const label = title ? `${String(title)} Overview` : "Overview";
     return {
         id: "overview",
         label,
@@ -513,7 +561,7 @@ function createGeneratedOverviewViewpoint(document, projection, preset) {
         generated: true,
     };
 }
-function applyViewpointField(draft, field, value, projection, preset, relationships, objectMap) {
+function applyViewpointField(draft, field, value, document, projection, preset, relationships, objectMap) {
     const normalizedValue = value.trim();
     switch (field) {
         case "label":
@@ -580,7 +628,7 @@ function applyViewpointField(draft, field, value, projection, preset, relationsh
         case "groups":
             draft.filter = {
                 ...(draft.filter ?? createEmptyViewpointFilter()),
-                groupIds: parseViewpointGroups(normalizedValue, relationships, objectMap),
+                groupIds: parseViewpointGroups(normalizedValue, document, relationships, objectMap),
             };
             return;
     }
@@ -671,6 +719,7 @@ function parseViewpointLayers(value) {
             rawLayer === "guides" ||
             rawLayer === "orbits-back" ||
             rawLayer === "orbits-front" ||
+            rawLayer === "relations" ||
             rawLayer === "objects" ||
             rawLayer === "labels" ||
             rawLayer === "metadata") {
@@ -690,8 +739,12 @@ function parseViewpointObjectTypes(value) {
         entry === "structure" ||
         entry === "phenomenon");
 }
-function parseViewpointGroups(value, relationships, objectMap) {
+function parseViewpointGroups(value, document, relationships, objectMap) {
     return splitListValue(value).map((entry) => {
+        if (document.schemaVersion === "2.1" ||
+            document.groups.some((group) => group.id === entry)) {
+            return entry;
+        }
         if (entry.startsWith("wo-") && entry.endsWith("-group")) {
             return entry;
         }
@@ -837,8 +890,9 @@ function placeOrbitingChildren(object, positions, orbitDrafts, leaderDrafts, con
     }
     const orbiting = [...(context.orbitChildren.get(object.id) ?? [])].sort(compareOrbiting);
     const orbitMetricContext = computeOrbitMetricContext(orbiting, parent.radius, context.spacingFactor, context.scaleModel);
+    const orbitRadiiPx = resolveOrbitRadiiPx(orbiting, orbitMetricContext);
     orbiting.forEach((child, index) => {
-        const orbitGeometry = resolveOrbitGeometry(child, index, orbiting.length, parent, orbitMetricContext, context);
+        const orbitGeometry = resolveOrbitGeometry(child, index, orbiting.length, parent, orbitMetricContext, orbitRadiiPx[index] ?? orbitMetricContext.innerPx, context);
         orbitDrafts.push({
             object: child,
             parentId: object.id,
@@ -913,6 +967,7 @@ function computeOrbitMetricContext(objects, parentRadius, spacingFactor, scaleMo
             innerPx,
             stepPx,
             pixelSpread: Math.max(stepPx * Math.max(objects.length - 1, 1), stepPx),
+            minimumGapPx: stepPx * 0.42,
         };
     }
     const minMetric = Math.min(...presentMetrics);
@@ -926,9 +981,10 @@ function computeOrbitMetricContext(objects, parentRadius, spacingFactor, scaleMo
         innerPx,
         stepPx,
         pixelSpread: Math.max(stepPx * Math.max(objects.length - 1, 1), stepPx),
+        minimumGapPx: stepPx * 0.42,
     };
 }
-function resolveOrbitGeometry(object, index, count, parent, metricContext, context) {
+function resolveOrbitGeometry(object, index, count, parent, metricContext, orbitRadiusPx, context) {
     const placement = object.placement;
     const band = object.type === "belt" || object.type === "ring";
     if (!placement || placement.mode !== "orbit") {
@@ -948,7 +1004,7 @@ function resolveOrbitGeometry(object, index, count, parent, metricContext, conte
         };
     }
     const eccentricity = clampNumber(typeof placement.eccentricity === "number" ? placement.eccentricity : 0, 0, 0.92);
-    const semiMajor = resolveOrbitRadiusPx(object, index, metricContext);
+    const semiMajor = orbitRadiusPx;
     const baseMinor = Math.max(semiMajor * Math.sqrt(1 - eccentricity * eccentricity), semiMajor * 0.18);
     const inclinationDeg = unitValueToDegrees(placement.inclination) ?? 0;
     const inclinationScale = context.projection === "isometric"
@@ -989,17 +1045,23 @@ function resolveOrbitGeometry(object, index, count, parent, metricContext, conte
         objectY: objectPoint.y,
     };
 }
-function resolveOrbitRadiusPx(object, index, metricContext) {
-    const metric = orbitMetric(object);
-    if (metric === null) {
-        return metricContext.innerPx + index * metricContext.stepPx;
-    }
-    if (metricContext.metricSpread > 0) {
-        return (metricContext.innerPx +
-            ((metric - metricContext.minMetric) / metricContext.metricSpread) *
-                metricContext.pixelSpread);
-    }
-    return metricContext.innerPx + Math.log10(metric + 1) * metricContext.stepPx;
+function resolveOrbitRadiusPx(metric, metricContext) {
+    return metricContext.innerPx + metricContext.stepPx * log2(Math.max(metric, 0) + 1);
+}
+function resolveOrbitRadiiPx(objects, metricContext) {
+    const radii = [];
+    objects.forEach((object, index) => {
+        const metric = orbitMetric(object);
+        const fallbackRadius = metricContext.innerPx + index * metricContext.stepPx;
+        const baseRadius = metric === null
+            ? fallbackRadius
+            : resolveOrbitRadiusPx(metric, metricContext);
+        const minimumRadius = index === 0
+            ? metricContext.innerPx
+            : (radii[index - 1] ?? metricContext.innerPx) + metricContext.minimumGapPx;
+        radii.push(Math.max(baseRadius, minimumRadius));
+    });
+    return radii;
 }
 function orbitMetric(object) {
     if (!object.placement || object.placement.mode !== "orbit") {
@@ -1007,6 +1069,9 @@ function orbitMetric(object) {
     }
     return toDistanceMetric(object.placement.semiMajor ?? object.placement.distance ?? null);
 }
+function log2(value) {
+    return Math.log(value) / Math.log(2);
+}
 function resolveOrbitPhase(phase, index, count) {
     const degreeValue = phase ? unitValueToDegrees(phase) : null;
     if (degreeValue !== null) {

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

@@ -2,7 +2,7 @@ export type WorldOrbitObjectType = "system" | "star" | "planet" | "moon" | "belt
 export type PlacementMode = "orbit" | "at" | "surface" | "free";
 export type Unit = "au" | "km" | "m" | "ly" | "pc" | "kpc" | "re" | "rj" | "sol" | "me" | "mj" | "s" | "min" | "h" | "d" | "y" | "ky" | "my" | "gy" | "K" | "deg";
 export type WorldOrbitDocumentVersion = "1.0";
-export type WorldOrbitAtlasDocumentVersion = "2.0";
+export type WorldOrbitAtlasDocumentVersion = "2.0" | "2.1";
 export type WorldOrbitDraftDocumentVersion = "2.0-draft";
 export type WorldOrbitAnyDocumentVersion = WorldOrbitDocumentVersion | WorldOrbitAtlasDocumentVersion | WorldOrbitDraftDocumentVersion;
 export type ViewProjection = "topdown" | "isometric";
@@ -56,38 +56,102 @@ export interface AstInfoEntryNode {
 export interface WorldOrbitDocument {
     format: "worldorbit";
     version: WorldOrbitDocumentVersion;
+    schemaVersion: WorldOrbitAnyDocumentVersion;
     system: WorldOrbitSystem | null;
+    groups: WorldOrbitGroup[];
+    relations: WorldOrbitRelation[];
     objects: WorldOrbitObject[];
 }
 export interface WorldOrbitAtlasDocument {
     format: "worldorbit";
     version: WorldOrbitAtlasDocumentVersion;
+    schemaVersion: WorldOrbitAtlasDocumentVersion;
     sourceVersion: WorldOrbitDocumentVersion;
     system: WorldOrbitAtlasSystem | null;
+    groups: WorldOrbitGroup[];
+    relations: WorldOrbitRelation[];
     objects: WorldOrbitObject[];
     diagnostics: WorldOrbitDiagnostic[];
 }
 export interface WorldOrbitDraftDocument {
     format: "worldorbit";
     version: WorldOrbitDraftDocumentVersion;
+    schemaVersion: WorldOrbitDraftDocumentVersion;
     sourceVersion: WorldOrbitDocumentVersion;
     system: WorldOrbitAtlasSystem | null;
+    groups: WorldOrbitGroup[];
+    relations: WorldOrbitRelation[];
     objects: WorldOrbitObject[];
     diagnostics: WorldOrbitDiagnostic[];
 }
 export interface WorldOrbitSystem {
     type: "system";
     id: string;
+    title?: string | null;
+    description?: string | null;
+    epoch?: string | null;
+    referencePlane?: string | null;
     properties: Record<string, NormalizedValue>;
     info: Record<string, string>;
 }
 export interface WorldOrbitObject {
     type: Exclude<WorldOrbitObjectType, "system">;
     id: string;
+    groups?: string[];
+    epoch?: string | null;
+    referencePlane?: string | null;
+    tidalLock?: boolean;
+    resonance?: WorldOrbitResonance | null;
+    renderHints?: WorldOrbitRenderHints | null;
+    deriveRules?: WorldOrbitDeriveRule[];
+    validationRules?: WorldOrbitValidationRule[];
+    lockedFields?: string[];
+    tolerances?: WorldOrbitToleranceRule[];
+    typedBlocks?: Partial<Record<WorldOrbitTypedBlockName, Record<string, string>>>;
     properties: Record<string, NormalizedValue>;
     placement: Placement | null;
     info: Record<string, string>;
 }
+export type WorldOrbitTypedBlockName = "climate" | "habitability" | "settlement";
+export interface WorldOrbitGroup {
+    id: string;
+    label: string;
+    summary: string;
+    color: string | null;
+    tags: string[];
+    hidden: boolean;
+}
+export interface WorldOrbitRelation {
+    id: string;
+    from: string;
+    to: string;
+    kind: string;
+    label: string | null;
+    summary: string | null;
+    tags: string[];
+    color: string | null;
+    hidden: boolean;
+}
+export interface WorldOrbitResonance {
+    targetObjectId: string;
+    ratio: string;
+}
+export interface WorldOrbitRenderHints {
+    renderLabel?: boolean;
+    renderOrbit?: boolean;
+    renderPriority?: number;
+}
+export interface WorldOrbitDeriveRule {
+    field: string;
+    strategy: string;
+}
+export interface WorldOrbitValidationRule {
+    rule: string;
+}
+export interface WorldOrbitToleranceRule {
+    field: string;
+    value: NormalizedValue;
+}
 export type NormalizedValue = string | number | boolean | string[] | UnitValue;
 export type Placement = OrbitPlacement | AtPlacement | SurfacePlacement | FreePlacement;
 export interface OrbitPlacement {
@@ -167,6 +231,7 @@ export interface RenderSceneObject {
     ancestorIds: string[];
     childIds: string[];
     groupId: string | null;
+    semanticGroupIds: string[];
     x: number;
     y: number;
     radius: number;
@@ -186,6 +251,7 @@ export interface RenderOrbitVisual {
     object: WorldOrbitObject;
     parentId: string;
     groupId: string | null;
+    semanticGroupIds: string[];
     kind: "circle" | "ellipse";
     cx: number;
     cy: number;
@@ -205,6 +271,7 @@ export interface RenderLeaderLine {
     objectId: string;
     object: WorldOrbitObject;
     groupId: string | null;
+    semanticGroupIds: string[];
     x1: number;
     y1: number;
     x2: number;
@@ -217,6 +284,7 @@ export interface RenderSceneLabel {
     objectId: string;
     object: WorldOrbitObject;
     groupId: string | null;
+    semanticGroupIds: string[];
     label: string;
     secondaryLabel: string;
     x: number;
@@ -226,7 +294,7 @@ export interface RenderSceneLabel {
     direction: "above" | "below" | "left" | "right";
     hidden: boolean;
 }
-export type SceneLayerId = "background" | "guides" | "orbits-back" | "orbits-front" | "objects" | "labels" | "metadata";
+export type SceneLayerId = "background" | "guides" | "orbits-back" | "orbits-front" | "relations" | "objects" | "labels" | "metadata";
 export interface RenderSceneViewpointFilter {
     query: string | null;
     objectTypes: Array<Exclude<WorldOrbitObjectType, "system">>;
@@ -261,6 +329,27 @@ export interface RenderSceneGroup {
     leaderIds: string[];
     contentBounds: RenderBounds;
 }
+export interface RenderSceneSemanticGroup {
+    id: string;
+    label: string;
+    summary: string;
+    color: string | null;
+    tags: string[];
+    hidden: boolean;
+    objectIds: string[];
+}
+export interface RenderSceneRelation {
+    renderId: string;
+    relationId: string;
+    relation: WorldOrbitRelation;
+    fromObjectId: string;
+    toObjectId: string;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+    hidden: boolean;
+}
 export interface RenderScene {
     width: number;
     height: number;
@@ -277,9 +366,11 @@ export interface RenderScene {
     contentBounds: RenderBounds;
     layers: RenderSceneLayer[];
     groups: RenderSceneGroup[];
+    semanticGroups: RenderSceneSemanticGroup[];
     viewpoints: RenderSceneViewpoint[];
     objects: RenderSceneObject[];
     orbitVisuals: RenderOrbitVisual[];
+    relations: RenderSceneRelation[];
     leaders: RenderLeaderLine[];
     labels: RenderSceneLabel[];
 }
@@ -349,12 +440,15 @@ export interface WorldOrbitAtlasSystem {
     type: "system";
     id: string;
     title: string | null;
+    description: string | null;
+    epoch: string | null;
+    referencePlane: string | null;
     defaults: WorldOrbitAtlasDefaults;
     atlasMetadata: Record<string, string>;
     viewpoints: WorldOrbitAtlasViewpoint[];
     annotations: WorldOrbitAtlasAnnotation[];
 }
-export type AtlasDocumentPathKind = "system" | "defaults" | "metadata" | "object" | "viewpoint" | "annotation";
+export type AtlasDocumentPathKind = "system" | "defaults" | "metadata" | "group" | "object" | "viewpoint" | "annotation" | "relation";
 export interface AtlasDocumentPath {
     kind: AtlasDocumentPathKind;
     id?: string;

package/packages/markdown/README.md

@@ -1,6 +1,6 @@
 # @worldorbit/markdown
 
-WorldOrbit markdown contains build-time integration for fenced `worldorbit` blocks in Unified, Remark, and Rehype pipelines.
+WorldOrbit markdown contains build-time integration for fenced `worldorbit` blocks in Unified, Remark, and Rehype pipelines and accepts the same Schema 2.1 atlas source as the core loader.
 
 Main exports:
 

package/packages/viewer/README.md

@@ -1,6 +1,6 @@
 # @worldorbit/viewer
 
-WorldOrbit viewer contains scene-to-SVG rendering, theme presets, browser interactivity, and embed hydration helpers.
+WorldOrbit viewer contains scene-to-SVG rendering, theme presets, browser interactivity, atlas controls, and embed hydration helpers for WorldOrbit documents up to Schema 2.1.
 
 Main exports:
 
@@ -8,5 +8,6 @@ Main exports:
 - `renderDocumentToSvg(document, options?)`
 - `renderSourceToSvg(source, options?)`
 - `createInteractiveViewer(container, options)`
+- `createAtlasViewer(container, options)`
 - `createWorldOrbitEmbedMarkup(payload, options?)`
 - `mountWorldOrbitEmbeds(root?, options?)`

package/packages/viewer/dist/atlas-state.js

@@ -133,6 +133,7 @@ export function sceneViewpointToLayerOptions(viewpoint) {
     return {
         background: viewpoint.layers.background,
         guides: viewpoint.layers.guides,
+        relations: viewpoint.layers.relations,
         orbits: viewpoint.layers["orbits-front"] === undefined && viewpoint.layers["orbits-back"] === undefined
             ? undefined
             : viewpoint.layers["orbits-front"] !== false || viewpoint.layers["orbits-back"] !== false,
@@ -174,7 +175,12 @@ function matchesObjectFilter(object, filter) {
         return false;
     }
     if (filter.groupIds?.length && (!object.groupId || !filter.groupIds.includes(object.groupId))) {
-        return false;
+        const hasSemanticMatch = object.semanticGroupIds.length > 0 &&
+            filter.groupIds.some((groupId) => object.semanticGroupIds.includes(groupId));
+        const hasLegacyMatch = Boolean(object.groupId && filter.groupIds.includes(object.groupId));
+        if (!hasSemanticMatch && !hasLegacyMatch) {
+            return false;
+        }
     }
     if (filter.tags?.length) {
         const objectTags = Array.isArray(object.object.properties.tags)

package/packages/viewer/dist/atlas-viewer.js

@@ -9,6 +9,7 @@ export function createAtlasViewer(container, options) {
     const controls = {
         search: options.controls?.search ?? true,
         typeFilter: options.controls?.typeFilter ?? true,
+        groupFilter: options.controls?.groupFilter ?? true,
         viewpointSelect: options.controls?.viewpointSelect ?? true,
         inspector: options.controls?.inspector ?? true,
         bookmarks: options.controls?.bookmarks ?? true,
@@ -18,6 +19,7 @@ export function createAtlasViewer(container, options) {
     const toolbar = container.querySelector("[data-atlas-toolbar]");
     const searchInput = container.querySelector("[data-atlas-search]");
     const typeFilterSelect = container.querySelector("[data-atlas-type-filter]");
+    const groupFilterSelect = container.querySelector("[data-atlas-group-filter]");
     const viewpointSelect = container.querySelector("[data-atlas-viewpoint]");
     const bookmarkButton = container.querySelector("[data-atlas-bookmark]");
     const bookmarkList = container.querySelector("[data-atlas-bookmarks]");
@@ -31,6 +33,7 @@ export function createAtlasViewer(container, options) {
     let searchQuery = options.initialQuery?.trim() ?? baseFilter?.query ?? "";
     let objectTypeFilter = options.initialObjectType ??
         (baseFilter?.objectTypes?.length === 1 ? baseFilter.objectTypes[0] : null);
+    let groupFilter = baseFilter?.groupIds?.[0] ?? null;
     let bookmarks = [];
     let viewer;
     viewer = createInteractiveViewer(stage, {
@@ -78,6 +81,7 @@ export function createAtlasViewer(container, options) {
     });
     applyCurrentFilter();
     populateViewpoints();
+    populateGroups();
     syncControlsFromFilter(viewer.getFilter());
     renderBookmarks();
     updateSearchResults();
@@ -90,6 +94,10 @@ export function createAtlasViewer(container, options) {
         objectTypeFilter = (typeFilterSelect.value || null);
         applyCurrentFilter();
     });
+    groupFilterSelect?.addEventListener("change", () => {
+        groupFilter = groupFilterSelect.value || null;
+        applyCurrentFilter();
+    });
     viewpointSelect?.addEventListener("change", () => {
         const activeViewer = requireViewer();
         if (!viewpointSelect.value) {
@@ -233,6 +241,7 @@ export function createAtlasViewer(container, options) {
     return api;
     function refreshAfterInputChange() {
         populateViewpoints();
+        populateGroups();
         applyCurrentFilter();
         renderBookmarks();
         updateSearchResults();
@@ -249,7 +258,7 @@ export function createAtlasViewer(container, options) {
             query: searchQuery || undefined,
             objectTypes: objectTypeFilter ? [objectTypeFilter] : undefined,
             tags: baseFilter?.tags,
-            groupIds: baseFilter?.groupIds,
+            groupIds: groupFilter ? [groupFilter] : baseFilter?.groupIds,
             includeAncestors: baseFilter?.includeAncestors ?? true,
         });
     }
@@ -257,12 +266,16 @@ export function createAtlasViewer(container, options) {
         searchQuery = filter?.query?.trim() ?? "";
         objectTypeFilter =
             filter?.objectTypes?.length === 1 ? filter.objectTypes[0] : null;
+        groupFilter = filter?.groupIds?.length === 1 ? filter.groupIds[0] : null;
         if (searchInput && document.activeElement !== searchInput) {
             searchInput.value = searchQuery;
         }
         if (typeFilterSelect) {
             typeFilterSelect.value = objectTypeFilter ?? "";
         }
+        if (groupFilterSelect) {
+            groupFilterSelect.value = groupFilter ?? "";
+        }
     }
     function populateViewpoints() {
         if (!viewpointSelect) {
@@ -278,6 +291,17 @@ export function createAtlasViewer(container, options) {
         ].join("");
         viewpointSelect.value = active;
     }
+    function populateGroups() {
+        if (!groupFilterSelect) {
+            return;
+        }
+        const activeViewer = requireViewer();
+        groupFilterSelect.innerHTML = [
+            `<option value="">All groups</option>`,
+            ...activeViewer.getScene().semanticGroups.map((group) => `<option value="${escapeHtml(group.id)}">${escapeHtml(group.label)}</option>`),
+        ].join("");
+        groupFilterSelect.value = groupFilter ?? "";
+    }
     function syncViewpointControl() {
         if (!viewpointSelect) {
             return;
@@ -313,6 +337,8 @@ export function createAtlasViewer(container, options) {
                 projection: activeViewer.getScene().projection,
                 renderPreset: activeViewer.getScene().renderPreset,
                 groupCount: activeViewer.getScene().groups.length,
+                semanticGroupCount: activeViewer.getScene().semanticGroups.length,
+                relationCount: activeViewer.getScene().relations.length,
                 viewpointCount: activeViewer.getScene().viewpoints.length,
             },
         };
@@ -351,6 +377,14 @@ function buildAtlasViewerMarkup(controls) {
           </select>
         </label>`
             : "",
+        controls.groupFilter
+            ? `<label class="wo-atlas-field">
+          <span>Group</span>
+          <select data-atlas-group-filter>
+            <option value="">All groups</option>
+          </select>
+        </label>`
+            : "",
         controls.viewpointSelect
             ? `<label class="wo-atlas-field">
           <span>Viewpoint</span>